docs: add portable update architecture guide
This commit is contained in:
Misaka
274
docs/portable-auto-update-architecture.md
Normal file
274
docs/portable-auto-update-architecture.md
Normal file
@@ -0,0 +1,274 @@
|
||||
# ERPAuto 便携版自动更新说明
|
||||
|
||||
## 概览
|
||||
|
||||
当前实现的是一套面向 Windows 便携版的自定义更新系统，核心特点如下：
|
||||
|
||||
- 基于 S3 兼容对象存储分发更新包
|
||||
- 按登录用户角色决定更新通道和行为
|
||||
- `User` 只跟随 `Stable`
|
||||
- `Admin` 同时可见 `Stable` 和 `Preview`
|
||||
- 更新包可后台下载，但安装必须由用户触发
|
||||
- 安装阶段使用独立的原生 `portable-updater.exe` 完成 exe 替换
|
||||
|
||||
## 核心组件
|
||||
|
||||
- 主进程更新服务
|
||||
路径：[`src/main/services/update/update-service.ts`](/d:/FileLib/Projects/CodeMigration/ERPAuto/src/main/services/update/update-service.ts)
|
||||
- 更新规则工具
|
||||
路径：[`src/main/services/update/update-utils.ts`](/d:/FileLib/Projects/CodeMigration/ERPAuto/src/main/services/update/update-utils.ts)
|
||||
- 更新 IPC
|
||||
路径：[`src/main/ipc/update-handler.ts`](/d:/FileLib/Projects/CodeMigration/ERPAuto/src/main/ipc/update-handler.ts)
|
||||
- 前端更新弹窗
|
||||
路径：[`src/renderer/src/components/UpdateDialog.tsx`](/d:/FileLib/Projects/CodeMigration/ERPAuto/src/renderer/src/components/UpdateDialog.tsx)
|
||||
- 前端更新入口
|
||||
路径：[`src/renderer/src/App.tsx`](/d:/FileLib/Projects/CodeMigration/ERPAuto/src/renderer/src/App.tsx)
|
||||
- 原生更新器
|
||||
路径：[`build/PortableUpdater.cs`](/d:/FileLib/Projects/CodeMigration/ERPAuto/build/PortableUpdater.cs)
|
||||
- 更新器编译脚本
|
||||
路径：[`scripts/compile-updater.js`](/d:/FileLib/Projects/CodeMigration/ERPAuto/scripts/compile-updater.js)
|
||||
- 发布准备脚本
|
||||
路径：[`scripts/prepare-release.js`](/d:/FileLib/Projects/CodeMigration/ERPAuto/scripts/prepare-release.js)
|
||||
- 发布上传脚本
|
||||
路径：[`scripts/upload-release.js`](/d:/FileLib/Projects/CodeMigration/ERPAuto/scripts/upload-release.js)
|
||||
|
||||
## 角色策略
|
||||
|
||||
### `User`
|
||||
|
||||
- 只读取 `stable/index.json`
|
||||
- 目标版本永远是最新 `Stable`
|
||||
- 如果当前客户端是 `Preview`，即使本地版本号更高，也会被视为“需要更新回稳定版”
|
||||
- 后台会自动下载推荐的 `Stable`
|
||||
- 用户点击后执行安装
|
||||
|
||||
### `Admin`
|
||||
|
||||
- 同时读取 `stable/index.json` 和 `preview/index.json`
|
||||
- 不自动下载
|
||||
- 只展示可选版本和更新说明
|
||||
- 由管理员手动选择版本并触发下载、安装
|
||||
|
||||
## 当前安装包身份
|
||||
|
||||
构建时会注入 `__APP_CHANNEL__`，用于标识当前客户端自身是 `stable` 还是 `preview`。
|
||||
|
||||
这个值的作用非常关键：
|
||||
|
||||
- 决定 `User` 是否需要从 `Preview` 洗回 `Stable`
|
||||
- 决定 `Admin` 当前处于哪条版本线
|
||||
- 决定更新弹窗中当前通道的展示
|
||||
|
||||
相关声明：
|
||||
|
||||
- [`src/shared/app-env.d.ts`](/d:/FileLib/Projects/CodeMigration/ERPAuto/src/shared/app-env.d.ts)
|
||||
- [`src/renderer/src/env.d.ts`](/d:/FileLib/Projects/CodeMigration/ERPAuto/src/renderer/src/env.d.ts)
|
||||
|
||||
## 远端目录结构
|
||||
|
||||
更新目录按通道分开：
|
||||
|
||||
```text
|
||||
updates/win-portable/stable/index.json
|
||||
updates/win-portable/stable/artifacts/erpauto-<version>-stable-portable.exe
|
||||
updates/win-portable/stable/changelogs/<version>.md
|
||||
|
||||
updates/win-portable/preview/index.json
|
||||
updates/win-portable/preview/artifacts/erpauto-<version>-preview-portable.exe
|
||||
updates/win-portable/preview/changelogs/<version>.md
|
||||
```
|
||||
|
||||
`index.json` 的每个条目至少包含：
|
||||
|
||||
- `version`
|
||||
- `channel`
|
||||
- `artifactKey`
|
||||
- `sha256`
|
||||
- `size`
|
||||
- `publishedAt`
|
||||
- `changelogKey`
|
||||
- `notesSummary`
|
||||
|
||||
## 总体架构图
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
A[Electron Renderer] -->|IPC| B[Update Handler]
|
||||
B --> C[Update Service]
|
||||
C --> D[S3-Compatible Object Storage]
|
||||
C --> E[Local Cache<br/>pending-update]
|
||||
C --> F[portable-updater.exe]
|
||||
F --> G[Replace Old EXE]
|
||||
G --> H[Launch New EXE]
|
||||
```
|
||||
|
||||
## 登录后的更新时序
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant U as User/Admin
|
||||
participant R as Renderer
|
||||
participant A as Auth Handler
|
||||
participant S as Update Service
|
||||
participant O as Object Storage
|
||||
|
||||
U->>R: 登录 / 无感登录
|
||||
R->>A: auth.login / auth.silentLogin
|
||||
A->>S: setUserContext(userType)
|
||||
S->>O: 读取 stable/index.json
|
||||
alt Admin
|
||||
S->>O: 读取 preview/index.json
|
||||
end
|
||||
S->>S: 计算推荐版本与状态
|
||||
alt User 且需要更新
|
||||
S->>O: 下载最新 Stable
|
||||
S->>S: 校验 sha256
|
||||
S-->>R: UPDATE_STATUS_CHANGED(downloaded)
|
||||
else Admin
|
||||
S-->>R: UPDATE_STATUS_CHANGED(available)
|
||||
end
|
||||
```
|
||||
|
||||
## `User` 更新决策图
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[当前用户是 User] --> B[读取 stable 最新版本]
|
||||
B --> C{当前通道是 preview?}
|
||||
C -- 是 --> D[强制推荐回 Stable]
|
||||
C -- 否 --> E{当前版本 != 最新 Stable?}
|
||||
E -- 是 --> F[推荐最新 Stable]
|
||||
E -- 否 --> G[不提示更新]
|
||||
D --> H[后台自动下载]
|
||||
F --> H
|
||||
H --> I[校验 sha256]
|
||||
I --> J[导航栏显示 立即更新]
|
||||
```
|
||||
|
||||
## `Admin` 更新决策图
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[当前用户是 Admin] --> B[读取 stable 目录]
|
||||
A --> C[读取 preview 目录]
|
||||
B --> D[合并目录]
|
||||
C --> D
|
||||
D --> E{是否存在更高版本?}
|
||||
E -- 是 --> F[推荐更高版本]
|
||||
E -- 否 --> G{是否存在跨通道可切换版本?}
|
||||
G -- 是 --> H[推荐跨通道版本]
|
||||
G -- 否 --> I[不展示更新]
|
||||
F --> J[打开弹窗后手动下载]
|
||||
H --> J
|
||||
```
|
||||
|
||||
## 安装阶段时序
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant R as Renderer
|
||||
participant S as Update Service
|
||||
participant P as portable-updater.exe
|
||||
participant X as Current Portable EXE
|
||||
participant N as New Downloaded EXE
|
||||
|
||||
R->>S: installDownloaded()
|
||||
S->>P: 启动 portable-updater.exe
|
||||
S->>X: app.quit()
|
||||
P->>X: 等待旧进程退出
|
||||
P->>X: 等待文件解锁
|
||||
P->>X: 备份为 .bak
|
||||
P->>N: 移动到目标路径
|
||||
P->>X: 启动新版本
|
||||
P->>X: 删除 .bak
|
||||
```
|
||||
|
||||
## 本地目录与日志
|
||||
|
||||
### 下载缓存
|
||||
|
||||
```text
|
||||
%APPDATA%\erpauto\pending-update\
|
||||
```
|
||||
|
||||
### 更新器运行文件与日志
|
||||
|
||||
```text
|
||||
%APPDATA%\erpauto\updates\
|
||||
portable-updater.exe
|
||||
portable-update.log
|
||||
portable-launch.log
|
||||
```
|
||||
|
||||
## 发布流程
|
||||
|
||||
### 1. 构建
|
||||
|
||||
```powershell
|
||||
$env:APP_CHANNEL="stable"
|
||||
npm run build:win
|
||||
```
|
||||
|
||||
### 2. 准备发布目录
|
||||
|
||||
```powershell
|
||||
node scripts/prepare-release.js --channel stable --changelog docs/releases/1.3.2-rebuild.md
|
||||
```
|
||||
|
||||
### 3. 上传到对象存储
|
||||
|
||||
```powershell
|
||||
npm run release:upload -- --channel stable --verify
|
||||
```
|
||||
|
||||
## 发布流程图
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[build:win] --> B[生成 dist/erpauto-portable.exe]
|
||||
B --> C[prepare-release]
|
||||
C --> D[复制 artifact]
|
||||
C --> E[复制 changelog]
|
||||
C --> F[生成 index.json]
|
||||
F --> G[release-upload]
|
||||
G --> H[上传到对象存储]
|
||||
H --> I[verify 远端 index.json]
|
||||
```
|
||||
|
||||
## 版本排序规则
|
||||
|
||||
为了避免“后发布低版本覆盖高版本”的问题，当前排序规则是：
|
||||
|
||||
- 优先按版本号降序
|
||||
- 同版本再按 `publishedAt` 降序
|
||||
|
||||
这条规则同时存在于：
|
||||
|
||||
- [`src/main/services/update/update-utils.ts`](/d:/FileLib/Projects/CodeMigration/ERPAuto/src/main/services/update/update-utils.ts)
|
||||
- [`scripts/prepare-release.js`](/d:/FileLib/Projects/CodeMigration/ERPAuto/scripts/prepare-release.js)
|
||||
|
||||
## 失败保护
|
||||
|
||||
当前实现包含这些基本保护：
|
||||
|
||||
- 缺失 `preview/index.json` 时，按空列表处理，不中断整体更新检查
|
||||
- 更新包下载完成后必须校验 `sha256`
|
||||
- `portable-updater.exe` 会等待旧进程退出和目标文件解锁
|
||||
- 替换前先备份旧 exe 为 `.bak`
|
||||
- 替换失败时尝试回滚
|
||||
|
||||
## 当前已验证通过的能力
|
||||
|
||||
- `1.3.1 -> 1.3.2` 的 `Stable` 发布链路已打通
|
||||
- 新分支实现能够成功构建 Windows 便携版
|
||||
- 原生 `portable-updater.exe` 能成功编译并被打包带入资源目录
|
||||
- 本地发布目录生成正常
|
||||
- 上传脚本可将更新包和索引发布到对象存储
|
||||
- 客户端真实升级流程已验证通过
|
||||
|
||||
## 后续可继续优化的点
|
||||
|
||||
- 将 `UpdateService` 进一步拆分，降低文件复杂度
|
||||
- 将日志策略区分成“正式日志”和“诊断日志”
|
||||
- 增加更多针对下载与安装阶段的单测
|
||||
- 将完整构建发布链路整理为一键化脚本
|
||||
Reference in New Issue
Block a user