Add migration token parameters to Jenkins deploy flows

docs/technical/JENKINS_RUST_BUILD_DEPLOY_PIPELINES_2026-04-23.md

@@ -101,7 +101,7 @@ scripts/jenkins-deploy-release.sh \
 2. 覆盖前如果旧部署目录存在 `migration-bootstrap-secret.txt`，先复制到 `deploy-state/migration-bootstrap-secret.previous.txt`，供新版本 `start.sh` 在 schema 冲突自动迁移时授权导出旧库。该文件属于 Jenkins 部署状态，不放入 `run/`，避免 `sudo` 启停脚本生成的 root 私有运行目录阻断后续部署写入。
 3. 只删除发布产物白名单中的旧文件，例如 `web/`、`api-server`、`spacetime_module.wasm`、`migration-bootstrap-secret.txt`、`scripts/`、`.env*`、`start.sh`、`stop.sh`、`web-server.mjs`、`README.md`。
 4. 将指定版本目录中的同名发布产物复制到部署目录；文件产物使用普通复制，`web/`、`scripts/` 等目录产物必须递归复制。
-5. 把 `WEB_PORT`、`MIGRATE_ON_CONFLICT`、`MIGRATION_DIRECTORY` 写入部署目录 `.env.local`，确保通过 sudo 执行 `start.sh` 时仍能读取 Jenkins 参数；启动前读取 `.env` 与 `.env.local` 中最终的 `GENARRATIVE_SPACETIME_DATABASE`，打印并校验其符合 SpacetimeDB 数据库名规则。
+5. 把 `WEB_PORT`、`MIGRATE_ON_CONFLICT`、`MIGRATION_DIRECTORY` 写入部署目录 `.env.local`，确保通过 sudo 执行 `start.sh` 时仍能读取 Jenkins 参数；启动前读取 `.env` 与 `.env.local` 中最终的 `GENARRATIVE_SPACETIME_DATABASE`，打印并校验其符合 SpacetimeDB 数据库名规则。Jenkins 参数 `MIGRATION_EXPORT_TOKEN` / `MIGRATION_IMPORT_TOKEN` 会分别写入 `GENARRATIVE_SPACETIME_MIGRATION_EXPORT_TOKEN` / `GENARRATIVE_SPACETIME_MIGRATION_IMPORT_TOKEN`；如果参数为空，部署目录已有同名变量时会尽量保留。
 6. 如果 `CLEAR_DATABASE=true`，部署脚本会以 `./start.sh --clear-database` 启动新版本；这样发布阶段的 `spacetime publish` 会追加 `-c=on-conflict`，代表人工确认清库，不进入自动导出和回灌。
 7. 执行新版本 `start.sh`；普通发布遇到 schema 冲突时，默认由发布包内迁移脚本自动导出旧库、清库发布新 wasm、导入回灌。
 
@@ -148,6 +148,8 @@ jenkins/Jenkinsfile.build-and-deploy
 6. `CLEAR_DATABASE`：部署阶段是否清空 SpacetimeDB 数据后再发布 wasm；默认 `false`。
 7. `MIGRATE_ON_CONFLICT`：普通部署遇到 SpacetimeDB schema 冲突时是否自动导出、清库发布、导入回灌；默认 `true`。
 8. `MIGRATION_DIRECTORY`：自动迁移 JSON 输出目录；留空时使用部署目录内 `database-migrations/<database>`。
+9. `MIGRATION_EXPORT_TOKEN`：可选，旧库已授权迁移操作员 token，只在 schema 冲突导出旧库时使用。
+10. `MIGRATION_IMPORT_TOKEN`：可选，新库已授权迁移操作员 token，只在清库发布新 wasm 后导入回灌时使用。
 
 如果当前 Jenkins 没有额外配置独立 Agent，而是直接在控制器自身执行任务，`AGENT_LABEL` 应填写 `built-in`。
 如果 Jenkins 进程以默认 `jenkins` 用户运行，部署目录建议直接放在 `/var/lib/jenkins/deploy/Genarrative` 这类 Jenkins 自有目录下，避免再依赖 `/home/ubuntu/*` 的额外写权限。
@@ -164,6 +166,8 @@ jenkins/Jenkinsfile.build-and-deploy
 7. `RUN_DEPLOY_HOOKS_WITH_SUDO`
 8. `EXPECTED_UPSTREAM_JOB`
 9. `WEB_PORT`
+10. `MIGRATION_EXPORT_TOKEN`
+11. `MIGRATION_IMPORT_TOKEN`
 
 其中仅 `构建并部署` 流水线还需要：
 
@@ -173,7 +177,9 @@ jenkins/Jenkinsfile.build-and-deploy
 4. `CLEAR_DATABASE`
 5. `MIGRATE_ON_CONFLICT`
 6. `MIGRATION_DIRECTORY`
-7. `DATABASE`：发布包默认数据库名，默认 `genarrative-pipeline-local-test`，必须匹配 `^[a-z0-9]+(-[a-z0-9]+)*$`。
+7. `MIGRATION_EXPORT_TOKEN`
+8. `MIGRATION_IMPORT_TOKEN`
+9. `DATABASE`：发布包默认数据库名，默认 `genarrative-pipeline-local-test`，必须匹配 `^[a-z0-9]+(-[a-z0-9]+)*$`。
 
 如果你选择启用 `RUN_DEPLOY_HOOKS_WITH_SUDO=true`，推荐提前在服务器上增加一份最小 sudoers 配置，例如：
 

docs/technical/SPACETIMEDB_JSON_STRING_MIGRATION_PROCEDURE_2026-04-27.md

@@ -175,6 +175,15 @@ Jenkins 参数 `CLEAR_DATABASE=true` 或手工执行 `./start.sh --clear-databas
 - 导出旧库：优先使用 `deploy-state/migration-bootstrap-secret.previous.txt`，也就是旧模块编译时注入的密钥。
 - 导入新库：使用当前发布包 `migration-bootstrap-secret.txt`，也就是新模块编译时注入的密钥。
 
+如果旧库或新库的 `database_migration_operator` 表已经不为空，bootstrap secret 不能再越权授权新的操作员；此时必须由已有迁移操作员发起授权，或在部署目录 `.env.local` 中配置已授权操作员的连接 token：
+
+```text
+GENARRATIVE_SPACETIME_MIGRATION_EXPORT_TOKEN=<旧库迁移操作员 token>
+GENARRATIVE_SPACETIME_MIGRATION_IMPORT_TOKEN=<新库迁移操作员 token>
+```
+
+`GENARRATIVE_SPACETIME_MIGRATION_EXPORT_TOKEN` 只用于 schema 冲突时导出旧库；`GENARRATIVE_SPACETIME_MIGRATION_IMPORT_TOKEN` 只用于清库发布新 wasm 后导入回灌。Jenkins 覆盖部署会尽量保留部署目录现有 `.env.local` 中的这两个 token，除非新发布包已经显式提供同名变量。
+
 如果不是通过 Jenkins 部署脚本覆盖发布包，而是手工替换文件，必须在覆盖前保留旧 `migration-bootstrap-secret.txt`；否则旧库迁移 procedure 可能无法授权导出。
 
 ### 删除表和删除字段
@@ -250,6 +259,8 @@ node scripts/spacetime-import-migration-json.mjs \
 
 如果你已经有可用的数据库连接 token，也可以显式传 `--token <web-api-token>`。这种情况下脚本不会自动授权；该 token 对应的 identity 必须已经是迁移操作员。
 
+如果 `authorize_database_migration_operator` 返回 `当前 identity 未被授权执行数据库迁移`，说明当前机器 `spacetime` CLI 登录身份不是既有迁移操作员。表内已经存在操作员时，即使提供了正确 bootstrap secret，也不会允许非操作员继续扩权；需要先让既有操作员授权当前部署机 identity，或直接使用既有操作员 token 执行导出/导入。
+
 正式导入前建议先加 `--dry-run`，确认 JSON 可解析、版本匹配、表名都在迁移白名单内。
 
 `--dry-run` 不会模拟目标库主键或唯一约束冲突，因此增量模式的 `skipped_row_count` 只有真实导入时才准确。