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

原文永久链接：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列表：

Root Server IP Whitelist | ZeroTier Documentation

官方PLANET位置：Los Angeles, Miami, Tokyo, Zurich, San Francisco

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

## 查询所有

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

用到的源项目：https://github.com/key-networks/ztncui
Reverse Proxy Subdirectory? · Issue #11 · key-networks/ztncui

原项目和基于这个的docker项目都无法支持反向代理的子路径
二次开发后的项目：https://github.com/piwind/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

用到的原项目：https://github.com/xubiaolin/docker-zerotier-planet
二次开发后的项目：https://github.com/piwind/docker-zerotier-planet

对应的docker镜像：https://hub.docker.com/r/piwind/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

内容如下：

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的情况下设置防火墙：

## 确保目标端口的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端口连通性的办法：

## 服务器

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中显示

本文声明：

此文可能会存在排版、样式不美观，图片无法显示等问题

文章内容在原文永久链接中会定期更新，此文不做同步更新

限于篇幅长度限制，此文可能会有裁剪

建议阅读原文链接