Add deploy pipeline SpacetimeDB auto migration

docs/technical/SPACETIMEDB_JSON_STRING_MIGRATION_PROCEDURE_2026-04-27.md

@@ -146,6 +146,31 @@ npm run spacetime:publish:maincloud -- --database xushi-p4wfr
 
 冲突自动迁移需要发布脚本本次生成的 `GENARRATIVE_SPACETIME_MIGRATION_BOOTSTRAP_SECRET`。因此不要和 `--no-migration-bootstrap-secret` 同时使用。
 
+### 部署流水线自动迁移
+
+Ubuntu 发布包的 `start.sh` 与 Jenkins `Genarrative-Deploy` 也采用同一套迁移 procedure，但迁移触发点在部署目录内：
+
+1. Jenkins 覆盖部署前，如果旧部署目录存在 `migration-bootstrap-secret.txt`，先保存到 `run/migration-bootstrap-secret.previous.txt`。
+2. Jenkins 复制新发布包，包含新 wasm、新 `migration-bootstrap-secret.txt` 和 `scripts/spacetime-*.mjs` 迁移脚本。
+3. 新 `start.sh` 先不清库发布当前包内 `spacetime_module.wasm`。
+4. 如果发布成功，流程结束。
+5. 如果发布失败且输出可判定为 schema 冲突，`start.sh` 用旧密钥授权导出旧库 JSON。
+6. 导出成功后，`start.sh` 清库发布新 wasm。
+7. 新 wasm 发布成功后，`start.sh` 用新密钥授权导入，并以 `--replace-existing` 回灌迁移 JSON。
+
+自动迁移 JSON 默认保存到部署目录的 `database-migrations/<database>/<timestamp>.json`。可通过 Jenkins 参数 `MIGRATION_DIRECTORY` 或环境变量 `GENARRATIVE_SPACETIME_MIGRATION_DIR` 覆盖。该目录属于运行态数据，部署脚本不会删除。
+
+Jenkins 参数 `MIGRATE_ON_CONFLICT` 默认 `true`。如果设为 `false`，普通发布遇到 schema 冲突时会保留原始失败，不执行导出、清库发布和导入回灌。
+
+Jenkins 参数 `CLEAR_DATABASE=true` 或手工执行 `./start.sh --clear-database` 时，语义是人工确认清库发布；此时 `spacetime publish` 追加 `-c=on-conflict`，不执行自动导出和导入回灌。
+
+自动迁移依赖两个引导密钥：
+
+- 导出旧库：优先使用 `run/migration-bootstrap-secret.previous.txt`，也就是旧模块编译时注入的密钥。
+- 导入新库：使用当前发布包 `migration-bootstrap-secret.txt`，也就是新模块编译时注入的密钥。
+
+如果不是通过 Jenkins 部署脚本覆盖发布包，而是手工替换文件，必须在覆盖前保留旧 `migration-bootstrap-secret.txt`；否则旧库迁移 procedure 可能无法授权导出。
+
 ### 删除表和删除字段
 
 迁移文件来自旧模块时，可能包含新模块已经删除的表或字段。导入阶段按以下规则处理：