跳到主要内容

版本发布与预发布渠道

Canopy 如何对版本进行编号、打标签并发布容器镜像。本页是需要在生产环境中固定版本的运营者以及负责发布的维护者的参考文档。

版本编号​

Canopy 遵循语义化版本控制。当前版本的唯一可信来源是仓库根目录的 /VERSION 文件。

  • 补丁（例如 1.0.0 → 1.0.1）：仅错误修复。始终可以安全升级。
  • 次要（例如 1.0.0 → 1.1.0）：新功能。根据兼容性政策向后兼容。
  • 主要（例如 1.x → 2.0.0）：破坏性更改。迁移说明随版本一同发布。

版本号在每个 PR 中只升级一次，而非每次提交。PR 的 CHANGELOG 条目以新版本为标题；CI 的 version-check.yml 会拒绝任何在没有 CHANGELOG.md 中对应 ## [<version>] 标题的情况下升级 VERSION 的 PR。

容器镜像标签​

每次向 main 的推送和每个 v*.*.* 标签都会触发 .github/workflows/docker-publish.yml，该工作流会构建并推送多架构（amd64 + arm64）镜像到 GHCR。

对于 v1.2.3 这样的发布标签，每个镜像上发布的标签为：

标签指向稳定？
1.2.3恰好该版本是——在生产中固定此版本
1.21.2.x 上的最新补丁随补丁向前滚动
11.x 上的最新次要版本随次要版本向前滚动
latest最新非预发布版本随每次发布向前滚动
sha-<short>精确提交是——调试/预发布

对于向 main 的推送（无标签），仅生成 main 和 sha-<short> 标签——永远不生成 latest，也不生成任何 semver 标签。

所有已发布的镜像清单均使用 cosign 无密钥 OIDC 签名。验证和 SBOM 详细信息请参阅供应链。

预发布渠道​

对于更改容器布局、基础镜像、默认 UID、卷名、默认端口或架构且需要运营者操作的次要版本，在最终标签之前会发布一个发布候选版。

约定：

  • RC 标签为 vX.Y.0-rc.N——从不用于补丁版本，仅用于有运营者可见更改的次要版本。
  • 发布工作流的 docker/metadata-action 配置了 flavor: latest=auto。这会自动将预发布 semver 标签从 :latest、:X.Y 和 :X 中排除——RC 仅作为 :X.Y.0-rc.N 发布。固定到 :latest 的运营者不会意外拉取 RC。
  • RC 标签的 GitHub Release 应在 Releases 页面中标记为预发布。当前的 github-release.yml 工作流始终创建非预发布版本；维护者在工作流运行后手动切换预发布开关（或通过 gh release edit vX.Y.0-rc.N --prerelease 编辑版本）。

等待时间：

  • RC 在推广之前至少等待 48–72 小时，或者至少有一位维护者以外的运营者报告成功升级——以较长者为准。
  • 如果针对 RC 的错误报告值得修复，则以 vX.Y.0-rc.N+1 的形式发布。之前的 RC 保留在 GHCR 中以便重现。

推广到最终版本：

  • 最终 vX.Y.0 标签在与最后一个 RC 相同的提交上创建。发布工作流会重新构建并重新标记多架构镜像；即使源代码相同，摘要也会与 RC 不同（构建输入包含时间戳）。
  • 此时 :X.Y、:X 和 :latest 标签移动以指向最终版本。

发布流程（维护者清单）​

对于普通补丁或次要版本——无需 RC 渠道：

  1. 在功能分支上，升级 VERSION 并在 CHANGELOG.md 中添加对应的 ## [<version>] - YYYY-MM-DD 标题。
  2. 如果任何后端路由或架构发生更改，运行 python scripts/dump_openapi.py；如果结果发生变化则提交。
  3. 打开 PR。CI 运行代码检查、测试、OpenAPI 偏差检查和 version-check.yml。
  4. 压缩合并到 main。
  5. 从 main：git tag -s v<version> -m "v<version>"（或 git tag v<version>，如果未配置签名密钥），git push origin v<version>。
  6. Publish GitHub Release 工作流从 CHANGELOG.md 提取 ## [<version>] 节并创建 GitHub Release。
  7. Publish Docker images to GHCR 工作流构建、签名并发布多架构镜像。
  8. 使用 cosign 验证： 
    cosign verify \
      --certificate-identity-regexp 'https://github.com/Rhizo-Tech/canopy/.+' \
      --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
      ghcr.io/rhizo-tech/canopy/backend:<version>

对于需要 RC 的次要版本：

  1. 与上述相同的 PR-和-合并流程，但升级到 1.Y.0-rc.1。
  2. 合并后，打上 v1.Y.0-rc.1 标签并推送。发布工作流构建并推送 RC 镜像（仅 :1.Y.0-rc.1，永远不是 :latest 或短标签——flavor: latest=auto 处理这一点）。发布工作流创建 GitHub Release；之后通过 gh release edit v1.Y.0-rc.1 --prerelease 或在 GitHub 界面中手动切换为预发布。
  3. 等待等待窗口。根据需要使用 -rc.2、-rc.3 处理任何报告的问题。
  4. 推广：在最终 PR 中将 VERSION 升级到 1.Y.0（CHANGELOG 条目整合所有 RC 修复），合并，打上 v1.Y.0 标签，推送。:latest 和短标签现在指向已推广的版本。

生命周期终止​

只有最新的次要版本线接收安全修复。完整政策请参阅 SECURITY.md。较旧的次要版本线已到达生命周期终止，不会接收向后移植——使用旧版本的运营者应按照兼容性政策规划升级。