🚀 使用 Docker Compose 部署 ZeroTier 虚拟局域网（面板 + 中继 + 客户端）

🚀 使用 Docker Compose 部署 ZeroTier 私有网络

本教程将指导您使用 Docker Compose 部署功能完整的 ZeroTier 私有网络解决方案，整合了 ztncui 控制面板、ZeroTier Moon 中继服务器和 ZeroTier 客户端，帮助您构建高性能的虚拟专用网络。

📝 项目简介

ZeroTier 是一款先进的软件定义网络（SDN）工具，能够将分布在全球的设备连接成一个安全的虚拟局域网，仿佛这些设备都在同一个本地网络中。

核心架构组件：

PLANET（行星服务器）：ZeroTier 的官方根服务器
MOON（卫星服务器）：用户自建的私有根服务器，起到代理加速作用
LEAF（网络客户端）：连接到网络的终端设备

ztncui 核心功能：

Web 可视化管理：通过浏览器管理 ZeroTier 网络，无需命令行操作
网络配置管理：轻松创建、编辑和删除网络配置
设备监控：实时查看设备在线状态和 IP 地址分配
用户权限控制：管理用户账户和网络访问权限

📝 项目简介2

ZeroTier 是一款开源的 跨平台虚拟局域网（VLAN）工具，通过 “面板管理 + 中继节点 + 客户端接入” 架构，可将分散在不同网络的设备（如家庭 NAS、公司电脑、云服务器）组成一个统一的虚拟网络，实现设备间直接通信（无需公网 IP 或端口转发）。本次部署包含三个核心组件：

组件	作用	部署环境要求
ztncui	Web 管理面板，用于创建虚拟网络、管理设备授权、查看网络状态	需公网服务器（便于远程管理）
zerotier-moon	中继节点（Moon），优化跨地域设备连接速度，减少延迟	需公网服务器（与面板可同机）
zerotier-one	客户端，安装在需要加入虚拟网络的设备上（如内网 NAS、本地电脑）	内网 / 外网设备均可（需联网）

核心特点

跨平台兼容：支持 Linux、Windows、macOS、Android、iOS，甚至路由器、树莓派，设备接入无门槛；
轻量低耗：单个组件容器内存占用 < 50MB，CPU 消耗可忽略，适配低配置设备（如入门级云服务器、NAS）；
安全加密：设备通信采用端到端加密（AES-256-GCM），虚拟网络 ID（Network ID）唯一，防止未授权接入；
灵活管理：通过 ztncui 面板可视化操作，无需命令行即可完成网络创建、设备授权、IP 分配；
中继优化：Moon 节点解决跨运营商 / 跨地域连接卡顿问题，提升虚拟网络稳定性（默认 ZeroTier 依赖官方中继，自建 Moon 更灵活）；
数据持久化：所有组件的配置（网络信息、设备证书）均通过目录挂载本地存储，容器删除后重启可无缝恢复。

🔧 部署前准备

系统环境要求

操作系统：支持 Linux、Windows、macOS
Docker 引擎：版本 20.10+
Docker Compose：版本 2.0+
硬件资源：
内存：至少 1GB
存储空间：至少 2GB 可用空间
网络：稳定的互联网连接

环境检查

检查 Docker 服务状态 bash systemctl status docker 确保 Docker 服务处于 active (running) 状态
检查 Docker Compose 版本 bash docker compose version
创建部署目录结构 bash mkdir -p /home/compose/zerotier/{ztncui,moon,client} cd /home/compose/zerotier

⚙️ 配置 Docker Compose

1. ztncui 控制面板配置

创建 ztncui/docker-compose.yml 文件：

#version: '3'   
#docker run --restart always -d --name ztncui -e HTTP_PORT=4000 -e HTTP_ALL_INTERFACES=yes -e ZTNCUI_PASSWD=aaaaaa. -p 4000:4000 keynetworks/ztncui
#version: '2'
services:
    ztncui:
        image: keynetworks/ztncui  # 官方面板镜像（稳定版）
        restart: always  # 容器退出自动重启，保障管理服务稳定
        container_name: ztncui  # 容器名，便于管理
        environment:
            - HTTP_PORT=4000  # 容器内面板端口（固定，不可改）
            - HTTP_ALL_INTERFACES=yes  # 允许所有网卡访问面板（公网部署必需）
            - ZTNCUI_PASSWD=aaaaaa.  # 面板登录密码！建议修改为强密码（如 ZT_Admin@2024!）
        ports:
            - '40001:4000' # 端口映射：主机 40001 → 容器 4000（主机端口可自定义，需与开放端口一致）

关键配置说明： - HTTP_ALL_INTERFACES=yes：允许从任意 IP 访问 ztncui 服务 - 数据持久化：确保配置和数据在容器重启后不丢失

2. Moon 中继服务器配置

创建 moon/docker-compose.yml 文件：

#version: '3'   
#docker run --name zerotier-moon -d --restart always -p 9993:9993/udp -v /home/zerotier:/var/lib/zerotier-one seedgou/zerotier-moon -4 1.1.193.1    [公网服务器ip]
#docker run --name zerotier-moon -d --restart always -p 9993:9993/udp -v /moon:/var/lib/zerotier-one -4 1.1.193.1 seedgou/zerotier-moon 
#version: '2'
services:
    zerotier-moon:
        image: seedgou/zerotier-moon  # Moon 中继镜像（seedgou 维护版，兼容 Docker）
        container_name: zerotier-moon  # 容器名，便于管理
        restart: always  # 中继断连后自动重启
        ports:
            - '19993:9993/udp'  # 端口映射：主机 19993/UDP → 容器 9993/UDP（中继通信必需，UDP 协议！）
        volumes:
            # 核心挂载：本地 /moon → 容器 /var/lib/zerotier-one（存储 Moon 配置、证书）
            - '/moon:/var/lib/zerotier-one'
        #command: [--workspace=/siyuanworkspace,--accessAuthCode=xxxxxx,--lang=zh_CN]

        # 关键命令：-4 后接公网服务器 IP（Moon 节点的标识，必须正确！）
        command: [-4 1.1.193.1]  # 替换为你的公网 IP（如 1.2.3.4）

关键配置说明： - Moon 服务器需要公网 IP 地址 - 确保防火墙开放 9993 UDP 端口 - Moon 节点起到代理加速作用，提升连接稳定性

3. ZeroTier 客户端配置

创建 client/docker-compose.yml 文件：

#version: '3'
services:
  zerotier-one: 
    #image: zerotier/zerotier
    image: bltavares/zerotier:latest  # 客户端镜像（bltavares 维护版，跨架构兼容）
    ports:
      # 端口映射：主机 29993 → 容器 9993（可选，用于客户端通信调试）
      - "29993:9993"
    network_mode: bridge  # 桥接模式（默认，无需修改）
    #network_mode: host
    container_name: zerotier-one  # 容器名，便于管理
    #--network=bridge \
    cap_add:
      # 赋予容器网络管理权限（ZeroTier 接入虚拟网络必需）
      - NET_ADMIN
      - SYS_ADMIN
    devices:
      #挂载 tun 设备（Linux 虚拟网络接口，必需）
      - /dev/net/tun
    volumes:
      # 核心挂载：本地 ./conf → 容器 /var/lib/zerotier-one（存储客户端配置、网络证书）
      - ./conf:/var/lib/zerotier-one
    #command: 
      #- <NETWORK ID>
    restart: always  # 客户端断连后自动重连
    #restart: unless-stopped

#1.keynetworks/ztncui搭建面板，
#2.seedgou/zerotier-moon搭建中继moon,
#3.bltavares/zerotier搭建zerotier-one，连接（ztuncui面板的work网络ID）＋（MOON的中继）+列出网络状态和连接状态。

关键配置说明： - NET_ADMIN 和 SYS_ADMIN 权限：用于网络管理 - network_mode: bridge：容器网络模式配置 - 数据持久化：保存客户端配置和网络信息

关键配置说明2：（新手必看）

组件	关键配置项	注意事项
ztncui	`ZTNCUI_PASSWD`	必须修改默认密码！避免面板被未授权访问，建议包含字母 + 数字 + 符号。
zerotier-moon	`command: [-4, 公网IP]`	公网 IP 必须正确，否则 Moon 中继无法被客户端识别，可通过 `curl ifconfig.me` 查看公网 IP。
zerotier-one	`cap_add: [NET_ADMIN, SYS_ADMIN]`	不可删除！客户端需网络管理权限才能接入虚拟网络，删除会导致容器启动失败。
所有组件	`restart: always`	确保服务意外中断后自动恢复，尤其 Moon 和客户端，保障虚拟网络稳定性。

🚀 启动与验证

启动所有服务

按顺序启动三个核心组件：

启动 ztncui 控制面板 bash cd /home/compose/zerotier/ztncui docker compose up -d
启动 Moon 中继服务器 bash cd /home/compose/zerotier/moon docker compose up -d
启动 ZeroTier 客户端 bash cd /home/compose/zerotier/client docker compose up -d

验证服务状态

检查容器运行状态 bash docker ps 应该看到三个服务都处于 Up 状态
验证 ztncui 控制面板
访问 http://你的服务器IP:40001
使用默认凭证登录（用户名：admin，密码：password）
重要：首次登录后立即修改密码
验证 Moon 服务器 bash docker logs zerotier-moon 检查日志确认 Moon 服务正常运行
验证客户端状态 bash docker exec zerotier-one zerotier-cli status 应该显示客户端在线状态

🚀 启动与验证2

2. 步骤 2：启动 Moon 中继并关联网络

（1）启动 Moon 容器

# 进入 Moon 部署目录
cd /opt/zerotier/moon
# 启动容器（首次启动会生成 Moon 配置，约 10 秒）
docker compose up -d

（2）获取 Moon 配置并导入面板

1.进入 Moon 容器，查看 Moon 标识（需复制 moon.json 内容）：

    # 进入 Moon 容器
    docker exec -it zerotier-moon /bin/bash
    # 查看 Moon 配置（复制输出的所有内容，含 {}）
    cat /var/lib/zerotier-one/moon.json
    # 退出容器
    exit

2.导入面板：

回到 ztncui 面板，进入刚创建的网络（如 “Home-VLAN”）；点击「Moon Nodes」→「Add Moon」，粘贴刚才复制的 moon.json 内容；点击「Add」，Moon 中继关联到虚拟网络，后续客户端可通过此中继连接。

3. 步骤 3：启动客户端并加入网络

（1）启动客户端容器

# 进入客户端部署目录
cd /opt/zerotier/one
# 启动容器
docker compose up -d

（2）客户端加入虚拟网络

进入客户端容器，执行加入命令（替换 8056c2e21c000001 为你的 Network ID）：

    # 进入客户端容器
    docker exec -it zerotier-one /bin/bash
    # 加入虚拟网络（Network ID 替换为你的）
    zerotier-cli join 8056c2e21c000001
    # 查看加入状态（显示“JOINED”即成功）
    zerotier-cli status
    # 退出容器
    exit

（3）面板授权客户端

回到 ztncui 面板，进入虚拟网络→「Members」；
找到客户端设备（列表中显示客户端的「Address」，如 a1b2c3d4e5f6）；
点击客户端右侧「Authorize」（授权），并可自定义「IP Assignment」（分配固定 IP，如 10.147.17.10）；
授权后，客户端状态变为「Online」，虚拟网络接入成功！

4. 验证虚拟网络通信

在客户端设备上 ping 面板 / Moon 服务器的虚拟 IP（如面板服务器在虚拟网络中的 IP 为 10.147.17.1）：

# 客户端设备执行 ping 命令（替换为虚拟网络中的 IP）
ping 10.147.17.1

若能 ping 通，说明虚拟网络通信正常；
若不通，检查客户端是否授权、Moon 是否关联网络、端口是否开放（重点 UDP 19993）。

🔌 基础配置与使用

创建和管理 ZeroTier 网络

1.在 ztncui 中创建网络 - 登录 ztncui 控制面板 - 点击 "Add network" 创建新网络 - 配置网络名称和 IP 段（如 192.168.192.0/24）

2.客户端加入网络 bash docker exec zerotier-one zerotier-cli join <网络ID>

3.在 ztncui 中授权设备 - 进入网络管理界面 - 找到未授权的设备并勾选 "Authorized" - 为设备分配静态 IP 地址（可选）

Moon 服务器配置优化

1.生成 Moon 配置文件

   # 进入 Moon 容器
   docker exec -it zerotier-moon bash
   cd /var/lib/zerotier-one
   zerotier-idtool initmoon identity.public > moon.json

2.配置 Moon 端点信息在 moon.json 文件中添加公网 IP：

   {
     "stableEndpoints": ["192.3.148.184/9993"]
   }

3.生成 Moon 签名文件

   zerotier-idtool genmoon moon.json

客户端连接 Moon 服务器

1.将 Moon 文件复制到客户端

   docker cp zerotier-moon:/var/lib/zerotier-one/0000000ac535316c.moon ./client_data/moons.d/

2.重启客户端服务

   docker restart zerotier-one

3.验证 Moon 连接

   docker exec zerotier-one zerotier-cli listpeers

应该能看到 Moon 服务器节点

🔌基础配置与使用2

1. 面板管理（ztncui）

管理设备：在「Members」中授权 / 取消授权设备，分配固定 IP，查看设备在线状态；
修改网络：在「Settings」中调整虚拟网络 IP 段（如改为 192.168.100.x）、启用 DHCP；
查看日志：在「Logs」中查看网络连接日志，排查设备接入问题。

2. Moon 中继优化

多 Moon 部署：若设备分布在多个地域，可在不同地区部署 Moon 中继，面板中添加多个 Moon 节点，客户端会自动选择最优中继；
查看 Moon 状态：进入 Moon 容器执行 zerotier-cli listpeers，查看连接的客户端数量。

3. 客户端操作（zerotier-one）

退出网络：进入客户端容器执行 zerotier-cli leave 网络ID；
查看网络信息：执行 zerotier-cli listnetworks，显示当前加入的网络、虚拟 IP、状态；
设置开机启动：容器已配置 restart: always，设备重启后客户端会自动启动并重新加入网络。

🛠️ 维护与管理

日常维护操作

1.服务监控

   # 查看所有服务状态
   docker ps -a

   # 查看服务日志
   docker compose logs -f

2.数据备份

   # 备份所有配置数据
   tar -czf zerotier-backup-$(date +%Y%m%d).tar.gz /home/compose/zerotier

3.服务更新

   # 更新 ztncui
   cd /home/compose/zerotier/ztncui
   docker compose pull && docker compose up -d

   # 更新客户端
   cd /home/compose/zerotier/client
   docker compose pull && docker compose up -d

性能监控

1.网络状态检查

   # 查看客户端网络状态
   docker exec zerotier-one zerotier-cli listnetworks

   # 查看节点列表
   docker exec zerotier-one zerotier-cli listpeers

2.连接质量测试

   # 测试到 Moon 服务器的延迟
   docker exec zerotier-one ping <Moon服务器IP>

🛠️ 维护与管理2

1. 容器基础操作（分组件）

组件	启动命令	停止命令	查看日志命令
ztncui	`cd /opt/zerotier/ztncui && docker compose up -d`	`cd /opt/zerotier/ztncui && docker compose down`	`docker compose logs -f ztncui`
zerotier-moon	`cd /opt/zerotier/moon && docker compose up -d`	`cd /opt/zerotier/moon && docker compose down`	`docker compose logs -f zerotier-moon`
zerotier-one	`cd /opt/zerotier/one && docker compose up -d`	`cd /opt/zerotier/one && docker compose down`	`docker compose logs -f zerotier-one`

2. 数据备份（防止配置丢失）

组件	备份目录	备份命令（示例）
ztncui	无需单独备份（配置在容器内，重建需重新创建网络）	-
zerotier-moon	`/moon`	`tar -czf moon-backup-$(date +%Y%m%d).tar.gz /moon`
zerotier-one	`./conf`（客户端部署目录）	`cd /opt/zerotier/one && tar -czf one-backup-$(date +%Y%m%d).tar.gz conf`

3. 更新镜像（获取最新功能 / 修复漏洞）

以 Moon 中继为例，其他组件更新步骤相同：

# 进入 Moon 部署目录
cd /opt/zerotier/moon
# 拉取最新镜像
docker compose pull
# 重启容器应用更新（配置不丢失）
docker compose up -d

🐛 常见问题排查

1. 无法访问 ztncui 控制面板

问题现象：浏览器访问 http://IP:40001 无响应

解决方案： - 检查防火墙设置，确保 40001 端口已开放 - 验证容器状态：docker ps | grep ztncui - 查看服务日志：docker logs ztncui

2. 客户端无法加入网络

问题现象：zerotier-cli join 命令执行失败

解决方案： - 检查网络 ID 是否正确 - 验证客户端与控制面板的网络连通性 - 检查客户端时间同步设置

3. Moon 服务器不生效

问题现象：客户端无法连接 Moon 服务器

解决方案： - 验证 Moon 配置文件是否正确生成 - 检查 Moon 文件是否已正确放置到客户端的 moons.d 目录 - 确认防火墙已开放 9993 UDP 端口

4. 网络连接不稳定

问题现象：设备间连接时断时续

解决方案： - 检查 Moon 服务器的网络带宽 - 验证 NAT 穿透是否正常工作 - 考虑在更多地理位置部署 Moon 服务器

5. 设备授权问题

问题现象：设备已加入但无法通信

解决方案： - 在 ztncui 中检查设备是否已授权 - 验证 IP 地址分配是否正确 - 检查网络路由设置

通过本教程，您已经成功部署了完整的 ZeroTier 私有网络解决方案。这个架构结合了 ztncui 的便捷管理、Moon 服务器的加速优化和 ZeroTier 客户端的稳定连接，为您提供了一个高性能、可自托管的虚拟专用网络环境。如果在使用过程中遇到其他问题，可以参考 ZeroTier 官方文档或相关社区资源。

🐛 常见问题排查2

1. 面板无法访问（ERR_CONNECTION_REFUSED）

原因 1：40001 端口未开放或被占用。解决：
1. 检查端口：sudo lsof -i :40001，若占用则停止对应服务；
2. 重新开放端口：sudo ufw allow 40001/tcp，云服务器同步安全组。
3. 原因 2：面板密码错误。解决：修改 docker-compose.yml 中的 ZTNCUI_PASSWD，重启容器：docker compose down && docker compose up -d。

2. Moon 中继无法关联到面板（导入 moon.json 失败）

原因 1：Moon 容器中 moon.json 未生成（首次启动未完成）。解决：等待 30 秒后重新进入容器查看 moon.json，或重启 Moon 容器。
原因 2：command 中的公网 IP 错误。解决：修改 docker-compose.yml 中的公网 IP，重启 Moon 容器，重新生成 moon.json 并导入。

3. 客户端加入网络失败（显示 “NOT_JOINED”）

原因 1：Network ID 错误（复制时多空格 / 少字符）。解决：核对面板中的 Network ID，重新执行 zerotier-cli join 正确ID。
原因 2：客户端未授权（面板中未点击「Authorize」）。解决：面板进入网络→「Members」，找到客户端设备，点击「Authorize」，等待 10 秒后查看状态。
原因 3：UDP 19993 端口未开放（Moon 中继通信必需）。解决：公网服务器执行 sudo ufw allow 19993/udp，云服务器安全组添加 UDP 19993 入站规则。

4. 虚拟网络内设备无法 ping 通

原因 1：设备防火墙阻止 ICMP 协议（ping 依赖 ICMP）。解决：关闭设备防火墙（或允许 ICMP 协议），如 Linux 执行 sudo ufw allow icmp。
原因 2：虚拟 IP 分配错误（客户端未获取到虚拟 IP）。解决：面板中查看客户端「IP Assignment」，若为空，点击「Assign IP」手动分配，重启客户端容器。