1. 文档概述
本文档旨在规范和指导在全新 Ubuntu Linux 环境下，通过 IPv6 网络实现 SSH 远程直连，并完成 ZeroTier 客户端安装、私有 Planet 节点配置及虚拟局域网接入的标准流程。
-
适用环境: Ubuntu 25.10 (或类似 Debian 系发行版)
-
前置条件:
- 服务器已分配公网 IPv6 地址（基于 SLAAC 或 DHCPv6）。
- 本地操作端需具备 IPv6 网络环境。
- 已备好编译完成的私有
planet配置文件。 - 操作终端推荐：MobaXterm。
2. 阶段一：服务器远程接入配置 (IPv6 + SSH)
2.1 获取并识别目标 IP 地址
在新装系统上，需获取用于公网访问的 IPv6 地址。
-
操作命令:
ip -6 a或ip -6 addr show ens2 -
地址识别 (关键坑点):
- 公网地址 (
scope global): 例如2409:8a28:...。这是由运营商下发前缀结合物理 MAC 地址生成的公网可达地址，必须使用此地址进行 SSH 连接。 - 链路本地地址 (
scope link): 例如fe80::...。这是局域网内部路由寻址使用的保留地址，无法跨网段通信，不可用于外网直连。
- 公网地址 (
2.2 建立 MobaXterm SSH 连接
- 打开 MobaXterm，新建 SSH Session。
- Remote host: 填入上述获取的
scope global级别的 IPv6 地址（无需添加[]括号）。 - Specify username: 勾选并输入系统级用户名（如
openclaw）。 - Port: 默认 22。点击 OK 并输入密码完成连接。
⚠️ 常见故障排除 (Troubleshooting)
-
故障现象: MobaXterm 连接超时 (
Connection timed out)。 -
成因与解决方案:
- 本地网络环境不支持 IPv6: 运行 MobaXterm 的宿主机未获取到 IPv6 地址。需切换至手机热点或开启本地路由器 IPv6 功能。
- 上级网关防火墙拦截 (最常见): 运营商光猫或本地路由器默认开启 IPv6 入站防火墙（IPv6 Firewall SPI），导致外部主动发起的 TCP 22 端口握手被丢弃。解决: 登录网关后台，降低 IPv6 防火墙等级或针对特定设备放行。
- 系统级防火墙 (UFW): Ubuntu 内部防火墙未放行 SSH。解决: 执行
sudo ufw allow 22/tcp。 - SSH 守护进程未启动: 解决: 执行
sudo systemctl status ssh检查状态，必要时执行sudo apt install openssh-server -y安装。
3. 阶段二：ZeroTier 安装与私有 Planet 配置
3.1 自动化安装 ZeroTier 客户端
使用官方提供的 Bash 脚本进行静默安装：
Bash
curl -s https://install.zerotier.com | sudo bash
3.2 替换私有 Planet 配置文件
由于 ZeroTier 默认连接官方根服务器，需将其替换为自建的私有根服务器配置，以提升 P2P 打洞成功率和连接稳定性。
-
文件上传: 利用 MobaXterm 左侧的 SFTP 图形化界面，将本地预先准备好的
planet文件拖拽上传至用户家目录（如/home/openclaw/）。 -
备份默认配置:
Bash
sudo mv /var/lib/zerotier-one/planet /var/lib/zerotier-one/planet.bak -
覆盖新配置:
Bash
sudo cp /home/openclaw/planet /var/lib/zerotier-one/planet -
重置属主与权限 (关键坑点):
Bash
sudo chown zerotier-one:zerotier-one /var/lib/zerotier-one/planet sudo chmod 644 /var/lib/zerotier-one/planet- 成因说明: 如果直接由 root 或普通用户
cp文件，文件所有者可能发生改变。ZeroTier 核心进程由zerotier-one用户运行，若无读权限，将导致服务启动失败或忽略该配置文件。
- 成因说明: 如果直接由 root 或普通用户
3.3 重启服务并验证
-
重启命令:
sudo systemctl restart zerotier-one -
验证节点状态:
sudo zerotier-cli peers- 预期结果: 列表中必须出现你的私有 Planet 节点 ID，且对应 ROLE 列显示为
PLANET。
- 预期结果: 列表中必须出现你的私有 Planet 节点 ID，且对应 ROLE 列显示为
4. 阶段三：网络接入与授权
4.1 加入虚拟局域网
执行加入网络命令，请求接入指定的 Network ID。
Bash
sudo zerotier-cli join 20681eabb50d23f9
⚠️ 常见故障排除 (Troubleshooting)
- 故障现象: 执行
join <20681eabb50d23f9>报错。 - 成因与解决方案: IT 文档或教程中常见的尖括号
< >仅作为“此处需替换为自定义变量”的占位符标识。在终端实际执行时，必须移除尖括号，否则 Shell 会将其误认为重定向操作符。
4.2 控制台授权 (收尾关键步骤)
终端提示 200 join OK 仅代表设备发出了接入申请，此时并未获得内网 IP。
- 操作: 必须登录 ZeroTier 控制台（如官方 Dashboard 或自建的 ztncui/ZeroUI），在网络管理页面找到新增的设备记录，勾选
Auth(授权) 选框。设备才能完成最终组网并获取虚拟局域网 IP。
5. 阶段四：验证 P2P 直连状态与网络调优 (NAT Traversal)
在设备成功加入 ZeroTier 网络并获得内网 IP 后，可以验证节点间的通信是直连 (DIRECT) 还是中转 (RELAY)。
5.1 状态查询与指标解读
在你的 Ubuntu 服务器（或任意已加入该网络的终端）上执行以下命令，查看当前与其他节点的连接拓扑图：
Bash
sudo zerotier-cli peers
命令会输出一张表格，重点关注以下几个字段：
<ztaddr>(节点 ID): 对方设备的 10 位 ZeroTier 地址。<role>(角色):PLANET（根节点/你的私有服务器）、LEAF（普通终端设备，如你的电脑或手机）。<lat>(延迟): 节点间的通讯延迟。直连通常在几十毫秒内；如果超过 100ms 甚至数百毫秒，极大概率是处于中转状态。<link>(链路状态 - 核心指标):DIRECT：（理想状态） 表示两端成功打穿 NAT，建立了 P2P 直连。此时两机通讯速度取决于双方物理宽带的上限。RELAY：（异常状态） 表示 P2P 打洞失败，所有数据包都在通过你的 Planet 节点进行中转转发。此时速度受限于 Planet 服务器的带宽（如果你的云服务器带宽只有 3M，那内网传输最高也就 3M）。
5.2 链路异常 (RELAY 状态) 排障方案
如果你发现你的本地电脑连接这台 Ubuntu 服务器显示为 RELAY，请按照以下顺序排查“网络打洞”失败的原因：
方案 A：放行本地防火墙的 UDP 端口 (最常见)
ZeroTier 依赖 UDP 协议进行 NAT 穿透。默认监听端口为 9993。
- 在 Ubuntu 端： 确保 UFW 防火墙没有拦截 UDP 流量。执行以下命令显式放行：
- 在云服务器控制台（如果有）： 如果这台 Ubuntu 是一台云服务器（如阿里云、腾讯云等），必须前往网页端的“安全组”设置，添加入站规则，放行 UDP 协议的 9993 端口。
方案 B：解决严格型 NAT (Symmetric NAT) 问题
如果在两端都放行了防火墙后依然是 RELAY，通常是因为你本地电脑所处的网络环境（如部分公司的企业级路由、或者是深层级联的家用级光猫拨号路由）是对称型 NAT (Symmetric NAT)，这种 NAT 类型极难被穿透。
- 对策 1（开启 UPnP）： 登录你本地网络的路由器管理后台，找到并开启
UPnP功能。这允许 ZeroTier 客户端自动向路由器申请端口映射。 - 对策 2（手动端口映射/Port Forwarding）： 如果 UPnP 无效，在路由器后台手动设置一条端口转发规则，将外网的任意 UDP 端口转发到你本地电脑的
9993端口。 - 对策 3（IPv6 降维打击）： 就像我们之前配置的一样，如果你两端的设备都有公网 IPv6 地址，ZeroTier 会优先通过 IPv6 建立直连，通常能完美绕过复杂的 IPv4 NAT 穿透难题。确保两端
zerotier-cli peers列表里的<last path>显示的是 IPv6 地址。