Genarrative/docs/technical/JENKINS_SPACETIMEDB_DATABASE_MIGRATION_PIPELINES_2026-04-29.md

Jenkins SpacetimeDB 数据库导入导出流水线方案

日期：2026-04-29

1. 目标

为 Jenkins 增加两条人工触发的数据库迁移流水线：

1. Genarrative-Database-Export：调用仓库内 scripts/spacetime-export-migration-json.mjs，通过 SpacetimeDB 迁移导出 procedure 生成迁移 JSON，并归档为 Jenkins 产物。
2. Genarrative-Database-Import：调用仓库内 scripts/spacetime-import-migration-json.mjs，通过 SpacetimeDB 迁移导入 procedure 导入迁移 JSON，默认只执行 dry-run。

本方案只编排已有迁移脚本，不在 Jenkinsfile 中重新实现表结构枚举、JSON 解析或 SQL 拼接逻辑。

2. 执行依据

1. SpacetimeDB CLI 调用按仓库技能 spacetimedb-cli 执行，数据库调用通过 spacetime call 或 HTTP procedure API 完成。
2. SpacetimeDB 读写语义按 spacetimedb-concepts 执行：导入导出能力由模块内 procedure/reducer 负责校验和事务处理，Jenkins 不直接改表。
3. 迁移脚本复用当前仓库的参数解析与错误处理：
   • scripts/spacetime-export-migration-json.mjs
   • scripts/spacetime-import-migration-json.mjs
   • scripts/spacetime-migration-common.mjs

3. Jenkins 作业

3.1 数据库导出

脚本路径：

jenkins/Jenkinsfile.database-export

推荐作业名：

Genarrative-Database-Export

关键参数：

1. DATABASE：目标 SpacetimeDB 数据库名；留空时读取仓库环境变量。
2. SERVER：SpacetimeDB server 别名，默认 maincloud。
3. SERVER_URL：显式服务地址；填写后优先于 SERVER。
4. ROOT_DIR：可选，透传给 spacetime --root-dir。
5. INCLUDE_TABLES：可选，逗号分隔的表名白名单。
6. OUTPUT_DIRECTORY：导出文件目录，默认 database-exports。
7. EXPORT_NAME：导出文件名；留空时使用 spacetime-migration-<BUILD_NUMBER>.json。

导出成功后，Jenkins 归档：

<OUTPUT_DIRECTORY>/<EXPORT_NAME>

3.2 数据库导入

脚本路径：

jenkins/Jenkinsfile.database-import

推荐作业名：

Genarrative-Database-Import

关键参数：

1. INPUT_FILE：必填，迁移 JSON 文件路径。
2. DATABASE、SERVER、SERVER_URL、ROOT_DIR：与导出流水线一致。
3. INCLUDE_TABLES：可选，只导入指定表。
4. DRY_RUN：默认 true，只校验不写入。
5. INCREMENTAL：默认 true，跳过已存在或冲突的行。
6. REPLACE_EXISTING：默认 false，只覆盖本次迁移文件中涉及的表；不可与 INCREMENTAL 同时启用。
7. BOOTSTRAP_SECRET：可选，用于授权临时 Web API identity。
8. TOKEN：可选，SpacetimeDB 客户端连接 token；留空时脚本会自动创建临时 identity 并在结束后撤销。
9. NOTE：迁移授权备注。

4. 安全边界

1. 导入流水线默认 DRY_RUN=true，需要人工明确关闭才会写入数据。
2. INCREMENTAL 与 REPLACE_EXISTING 互斥，Jenkinsfile 会在执行前阻止同时启用。
3. Jenkinsfile 不打印 token；生产环境应通过 Jenkins 凭据或目标机器环境变量传入敏感值。
4. 如果不传 TOKEN，导入脚本会创建临时 Web API identity，并调用迁移授权/撤销 procedure 收敛权限窗口。

5. 文件清单

jenkins/Jenkinsfile.database-export
jenkins/Jenkinsfile.database-import
docs/technical/JENKINS_SPACETIMEDB_DATABASE_MIGRATION_PIPELINES_2026-04-29.md