备份、恢复、升级与回滚

升级不是复制新文件。可靠变更必须把程序版本、配置、数据库 Schema、安全材料、MediaServer 和录像索引作为一个可恢复整体。

实际执行正式包升级时，先阅读在线升级：akn upgrade 与页面升级完整指南；本页继续说明更广的备份、恢复和回滚治理原则。

Deployment 覆盖配置的保留

页面保存的节点地址和策略可能位于 Config/akstream.next.Deployment.json，它不只是安装器可以随意重建的临时文件。安装/升级写入此文件时，旧值（包括 false、0、空字符串、null、数组和未知字段）优先保留，只补入主配置和覆盖文件都没有的新安装参数。新默认值不会再次遮蔽主配置中已经确定的托管路径、开关或 FFmpeg 参数。

托管 ZLMediaKit 的 ZLMediaKit/config.ini 同样属于运行期配置，不属于可以用发布包默认文件直接覆盖的程序文件。升级以新包文件作为结构基线并补入新增节和新增键，但旧安装中已经存在的全部键值、自定义键和自定义节保持优先；因此延迟、轨道等待、RTSP/RTP、HLS 和其他用户管理的原生调优不会因换版恢复成发布默认值。ZLMediaKit 官方配置允许同一节分段出现，安装器会按同一逻辑节合并；重复键或非法行会在停止旧服务前中止升级，避免歧义值被静默覆盖。启动后，媒体身份、Secret、Hook、安全策略、受管监听端口和 RTC 等明确由 AKStream.Next 拥有的键仍会从已经保留的 AKStream.Next 配置协调，这不属于发布包默认值覆盖。

损坏 JSON、重复字段或大小写冲突字段会在停止旧服务前拒绝。实际变化使用同目录临时文件原子替换，替换前保存 akstream.next.Deployment.json.upgrade-backup.*；若不需要新增覆盖，不会重新创建已退役的引导文件。Runtime/GC 参数仍按“新运行时结构 + 旧 configProperties 优先”的规则合并。

如果旧版本升级已导致地址丢失，先从升级事务中的 Config 备份核对旧值，再通过目标节点的配置页面恢复受影响字段；不要用整份旧配置直接覆盖新配置，也不要公开包含凭据的备份。

flowchart LR
    A[一致性备份] --> B[隔离环境恢复验证]
    B --> C[生产升级]
    C --> D{关键路径通过?}
    D -->|是| E[观察并完成]
    D -->|否| F[按预案回滚整个一致状态]

备份范围

数据库与文件需要一致时间点。仅备份索引不备份文件，或反过来，都不能完整恢复录像业务。

恢复演练

至少在隔离环境定期执行：

1. 准备与生产兼容的目标系统和数据库。
2. 恢复配置、安全目录和数据库。
3. 恢复或重新挂载录像根。
4. 使用固定旧版本启动，验证节点与 MediaServer 连接。
5. 抽查登录、设备、实时流、录像检索与下载。
6. 记录 RPO、RTO、缺失数据和人工步骤。

“备份任务成功”不等于可恢复。

升级前

• 阅读目标版本说明与已知限制。
• 核对目标操作系统/RID 包、版本和 SHA-256。
• 备份并记录恢复点。
• 检查数据库、录像扫描、裁剪和异步任务没有异常积压。
• 在预生产使用真实设备和关键用户路径回归。
• 明确停机窗口、观察期、回滚决策人和命令。

升级执行

1. 停止新增高风险任务，等待关键录像或裁剪收尾。
2. 按部署脚本顺序停止/升级服务，不直接覆盖正在使用的文件。
3. 应用数据库与配置迁移，保存迁移日志。
4. 启动后先检查健康、Schema、配置版本和节点。
5. 再验证设备、首路流、录像、RTC 和第三方集成。
6. 观察错误率、资源、协议超时和文件产出。

回滚

回滚触发条件应在升级前定义，例如核心用户路径失败、数据迁移错误、持续录像中断或无法控制的性能退化。

程序回滚必须与数据库和配置兼容。如果新版本做了不可逆数据迁移，不能只换回旧二进制；应恢复完整一致备份或执行经过验证的降级步骤。

多节点顺序

分批升级，保持协议兼容窗口。先升级验证节点，再扩大范围。已有媒体会话不保证跨节点无损迁移，操作前告知影响并选择低峰窗口。

完成标准

• 目标版本与所有组件一致，健康和配置无漂移。
• 关键用户路径通过，观察期无新增高优先级异常。
• 备份、升级日志、测试证据和实际变更已归档。
• 回滚材料在观察期结束前保留。