把内网里的服务，开放给外面的人

快速开始

配置都在官网完成，客户端只负责连接：粘贴密钥，点连接。全程五步。

1. 注册账号，选择套餐在官网

   打开官网注册页，注册并登录，再选一个套餐。注册后会自动获得免费体验套餐，想先试试直接用就行。第一次打开客户端、还没有授权密钥时，点「免费注册，获取授权密钥」，也会直接打开注册页。

2. 拿到授权密钥在官网

   系统会为你生成授权密钥。完整密钥只显示这一次，请马上复制保存。之后只会看到 abcd****wxyz 这样的脱敏形式。

3. 添加映射在官网

   进入「控制面板」→「映射管理」，选协议（TCP / UDP / HTTPS），填内网 IP 和端口。HTTPS 还可以填域名。在客户端的「我的房间」点「＋ 开放新游戏」，也会打开网站。详见添加映射。

4. 下载并安装客户端在你的设备上

   官网「客户端下载」页会按你当前的系统推荐安装包。Windows 有图形界面，Linux 和 macOS 是命令行版。详见安装客户端。

5. 粘贴密钥，开放房间在客户端

   打开客户端，进入「设置」，在「账号与套餐」里粘贴授权密钥，点「获取隧道」。你在网页上配好的映射会以房间卡片的形式出现在「我的房间」里。再点右下角的「开放房间」，隧道开始转发，卡片状态变成「● 在线」。

安装客户端

官网「客户端下载」页会根据你访问时的系统自动推荐安装包。手动选择时，对照下表。

# 查看 CPU 架构，决定下载哪个包
uname -m

# 放到固定目录，并赋予执行权限
mkdir -p /opt/playnest
cd /opt/playnest
chmod +x ./playnest

{
  "LicenseKey": "把你的授权密钥粘贴到这里",
  "ControlApiBaseUrl": "https://你的网站地址"
}

./playnest

[Unit]
Description=Playnest client
After=network-online.target
Wants=network-online.target

[Service]
WorkingDirectory=/opt/playnest
ExecStart=/opt/playnest/playnest
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now playnest

# 查看运行日志
journalctl -u playnest -f

mkdir -p /usr/local/playnest
cd /usr/local/playnest
chmod +x ./playnest

# 创建 client.json，内容见 Linux 标签页
./playnest

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key><string>com.playnest.client</string>
  <key>ProgramArguments</key>
  <array><string>/usr/local/playnest/playnest</string></array>
  <key>WorkingDirectory</key><string>/usr/local/playnest</string>
  <key>RunAtLoad</key><true/>
  <key>KeepAlive</key><true/>
  <key>StandardOutPath</key><string>/tmp/playnest.log</string>
  <key>StandardErrorPath</key><string>/tmp/playnest.err</string>
</dict>
</plist>

launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.playnest.client.plist

docker run -d --name playnest \
  --restart unless-stopped \
  --network host \
  -v "$(pwd)/client.json:/app/client.json" \
  playnest/client:latest

# 查看日志
docker logs -f playnest

认识客户端界面

这一节说的是图形界面版客户端（界面里叫「游巢」）。顶栏有三个入口，其余信息都在窗口的边上。

房间卡片怎么看

• ● 在线：已经开放，朋友可以加入。○ 未开放：还没点「开放房间」，朋友加入不了。
• 暂无好友连接，或「N 位好友 · 均为直连 / 走中转 / X 条直连 / Y 条中转」：当前有几位朋友连着，以及走的路线。
• 详情：展开后能看到中转地址（朋友没装 Playnest 时直接填它），以及这个房间当前每一条连接的来源 IP、时长、速率、流量和归属地。

界面语言

「设置」→「高级设置」→「界面语言」可以切换简体中文和 English。第一次启动时会按系统语言自动选择，之后记住你的选择。

高级设置里有什么

默认是收起的，一般不用动：控制面地址、界面语言、传输通道（测试用，默认自动：先试 KCP，连不上再切 WebSocket）、日志入口、关于（版本号、设置文件和日志目录的位置）。

邀请好友联机

你把游戏服务开放出去之后，朋友有两种方式连进来：装了 Playnest 的，输入邀请码加入，不用账号，也不用知道你的地址；没装的，直接在游戏里填节点的公网地址。

房主：生成邀请码

1. 先确认房间已经开放：「我的房间」里的卡片显示「● 在线」。没有开放的话，朋友加入不了。
2. 在要分享的房间卡片上点「邀请好友」。
3. 设置「好友上限」（这张邀请码最多能被用来加入几次，1–50，默认 8）和「有效期」（24 小时或 7 天），点「生成邀请码」。
4. 点「复制邀请码」，发给朋友。邀请码是 8 位字母和数字，显示成 ABCD-2345 这样，不会出现容易看错的 I、O、0、1。

弹窗下方的「已发出的邀请」里能看到每张邀请还剩多久、已经加入几位，可以再次「复制」，也可以「撤销」。撤销之后这张邀请码就不能再用来加入了。

朋友：用邀请码加入（装了客户端）

1. 打开客户端，点顶栏「加入房间」。不需要授权密钥，也不需要登录。
2. 粘贴邀请码，点「加入房间」。如果剪贴板里正好有邀请码，页面上会提示「检测到剪贴板里有邀请码」，点「一键加入」就行。
3. 加入成功后，页面显示「在游戏里连接这个地址」，形如 127.0.0.1:25565。点「复制地址」，把它填进游戏。
4. 不玩了，点「断开」。

没装客户端的朋友

不想装软件也能连：把房间的公网地址发给他，让他在游戏里直接填「节点地址:公网端口」。这个地址在房间卡片的「详情」里（中转地址），也在邀请弹窗的「好友没装游巢？也能连」里。

流量算谁的

朋友不需要账号，也不需要套餐。经节点中转的流量都计在房主的套餐里，速度也受房主的套餐限制。直连不经过节点，既不限速，也不计流量。朋友看不到房主的套餐、流量余额和内网 IP。

直连与中转

朋友加入之后，数据有两条路可以走：

朋友加入时先走中转，马上就能玩；同时后台尝试直连。直连成功后，新建的连接自动走直连，已经连着的游戏不会被打断。直连中途断了，会自动回到中转，不用任何操作。

直连是怎么尝试的

游巢会按下面的顺序，一种一种地试，前面的成功了就不再试后面的。所有方式都试过、都不通，才会继续用中转。整个过程在后台进行，最多十几秒，不影响你先玩起来。

前面的方式比后面的快，所以局域网永远优先。两个人恰好都在 192.168.1.x 这样的网段，但其实不在同一个局域网，也没有关系：游巢会用只有双方才知道的密钥验证对方，连到别人的设备上也不会成功，只会继续往下试。

朋友的页面上怎么看

加入房间后，右上角的徽标显示「● 已直连」或「● 中转中」。直连成功后，进度行会标出实际走的方式，例如「✓ 直连已建立 · 局域网」，可能是「局域网」「端口映射」「公网打洞」或「端口预测打洞」。下面三格分别说明路径、速度和流量：直连是「不限速」「不计流量」，中转是「中转限速」「由房主承担」。

房主：开关直连

「设置」→「联机」→「P2P 直连」，默认开启，所有套餐（包括免费套餐）都可以用。关闭之后，朋友只能走中转，已经建立的直连会立即关闭，朋友的新连接自动走中转。

直连没成功，页面会告诉你原因

客户端底栏的网络检测

客户端启动后会检测你自己的网络，结果显示在窗口左下角：「你的网络适合 P2P 直连」、「当前网络直连较难，会多试几种方式，都不行才使用中转」，或「暂时没能检测网络类型，直连不一定可用，会自动回落到中转」。这只是参考，不管哪种结果，联机都能用，最差是走中转。

房主的中转额度用完了

本月中转流量用完后，走中转的联机会暂停，直连不受影响。客户端会在流量条下面提示「本月额度已用完」。可以升级套餐，或等下个周期重置。

添加映射

一条映射，就是把「公网上的一个入口」对应到「内网里的一个服务」。登录官网，进入「控制面板」→「映射管理」，点新增。可以随时编辑、停用或删除，保存后立即生效。在客户端里，一条映射显示为「我的房间」里的一张房间卡片。

要填哪些内容

三种协议怎么选

HTTPS 与域名

添加 HTTPS 映射时，域名栏有两种填法，能力和要做的准备都不一样。

自带域名通常需要套餐里包含「自定义域名」，具体看你的套餐。

用自己的域名，一步步来

1. 在「映射管理」新增一条映射，协议选 HTTPS，域名栏填你的域名，内网目标填你的 Web 服务的 IP 和 HTTPS 端口。
2. 保存后，页面会提示你把域名指向哪个节点地址。
3. 到你的域名服务商，添加一条解析记录：记录类型选 CNAME 或 A，主机记录填你要用的前缀（例如 www），记录值填页面给出的地址。
4. 等解析生效。这通常要几分钟，个别情况更久。
5. 用浏览器访问你的域名。如果提示证书错误，检查内网 Web 服务上的证书是否有效、是否包含这个域名。

密钥管理

授权密钥就是你的通行证：客户端只认密钥，其余配置都在网页上。在「控制面板」→「密钥管理」里可以：

• 查看和复制：日常只显示脱敏形式，例如 abcd****wxyz。完整密钥只在生成的那一刻展示一次。
• 一键重置：生成新密钥，旧密钥立即失效。

换电脑或换设备

在新设备上装好客户端，粘贴同一个密钥即可，映射不用重新配置。

客户端怎么保存密钥

客户端只在本机保存授权密钥。节点地址和映射每次启动都会重新向服务器获取，不会存在本地。所以密钥一旦作废，光靠本地文件是连不上节点的。

重置密钥之后

1. 旧密钥马上失效，正在运行的隧道在下次断线重连时会认证失败。
2. 复制新密钥。完整内容只显示这一次。
3. 更新客户端：图形界面版到「设置」→「账号与套餐」粘贴新密钥，点「获取隧道」，正在开放的房间会自动用新密钥重连；Linux、macOS、Docker 命令行版修改 client.json 后重启客户端。

套餐与流量

「控制面板」→「用量与账单」里能看到当前套餐、剩余流量和到期时间，也可以在这里续费或升级。

套餐限制的几个维度

在客户端里看额度

• 右上角的徽标是当前套餐名。
• 「我的房间」底部有「本月中转流量」进度条，用到 80% 变黄，用完变红并提示。
• 「设置」→「账号与套餐」里能看到套餐名、已用流量和中转限速。套餐是体验档、流量快用完或已用完时，这里会出现「升级套餐」按钮。
• 朋友用邀请码加入时的中转流量，都计在你的额度里，朋友自己不需要套餐。

到期或用完流量会怎样

• 到期：密钥状态变为欠费停用，认证会被直接拒绝，新的隧道建立不起来。续费后恢复。
• 流量用完：视平台设置，可能直接停用，也可能降速继续使用。用量在「用量与账单」里能随时查看。在客户端里，额度用完后走中转的联机会暂停，直连不受影响。
• 续费或升级：支付成功后，套餐、额度和到期时间会自动更新，不需要重装客户端或改任何配置。支持的支付方式以结账页为准。

运行状态与日志

「控制面板」→「实时状态」会显示每条映射是否在线、当前有多少连接。数据是实时推送的，不用手动刷新。

在客户端里，「我的房间」的卡片状态也能看出来：「● 在线」说明隧道已建立，「○ 未开放」说明还没点「开放房间」。

客户端的日志（图形界面版在「设置」→「高级设置」→「查看日志」；Linux、macOS 是终端输出或日志文件）会告诉你连接进行到哪一步：

故障排查

先看客户端日志和「实时状态」，再对照下面的情况。

安全建议

• 保管好密钥：只在自己的设备上使用，泄露就重置。
• 只开放需要的服务：每条映射都会让内网的一个服务对公网可见。数据库、远程桌面、路由器后台这类敏感服务，除非确实需要，不要映射出去；一定要开放时，请设置强密码，并保持软件更新。
• 不用的映射及时停用：在「映射管理」里停用即可，配置会保留。
• 需要全程加密，选自带域名：自带域名的 HTTPS 是原样转发加密数据，平台看不到内容。系统二级域名由平台解密后转发，方便但不是端到端加密。
• 留意异常流量：在「用量与账单」里发现流量异常增长，先检查映射，必要时重置密钥。
• 邀请码只发给信得过的人：拿到邀请码的人能连你开放的所有游戏。用完或发错了，在「邀请好友」弹窗里撤销，邀请的有效期也尽量设短一点。
• 直连会暴露公网 IP：直连时朋友能看到你的公网 IP。不想暴露，就在「设置」里关闭 P2P 直连，朋友会自动走中转。
• 客户端与官网的通信走 HTTPS：客户端获取节点和映射的请求都经过加密连接。

常见问题