Logo

菜单

r117
r117
发布于 2025-07-24 / 84 阅读
3
0

使用Zerotier 部署私人组网

ZeroTier 私有控制器部署文档（使用 ZTNCUI，Docker 方案）

本文基于实际部署经验整理，使用 ZTNCUI 图形界面搭建 ZeroTier 私有控制器，适用于自托管内网穿透、异地组网等场景。

📦 1. 环境准备

  • 操作系统：推荐使用 Ubuntu 20.04+
  • 已安装：
    • Docker
    • Docker Compose（如 Docker 已内置可省略）

安装命令（如未安装）：

sudo apt update
sudo apt install docker docker-compose -y

📁 2. 目录结构

mkdir ~/zerotier
cd ~/zerotier
mkdir ztncui-data
mkdir zerotier-one

🐳 3. 编写 docker-compose.yml

services:
  ztncui:
    image: keynetworks/ztncui
    container_name: ztncui
    restart: always
    network_mode: host
    cap_add:
      - NET_ADMIN
      - SYS_ADMIN
    devices:
      - /dev/net/tun
    environment:
      - HTTP_PORT=4000
      - HTTP_ALL_INTERFACES=yes
      - ZTNCUI_PASSWD=admin@123
    volumes:
      - ./zerotier-one:/var/lib/zerotier-one
      - ./ztncui-data:/opt/key-networks/ztncui/etc

📌 说明：

  • 无需单独部署 ZeroTier client，ztncui 自身已等效 client；
  • 使用 host 网络，确保其具备 TUN、9993/UDP 能力；
  • ztncui-data 是给 ztncui 自己用的目录（配置/账户等）；
  • zerotier-one 是给 ZeroTier 控制器使用的核心数据目录；
  • 请确保开放防火墙端口：
    • 4000/TCP 用于访问 ZTNCUI 控制面板；
    • 9993/UDP 用于 ZeroTier 网络通信。

🚀 4. 启动服务

docker compose up -d

🌐 5. 初始化控制器

（1）访问管理页面

浏览器访问：

http://<服务器公网IP>:4000
  • 用户名：admin
  • 密码：ZTNCUI_PASSWD 环境变量设置的值（如上文设为 admin@123）

（2）创建网络

  • 点击「Create Network」
  • 设置 IP 段（如 10.10.10.0/24）
  • 保存后记下生成的 Network ID

（3）将控制器自身加入网络

docker exec -it ztncui zerotier-cli join <NetworkID>

然后在 UI 中 Approve 此设备，并勾选「Allow Managed IP」。 这一步主要是让之后可以改用内部ip访问控制器

🌙 6. 配置 Moon（可选但推荐）

用于帮助客户端节点发现控制器，适合完全私有部署。 下面演示的是用ztncui所在容器启用moon，虽然感觉有点我找我自己的感觉，但是按理说，不部署moon会导致找控制器的这部操作用官方给的planet节点，缺少安全性(?)，总之如果有别的物理服务器，单独作为moon肯定更好 注意部署好的moon不需要加入网络，但需要每个client单独orbit它

（1）进入容器

docker exec -it ztncui bash

（2）生成 moon.json

zerotier-idtool initmoon /var/lib/zerotier-one/identity.public > /var/lib/zerotier-one/moon.json

（3）修改 moon.json 中 endpoints

使用任意编辑器打开 moon.json，将 stableEndpoints 设置为你的公网 IP 和端口（通常为 9993）：

"stableEndpoints": [ "1.2.3.4/9993" ]

确保 IP 为客户端可访问的控制器公网地址。

（4）生成 .moon 文件

zerotier-idtool genmoon /var/lib/zerotier-one/moon.json

该命令将生成一个 .moon 文件，但不会自动放入 moon.d 目录。

（5）手动创建 moon.d 目录（如不存在）

mkdir -p /var/lib/zerotier-one/moon.d

（6）移动 .moon 文件至 moon.d

mv /var/lib/zerotier-one/*.moon /var/lib/zerotier-one/moon.d/

确保最终 .moon 文件路径如下：

/var/lib/zerotier-one/moon.d/000000xxxxxxxxxx.moon

（7）重启 ZeroTier 服务

zerotier-cli dump   # 可选：查看 Moon 是否被加载

🖥️ 7. 客户端安装与连接

✅ 下载客户端

平台 下载地址
Windows https://www.zerotier.com/download/
macOS https://www.zerotier.com/download/
Linux https://www.zerotier.com/download/
Android Google Play：搜索「ZeroTier」
iOS App Store：搜索「ZeroTier」

✅ Linux 客户端安装示例

curl -s https://install.zerotier.com | sudo bash
sudo zerotier-cli join <NetworkID>

🧭 8. 客户端 Orbit Moon 操作（用于加速发现控制器）

可选步骤，强烈推荐用于客户端主动发现 Moon 控制器，提升连接稳定性。

（1）显式 Orbit

zerotier-cli orbit <moon_id> <moon_id>
  • <moon_id>：.moon 文件名（去掉 .moon 后缀），如 0000003e61ccab48

示例：

zerotier-cli orbit 3e61ccab33 3e61ccab33

执行后客户端会优先尝试通过该 Moon 节点连接控制器。

🔐 9. 建议与维护

  • ✅ 定期备份 ztncui-data/ 和 zerotier-one/，防止数据丢失；
  • ✅ 修改密码：更改 ZTNCUI_PASSWD 后需重启容器；
  • ✅ 建议使用反向代理 + HTTPS 保护 Web 控制台（如 Nginx + Certbot）；
  • ✅ 使用防火墙/安全组限制访问 4000 端口，仅对内网或可信 IP 开放。

🧯 10. 常见问题排查

问题 原因/解决方案
.moon 文件未生成 使用 find / -name '*.moon' 查找文件位置
容器无法访问 9993 network_mode: host 未启用或防火墙阻挡
UI 可用但无法管理网络 未执行 zerotier-cli join 加入控制器网络
orbit 后客户端仍连接不上 .moon 文件未复制/配置错误或未重启客户端
客户端连接控制器失败 检查 endpoints 是否正确指向公网 IP 和 9993

评论