ZeroTier One 网络虚拟化服务实战指南local.conf 配置详解与 JSON 管理 API 全解析【免费下载链接】ZeroTierOneA Smart Ethernet Switch for Earth项目地址: https://gitcode.com/GitHub_Trending/ze/ZeroTierOneZeroTier One 是 ZeroTier 虚拟网络的核心守护进程它负责把桌面、笔记本、服务器、虚拟机等设备接入 ZeroTier 虚拟网络。本文基于 service/README.md 展开系统讲解本地节点配置文件local.conf的全部可用设置项物理路径黑名单、可信路径、对端提示、端口与软件更新策略等并逐字段剖析内建 JSON 管理 API/status、/network、/peer等同时结合 OneService.cpp 等源码说明底层实现帮助读者掌握 ZeroTier One 的本地化配置与远程管理能力能够在大型部署中通过 Puppet、Chef、SaltStack 等工具统一下发配置。ZeroTier One 服务是什么ZeroTier One 是 ZeroTier 网络虚拟化服务的实际实现。正如 service/README.md 所述它是一个为桌面、笔记本、服务器、虚拟机等设备提供 ZeroTier 虚拟网络连接能力的服务。移动端iOS/Android拥有各自的原生实现Java 与 Objective-C它们只复用 ZeroTier 核心引擎而桌面与服务端设备使用的正是本仓库中的 OneService。从源码结构看OneService.hpp 定义了OneService抽象类它对外暴露如下核心能力newInstance(hp, port)创建服务实例传入 home 路径与端口0 表示随机端口端口会被写入 home 路径下的zerotier-one.port文件供 CLI 读取run()执行服务主 I/O 循环直到被终止getNetworkSettings()/setNetworkSettings()读写某个网络的本地设置allowManaged、allowGlobal、allowDefault、allowDNSterminate()从其他线程或信号处理器中终止服务。ReasonForTermination枚举则定义了四种退出原因ONE_STILL_RUNNING仍在运行、ONE_NORMAL_TERMINATION正常退出、ONE_UNRECOVERABLE_ERROR不可恢复错误、ONE_IDENTITY_COLLISION身份与其它节点冲突。本地配置文件 local.conf文件位置与加载机制ZeroTier One 的 home 目录中有一个名为local.conf的 JSON 文件用于存放适用于本节点的配置选项。该文件默认不存在需要你自行创建。它可以用来设置可信路径trusted path拉黑blacklist某些物理路径为特定节点配置物理路径提示path hints定义可信上游设备联合根节点 / federated roots。在大型部署中可以使用 Puppet、Chef、SaltStack 等工具统一下发该文件使所有系统保持一致的配置。文件必须使用合法的 JSON 格式——因为 ZeroTier One 自身也可能编辑并重写这个文件。若要校验配置合法性可以粘贴到 jsonlint.com 等在线工具或使用jq命令行工具。加载情况可通过zerotier-cli info -j的输出确认。从 OneService.cpp 可以看到加载逻辑服务启动时读取homePath /local.conf使用OSUtils::jsonParse解析若根元素不是 JSON 对象或解析失败会打印ERROR: unable to parse local.conf ...并直接exit(1)退出——因此格式错误会导致服务无法启动。同时该文件会被监控内容发生变化时会自动重新加载stat检查 mtime。全部可用设置项以下是local.conf支持的全部设置注意下方仅为便于阅读的示意图并非合法 JSONJSON 也不支持注释{ 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, /* 设置后覆盖默认随机副端口 */ tertiaryPort: 1-65535, /* 设置后覆盖默认随机第三端口 */ portMappingEnabled: true|false, /* 为 true默认时尝试用 uPnP 或 NAT-PMP 映射端口 */ allowSecondaryPort: true|false /* false 将同时禁用副端口 */ softwareUpdate: apply|download|disable, /* 自动应用更新 / 仅下载 / 禁用内建软件更新 */ softwareUpdateChannel: release|beta, /* 软件更新通道 */ softwareUpdateDist: true|false, /* 为 true 时对外分发软件更新仅对 ZeroTier, Inc. 自身有意义默认 false */ interfacePrefixBlacklist: [ XXX,... ], /* 接口名前缀如 eth 对应 eth#数组拉黑后不用于 ZT 流量 */ allowManagementFrom: [ NETWORK/bits, ...] |null, /* 非 NULL 时允许来自该 IP 网络的 JSON/HTTP 管理。默认仅 127.0.0.1 */ bind: [ ip,... ], /* 存在且非 null 时仅绑定到这些 IP 而不是每个接口允许通配 IP */ allowTcpFallbackRelay: true|false, /* 是否允许建立 TCP 中继连接默认 true */ enableMetrics: true|false /* 为 true 时启用 metrics.prom 中的指标采集 */ } }trustedPathId 详解可信路径trusted path是一条不需要加密与认证的物理网络。它带来性能提升但会牺牲 ZeroTier 在该路径上的全部安全特性。只有在清楚后果且确实需要性能时才应使用设置可信路径有两个硬性要求使用该路径的所有设备必须为同一网络定义相同的 trusted path ID可信路径 ID 是任意正整数非零。例如同一 LAN 内、IP 位于 10.0.0.0/24 的一组设备如果都为该网络定义相同的可信路径 ID 25就可以把它当作快速可信路径使用。从源码看trustedPathId与mtu会在 OneService.cpp 中被解析进ZT_PhysicalPathConfiguration再通过_node-setPhysicalPathConfiguration()写入内核路径管理Node.cpp 将其转发给Topology::setPhysicalPathConfiguration。当路径被标记为可信时Node.cpp 会把对应的trustedPathId填充进该路径数据面将跳过加解密处理。一个完整的 local.conf 示例{ physical: { 10.0.0.0/24: { blacklist: true }, 10.10.10.0/24: { trustedPathId: 101010024 }, }, virtual: { feedbeef12: { role: UPSTREAM, try: [ 10.10.20.1/9993 ], blacklist: [ 192.168.0.0/24 ] } }, settings: { softwareUpdate: apply, softwareUpdateChannel: release } }这个示例做了四件事将物理网段10.0.0.0/24全部拉黑任何 ZeroTier 流量都不会走该网段将10.10.10.0/24定义为可信路径ID 为101010024该网段内通信不再加密为节点feedbeef12提供到达提示10.10.20.1/9993并拒绝使用192.168.0.0/24物理路径全局开启自动应用更新并锁定 release 更新通道。各设置项的源码实现细节OneService.cpp 展示了settings各字段的实际解析逻辑可补充以下细节allowTcpFallbackRelay默认true且当链路聚合bonding生效时会被强制关闭 !_node-bondController()-inUse()因为 bonding 策略与 TCP 中继互斥primaryPort解析后做 0xffff截断取值必须落在 1–65535若为 0 则随机选择源码中在 20000–65500 区间随机尝试绑定最多 256 次试探secondaryPort/tertiaryPort默认随机allowSecondaryPort: false会同时禁用副端口副端口与第三端口往往配合 uPnP/NAT-PMP 映射对应portMappingEnabled默认 true通过 ext/miniupnpc 与 ext/libnatpmp 实现interfacePrefixBlacklist的每个前缀会与网卡名匹配命中即不参与 ZT 流量收发OneService.cppallowManagementFrom控制管理面来源 IP结合 HTTP 控制面的authCheck逻辑OneService.cpp非 loopback 来源必须命中该白名单才可能通过鉴权enableMetrics: true会开启metrics.prom指标采集对应/metricsHTTP 端点另有一些 README 未列出的扩展项controllerDbPath控制器数据库路径、ssoRedirectURL、以及 Central Controller 模式下的controller、redis、otelOpenTelemetry 导出端点与采样率等配置具体可参考 OneService.cpp。网络虚拟化服务 JSON API通用约定ZeroTier One 内建的控制面基于 cpp-httplibext/cpp-httplib/httplib.h在 OneService.cpp 中注册路由。JSON API 支持GET、POST/PUT、DELETE其中PUT 是 POST 的同义词其它方法包括 HEAD不被支持。POST 的 JSON 值具有极强的类型敏感性字段必须严格匹配规定类型否则会被忽略或报错。要点包括任何带引号的都是字符串因此布尔值和整数不能加引号布尔值只能是true或false整数不能带小数点带小数点即浮点数JSON 对象中未识别的字段也会被忽略。如果发现某个设置被忽略、被设成奇怪的值或收到错误请先对照下表中的类型逐一检查提交的字段类型。所有 API 请求都必须通过认证令牌authentication token。ZeroTier One 会把令牌保存在工作目录下的authtoken.secret文件中创建逻辑见 OneService.cpp若无法写入会直接报告致命错误。令牌可通过两种方式提供URL 参数?auth...HTTP 请求头X-ZT1-Auth静态 UI 页面是唯一无需认证即可访问的内容。此外可通过jsonpURL 参数请求 JSONP 封装响应会以脚本形式返回JSON 载荷包裹在参数指定的函数名调用中。从源码看认证还额外支持Authorization: Bearer token头且/health、/sso属于免认证端点OneService.cpp。/status —— 获取节点运行状态用途获取运行中节点的状态与寻址信息方法GET返回{ object }字段类型描述可写addressstring本节点的 10 位十六进制 ZeroTier 地址否publicIdentitystring本节点的 ZeroTier identity.public否worldIdintegerZeroTier world ID除测试外不变否worldTimestampinteger最近一次 world 定义的时间戳否onlineboolean为 true 表示至少一个上游对端可达否tcpFallbackActiveboolean为 true 表示正在使用慢速 TCP 回退中继否relayPolicystring中继策略ALWAYS、TRUSTED 或 NEVER否versionMajorinteger主版本号否versionMinorinteger次版本号否versionRevinteger修订号否versionstringmajor.minor.revision否clockinteger节点当前系统时钟自 epoch 起的毫秒数否源码实现位于 OneService.cpp通过_node-status(status)取得ZT_NodeStatus其中address以%.10llx格式化为 10 位十六进制字符串tcpFallbackActive依据_tcpFallbackTunnel是否建立来判断。/network —— 网络成员列表用途获取所有网络成员关系方法GET返回[ {object}, ... ]GET /network返回本节点已加入的所有网络数组数组元素即下方网络对象格式。对应实现为networkListGetOneService.cpp。/network/network ID —— 加入 / 离开网络用途获取、加入或离开一个网络方法GET、POST、DELETE返回{ object }加入网络POST 到该地址即可。由于网络没有必填可写参数POST 数据可选、可以省略。例如POST /network/8056c2e21c000001加入公网 Earth 网络。源码中networkPost调用_node-join(wantnw, ...)后解析请求体中的allowManaged、allowGlobal、allowDefault、allowDNS四个布尔字段OneService.cpp。注意 FreeBSD 上allowDefault不可用返回 400见 issue #580 相关注释。离开网络DELETE 该地址例如DELETE /network/8056c2e21c000001对应networkDelete调用_node-leave()。大多数网络设置不可写因为它们由网络控制器controller定义。可写字段仅限下表带 yes 的四个本地策略项。字段类型描述可写idstring16 位十六进制网络 ID否nwidstring16 位十六进制网络 ID遗留字段否macstring该网络虚拟网卡的 MAC 地址否namestring网络短名称来自控制器否statusstring网络状态OK、ACCESS_DENIED 等否typestring网络类型PUBLIC 或 PRIVATE否mtuinteger以太网 MTU否dhcpboolean为 true 表示应使用 DHCP 获取 IP 信息否bridgeboolean为 true 表示该设备可以桥接其它设备否broadcastEnabledboolean为 true 时 ff:ff:ff:ff:ff:ff 广播可用否portErrorinteger底层 tap 驱动返回的错误码否netconfRevisioninteger网络配置修订 ID否assignedAddresses[string]ZeroTier 分配的 IP 地址数组含 /bits否routes[object]ZeroTier 分配的路由数组见下否portDeviceNamestring虚拟网络设备名若有否allowManagedboolean是否允许 IP 与路由管理是allowGlobalboolean是否允许与全局 IP 重叠的 IP 与路由是allowDefaultboolean是否允许覆盖系统默认路由是allowDNSboolean是否允许在网络上配置 DNS是Route 对象字段类型描述可写targetstring目标网络 / 掩码位数否viastring网关 IP下一跳LAN 内为 null否flagsinteger标志位当前恒为 0否metricinteger路由度量当前未使用否这四个可写字段与 OneService.hpp 中NetworkSettings结构体一一对应还额外包含一个源码级allowManagedWhitelist白名单字段README 未提及。这些设置会被持久化为networks.d/16位网络ID.local.conf与networks.d/16位网络ID.conf格式见 OneService.cpp。/peer —— 对端列表用途获取所有对端方法GET返回[ {object}, ... ]GET /peer返回当前所有对端的 peer 对象数组实现见peerListGetOneService.cpp其中 bonded 对端会附带链路聚合信息。/peer/address —— 查询 / 设置对端用途获取或设置某个对端的信息方法GET、POST返回{ object }字段类型描述可写addressstring对端的 10 位十六进制 ZeroTier 地址否versionMajorinteger对端主版本若已知否versionMinorinteger对端次版本若已知否versionRevinteger对端修订号若已知否versionstringmajor.minor.revision否latencyinteger若已知则为毫秒级延迟否rolestringLEAF、UPSTREAM、ROOT 或 PLANET否paths[object]当前活跃的物理路径见下否Path 对象字段类型描述可写addressstring物理套接字地址如 IP/port否lastSendinteger最后通过该路径发送的时间否lastReceiveinteger最后通过该路径接收的时间否activeboolean该路径是否使用中否expiredboolean该路径是否已过期否preferredboolean是否为当前优选路径否trustedPathIdinteger非零表示该路径为可信路径未加密否trustedPathId字段再次印证了前文可信路径机制当某条物理路径被标记为可信时它会以非零 ID 出现在 peer 的路径列表中表示该路径上的流量不经过加解密。其它控制面端点源码中除 README 记载的端点外还注册了以下控制面路由OneService.cpp可作为运维排查的补充/configGET与/config/settingsPOST/PUT读取与修改节点配置/healthGET健康检查免认证/moon与/moon/10位地址列出 / 创建 / 删除 moon自定义根节点/bond/show/10位地址、/bond/rotate/10位地址、/bond/setmtu/...链路聚合bonding的查看、强制轮换链路与设置 MTU/metrics指标采集端点支持独立的metrics令牌鉴权需enableMetrics: true。这些端点与zerotier-clizerotier-cli.1.md的交互行为一一对应CLI 本质上是该 JSON API 的命令行封装。实际操作示例以下操作默认服务运行在默认端口 9993home 目录为平台默认路径Linux 为/var/lib/zerotier-onemacOS 为/Library/Application Support/ZeroTier/OneWindows 为C:\ProgramData\ZeroTier\One见 OSUtils.cpp。1. 查看节点状态# 方式一CLI自动读取 authtoken.secret zerotier-cli info -j # 方式二直接调用 JSON API curl -H X-ZT1-Auth: $(cat /var/lib/zerotier-one/authtoken.secret) \ http://127.0.0.1:9993/status2. 加入 / 离开一个网络# 加入公网 Earth 网络 curl -X POST -H X-ZT1-Auth: $(cat /var/lib/zerotier-one/authtoken.secret) \ http://127.0.0.1:9993/network/8056c2e21c000001 # 离开该网络 curl -X DELETE -H X-ZT1-Auth: $(cat /var/lib/zerotier-one/authtoken.secret) \ http://127.0.0.1:9993/network/8056c2e21c0000013. 查看对端与路径curl -H X-ZT1-Auth: $(cat /var/lib/zerotier-one/authtoken.secret) \ http://127.0.0.1:9993/peer | jq4. 校验 local.confjq . /var/lib/zerotier-one/local.conf # 解析失败即格式非法 zerotier-cli info -j # 确认配置已生效总结与注意事项local.conf是节点级配置的唯一入口格式必须合法JSON 解析失败会导致服务直接退出修改后会自动热加载大规模部署时建议用配置管理工具统一下发trustedPathId是性能与安全的权衡点可信路径跳过加密与认证仅在同一网络的所有设备使用相同 ID 时才生效务必谨慎使用JSON API 类型敏感布尔与整数必须严格按类型提交所有写操作需携带authtoken.secret中的令牌可写网络参数仅有allowManaged、allowGlobal、allowDefault、allowDNS四个本地策略其余网络属性由控制器决定若需深入了解实现细节可继续阅读 OneService.cpp、OneService.hpp 与 Node.cpp 中setPhysicalPathConfiguration相关的路径管理逻辑。【免费下载链接】ZeroTierOneA Smart Ethernet Switch for Earth项目地址: https://gitcode.com/GitHub_Trending/ze/ZeroTierOne创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 ZeroTier One 网络虚拟化服务实战指南：local.conf 配置详解与 JSON 管理 API 全解析
ZeroTier One 网络虚拟化服务实战指南local.conf 配置详解与 JSON 管理 API 全解析【免费下载链接】ZeroTierOneA Smart Ethernet Switch for Earth项目地址: https://gitcode.com/GitHub_Trending/ze/ZeroTierOneZeroTier One 是 ZeroTier 虚拟网络的核心守护进程它负责把桌面、笔记本、服务器、虚拟机等设备接入 ZeroTier 虚拟网络。本文基于 service/README.md 展开系统讲解本地节点配置文件local.conf的全部可用设置项物理路径黑名单、可信路径、对端提示、端口与软件更新策略等并逐字段剖析内建 JSON 管理 API/status、/network、/peer等同时结合 OneService.cpp 等源码说明底层实现帮助读者掌握 ZeroTier One 的本地化配置与远程管理能力能够在大型部署中通过 Puppet、Chef、SaltStack 等工具统一下发配置。ZeroTier One 服务是什么ZeroTier One 是 ZeroTier 网络虚拟化服务的实际实现。正如 service/README.md 所述它是一个为桌面、笔记本、服务器、虚拟机等设备提供 ZeroTier 虚拟网络连接能力的服务。移动端iOS/Android拥有各自的原生实现Java 与 Objective-C它们只复用 ZeroTier 核心引擎而桌面与服务端设备使用的正是本仓库中的 OneService。从源码结构看OneService.hpp 定义了OneService抽象类它对外暴露如下核心能力newInstance(hp, port)创建服务实例传入 home 路径与端口0 表示随机端口端口会被写入 home 路径下的zerotier-one.port文件供 CLI 读取run()执行服务主 I/O 循环直到被终止getNetworkSettings()/setNetworkSettings()读写某个网络的本地设置allowManaged、allowGlobal、allowDefault、allowDNSterminate()从其他线程或信号处理器中终止服务。ReasonForTermination枚举则定义了四种退出原因ONE_STILL_RUNNING仍在运行、ONE_NORMAL_TERMINATION正常退出、ONE_UNRECOVERABLE_ERROR不可恢复错误、ONE_IDENTITY_COLLISION身份与其它节点冲突。本地配置文件 local.conf文件位置与加载机制ZeroTier One 的 home 目录中有一个名为local.conf的 JSON 文件用于存放适用于本节点的配置选项。该文件默认不存在需要你自行创建。它可以用来设置可信路径trusted path拉黑blacklist某些物理路径为特定节点配置物理路径提示path hints定义可信上游设备联合根节点 / federated roots。在大型部署中可以使用 Puppet、Chef、SaltStack 等工具统一下发该文件使所有系统保持一致的配置。文件必须使用合法的 JSON 格式——因为 ZeroTier One 自身也可能编辑并重写这个文件。若要校验配置合法性可以粘贴到 jsonlint.com 等在线工具或使用jq命令行工具。加载情况可通过zerotier-cli info -j的输出确认。从 OneService.cpp 可以看到加载逻辑服务启动时读取homePath /local.conf使用OSUtils::jsonParse解析若根元素不是 JSON 对象或解析失败会打印ERROR: unable to parse local.conf ...并直接exit(1)退出——因此格式错误会导致服务无法启动。同时该文件会被监控内容发生变化时会自动重新加载stat检查 mtime。全部可用设置项以下是local.conf支持的全部设置注意下方仅为便于阅读的示意图并非合法 JSONJSON 也不支持注释{ 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, /* 设置后覆盖默认随机副端口 */ tertiaryPort: 1-65535, /* 设置后覆盖默认随机第三端口 */ portMappingEnabled: true|false, /* 为 true默认时尝试用 uPnP 或 NAT-PMP 映射端口 */ allowSecondaryPort: true|false /* false 将同时禁用副端口 */ softwareUpdate: apply|download|disable, /* 自动应用更新 / 仅下载 / 禁用内建软件更新 */ softwareUpdateChannel: release|beta, /* 软件更新通道 */ softwareUpdateDist: true|false, /* 为 true 时对外分发软件更新仅对 ZeroTier, Inc. 自身有意义默认 false */ interfacePrefixBlacklist: [ XXX,... ], /* 接口名前缀如 eth 对应 eth#数组拉黑后不用于 ZT 流量 */ allowManagementFrom: [ NETWORK/bits, ...] |null, /* 非 NULL 时允许来自该 IP 网络的 JSON/HTTP 管理。默认仅 127.0.0.1 */ bind: [ ip,... ], /* 存在且非 null 时仅绑定到这些 IP 而不是每个接口允许通配 IP */ allowTcpFallbackRelay: true|false, /* 是否允许建立 TCP 中继连接默认 true */ enableMetrics: true|false /* 为 true 时启用 metrics.prom 中的指标采集 */ } }trustedPathId 详解可信路径trusted path是一条不需要加密与认证的物理网络。它带来性能提升但会牺牲 ZeroTier 在该路径上的全部安全特性。只有在清楚后果且确实需要性能时才应使用设置可信路径有两个硬性要求使用该路径的所有设备必须为同一网络定义相同的 trusted path ID可信路径 ID 是任意正整数非零。例如同一 LAN 内、IP 位于 10.0.0.0/24 的一组设备如果都为该网络定义相同的可信路径 ID 25就可以把它当作快速可信路径使用。从源码看trustedPathId与mtu会在 OneService.cpp 中被解析进ZT_PhysicalPathConfiguration再通过_node-setPhysicalPathConfiguration()写入内核路径管理Node.cpp 将其转发给Topology::setPhysicalPathConfiguration。当路径被标记为可信时Node.cpp 会把对应的trustedPathId填充进该路径数据面将跳过加解密处理。一个完整的 local.conf 示例{ physical: { 10.0.0.0/24: { blacklist: true }, 10.10.10.0/24: { trustedPathId: 101010024 }, }, virtual: { feedbeef12: { role: UPSTREAM, try: [ 10.10.20.1/9993 ], blacklist: [ 192.168.0.0/24 ] } }, settings: { softwareUpdate: apply, softwareUpdateChannel: release } }这个示例做了四件事将物理网段10.0.0.0/24全部拉黑任何 ZeroTier 流量都不会走该网段将10.10.10.0/24定义为可信路径ID 为101010024该网段内通信不再加密为节点feedbeef12提供到达提示10.10.20.1/9993并拒绝使用192.168.0.0/24物理路径全局开启自动应用更新并锁定 release 更新通道。各设置项的源码实现细节OneService.cpp 展示了settings各字段的实际解析逻辑可补充以下细节allowTcpFallbackRelay默认true且当链路聚合bonding生效时会被强制关闭 !_node-bondController()-inUse()因为 bonding 策略与 TCP 中继互斥primaryPort解析后做 0xffff截断取值必须落在 1–65535若为 0 则随机选择源码中在 20000–65500 区间随机尝试绑定最多 256 次试探secondaryPort/tertiaryPort默认随机allowSecondaryPort: false会同时禁用副端口副端口与第三端口往往配合 uPnP/NAT-PMP 映射对应portMappingEnabled默认 true通过 ext/miniupnpc 与 ext/libnatpmp 实现interfacePrefixBlacklist的每个前缀会与网卡名匹配命中即不参与 ZT 流量收发OneService.cppallowManagementFrom控制管理面来源 IP结合 HTTP 控制面的authCheck逻辑OneService.cpp非 loopback 来源必须命中该白名单才可能通过鉴权enableMetrics: true会开启metrics.prom指标采集对应/metricsHTTP 端点另有一些 README 未列出的扩展项controllerDbPath控制器数据库路径、ssoRedirectURL、以及 Central Controller 模式下的controller、redis、otelOpenTelemetry 导出端点与采样率等配置具体可参考 OneService.cpp。网络虚拟化服务 JSON API通用约定ZeroTier One 内建的控制面基于 cpp-httplibext/cpp-httplib/httplib.h在 OneService.cpp 中注册路由。JSON API 支持GET、POST/PUT、DELETE其中PUT 是 POST 的同义词其它方法包括 HEAD不被支持。POST 的 JSON 值具有极强的类型敏感性字段必须严格匹配规定类型否则会被忽略或报错。要点包括任何带引号的都是字符串因此布尔值和整数不能加引号布尔值只能是true或false整数不能带小数点带小数点即浮点数JSON 对象中未识别的字段也会被忽略。如果发现某个设置被忽略、被设成奇怪的值或收到错误请先对照下表中的类型逐一检查提交的字段类型。所有 API 请求都必须通过认证令牌authentication token。ZeroTier One 会把令牌保存在工作目录下的authtoken.secret文件中创建逻辑见 OneService.cpp若无法写入会直接报告致命错误。令牌可通过两种方式提供URL 参数?auth...HTTP 请求头X-ZT1-Auth静态 UI 页面是唯一无需认证即可访问的内容。此外可通过jsonpURL 参数请求 JSONP 封装响应会以脚本形式返回JSON 载荷包裹在参数指定的函数名调用中。从源码看认证还额外支持Authorization: Bearer token头且/health、/sso属于免认证端点OneService.cpp。/status —— 获取节点运行状态用途获取运行中节点的状态与寻址信息方法GET返回{ object }字段类型描述可写addressstring本节点的 10 位十六进制 ZeroTier 地址否publicIdentitystring本节点的 ZeroTier identity.public否worldIdintegerZeroTier world ID除测试外不变否worldTimestampinteger最近一次 world 定义的时间戳否onlineboolean为 true 表示至少一个上游对端可达否tcpFallbackActiveboolean为 true 表示正在使用慢速 TCP 回退中继否relayPolicystring中继策略ALWAYS、TRUSTED 或 NEVER否versionMajorinteger主版本号否versionMinorinteger次版本号否versionRevinteger修订号否versionstringmajor.minor.revision否clockinteger节点当前系统时钟自 epoch 起的毫秒数否源码实现位于 OneService.cpp通过_node-status(status)取得ZT_NodeStatus其中address以%.10llx格式化为 10 位十六进制字符串tcpFallbackActive依据_tcpFallbackTunnel是否建立来判断。/network —— 网络成员列表用途获取所有网络成员关系方法GET返回[ {object}, ... ]GET /network返回本节点已加入的所有网络数组数组元素即下方网络对象格式。对应实现为networkListGetOneService.cpp。/network/network ID —— 加入 / 离开网络用途获取、加入或离开一个网络方法GET、POST、DELETE返回{ object }加入网络POST 到该地址即可。由于网络没有必填可写参数POST 数据可选、可以省略。例如POST /network/8056c2e21c000001加入公网 Earth 网络。源码中networkPost调用_node-join(wantnw, ...)后解析请求体中的allowManaged、allowGlobal、allowDefault、allowDNS四个布尔字段OneService.cpp。注意 FreeBSD 上allowDefault不可用返回 400见 issue #580 相关注释。离开网络DELETE 该地址例如DELETE /network/8056c2e21c000001对应networkDelete调用_node-leave()。大多数网络设置不可写因为它们由网络控制器controller定义。可写字段仅限下表带 yes 的四个本地策略项。字段类型描述可写idstring16 位十六进制网络 ID否nwidstring16 位十六进制网络 ID遗留字段否macstring该网络虚拟网卡的 MAC 地址否namestring网络短名称来自控制器否statusstring网络状态OK、ACCESS_DENIED 等否typestring网络类型PUBLIC 或 PRIVATE否mtuinteger以太网 MTU否dhcpboolean为 true 表示应使用 DHCP 获取 IP 信息否bridgeboolean为 true 表示该设备可以桥接其它设备否broadcastEnabledboolean为 true 时 ff:ff:ff:ff:ff:ff 广播可用否portErrorinteger底层 tap 驱动返回的错误码否netconfRevisioninteger网络配置修订 ID否assignedAddresses[string]ZeroTier 分配的 IP 地址数组含 /bits否routes[object]ZeroTier 分配的路由数组见下否portDeviceNamestring虚拟网络设备名若有否allowManagedboolean是否允许 IP 与路由管理是allowGlobalboolean是否允许与全局 IP 重叠的 IP 与路由是allowDefaultboolean是否允许覆盖系统默认路由是allowDNSboolean是否允许在网络上配置 DNS是Route 对象字段类型描述可写targetstring目标网络 / 掩码位数否viastring网关 IP下一跳LAN 内为 null否flagsinteger标志位当前恒为 0否metricinteger路由度量当前未使用否这四个可写字段与 OneService.hpp 中NetworkSettings结构体一一对应还额外包含一个源码级allowManagedWhitelist白名单字段README 未提及。这些设置会被持久化为networks.d/16位网络ID.local.conf与networks.d/16位网络ID.conf格式见 OneService.cpp。/peer —— 对端列表用途获取所有对端方法GET返回[ {object}, ... ]GET /peer返回当前所有对端的 peer 对象数组实现见peerListGetOneService.cpp其中 bonded 对端会附带链路聚合信息。/peer/address —— 查询 / 设置对端用途获取或设置某个对端的信息方法GET、POST返回{ object }字段类型描述可写addressstring对端的 10 位十六进制 ZeroTier 地址否versionMajorinteger对端主版本若已知否versionMinorinteger对端次版本若已知否versionRevinteger对端修订号若已知否versionstringmajor.minor.revision否latencyinteger若已知则为毫秒级延迟否rolestringLEAF、UPSTREAM、ROOT 或 PLANET否paths[object]当前活跃的物理路径见下否Path 对象字段类型描述可写addressstring物理套接字地址如 IP/port否lastSendinteger最后通过该路径发送的时间否lastReceiveinteger最后通过该路径接收的时间否activeboolean该路径是否使用中否expiredboolean该路径是否已过期否preferredboolean是否为当前优选路径否trustedPathIdinteger非零表示该路径为可信路径未加密否trustedPathId字段再次印证了前文可信路径机制当某条物理路径被标记为可信时它会以非零 ID 出现在 peer 的路径列表中表示该路径上的流量不经过加解密。其它控制面端点源码中除 README 记载的端点外还注册了以下控制面路由OneService.cpp可作为运维排查的补充/configGET与/config/settingsPOST/PUT读取与修改节点配置/healthGET健康检查免认证/moon与/moon/10位地址列出 / 创建 / 删除 moon自定义根节点/bond/show/10位地址、/bond/rotate/10位地址、/bond/setmtu/...链路聚合bonding的查看、强制轮换链路与设置 MTU/metrics指标采集端点支持独立的metrics令牌鉴权需enableMetrics: true。这些端点与zerotier-clizerotier-cli.1.md的交互行为一一对应CLI 本质上是该 JSON API 的命令行封装。实际操作示例以下操作默认服务运行在默认端口 9993home 目录为平台默认路径Linux 为/var/lib/zerotier-onemacOS 为/Library/Application Support/ZeroTier/OneWindows 为C:\ProgramData\ZeroTier\One见 OSUtils.cpp。1. 查看节点状态# 方式一CLI自动读取 authtoken.secret zerotier-cli info -j # 方式二直接调用 JSON API curl -H X-ZT1-Auth: $(cat /var/lib/zerotier-one/authtoken.secret) \ http://127.0.0.1:9993/status2. 加入 / 离开一个网络# 加入公网 Earth 网络 curl -X POST -H X-ZT1-Auth: $(cat /var/lib/zerotier-one/authtoken.secret) \ http://127.0.0.1:9993/network/8056c2e21c000001 # 离开该网络 curl -X DELETE -H X-ZT1-Auth: $(cat /var/lib/zerotier-one/authtoken.secret) \ http://127.0.0.1:9993/network/8056c2e21c0000013. 查看对端与路径curl -H X-ZT1-Auth: $(cat /var/lib/zerotier-one/authtoken.secret) \ http://127.0.0.1:9993/peer | jq4. 校验 local.confjq . /var/lib/zerotier-one/local.conf # 解析失败即格式非法 zerotier-cli info -j # 确认配置已生效总结与注意事项local.conf是节点级配置的唯一入口格式必须合法JSON 解析失败会导致服务直接退出修改后会自动热加载大规模部署时建议用配置管理工具统一下发trustedPathId是性能与安全的权衡点可信路径跳过加密与认证仅在同一网络的所有设备使用相同 ID 时才生效务必谨慎使用JSON API 类型敏感布尔与整数必须严格按类型提交所有写操作需携带authtoken.secret中的令牌可写网络参数仅有allowManaged、allowGlobal、allowDefault、allowDNS四个本地策略其余网络属性由控制器决定若需深入了解实现细节可继续阅读 OneService.cpp、OneService.hpp 与 Node.cpp 中setPhysicalPathConfiguration相关的路径管理逻辑。【免费下载链接】ZeroTierOneA Smart Ethernet Switch for Earth项目地址: https://gitcode.com/GitHub_Trending/ze/ZeroTierOne创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考