ZeroTier One 源码构建与运行完全指南Makefile、CMake 与多平台部署【免费下载链接】ZeroTierOneA Smart Ethernet Switch for Earth项目地址: https://gitcode.com/GitHub_Trending/ze/ZeroTierOne导读本文以 ZeroTier One 仓库根目录的 build.md 为核心骨架系统讲解这个开源虚拟局域网SDN项目在 macOS、Linux、Windows、FreeBSD、OpenBSD 等多平台上的源码构建、自测selftest、服务启动与目录组织方式。读完本文你将掌握make与 CMake 两条构建路径的完整操作、ZT_NONFREE等关键开关的实际影响、zerotier-one -d的守护进程运行方式以及配置主目录、JSON API 与local.conf之间的关系可直接在目标平台上完成从源码到可运行服务的全流程。一、构建总览两套并行的构建体系ZeroTier One 的构建体系分为官方主路径与 CMake 便捷路径两套它们长期并存、产出等价的可执行文件官方构建路径macOS 与 Linux 使用根目录的make分别加载 make-mac.mk 与 make-linux.mkFreeBSD / OpenBSD / NetBSD 使用gmakeGNU makeWindows 使用 windows/ 下的 Visual Studio 解决方案。官方发布版本均由此路径产出。CMake 便捷路径根目录 CMakeLists.txt 提供的备选方案配合 CMakePresets.json 预设使用方便习惯 CMake 工作流的开发者但它不是官方发布渠道。两个体系共享同一套核心源码与目标文件清单根 Makefile 按uname -s自动选择平台规则例如在 Linux 上 includemake-linux.mk、在 FreeBSD 上设置CCclang后 includemake-bsd.mk而公共的 objects.mk 与 objects-nonfree.mk 定义了node/、osdep/、service/等目录下需要编译的目标文件。当前仓库版本号定义在 version.h为 1.16.2ZEROTIER_ONE_VERSION_MAJOR1、MINOR16、REVISION2。提示CMake 的 CMakeLists.txt 在注释中明确说明它是 makefile 构建的“faithful mirror忠实镜像”架构检测、编译选项、特性开关均逐条翻译自make-linux.mk。因此理解任意一条路径的开关语义即可迁移到另一条路径。二、平台要求与工具链准备macOS需要Xcode command line toolsmacOS 版本要求10.13 或更新make-mac.mk 中的MACOS_VERSION_MIN10.13会通过-mmacosx-version-min10.13编译参数固化这一下限。编译器固定为clang/clang。若构建开启 SSO单点登录功能还需要为 x86_64 与 ARM64 目标安装Rust详见下文“SSO 与 rustybits”小节。Linux最低编译器版本GCC/G 8.x或CLANG/CLANG 5.x。Linux 的 makefile 会自动探测并优先使用 clang/clangmake-linux.mk 检查/usr/bin/clang是否存在若存在则选中它因为多数情况下它产出的二进制更小、速度略快。若想强制使用 gcc可在 make 命令行显式覆盖make CCgcc CXXg同样地开启 SSO 时需要 Rustx86_64 与 ARM64 目标。Windows需要Visual Studio 2022操作系统为Windows 10 或更新。官方路径使用 windows/ZeroTierOne.sln 解决方案其中 windows/TapDriver6/ 是 NDIS6 虚拟网卡驱动工程windows/ZeroTierOneSDK/ 是 SDK 工程。开启 SSO 时同样需要 Rustx86_64 与 ARM64 目标对应i686/x86_64/aarch64-pc-windows-msvctriple见 CMakeLists.txt。FreeBSD 与 OpenBSD必须使用 GNU make安装后以gmake命令构建根 Makefile 中 FreeBSD 设置ZT_BUILD_PLATFORM7、OpenBSD 设置为 9并统一使用 clang。FreeBSD 还需要binutilspkg install binutils。OpenBSD 的硬性限制最多只能加入 4 个网络成员因为系统只有 4 个 tap 设备/dev/tap0到/dev/tap3。这是平台固有限制与 ZeroTier 软件本身无关。NetBSD 也有独立的 make-netbsd.mk 规则从 CMakeLists.txt 的平台代码定义看FreeBSD7、OpenBSD9、macOS3、Windows2、Linux1而 NetBSD 未分配独立平台码编译期回退为 0。三、基本构建命令在 macOS 与 Linux 上最简单的构建方式make该命令会依次产出三个二进制见 make-linux.mk 的one目标zerotier-one守护进程本体、以及指向它的符号链接zerotier-idtool与zerotier-cli——三个工具实际是同一个可执行文件通过 argv[0] 与参数分派one.cpp 中-i进入 idtool 模式、-q进入 cli 查询模式。发布版默认编译为 Release-O3 -fstack-protector并带-pie -Wl,-z,relro,-z,now等加固参数Debug 版则用make ZT_DEBUG1。FreeBSD / OpenBSD / NetBSD 上则执行gmake常用构建目标目标作用make/gmake构建守护进程zerotier-one及zerotier-cli、zerotier-idtool符号链接make selftest构建zerotier-selftest自测二进制见下节make core仅构建静态库libzerotiercore.a核心引擎供 SDK 类场景使用make debug以ZT_DEBUG1构建 one 与 selftestmake official官方发布构建ZT_OFFICIAL1 ZT_NONFREE1并行全量构建make manpages从 doc/ 生成 man 手册页make clean清理全部产物保留源码make debian/make redhat调用debuild/rpmbuild打 .deb / .rpm 包自测make selftest构建文档特别强调在新平台或新架构上首次构建时强烈建议运行自测make selftest ./zerotier-selftest它会在zerotier-selftest中执行大量单元测试覆盖身份identity生成与验证、证书、密码学原语Salsa20/12、SHA-512、Poly1305、Ed25519、AES 等、网络配置、规则引擎、路由等内容并报告构建环境信息。例如 selftest.cpp 中“Generating identities A and B…”即是对节点身份密钥对的生成与签名验签测试。CMake 路径下非 Windows 平台同样生成zerotier-selftest目标CMakeLists.txt。四、构建开关ZT_NONFREE 与 SSOFree vs. DefaultZT_NONFREE这是理解 ZeroTier One 构建体系最核心的开关默认非 free构建守护进程会内置基于 FileDB 的网络控制器该代码位于 nonfree/属于“source available源码可得但非自由许可”这正是官方发布版的行为ZT_NONFREEON。在 make 路径中make-linux.mk 通过ZT_NONFREE1引入objects-nonfree.mk中的控制器目标文件并定义-DZT_NONFREE_CONTROLLERCMake 路径则默认ZT_NONFREE为 ONCMakeLists.txt只有ZT_NONFREEON时才add_subdirectory(nonfree)并把zerotier-controller链接进最终二进制。纯 free 构建设置-DZT_NONFREEOFF或使用*-free-*预设守护进程只包含MPL-2.0许可的 node/、osdep/、service/ 代码不编译、不链接任何nonfree/代码。判断依据当前仓库 node/、osdep/、service/ 采用 MPL-2.0见 LICENSE-MPL.txt而 nonfree/LICENSE.md 单独声明其非自由许可。SSO单点登录与 rustybits开启 SSO 功能需要Rust工具链原因是 SSO/OIDC 认证逻辑由 Rust 子工程 rustybits/其src/zeroidc/目录存放 OIDC 实现编译为静态库后链接进 C 守护进程。以 make-linux.mk 为例当架构支持 SSOZT_SSO_SUPPORTED1且非嵌入式构建时会链接rustybits/target/release/librustybits.a并附加-ldl -lssl -lcrypto。需要安装的 Rust target 取决于平台macOS 为x86_64-apple-darwin与aarch64-apple-darwinWindows 为x86_64/i686/aarch64-pc-windows-msvc见 CMakeLists.txt。若构建中未启用 SSO则无需 Rust。五、CMake 可选构建路径CMake 是备选构建路径仅为便利提供官方构建仍由平台 makefile 与windows/的 Visual Studio 解决方案产出。前置条件CMake 3.15 或更新预设文件要求 3.21见 CMakePresets.json。与 makefile 构建相同的编译器/工具链开启 SSO 时同样需要 Rust。OpenTelemetry API仅头文件必须出现在CMAKE_PREFIX_PATH中。运行一次 bootstrap 脚本默认快速模式即不带ZT_CONTROLLER_DEPS1即可将其装入./.depsscripts/bootstrap-deps.sh # 默认模式仅头文件的 OTel API 装入 ./.deps脚本结束时scripts/bootstrap-deps.sh会打印出构建时应使用的确切-DCMAKE_PREFIX_PATH值。使用预设推荐cmake --list-presets可查看当前操作系统可用的全部预设。守护进程相关预设如下预设构建内容macos-release/linux-release默认守护进程包含非自由的内置控制器macos-free-release/linux-free-release纯 free守护进程ZT_NONFREEOFF无非自由代码macos-debug/linux-debug以及*-free-debug上述预设的 Debug 变体macos-universal-releasemacOS 通用二进制arm64 x86_64守护进程freebsd-release/openbsd-release/netbsd-release及*-free-release、*-debugBSD 守护进程 / free 变体windows-x64-release及windows-x64-freeWindows 守护进程 / free 变体实际使用示例# 默认非 free守护进程 cmake --preset macos-release cmake --build --preset macos-release # 纯 free 守护进程 cmake --preset macos-free-release cmake --build --preset macos-free-release每个预设使用独立的构建目录build-presetName/因此二进制位于例如build-macos-free-release/zerotier-one。macOS/Linux 预设使用单配置 Unix Makefiles 生成器构建类型Release/Debug已固化在预设名中不存在Release/子目录Windows 预设则走 Visual Studio 多配置生成器需在 build 预设里以--configuration Release/Debug指定。手动调用不使用预设# 默认非 free守护进程 —— .deps 中的 OTel API 来自 bootstrap-deps.sh cmake -DCMAKE_PREFIX_PATH$PWD/.deps -S . -B build cmake --build build -j8 # 纯 free 守护进程 cmake -DZT_NONFREEOFF -DCMAKE_PREFIX_PATH$PWD/.deps -S . -B build cmake --build build -j8产物为build/zerotier-one。在 macOS 上若依赖来自 Homebrew需要把 Homebrew 的前缀追加进CMAKE_PREFIX_PATH预设正是这么做的见 CMakePresets.json 中macos-base追加的$env{HOMEBREW_PREFIX}及其 openssl3、libpq 路径。中央控制器Central Controller构建如需构建托管版中央控制器-DZT1_CENTRAL_CONTROLLER1需以ZT_CONTROLLER_DEPS1运行 bootstrap构建完整的 OpenTelemetry SDK/OTLP 导出器与 google-cloud-cppbigtable、pubsub并额外依赖 libpq、redis-plus-plus 等scripts/bootstrap-deps.sh、CMakeLists.txt。该路径不支持 Windows。控制器后端实现位于 nonfree/controller/详见其 README_CENTRAL_CONTROLLER.md。六、运行 ZeroTier One 服务命令行参数以zerotier-one -h查看完整帮助源码见 one.cpp核心参数包括参数作用-h显示帮助-v显示版本号-dfork 到后台以守护进程方式运行仅 Unix 系-U跳过权限检查不尝试降权运行-pport指定 UDP/TCP(HTTP) 端口默认 99930 为随机端口-C以命令行方式而非 Windows 服务运行Windows-I/-R安装 / 卸载 Windows 服务Windows-i进入 zerotier-idtool 模式身份管理-q进入 zerotier-cli 模式API 查询从源码启动服务Linux 与 BSD 上从源码构建后启动服务sudo ./zerotier-one -d-d会使进程 fork 到后台首次运行时会自动创建 home 目录、生成节点身份identity.public/identity.secret与authtoken.secret。在大多数发行版、macOS 与 Windows 上官方安装包会自动启动服务并配置开机自启无需手动操作。配置文件 home 目录位置ZeroTier 将配置与状态文件存放在平台特定的 home 目录实现见 osdep/OSUtils.cpp也可通过环境变量ZEROTIER_HOME覆盖平台Home 目录Linux/var/lib/zerotier-oneFreeBSD / OpenBSD/var/db/zerotier-onemacOS/Library/Application Support/ZeroTier/OneWindows\ProgramData\ZeroTier\One默认若 Windows 安装在非标准盘符或采用特殊布局“shared app data”基目录可能不同JSON API 与本地管理服务通过JSON API进行控制默认监听127.0.0.1:9993同时也会监听0.0.0.0:9993但仅在local.conf中正确配置了allowManagementFrom时该监听才可被外部使用源码中_allowManagementFrom由 service/OneService.cpp 从配置解析并用于管理连接鉴权。仓库附带的zerotier-cli命令行工具封装了常用 API 调用如加入/离开网络。API 认证令牌保存在 home 目录的authtoken.secret文件中service/OneService.cpp若写入失败会提示使用-U参数运行。实际监听端口写入 home 目录的zerotier-one.port文件service/OneService.cpp。API 完整文档见 service/README.md其中包含/status、/network、/network/networkID、/peer、/peer/address等端点的字段说明与可写属性例如allowManaged、allowGlobal、allowDefault、allowDNS为网络级可写字段。节点级配置通过 home 目录下的local.confJSON 格式不存在时不创建即用默认值设置支持physical物理路径黑名单、trustedPathId 可信路径、mtu、virtual按节点地址的try提示与blacklist、settingsprimaryPort、portMappingEnabled、softwareUpdate、allowManagementFrom、bind、enableMetrics等。校验配置是否生效可用zerotier-cli info -j检查。七、仓库目录结构与许可体系顶层目录职责目录职责node/核心组网代码Peer、Topology、Network、Packet、Switch、Multicaster、Identity、CryptoAES、Salsa20、Poly1305、SHA512、ECC等osdep/操作系统相关代码LinuxEthernetTap、BSDEthernetTap、MacEthernetTap、WindowsEthernetTap、PortMapper、OSUtils、Phy 等service/服务实现与 JSON APIOneService以及 service/README.md 的 API 文档controller/网络控制器实现注当前仓库中控制器源码位于 nonfree/controller/顶部目录保留该说明条目ext/为构建便利引入的外部代码保留各自原始许可证http-parser、miniupnpc、libnatpmp、hiredis、inja、nlohmann json、opentelemetry-cpp-api-only、prometheus-cpp-lite 等nonfree/“源码可得”非自由部分FileDB 控制器、中央控制器后端PostgreSQL、Redis、BigTable、PubSubwindows/Windows 专属Visual Studio 解决方案ZeroTierOne.sln、NDIS6 驱动、SDK 工程构建系统要点标准构建make自测构建make selftest平台差异FreeBSD/OpenBSD 用gmakeGNU makeWindows 用 windows/ZeroTierOne.sln 的 Visual Studio 解决方案许可结构node/、osdep/、service/MPL-2.0见 LICENSE-MPL.txtnonfree/非自由“源码可得”代码见 nonfree/LICENSE.mdext/外部代码保留原始许可证如 ext/ 下各子目录自带的 LICENSE/COPYING八、常见问题与排查建议架构无法识别若 make 构建报FATAL: architecture could not be determined from $(CC) -dumpmachine说明当前编译器目标不在 make-linux.mk 的架构映射表中该表覆盖 x86_64、i386、arm/armhf/armv6/armv7、aarch64、mips、powerpc、s390x、riscv64、loongarch64 等CMake 路径则会在 CMakeLists.txt 抛出类似的 FATAL_ERROR。OpenTelemetry 找不到CMake 构建若报opentelemetry-cpp (API) was not found请先运行scripts/bootstrap-deps.sh再以脚本输出的CMAKE_PREFIX_PATH重新配置。authtoken 写不进去以 root 运行zerotier-one -d时若提示authtoken.secret could not be written可尝试-U参数跳过权限处理。OpenBSD 无法加入更多网络确认是否超过了 4 个 tap 设备的平台上限。新平台首次构建务必先make selftest并运行zerotier-selftest验证密码学与身份模块在目标架构上的正确性。结语从make到cmake --preset从 MPL-2.0 的自由守护进程到含内置控制器的官方构建ZeroTier One 提供了一套分层清晰、平台适配完善的多目标构建体系。无论是为嵌入式设备交叉编译、为生产环境打包发行版还是仅需在开发机上快速跑起一个虚拟局域网节点本文梳理的开关语义、目录结构与运行方式都能帮助你准确选择正确的构建路径并在新平台上通过 selftest 快速验证环境的可靠性。【免费下载链接】ZeroTierOneA Smart Ethernet Switch for Earth项目地址: https://gitcode.com/GitHub_Trending/ze/ZeroTierOne创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考