meijiaka-zy/docs/release-guide.md

应用发版操作手册

本文档描述美家卡智影桌面应用的完整发版流程。 采用 Tauri 官方 updater 插件 + FastAPI 动态更新 JSON + 七牛云存储方案。

---

前置条件

1. 签名密钥

当前使用 Tauri 自动更新签名密钥对，私钥用于构建时签名，公钥写入前端配置。

# 确认密钥对存在（私钥文件名以你本地实际为准）
ls ~/.tauri/meijiaka.key ~/.tauri/meijiaka.key.pub

• 私钥：构建时用于签名更新包，不要泄露，不要提交到 Git
• 公钥：内容已写入 tauri-app/src-tauri/tauri.conf.json 的 plugins.updater.pubkey

注意：如果重新生成了签名密钥对，旧版本客户端将无法通过自动更新升级（旧公钥无法验证新私钥的签名），只能手动下载重装。详细说明见本文档末尾"密钥更换与手动下载"。

2. 七牛云环境变量（复用素材上传配置）

# python-api/.env
QINIU_ACCESS_KEY=xxx
QINIU_SECRET_KEY=xxx
QINIU_VIDEO_BUCKET=media-liche
QINIU_VIDEO_DOMAIN=media.liche.cn

3. 后端已部署

# 测试环境
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：修改版本号

所有包含版本号的位置必须保持一致，建议统一修改后全局搜索确认：

# 项目根目录
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：构建

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：发布

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 验证

curl "https://dev.tapi.meijiaka.cn/api/v1/update/check?version=1.5.15&target=darwin&arch=aarch64"

正常返回示例：

{
  "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. 或在设置 → 系统更新中手动点击"检查更新"

---

回滚操作

若发出去的版本有问题，删除版本记录即可：

# 测试/本地环境
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）