版本發布

發布約定

只有維護者推送 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。升級部署前備份，降級需恢復符合版本的資料庫，參見 部署與升級。