造物矩阵模板

Appearance

升级与回滚 ​

每个模板压缩包都是不可变版本。不要覆盖旧包，也不要直接在正在运行的目录中解压新版本。

升级前 ​

  1. 下载目标版本及其 SHA-256，执行 shasum -a 256 <压缩包> 并与下载页一致。
  2. 保存当前运行版本号、Git 定制提交和 .env，备份 PostgreSQL、Redis 持久化数据及用户上传文件。
  3. 阅读版本记录，确认 Node、pnpm、Docker、数据库迁移和环境变量兼容性。
  4. 在新目录解压，比较 .env.example、config/community-template.json 与自己的品牌定制，只迁移新版本仍需要的配置，不复制过期或来源不明的凭据。

升级流程 ​

bash
pnpm install --frozen-lockfile
pnpm --filter @zaowu/template-core validate:config -- config/community-template.json
pnpm ops:template:preflight
pnpm typecheck
pnpm test
pnpm build

先在隔离环境恢复一份生产备份并执行迁移，再启动新版本。验证首页、登录、文章、订阅、支付回调、软件交付和后台操作后，再切换 Nginx 或负载均衡入口。

迁移必须由当前版本提供的正式命令执行。不要手改迁移记录，也不要在未备份时运行不可逆 SQL。

回滚 ​

如果新版本只包含向后兼容的应用改动，可将入口切回上一版本容器并再次检查健康状态。

如果已经执行不可逆数据库迁移：

  1. 停止写入并保留故障现场日志。
  2. 停止新版本服务，但不要执行 docker compose down -v。
  3. 从升级前备份恢复数据库与文件，再启动上一版本。
  4. 验证用户登录、内容读取、订单与下载权益后再恢复流量。

不要让旧应用连接结构不兼容的新数据库。无法确认迁移可逆时，宁可继续隔离排查，也不要直接切回。

保留材料 ​

每次升级至少保留：原始压缩包、SHA-256、版本记录、部署时间、操作者、备份位置、迁移输出、健康检查结果和回滚结果。建议始终保留最近两个已验证版本。