---
url: /docs/agentbuff-stack/template-upgrades.md
---
# 模板版本与升级

## 记录来源

模板源根目录的 `template.json` 记录名称和版本。生成项目增加来源 revision、生成时间和源目录是否包含未提交修改。

从已经生成的产品再次生成时，保留原模板来源 revision，更新新产品身份与生成时间。它不会把上一站的 Git HEAD 假装成模板版本。无 Git 来源且没有已有 revision 时记录为空，不编造提交。

用于正式产品时优先从明确版本的干净模板提交生成。未提交修改标记帮助识别与对应 revision 不完全一致的副本。

## 新站生成范围

生成器明确复制 web、app、api、email、共享包、db、infra、中文教程、产品脚本和必要根配置。官网应用、案例资产、官网博客、改造计划、原 Git 历史与原自动发布工作流不进入副本。

凭据、环境私有文件、邮件记录、缓存、依赖和构建产物被排除。生成器只写入非秘密默认环境；认证 secret 和实际服务凭据由每个产品独立配置。

首次执行 `bun install` 更新新项目工作区成员对应的锁文件，提交该产品自己的锁文件后可使用 `--frozen-lockfile`。不要沿用包含官网工作区的源锁文件直接声称副本已经通过干净安装。

## 升级现有产品

1. 读取产品 `template.json` 与当前模板变更说明，确认来源和差异。
2. 在产品自己的分支中应用与所用模块相关的修改。
3. 保留产品处理器、文章、品牌、套餐和环境配置。
4. 如果改动数据结构，先审查迁移，再按对应环境安排执行；生成器不会自动执行迁移。
5. 运行受影响的构建、类型与行为验证，确认后更新来源记录。

生成器拒绝覆盖已有目标目录，不会自动刷新一个已经自定义的产品。当前没有自动合并产品代码、站群后台或一键线上部署能力。

## 本地旧站升级与代码回退演练

I15 提供 `db:validate-upgrades`，验收已经发布的 0012 版本到当前增量历史与 Worker，再切回旧 Worker。命令仅使用一次性回环数据库、独立 Queue / R2 和旧代码归档；需要能创建 / 删除测试库的本机 PostgreSQL 维护连接。开发连接只用于创建 / 清理自有测试库与核对主库迁移数，不升级主预览。不要将该命令当作真实产品的迁移或发布入口。

在包含历史提交的模板源仓库执行：

```sh
bun db:validate-upgrades 3e6dd9df578e2f927a5493a2b06f1dbcc14f8293
```

参数必须是本地存在的 Git 提交；当前流程要求该版本包含到 `0012_public_invisible_woman` 为止的 13 条历史。命令比较旧 SQL 及历史条目和当前前缀，拒绝重写历史，然后通过 `git archive` 读取旧代码、按旧锁文件安装依赖并构建邮件。安装忽略依赖生命周期脚本，不修改源仓库或源锁文件。生成站没有原 Git 历史，不能直接套用这个提交；需在保留对应历史的源仓库执行，或选择符合前提的本地历史提交。缺少旧版本时失败，不用当前代码假装旧版本。

演练流程：

1. 旧版实际 Worker 注册普通账号，上传文本，通过报价确认扣 3 积分，Queue 处理后下载原私有结果。
2. 停止 Worker，用旧版原任务存储入口提交第二个带报价的收费任务，但不发送队列。这是“数据库已提交、尚未投递”的明确故障边界，余额为 14；没有伪造模型调用或真实外部付款。
3. 比较旧公共表的全部原字段、行数及数据摘要，并保存原迁移编号 / 哈希 / 时间。仅在临时迁移副本的最后 SQL 注入故障，实际确认整批增量回滚、原数据与历史保留、新增表及索引不存在。
4. 应用未修改的完整当前历史；原字段与记录不变，新字段 / 表通过各自迁移增加。重复执行不重复应用迁移；内部迁移序列可能因 PostgreSQL 回滚产生编号间隔，不以连续编号判断成功。
5. 启动新版 Worker，原 Cookie 下载旧文件、重复提交返回原任务；维护入口补投第二个任务，真实 Queue / R2 成功交付，保持 14 积分、两条预扣记录和每任务一次执行。
6. 切回旧 Worker，在扩展后的数据库上下载两份原结果、重放原请求；核对原业务字段保持。正常请求会推进限流计数，因此运行阶段不把计数不变当作业务兼容条件；停机迁移阶段仍核对该表全部原字段。

结束时清理旧版本归档、依赖、数据库和本地资源。输出不含连接、密码、原文件内容或完整数据库错误；失败标明阶段及安全错误编号，主库和源配置另行核对。

**边界：** 本次已验证 0012 基线、默认关闭的可选模块、定价为 3 积分的文本示例和固定本地样本。旧付款 / 联盟存量、所有历史版本、产品自定义处理器、真实云端混合版本、负载及外部服务需分别验收。此流程没有自动合并产品代码、更新 `template.json` 来源或宣布 I15 / I16 完成。