发布与升级说明

本页维护跨版本升级与回退流程，不复制具体版本号、发布摘要或破坏性变更正文。当前发布基线、 显著变化和 Breaking change 统一以 RELEASE_NOTES.md 为准。

发布版本基线

正式交付与验收优先使用双方确认的 Git tag；无法使用 tag 时，记录完整的 40 位 commit SHA。 分支 HEAD 会随提交移动，不能作为验收基线。源码访问申请、Git LFS 拉取、权限与许可边界统一见 源码仓库访问与授权，本页不重复权限操作细节。

发布前检查

1. 阅读 RELEASE_NOTES.md 中目标版本及从当前版本跨越的所有版本条目。
2. 确认目标 tag；无法使用 tag 时，确认并记录完整 commit SHA，禁止仅记录分支 HEAD。
3. 识别受影响的运行时 API、配置、数据库 schema、模型和部署资产。
4. 确认本次发布的服务范围与配置变更边界。
5. 在非生产环境使用目标配置完成 bun run lint、bun run typecheck 与受影响模块的构建、测试和链路验证。
6. 记录上线顺序、健康检查、观察指标、负责人、回退触发条件和回退命令。

升级前置检查

• 备份数据库，并确认 schema 变更采用的迁移或 db:push 策略。
• 保存上一可用版本的二进制、前端静态文件、配置和模型组合。
• 校验 PostgreSQL、Redis、OpenAI 兼容推理后端、FreeSWITCH 与 FFmpeg 等外部依赖。
• 校验模型文件路径、权限、磁盘空间和 SDK 运行库。
• 校验 FreeSWITCH ESL 地址、outbound 回连地址、媒体可达性和 TTS 公网 / 内网 URL。
• 从服务目录生成本次环境的监听与健康检查清单。
• 对照故障排查准备关键日志定位方式。

具体版本要求不得从本页猜测；必须回到 RELEASE_NOTES.md 的目标版本条目确认。

推荐升级顺序

除目标版本发布说明另有要求外，建议：

1. 停止新任务派发，等待活跃通话和后台任务收敛。
2. 备份数据库、配置、可执行文件和前端产物。
3. 应用数据库 schema 变更，并记录执行结果。
4. 升级 ONNX 语音服务，逐个验证健康检查和最小 ASR / TTS / Emotion 请求。
5. 升级 callflow-esl、管理 API (callflow-server) 和 callout-server（含 AI 策略中台），逐个检查健康状态和依赖日志。
6. 升级前端与反向代理静态资源。
7. 验证系统一的呼入 / 外呼、ASR、TTS 和管理配置链路。
8. 验证系统二的派发、流程脚本、结果回写、坐席软电话、转人工和后台分析链路。
9. 恢复任务派发，并在观察窗口内监控错误率、超时、队列与资源使用。

任务中临时启动的验证服务必须在结束前停止。

兼容性判断

升级评审至少逐项回答：

• API / WebSocket 请求、响应、事件或状态码是否变化？
• 配置字段、环境变量、默认值或路径解析是否变化？
• 数据库 schema 和数据语义是否变化？
• FreeSWITCH 拨号计划、通道变量、媒体格式或回连方式是否变化？
• 模型、SDK、FFmpeg 或系统运行库要求是否变化？
• 缓存、限流、重试、超时、后台任务或关闭行为是否变化？

答案与迁移动作写入 RELEASE_NOTES.md 对应版本；模块契约细节更新到对应配置、API 或协议专题。

回退原则

• 以恢复稳定业务链路为第一目标，按上线步骤逆序回退。
• 二进制、配置、数据库 schema 和数据必须作为一个兼容组合评估，不能只替换单个文件。
• 若数据库变更不可逆，先执行发布前定义的数据恢复或向前修复方案。
• 若只影响某个独立服务且契约向后兼容，可只回退该服务；否则按依赖链整体回退。
• 回退后重新执行服务健康检查和关键业务冒烟，并记录触发原因与遗留数据处理。

发布材料

• 版本事实与破坏性变更：RELEASE_NOTES.md
• 源码访问与交付基线：源码仓库访问与授权
• 部署资产提供范围：deploy/README.md
• 服务与健康检查：服务目录
• 部署步骤：部署与运行与生产部署与落地
• 文档同步规则：文档规范