GenarrativeAI/Genarrative
5
0
Fork 0
Code Issues Pull Requests Actions 5 Packages Projects Releases Wiki Activity
Files
562b5eb7200bf6de5a68a58911df9d9abf65c165
Genarrative/docs/technical/JENKINS_SPACETIMEDB_DATABASE_MIGRATION_PIPELINES_2026-04-29.md

7.6 KiB
Raw Blame History

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

日期：2026-04-29

状态：历史方案。旧数据库导入导出 Jenkinsfile 已从仓库删除，生产版 Genarrative-Database-Export / Genarrative-Database-Import 已按 PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md 落地到 jenkins/Jenkinsfile.production-database-export 与 jenkins/Jenkinsfile.production-database-import。本文只保留迁移脚本参数、权限边界和 CHUNK_SIZE 等经验；生产 Job 入口以生产部署计划和 jenkins/Jenkinsfile.production-* 为准。

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。该文件当前仓库已删除；生产版入口为 jenkins/Jenkinsfile.production-database-export。

推荐作业名：

Genarrative-Database-Export

关键参数：

  1. DEPLOY_TARGET：逻辑导出目标，development 映射到 linux && genarrative-build，release 映射到 linux && genarrative-release-deploy。
  2. CONFIRM_RELEASE_DEPLOY_AGENT：DEPLOY_TARGET=release 时必填确认。
  3. SOURCE_BRANCH / COMMIT_HASH：固定本次执行的迁移脚本版本。
  4. DATABASE：必填，目标 SpacetimeDB 数据库名。
  5. SPACETIME_SERVER：SpacetimeDB server 别名，默认 local。
  6. SPACETIME_SERVER_URL：显式服务地址；填写后优先于 SPACETIME_SERVER。
  7. SPACETIME_ROOT_DIR：spacetime --root-dir，默认 /stdb。
  8. INCLUDE_TABLES：可选，逗号分隔的表名白名单。
  9. WORKSPACE_EXPORT_DIRECTORY：Jenkins workspace 内导出目录，默认 database-exports。
  10. SERVER_BACKUP_DIRECTORY：可选，目标机器上的额外备份目录；留空则不保存服务器副本。
  11. EXPORT_NAME：导出文件名；留空时使用 spacetime-migration-<BUILD_NUMBER>.json。
  12. TOKEN_CREDENTIAL_ID：可选，已授权迁移 operator token 的 Jenkins Secret Text 凭据 ID。
  13. BOOTSTRAP_SECRET_CREDENTIAL_ID：可选，迁移 bootstrap secret 的 Jenkins Secret Text 凭据 ID。

导出成功后，Jenkins 归档：

<WORKSPACE_EXPORT_DIRECTORY>/<EXPORT_NAME>
<WORKSPACE_EXPORT_DIRECTORY>/<EXPORT_NAME>.sha256

3.2 数据库导入

旧脚本路径：jenkins/Jenkinsfile.database-import。该文件当前仓库已删除；生产版入口为 jenkins/Jenkinsfile.production-database-import。

推荐作业名：

Genarrative-Database-Import

关键参数：

  1. INPUT_SOURCE：必填，pipeline_archive 表示从 Genarrative-Database-Export 归档复制输入文件，manual_upload 表示本次构建手动上传数据源；两种方式互斥。
  2. EXPORT_JOB_NAME / EXPORT_BUILD_NUMBER_TO_IMPORT / INPUT_FILE：仅 pipeline_archive 模式使用。EXPORT_JOB_NAME 默认是导出流水线 Genarrative-Database-Export；INPUT_FILE 可留空，留空时按导出流水线默认归档路径解析为 database-exports/spacetime-migration-<导出构建号>.json。
  3. MANUAL_INPUT_FILE：仅 manual_upload 模式使用，Jenkins 通过 file parameter 接收本次构建上传文件。
  4. DATABASE、SERVER、SERVER_URL、DEPLOY_DIRECTORY、ROOT_DIR：与导出流水线一致。
  5. INCLUDE_TABLES：可选，只导入指定表。
  6. CHUNK_SIZE：迁移 JSON 分片大小，默认 524288 bytes。导入脚本会在文件超过该大小或直接导入触发 HTTP 413 时自动分片上传。
  7. DRY_RUN：默认 true，只校验不写入。
  8. INCREMENTAL：默认 true，跳过已存在或冲突的行。
  9. REPLACE_EXISTING：默认 false，只覆盖本次迁移文件中涉及的表；不可与 INCREMENTAL 同时启用。
  10. BOOTSTRAP_SECRET：可选，用于授权临时 Web API identity。
  11. TOKEN：可选，SpacetimeDB 客户端连接 token；留空时脚本会自动创建临时 identity 并在结束后撤销。
  12. NOTE：迁移授权备注。

4. 安全边界

  1. 导入流水线默认 DRY_RUN=true，需要人工明确关闭才会写入数据。
  2. INCREMENTAL 与 REPLACE_EXISTING 互斥，Jenkinsfile 会在执行前阻止同时启用。
  3. INPUT_SOURCE=pipeline_archive 时必须填写 EXPORT_BUILD_NUMBER_TO_IMPORT；EXPORT_JOB_NAME 默认使用导出流水线名称，INPUT_FILE 默认使用导出流水线默认归档路径，只有导出时自定义目录或文件名才需要显式填写。
  4. INPUT_SOURCE=manual_upload 时必须上传 MANUAL_INPUT_FILE，并把 CONFIRM_INPUT_FILE 填成原始文件名；EXPORT_JOB_NAME 的默认值可以保留，不参与该模式的输入边界。
  5. Jenkinsfile 不打印 token；生产环境应通过 Jenkins 凭据或目标机器环境变量传入敏感值。
  6. 如果不传 TOKEN，导入脚本会创建临时 Web API identity，并调用迁移授权/撤销 procedure 收敛权限窗口。
  7. 导入导出流水线在调用仓库内迁移脚本前都会执行 git reset --hard HEAD，确保固定源码目录中的本地改动不会影响本次迁移操作。
  8. 如果日志出现 SpacetimeDB HTTP 413: Failed to buffer the request body: length limit exceeded，优先把 CHUNK_SIZE 调低到 262144 或更小后重跑。该参数只降低单次 HTTP body，不改变导入表范围。

5. 本地部署测试参数

Genarrative-Build-And-Deploy 增加以下本地发布包参数，便于在 Jenkins 中测试本地 SpacetimeDB，不依赖 Maincloud：

  1. DATABASE：发布包默认数据库名，默认 genarrative-pipeline-local-test。SpacetimeDB CLI 当前要求数据库名匹配 ^[a-z0-9]+(-[a-z0-9]+)*$，只能使用小写字母、数字，并用单个短横线分隔；不要使用大写字母、点号、下划线、首尾短横线或连续短横线。
  2. API_PORT：发布包内 api-server 端口，默认 8082。
  3. WEB_PORT：发布包内静态网站端口，默认 25001。
  4. SPACETIME_PORT：发布包内本地 SpacetimeDB 端口，默认 3101。
  5. DEPLOY_DIRECTORY：固定部署目录，继续透传给 Genarrative-Deploy。

数据库导入导出流水线在本地测试时应显式填写：

DATABASE=genarrative-pipeline-local-test
SERVER_URL=http://127.0.0.1:3101
DEPLOY_DIRECTORY=/var/lib/jenkins/deploy/Genarrative

这样脚本会自动使用 /var/lib/jenkins/deploy/Genarrative/.spacetimedb 作为 spacetime --root-dir，避免回退到 Jenkins 用户全局 CLI 登录态，也避免误连 Maincloud。

6. 文件清单

jenkins/Jenkinsfile.production-database-export
jenkins/Jenkinsfile.production-database-import
docs/technical/JENKINS_SPACETIMEDB_DATABASE_MIGRATION_PIPELINES_2026-04-29.md
Reference in New Issue View Git Blame Copy Permalink