CodeCow/docker-zerotier-planet

Fork 0

mirror of https://github.com/xubiaolin/docker-zerotier-planet.git synced 2026-06-04 21:04:27 +08:00

Anonymous c042ff585e fix

2026-05-13 00:30:26 +08:00

23 KiB

Raw Permalink Blame History

🌐 Languages: English | 中文

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

Docker ZeroTier Planet

使用 Docker Compose 部署 ZeroTier Planet 服务器，支持容器化运行与维护

📢 交流群

TG交流群：https://t.me/+JduuWfhSEPdlNDk1

QQ Group

1群：692635772
2群：785620313
3群：316239544
4群：1027678459
5群：651935808

📱 微信公众号

✨ 功能特性

✅ 支持 Linux/AMD64、Linux/ARM64 架构
🐳 Docker 容器化部署
📥 支持 URL 下载 planet、moon 配置
🌐 可作为 Moon 或 Planet 服务器搭建
🔧 基于 Docker Compose 的部署与维护流程
📊 可视化 Web 管理界面

0. 托管服务

0.1 自运营容器服务

寻找便捷的解决方案？

我们提供专业的托管服务：

服务项目	详情
试用期	免费试用 3 天
年费	仅需 99￥
带宽	高速带宽 300Mbit
流量政策	每月 100G 转发流量，P2P 连接后不计流量，超出后每 10 元 100G
机房	优质线路：宁波电信机房
联系方式	Telegram：https://t.me/uxkram 或加入 QQ 群咨询群主

测速图如下：

0.2 雨云容器服务

0.3 微信公众号

欢迎关注公众号获取最新动态和技术分享

1. ZeroTier 介绍

ZeroTier 是一款强大的 P2P VPN 工具，它能让你在互联网上搭建属于自己的虚拟局域网。通过它，你可以轻松实现远程访问家中设备的需求 - 比如在公司用手机直接访问家里的 NAS。最重要的是，设备之间是点对点直连的，无需经过中转服务器，既保证了速度，又提升了安全性。

工作原理

通过 ZeroTier One 客户端，在不同设备（如笔记本、手机、服务器等）之间建立 P2P 连接，即使这些设备都在 NAT 后面也没问题。它使用了 STUN 等技术，可以穿透大多数类型的 NAT，实现设备间的直接通信。如果实在无法直连，才会通过中转服务器进行通信。

简单来说，ZeroTier 就像是一个跨越互联网的"虚拟交换机"，让分布在世界各地的设备，都能像在同一个局域网内一样方便地相互访问。

ZeroTier 网络中的关键概念

概念	说明
PLANET（行星服务器）	ZeroTier 网络的核心根服务器，负责网络发现和初始连接。相当于整个网络的"中枢"
MOON（卫星服务器）	用户可以自建的私有根服务器。它可以作为区域性的代理节点，帮助就近的设备更快地建立连接，提升网络性能
LEAF（叶子节点）	所有接入 ZeroTier 网络的终端设备，如电脑、手机、服务器等。这些设备通过 PLANET 和 MOON 的协调来相互发现和通信

本教程将指导您搭建一个私有的 PLANET 服务器，让您完全掌控自己的 ZeroTier 网络。

2. 为什么要自建 PLANET 服务器

自建 PLANET 服务器有以下几个重要原因：

🚀 性能优势

提升网络稳定性：官方服务器位于海外，国内用户访问延迟高且不稳定。自建服务器可以大幅提升连接质量
加快连接速度：本地化的 PLANET 服务器可以更快地帮助设备建立 P2P 连接

🔒 安全优势

增强网络控制：自建服务器让您完全掌控网络配置，可以根据需求进行优化调整
提高安全性：私有化部署意味着网络流量不经过第三方服务器，更加安全可靠

💪 可靠性优势

降低依赖：避免因官方服务器故障或网络波动影响您的业务正常运行

3. 开始安装

3.1 环境准备

在开始安装之前，请确保您的服务器满足以下条件：

服务器要求

✅ 拥有公网 IP 地址
✅ 需开放以下端口：
- 3443/tcp (管理面板，根据实际情况调整)
- 9994/tcp (ZeroTier 通信，根据实际情况调整)
- 9994/udp (ZeroTier 通信，根据实际情况调整)

软件依赖

✅ Docker (容器运行环境)
✅ Git (获取项目代码)

系统要求

推荐使用较新的 Linux 发行版：

Debian 12
Ubuntu 20.04+
Rocky Linux
其他同类系统

3.1.1 安装 Git

# Debian/Ubuntu 等
apt update && apt install git -y 

# CentOS 等
yum update && yum install git -y

3.1.2 安装 Docker

curl -fsSL https://get.docker.com | bash

注意：如果网络问题导致无法安装，可以使用国内镜像安装，请参考：安装 Docker

3.1.3 启动 Docker

service docker start

3.1.4 配置 Docker 加速镜像（可选）

sudo mkdir -p /etc/docker

sudo tee /etc/docker/daemon.json > /dev/null <<EOF
{
  "registry-mirrors": [
    "https://hub.bwg.imoyuapp.win"
  ]
}
EOF

sudo systemctl daemon-reload
sudo systemctl restart docker

3.2 下载项目源码

官方地址：

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

加速地址：

git clone https://ghproxy.imoyuapp.win/github.com/xubiaolin/docker-zerotier-planet.git

3.3 使用 Docker Compose 安装

cd docker-zerotier-planet

创建并编辑配置：

cp .env.example .env
vim .env

至少设置 IP_ADDR4 或 IP_ADDR6。默认 compose.yaml 会把管理界面和文件服务固定绑定到宿主机 127.0.0.1，即使误把 HOST_BIND_IP 改成公网地址也不会公开明文 HTTP。

启动服务：

docker compose up -d

查看访问信息：

docker compose ps
docker exec ${CONTAINER_NAME:-myztplanet} sh -c 'cat /app/config/ztncui.initial-password'

3.4 下载 planet 文件

脚本运行完成后，会在 ./data/zerotier/dist 目录下生成 planet 和 moon 配置文件。

默认情况下，文件下载服务只建议在本机或经过 TLS 反向代理后访问，并且使用请求头传递访问密钥，不再把密钥放到 URL 中。文件服务密钥保存在 ./data/zerotier/config/file_server.key。

推荐下载方式：

在服务器本机下载（推荐）

FILE_KEY=$(cat ./data/zerotier/config/file_server.key)
curl -H "Authorization: Bearer ${FILE_KEY}" http://127.0.0.1:3000/planet -o planet
# moon 文件示例：curl -H "Authorization: Bearer ${FILE_KEY}" http://127.0.0.1:3000/<moon-id>.moon -o <moon-id>.moon

使用 scp、SFTP 或其他文件传输工具从服务器下载
通过 HTTPS 反向代理访问：请先参考第 5 节配置 TLS，再使用同样的 Authorization: Bearer 请求头下载。

安全提示：不要分享包含密钥的命令输出，也不要使用带密钥的查询字符串下载链接。ALLOW_QUERY_FILE_KEY=true 仅用于短期兼容旧流程，默认关闭，并计划移除。重要：请妥善保存这些文件，后续配置客户端时会用到。

3.5 新建网络

3.5.1 访问管理界面

默认部署会把管理界面绑定到宿主机 127.0.0.1:3443，避免在公网明文暴露。请在服务器本机访问，或使用 SSH 隧道/TLS 反向代理访问：

ssh -L 3443:127.0.0.1:3443 <user>@<server-ip>
# 然后在本机浏览器打开 http://127.0.0.1:3443

登录信息：

用户名默认是 admin（可通过 ZTNCUI_USER 修改）
密码不再使用公开默认值；如未通过 ZTNCUI_BOOTSTRAP_PASSWORD 或 ZTNCUI_BOOTSTRAP_PASSWORD_FILE 指定，容器首次启动时会生成随机密码
生成的初始密码保存在 ./data/zerotier/config/ztncui.initial-password，建议首次登录后立即修改并妥善保存

docker exec ${CONTAINER_NAME:-myztplanet} sh -c 'cat /app/config/ztncui.initial-password'

安全提示：不要再使用公开默认管理凭据。如果确实需要把管理界面暴露到公网，请优先使用 TLS 反向代理；公网明文 HTTP 仅适合临时实验环境，并需要显式开启相应公开访问开关。

3.5.2 创建网络

登录后点击 "Networks" 菜单
点击 "Add Network" 按钮创建新网络
输入一个便于识别的网络名称，其他选项可保持默认
点击 "Create Network" 按钮完成创建

创建成功后系统会自动生成一个网络 ID，这个 ID 在后续客户端配置时会用到，请记录下来。

3.5.3 分配网络 IP

选中 "Easy Setup"
生成 IP 范围

4. 客户端配置

ZeroTier 支持多种主流操作系统的客户端，包括：

Windows
macOS
Linux
Android

4.0 一键安装与替换 planet

Windows、Linux、macOS 可以使用仓库内的一键脚本自动完成 ZeroTier 安装、下载并替换 planet、重启服务；传入网络 ID 时还会自动执行 join。

先在部署服务器上读取文件服务密钥：

FILE_KEY=$(cat ./data/zerotier/config/file_server.key)

PLANET_URL 建议使用已经配置好 TLS 的 HTTPS 反向代理地址，例如 https://files.example.com/planet。脚本默认拒绝明文 HTTP；仅临时内网测试时才使用 --allow-insecure-http 或 -AllowInsecureHttp。

Windows（管理员 PowerShell）：

$PlanetUrl = "https://files.example.com/planet"
$FileKey = "替换为 ./data/zerotier/config/file_server.key 的内容"
$NetworkId = "替换为网络 ID，可不传"
$Script = "$env:TEMP\install-zerotier-client.ps1"
Invoke-WebRequest "https://raw.githubusercontent.com/xubiaolin/docker-zerotier-planet/master/scripts/install-zerotier-client.ps1" -OutFile $Script
powershell -ExecutionPolicy Bypass -File $Script -PlanetUrl $PlanetUrl -FileKey $FileKey -NetworkId $NetworkId

Linux/macOS：

curl -fsSL https://raw.githubusercontent.com/xubiaolin/docker-zerotier-planet/master/scripts/install-zerotier-client.sh \
  | sudo bash -s -- \
      --planet-url "https://files.example.com/planet" \
      --file-key "${FILE_KEY}" \
      --network-id "替换为网络 ID，可不传"

下载 planet 时脚本使用 Authorization: Bearer 请求头，不会把 FILE_KEY 放进 URL。

4.1 Windows 配置

以下是手动配置步骤，适合排障或不希望使用一键脚本的场景。

步骤 1：下载客户端

首先去 ZeroTier 官网下载一个 ZeroTier 客户端

步骤 2：替换 planet 文件

将 planet 文件覆盖粘贴到 C:\ProgramData\ZeroTier\One 中（这个目录是个隐藏目录，需要允许查看隐藏目录才行）

步骤 3：重启服务

按 Win + S 搜索 "服务"
找到 ZeroTier One，并且重启服务

步骤 4：加入网络

使用管理员身份打开 PowerShell，执行如下命令：

PS C:\Windows\system32> zerotier-cli.bat join 网络id
200 join OK
PS C:\Windows\system32>

注意：网络 ID 就是在网页里面创建的那个网络 ID

步骤 5：授权设备

登录管理后台可以看到有个新的客户端，勾选 Authorized 即可

IP assignment 里面会出现 ZeroTier 的内网 IP

步骤 6：验证连接

执行如下命令验证连接状态：

PS C:\Windows\system32> zerotier-cli.bat peers
200 peers
<ztaddr>   <ver>  <role> <lat> <link> <lastTX> <lastRX> <path>
fcbaeb9b6c 1.8.7  PLANET    52 DIRECT 16       8994     1.1.1.1/9993
fe92971aad 1.8.7  LEAF      14 DIRECT -1       4150     2.2.2.2/9993
PS C:\Windows\system32>

可以看到有一个 PLANET 和 LEAF 角色，连接方式均为 DIRECT（直连）

到这里就加入网络成功了！

4.2 Linux 客户端

以下是手动配置步骤，适合排障或不希望使用一键脚本的场景。

配置步骤：

安装 Linux 客户端软件
进入目录 /var/lib/zerotier-one
替换目录下的 planet 文件
重启 zerotier-one 服务：service zerotier-one restart
加入网络：zerotier-cli join 网络id
管理后台同意加入请求
执行 zerotier-cli peers 可以看到 PLANET 角色

4.3 安卓客户端配置

推荐使用 Zerotier 非官方安卓客户端

4.4 MacOS 客户端配置

以下是手动配置步骤，适合排障或不希望使用一键脚本的场景。

配置步骤：

进入 /Library/Application\ Support/ZeroTier/One/ 目录，并替换目录下的 planet 文件
重启 ZeroTier-One：cat /Library/Application\ Support/ZeroTier/One/zerotier-one.pid | sudo xargs kill
加入网络：zerotier-cli join 网络id
管理后台同意加入请求
执行 zerotier-cli peers 可以看到 PLANET 角色

4.5 OpenWRT 客户端配置

配置步骤：

安装 ZeroTier 客户端
进入目录 /etc/config/zero/planet
替换目录下的 planet 文件
在 OpenWRT 网页后台先关闭 ZeroTier 服务，再开启 ZeroTier 服务
在 OpenWRT 网页后台加入网络
管理后台同意加入请求
执行 ln -s /etc/config/zero /var/lib/zerotier-one
执行 zerotier-cli peers 可以看到 PLANET 角色

4.6 iOS 客户端配置

方案一：越狱方案 越狱后安装 ZeroTier，然后替换 planet 文件

方案二：WireGuard 方案 使用 WireGuard 接入到 ZeroTier 网络

5. 管理面板 TLS/反向代理配置

默认部署会把管理界面和文件下载服务绑定在宿主机本地地址（例如 127.0.0.1:3443、127.0.0.1:3000）。如果需要公网访问，请使用带有效证书的 HTTPS 反向代理，不建议直接暴露明文 HTTP。

下面示例使用两个域名分别代理管理界面和文件下载服务；也可以按自己的网关策略调整：

upstream zerotier_ui {
  server 127.0.0.1:3443;
}

upstream zerotier_files {
  server 127.0.0.1:3000;
}

server {
  listen 443 ssl http2;
  server_name {CUSTOM_DOMAIN}; # 管理界面域名

  ssl_certificate     pem 或 crt 文件的路径;
  ssl_certificate_key key 文件的路径;
  ssl_protocols TLSv1.2 TLSv1.3;
  ssl_prefer_server_ciphers off;

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

server {
  listen 443 ssl http2;
  server_name files.{CUSTOM_DOMAIN}; # 文件下载域名

  ssl_certificate     pem 或 crt 文件的路径;
  ssl_certificate_key key 文件的路径;
  ssl_protocols TLSv1.2 TLSv1.3;
  ssl_prefer_server_ciphers off;

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

server {
  listen 80;
  server_name {CUSTOM_DOMAIN} files.{CUSTOM_DOMAIN};
  return 301 https://$host$request_uri;
}

通过反向代理下载文件时，仍然需要请求头认证：

FILE_KEY=$(cat ./data/zerotier/config/file_server.key)
curl -H "Authorization: Bearer ${FILE_KEY}" https://files.{CUSTOM_DOMAIN}/planet -o planet

更多凭据轮换、旧版本迁移、ztncui 引用更新和公开访问注意事项见 SECURITY.md。

6. 卸载

停止并删除容器：

docker compose down

如需同时删除数据目录：

rm -rf ./data/zerotier

升级：

docker compose pull
docker compose up -d

可选维护命令：

./scripts/ztplanet.sh reset-password
./scripts/ztplanet.sh doctor

7. 常见问题

Q1: 为什么我 ping 不通目标机器？

A: 请检查防火墙设置，Windows 系统需要允许 ICMP 入站，Linux 同理

Q2: iOS 客户端怎么用？

A: iOS 客户端插件在这里，设备需要越狱：https://github.com/lemon4ex/ZeroTieriOSFix

Q3: 为什么看不到官方的 Planet？

A: 该项目剔除了官方服务器，只保留了自定义的 Planet 节点

Q4: 我更换了 IP 需要怎么处理？

A: 如果 IP 更换了，则需要重新部署，相当于全新部署

Q5: PVE lxc 容器没有创建网卡？

A: 需要修改 lxc 容器的配置，同时 lxc 容器需要取消勾选"无特权"

配置文件位置在 /etc/pve/lxc/{ID}.conf

Proxmox 7.0 之前的版本添加以下内容：

lxc.cgroup.devices.allow: c 10:200 rwm
lxc.mount.entry: /dev/net/tun dev/net/tun none bind,create=file

Proxmox 7.0 之后的版本添加以下内容：

lxc.cgroup2.devices.allow: c 10:200 rwm
lxc.mount.entry: /dev/net/tun dev/net/tun none bind,create=file

Q6: 管理后台忘记密码怎么办？

A: 可以执行 ./scripts/ztplanet.sh reset-password，或直接在容器内重置。下面示例会生成新密码、写入 /app/config/ztncui.initial-password，并立即应用：

docker exec ${CONTAINER_NAME:-myztplanet} sh -c 'umask 077; openssl rand -base64 24 | tr -d "\n" > /app/config/ztncui.initial-password; printf "\n" >> /app/config/ztncui.initial-password; ZTNCUI_ADMIN_PASSWORD_FILE=/app/config/ztncui.initial-password node /app/ztncui_admin.js'
docker restart ${CONTAINER_NAME:-myztplanet}
docker exec ${CONTAINER_NAME:-myztplanet} sh -c 'cat /app/config/ztncui.initial-password'

Q7: 为什么连不上 planet？

A: 请检查防火墙，如果是阿里云、腾讯云用户，需要在对应平台后台防火墙放行端口。Linux 机器上也要放行，如果安装了 ufw 等防火墙工具。

Q8: 如何判断是直连还是中转？

A: 管理员权限执行终端，运行 zerotier-cli peers

<ztaddr>   <ver>  <role> <lat> <link>   <lastTX> <lastRX> <path>
69c0d507d0 -      LEAF      -1 RELAY
93caa675b0 1.12.2 PLANET  -894 DIRECT   4142     4068     110.42.99.46/9994
ab403e2074 1.10.2 LEAF      -1 RELAY

如果你的 ztaddr 是 RELAY，就说明是中转

Q9: 为什么我的 ZeroTier 传输不稳定？

A: 由于 ZeroTier 使用的是 UDP 协议，部分地区可能对 UDP 进行了 QoS，可以考虑使用 OpenVPN。

Q10: 支持域名吗？

A: 暂不支持

Q11: ARM 服务器可以搭建吗？

A: 可以

Q12: 推荐用什么方式部署？

A: 推荐直接使用仓库内的 compose.yaml：

cp .env.example .env
vim .env
docker compose up -d

如果只是临时实验需要公网明文访问管理界面和文件服务，可设置 HOST_BIND_IP=0.0.0.0，并显式加载公网 override：

docker compose -f compose.yaml -f compose.public-http.yaml up -d

该 override 会将容器内 PUBLIC_HTTP 设为 true。生产公网访问仍推荐 TLS 反向代理。

Q13: 构建时是否锁定上游版本？

A: 是。Dockerfile 通过 ZEROTIER_REF 指定 ZeroTier One 源码引用，并通过 ZTNCUI_REF 固定 ztncui 到完整提交 1b2284864de48d2dcae22582fff122fe24909c3d；构建时会输出并校验实际 checkout 的提交。GitHub Actions 和本地 build.sh 都会显式传入 ZeroTier 构建参数，避免自动构建时镜像标签和源码版本脱节。

ZeroTier One 新分支已移除 legacy attic/world 目录。本项目不再依赖该目录构建 mkworld，而是直接使用当前 zerotier-idtool genmoon 根据 worldType=planet 生成 planet world 文件。

如需升级 ztncui，请先审查上游变更，再同步更新 Dockerfile 默认 ZTNCUI_REF 和 .github/workflows/image-build.yml 中的 ZTNCUI_REF，然后重新构建验证。当前上游固定提交不包含 package-lock.json/npm-shrinkwrap.json，镜像仍会执行 npm install 解析 npm 传递依赖；在引入经审查的锁文件前，这仍是已知的剩余可复现性风险。

8. 开发计划

🥰 您的捐助可以让开发计划的速度更快 🥰

多 planet 支持
3443 端口自定义支持
planet 和 controller 分离部署

9. 风险声明

本项目仅供学习和研究使用，不鼓励用于商业用途。我们不对任何因使用本项目而导致的任何损失负责。

10. 类似项目

WireGuard 一键脚本

11. 捐助和支持

如果觉得本项目对您有帮助，欢迎通过扫描下方赞赏码捐助项目 :)

12. 鸣谢

感谢以下网友投喂，你们的支持和鼓励是我不懈更新的动力

按时间顺序排序：

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

23 KiB Raw Permalink Blame History Unescape Escape

Docker ZeroTier Planet

📢 交流群

Telegram

QQ Group

📱 微信公众号

✨ 功能特性

📋 目录

0. 托管服务

0.1 自运营容器服务

0.2 雨云容器服务

0.3 微信公众号

1. ZeroTier 介绍

工作原理

ZeroTier 网络中的关键概念

2. 为什么要自建 PLANET 服务器

🚀 性能优势

🔒 安全优势

💪 可靠性优势

3. 开始安装

3.1 环境准备

服务器要求

软件依赖

系统要求

3.1.1 安装 Git

3.1.2 安装 Docker

3.1.3 启动 Docker

3.1.4 配置 Docker 加速镜像（可选）

3.2 下载项目源码

3.3 使用 Docker Compose 安装

3.4 下载 planet 文件

3.5 新建网络

3.5.1 访问管理界面

3.5.2 创建网络

3.5.3 分配网络 IP

4. 客户端配置

4.0 一键安装与替换 planet

4.1 Windows 配置

步骤 1：下载客户端

步骤 2：替换 planet 文件

步骤 3：重启服务

步骤 4：加入网络

步骤 5：授权设备

步骤 6：验证连接

4.2 Linux 客户端

4.3 安卓客户端配置

4.4 MacOS 客户端配置

4.5 OpenWRT 客户端配置

4.6 iOS 客户端配置

5. 管理面板 TLS/反向代理配置

6. 卸载

7. 常见问题

Q1: 为什么我 ping 不通目标机器？

Q2: iOS 客户端怎么用？

Q3: 为什么看不到官方的 Planet？

Q4: 我更换了 IP 需要怎么处理？

Q5: PVE lxc 容器没有创建网卡？

Q6: 管理后台忘记密码怎么办？

Q7: 为什么连不上 planet？

Q8: 如何判断是直连还是中转？

Q9: 为什么我的 ZeroTier 传输不稳定？

Q10: 支持域名吗？

Q11: ARM 服务器可以搭建吗？

Q12: 推荐用什么方式部署？

Q13: 构建时是否锁定上游版本？

8. 开发计划

9. 风险声明

10. 类似项目

11. 捐助和支持

12. 鸣谢

📚 参考链接

23 KiB

Raw Permalink Blame History