ZeroTier One Docker 容器化部署与镜像构建实战指南【免费下载链接】ZeroTierOneA Smart Ethernet Switch for Earth项目地址: https://gitcode.com/GitHub_Trending/ze/ZeroTierOneZeroTier 是一个面向地球的智能可编程以太网交换机它允许所有联网设备、虚拟机、容器和应用程序像位于同一物理数据中心或云区域一样相互通信。本文以仓库中的 README.docker.md 为核心结合 Dockerfile.release、entrypoint.sh.release 以及服务端源码系统讲解如何构建 ZeroTier 官方 Docker 镜像、以容器方式运行 zerotier-one、通过环境变量注入身份与配置以及如何借助控制套接字与 local.conf 完成节点管理。读完本文你将能够独立完成 ZeroTier 容器的构建、加入网络、身份预置与生产化调优。ZeroTier 与容器化为什么需要容器版ZeroTier 的定位是智能可编程以太网交换机它把「密码学寻址且安全的点对点网络」称为 VL1与「类似 VXLAN 的以太网仿真层」称为 VL2结合起来。VL2 以太网虚拟化层内置了细粒度的访问控制规则可用于网络微隔离与安全监控等企业级 SDN 特性。所有 ZeroTier 流量都使用只有你掌握的私钥进行端到端加密绝大多数流量走点对点直连仅在无法建立点对点连接时才会借助免费但较慢的中继服务器转发。正因网络是大多数应用的地基而不是应用本身很多使用者希望基于官方配方构建自己的镜像。仓库为此同时提供了两套 Docker 构建方案文件定位Dockerfile.release从官方 deb 仓库拉取指定版本的 zerotier-one 软件包构建README 主推方案Dockerfile.ci在构建阶段用make从源码编译适合 CI 环境验证最新代码构建 Docker 镜像基础镜像与构建流程README.docker.md 说明镜像基于 Debian 构建当前仓库中的 Dockerfile.release 实际基于debian:bookworm并声明了ARG VERSION。整个构建流程分为三步导入 ZeroTier 官方 GPG 签名密钥从download.zerotier.com/contact%40zerotier.com.gpg下载并导入到/usr/share/zerotier/zerotier.gpg随后写入 apt 源deb [signed-by/usr/share/zerotier/zerotier.gpg] http://download.zerotier.com/debian/bookworm bookworm main安装指定版本的软件包apt-get install zerotier-one${VERSION} curl iproute2 net-tools iputils-ping openssl libssl3 -y并清空/var/lib/zerotier-one保证镜像干净。拷贝 entrypoint.sh.release 为/entrypoint.sh并赋予可执行权限随后声明HEALTHCHECK、ENTRYPOINT与空的CMD。构建参数README 中记录了三个构建参数参数说明默认值PACKAGE_BASEURL软件包仓库的基础 URLhttps://download.zerotier.com/debian/buster/pool/main/z/zerotier-one/ARCH软件包的架构Debian 格式必须与镜像架构匹配amd64VERSION必需要拉取的 ZeroTier 版本号无需要说明的是当前仓库的 Dockerfile.release 中实际生效的构建参数是VERSIONREADME 中描述的PACKAGE_BASEURL、ARCH用于更早版本的镜像配方。以仓库实际内容为准VERSION 是唯一必需的构建参数可直接对应 version.h 中定义的版本三元组当前为 1.16.2。构建命令docker build -f Dockerfile.release -t mybuild --build-arg VERSION1.6.5 .-f Dockerfile.release指定使用发布版 Dockerfile-t mybuild指定镜像标签--build-arg VERSION1.6.5传入要安装的版本号。构建完成后mybuild即为可运行的容器镜像。运行容器加入一个或多个网络运行前提zerotier/zerotier镜像对宿主有两个硬性要求CAP_NET_ADMIN能力zerotier-one 需要创建和配置虚拟网卡、路由必须通过--cap-add NET_ADMIN授予/dev/net/tun设备VL2 以太网仿真依赖 TUN/TAP 驱动必须通过--device /dev/net/tun把设备转发进容器。若/dev/net/tun缺失程序将无法启动。这一点在仓库另一个容器化示例 ext/installfiles/linux/zerotier-containerized/main.sh 中有明确体现启动前会检查/dev/net/tun是否存在否则输出FATAL: cannot start ZeroTier One in container并以非零码退出。加入网络要加入网络直接把网络 ID 作为命令行参数传给容器可以同时传入多个docker run --name myzerotier --rm --cap-add NET_ADMIN --device /dev/net/tun zerotier/zerotier:latest abcdefdeadbeef00这里abcdefdeadbeef00是一个 16 位十六进制网络 ID。容器启动后会为每个网络 ID 在/var/lib/zerotier-one/networks.d/下创建对应的network-id.conf文件然后后台启动 zerotier-one主进程则进入无限睡眠等待。验证网络状态控制套接字加入所有网络后容器会进入休眠直到被终止。注意在 ZeroTier 中加入网络并不代表你已获得 IP 或可以做任何事。在尝试监听网络之前应先用控制套接字确认网络可用docker exec myzerotier zerotier-cli listnetworks输出会列出每个网络的 ID、状态如OK、ACCESS_DENIED、类型、分配的地址等。在没有预先配置身份的情况下通常意味着你需要登录 ZeroTier Central 管理后台找到你的节点身份10 位十六进制地址点击该网络对应的勾选框完成授权网络状态才会变为OK并分配地址。进程与优雅退出机制entrypoint.sh.release 中zerotier-one是以后台方式nohup /usr/sbin/zerotier-one 启动的容器真正的主进程是一个休眠的 shell 脚本。这种设计允许zerotier-one在 Docker 特有的场景下优雅退出脚本用trap killzerotier INT TERM捕获 SIGINT/SIGTERM向记录在/var/lib/zerotier-one/zerotier-one.pid中的进程号发送kill后再退出避免容器停止时留下孤儿进程。启动后脚本会循环调用grepzt()检查 pid 文件存在且对应/proc/pid目录存在等待守护进程就绪期间如果存在nohup.out还会打印末尾 10 行便于排查。环境变量身份、密钥与配置注入镜像通过环境变量暴露节点管理的几个关键开关。这些变量在 entrypoint.sh.release 中由mkztfile函数落地为/var/lib/zerotier-one/下的真实文件mkztfile() { file$1 mode$2 content$3 mkdir -p /var/lib/zerotier-one echo -n $content /var/lib/zerotier-one/$file chmod $mode /var/lib/zerotier-one/$file }环境变量作用落盘文件文件权限ZEROTIER_JOIN_NETWORKS以环境变量方式声明要加入的网络空格分隔可多个为每个 ID 在networks.d/创建.conf—ZEROTIER_API_SECRET替换authtoken.secret管理控制套接字的认证密钥authtoken.secret、metricstoken.secret0600ZEROTIER_IDENTITY_PUBLIC写入节点的identity.public文件可用zerotier-idtool生成identity.public0644ZEROTIER_IDENTITY_SECRET写入节点的identity.secret文件identity.secret0600ZEROTIER_LOCAL_CONF设置 zerotier-one 的local.conf文件内容local.conf0644几个值得注意的实现细节ZEROTIER_API_SECRET同时写入两个文件authtoken.secret是 JSON/HTTP 控制 API 的认证令牌metricstoken.secret用于指标接口。容器暴露在localhost:9993的控制端口正是靠它鉴权详见 service/README.md 中关于 API 认证的说明。身份文件成对出现identity.public与identity.secret必须配套。zerotier-idtool是zerotier-one二进制的子命令在 Dockerfile.ci 中通过符号链接方式提供可生成身份对。预置身份的价值在于容器重建后节点地址不变不必重新在 Central 后台授权。ZEROTIER_LOCAL_CONF注入的是 JSON 文本脚本会原样写入local.conf0644若 JSON 非法service/OneService.cpp 会在启动时直接报错unable to parse local.conf。因此注入内容必须保证是合法的 JSON。此外脚本还会无条件写入zerotier-one.port内容9993权限 0600固定节点监听端口便于端口转发与管理。深入 local.conf容器内的高级节点配置ZEROTIER_LOCAL_CONF注入的local.conf是 zerotier-one 的本地节点配置完整字段定义与示例见 service/README.md。它的顶层结构如下{ physical: { /* 作用于物理 L2/L3 网络路径的设置 */ NETWORK/bits: { /* 网络如 10.0.0.0/24 或 fd00::/32 */ blacklist: true|false, /* 为 true 时对该路径屏蔽所有 ZeroTier 流量 */ trustedPathId: 0|!0, /* 非零则定义为可信路径见下文 */ mtu: 0|!0 /* 非零则设置该路径的 UDP 最大负载 MTU */ } /* ,... 更多网络 */ }, virtual: { /* 作用于 ZeroTier 虚拟网络设备VL1的设置 */ ##########: { /* 10 位十六进制 ZeroTier 地址 */ try: [ IP/port, ... ], /* 上游/根节点离线时尝试直连对端的提示 */ blacklist: [ NETWORK/bits, ... ] /* 仅对该对端屏蔽某物理路径 */ } }, settings: { /* 其他全局设置 */ primaryPort: 1-65535, /* 覆盖默认端口 9993 及命令行端口 */ secondaryPort: 1-65535, /* 覆盖默认随机辅助端口 */ portMappingEnabled: true|false,/* 默认 true尝试用 uPnP/NAT-PMP 映射端口 */ allowSecondaryPort: true|false, softwareUpdate: apply|download|disable, softwareUpdateChannel: release|beta, interfacePrefixBlacklist: [ eth, ... ], allowManagementFrom: [ NETWORK/bits, ... ] | null, /* 非 null 时允许来自该网络的 JSON/HTTP 管理默认仅 127.0.0.1 */ bind: [ ip, ... ], /* 绑定到指定 IP 而非每个接口 */ allowTcpFallbackRelay: true|false, /* 默认 true允许 TCP 中继回退连接 */ enableMetrics: true|false } }一个可直接用于容器的示例对应 service/README.md 中的示例为{ physical: { 10.0.0.0/24: { blacklist: true }, 10.10.10.0/24: { trustedPathId: 101010024 } }, virtual: { feedbeef12: { try: [ 10.10.20.1/9993 ], blacklist: [ 192.168.0.0/24 ] } }, settings: { softwareUpdate: apply, softwareUpdateChannel: release } }关于trustedPathId的警告可信路径指不需要加密和认证的物理网络。它能带来性能提升但在该路径上会牺牲 ZeroTier 的全部安全特性只有在明确知道风险且确实需要性能时才应使用。使用同一可信路径的所有设备必须为同一网络配置相同的可信路径 ID任意非零正整数。例如 10.0.0.0/24 网段内的一组设备若都对该网络定义可信路径 ID 为25即可在该局域网内走快速可信路径。从 service/OneService.cpp 的源码看运行中的节点会周期性检查local.conf的修改时间并自动重新加载因此容器内修改local.conf或更新ZEROTIER_LOCAL_CONF重启容器后无需重启 zerotier-one 即可让大部分设置生效解析失败时进程会打印ERROR: unable to parse local.conf类错误并拒绝使用该文件。控制面authtoken 与 9993 端口zerotier-cli之所以能在容器内外与守护进程对话靠的是运行在9993 端口的本地 JSON/HTTP 控制 API见 service/README.md。API 的认证令牌保存在authtoken.secret中这正是ZEROTIER_API_SECRET要替换的文件docker exec进入容器后zerotier-cli自动读取该文件完成鉴权。容器外访问的方式是把端口映射出来例如-p 127.0.0.1:9993:9993再配合ZEROTIER_API_SECRET设置你自己的令牌即可远程驱动控制面。控制 API 常用端点包括端点方法说明/statusGET节点运行状态与寻址信息address、version、online 等/networkGET所有已加入网络的成员信息数组/network/network IDGET/POST/DELETE查询、加入POST、离开DELETE网络/peerGET所有对等节点信息例如在容器外执行curl -H X-ZT1-Auth: token http://localhost:9993/status即可获取节点状态。注意 API 对 JSON 字段类型极度敏感布尔值必须是true/false不能加引号整数不能带小数点字段类型不匹配会被忽略或报错。生产实践与技巧端口转发高流量服务建议把容器 IP 的 9993 端口UDP转发到外部让对端可以直接建立点对点连接减少中继依赖。早期容器化示例 ext/installfiles/linux/zerotier-containerized/Dockerfile 就显式声明了EXPOSE 9993/udp。远程管理把localhost:9993转发到控制网络以便远程驱动同时务必通过ZEROTIER_API_SECRET正确设置 authtoken。身份预生成建议在生产环境预先生成身份对zerotier-idtool生成identity.public/identity.secret通过ZEROTIER_IDENTITY_PUBLIC与ZEROTIER_IDENTITY_SECRET注入。这样无论容器如何重建节点的 10 位地址都保持不变Central 后台的授权无需重复操作。持久化数据zerotier-one 的所有运行时数据身份、authtoken、已加入网络、网络配置缓存都位于/var/lib/zerotier-one。若希望容器销毁后保留节点状态应将该目录挂载为卷volume 或 bind-mount这也是 ext/installfiles/linux/zerotier-containerized/Dockerfile 顶部注释明确给出的建议。健康检查Dockerfile.release 声明了HEALTHCHECK --interval1s CMD bash /healthcheck.sh。该脚本由 entrypoint.sh.release 在启动时动态生成对每个命令行参数与ZEROTIER_JOIN_NETWORKS中的网络执行zerotier-cli get id status只有全部返回OK才视为健康。这保证了编排系统如 Kubernetes、Docker Compose能感知网络尚未就绪的容器。CI 环境下的源码构建镜像如果需要基于最新源码而非发布包构建可使用 Dockerfile.ci第一阶段在ubuntu:21.04中用make编译将产物zerotier-one复制到运行阶段并建立zerotier-idtool、zerotier-cli的符号链接同时安装iproute2、net-tools、ping等排障工具。它同样复用 entrypoint.sh.release 作为入口。小结ZeroTier 的容器化方案可以归纳为一条清晰的主线用构建参数锁定版本 → 用 entrypoint 脚本把环境变量落地为身份与配置文件 → 用 9993 控制端口统一管理。掌握了 entrypoint.sh.release 的落盘逻辑与 service/README.md 的local.conf、API 语义就能在容器环境中稳定地预置身份、注入网络配置、实现优雅退出与健康检查进而把 ZeroTier 作为安全网络底座嵌入到自己的编排体系之中。【免费下载链接】ZeroTierOneA Smart Ethernet Switch for Earth项目地址: https://gitcode.com/GitHub_Trending/ze/ZeroTierOne创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考