> For the complete documentation index, see [llms.txt](https://summerain-1.gitbook.io/summerain/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://summerain-1.gitbook.io/summerain/zh-cn/yong-hu-yu-yun-wei/migrations.md).

# 数据库迁移

从 v2.0.3 开始，服务器启动通过 `repository.BootstrapDatabase(ctx, db)` 统一管理所有 MySQL 引导工作。 任何引导错误都是致命错误：服务器必须在接受流量前退出。

引导过程会独占一个物理 SQL 连接，在该连接上获取数据库范围的 MySQL advisory lock，并一直持有二者直到所有阶段完成。持锁期间会：

1. 创建或加载 `schema_migrations`，然后校验版本连续性、已知版本以及 不可变的 SHA-256 校验和；
2. 确认每个已记录操作所代表的对象仍然存在，包括列、索引、表以及 容量锁种子行；
3. 存在时移除不兼容的旧版访问令牌数据和列；
4. 应用 GORM 基线结构；
5. 按版本顺序应用缺失的带校验和操作，在添加列或索引前查询 `information_schema`，并仅在某版本的全部操作成功后记录该版本；
6. 在不覆盖现有值的前提下写入所需的默认配置。

账本和已应用对象的校验会在任何破坏性旧版处理之前完成。已记录对象缺失、 校验和不匹配、未知版本、版本断层、DDL 失败或默认配置写入失败，都会中止启动。 引导返回时会释放 advisory lock。

MySQL DDL 会隐式提交。因此，每项带校验和的迁移操作都必须是增量操作，并能在中断后安全重试； 但引导过程不承诺对 MySQL 已提交的 DDL 进行事务回滚。修正报告的问题后，重新运行引导即可。 绝不能编辑已经应用的迁移；应追加更高版本。破坏性的重命名、删除列和删除表必须有 单独的兼容与回滚方案，因此带校验和的 V2 迁移有意不包含这些操作。旧版访问令牌清理是一个 位于该增量迁移列表之外的专用兼容阶段。

## 面向生产环境的 SQL 生成

`scripts/generate-sql-migration.sh` 会把模型与带校验和迁移所产生的结构， 渲染成本目录下的显式快照文件，例如 `20261003_122900_baseline_schema.up.sql`：

```bash
./scripts/dev-wsl.sh deps-up
bash scripts/generate-sql-migration.sh baseline_schema
bash scripts/generate-sql-migration.sh --verify backend/migrations/<file>.up.sql
```

该命令只会在 `SUMMERAIN_SCHEMA_DSN`（默认 `root:summerain-dev@tcp(127.0.0.1:13306)/`）上创建并删除一次性数据库， 绝不接触已有数据库。每个生成的文件在被接受前都会校验：先把文件应用到一个空数据库， 随后运行的引导过程必须让该结构保持不变，从而证明快照与模型及所有带校验和的迁移一致。 当设置 `SUMMERAIN_SCHEMA_DSN` 时，`go test ./cmd/schema-migration-gen/...` 会执行同样的检查。

在生产环境启动本版本前，请先把快照应用到空数据库。服务器启动仍会校验结构并记录迁移账本； 它不会在该约定之外新增列或表，因此不完整或含糊的恢复会快速失败，而不会静默修改生产数据。 已有数据库继续通过上述追加型带校验和运行器升级。快照一经提交即不可更改： 每次结构变更都应重新生成当前结构并提交一份新的带日期文件。

## 首次升级到 v2.0.3

启动第一个 v2.0.3 实例之前，必须停止所有正在运行 v2.0.2 或更旧版本的后端实例。 不得进行新旧二进制文件重叠运行的滚动部署：旧版可能会在现由 `BootstrapDatabase` 管理的 advisory lock 之外执行旧版清理、基线迁移和默认配置写入。 当一个 v2.0.3 实例成功完成引导后，可正常启动其余 v2.0.3 实例，它们会通过同一把锁串行化。

当前版本：

* `2026071501`：为 `images` 添加 V2 流水线元数据和索引。
* `2026071502`：创建 V2 变体、上传会话/部件、处理任务以及事务性发件箱表。
* `2026071601`：添加单例行，用于在多个后端实例间串行化全局上传容量预留。
* `2026071602`：添加存储引用查询索引和有界控制平面保留索引。
* `2026071603`：添加远程后端、端点和存储桶血缘列及索引。历史行保持未分类， 交由独立迁移工具处理；服务器启动时绝不会推断其存储目标。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://summerain-1.gitbook.io/summerain/zh-cn/yong-hu-yu-yun-wei/migrations.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `build a script that syncs our docs to a CMS` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.