ZeroTierOne 全局虚拟局域网实战指南VL1/VL2 架构、构建配置与 JSON 控制 API 全解析【免费下载链接】ZeroTierOneA Smart Ethernet Switch for Earth项目地址: https://gitcode.com/GitHub_Trending/ze/ZeroTierOne本指南围绕 README.md 展开系统讲解 ZeroTier 的核心理念——一台面向地球的智能可编程以太网交换机如何通过 VL1 加密点对点网络与 VL2 以太网模拟层让分布在全球的设备像处于同一数据中心一样互联。读完本文你将掌握 ZeroTier 的架构原理、各平台构建方法、local.conf完整配置、zerotier-cli常用命令以及本地 JSON 控制 API 的字段细节。项目定位一台覆盖地球的智能以太网交换机README 开篇给出了 ZeroTier 最精炼的定义A smart programmable Ethernet switch for planet Earth。它的目标是让所有联网设备服务器、虚拟机、容器、应用程序能够彼此通信仿佛它们全部位于同一个物理数据中心或云区域中。这一目标由两层协议栈协作完成VL1Virtual Layer 1基于密码学寻址的、安全的点对点网络层。它负责节点之间的加密传输、身份认证与路径发现是所有通信的地基。VL2Virtual Layer 2以太网模拟层类似于 VXLAN 的思路在 VL1 之上虚拟出以太网。VL2 层内置了企业级 SDN 能力例如用于网络微隔离micro-segmentation和安全监控的细粒度访问控制规则即规则编译器rule-compiler/所生成的能力/标签规则。从源码角度看这套架构的核心实现位于 node/README.md 所描述的网络虚拟化核心Network Hypervisor Core一个完全与操作系统无关的全局虚拟以太网交换引擎。node/目录内不含任何真实的 I/O、端口配置等 OS 相关代码只接收线缆报文、输出以太网报文反之亦然对外通过 include/ZeroTierOne.h 暴露一个简单的 C API。该目录下的核心类如Network.cpp、Peer.cpp、Switch.cpp、Topology.cpp完整实现了 VL1 的寻址/路由与 VL2 的以太网模拟例如 node/Network.hpp 中即把 VL2 上的发送流程定义为无副作用的第一步操作。安全模型方面README 明确了两点事实所有 ZeroTier 流量都使用仅由你控制的密钥进行端到端加密大部分流量走点对点直连路径对于无法建立 P2P 连接的用户官方提供免费但较慢的中继relay服务。构建与平台要求构建细节记录在 build.md 中它是 README 指向的核心构建文档涵盖各平台的要求平台工具链要求构建命令macOSXcode 命令行工具macOS 10.13若启用 SSO 需 Rustx86_64/ARM64makeLinuxGCC/G 8.x 或 CLANG/CLANG 5.xmakefile 自动优先选择 clang可传CC/CXX覆盖若启用 SSO 需 RustmakeWindowsVisual Studio 2022Windows 10打开windows/下的解决方案FreeBSDGNU makegmakebinutilspkg install binutilsgmakeOpenBSDGNU make注意仅 4 个 tap 设备/dev/tap0~/dev/tap3网络成员数上限为 4gmakeCMake 是官方提供的一条可选构建路径官方发布版仍由平台 makefile 与windows/解决方案产出。使用 CMake 前需先执行一次 scripts/bootstrap-deps.sh默认快速模式仅拉取 header-only 的 OpenTelemetry API 到./.deps不要设置ZT_CONTROLLER_DEPS1。CMake 3.15 可用预设cmake --list-presets # 查看当前 OS 可用预设 cmake --preset linux-release # 默认守护进程含 nonfree 内置控制器 cmake --build --preset linux-release cmake --preset linux-free-release # 纯自由版ZT_NONFREEOFF不编译 nonfree/ cmake --build --preset linux-free-releaseFree 与默认non-free构建的区别默认守护进程会内置nonfree/下的 FileDB 网络控制器即官方构建的ZT_NONFREEON行为若设置-DZT_NONFREEOFF或使用*-free-*预设则仅编译链接 MPL-2.0 的node/、osdep/、service/代码得到无控制器功能的纯自由守护进程。每个预设输出到独立目录build-presetName/二进制位于build-presetName/zerotier-one。不借助预设的手动等价命令cmake -DCMAKE_PREFIX_PATH$PWD/.deps -S . -B build cmake --build build -j8 # 纯自由版 cmake -DZT_NONFREEOFF -DCMAKE_PREFIX_PATH$PWD/.deps -S . -B build cmake --build build -j8构建后建议运行make selftest它会编译zerotier-selftest二进制对内部各模块做单元测试并报告构建环境信息在新平台或新架构上首推执行。运行服务与常用 CLI 操作zerotier-one的完整用法见 doc/zerotier-one.8.md。构建完成后Linux/BSD 上以守护进程方式启动sudo ./zerotier-one -d常用启动开关开关作用-h显示帮助-v显示版本-U跳过特权检查允许非 root 运行通常用于仅作为网络控制器、不加入网络的场景-pport指定主端口默认 9993为 0 时每次随机选择-d后台守护进程化运行-i/-q切换为zerotier-idtool/zerotier-cli人格二进制名或符号链接名匹配时自动生效工作目录Home Folder按平台存放于Linux/var/lib/zerotier-oneFreeBSD/OpenBSD/var/db/zerotier-oneMac/Library/Application Support/ZeroTier/OneWindows\ProgramData\ZeroTier\One工作目录必须持久保存其中identity.secret一旦丢失本机唯一的 10 位十六进制 ZeroTier 地址及其 ECC-256 密钥对即告丢失。首次启动时服务会执行反 DDoS/反伪造的工作量证明来生成身份在慢速系统上可能耗时 10 秒以上且仅此一次。加入/退出网络使用zerotier-cli详见 doc/zerotier-cli.1.md# 加入 ZeroTier 官方公共测试网络 Earth sudo zerotier-cli join 8056c2e21c000001 sudo zerotier-cli listnetworks # 等待分配 Earth 内网 IP ping earth.zerotier.net # 退出网络 sudo zerotier-cli leave 8056c2e21c000001 # 查看 VL1 层对等节点含根服务器与控制器 sudo zerotier-cli listpeerszerotier-cli的核心命令包括info本机地址与连接状态、listpeers近 30 分钟通信过的 VL1 对等体、listnetworks已加入网络与托管 IP、join/leave。若允许非特权用户控制服务可把认证令牌复制到用户主目录sudo cp /var/lib/zerotier-one/authtoken.secret /home/user/.zeroTierOneAuthToken chown user /home/user/.zeroTierOneAuthToken chmod 0600 /home/user/.zeroTierOneAuthToken注意这等同于把连接/断开任意虚拟网络的权力交给了该用户。脚本场景推荐-j参数获取原始 JSON 输出-Dpath可指定非默认的服务工作目录。local.conf本地节点精细化配置service/README.md 详细说明了local.conf——放在 ZeroTier 工作目录下、默认不存在、需手动创建的 JSON 配置文件。它用于设置信任路径trusted paths、屏蔽物理路径、为特定节点提供物理路径提示、定义受信任的上游设备federated roots。在大规模部署中可用 Puppet、Chef、SaltStack 等工具统一下发。配置是否生效可通过zerotier-cli info -j校验。完整配置骨架JSON 不支持注释以下仅为示意结构{ 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, /* 是否对外分发更新默认 false仅对 ZeroTier 自身有意义 */ interfacePrefixBlacklist: [ eth, ... ], /* 屏蔽用于 ZT 流量的接口名前缀 */ allowManagementFrom: [ NETWORK/bits, ... ] | null, /* 非 null 时允许来自该网段的 JSON/HTTP 管理默认仅 127.0.0.1 */ bind: [ ip, ... ], /* 非空时只绑定这些 IP允许通配 IP */ allowTcpFallbackRelay: true|false, /* 是否允许建立 TCP 中继连接默认 true */ enableMetrics: true|false /* 是否在 metrics.prom 中采集指标 */ } }trustedPathId 的关键语义信任路径指无需加密与认证即可通信的物理网络能带来性能提升但会牺牲该路径上 ZeroTier 的全部安全特性。使用前提是所有设备对同一网络配置相同且非零的 trustedPathId任意正整数。例如同一局域网 10.0.0.0/24 内的一组设备若都对该网段定义 trustedPathId 为 25即可使用这条快速信任路径——文档原话是仅在明确知晓后果且确实需要性能时才使用。service/README.md给出的完整示例{ 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 } }从源码实现看local.conf的加载发生在服务启动阶段service/OneService.cpp 中OSUtils::readFile读取local.conf若根元素不是 JSON 对象或 JSON 非法会向 stderr 输出明确的错误信息并拒绝加载运行时还会周期性检查文件变更并热重载service/OneService.cpp。此外networks.d目录下每个网络还可以存在16位网络ID.local.conf形式的按网络细粒度配置service/OneService.cpp覆盖全局local.conf中对应网络的变量。配置时必须保证 JSON 格式合法可用jq校验因为服务本身也可能重写该文件。本地 JSON 控制 API服务通过默认监听于127.0.0.1:9993的 JSON API 进行控制也监听0.0.0.0:9993但仅当local.conf正确配置allowManagementFrom后才可用。API 支持 GET、POST/PUTPUT 等同 POST与 DELETE。类型极其敏感布尔值必须为true/false整数不得含小数点字符串必须加引号提交字段类型不符会被忽略、报错或置为异常值未识别字段同样被忽略。所有请求需携带认证令牌authtoken.secret文件内容可通过?authtokenURL 参数或X-ZT1-AuthHTTP 请求头提供静态 UI 页面是唯一免认证的资源。另支持jsonp函数名参数获取 JSONP 封装响应。/statusGET返回运行状态与寻址信息字段全部只读address本机 10 位十六进制地址、publicIdentity、worldId/worldTimestamp世界定义、online是否至少有一个上游可达、tcpFallbackActive是否使用慢速 TCP 回退、relayPolicyALWAYS/TRUSTED/NEVER、versionMajor/versionMinor/versionRev/version软件版本本仓库当前为 1.16.2见 version.h、clock节点系统时钟毫秒时间戳。/network 与 /network/network IDGET/network返回该节点已加入的全部网络对象数组。POST/network/16位十六进制网络ID加入网络如加入公共网络 Earth 即 POST/network/8056c2e21c000001POST 数据可省略DELETE 退出网络。网络对象中可写字段仅四个其余均由控制器下发字段类型说明可写id / nwidstring16 位十六进制网络 ID后者为遗留字段nomacstring该网络虚拟网卡的 MAC 地址nonamestring网络短名称nostatusstringOK、ACCESS_DENIED 等状态notypestringPUBLIC 或 PRIVATEnomtuinteger以太网 MTUnodhcpboolean是否应通过 DHCP 获取 IPnobridgeboolean该设备能否桥接其他设备nobroadcastEnabledboolean广播ff:ff:ff:ff:ff:ff是否可用noportErrorinteger底层 tap 驱动返回的错误码nonetconfRevisioninteger网络配置修订号noassignedAddresses[string]分配的 ZeroTier IP 地址含 /bitsnoroutes[object]分配的路由见下noportDeviceNamestring虚拟网络设备名noallowManagedboolean是否允许 IP 与路由托管yesallowGlobalboolean是否允许与全球 IP 重叠的 IP/路由yesallowDefaultboolean是否允许覆盖系统默认路由yesallowDNSboolean是否允许配置网络 DNSyesRoute 对象字段target目标网段/掩码位数、via下一跳网关 IP 或 LAN 为 null、flags当前恒为 0、metric路由度量当前未使用全部只读。/peer 与 /peer/addressGET/peer返回当前全部对等体数组。Peer 对象字段address10 位十六进制地址、versionMajor/Minor/Rev/version远端版本已知时、latency毫秒延迟已知时、roleLEAF、UPSTREAM、ROOT 或 PLANET、paths当前活跃物理路径数组。Path 对象字段address物理 socket 地址形如 IP/port、lastSend/lastReceive最近收发时间戳、active是否使用中、expired是否已过期、preferred是否为当前首选路径、trustedPathId非零表示未加密的信任路径。以上字段表与one.cpp中zerotier-cli人格的实现one.cpp相互印证CLI 本身只是对这套 JSON API 的封装-j输出即 API 原始 JSON。网络控制器私有网络的大脑每个 ZeroTier 虚拟网络都依赖一个网络控制器Network Controller负责接纳成员、签发证书与下发默认配置。仓库中 nonfree/controller/README.md 介绍了参考实现它与 ZeroTier 官方托管服务my.zerotier.com所用的控制器几乎一致仅数据库后端不同。数据存储控制器数据以 JSON 格式存于工作目录的controller.d下可直接复制、rsync、纳入 git。运行期间不应原地修改这些文件编辑时务必避免写入损坏的 JSON否则重启后可能丢数据优先通过 API 操作。规模与可靠性理论上单个控制器可承载 2^24 个网络、服务数百万设备但官方建议将大量网络分散到多个控制器以均衡负载、提升容错。由于控制器使用文件系统作为数据存储重负载场景推荐快速 SSD。实现高可用只需复制工作目录做主备配合 Nomad、Kubernetes 等编排工具在主控宕机时拉起备份即可。容器化控制器容器无需真正加入网络因此不需要--device/dev/net/tun --privileged等特权只需映射本地 JSON API 端口并允许访问互联网至少 UDP/9993即可。旧版迁移1.1.14 及更早版本使用 SQLitecontroller.db升级必须运行仓库附带的migrate-sqlite工具迁移到新的文件系统 JSON 格式若工作目录残留旧controller.db而直接启动新版控制器进程会向 stderr 打印错误后终止。控制器 API 与本地控制 API 共用同一端点默认 127.0.0.1:9993全部路由挂在/controller基路径下认证方式同为X-ZT1-Auth头或?auth参数注意后者可能进入请求日志。控制器本身不做细粒度访问控制且只有网络 ID 前 10 位十六进制与控制器 ZeroTier ID 一致的网络才真正受其管辖。控制器同样对 JSON 类型极度敏感。监控方面/metrics端点暴露 Prometheus 指标controller_network_count服务中的网络数Gauge、controller_member_count成员数Gauge、controller_network_change_count/controller_member_change_count网络/成员配置变更计数Counter、controller_member_auth_count/controller_member_deauth_count成员认证/撤销认证计数Counter。配合local.conf的enableMetrics设置即可启用指标采集。工作目录中的关键文件服务工作目录内的文件语义详见 doc/zerotier-one.8.md文件/目录说明identity.public公钥身份10 位十六进制地址 公钥identity.secret完整身份含私钥复制它即可迁移地址务必备份并严格保护控制器场景下它相当于网络 CA 私钥authtoken.secret本地 JSON API 认证令牌缺失时启动自动生成devicemap记录 zt# 接口号与网络的映射跨重启持久化FreeBSD 等长接口名平台可能无此文件zerotier-one.pid/zerotier-one.port进程 PID 与主端口后者供zerotier-cli定位控制 APIcontroller.db/controller.db.backup旧版 SQLite 控制器数据库及周期备份新版为controller.d/JSON 目录iddb.d/近 60 天通信过对等体的公钥身份缓存可删除但会拖慢建连networks.d/已加入网络的配置与证书缓存在启动前touch一个空的网络ID.conf可预配置加入某网络许可证结构README 明确了许可证边界与 build.md 的目录结构说明一致node/、osdep/、service/等目录除ext/与nonfree/外遵循 MPL-2.0见 LICENSE-MPL.txtnonfree/下的源码可得source available非自由部分见 nonfree/LICENSE.mdext/为构建便利或向后兼容引入的外部代码保留各自原始许可证对应仓库中的ext/目录内含 hiredis、libnatpmp、http-parser、inja、nlohmann json 等。由此可以得出与构建章节呼应的结论想要一个纯 MPL-2.0 的自由守护进程使用 CMake 预设时请选择*-free-*变体ZT_NONFREEOFF它不会编译或链接任何nonfree/代码而默认官方发布形态构建则包含内置的 FileDB 网络控制器可同时承担节点与控制器的角色。【免费下载链接】ZeroTierOneA Smart Ethernet Switch for Earth项目地址: https://gitcode.com/GitHub_Trending/ze/ZeroTierOne创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
