☰

企业官网建设流程全解析

首页 / 建站日记 / 企业官网建设流程全解析
ZeroTier One 源码构建与运行完全指南：Makefile、CMake 与多平台部署
2026/9/13 20:01:58 网站建设 项目流程

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.mk），FreeBSD / OpenBSD / NetBSD 使用gmake（GNU make），Windows 使用 windows/ 下的 Visual Studio 解决方案。官方发布版本均由此路径产出。
  • CMake 便捷路径：根目录 CMakeLists.txt 提供的备选方案，配合 CMakePresets.json 预设使用，方便习惯 CMake 工作流的开发者，但它不是官方发布渠道。

两个体系共享同一套核心源码与目标文件清单：根 Makefile 按uname -s自动选择平台规则，例如在 Linux 上 includemake-linux.mk、在 FreeBSD 上设置CC=clang后 includemake-bsd.mk；而公共的 objects.mk 与 objects-nonfree.mk 定义了node/、osdep/、service/等目录下需要编译的目标文件。当前仓库版本号定义在 version.h，为 1.16.2（ZEROTIER_ONE_VERSION_MAJOR=1、MINOR=16、REVISION=2）。

提示：CMake 的 CMakeLists.txt 在注释中明确说明它是 makefile 构建的“faithful mirror（忠实镜像）”，架构检测、编译选项、特性开关均逐条翻译自make-linux.mk。因此理解任意一条路径的开关语义，即可迁移到另一条路径。

二、平台要求与工具链准备

macOS

  • 需要Xcode command line tools，macOS 版本要求10.13 或更新（make-mac.mk 中的MACOS_VERSION_MIN=10.13会通过-mmacosx-version-min=10.13编译参数固化这一下限）。
  • 编译器固定为clang/clang++。
  • 若构建开启 SSO（单点登录）功能，还需要为 x86_64 与 ARM64 目标安装Rust（详见下文“SSO 与 rustybits”小节）。

Linux

  • 最低编译器版本：GCC/G++ 8.x或CLANG/CLANG++ 5.x。

  • Linux 的 makefile 会自动探测并优先使用 clang/clang++（make-linux.mk 检查/usr/bin/clang是否存在，若存在则选中它），因为多数情况下它产出的二进制更小、速度略快。若想强制使用 gcc，可在 make 命令行显式覆盖：

    make CC=gcc CXX=g++

  • 同样地，开启 SSO 时需要 Rust（x86_64 与 ARM64 目标）。

Windows

  • 需要Visual Studio 2022，操作系统为Windows 10 或更新。
  • 官方路径使用 windows/ZeroTierOne.sln 解决方案；其中 windows/TapDriver6/ 是 NDIS6 虚拟网卡驱动工程，windows/ZeroTierOneSDK/ 是 SDK 工程。
  • 开启 SSO 时同样需要 Rust（x86_64 与 ARM64 目标，对应i686/x86_64/aarch64-pc-windows-msvctriple，见 CMakeLists.txt）。

FreeBSD 与 OpenBSD

  • 必须使用 GNU make：安装后以gmake命令构建（根 Makefile 中 FreeBSD 设置ZT_BUILD_PLATFORM=7、OpenBSD 设置为 9，并统一使用 clang）。
  • FreeBSD 还需要binutils：pkg install binutils。
  • OpenBSD 的硬性限制：最多只能加入 4 个网络成员，因为系统只有 4 个 tap 设备（/dev/tap0到/dev/tap3）。这是平台固有限制，与 ZeroTier 软件本身无关。
  • NetBSD 也有独立的 make-netbsd.mk 规则；从 CMakeLists.txt 的平台代码定义看，FreeBSD=7、OpenBSD=9、macOS=3、Windows=2、Linux=1，而 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_DEBUG=1。

FreeBSD / OpenBSD / NetBSD 上则执行：

gmake

常用构建目标

目标作用
make/gmake构建守护进程zerotier-one及zerotier-cli、zerotier-idtool符号链接
make selftest构建zerotier-selftest自测二进制（见下节）
make core仅构建静态库libzerotiercore.a（核心引擎，供 SDK 类场景使用）
make debug以ZT_DEBUG=1构建 one 与 selftest
make official官方发布构建：ZT_OFFICIAL=1 ZT_NONFREE=1并行全量构建
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 与 SSO

Free vs. Default（ZT_NONFREE）

这是理解 ZeroTier One 构建体系最核心的开关：

  • 默认（非 free）构建：守护进程会内置基于 FileDB 的网络控制器，该代码位于 nonfree/，属于“source available（源码可得但非自由许可）”，这正是官方发布版的行为（ZT_NONFREE=ON）。在 make 路径中，make-linux.mk 通过ZT_NONFREE=1引入objects-nonfree.mk中的控制器目标文件，并定义-DZT_NONFREE_CONTROLLER；CMake 路径则默认ZT_NONFREE为 ON（CMakeLists.txt），只有ZT_NONFREE=ON时才add_subdirectory(nonfree)并把zerotier-controller链接进最终二进制。
  • 纯 free 构建：设置-DZT_NONFREE=OFF（或使用*-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 为例，当架构支持 SSO（ZT_SSO_SUPPORTED=1）且非嵌入式构建时，会链接rustybits/target/release/librustybits.a并附加-ldl -lssl -lcrypto。需要安装的 Rust target 取决于平台：macOS 为x86_64-apple-darwin与aarch64-apple-darwin，Windows 为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_DEPS=1）即可将其装入./.deps：

    scripts/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_NONFREE=OFF，无非自由代码）
macos-debug/linux-debug（以及*-free-debug）上述预设的 Debug 变体
macos-universal-releasemacOS 通用二进制（arm64 + x86_64）守护进程
freebsd-release/openbsd-release/netbsd-release（及*-free-release、*-debug）BSD 守护进程 / free 变体
windows-x64-release（及windows-x64-free）Windows 守护进程 / 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_NONFREE=OFF -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}及其 openssl@3、libpq 路径）。

中央控制器（Central Controller）构建

如需构建托管版中央控制器（-DZT1_CENTRAL_CONTROLLER=1），需以ZT_CONTROLLER_DEPS=1运行 bootstrap，构建完整的 OpenTelemetry SDK/OTLP 导出器与 google-cloud-cpp（bigtable、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跳过权限检查，不尝试降权运行
-p<port>指定 UDP/TCP(HTTP) 端口（默认 9993，0 为随机端口）
-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-one
FreeBSD / OpenBSD/var/db/zerotier-one
macOS/Library/Application Support/ZeroTier/One
Windows\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.conf（JSON 格式，不存在时不创建即用默认值）设置，支持physical（物理路径黑名单、trustedPathId 可信路径、mtu）、virtual（按节点地址的try提示与blacklist）、settings（primaryPort、portMappingEnabled、softwareUpdate、allowManagementFrom、bind、enableMetrics等）。校验配置是否生效可用zerotier-cli info -j检查。

七、仓库目录结构与许可体系

顶层目录职责

目录职责
node/核心组网代码：Peer、Topology、Network、Packet、Switch、Multicaster、Identity、Crypto（AES、Salsa20、Poly1305、SHA512、ECC）等
osdep/操作系统相关代码：LinuxEthernetTap、BSDEthernetTap、MacEthernetTap、WindowsEthernetTap、PortMapper、OSUtils、Phy 等
service/服务实现与 JSON API（OneService），以及 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、PubSub）
windows/Windows 专属：Visual Studio 解决方案（ZeroTierOne.sln）、NDIS6 驱动、SDK 工程

构建系统要点

  • 标准构建：make
  • 自测构建：make selftest
  • 平台差异：FreeBSD/OpenBSD 用gmake（GNU make）；Windows 用 windows/ZeroTierOne.sln 的 Visual Studio 解决方案

许可结构

  • node/、osdep/、service/：MPL-2.0（见 LICENSE-MPL.txt）
  • nonfree/：非自由“源码可得”代码（见 nonfree/LICENSE.md）
  • ext/：外部代码，保留原始许可证（如 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），仅供参考

标签： 网站建设 企业官网 项目流程 UI设计 前端开发

热门文章

文章分类

标签云

网站建设 响应式设计 用户体验 SEO优化 前端开发 小程序 电商平台 性能优化

相关文章

您可能感兴趣的其他内容

Figma 变量创建指南：从源 Token 数据到语义化变量体系的建模与落地（基于 figma-use Skill 实践）
2026/9/13 20:01:18 网站建设

Figma 变量创建指南：从源 Token 数据到语义化变量体系的建模与落地（基于 figma-use Skill 实践）

Figma 变量创建指南&#xff1a;从源 Token 数据到语义化变量体系的建模与落地&#xff08;基于 figma-use Skill 实践&#xff09; 【免费下载链接】skills Skills Catalog for Codex 项目地址: https://gitcode.com/GitHub_Trending/skills4/skills 本篇指南聚焦于「如…...

阅读更多 →
MaxKB v2.6.0智能体触发器与知识库升级详解
2026/9/13 19:59:38 网站建设

MaxKB v2.6.0智能体触发器与知识库升级详解

1. MaxKB v2.6.0版本核心升级解析MaxKB开源企业级智能体平台最新发布的v2.6.0版本带来了多项重要功能升级&#xff0c;其中最引人注目的是全面增强的触发器能力。这个版本标志着智能体自动化水平迈上新台阶&#xff0c;为企业用户提供了更高效的业务流程自动化解决方案。作为一…...

阅读更多 →
AI音乐生成全链路实操：从歌词到成品音频的工程化指南
2026/9/13 19:58:33 网站建设

AI音乐生成全链路实操：从歌词到成品音频的工程化指南

1. 为什么Easy-Vibe选中了“AI音乐生成”这一站1.1 课程里“Vibe”的真实含义&#xff1a;不只要跑通模型&#xff0c;还要控制那种感觉Datawhale的Easy-Vibe系列2026年2月这期&#xff0c;主题定在AI音乐生成方向。说实话&#xff0c;我第一次看到课程名里的“Vibe”这个词&am…...

阅读更多 →

需要专业的网站建设服务？

联系我们获取免费的网站建设咨询和方案报价，让我们帮助您实现业务目标

立即咨询