# 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 数据库导出

脚本路径：

```text
jenkins/Jenkinsfile.database-export
```

推荐作业名：

```text
Genarrative-Database-Export
```

关键参数：

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

导出成功后，Jenkins 归档：

```text
<OUTPUT_DIRECTORY>/<EXPORT_NAME>
```

### 3.2 数据库导入

脚本路径：

```text
jenkins/Jenkinsfile.database-import
```

推荐作业名：

```text
Genarrative-Database-Import
```

关键参数：

1. `INPUT_FILE`：必填，迁移 JSON 文件路径。
2. `DATABASE`、`SERVER`、`SERVER_URL`、`DEPLOY_DIRECTORY`、`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. 本地部署测试参数

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

1. `DATABASE`：发布包默认数据库名，默认 `genarrative_pipeline_local_test`。
2. `API_PORT`：发布包内 api-server 端口，默认 `8082`。
3. `WEB_PORT`：发布包内静态网站端口，默认 `25001`。
4. `SPACETIME_PORT`：发布包内本地 SpacetimeDB 端口，默认 `3101`。
5. `DEPLOY_DIRECTORY`：固定部署目录，继续透传给 `Genarrative-Deploy`。

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

```text
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. 文件清单

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