小鱼开发
213 lines
6.4 KiB
Markdown
213 lines
6.4 KiB
Markdown
# 应用发版操作手册
|
||
|
||
> 本文档描述美家卡智影桌面应用的完整发版流程。
|
||
> 采用 Tauri 官方 updater 插件 + FastAPI 动态更新 JSON + 七牛云存储方案。
|
||
|
||
---
|
||
|
||
## 前置条件
|
||
|
||
### 1. 签名密钥
|
||
|
||
当前使用 Tauri 自动更新签名密钥对，私钥用于构建时签名，公钥写入前端配置。
|
||
|
||
```bash
|
||
# 确认密钥对存在（私钥文件名以你本地实际为准）
|
||
ls ~/.tauri/meijiaka.key ~/.tauri/meijiaka.key.pub
|
||
```
|
||
|
||
- **私钥**：构建时用于签名更新包，**不要泄露，不要提交到 Git**
|
||
- **公钥**：内容已写入 `tauri-app/src-tauri/tauri.conf.json` 的 `plugins.updater.pubkey`
|
||
|
||
> **注意**：如果重新生成了签名密钥对，旧版本客户端将无法通过自动更新升级（旧公钥无法验证新私钥的签名），只能手动下载重装。详细说明见本文档末尾"密钥更换与手动下载"。
|
||
|
||
|
||
### 2. 七牛云环境变量（复用素材上传配置）
|
||
|
||
```bash
|
||
# python-api/.env
|
||
QINIU_ACCESS_KEY=xxx
|
||
QINIU_SECRET_KEY=xxx
|
||
QINIU_VIDEO_BUCKET=media-liche
|
||
QINIU_VIDEO_DOMAIN=media.liche.cn
|
||
```
|
||
|
||
### 3. 后端已部署
|
||
|
||
```bash
|
||
# 测试环境
|
||
cd python-api
|
||
docker compose -f docker-compose.test.yml up -d --build
|
||
|
||
# 验证
|
||
curl https://dev.tapi.meijiaka.cn/api/v1/system/health
|
||
```
|
||
|
||
> 数据库表会在 Docker 启动时自动创建（`alembic upgrade head` 已内置于容器启动命令），无需手动执行迁移。
|
||
|
||
---
|
||
|
||
## 发版流程
|
||
|
||
### 步骤 1：修改版本号
|
||
|
||
所有包含版本号的位置必须保持一致，建议统一修改后全局搜索确认：
|
||
|
||
```bash
|
||
# 项目根目录
|
||
VERSION
|
||
AGENTS.md
|
||
|
||
# 前端
|
||
tauri-app/package.json
|
||
tauri-app/src-tauri/Cargo.toml
|
||
tauri-app/src-tauri/tauri.conf.json
|
||
tauri-app/src-tauri/Cargo.lock # name = "tauri-app" 对应的 version
|
||
tauri-app/AGENTS.md
|
||
|
||
# 后端
|
||
python-api/pyproject.toml
|
||
python-api/uv.lock # name = "meijiaka-ai-api" 对应的 version
|
||
python-api/app/config.py # APP_VERSION 默认值
|
||
```
|
||
|
||
> 当前版本示例：`1.9.1`。修改后可用 `grep -R "1.9.0"` 检查是否有遗漏。
|
||
|
||
### 步骤 2：构建
|
||
|
||
```bash
|
||
cd tauri-app
|
||
export TAURI_SIGNING_PRIVATE_KEY="$HOME/.tauri/meijiaka.key"
|
||
export TAURI_SIGNING_PRIVATE_KEY_PASSWORD="" # 若私钥有密码则填写
|
||
npm run tauri build
|
||
```
|
||
|
||
构建产物（含签名文件）位于 `src-tauri/target/release/bundle/`：
|
||
|
||
| 平台 | 安装包 | 签名文件 |
|
||
|------|--------|----------|
|
||
| macOS | `macos/*.app.tar.gz` | `.app.tar.gz.sig` |
|
||
| Windows | `nsis/*-setup.exe` | `.exe.sig` |
|
||
| Linux | `appimage/*.AppImage` | `.AppImage.sig` |
|
||
|
||
> **注意**：不同平台的构建产物和签名文件是 Tauri 自动生成的。若只发 macOS 版本，只需上传 macOS 的包即可；Windows/Linux 用户不会收到更新提示。
|
||
|
||
### 步骤 3：发布
|
||
|
||
```bash
|
||
cd python-api
|
||
|
||
python scripts/publish_release.py \
|
||
--version 1.6.0 \
|
||
--notes "修复视频导出崩溃\n优化启动速度" \
|
||
--bundle-dir ../tauri-app/src-tauri/target/release/bundle
|
||
```
|
||
|
||
脚本执行逻辑：
|
||
|
||
1. 扫描 `bundle/` 目录，匹配 `.sig` 文件和对应的安装包
|
||
2. 上传安装包到七牛云 `media-liche` bucket 的 `releases/{version}/` 路径
|
||
3. 读取 `.sig` 文件内容（Ed25519 签名）
|
||
4. 调用后端 API `POST /api/v1/update/releases`，将版本信息写入数据库
|
||
|
||
> 若后端在本地 Docker（端口 8081），加 `--api-url http://localhost:8081`
|
||
|
||
---
|
||
|
||
## 验证发版
|
||
|
||
### API 验证
|
||
|
||
```bash
|
||
curl "https://dev.tapi.meijiaka.cn/api/v1/update/check?version=1.5.15&target=darwin&arch=aarch64"
|
||
```
|
||
|
||
正常返回示例：
|
||
|
||
```json
|
||
{
|
||
"version": "1.6.0",
|
||
"notes": "修复视频导出崩溃\n优化启动速度",
|
||
"pub_date": "2026-05-15T10:00:00+00:00",
|
||
"mandatory": false,
|
||
"platforms": {
|
||
"darwin-aarch64": {
|
||
"url": "https://media.liche.cn/releases/1.6.0/xxx.app.tar.gz",
|
||
"signature": "-----BEGIN SIGNATURE-----\nxxx\n-----END SIGNATURE-----"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 客户端验证
|
||
|
||
1. 启动桌面应用，3 秒后自动检查更新
|
||
2. 若当前版本低于数据库最新版本，弹出更新对话框
|
||
3. 或在**设置 → 系统更新**中手动点击"检查更新"
|
||
|
||
---
|
||
|
||
## 回滚操作
|
||
|
||
若发出去的版本有问题，删除版本记录即可：
|
||
|
||
```bash
|
||
# 测试/本地环境
|
||
docker exec meijiaka-zy-api psql $DATABASE_URL \
|
||
-c "DELETE FROM app_releases WHERE version = '1.6.0';"
|
||
|
||
# 或进入服务器直接执行
|
||
psql $DATABASE_URL -c "DELETE FROM app_releases WHERE version = '1.6.0';"
|
||
```
|
||
|
||
用户下次检查更新时会自动拿到上一个版本。
|
||
|
||
---
|
||
|
||
## 跨平台说明
|
||
|
||
| 平台 | 安装包格式 | 安装行为 | 是否需要重启 |
|
||
|------|-----------|---------|------------|
|
||
| macOS | `.app.tar.gz` | 解压替换 `.app` bundle | 是 |
|
||
| Windows | `.exe` / `.msi` | 运行安装程序替换 | 是（安装程序强制退出应用）|
|
||
| Linux | `.AppImage` | 替换可执行文件 | 是 |
|
||
|
||
Tauri updater 插件已内置跨平台安装逻辑，前端代码无需区分平台。
|
||
|
||
---
|
||
|
||
## 密钥更换与手动下载
|
||
|
||
如果签名密钥对发生更换（例如旧私钥丢失、泄露或主动轮换）：
|
||
|
||
1. **旧版本客户端无法自动更新**
|
||
- 旧客户端内置的旧公钥无法验证新私钥签名的更新包
|
||
- Tauri updater 会在签名验证阶段失败
|
||
|
||
2. **必须引导用户手动下载重装**
|
||
- 后端已提供统一下载入口：`GET /api/v1/update/download`
|
||
- 该接口根据 `User-Agent` 自动匹配最新版本和平台安装包
|
||
- 也支持显式传参：`/api/v1/update/download?target=darwin&arch=x86_64`
|
||
- 返回 **302 重定向**到对应安装包的七牛云 URL
|
||
|
||
3. **分发链接示例**
|
||
- 网页/文档固定链接：`https://dev.tapi.meijiaka.cn/api/v1/update/download`
|
||
- 应用内手动下载按钮：调用 Tauri `opener` 打开上述链接即可
|
||
|
||
4. **恢复自动更新**
|
||
- 用户手动安装新版本后，新安装包中已包含新公钥
|
||
- 后续版本可恢复正常的自动更新流程
|
||
|
||
---
|
||
|
||
## 文件清单
|
||
|
||
| 文件 | 作用 |
|
||
|------|------|
|
||
| `~/.tauri/meijiaka.key` | 私钥（签名用，勿泄露） |
|
||
| `tauri-app/.tauri-signing-key.pub` | 公钥源文件 |
|
||
| `tauri-app/src-tauri/tauri.conf.json` | updater 配置：公钥 + endpoint URL |
|
||
| `python-api/scripts/publish_release.py` | 发版脚本（扫描 .sig → 上传七牛云 → 写数据库） |
|
||
| `python-api/app/api/v1/update.py` | 后端更新检查 API + 统一下载入口 |
|
||
| `python-api/app/models/update.py` | 数据库模型（`mjk_app_releases` / `mjk_app_release_packages`） |
|