系统升级方案
适用范围：客户端部署的 Windows / macOS / Linux 三平台分发包
状态：功能规划说明
一、背景
系统以压缩包形式分发到终端用户机器，用户双击各平台启动脚本即可使用，内置数据库与包管理工具。此前系统仅具备数据库结构自动迁移能力，没有代码层面的自动更新能力。
二、目标
在不破坏用户数据（数据库数据目录、上传目录、自定义配置、日志等）的前提下，为用户提供自动更新能力：
- 可检查新版本 —— 后台界面查看、用户点击升级
- 下载可靠 —— 网络不稳定也能完成下载（支持断点续传）
- 升级失败可恢复 —— 升级异常时系统按内部机制处理，尽量回到可用状态
- 发布可控 —— 支持分批发布与快速下线问题版本（能力概述，具体策略见发布流程）
核心约束（已与用户确认）：
- 用户是普通终端用户（点启动脚本即用），不能要求安装额外工具
- 二进制锁定（内置数据库 / 音视频处理工具 / 包管理工具不跟随升级），仅升级 Python 代码 / 前端 / SQL / 模板
- 复用公开代码托管平台作为分发渠道
- 三平台行为一致
三、总体设计（概述）
系统支持自动更新，整体流程概述如下：
- 检查更新：客户端从版本清单（托管平台仓库内，多源地址按顺序尝试）异步获取最新版本信息；
- 下载升级包：HTTP 下载发布包，支持断点续传与多源切换；
- 应用升级：由独立的更新进程（与主程序隔离，规避运行中文件被占用的问题）在旧版本退出后替换代码文件；用户数据、配置、内置二进制始终不被覆盖（升级保护路径白名单）；
- 数据库迁移：新版本启动时自动执行数据库迁移脚本；
- 健康检查：新版本启动后做健康检查，异常时由系统内部机制处理；
- 升级管控：版本清单由维护者管理，支持通道划分、强制升级标记、版本下线等发布策略（内部机制，此处不展开）。
关键设计点：
- 更新进程独立于主程序目录运行（规避操作系统文件占用问题）；
- 升级全程状态可查询（后台提供实时状态查看）；
- 升级日志落库，可追溯每次升级的版本、结果与操作人；
- 全程遵循非阻塞规则（异步下载、异步状态推送）。
四、用户数据保护
升级过程完全不动的路径（白名单，示意）：
# 用户配置
config_*.yml / 自定义配置文件
# 用户数据
data/（数据库数据）、upload/（上传文件）、files/、logs/
# 内置二进制（版本锁定，不更新）
bin/
# 本地特殊文件
*.local.json、.env
# 用户二开覆盖目录（可选）
custom_overrides/
用户若自定义了 custom_overrides/ 目录，升级后系统会按原项目相对路径自动复制覆盖到对应位置，支持二次开发覆盖。
五、升级入口与界面
- 管理后台提供升级管理页：查看当前版本 / 最新版本、更新内容、开始升级、实时进度（阶段 + 进度条 + 日志）、备份管理、升级历史；
- 升级前对大版本升级展示备份提示，需用户确认已备份重要数据；
- 状态推送优先采用 SSE，轮询兜底。
六、配置项（概述）
升级能力通过集中配置管理（config/constant.py 与统一配置），主要配置项（详见配置文件）：
- 升级总开关、检查间隔、是否自动下载；
- 版本清单地址（多源，按顺序 fallback）；
- 通道选择、是否允许降级、失败时是否自动恢复旧版；
- 备份保留数量、健康检查超时等。
七、发布流程（给维护者，概述）
- 开发完成、测试通过后更新版本号；
- 打标签发布，由托管平台自动生成发布包；
- 维护者更新仓库内版本清单（含发布元数据、多源下载地址、完整性信息），必要时先行小范围通道验证，再全量；
- 发现问题版本时，可在版本清单中标记下线并回退推荐版本，客户端下次检查更新即生效；
- 发布工具与密钥由维护者妥善保管（不入库）。
八、测试计划（概述）
- 基础场景：无网络 / 无新版本 / 有新版本 / 用户取消 / 磁盘不足 / 下载中断续传；
- 异常恢复：升级中断（进程被杀 / 断电）后重启，系统能识别未完成升级并按内部机制恢复；
- 回退验证：升级失败（含数据库迁移失败）时的恢复路径；
- 跨平台：Windows / macOS / Linux 分别验证，含中文用户名路径；
- 并发：重复触发升级请求应被拒绝。
九、风险与注意事项
- 发布前必须充分测试；大版本升级建议在更新说明中强提示用户先备份；
- 数据库迁移为破坏性变更时需特别谨慎，升级前要求用户确认备份；
- 用户本地修改过被跟踪文件时升级会按保护策略处理，建议重要自定义内容放入二开覆盖目录；
- 二进制（数据库 / 音视频工具 / 包管理工具）不参与升级，其大版本升级走独立渠道（后续规划）。
十、后续可扩展
- 增量更新（只下载变化部分）；
- 内置二进制独立更新通道；
- 内网分发（局域网互相同步升级包）；
- 多语言更新说明；
- 升级失败脱敏上报，便于发布方排查。