meijiaka-zy/docs/release-guide.md

应用发版操作手册

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

---

前置条件

1. 签名密钥（已生成，只需确认存在）

ls ~/.tauri/meijiaka.key ~/.tauri/meijiaka.key.pub

• 私钥 ~/.tauri/meijiaka.key：构建时用于签名，不要泄露
• 公钥内容：已写入 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：修改版本号

三个文件版本号必须完全一致：

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：构建

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

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 插件已内置跨平台安装逻辑，前端代码无需区分平台。

---

文件清单

文件	作用
~/.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	数据库模型（mjk_app_releases / mjk_app_release_packages）