Docker ZeroTier Planet

简体中文 · English

使用 Docker 在 Linux 服务器上部署自己的 ZeroTier Planet，同时提供网络管理界面和 planet / moon 文件下载服务。适合希望自行管理 ZeroTier 根节点与网络的用户。

**先了解：**客户端需要替换 planet 文件才能使用自建 Planet；自建根节点不保证设备间一定直连，也不等于所有业务流量都经过或都不经过这台服务器。管理界面默认通过 HTTP 访问，部署后请尽快修改默认密码。

本项目的 CDN 加速和安全保护由腾讯 EdgeOne 赞助

广告

• 雨云容器服务一键部署-买服务器上雨云
• MyHeadScale-5台设备永久免费-不限流量
• Bandwagonhost-CN2 优质线路

交流与支持

• Telegram 交流群
• QQ 群：
  • 692635772
  • 785620313
  • 316239544
  • 1027678459
  • 651935808

如果项目对你有帮助，也可以支持该项目

微信公众号：

阅读导航

• 广告
• 交流与支持
• 快速开始：准备服务器、部署容器、创建网络
• 客户端接入：分平台替换 planet 并加入网络
• 运维与安全：数据备份、更新、卸载、Compose 与 HTTPS
• 常见问题：连接、端口、IP 变更等
• 项目与社区：开发计划、风险声明、致谢与参考资料

快速开始

1. 准备服务器

准备一台有公网 IPv4 地址的 Linux 服务器，安装 Docker 和 Git。部署脚本面向 Linux；镜像构建脚本面向 linux/amd64 和 linux/arm64。尚未安装 Docker 时，可参考 Docker 官方安装文档。

在服务器防火墙和云平台安全组中放行实际使用的端口（安装时可按提示修改默认值）：

不建议将管理界面或文件下载入口直接暴露给不受信任的访问者。下载链接中的密钥也应当按凭据保管。

2. 运行部署脚本

git clone https://github.com/xubiaolin/docker-zerotier-planet.git
cd docker-zerotier-planet
./deploy.sh

按提示选择 1. 安装，依次填写 ZeroTier、管理界面和文件下载端口，并选择自动获取或手动填写服务器公网 IP。

部署脚本使用 docker run 创建容器；仓库没有自带的 Compose 配置文件。

**已有部署不要直接选择重新安装：该流程会删除当前项目目录下的 data/zerotier/，请先备份，升级请选“更新”。**若镜像拉取失败，先确认 Docker 可以访问镜像仓库，不要直接覆盖服务器现有的 Docker 配置。

请在项目目录运行脚本：数据路径按当前工作目录计算。

部署后可检查容器和日志：

docker ps --filter name=myztplanet
docker logs myztplanet

3. 创建网络并下载文件

1. 打开 http://<服务器公网 IP>:3443（若修改了管理端口，请使用实际端口）并登录。默认用户名为 admin，默认密码为 password；首次登录后立即修改密码。
2. 在 Networks 页面点击 Add Network，填写名称并创建网络，记下生成的 Network ID。需要自动分配虚拟 IP 时，在网络设置中使用 Easy Setup 配置地址段。
3. 从部署完成时脚本给出的下载地址，或从服务器的 ./data/zerotier/dist/ 获取 planet 文件，将它分发给需要连接此私有 Planet 的客户端。moon 文件同样生成在该目录中，本项目已把节点自身配置为 moon，其他节点按需下载使用。

**请备份整个 data/zerotier/ 目录。**其中不仅有供客户端下载的文件，还包含节点身份、签名密钥、控制器和管理界面数据。不要将该目录或下载密钥提交到公开仓库。

这套部署包含什么

ZeroTier 会尝试让节点直接通信；是否能够直连仍取决于双方网络、NAT 和防火墙环境。自建 Planet 不能替代端到端连通性排查。

客户端接入

**通用流程：**在客户端安装 ZeroTier → 备份原有 planet（如果存在）→ 放入服务器生成的新文件 → 重启 ZeroTier 服务 → 加入创建的 Network ID → 在管理界面授权设备 → 检查分配地址和连接状态。

下面命令中的 0123456789abcdef 仅作为 Network ID 示例，执行时请替换为自己创建的 ID。不同发行版或客户端版本的安装路径可能不同，请以实际安装位置为准。

Windows

1. 安装 ZeroTier One 客户端，将生成的 planet 放到 C:\ProgramData\ZeroTier\One\planet（ProgramData 默认隐藏）；覆盖前备份原文件。

2. 在 Windows“服务”中重启 ZeroTier One，再在可调用 zerotier-cli.bat 的管理员终端加入网络：

   zerotier-cli.bat join 0123456789abcdef
   zerotier-cli.bat peers
   

3. 在管理界面的成员列表中勾选该设备的 Authorized，确认它获得虚拟 IP。peers 输出中可查看 Planet 和其他节点的连接状态；Planet 为 DIRECT 不代表所有设备之间也都直连。

Linux

将 planet 备份并复制到 ZeroTier 数据目录（通常是 /var/lib/zerotier-one/planet），重启服务，然后加入网络：

sudo cp planet /var/lib/zerotier-one/planet
sudo systemctl restart zerotier-one
sudo zerotier-cli join 0123456789abcdef
sudo zerotier-cli peers

覆盖前请先备份目标路径已有的文件；如果系统没有使用 systemd，请使用该系统对应的服务管理命令。最后回到管理界面授权该设备。

macOS

将 planet 备份并放入 /Library/Application Support/ZeroTier/One/，重启 ZeroTier One 后加入网络，并在管理界面授权。路径中包含空格；使用终端操作时需要正确引用路径。服务重启方式以当前安装版本为准。

OpenWrt

先确认所安装的 ZeroTier 插件是否支持自定义 planet，以及它实际使用的数据目录。部分插件使用 /etc/config/zero/planet；放入文件后在 OpenWrt 管理界面重启 ZeroTier，再加入网络并授权设备。不要在未核实目录的情况下直接创建或覆盖系统软链接。

Android 与 iOS

• **Android：**可参考支持自定义 Planet 的第三方客户端 ZerotierFix，使用前请自行检查其版本兼容性及维护状态。
• **iOS：**替换 planet 需要客户端或系统提供相应能力；可了解 ZeroTieriOSFix 等非官方方案，其适用条件和风险由使用者自行评估。WireGuard 是另一种协议，不能直接作为 ZeroTier 客户端加入本项目创建的网络。

运维与安全

数据目录与备份

部署脚本将以下宿主机目录挂载进容器；备份时应保留整个 data/zerotier/，而不只是 planet 文件：

**更新前先备份。**运行 ./deploy.sh 并选择“更新”会保留已挂载的数据，但会重建容器；选择重新“安装”前要特别注意数据清理提示，不能把它当作无损升级。部署脚本在数据目录已有内容时不会自动重新生成 planet / moon；只修改 IP 或端口环境变量，不会更新已生成的节点信息和客户端文件。

保护管理界面和下载入口

• 首次登录立即修改默认密码；管理界面默认使用 http://，3443 只是端口号，不表示已启用 TLS。
• 使用防火墙限制管理端口的访问来源；对外提供管理界面时，建议由 Nginx 等反向代理终止 HTTPS。
• 下载链接和相关密钥不要公开传播。文件服务使用 SECRET_KEY 作为下载密钥；如果没有固定该值，容器重启后会生成新密钥，旧下载链接随之失效。镜像中的 FILE_KEY 不是文件服务实际读取的变量。

以下示例假设 Nginx 与容器运行在同一台主机，证书已自行准备，且 3443 是实际映射的管理端口。还应通过防火墙限制对 3443 的直接公网访问：

server {
    listen 80;
    server_name planet.example.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name planet.example.com;

    ssl_certificate /path/to/fullchain.pem;
    ssl_certificate_key /path/to/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;

    location / {
        proxy_pass http://127.0.0.1:3443;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

使用 Docker Compose（手动方式）

仓库没有附带 compose.yaml。如果不使用交互式部署脚本，可将以下示例保存为 compose.yaml，填入自己的公网 IPv4 和足够长的随机 SECRET_KEY 后，在该文件所在目录运行 docker compose up -d：

services:
  myztplanet:
    image: xubiaolin/zerotier-planet:latest
    container_name: myztplanet
    restart: unless-stopped
    ports:
      - "9994:9994/tcp"
      - "9994:9994/udp"
      - "3443:3443/tcp"
      - "3000:3000/tcp"
    environment:
      IP_ADDR4: "203.0.113.10" # 替换为服务器公网 IPv4
      IP_ADDR6: "" # 留空时容器仍会尝试自动获取公网 IPv6
      ZT_PORT: "9994"
      API_PORT: "3443"
      FILE_SERVER_PORT: "3000"
      SECRET_KEY: "replace-with-a-long-random-secret"
    volumes:
      - ./data/zerotier/dist:/app/dist
      - ./data/zerotier/ztncui:/app/ztncui
      - ./data/zerotier/one:/var/lib/zerotier-one
      - ./data/zerotier/config:/app/config

示例端口与容器环境变量保持一致；如果修改监听端口，请同步修改映射和防火墙规则。**不要把填有真实公网 IP、下载密钥或私密配置的 Compose 文件提交到公开仓库。**手动 Compose 部署不提供 deploy.sh 的交互流程，遇到问题请检查 docker logs myztplanet。

卸载

在项目目录运行 ./deploy.sh，根据菜单提示选择“卸载”。若手动管理容器，可执行 docker rm -f myztplanet；这只删除容器，不等于清除宿主机的 data/zerotier/ 数据。删除数据前请先核实目录内容并完成备份。

常见问题

为什么无法连接自建 Planet？

先核对客户端是否使用当前部署生成的 planet 并已重启 ZeroTier；再检查服务器公网 IP，以及 9994/tcp、9994/udp 的容器端口映射、服务器防火墙和云平台安全组。自定义过端口时，以实际配置为准。

已加入网络，为什么仍 ping 不通其他设备？

确认两端都已加入同一个 Network ID、在管理界面获得授权并分配了地址；随后检查目标设备操作系统防火墙是否允许 ICMP 和所需业务端口。不能仅凭 join OK 判断网络已经可用。

如何判断直连还是中转？

在客户端运行 zerotier-cli peers，查看目标节点对应的连接状态。DIRECT 表示该条连接直连，RELAY 表示该条连接经中转；连接到 Planet 为 DIRECT 并不保证到其他 LEAF 也直连。

为什么看不到 ZeroTier 官方 Planet？

客户端替换为本项目生成的 planet 后，根节点列表指向自建 Planet，不会同时显示官方 Planet。请确认使用该文件是你的预期操作。

服务器公网 IP 或通信端口变了怎么办？

备份整个 data/zerotier/ 后重新规划部署，并生成与新地址相符的 planet 文件，然后重新分发给客户端。已有数据非空时，仅重启容器或改环境变量不会重生成文件；重新安装可能删除旧数据和身份，操作前务必备份。

忘记管理密码怎么办？

在项目目录运行 ./deploy.sh，选择菜单中的“重置密码”。脚本会将管理界面密码恢复为默认值 password 并重启容器；登录后立即更换密码。不要为重置密码删除 data/zerotier/，其中还保存着节点和网络数据。

支持域名或 ARM 服务器吗？

管理界面可以通过域名与反向代理访问；Planet 生成逻辑使用 IP_ADDR4 / IP_ADDR6 填写节点地址，不能简单用域名替代 IP。镜像构建脚本包含 linux/arm64 和 linux/amd64，使用前请确认所拉取的镜像包含对应架构。

PVE LXC 容器内没有创建虚拟网卡怎么办？

ZeroTier 需要访问 TUN 设备。请按当前 Proxmox / LXC 版本核对容器的 TUN 设备映射、权限和网络配置；修改特权模式或放宽设备权限会改变安全边界，不建议在不了解影响时直接套用旧版配置片段。

项目与社区

开发计划

• 多 Planet 支持
• 自定义管理界面端口
• Planet 与 Controller 分离部署

风险声明

本项目用于学习和研究。自行部署需要维护服务器、凭据和客户端配置；请评估安全与可用性风险，并遵守适用的法律及服务条款。项目维护者不对使用本项目产生的损失承担责任。

致谢

感谢以下支持项目的朋友（按原名单顺序）：

随性、我、你好、Calvin、小猪猪的饲养员、情若犹在、天天星期天、啊乐、夏末秋至、**忠、岸芷汀兰、Kimi Chen、匿名、阳光报告旷课、濂溪先生、Water、匿名、匿名、陆、精钢葫芦娃、唯、王小新、匿名、Duck不必。

相关项目与参考资料

• WireGuard 一键脚本
• ZeroTier 虚拟局域网详解
• 五分钟自建 ZeroTier 的 Planet / Controller