升级与迁移

升级方式由目标版本的兼容性证据决定，而不是由集群节点数决定。当前文档不提供跨所有版本的混跑、降级或 v2 到 v3 原地存储迁移保证。

冻结升级契约

开始前记录：

• 当前和目标提交 SHA、制品摘要、Go/构建工具链与配置版本；
• 目标版本发布说明中对协议、Controller、Slot/Channel 元数据、存储和配置的兼容声明；
• 是否允许混跑、允许的版本跨度、升级顺序和最长混跑时间；
• 不可逆的持久化边界、降级支持和最后可安全回滚点；
• 已通过当前计划版本测试的仓库、完整验证归档和恢复演练；
• /readyz、错误、延迟、连接、队列、Controller、Slot、Channel、磁盘和业务验收基线。

任何一项未知都应选择维护窗口，或暂停升级等待版本负责人确认。

兼容性已明确时的滚动升级

1. 冻结拓扑、扩缩容、备份恢复和无关配置变更。
2. 从流量入口摘除一个非关键节点，等待连接和工作安全排空。
3. 使用目标制品和已验证配置重启该节点；不要改变节点 ID 或数据目录。
4. 等待 /readyz，确认控制版本追平、Slot/Channel 角色稳定且没有新错误或积压。
5. 发送小比例业务流量，验证收发、重连、历史消息和下游集成。
6. 一次只推进一个节点；始终遵守发布说明规定的 Controller voter 顺序与混跑时限。
7. 全部完成后继续观察一个完整业务高峰，并保存升级证据。

滚动不等于无风险。十万成员群组、高消息率和大量在线用户会放大重连、迁移和缓存预热成本，必须保留容量余量。

未声明兼容时的维护升级

1. 完成备份验证、回滚演练和业务停机通知。
2. 停止流量并确认集群进入受控维护状态，写入与下游投递已经排空。
3. 按该版本明确的停止顺序关闭节点，且不要在需要 Controller 协调的阶段同时终止所有 voters。
4. 替换所有节点制品和配置，确保版本一致后再按发布说明启动。
5. 等待全部节点、Controller 和 256 个 Slot 稳定并通过 /readyz。
6. 完成业务验收后逐步恢复流量；任何未知或错误都停止切流。

回滚边界

只有在目标二进制尚未写入旧版本无法理解的持久状态，且发布说明明确支持降级时，才能回滚二进制。配置删除或重命名、元数据编码、存储格式和控制状态都可能让简单替换二进制变得不安全。

越过不可逆边界后，不要尝试盲目降级。保持流量关闭，保存日志与状态，按版本专用恢复步骤或已演练的备份恢复处理。

v2 到 v3

当前没有通用的 v2→v3 原地存储转换契约或自动工具。不要把 v2 数据目录复制到 v3 节点，也不要把 v3 备份恢复当作新集群导入接口。

迁移必须作为独立项目：冻结业务数据语义与可接受停机，盘点用户、频道、成员、消息、设备 Token 和外部集成，定义经验证的导出/转换/校验/切换/回退方法，并用接近真实规模的数据演练。没有版本专用方案时继续运行现有系统，不执行试探性生产转换。