发布与升级

要运营自己的部署，请从已发布的版本装起；贡献代码则提交到 dev。本页讲怎样确认当前运行的是哪个版本、怎样规划升级；初次安装见安装，服务操作命令见部署。

版本标识与支持

每个版本都是一个 GitHub release，tag 用 UTC 日期，格式为 YYYYMMDD；同一天再发布的版本依次加上 .1、.2，以此类推。它们是按日期标记的快照，不是语义化版本那样的兼容性承诺。维护者发版时把 main 推进到 dev 上的某个 commit，随后 Release 工作流会发布一个带自动生成变更说明的 release。

标识

说明

已发布的日期 tag

带有 GitHub 发布说明的固定源码快照

main

维护者每次发版时推进到 dev 的分支，会随时间变化

dev 或功能分支

开发中的代码，可能比最新的发布版本还新

完整 commit SHA

确切的源码版本；本地改动需另行说明

镜像摘要，image@sha256:…

确切的容器产物，可能和宿主机上检出的代码不一致

CI 会把后端和控制台的候选镜像打上 dev-<full-sha> tag，并附带短 SHA 别名。候选 tag 只说明这是开发产物，不代表这个 commit 有对应的日期版本。pyproject.toml 和 apps/frontend/package.json 里的 0.1.0 只是包元数据，看不出实际部署的是哪个构建。

报告问题时，尽量针对最新的发布版本。修复一般先合入 dev，再随后续版本发布。项目没有文档约定的 LTS 分支，不保证 backport 的时间窗口，也不承诺响应时间；不要以为旧版本会自动拿到修复。旧版本上的问题报告同样有用：请写明确切的版本，并说明最新发布版本是否也有这个问题。安全问题请按安全政策报告。

在 bug 报告中附上版本

从源码安装的，请在构建或启动服务所用的代码目录里运行：

git rev-parse HEAD
git describe --tags --exact-match HEAD
git status --short

HEAD 不正好在某个 tag 上时，第二条命令会报错，这时报告 SHA 即可。有本地改动请说明，但不要贴出密钥或私有配置。

用标准 Compose 栈部署的，查看正在运行的产物：

docker inspect --format '{{.Name}} image={{.Config.Image}} id={{.Image}}' \
  hybridinference-backend hybridinference-frontend

如果部署使用不同的容器名，请替换为实际名称。附上部署配置中固定使用的镜像摘要。构建时提供 SHA 后，控制台页脚也会显示该值；build dev / local build 表示未提供对应元数据。页脚标识的是控制台构建版本，因此前后端独立部署时，还需另行报告后端版本。

兼容性与破坏性变更

阅读当前安装版本到目标版本之间每次发布的说明及关联 PR。日期 tag 本身不能证明兼容性，OpenAI 兼容 API 也不意味着支持所有 provider 扩展。检查你的客户端实际使用的端点、流式行为和模型配置。

修改 HTTP 契约、认证、环境变量或 YAML 配置项、默认值或数据库 schema 时，贡献者应在 PR 中说明前后行为。写清楚哪些使用者需要采取行动，给出配置或迁移步骤，并说明旧版本是否还能使用变更后的数据。在 PR 和发布说明中明确标记破坏性变更；自动生成的 commit 摘要不足以说明运维人员应如何升级。

升级与回滚

  1. 记下当前和目标的 release/commit、后端和控制台的镜像标识，以及正在生效的发行版和配置。保留旧的产物，这样回滚时不必重新构建。

  2. 阅读目标版本的配置要求。保留部署现有的 .env、overlay 和密钥，把必需的改动合并进去，不要用新的示例文件整个替换掉。JWT_SECRET_KEY、API_KEY_SECRET 和 ERASURE_FENCE_SECRET 在所有副本之间、升级前后都要保持不变。改了第一个，访问 token 会失效；改了第二个，现有 API key 的哈希就无法验证；改了第三个（或者在它留空时顶替它的第二个），后端就无法启动。不要把升级当成轮换密钥的机会。

  3. 备份每个已配置的数据库，并确认备份可恢复到独立数据库。妥善保存配套的配置和密钥副本。标准 Postgres 命令见数据库备份；其他部署请采用存储服务商的备份流程。

  4. 先在隔离的本地或 staging 部署上演练，用独立的存储和合适的测试数据。应用启动时会创建和更新 schema，所以只要让新后端连上某个数据库启动一次，就可能改动它。检查启动日志和 /health/ready，然后验证登录、一个现有的 API key、一次经过路由的请求；客户端用到流式的话，也验证流式请求。

  5. 用你现有的部署方式部署选定的版本。从源码构建的标准栈里，make build 会用当前检出的代码重新构建镜像并重建服务；make restart 则沿用现有镜像。重新构建代码和重新加载配置有什么区别，见部署。放正常流量进来之前，先核对正在运行的产物标识，再把演练时的检查重做一遍。

切回旧镜像不会撤销数据库变更。如果旧版本与升级后的 schema 和数据兼容，可以恢复配套的应用产物和配置。否则，应先停止应用写入，恢复配套的升级前数据库备份，再启动旧版本。这会丢弃备份之后的写入，因此恢复计划必须考虑这些数据。目前没有通用的自动 schema 降级命令；make down 会保留数据，删除 volume 是重置而非回滚。