Sonic 打包发布全指南:版本提升、Debian 打包与多平台 Release 流程
Sonic 打包发布全指南:版本提升、Debian 打包与多平台 Release 流程
导读
本文以仓库根目录的 PACKAGING.md 为主线,系统梳理 Sonic 从「提升版本号」到「构建发布」再到「签名上传」的完整打包流程。你将掌握三件事:如何在发布前正确同步 Cargo 与 Debian 包的版本号、Sonic 的 Debian 打包目录结构(debian/ 下各文件的作用与相互关系),以及如何借助 scripts/ 下的脚本完成二进制归档、包构建与 GPG 签名。文中所有步骤与参数均结合当前仓库的实际源码(Cargo.toml、debian/rules、scripts/ 等)逐一验证,可直接复制到自己的发布实践中。
说明:PACKAGING.md 以版本
1.0.0作为演示示例;当前仓库实际版本为1.4.9(见 Cargo.toml 与 debian/rules),下文所有命令均以你实际发布的版本号替换1.0.0即可。
一、发布前的版本提升(Version Bump)
PACKAGING.md 明确给出了每次发版前必须完成的三步版本同步操作,缺一不可:
1. 提升 Cargo.toml 中的版本号
打开仓库根目录的 Cargo.toml,将 [package] 段的 version 字段改为目标版本:
[package]
name = "sonic"
version = "1.0.0" # 从当前版本提升到待发布版本
Sonic 的版本遵循语义化版本(SemVer)约定,version 字段是 Cargo 构建、发布到 crates.io 时使用的唯一版本来源。
2. 执行 cargo update 同步 Cargo.lock
cargo update
cargo update 会根据新的 Cargo.toml 重新解析依赖图并更新 Cargo.lock。锁定文件中的 version 记录必须与 Cargo.toml 保持一致,否则 CI 构建出的二进制会携带错误版本信息,且 cargo publish 会因元数据不一致而失败。
3. 同步 Debian 包版本号
打开 debian/rules,将 VERSION 变量提升为同样的版本:
DISTRIBUTION = $(shell lsb_release -sr)
VERSION = 1.0.0
PACKAGEVERSION = $(VERSION)-0~$(DISTRIBUTION)0
这里可以看到 Sonic 的 Debian 包版本号并非直接取 VERSION,而是拼上发行版代号:PACKAGEVERSION = $(VERSION)-0~$(DISTRIBUTION)0,例如在 Debian Bookworm 上会生成 1.0.0-0~bookworm0。这种「~ 版本号」是 Debian 的向后兼容版本约定——带 ~ 的版本永远小于不带 ~ 的同名版本,确保同一上游版本为不同发行版构建的包可以正确覆盖升级。
核心要点:Cargo.toml、Cargo.lock、debian/rules 三处版本必须一致,这是后续所有打包、签名、上传步骤正确性的前提。
二、Sonic 的 Debian 打包目录解剖
Sonic 采用标准的 debian/ 目录结构(debian/ 目录),配合 dh(debhelper)构建体系工作。理解每个文件的作用,是读懂 PACKAGING.md 发布流程的基础:
| 文件 | 作用 |
|---|---|
| debian/control | 包元数据:包名 sonic、Section net、依赖 adduser、MPL-2.0 描述等 |
| debian/rules | 可执行的 Makefile 规则,定义包的下载、剥离、配置改写等构建行为 |
| debian/changelog | Debian 变更日志,dh 会自动读取并生成包版本信息 |
| debian/compat | debhelper 兼容级别,当前为 10 |
| debian/source/format | 源码包格式声明:3.0 (quilt) |
| debian/copyright | 版权与许可证声明(MPL-2.0,machine-readable 格式) |
| debian/sonic.install | 安装文件清单:二进制、配置与数据目录的落盘位置 |
| debian/sonic.postinst | 安装后脚本:创建系统用户并修正数据目录属主 |
| debian/sonic.service | systemd 单元文件,定义服务的启动方式与运行用户 |
1. debian/control:包元数据与依赖
debian/control 声明了包的对外元数据:
Source: sonic
Section: net
Priority: ext
Maintainer: Valerian Saliou <valerian@valeriansaliou.name>
Standards-Version: 3.9.4
Build-Depends: wget, ca-certificates
...
Package: sonic
Architecture: any
Depends: adduser
值得注意的两点:
Build-Depends: wget, ca-certificates:构建期依赖不是编译器,而是下载工具——这与debian/rules中用wget拉取预编译 tarball 的策略直接对应;Depends: adduser:运行时依赖adduser,因为 debian/sonic.postinst 需要用adduser创建sonic系统用户。
2. debian/rules:从 tarball 到 Debian 包的构建逻辑
debian/rules 是打包的核心。它没有走「源码编译」路线,而是直接下载官方发布的多架构二进制 tarball 再重新包装,逐行拆解如下:
#!/usr/bin/make -f
DISTRIBUTION = $(shell lsb_release -sr) # 当前发行版代号,如 bookworm
VERSION = 1.4.9
PACKAGEVERSION = $(VERSION)-0~$(DISTRIBUTION)0 # 形如 1.4.9-0~bookworm0
URL = https://github.com/valeriansaliou/sonic/releases/download/v$(VERSION)/
%:
dh $@ --with systemd # 启用 debhelper + systemd 集成
override_dh_auto_clean:
override_dh_auto_test:
override_dh_auto_build:
override_dh_auto_install:
$(eval ENV_ARCH := $(shell dpkg --print-architecture)) # 本机架构,如 amd64
$(eval ENV_ISA := $(shell if [ "$(ENV_ARCH)" = "amd64" ]; then echo "x86_64"; else echo "$(ENV_ARCH)"; fi))
$(eval ENV_TARBALL := v$(VERSION)-$(ENV_ISA)-gnu.tar.gz)
echo "Architecture: $(ENV_ARCH)"
echo "Instruction Set: $(ENV_ISA)"
echo "Target: $(URL)$(ENV_TARBALL)"
wget -N --progress=dot:mega $(URL)$(ENV_TARBALL) # 下载 v<VERSION>-<ISA>-gnu.tar.gz
tar -xf $(ENV_TARBALL) # 解压出 sonic/ 目录
strip sonic/sonic # 剥离符号表,缩小体积
mv sonic/config.cfg sonic/sonic.cfg # 配置重命名
mkdir sonic/store/
sed -i 's/path = ".\/data\/store\//path = "\/var\/lib\/sonic\/store\//g' sonic/sonic.cfg
override_dh_gencontrol:
dh_gencontrol -- -v$(PACKAGEVERSION) # 用发行版后缀版本生成 control 信息
关键行为总结:
- 架构映射:
amd64映射为x86_64,其余架构直接沿用dpkg --print-architecture的结果,拼出v1.4.9-x86_64-gnu.tar.gz这样的官方归档文件名; - tarball 命名约定:归档名格式为
v<VERSION>-<ISA>-gnu.tar.gz,与 scripts/release_binaries.sh 中final_tar="v$SONIC_VERSION-$1-$2.tar.gz"的产出格式一一对应; - 运行时路径改写:通过
sed将配置中的存储路径从仓库默认的./data/store/改写为 Debian 包约定路径/var/lib/sonic/store/,确保服务以系统化方式落地; - 跳过编译:
override_dh_auto_build等被显式置空,因为二进制已由上游 CI 预编译,打包机只需下载、剥离、重新布局。
3. debian/sonic.install:文件落盘清单
debian/sonic.install 将 debian/rules 处理后的产物安装到目标位置:
sonic/sonic usr/bin/
sonic/sonic.cfg etc/
sonic/store/ var/lib/sonic/
即:二进制放入 /usr/bin/sonic,配置放入 /etc/sonic.cfg,存储目录挂到 /var/lib/sonic/store/——与 debian/rules 中 sed 改写的路径、以及 systemd 单元中的 ExecStart 参数完全吻合。
4. debian/sonic.postinst:安装后的用户与权限
debian/sonic.postinst 在 configure 阶段执行:
adduser --system --disabled-password --disabled-login --home /var/empty \
--no-create-home --quiet --group sonic && \
chown sonic:sonic -R /var/lib/sonic/
它创建一个不可登录的系统用户 sonic,并把 /var/lib/sonic/ 的属主修正为 sonic:sonic。这正是 debian/control 声明 Depends: adduser 的原因,也是 debian/sonic.service 中 User=sonic、Group=sonic 能正常工作的前提。
5. debian/sonic.service:systemd 单元定义
debian/sonic.service 定义服务生命周期:
[Unit]
Description=Sonic Search Index
After=network.target
[Service]
Type=simple
User=sonic
Group=sonic
ExecStart=/usr/bin/sonic -c /etc/sonic.cfg
Restart=on-failure
LimitNOFILE=infinity
[Install]
WantedBy=multi-user.target
- 以
sonic用户运行,配置文件指向/etc/sonic.cfg(即sonic.install安装的位置); Restart=on-failure保证异常退出自动拉起;LimitNOFILE=infinity放开文件描述符上限——这与 Sonic 作为高频检索服务需要持有大量连接与文件句柄的场景相符;WantedBy=multi-user.target使其随系统多用户模式开机自启。
6. 其余文件
- debian/compat 声明 debhelper 兼容级别为
10; - debian/source/format 使用
3.0 (quilt)格式; - debian/changelog 当前为
0.0.0-1 UNRELEASED初始条目,正式发布前应补上对应版本与变更记录(dh会依据它生成包的版本元数据); - debian/copyright 采用 machine-readable 格式声明 MPL-2.0 许可证。
三、完整 Release 发布流程
PACKAGING.md 给出了从代码标记到发布上线的完整四步流程,以下结合仓库脚本逐条展开:
第 1 步:打 Git 标签并推送
git tag v1.0.0
git push origin v1.0.0
标签命名必须使用 v 前缀 + 版本号(如 v1.0.0)。这是后续所有环节的锚点:CI 的 release job、scripts/ 中的 tarball 命名(v1.0.0-x86_64-gnu.tar.gz)以及 debian/rules 的 URL 下载地址,全部依赖该标签存在。
第 2 步:等待 CI Release Job 完成
推送标签后,仓库配置的 GitHub Actions 会触发 release 工作流,为多架构(如 x86_64 的 GNU 目标)并行构建并产出二进制归档。这一步对应 scripts/release_binaries.sh 中描述的产物形态。可在仓库的 Actions 页面观察各 job 状态,全部绿后才进入下一步。
第 3 步:下载归档并本地签名
PACKAGING.md 明确指出:签名不是在 CI 中完成的,而是下载所有 release 归档后在本地用脚本签名:
./scripts/sign_binaries.sh --version=1.0.0
scripts/sign_binaries.sh 的实现细节:
- 参数解析:
-v/--version,并会剥离版本号开头的v(SONIC_VERSION="${argument_value/v}"),因此--version=v1.0.0与--version=1.0.0等价; - 缺少
--version参数时脚本会报错退出,防止误操作; - 签名核心命令:
gpg -u "valerian@valeriansaliou.name" --armor --detach-sign "v1.0.0-x86_64-gnu.tar.gz"
即用维护者的 GPG 私钥对 v<VERSION>-<ISA>-gnu.tar.gz 生成 ASCII 装甲格式的分离签名(.asc 文件)。注意 gpg_signer 硬编码为 valerian@valeriansaliou.name,与 debian/control 中的 Maintainer 一致。
第 4 步:发布变更日志、归档与签名
在 GitHub Releases 页面新建 Release:
- 撰写 changelog(对应仓库根目录的 CHANGELOG.md,发布时应摘录本次版本的核心变更,如新命令、协议改动、性能优化等);
- 上传第 2 步构建的所有归档文件(
v1.0.0-*.tar.gz); - 一并上传第 3 步生成的对应签名文件(
*.asc),使用户可以校验下载文件的完整性与来源。
说明:PACKAGING.md 中的 Actions 与 Releases 链接指向上游项目页面;本文按当前仓库实际情况整理为流程描述,不引用外部链接。
四、配套脚本:从源码到归档的三级流水线
scripts/ 目录下的三个脚本与 PACKAGING.md 的发布流程深度咬合,构成「构建 → 打包 → 签名」的完整链路:
1. scripts/release_binaries.sh:跨架构编译与归档
scripts/release_binaries.sh 负责为指定 target 编译并打 tarball:
cargo build --target "$3" --release && \
mkdir ./sonic && \
cp -p "target/$3/release/sonic" ./sonic/ && \
cp -r ./config.cfg sonic/ && \
tar --owner=0 --group=0 -czvf "$final_tar" ./sonic
- 产物结构固定为
sonic/sonic+sonic/config.cfg,与debian/rules解包后的目录布局完全一致; - 使用
--owner=0 --group=0强制归档内文件属主为 root,保证不同环境下解包一致; - 当前脚本只调用了
x86_64-unknown-linux-gnu一个 target,从源码结构看,多架构扩展只需为每个目标重复调用release_for_architecture即可。
2. scripts/build_packages.sh:调用 packpack 构建发行版包
scripts/build_packages.sh 使用 packpack(PackPack 项目的打包工具)为指定 OS/发行版构建包:
git clone https://github.com/packpack/packpack.git packpack
build_for_target "x86_64" "debian" "bookworm" ".deb"
脚本先克隆 packpack,再为 debian/bookworm 目标构建 .deb,产物移动到 ./packages/debian_bookworm/ 目录,最后清理 ./build 与 ./packpack。OS、DIST、ARCH 均通过环境变量传给 packpack,debian/rules 中的 $(shell lsb_release -sr) 正是 packpack 容器内检测发行版代号的依据。
3. scripts/sign_binaries.sh:本地 GPG 分离签名
如第三节所述,该脚本对每个架构的 tarball 执行 gpg --armor --detach-sign,生成 .asc 签名文件,供 Release 页面上传。
五、发布清单与常见注意事项
将 PACKAGING.md 的要点整理为可勾选的发布清单:
版本提升阶段(发版前)
- ✅ Cargo.toml 中
version提升为目标版本; - ✅ 执行
cargo update同步 Cargo.lock; - ✅ debian/rules 中
VERSION同步为目标版本; - ✅ 更新 debian/changelog 与 CHANGELOG.md。
发布阶段(打标签后)
5. ✅ 创建并推送 v<版本> 标签;
6. ✅ 等待 CI release job 完成并产出全架构 tarball;
7. ✅ 下载所有归档,执行 ./scripts/sign_binaries.sh --version=<版本> 生成签名;
8. ✅ 在 Releases 页面发布 changelog,并上传归档 + .asc 签名文件。
注意事项
- 版本一致性:
Cargo.toml/Cargo.lock/debian/rules三者版本必须完全一致,任何一处遗漏都会导致构建产物或包版本错乱; - 签名必须本地完成:PACKAGING.md 明确签名不在 CI 中进行,而是下载归档后在本机用维护者 GPG 私钥签名——这避免了将私钥暴露给 CI 环境的安全风险;
- 架构映射规则:
amd64↔x86_64,其余架构沿用原值,下载与签名时要注意 tarball 命名中的 ISA 字段; - 路径改写依赖顺序:
debian/rules中的sed改写、debian/sonic.install的落盘位置、debian/sonic.service的ExecStart参数三者必须保持路径一致(/var/lib/sonic/store/、/etc/sonic.cfg),改动任一环节需同步验证其他两处; - Docker 路径参考:Dockerfile 也展示了 Sonic 官方容器化的等价做法——多阶段构建(
rust:slim-bullseye编译 →distroless/cc运行)、strip二进制、sonic -c /etc/sonic.cfg启动、暴露1491端口。如果团队用容器发布而非 Debian 包,可参照此文件,但存储目录应使用 volume 挂载持久化。
结语
PACKAGING.md 是一份精炼的发布备忘,而它与 debian/ 目录、scripts/ 三个脚本共同构成了一套「单点维护版本、CI 多架构编译、本地签名、多渠道分发」的完整工程化发布体系。按本文梳理的清单逐步执行,即可复现 Sonic 官方从 v1.0.0 到任一版本的打包发布全流程。