升级与回滚

全新安装用由迁移链生成的安装脚本，当前基线为 0000_foundation、0001_tables、0002_guards（应用版本 1–3）。后续发布从 0003 起新增前向迁移，使用同一迁移运行器；没有回滚迁移。

升级前复制标题链接

完成备份与恢复演练。在最近备份的副本上应用同一版本迁移，记录耗时和锁影响。读取当前构建 packages/db/src/schema-version.ts 的 APP_SCHEMA 与 APP_SCHEMA_REQUIRED，以及数据库迁移状态；不要把文档中的固定版本当作实时值。

bun run --cwd packages/db migrate status
bun run --cwd packages/db migrate up --dry-run
bun run --cwd packages/db migrate up

迁移必须直连数据库，以迁移角色执行。迁移文件不可修改，校验和不符时停止调查。expand 迁移增加兼容结构；提高 min_app_schema 的 contract 迁移需要显式 --contract，应等旧应用全部退出且回滚窗口结束后再执行。

回滚应用复制标题链接

schema 在旧构建兼容窗口内时，优先部署上一个 Worker version 或自托管构建，再验证 /readyz 与业务烟测。可用 wrangler versions deploy 选择已记录的旧版本；确认该命令针对正确应用和环境。回滚不会撤销已经发生的付款、发信或其他外部事实。

修正数据库结构复制标题链接

迁移只向前，不提供 down 命令。迁移失败时当前事务回滚、部署停止；结构或数据问题通过新的前向迁移修正。需要恢复数据时按备份与恢复从备份或 PITR 恢复，不能把结构回退当作数据恢复。

发布后检查 /healthz、/readyz、Cron 积压、节点配置收敛、订阅分发与测试付款；保留构建、schema、Worker version、OpenAPI 校验和及烟测结果。

已发布镜像复制标题链接

Conventional feat/fix/perf 提交驱动 semantic-release。develop 分支发布 alpha 预发布：首次为 v1.0.0-alpha.1，之后递增 alpha.N；main 分支只承载正式版本，正式发版即把 develop 合并到 main，第一个正式版本为 v1.0.0。版本提交含 [skip ci]，不发布 npm。

Docker 标签不带 v。用 PPANEL_IMAGE 固定 X.Y.Z-alpha.N（Bun）或 X.Y.Z-alpha.N-node（Node），执行 docker compose pull && docker compose up -d。先备份；迁移升级先停 API，确认 migrate 成功后重建 API。应用回滚恢复上个镜像标签/摘要，在 schema 兼容窗口内重建同一组服务。稳定标签提供 latest/latest-node，预发布跟随 alpha/alpha-node；Redis/Valkey 命令见 Compose。