From d71cfb8449210d3403b226b3ca5ffc9f0a04bd51 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=B0=8F=E9=B1=BC=E5=BC=80=E5=8F=91?= <git@xiaoyu.com>
Date: Fri, 15 May 2026 17:17:14 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=96=B0=E5=A2=9E=E5=BA=94=E7=94=A8?=
 =?UTF-8?q?=E5=8F=91=E7=89=88=E6=93=8D=E4=BD=9C=E6=89=8B=E5=86=8C?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/release-guide.md | 173 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 173 insertions(+)
 create mode 100644 docs/release-guide.md

diff --git a/docs/release-guide.md b/docs/release-guide.md
new file mode 100644
index 0000000..6e4a0db
--- /dev/null
+++ b/docs/release-guide.md
@@ -0,0 +1,173 @@
+# 应用发版操作手册
+
+> 本文档描述美家卡智影桌面应用的完整发版流程。
+> 采用 Tauri 官方 updater 插件 + FastAPI 动态更新 JSON + 七牛云存储方案。
+
+---
+
+## 前置条件
+
+### 1. 签名密钥（已生成，只需确认存在）
+
+```bash
+ls ~/.tauri/meijiaka.key ~/.tauri/meijiaka.key.pub
+```
+
+- 私钥 `~/.tauri/meijiaka.key`：构建时用于签名，**不要泄露**
+- 公钥内容：已写入 `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
+cd tauri-app
+
+# 1. package.json
+npm version 1.6.0 --no-git-tag-version
+
+# 2. Cargo.toml
+# 手动修改：src-tauri/Cargo.toml → version = "1.6.0"
+
+# 3. tauri.conf.json
+# 手动修改：src-tauri/tauri.conf.json → "version": "1.6.0"
+```
+
+### 步骤 2：构建
+
+```bash
+cd tauri-app
+export TAURI_SIGNING_PRIVATE_KEY="$HOME/.tauri/meijiaka.key"
+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 插件已内置跨平台安装逻辑，前端代码无需区分平台。
+
+---
+
+## 文件清单
+
+| 文件 | 作用 |
+|------|------|
+| `~/.tauri/meijiaka.key` | 私钥（签名用，勿泄露） |
+| `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` | 数据库模型（`app_releases` / `release_packages`） |