ZeroTier 手册页构建指南从 Markdown 源文件到 roff/man 格式的完整工具链【免费下载链接】ZeroTierOneA Smart Ethernet Switch for Earth项目地址: https://gitcode.com/GitHub_Trending/ze/ZeroTierOne导读本文基于 ZeroTierOne 仓库中 doc/README.md 及其配套的构建脚本与手册页源文件完整讲解该项目的 Unix 手册页man pages生成流程如何使用ronn或 Node.js 的marked-man把 Markdown 编写的手册源文件编译为 roff/man 格式以及这套流程产出的zerotier-one(8)、zerotier-cli(1)、zerotier-idtool(1)三大手册各自覆盖的核心命令与配置项。读完本文你将掌握 ZeroTier 文档目录的组织方式、两种构建工具链的取舍与安装方法、构建脚本的逐行逻辑并能通过仓库源码验证手册中描述的开关参数、文件布局与认证机制的真实实现。一、doc 目录手册页的源文件与构建产物ZeroTier 的文档全部集中在仓库的 doc/ 目录下它既是手册页的“源码库”也是构建脚本的工作目录。目录内同时保存 Markdown 源文件与编译后的 roff/man 产物文件类型说明README.md说明文档介绍手册页构建方法本文主体build.sh构建脚本将三个.md源文件编译为.1/.8手册zerotier-one.8.md手册源文件服务端守护进程zerotier-one(8)的手册源zerotier-cli.1.md手册源文件命令行控制工具zerotier-cli(1)的手册源zerotier-idtool.1.md手册源文件身份管理工具zerotier-idtool(1)的手册源zerotier-one.8等构建产物编译后的 roff/man 格式手册可直接被man读取contactzerotier.com.gpg密钥文档签名用的公钥manpage_encoding_declaration.UTF-8辅助文件编码声明参考手册页的编号遵循 Unix 惯例1表示用户命令8表示系统管理命令守护进程。三个源文件彼此通过 “SEE ALSO” 交叉引用形成一套完整的命令行文档体系。二、构建流程核心./build.sh逐段解析doc/README.md 的核心指令只有一句话在doc/子目录下执行./build.sh即可构建全部手册页。但这一步背后脚本 doc/build.sh 实际上完成了一次完整的“工具链探测与回退”流程。下面逐段拆解2.1 运行前提检查脚本首先强制重置 PATH保证后续调用的ronn、node、npm均来自标准系统路径export PATH/bin:/usr/bin:/usr/local/bin:/sbin:/usr/sbin:/usr/local/sbin随后检查当前目录是否存在zerotier-cli.1.md不存在则报错并提示“必须在 ZeroTier 源码树的 doc/ 子目录下运行”if [ ! -f zerotier-cli.1.md ]; then echo This script must be run from the doc/ subfolder of the ZeroTier tree. fi接着清理上一次的构建产物rm -f *.1 *.2 *.8这一步保证每次构建都是干净的不会残留旧版本手册。2.2 工具链选择ronn 优先marked-man 兜底这是整个构建流程的“分叉点”if [ -e /usr/bin/ronn -o -e /usr/local/bin/ronn ]; then ronn -r zerotier-cli.1.md ronn -r zerotier-idtool.1.md ronn -r zerotier-one.8.md else # 走 marked-man 分支见 2.3 ... fi优先路径ronn。ronn是一个把 Markdown 编译为 roff/man 格式的 Ruby 程序在很多发行版上以软件包形式提供README 中列出的包名包括rubygem-ronn或ruby-ronn也可用gem install ronn安装。脚本通过检查/usr/bin/ronn与/usr/local/bin/ronn两个路径判断其是否可用可用时直接以-rroff 输出模式编译三个源文件。回退路径marked-man。doc/README.md 明确指出Node 的marked-man包与 RubyGems 的ronn是“大致等价”的两种 Markdown→roff 编译器脚本在 ronn 缺失时自动启用后者。2.3 marked-man 分支Node 探测与自动安装进入回退分支后脚本首先在多个常见路径间探测 Node 运行时NODE/usr/bin/node if [ ! -e $NODE ]; then if [ -e /usr/bin/nodejs ]; then NODE/usr/bin/nodejs elif [ -e /usr/local/bin/node ]; then NODE/usr/local/bin/node elif [ -e /usr/local/bin/nodejs ]; then NODE/usr/local/bin/nodejs else echo Unable to find ronn or node/npm -- cannot build man pages! exit 1 fi fi兼容了 Ubuntu/Debian 旧版将 Node 命名为nodejs的历史差异。Node 就绪后若本地尚未安装marked-man脚本会就地执行npm install marked-man将依赖装入doc/node_modules/if [ ! -f node_modules/marked-man/bin/marked-man ]; then echo Installing npm package marked-man -- MarkDown to ROFF converter... npm install marked-man fi最后分别调用 marked-man 完成三次编译$NODE node_modules/marked-man/bin/marked-man zerotier-cli.1.md zerotier-cli.1 $NODE node_modules/marked-man/bin/marked-man zerotier-idtool.1.md zerotier-idtool.1 $NODE node_modules/marked-man/bin/marked-man zerotier-one.8.md zerotier-one.82.4 与项目构建系统的集成这套脚本并非孤立存在它已被挂接到 ZeroTier 的顶层构建体系中。在 make-linux.mk 中可以看到cd doc ; ./build.sh的调用说明执行主构建时手册页会作为doc目标的一部分被自动生成类似地pkg/synology/README.md 与 pkg/synology/dsm7-docker/README.md 中的./build.sh build也走同一条手册页构建路径。README 中“Use ./build.sh to build the manual pages”的描述在仓库内可以找到完整的落地链路。三、构建产物之一zerotier-one(8) 服务端手册zerotier-one(8)是三大手册中的“系统管理”篇描述守护进程本身。它对应仓库入口 one.cpp 中的main()与printHelp()实现手册内容与源码高度一致。3.1 角色定位与运行方式zerotier-one负责把一台 UnixLinux/BSD/macOS系统接入一个或多个 ZeroTier 虚拟网络并把虚拟网络呈现为系统上的虚拟网口文档称其为 “peer to peer VPN client”。它通常由 systemdLinux或 launchdmacOS这类 init 系统托管而不是由用户直接启动。手册特别指出默认必须 root 运行除非使用-U开关且不打算真正加入网络典型场景只跑网络控制器微服务。3.2 工作目录home directory与平台差异服务状态存放在“工作目录”中未指定时按平台取默认值平台默认工作目录Linux/var/lib/zerotier-onemacOS/Library/Application Support/ZeroTier/OneFreeBSD 等 BSD/var/db/zerotier-one手册对工作目录给出了两条硬性约束必须持久化不能被系统清理守护进程自动清除也不能放在易失性存储中因为其中的identity.secret一旦丢失本机唯一的 10 位十六进制 ZeroTier 地址与密钥就随之丢失。此外同一台机器上可以运行多个zerotier-one实例前提是使用不同的主端口primary port与不同的工作目录但单实例本就可加入任意多个网络手册明确表示通常没必要这么做。3.3 控制 API 与认证机制服务通过127.0.0.1:主端口上的 JSON API 被控制默认主端口为 9993。访问该 API 需要授权令牌令牌通常存放于工作目录的authtoken.secret文件中某些平台在启用额外安全选项时非默认还会做 socket 对端 UID/GID 校验。这条机制在 one.cpp 的 CLI 实现中有直接印证程序先尝试从工作目录读取authtoken.secret读取失败时报错 “authtoken.secret not found or readable … (try again as root)”成功读取后把令牌放入X-ZT1-AuthHTTP 请求头再访问本地 API。可以看到手册描述与源码实现一一对应。3.4 首次启动的身份生成在全新工作目录中首次启动服务时会生成 ZeroTier 身份。由于地址生成内置了反 DDoS/反伪造的工作量证明proof of work函数慢速机器上这一过程可能耗时 10 秒以上该过程只发生一次结果保存为工作目录下的identity.secret它定义并“认领”了本机的 ZeroTier 地址及关联的 ECC-256 密钥对。源码中 one.cpp 甚至处理了极罕见的ONE_IDENTITY_COLLISION身份碰撞情况检测到身份冲突时把旧identity.secret另存为.saved_after_collision后重新生成可见身份文件在整个系统中的核心地位。3.5 完整开关列表zerotier-one支持的全部开关如下与 one.cpp 的printHelp()输出一致开关含义-h显示帮助-v显示版本-U跳过权限检查允许非特权用户运行典型场景仅作网络控制器-pport指定主端口默认 9993传 0 则每次随机选择-dfork 后以守护进程方式运行Unix 系-i进入zerotier-idtool人格行为等同于 zerotier-idtool(1)当二进制名或符号链接名为zerotier-idtool时自动生效-q进入zerotier-cli人格行为等同于 zerotier-cli(1)当二进制名或符号链接名为zerotier-cli时自动生效“人格”切换在源码 one.cpp 中有明确实现main()通过strstr(argv[0], zerotier-idtool)/strstr(argv[0], zerotier-cli)判断程序名后分别转入idtool()与cli()入口。也就是说ZeroTier 的三个工具实际上是同一个二进制按名字/开关分化出的三种行为这也是-i、-q开关存在的根本原因。3.6 工作目录文件布局FILES 章节手册详细列出了工作目录下的全部文件及其职责这是排查问题时的第一手资料文件/目录作用与注意事项identity.public身份的公开部分10 位十六进制地址 关联公钥identity.secret含私钥的完整身份。可复制此文件迁移 ZeroTier 地址必须备份私钥泄露意味着他人可冒充本设备并解密流量。对网络控制器而言该文件尤为敏感——它相当于控制器所辖网络这一证书颁发机构的私钥authtoken.secret本地 JSON API 的认证令牌不存在时启动时由安全随机源生成。使用时放入 HTTP 请求的X-ZT1-Auth头devicemap记录zt#接口号到 ZeroTier 网络的映射保证重启后接口编号稳定FreeBSD 等支持长接口名可直接编码网络 ID的系统上可能不存在此文件zerotier-one.pid服务的 PID正常关机时删除zerotier-one.port主端口号JSON API 即位于127.0.0.1:此端口启动时创建zerotier-cli读取它来定位控制 APIcontroller.db启用网络控制器构建时控制器的 SQLite3 数据库controller.db.backup控制器数据库的周期备份手册注明目前为“有变更时每 5 分钟”一次因不是正在使用的 SQLite 文件备份更安全新备份产生时旧文件被轮转而非原地覆写iddb.d/目录缓存过去 60 天内通信过的每个对端的公开身份删除会导致连接初始化变慢需要重新拉取对端完整身份但不会破坏功能networks.d目录缓存已加入网络的配置与证书信息。启动时 ZeroTier 会扫描其中的network ID.conf文件以恢复网络因此touch一个空的network ID.conf即可实现“不经 API 预配置加入某网络”空配置文件会触发从该网络控制器拉取完整配置networks.d的“空文件预配置”技巧尤其值得注意这是脱离 JSON API 的“免交互”入网方式在无 head 环境的批量部署中非常实用。四、构建产物之二zerotier-cli(1) 命令行控制工具zerotier-cli(1)是对本地 JSON API 的轻量封装适合脚本化与日常操作。4.1 权限与认证副本默认情况下zerotier-cli必须以 root 或sudo运行。若想让普通用户也能控制系统 ZeroTier 服务可以手工在工作目录之外创建一份认证令牌副本sudo cp /var/lib/zerotier-one/authtoken.secret /home/user/.zeroTierOneAuthToken chown user /home/user/.zeroTierOneAuthToken chmod 0600 /home/user/.zeroTierOneAuthToken手册同时给出两条重要提醒ZeroTier 服务主目录的位置因平台而异详见zerotier-one(8)授予该用户令牌等于赋予其“把系统接入/断开任意虚拟网络”的能力这是相当重的权限需谨慎评估。4.2 常用开关zerotier-cli的所有开关都可通过help输出查看其中两个最常用开关作用-j输出原始 JSON。比表格输出更易被脚本解析且包含表格中不存在的详细字段-Dpath指定替代的 ZeroTier 服务工作目录。当服务未运行在系统默认位置时用它指明zerotier-one.port与authtoken.secret的查找位置4.3 子命令一览子命令功能help显示帮助info显示本设备信息含 10 位 ZeroTier 地址与当前连接状态加-j获得更详细输出listpeers列出服务知道的 VL1虚拟层 1即对等网络对端即最近约 30 分钟内通信过的对端。注意这些并非虚拟网络上的全部设备还可能包含不在任何已加入网络中的设备通常是根服务器或网络控制器listnetworks列出本系统所属网络及信息例如被分配的 ZeroTier 托管 IP。手工配置在 ZeroTier 接口上的 IP 不会出现在这里需用系统标准网络接口命令查看join入网。只需join加 16 位十六进制网络 ID。随后用listnetworks查看状态要么收到控制器的证书及 IP 分配等信息要么收到access denied——此时需网络管理员在控制器上按设备 10 位 IDinfo可见完成授权leave退网断开连接并删除系统上的对应接口。对端可能因 30 分钟超时机制残留在listpeers中但既然不再共享网络已无法进行有意义的数据通信4.4 实战示例原手册原样保留加入 “Earth”——ZeroTier 的大规模公共测试网络$ sudo zerotier-cli join 8056c2e21c000001 $ sudo zerotier-cli listnetworks ( wait until you get an Earth IP ) $ ping earth.zerotier.net ( you should now be able to ping our Earth test IP )退出 “Earth”$ sudo zerotier-cli leave 8056c2e21c000001列出 VL1 对端$ sudo zerotier-cli listpeers在较新版本的源码中zerotier-cli还扩展出了bond子命令如 one.cpp 中zerotier-cli bond list、bond setmtu、bond peerId rotate等用于链路聚合bonding策略的管理说明该工具的 CLI 面仍在持续演进。五、构建产物之三zerotier-idtool(1) 身份管理工具zerotier-idtool用于创建与操作 ZeroTier 身份。手册开篇即给出身份的本质定义一个 ZeroTier 身份 一对公私钥或仅公开部分 一个由公钥经工作量证明哈希函数推导出的 10 位十六进制地址。5.1 参数约定凡命令参数要求公钥或完整含私钥身份时既可以用文件路径也可以直接在命令行内联身份字符串。5.2 子命令详解子命令语法说明help—显示帮助无参数运行同样显示帮助generategenerate [secret file] [public file] [vanity]生成新身份。指定 secret 文件则完整身份含私钥写入该文件指定 public 文件则公开部分写入均不指定时完整身份输出到 STDOUT。vanity为期望地址开头的十六进制前缀一般不用——因其工作量证明的内在成本生成带已知 16 位4 个十六进制字符前缀的身份在 2.8GHz Core i5 单核上平均需要约两小时validatevalidate identity本地校验身份的密钥与工作量证明函数是否对应只需公开部分getpublicgetpublic full identity从含私钥的完整身份中提取公开部分并输出到 STDOUTsignsign full identity file用 SHA512 ECC-256ed25519对文件内容签名签名以十六进制输出到 STDOUTverifyverify identity file signature用公钥校验sign产生的签名mkcommkcom full identity [id,value,maxdelta] [...]创建并签名网络成员证书。手册注明其“一般无用”——网络控制器会自动完成该工作此命令主要为测试目的保留5.3 实战示例原手册原样保留生成并打印一个新身份$ zerotier-idtool generate生成并同时写入身份的秘密与公开部分$ zerotier-idtool generate identity.secret identity.public生成一个地址以十六进制 “beef” 开头的虚荣地址会很慢$ zerotier-idtool generate beef.secret beef.public beef用身份私钥给文件签名$ zerotier-idtool sign identity.secret last_will_and_testament.txt用公钥校验文件签名$ zerotier-idtool verify identity.public last_will_and_testament.txtsign/verify的底层算法“SHA512 ECC-256ed25519”在仓库中有完整实现证据节点目录下同时存在 SHA512.cpp与 SHA512.hpp和 ECC.cpp与 ECC.hpp汇编优化的 ed25519 实现则位于 ext/ed25519-amd64-asm/含sign.c、open.c、keypair.c等可进一步深入阅读其密码学细节。六、手册页编写规范与交叉引用从三个源文件可以提炼出这套手册的编写约定供为该项目贡献文档时参考命名规则工具名.章节号.md编译产物为工具名.章节号首页头采用工具名(章节号) -- 一句话描述的格式例如zerotier-one(8) -- ZeroTier virtual network endpoint service标准分节均包含 SYNOPSIS用法概要、DESCRIPTION描述、COMMANDS 或 SWITCHES命令/开关、EXAMPLES示例、COPYRIGHT版权、SEE ALSO相关手册等节SEE ALSO 交叉引用三个手册互相引用zerotier-cli.1.md 指向zerotier-one(8)与zerotier-idtool(1)zerotier-idtool.1.md 指向zerotier-one(8)与zerotier-cli(1)zerotier-one.8.md 则反向引用前两者形成闭环。实际查看编译产物时可用man ./doc/zerotier-one.8一类的命令直接阅读生成的 roff 手册。七、常见问题与构建排障速查结合 doc/README.md 与 doc/build.sh 的逻辑整理出以下排障要点必须在 doc/ 子目录下运行脚本脚本会检查zerotier-cli.1.md是否存在在错误目录执行会直接提示两种工具链二选一即可README 明确二者“大致等价”。系统已装ronn时脚本优先走 ronn 分支检查/usr/bin/ronn与/usr/local/bin/ronn未安装则回退到 marked-man 分支此时要求系统具备 Node.js脚本依次探测node、nodejs的多个常见路径marked-man 自动安装首次构建且本地无marked-man时脚本自动执行npm install marked-man装到doc/node_modules/无需手工干预两者都缺则构建失败既无 ronn 也无 Node/npm 时脚本输出Unable to find ronn or node/npm -- cannot build man pages!并以退出码 1 结束重新构建前会清空旧产物脚本启动时rm -f *.1 *.2 *.8保证不残留过期手册。结语doc/README.md 虽短却浓缩了 ZeroTier 文档构建的完整设计一份 Markdown 源文件、两套等价工具链、一次自动化的探测与回退。通过本文的拆解可以看到构建脚本背后是 doc/build.sh 对ronn/marked-man的智能选择与 Node 路径的兼容处理而三大手册的内容又在 one.cpp 的main()/printHelp()、cli()、idtool()等实现以及 node/ 目录的密码学代码中得到逐一印证。无论你是想为项目补充文档、在无桌面环境批量部署 ZeroTier还是深入理解zerotier-one服务端的工作目录与认证体系这套“源文件 构建脚本 生成手册”的链路都是最直接的入口。【免费下载链接】ZeroTierOneA Smart Ethernet Switch for Earth项目地址: https://gitcode.com/GitHub_Trending/ze/ZeroTierOne创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
ZeroTier 手册页构建指南：从 Markdown 源文件到 roff/man 格式的完整工具链
ZeroTier 手册页构建指南从 Markdown 源文件到 roff/man 格式的完整工具链【免费下载链接】ZeroTierOneA Smart Ethernet Switch for Earth项目地址: https://gitcode.com/GitHub_Trending/ze/ZeroTierOne导读本文基于 ZeroTierOne 仓库中 doc/README.md 及其配套的构建脚本与手册页源文件完整讲解该项目的 Unix 手册页man pages生成流程如何使用ronn或 Node.js 的marked-man把 Markdown 编写的手册源文件编译为 roff/man 格式以及这套流程产出的zerotier-one(8)、zerotier-cli(1)、zerotier-idtool(1)三大手册各自覆盖的核心命令与配置项。读完本文你将掌握 ZeroTier 文档目录的组织方式、两种构建工具链的取舍与安装方法、构建脚本的逐行逻辑并能通过仓库源码验证手册中描述的开关参数、文件布局与认证机制的真实实现。一、doc 目录手册页的源文件与构建产物ZeroTier 的文档全部集中在仓库的 doc/ 目录下它既是手册页的“源码库”也是构建脚本的工作目录。目录内同时保存 Markdown 源文件与编译后的 roff/man 产物文件类型说明README.md说明文档介绍手册页构建方法本文主体build.sh构建脚本将三个.md源文件编译为.1/.8手册zerotier-one.8.md手册源文件服务端守护进程zerotier-one(8)的手册源zerotier-cli.1.md手册源文件命令行控制工具zerotier-cli(1)的手册源zerotier-idtool.1.md手册源文件身份管理工具zerotier-idtool(1)的手册源zerotier-one.8等构建产物编译后的 roff/man 格式手册可直接被man读取contactzerotier.com.gpg密钥文档签名用的公钥manpage_encoding_declaration.UTF-8辅助文件编码声明参考手册页的编号遵循 Unix 惯例1表示用户命令8表示系统管理命令守护进程。三个源文件彼此通过 “SEE ALSO” 交叉引用形成一套完整的命令行文档体系。二、构建流程核心./build.sh逐段解析doc/README.md 的核心指令只有一句话在doc/子目录下执行./build.sh即可构建全部手册页。但这一步背后脚本 doc/build.sh 实际上完成了一次完整的“工具链探测与回退”流程。下面逐段拆解2.1 运行前提检查脚本首先强制重置 PATH保证后续调用的ronn、node、npm均来自标准系统路径export PATH/bin:/usr/bin:/usr/local/bin:/sbin:/usr/sbin:/usr/local/sbin随后检查当前目录是否存在zerotier-cli.1.md不存在则报错并提示“必须在 ZeroTier 源码树的 doc/ 子目录下运行”if [ ! -f zerotier-cli.1.md ]; then echo This script must be run from the doc/ subfolder of the ZeroTier tree. fi接着清理上一次的构建产物rm -f *.1 *.2 *.8这一步保证每次构建都是干净的不会残留旧版本手册。2.2 工具链选择ronn 优先marked-man 兜底这是整个构建流程的“分叉点”if [ -e /usr/bin/ronn -o -e /usr/local/bin/ronn ]; then ronn -r zerotier-cli.1.md ronn -r zerotier-idtool.1.md ronn -r zerotier-one.8.md else # 走 marked-man 分支见 2.3 ... fi优先路径ronn。ronn是一个把 Markdown 编译为 roff/man 格式的 Ruby 程序在很多发行版上以软件包形式提供README 中列出的包名包括rubygem-ronn或ruby-ronn也可用gem install ronn安装。脚本通过检查/usr/bin/ronn与/usr/local/bin/ronn两个路径判断其是否可用可用时直接以-rroff 输出模式编译三个源文件。回退路径marked-man。doc/README.md 明确指出Node 的marked-man包与 RubyGems 的ronn是“大致等价”的两种 Markdown→roff 编译器脚本在 ronn 缺失时自动启用后者。2.3 marked-man 分支Node 探测与自动安装进入回退分支后脚本首先在多个常见路径间探测 Node 运行时NODE/usr/bin/node if [ ! -e $NODE ]; then if [ -e /usr/bin/nodejs ]; then NODE/usr/bin/nodejs elif [ -e /usr/local/bin/node ]; then NODE/usr/local/bin/node elif [ -e /usr/local/bin/nodejs ]; then NODE/usr/local/bin/nodejs else echo Unable to find ronn or node/npm -- cannot build man pages! exit 1 fi fi兼容了 Ubuntu/Debian 旧版将 Node 命名为nodejs的历史差异。Node 就绪后若本地尚未安装marked-man脚本会就地执行npm install marked-man将依赖装入doc/node_modules/if [ ! -f node_modules/marked-man/bin/marked-man ]; then echo Installing npm package marked-man -- MarkDown to ROFF converter... npm install marked-man fi最后分别调用 marked-man 完成三次编译$NODE node_modules/marked-man/bin/marked-man zerotier-cli.1.md zerotier-cli.1 $NODE node_modules/marked-man/bin/marked-man zerotier-idtool.1.md zerotier-idtool.1 $NODE node_modules/marked-man/bin/marked-man zerotier-one.8.md zerotier-one.82.4 与项目构建系统的集成这套脚本并非孤立存在它已被挂接到 ZeroTier 的顶层构建体系中。在 make-linux.mk 中可以看到cd doc ; ./build.sh的调用说明执行主构建时手册页会作为doc目标的一部分被自动生成类似地pkg/synology/README.md 与 pkg/synology/dsm7-docker/README.md 中的./build.sh build也走同一条手册页构建路径。README 中“Use ./build.sh to build the manual pages”的描述在仓库内可以找到完整的落地链路。三、构建产物之一zerotier-one(8) 服务端手册zerotier-one(8)是三大手册中的“系统管理”篇描述守护进程本身。它对应仓库入口 one.cpp 中的main()与printHelp()实现手册内容与源码高度一致。3.1 角色定位与运行方式zerotier-one负责把一台 UnixLinux/BSD/macOS系统接入一个或多个 ZeroTier 虚拟网络并把虚拟网络呈现为系统上的虚拟网口文档称其为 “peer to peer VPN client”。它通常由 systemdLinux或 launchdmacOS这类 init 系统托管而不是由用户直接启动。手册特别指出默认必须 root 运行除非使用-U开关且不打算真正加入网络典型场景只跑网络控制器微服务。3.2 工作目录home directory与平台差异服务状态存放在“工作目录”中未指定时按平台取默认值平台默认工作目录Linux/var/lib/zerotier-onemacOS/Library/Application Support/ZeroTier/OneFreeBSD 等 BSD/var/db/zerotier-one手册对工作目录给出了两条硬性约束必须持久化不能被系统清理守护进程自动清除也不能放在易失性存储中因为其中的identity.secret一旦丢失本机唯一的 10 位十六进制 ZeroTier 地址与密钥就随之丢失。此外同一台机器上可以运行多个zerotier-one实例前提是使用不同的主端口primary port与不同的工作目录但单实例本就可加入任意多个网络手册明确表示通常没必要这么做。3.3 控制 API 与认证机制服务通过127.0.0.1:主端口上的 JSON API 被控制默认主端口为 9993。访问该 API 需要授权令牌令牌通常存放于工作目录的authtoken.secret文件中某些平台在启用额外安全选项时非默认还会做 socket 对端 UID/GID 校验。这条机制在 one.cpp 的 CLI 实现中有直接印证程序先尝试从工作目录读取authtoken.secret读取失败时报错 “authtoken.secret not found or readable … (try again as root)”成功读取后把令牌放入X-ZT1-AuthHTTP 请求头再访问本地 API。可以看到手册描述与源码实现一一对应。3.4 首次启动的身份生成在全新工作目录中首次启动服务时会生成 ZeroTier 身份。由于地址生成内置了反 DDoS/反伪造的工作量证明proof of work函数慢速机器上这一过程可能耗时 10 秒以上该过程只发生一次结果保存为工作目录下的identity.secret它定义并“认领”了本机的 ZeroTier 地址及关联的 ECC-256 密钥对。源码中 one.cpp 甚至处理了极罕见的ONE_IDENTITY_COLLISION身份碰撞情况检测到身份冲突时把旧identity.secret另存为.saved_after_collision后重新生成可见身份文件在整个系统中的核心地位。3.5 完整开关列表zerotier-one支持的全部开关如下与 one.cpp 的printHelp()输出一致开关含义-h显示帮助-v显示版本-U跳过权限检查允许非特权用户运行典型场景仅作网络控制器-pport指定主端口默认 9993传 0 则每次随机选择-dfork 后以守护进程方式运行Unix 系-i进入zerotier-idtool人格行为等同于 zerotier-idtool(1)当二进制名或符号链接名为zerotier-idtool时自动生效-q进入zerotier-cli人格行为等同于 zerotier-cli(1)当二进制名或符号链接名为zerotier-cli时自动生效“人格”切换在源码 one.cpp 中有明确实现main()通过strstr(argv[0], zerotier-idtool)/strstr(argv[0], zerotier-cli)判断程序名后分别转入idtool()与cli()入口。也就是说ZeroTier 的三个工具实际上是同一个二进制按名字/开关分化出的三种行为这也是-i、-q开关存在的根本原因。3.6 工作目录文件布局FILES 章节手册详细列出了工作目录下的全部文件及其职责这是排查问题时的第一手资料文件/目录作用与注意事项identity.public身份的公开部分10 位十六进制地址 关联公钥identity.secret含私钥的完整身份。可复制此文件迁移 ZeroTier 地址必须备份私钥泄露意味着他人可冒充本设备并解密流量。对网络控制器而言该文件尤为敏感——它相当于控制器所辖网络这一证书颁发机构的私钥authtoken.secret本地 JSON API 的认证令牌不存在时启动时由安全随机源生成。使用时放入 HTTP 请求的X-ZT1-Auth头devicemap记录zt#接口号到 ZeroTier 网络的映射保证重启后接口编号稳定FreeBSD 等支持长接口名可直接编码网络 ID的系统上可能不存在此文件zerotier-one.pid服务的 PID正常关机时删除zerotier-one.port主端口号JSON API 即位于127.0.0.1:此端口启动时创建zerotier-cli读取它来定位控制 APIcontroller.db启用网络控制器构建时控制器的 SQLite3 数据库controller.db.backup控制器数据库的周期备份手册注明目前为“有变更时每 5 分钟”一次因不是正在使用的 SQLite 文件备份更安全新备份产生时旧文件被轮转而非原地覆写iddb.d/目录缓存过去 60 天内通信过的每个对端的公开身份删除会导致连接初始化变慢需要重新拉取对端完整身份但不会破坏功能networks.d目录缓存已加入网络的配置与证书信息。启动时 ZeroTier 会扫描其中的network ID.conf文件以恢复网络因此touch一个空的network ID.conf即可实现“不经 API 预配置加入某网络”空配置文件会触发从该网络控制器拉取完整配置networks.d的“空文件预配置”技巧尤其值得注意这是脱离 JSON API 的“免交互”入网方式在无 head 环境的批量部署中非常实用。四、构建产物之二zerotier-cli(1) 命令行控制工具zerotier-cli(1)是对本地 JSON API 的轻量封装适合脚本化与日常操作。4.1 权限与认证副本默认情况下zerotier-cli必须以 root 或sudo运行。若想让普通用户也能控制系统 ZeroTier 服务可以手工在工作目录之外创建一份认证令牌副本sudo cp /var/lib/zerotier-one/authtoken.secret /home/user/.zeroTierOneAuthToken chown user /home/user/.zeroTierOneAuthToken chmod 0600 /home/user/.zeroTierOneAuthToken手册同时给出两条重要提醒ZeroTier 服务主目录的位置因平台而异详见zerotier-one(8)授予该用户令牌等于赋予其“把系统接入/断开任意虚拟网络”的能力这是相当重的权限需谨慎评估。4.2 常用开关zerotier-cli的所有开关都可通过help输出查看其中两个最常用开关作用-j输出原始 JSON。比表格输出更易被脚本解析且包含表格中不存在的详细字段-Dpath指定替代的 ZeroTier 服务工作目录。当服务未运行在系统默认位置时用它指明zerotier-one.port与authtoken.secret的查找位置4.3 子命令一览子命令功能help显示帮助info显示本设备信息含 10 位 ZeroTier 地址与当前连接状态加-j获得更详细输出listpeers列出服务知道的 VL1虚拟层 1即对等网络对端即最近约 30 分钟内通信过的对端。注意这些并非虚拟网络上的全部设备还可能包含不在任何已加入网络中的设备通常是根服务器或网络控制器listnetworks列出本系统所属网络及信息例如被分配的 ZeroTier 托管 IP。手工配置在 ZeroTier 接口上的 IP 不会出现在这里需用系统标准网络接口命令查看join入网。只需join加 16 位十六进制网络 ID。随后用listnetworks查看状态要么收到控制器的证书及 IP 分配等信息要么收到access denied——此时需网络管理员在控制器上按设备 10 位 IDinfo可见完成授权leave退网断开连接并删除系统上的对应接口。对端可能因 30 分钟超时机制残留在listpeers中但既然不再共享网络已无法进行有意义的数据通信4.4 实战示例原手册原样保留加入 “Earth”——ZeroTier 的大规模公共测试网络$ sudo zerotier-cli join 8056c2e21c000001 $ sudo zerotier-cli listnetworks ( wait until you get an Earth IP ) $ ping earth.zerotier.net ( you should now be able to ping our Earth test IP )退出 “Earth”$ sudo zerotier-cli leave 8056c2e21c000001列出 VL1 对端$ sudo zerotier-cli listpeers在较新版本的源码中zerotier-cli还扩展出了bond子命令如 one.cpp 中zerotier-cli bond list、bond setmtu、bond peerId rotate等用于链路聚合bonding策略的管理说明该工具的 CLI 面仍在持续演进。五、构建产物之三zerotier-idtool(1) 身份管理工具zerotier-idtool用于创建与操作 ZeroTier 身份。手册开篇即给出身份的本质定义一个 ZeroTier 身份 一对公私钥或仅公开部分 一个由公钥经工作量证明哈希函数推导出的 10 位十六进制地址。5.1 参数约定凡命令参数要求公钥或完整含私钥身份时既可以用文件路径也可以直接在命令行内联身份字符串。5.2 子命令详解子命令语法说明help—显示帮助无参数运行同样显示帮助generategenerate [secret file] [public file] [vanity]生成新身份。指定 secret 文件则完整身份含私钥写入该文件指定 public 文件则公开部分写入均不指定时完整身份输出到 STDOUT。vanity为期望地址开头的十六进制前缀一般不用——因其工作量证明的内在成本生成带已知 16 位4 个十六进制字符前缀的身份在 2.8GHz Core i5 单核上平均需要约两小时validatevalidate identity本地校验身份的密钥与工作量证明函数是否对应只需公开部分getpublicgetpublic full identity从含私钥的完整身份中提取公开部分并输出到 STDOUTsignsign full identity file用 SHA512 ECC-256ed25519对文件内容签名签名以十六进制输出到 STDOUTverifyverify identity file signature用公钥校验sign产生的签名mkcommkcom full identity [id,value,maxdelta] [...]创建并签名网络成员证书。手册注明其“一般无用”——网络控制器会自动完成该工作此命令主要为测试目的保留5.3 实战示例原手册原样保留生成并打印一个新身份$ zerotier-idtool generate生成并同时写入身份的秘密与公开部分$ zerotier-idtool generate identity.secret identity.public生成一个地址以十六进制 “beef” 开头的虚荣地址会很慢$ zerotier-idtool generate beef.secret beef.public beef用身份私钥给文件签名$ zerotier-idtool sign identity.secret last_will_and_testament.txt用公钥校验文件签名$ zerotier-idtool verify identity.public last_will_and_testament.txtsign/verify的底层算法“SHA512 ECC-256ed25519”在仓库中有完整实现证据节点目录下同时存在 SHA512.cpp与 SHA512.hpp和 ECC.cpp与 ECC.hpp汇编优化的 ed25519 实现则位于 ext/ed25519-amd64-asm/含sign.c、open.c、keypair.c等可进一步深入阅读其密码学细节。六、手册页编写规范与交叉引用从三个源文件可以提炼出这套手册的编写约定供为该项目贡献文档时参考命名规则工具名.章节号.md编译产物为工具名.章节号首页头采用工具名(章节号) -- 一句话描述的格式例如zerotier-one(8) -- ZeroTier virtual network endpoint service标准分节均包含 SYNOPSIS用法概要、DESCRIPTION描述、COMMANDS 或 SWITCHES命令/开关、EXAMPLES示例、COPYRIGHT版权、SEE ALSO相关手册等节SEE ALSO 交叉引用三个手册互相引用zerotier-cli.1.md 指向zerotier-one(8)与zerotier-idtool(1)zerotier-idtool.1.md 指向zerotier-one(8)与zerotier-cli(1)zerotier-one.8.md 则反向引用前两者形成闭环。实际查看编译产物时可用man ./doc/zerotier-one.8一类的命令直接阅读生成的 roff 手册。七、常见问题与构建排障速查结合 doc/README.md 与 doc/build.sh 的逻辑整理出以下排障要点必须在 doc/ 子目录下运行脚本脚本会检查zerotier-cli.1.md是否存在在错误目录执行会直接提示两种工具链二选一即可README 明确二者“大致等价”。系统已装ronn时脚本优先走 ronn 分支检查/usr/bin/ronn与/usr/local/bin/ronn未安装则回退到 marked-man 分支此时要求系统具备 Node.js脚本依次探测node、nodejs的多个常见路径marked-man 自动安装首次构建且本地无marked-man时脚本自动执行npm install marked-man装到doc/node_modules/无需手工干预两者都缺则构建失败既无 ronn 也无 Node/npm 时脚本输出Unable to find ronn or node/npm -- cannot build man pages!并以退出码 1 结束重新构建前会清空旧产物脚本启动时rm -f *.1 *.2 *.8保证不残留过期手册。结语doc/README.md 虽短却浓缩了 ZeroTier 文档构建的完整设计一份 Markdown 源文件、两套等价工具链、一次自动化的探测与回退。通过本文的拆解可以看到构建脚本背后是 doc/build.sh 对ronn/marked-man的智能选择与 Node 路径的兼容处理而三大手册的内容又在 one.cpp 的main()/printHelp()、cli()、idtool()等实现以及 node/ 目录的密码学代码中得到逐一印证。无论你是想为项目补充文档、在无桌面环境批量部署 ZeroTier还是深入理解zerotier-one服务端的工作目录与认证体系这套“源文件 构建脚本 生成手册”的链路都是最直接的入口。【免费下载链接】ZeroTierOneA Smart Ethernet Switch for Earth项目地址: https://gitcode.com/GitHub_Trending/ze/ZeroTierOne创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
