《ZeroTier教程》02-使用docker部署自建PLANET和controller 二次开发ztncui控制面板

派风社区Piwind2025-09-27 23:55

原文永久链接：https://forum.piwind.com/d/39-zerotierjiao-cheng-02-shi-yong-dockerbu-shu-zi-jian-planethe-controller-er-ci-kai-fa-ztncuikong-zhi-mian-ban

Date: 2024-10-02

Update: 2025-09-19

2. 自建PLANET和controller

背景

ZeroTier 网络中的关键概念：

概念 说明
PLANET zerotier网络的根服务器，负责寻址、发现和中继，长度为10的ztaddr
MOON 作为PLANET的补充，节点在尝试P2P连接时，会优先使用MOON，无法建立的情况下再回落到PLANET。MOON无法单独工作，尽管MOON可以记录节点的ID信息确定连接线路，但是前提是controller也加入到MOON中来为节点授权（而zerotier的官方controller只加入了官方自己的PLANET）
LEAF 所有接入zerotier网络的节点，长度为10的随机的ztaddr，且由PLANET决定其ztaddr的唯一性（不唯一就重新生成），节点之间通过PLANET和MOON协调通信，并由controller控制授权
controller 通过controller创建的 Network，ID为16位，其前10位就是controller的ztaddr，自建PLANET的时候，controller和PLANET的ztaddr是一致的

官方PLANET列表：

可以通过nslookup查一下官方PLANET的ip地址：

bash 复制代码 
## 查询所有
nslookup root.zerotier.com

## 逐个查询
nslookup root-lax-01.zerotier.com
nslookup root-mia-01.zerotier.com
nslookup root-tok-01.zerotier.com
nslookup root-zrh-01.zerotier.com
nslookup root-alice-sfo-01.zerotier.com

由此可见：国内是没有zerotier官方PLANET的，自建有助于提升连接稳定性、直连成功率。

在杭州移动看到的连接的官方PLANET：

复制代码 
778cde7190 -      PLANET   472 DIRECT   25184    29758    103.195.103.66/9993【美国Florida州】
cafe04eba9 -      PLANET   440 DIRECT   25186    29792    2a02:6ea0:d405::9993/9993
cafe80ed74 -      PLANET   260 DIRECT   4728     29722    2a02:6ea0:c87f::1/9993
cafefd6717 -      PLANET  -178 DIRECT   25188    30412    79.127.159.187/9993【日本东京】

技术路线选择：

  • 自建PLANET：连接相对更快速更稳定

    不经过zerotier官方服务器，全程私有化流量，更安全更隐私

    controller也是自建的，因此自己掌握网络配置，也无需受到官方的类似设备数量免费上限25的限制

  • 自建MOON：作为官方PLANET的补充，节点在尝试P2P连接时，会优先使用MOON，无法建立的情况下再回落到官方PLANET（可以通过官方的 zerotier-idtool genmoon 快速创建MOON节点）

    更简单轻量，而且本质上也可以用于自建的PLANET

本次先着手于自建PLANET和controller。

前后速度对比

  • 设备1杭州移动家宽，设备2安徽电信家宽，PLANET用官方，355KB/s，而且非常不稳定

  • 设备1杭州移动家宽，设备2杭州联通5G，PLANET用官方，4MB/s

  • 设备1杭州移动家宽，设备2杭州联通5G，PLANET用自建，8MB/s，连接稳定很多

  • 设备1杭州移动家宽，设备2安徽电信家宽，PLANET自建，12MB/s，连接稳定在20ms

    白天发现也会连不上，300KB/s，不知道咋回事，91ms连接很不稳定

  • 设备1杭州移动家宽，设备2合肥联通5G，PLANET用自建，12MB/s，连接稳定

结论：

自建PLANET可以缩短建立P2P直连的耗时，提升直连成功率，以及无法直连的情况下走中转的速度会明显有提升；除此之外，对于建立P2P直连后的网速、稳定性的提升不明显

二次开发

ztncui

ztncui项目无法支持反向代理的子路径，使用nginx中的proxy_redirect和sub_filter也无法解决子路径的问题（毕竟不是纯前端项目）【而且项目已经至少2年没有更新了】

这里备注一下nginx尝试改子路径的配置：

复制代码 
        location /console/zerotier/ {
            proxy_pass http://127.0.0.1:20911/;
            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;

            proxy_redirect / /console/zerotier/;
            sub_filter_once off;
            sub_filter 'href="/'  'href="/console/zerotier/';
            sub_filter 'src="/'   'src="/console/zerotier/';
        }

fork了原项目，在新分支 add_basePath 上二次开发，提交PR，再更新到自己的项目的master分支中

docker-zerotier-planet

调整了自动化构建docker镜像的流程，修改了ztncui项目的链接，改为自己二次开发的ztncui，添加了支持环境变量BASE_PATH，使用vars.SPEC_ZEROTIER_TAG可以指定打包docker镜像时用到的zerotier-one的版本号

fork了原项目，二次开发，并通过推送tag到github触发CI来构建docker镜像

搭建流程

在portainer中创建stack，命名为 zerotier-planet，注意点如下：

  • curl -s https://ipv4.icanhazip.com/，可以拿到自己的公网ipv4地址
  • 这里的 ZT_PORT 和对应的映射端口都要一致
  • BASE_PATH就是nginx反向代理的子路径，例如 /console/zerotier

内容如下：

yaml 复制代码 
name: zerotier-planet

services:
  zerotier-planet:
    image: piwind/zerotier-planet:1.14.2
    container_name: zerotier-planet
    restart: unless-stopped
    ports:
      - 9994:9994
      - 9994:9994/udp
      - 3443:3443
      - 3000:3000
    volumes:
      - /data/linux/docker_data/zerotier-planet/dist:/app/dist
      - /data/linux/docker_data/zerotier-planet/ztncui:/app/ztncui
      - /data/linux/docker_data/zerotier-planet/one:/var/lib/zerotier-one
      - /data/linux/docker_data/zerotier-planet/config:/app/config
    environment:
      - IP_ADDR4=<ipv4 addr>
      - IP_ADDR6=
      - ZT_PORT=9994
      - API_PORT=3443
      - FILE_SERVER_PORT=3000
      - BASE_PATH=/console/zerotier

stack启动后还需要配置nginx，添加location块内容如下：

复制代码 
        location /console/zerotier/ {
            proxy_pass http://127.0.0.1:3443/;
            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;
        }
        location /console/zerotier-files/ {
            proxy_pass http://127.0.0.1:3000/;
            proxy_set_header HOST $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        }

ubuntu配置ufw和ufw-docker的情况下设置防火墙：

bash 复制代码 
## 确保目标端口的tcp和udp都是通的（要特别注意ufw-docker在没有给出tcp还是udp的情况下默认是tcp，因此需要写两条）
ufw-docker allow zerotier-planet 9994
ufw-docker allow zerotier-planet 9994/udp

ufw status

ztncui面板初始配置：

  • 首次用默认账号 admin，密码 password 登录，会提示修改密码
  • 顶部 "Add network"，输入Network name即可创建，可以得到Network ID
  • Easy setup，可以方便设置此网络的IP范围

信息：

复制代码 
planet ip：<ipv4 addr>
controller控制台：https://www.example.com/console/zerotier/
planet下载：https://www.example.com/console/zerotier-files/planet?key=<key>
moon下载：https://www.example.com/console/zerotier-files/<16-bit addr>.moon?key=<key>
Network ID：<16-bit network id>
IP池子：10.11.12.0/24，范围为 10.11.12.101~199

**授权设备操作：**到控制台中授权即可（Authorized勾选、IP assignment分配ip）

6. 补充说明

  • 测试UDP端口连通性的办法：

    bash 复制代码 
    ## 服务器
nc -u -l -v 5201

## 客户端
echo "hello" | nc -u -v 123.123.123.123 5201

  • 客户端切换网络的时候，zerotier需要一定时间才会自动切换zerotier的path，期间由于旧的path失效两者无法通信，如果想要尽快重新建立P2P连接，则要手动重新启动zerotier one服务

  • 安卓、iOS客户端，和linux、win客户端通信的延迟较高，不稳定（可能是因为走的方式不一样，手机端都是开启VPN的），但是测试了是从桌面端ping移动端延迟高，而移动端ping桌面端很流畅

    【不过这不是zerotier的问题，拿电脑直接ping手机的内网网段ip，其延迟也很高，也有可能是wifi连接的缘故，而电脑与电脑之间走的是网线】

  • 不同版本的zerotier之间通信可能会遇到延迟高等问题

  • 能否指定让某些network下的所有节点都走中转，不建立P2P连接（因为P2P连接质量不确定性很大）？

    经过测试，目前不行。

    不过看到版本1.16.0里面更新了 Network-Specific Relays (preview / beta)，这个功能后面应该会有

  • 自建PLANET项目中转不成功的问题：

    就是 zerotier-cli peers 中看不到其他的节点，可以ping上，但是无法正常访问任何端口上的任何服务

  • linux上都要主动发生通信，才会在peers中显示

本文声明：

  • 此文可能会存在排版、样式不美观，图片无法显示等问题
  • 文章内容在原文永久链接中会定期更新，此文不做同步更新
  • 限于篇幅长度限制，此文可能会有裁剪

建议阅读原文链接

热门推荐
01GitHub 镜像站点02UV 工具安装与国内镜像源配置指南03Multisim使用教程详尽版--(2025最新版)04KGG转MP3工具|非KGM文件|解密音频05UV安装并设置国内源0646个Nano-banana 精选提示词，持续更新中07Spec-Kit 使用指南08VsCode远程Copilot无法使用Claude Agent问题09jdk21下载、安装（Windows、Linux、macOS）10阿里最新开源Wan2.2-Animate-14B 本地部署教程：统一双模态框架，MoE架构赋能电影级角色动画与替换