版本发布

发布约定

只有维护者推送 v* 标签才触发 Release 工作流，普通分支提交或 PR 不自动发布。标签使用标准版本，如 v0.1.0、v0.1.0-rc.1，应用与 Docker 标签移除前导 v。

发布产物包括 Linux amd64/arm64 归档、docker.compose.yaml、SHA256SUMS 与 GHCR 多平台镜像。版本示例仅说明格式，不表示对应版本已发布。

只有仓库最高稳定版本可以推进 Docker latest 和 GitHub latest。预发布或旧维护版本不会倒退稳定通道。部署建议固定版本或镜像摘要。

维护者流程

在开发分支生成并检查 CHANGELOG.md，合并发布相关修改并运行 make check。选择一个未使用的版本，随后在同步且干净的 main 上执行：

make publish-check TAG=v0.1.0
make publish TAG=v0.1.0

第一条仅预检查，不创建或推送标签；第二条创建并推送一个注释标签，是真正的发布触发操作。要求 main 与唯一 origin 推送地址的远端 main 一致，工作树含未跟踪文件也必须干净，重复标签会被拒绝。

发布脚本不会自动切分支、合并或推送分支。推送成功只说明工作流已触发，仍需检查 Actions 执行结果才能宣布发布完成。

工作流

1. 校验标签与镜像路径，运行正常 CI。
2. 在原生 Linux amd64/arm64 上构建并冒烟测试容器。
3. 从已测试容器提取二进制，生成归档并验证版本。
4. 生成发布说明与草稿，推送已测试镜像和多平台标签。
5. 上传归档与校验文件，满足条件时推进稳定通道，再公开发布。

工作流使用受限 GITHUB_TOKEN，不需要 Docker Hub 或个人访问令牌。首次 GHCR 包可能为私有，需要维护者检查访问设置后才能匿名拉取。

失败处理

推送失败或无法确认时，本地标签会保留，因为远端可能已接受。先检查远端标签和 Actions；确认缺失后再按脚本打印的单标签命令重试。不要移动已有发布标签或强制推送。

最高稳定版本构建失败时重跑该发布，旧版本不会替代它更新 latest。升级部署前备份，降级需恢复匹配版本的数据库，参见 部署与升级。