XHIM SDK 与 Server 升级、灰度和回滚指南

适用阶段：0.1 Commercial Beta

本文面向 SDK 发行人员和服务端运维人员。App 业务开发者只需要按各平台 QuickStart 更新已签名 SDK 包，不应直接迁移 SQLite 或执行服务端数据库命令。

1. 升级前必须确认

同一次发布必须绑定以下身份：

text

产品：XHIM
产品版本：SemVer
Git Commit：完整对象 ID
C ABI generation：xhim_v1
Wire/SQLite Schema：制品内声明值
五端制品 Hash：签名 release/evidence manifest

发布人员先阅读 Changelog、兼容性策略和发布清单。以下任一条件不满足时停止发布：

Tag、Commit、包内版本或证据清单不一致；
ABI export、Protobuf 字段或 SQLite 冻结 fixture 检查失败；
目标平台不在本次签名真机矩阵中；
Server N/N-1 兼容测试、数据库备份校验或恢复演练未完成；
法务、SBOM、安全、容量或设备证据缺失。

2. 客户端升级顺序

在空白消费工程安装最终签名包，不引用仓库源码或本机构建目录；
校验运行时 ABI、SDK 版本和包 Hash；
使用测试账号验证登录、初始同步、时间线、发送、媒体、Push 和退出；
使用旧版本创建真实形态的加密账号数据库并正常关闭 Client；
复制完整测试 Profile 到可恢复测试环境，再由新内核执行一次性迁移；
验证历史消息、会话、草稿、社交投影、待发送 Outbox 和媒体任务；
先灰度内部账号，再灰度小比例客户，最后扩大范围。

升级前必须停止并销毁旧 Client。禁止两个内核版本同时打开同一账号数据库，禁止业务代码修改表结构、PRAGMA user_version、Cursor 或内部 ID。

3. Server 滚动升级顺序

推荐顺序：

text

验证备份与恢复演练
  → 部署兼容的新 Server
  → 保持 N/N-1 客户端窗口
  → 观察错误率、延迟、连接和积压
  → 灰度新客户端
  → 达到约定保留期后再停用旧协议能力

数据库迁移只能由单一受控迁移任务执行。应用实例先确认目标 Schema 已就绪，再逐批替换；不要让每个副本并发执行不受控 DDL。Endpoint/JWT 密钥使用重叠信任环轮换，先发布新公钥，再切换签发，最后在最长 Token/Endpoint 有效期和灰度窗口之后退役旧公钥。

4. 回滚边界

应用二进制回滚和数据库回滚是两件事：

如果新 Server 尚未写入旧版本不理解的数据，并且 N-1 合同测试通过，可以回滚应用实例；
已执行的前向数据库迁移默认不做破坏性逆迁移。先修复前向版本，或恢复到独立数据库并经过数据损失评估后再切换；
客户端数据库一旦由新 Schema 打开，不保证旧 SDK 能重新打开；
不允许通过降低 user_version、删列、清空 Outbox/媒体任务或覆盖数据库来伪造回滚成功；
发生安全事件时优先撤销凭证、隔离流量和停止发布，不要在未知数据状态下自动执行破坏性恢复。

5. 灰度观察项

至少观察：

登录成功率、CredentialRequired/Fatal 比例和 Endpoint 验签失败；
WSS 活跃连接、断线重连、Sync 延迟和 Cursor/协议错误；
Outbox/Push/媒体待处理量、重试、永久失败和审核等待时间；
PostgreSQL 连接池、锁等待、错误率、p95/p99 和磁盘增长；
App 崩溃、数据库打开/迁移错误、后台恢复和升级后历史数据一致性。

触发约定阈值时停止扩大灰度。回滚决定、操作者、时间、证据链接和数据影响必须进入审计记录。

6. 证据留存

一次可审计升级至少保留：

发布与证据 manifest 及其签名；
备份 Hash、校验结果和隔离环境恢复演练记录；
N/N-1 客户端/Server 兼容报告；
数据库迁移前后 Schema 与核心业务计数；
灰度时间线、监控链接、告警、回滚或放量审批；
最终五端包与真机结果。

服务端备份/恢复命令和限制见 XHIM Server 文档，发布门禁见商业发布证据。