企业官网建设流程全解析

ZeroTier One 官方发布流程全解析：版本号提升、多平台签名构建与质量检查

【免费下载链接】ZeroTierOneA Smart Ethernet Switch for Earth项目地址: https://gitcode.com/GitHub_Trending/ze/ZeroTierOne

本文档以仓库根目录下的 OFFICIAL-RELEASE-STEPS.md 为主体骨架，系统讲解 ZeroTier One 从"确定新版本号"到"产出带数字签名的 macOS/Windows 安装包"的完整官方发布流程。这份指南最初面向 ZeroTier 内部发布人员，但其中涉及的构建变量、签名工具链和安装包工程文件，对任何希望自行构建、打包或复刻官方二进制产出物的开发者同样具有直接参考价值。读完本文，你将掌握版本号在仓库中的分布位置与修改方法、make official在 macOS 上的真实执行序列，以及 Windows MSI 安装包的构建、签名与验收要点。

发布流程概览与前提条件

ZeroTier One 的官方发布流程分为两大阶段：版本号提升与安装包工程文件准备、分平台构建与签名。整个流程高度依赖持证密钥：

Note: Many of these steps will require GPG and other signing keys that are kept in cold storage and must be mounted.

也就是说，发布前需要将存放在冷存储（cold storage）中的 GPG 及其他签名密钥挂载到构建机上。这些密钥用于：

• macOS 安装包的 Developer ID 签名与 Apple 公证（notarization）；
• Windows MSI 文件的 DigiCert 产品签名；
• 源码发布时对 tarball 的 GPG 签名（在 debian 包等场景中同样会用到 GPG 身份，参见 debian/changelog 中的签名者信息）。

因此，普通开发者即使只做非官方自用构建，也不需要这些密钥；只有产出对外分发、可被系统信任安装的官方级安装包时才必须持有。

第一步：提升版本号并准备安装器工程

必须同步修改的版本文件清单

新版本发布时，版本号必须在以下全部文件中递增，任何一处遗漏都会导致"二进制内部版本"与"安装包显示版本"不一致：

注意最后一项位于../DesktopUI，即 ZeroTier 的 DesktopUI 仓库中——这是发布流程中唯一不在本仓库内的修改点，发布时需单独检出该仓库并同步提升版本。

从源码看版本号的真实构成

version.h 中的宏定义揭示了 ZeroTier 版本号的完整语义：

#define ZEROTIER_ONE_VERSION_MAJOR 1 #define ZEROTIER_ONE_VERSION_MINOR 16 #define ZEROTIER_ONE_VERSION_REVISION 2 #define ZEROTIER_ONE_VERSION_BUILD 0

其中BUILD字段的注释明确说明：它在每个major.minor.rev组合内从 0 开始，可仅通过递增它来"强制触发一次小更新"而不改变对外版本号，且它不参与实际对外版本字符串（version.h）。对外版本串由 version.h 拼接生成：

#define ZEROTIER_ONE_VERSION_STR _ZT_STR(ZEROTIER_ONE_VERSION_MAJOR) "." _ZT_STR(ZEROTIER_ONE_VERSION_MINOR) "." _ZT_STR(ZEROTIER_ONE_VERSION_REVISION)

即形如1.16.2。修改版本号时只需更新前三个宏（多数情况下无需动BUILD），并同步更新其他五个文件中的对应字段。作为对照，当前仓库的 debian/changelog 首行与 zerotier-one.spec 分别记录了1.16.2与Version: 1.16.2，三者保持一致。

Windows AIP 工程的特殊要求

OFFICIAL-RELEASE-STEPS.md 特别强调，最终的.AIP文件只能在 Windows 上使用 Advanced Installer Enterprise 编辑。除了递增版本号，还必须生成一个新的product code；而upgrade code GUID 则永远不能改变。这是 Windows Installer 的语义约束：

• UpgradeCode标识产品的"家族"，保持不变才能让新版安装包正确覆盖旧版；
• ProductCode每次发布必须变更，Windows 才认为这是新版本而非同名安装。

第二步：macOS 官方构建

一条命令的入口：make official

原文档对 macOS 构建的描述非常简洁——"Mac's easy. Just type:make official"。但这条命令背后隐藏着完整的构建流水线，可从 make-mac.mk 的official目标还原：

# For ZeroTier, Inc. to build official signed packages official: FORCE cd ../DesktopUI ; make ZT_OFFICIAL_RELEASE=1 make clean make ZT_OFFICIAL_RELEASE=1 -j 8 one ZT_NONFREE=1 make ZT_OFFICIAL_RELEASE=1 mac-dist-pkg

依次执行四步：

1. 构建 DesktopUI：进入仓库外的 DesktopUI 目录，以ZT_OFFICIAL_RELEASE=1环境编译桌面界面；
2. 清理：make clean确保无旧对象残留（清理规则见 make-mac.mk）；
3. 编译守护进程：make ZT_OFFICIAL_RELEASE=1 -j 8 one ZT_NONFREE=1，其中-j 8为 8 路并行编译，ZT_NONFREE=1表示将非 MPL 的商用组件一并编译进二进制（详见下文"构建变量"一节）；
4. 打发布包：执行mac-dist-pkg生成并签名 pkg 安装器。

mac-dist-pkg：打包、签名与公证

official目标的最后一步展开自 make-mac.mk：

# Requires Packages: http://s.sudre.free.fr/Software/Packages/about.html mac-dist-pkg: FORCE packagesbuild "ext/installfiles/mac/ZeroTier One.pkgproj" rm -f "ZeroTier One Signed.pkg" $(PRODUCTSIGN) --sign $(CODESIGN_INSTALLER_CERT) "ZeroTier One.pkg" "ZeroTier One Signed.pkg" if [ -f "ZeroTier One Signed.pkg" ]; then mv -f "ZeroTier One Signed.pkg" "ZeroTier One.pkg"; fi $(NOTARIZE) submit --apple-id "..." --team-id "..." --wait "ZeroTier One.pkg" echo '*** When Apple notifies that the app is notarized, run: xcrun stapler staple "ZeroTier One.pkg"'

这条目标完整印证了原文档的说明，并揭示了更多细节：

• 依赖Packages工具：packagesbuild读取 ext/installfiles/mac/ZeroTier One.pkgproj 生成ZeroTier One.pkg。这就是为什么原文档要求构建机装有 Packages；
• 安装包签名：$(PRODUCTSIGN) --sign $(CODESIGN_INSTALLER_CERT)使用 keychain 中的 release signing key（即"我们的 release signing key in the keychain"所指）对 pkg 签名；
• Apple 公证（notarization）：$(NOTARIZE) submit ... --wait将 pkg 提交给 Apple 进行公证并等待结果，随后仍需手动执行xcrun stapler staple "ZeroTier One.pkg"将公证票据钉入安装包——这一步是官方流程的收尾动作，在 make 输出中会有明确提示。

因此完整的 macOS 官方构建条件为：安装Packages、release 签名密钥在 keychain 中、配置好 Apple ID/Team ID 公证凭据，然后执行make official。

第三步：Windows 官方构建

Windows 侧的官方发布流程与 macOS 完全不同，它不走 Makefile，而是基于两个 GUI 工具链，分三步：

1. 用 Visual Studio 编译三架构 Release 二进制

原文档要求：

First load the Visual Studio solution and rebuild the UI and ZeroTier One in both x64, i386, and arm64Releasemode.

即加载 windows/ZeroTierOne.sln，在x64、i386、arm64三种架构下，分别以Release配置重新编译UI 与 ZeroTier One 守护进程。对应的工程文件为 windows/ZeroTierOne/ZeroTierOne.vcxproj，其中已预置ZT_NONFREE_CONTROLLER=1;ZT_NONFREE=1;ZT_SSO_ENABLED=1等官方构建宏（见该文件中的PreprocessorDefinitions）。

2. 用 Advanced Installer Enterprise 构建安装包

随后加载 ext/installfiles/windows/ZeroTier One.aip，检查版本号正确后执行构建。原文档特别警告：

The build will fail if any build artifacts are missing.

即 AIP 工程会校验所有构建产物（三架构的可执行文件、驱动等）是否齐全，缺少任何工件都会直接导致构建失败。这一步也正是前文"第一步"中要求在 Windows 上用 Advanced Installer Enterprise 更新版本号与 product code 的原因。

3. 代码签名与干净 VM 验收

• 签名：Windows 构建机必须持有来自DigiCert的产品签名证书（product signing key），用于对生成的MSI 文件进行 Authenticode 签名；
• 验收：签名后的 MSI 必须至少在若干台全新（CLEAN）的 Windows 虚拟机上安装测试，以确认安装器有效且签名正确。干净 VM 的意义在于排除"目标机恰好已装过旧版/已有环境依赖"造成的假阳性结果。

构建变量：官方构建与普通构建的差异根源

原文档虽未展开，但make official中出现的ZT_OFFICIAL_RELEASE、ZT_OFFICIAL、ZT_NONFREE三个变量是理解"官方构建"与"普通构建"差异的关键，均可在仓库源码中验证：

ZT_NONFREE：是否编译内置网络控制器

• 在 make-mac.mk、make-linux.mk 等平台 Makefile 中，ifeq ($(ZT_NONFREE),1)会追加-DZT_NONFREE_CONTROLLER宏定义；
• 该宏在 one.cpp 与 service/OneService.cpp 等多处控制内置 FileDB 网络控制器的编译分支；
• CMake 侧对应 CMakeLists.txt：ZT_NONFREE拉入 bundled FileDB 控制器，且"controller 隐含 ZT_NONFREE=1"，并注释说明其为官方构建所需；
• RELEASE-NOTES.md 明确：默认二进制不再包含控制器，make ZT_NONFREE=1用于构建包含非 MPL 组件的版本，且以该变量构建出的可执行文件采用专有商业许可而非 MPL。

ZT_OFFICIAL与ZT_OFFICIAL_RELEASE：官方构建标记

• Linux 侧official目标为make -j\nproc` ZT_OFFICIAL=1 ZT_NONFREE=1 all`（make-linux.mk），即并行全量编译并强制启用非 MPL 控制器组件；
• Debian 包构建同样走该路径，见 debian/rules：make ZT_OFFICIAL=1 ZT_NONFREE=1 all；
• macOS 侧使用ZT_OFFICIAL_RELEASE=1，并在 make-mac.mk 附近影响额外定义。

非官方 / 快速构建的替代路径

对于不需要官方签名和控制器组件的场景，仓库同样提供了轻量入口：

• 纯自由软件构建（不含控制器）：make one（或 CMake 下通过 CMakePresets.json 的linux-free-release/macos-free-release预设，以-DZT_NONFREE=OFF关闭非自由组件，参见 CMakeLists.txt）；
• 调试构建：make ZT_DEBUG=1 one（make-linux.mk）；
• Docker 镜像构建：make docker（make-linux.mk）。

这些路径适合个人验证，但它们不产出带官方签名的安装包，也无法替代上述官方流程。

发布后的配套工作：变更日志与质量门禁

版本号与构建流程之外，一次完整的官方发布还涉及配套文档的同步更新，这些都可在仓库中找到对应物：

• 发布说明：RELEASE-NOTES.md 按版本记录功能变更、修复与已知注意事项（如 1.16.0 的许可证变更、1.16.2 的ZT_MAX_NETWORK_SPECIALISTS上限提升等），是发布公告的素材来源；
• Debian changelog：debian/changelog 每个版本条目包含版本号、urgency 与签名者信息，其中 1.16.2 条目直接注明 "See RELEASE-NOTES.md for release notes"，说明两者需保持同步；
• GPG 签名密钥：正式发布源码包时同样依赖冷存储中的 GPG 密钥（doc/contact@zerotier.com.gpg 为签名公钥）。

小结：一次官方发布的完整检查清单

综合原文档与源码实现，可将 ZeroTier One 官方发布浓缩为以下检查清单，供发布人或希望产出"类官方"构建的开发者对照使用：

1. 版本号同步：依次更新 version.h、zerotier-one.spec、debian/changelog、ext/installfiles/mac/ZeroTier One.pkgproj、ext/installfiles/windows/ZeroTier One.aip 及 DesktopUI 的Info.plist；
2. Windows AIP：在 Advanced Installer Enterprise 中重新生成ProductCode，保持UpgradeCode不变；
3. macOS 构建：确保Packages与 release 签名密钥就绪，执行make official（内部为 DesktopUI → clean → 并行编译ZT_OFFICIAL_RELEASE=1 ZT_NONFREE=1→mac-dist-pkg签名+公证），公证通过后手工执行xcrun stapler staple；
4. Windows 构建：VS 下编译 x64/i386/arm64 三套 Release 产物 → Advanced Installer 检查版本并构建 → DigiCert 证书签名 MSI → 在若干干净 Windows VM 上安装验收；
5. 文档配套：更新 RELEASE-NOTES.md 与 debian/changelog。

其中第 3、4 步均以ZT_NONFREE=1为前提——它决定了二进制中是否包含内置网络控制器，也决定了产物的许可证属性（MPL 还是专有商用许可），是官方构建与非官方构建之间最实质的分界线。

【免费下载链接】ZeroTierOneA Smart Ethernet Switch for Earth项目地址: https://gitcode.com/GitHub_Trending/ze/ZeroTierOne