GenarrativeAI/Genarrative
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add production Jenkins release pipelines

Browse Source
This commit is contained in:
kdletters
2026-05-02 19:14:13 +08:00
parent 879a53bf8d
commit bdc3257003
38 changed files with 3315 additions and 982 deletions
Download Patch File Download Diff File Expand all files Collapse all files

74
docs/technical/JENKINS_SPACETIMEDB_DATABASE_MIGRATION_PIPELINES_2026-04-29.md
View File

@@ -2,6 +2,8 @@
日期：`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 增加两条人工触发的数据库迁移流水线：
@@ -24,11 +26,7 @@
### 3.1 数据库导出
脚本路径：
```text
jenkins/Jenkinsfile.database-export
```
旧脚本路径：`jenkins/Jenkinsfile.database-export`。该文件当前仓库已删除；生产版入口为 `jenkins/Jenkinsfile.production-database-export`。
推荐作业名：
@@ -38,28 +36,30 @@ 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`。
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 归档：
```text
<OUTPUT_DIRECTORY>/<EXPORT_NAME>
<WORKSPACE_EXPORT_DIRECTORY>/<EXPORT_NAME>
<WORKSPACE_EXPORT_DIRECTORY>/<EXPORT_NAME>.sha256
```
### 3.2 数据库导入
脚本路径：
```text
jenkins/Jenkinsfile.database-import
```
旧脚本路径：`jenkins/Jenkinsfile.database-import`。该文件当前仓库已删除；生产版入口为 `jenkins/Jenkinsfile.production-database-import`。
推荐作业名：
@@ -69,25 +69,29 @@ Genarrative-Database-Import
关键参数：
1. `INPUT_FILE`：必填，迁移 JSON 文件路径。
2. `DATABASE`、`SERVER`、`SERVER_URL`、`DEPLOY_DIRECTORY`、`ROOT_DIR`：与导出流水线一致。
3. `INCLUDE_TABLES`：可选，只导入指定表。
4. `CHUNK_SIZE`：迁移 JSON 分片大小，默认 `524288` bytes。导入脚本会在文件超过该大小或直接导入触发 HTTP 413 时自动分片上传。
5. `DRY_RUN`：默认 `true`，只校验不写入。
6. `INCREMENTAL`：默认 `true`，跳过已存在或冲突的行。
7. `REPLACE_EXISTING`：默认 `false`，只覆盖本次迁移文件中涉及的表；不可与 `INCREMENTAL` 同时启用。
8. `BOOTSTRAP_SECRET`：可选，用于授权临时 Web API identity。
9. `TOKEN`：可选，SpacetimeDB 客户端连接 token；留空时脚本会自动创建临时 identity 并在结束后撤销。
10. `NOTE`：迁移授权备注。
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. Jenkinsfile 不打印 token；生产环境应通过 Jenkins 凭据或目标机器环境变量传入敏感值。
4. 如果不传 `TOKEN`，导入脚本会创建临时 Web API identity，并调用迁移授权/撤销 procedure 收敛权限窗口。
5. 导入导出流水线在调用仓库内迁移脚本前都会执行 `git reset --hard HEAD`，确保固定源码目录中的本地改动不会影响本次迁移操作。
6. 如果日志出现 `SpacetimeDB HTTP 413: Failed to buffer the request body: length limit exceeded`，优先把 `CHUNK_SIZE` 调低到 `262144` 或更小后重跑。该参数只降低单次 HTTP body，不改变导入表范围。
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. 本地部署测试参数
@@ -112,7 +116,7 @@ DEPLOY_DIRECTORY=/var/lib/jenkins/deploy/Genarrative
## 6. 文件清单
```text
jenkins/Jenkinsfile.database-export
jenkins/Jenkinsfile.database-import
jenkins/Jenkinsfile.production-database-export
jenkins/Jenkinsfile.production-database-import
docs/technical/JENKINS_SPACETIMEDB_DATABASE_MIGRATION_PIPELINES_2026-04-29.md
```