系统升级方案

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