# 应用发版操作手册

> 本文档描述美家卡智影桌面应用的完整发版流程。
> 采用 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`） |
