Handle SpacetimeDB migration imports with chunked uploads

2026-04-30 15:20:49 +08:00
parent 1ccb8a710d
commit 22f3f963de
9 changed files with 567 additions and 20 deletions
--- a/docs/technical/JENKINS_SPACETIMEDB_DATABASE_MIGRATION_PIPELINES_2026-04-29.md
+++ b/docs/technical/JENKINS_SPACETIMEDB_DATABASE_MIGRATION_PIPELINES_2026-04-29.md
@@ -72,12 +72,13 @@ 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. `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`：迁移授权备注。

 ## 4. 安全边界

@@ -85,6 +86,7 @@ Genarrative-Database-Import
 2. `INCREMENTAL` 与 `REPLACE_EXISTING` 互斥，Jenkinsfile 会在执行前阻止同时启用。
 3. Jenkinsfile 不打印 token；生产环境应通过 Jenkins 凭据或目标机器环境变量传入敏感值。
 4. 如果不传 `TOKEN`，导入脚本会创建临时 Web API identity，并调用迁移授权/撤销 procedure 收敛权限窗口。
+5. 如果日志出现 `SpacetimeDB HTTP 413: Failed to buffer the request body: length limit exceeded`，优先把 `CHUNK_SIZE` 调低到 `262144` 或更小后重跑。该参数只降低单次 HTTP body，不改变导入表范围。

 ## 5. 本地部署测试参数

--- a/docs/technical/README.md
+++ b/docs/technical/README.md
@@ -5,6 +5,8 @@
 ## 文档列表

 - [SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md](./SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md)：冻结 SpacetimeDB 表结构变更约束、自动迁移可接受范围、冲突后的系统行为，以及保留旧数据的增量迁移流程；凡涉及 `spacetime publish`、表字段调整或 `migration.rs` 对齐时优先参考。
+- [SPACETIMEDB_JSON_STRING_MIGRATION_PROCEDURE_2026-04-27.md](./SPACETIMEDB_JSON_STRING_MIGRATION_PROCEDURE_2026-04-27.md)：记录 SpacetimeDB private 表迁移 JSON 导出/导入 procedure、迁移操作员授权、HTTP 413 分片导入、Jenkins 自动迁移回灌和导入脚本参数。
+- [JENKINS_SPACETIMEDB_DATABASE_MIGRATION_PIPELINES_2026-04-29.md](./JENKINS_SPACETIMEDB_DATABASE_MIGRATION_PIPELINES_2026-04-29.md)：记录 `Genarrative-Database-Export` / `Genarrative-Database-Import` 两条 SCM-backed 数据库迁移流水线参数、默认 dry-run、token 边界和 `CHUNK_SIZE` 413 规避参数。
 - [RPG_PROMPT_FRONTEND_REMOVAL_AND_SERVER_RS_MIGRATION_2026-04-28.md](./RPG_PROMPT_FRONTEND_REMOVAL_AND_SERVER_RS_MIGRATION_2026-04-28.md)：冻结 RPG 提示词禁止存在前端的边界，明确前端只保留 API client，角色私聊/NPC 对话/剧情续写等 prompt 统一收口到 `server-rs`。
 - [RPG_CREATION_RESULT_VIEW_BACKEND_TRUTH_MIGRATION_2026-04-28.md](./RPG_CREATION_RESULT_VIEW_BACKEND_TRUTH_MIGRATION_2026-04-28.md)：冻结 RPG 创作结果页保存、Agent session/result preview 真相优先级和结果页入口裁决迁移到后端 result-view 的落地边界。
 - [RPG_CREATION_PROFILE_GENERATION_BACKEND_MIGRATION_2026-04-28.md](./RPG_CREATION_PROFILE_GENERATION_BACKEND_MIGRATION_2026-04-28.md)：记录 RPG 创作 profile 生成移除非浏览器 legacy AI 回退，统一通过 `server-rs` 的 `/api/runtime/custom-world/profile` 生成世界底稿。
--- a/docs/technical/SPACETIMEDB_JSON_STRING_MIGRATION_PROCEDURE_2026-04-27.md
+++ b/docs/technical/SPACETIMEDB_JSON_STRING_MIGRATION_PROCEDURE_2026-04-27.md
@@ -8,7 +8,7 @@ SpacetimeDB reducer 必须保持确定性，不能访问文件系统和网络。

 1. `spacetime-module` 内的导出 procedure 读取迁移白名单表，并直接返回迁移 JSON 字符串。
 2. Node 运维脚本默认通过 `spacetime call` 调用导出 procedure，把返回的 JSON 字符串写入本地文件。
-3. Node 运维脚本读取本地 JSON 文件内容。导入时默认先通过 `POST /v1/identity` 创建临时 Web API identity/token，再用当前 CLI 登录态把该 identity 授权为迁移操作员，最后通过 HTTP request body 把 JSON 字符串传给导入 procedure。
+3. Node 运维脚本读取本地 JSON 文件内容。导入时默认先通过 `POST /v1/identity` 创建临时 Web API identity/token，再用当前 CLI 登录态把该 identity 授权为迁移操作员；小文件直接通过 HTTP request body 传给导入 procedure，大文件自动切成分片上传后再提交。
 4. 导入 procedure 校验 JSON 与表白名单后，在事务中写入目标数据库。

 procedure 不再访问 HTTP 文件桥，也不接收部署机本地文件路径。这样可以避开 SpacetimeDB 对 private/special-purpose 地址的 HTTP 访问限制，并避免把 private 表内容通过临时 HTTP 服务转发。
@@ -30,6 +30,8 @@ SpacetimeDB Wasm 运行环境不支持 `std::time::SystemTime::now()`，procedur

 `database_migration_operator` 只控制迁移 procedure 调用权限，不会被导出或导入，避免把源库的运维权限复制到目标库。

+大文件分片导入额外使用私有临时表 `database_migration_import_chunk` 暂存上传片段。这张表只保存当前导入过程的中间数据，提交成功后自动删除，失败时由脚本尽量调用清理 procedure；它不在迁移白名单内，也不会被导出到业务迁移 JSON。
+
 首次授权时，操作员表为空，必须通过编译进模块的 `GENARRATIVE_SPACETIME_MIGRATION_BOOTSTRAP_SECRET` 引导密钥授权第一位操作员。发布脚本会在构建或发布 SpacetimeDB 模块时自动生成一份强随机引导密钥、注入 wasm 编译环境，并在控制台显示；运维人员必须记录对应数据库本次发布输出的密钥。表内已经存在操作员后，后续授权与撤销只能由已有操作员发起；此时不再接受引导密钥越权扩权。

 新增 procedure：
@@ -99,6 +101,14 @@ node scripts/spacetime-revoke-migration-operator.mjs \

 `import_database_migration_incremental_from_file(ctx, input)`

+`put_database_migration_import_chunk(ctx, input)`
+
+`import_database_migration_from_chunks(ctx, input)`
+
+`import_database_migration_incremental_from_chunks(ctx, input)`
+
+`clear_database_migration_import_chunks(ctx, input)`
+
 输入字段：

 - `migration_json`: 导出 procedure 生成的完整迁移 JSON 字符串。
@@ -106,6 +116,15 @@ node scripts/spacetime-revoke-migration-operator.mjs \
 - `replace_existing`: 是否先清空本次迁移文件内实际导入的目标表。不会清空迁移文件未包含的表；分批迁移时只覆盖当前批次。
 - `dry_run`: 只解析和统计，不写表。

+分片导入字段：
+
+- `upload_id`: 本次分片上传的唯一 ID，只允许 ASCII 字母、数字、短横线或下划线。
+- `chunk_index`: 当前分片序号，从 `0` 开始。
+- `chunk_count`: 本次上传总分片数。
+- `chunk`: 当前迁移 JSON 片段，单片最多 `1048576` bytes。
+
+Node 导入脚本默认在文件超过 `524288` bytes 时使用分片导入；如果小文件直接导入仍遇到 `SpacetimeDB HTTP 413: Failed to buffer the request body: length limit exceeded`，也会自动退回分片流程。可通过 `--chunk-size <bytes>` 或环境变量 `GENARRATIVE_SPACETIME_MIGRATION_CHUNK_SIZE` 调小单片大小。
+
 导入模式：

 - 默认严格追加：不清空目标表，逐行插入；遇到主键或唯一约束冲突时失败并回滚，适合确认目标库没有同表旧数据时使用。
@@ -252,8 +271,9 @@ node scripts/spacetime-import-migration-json.mjs \

 1. `POST /v1/identity` 创建临时 Web API identity/token。
 2. 使用当前机器 `spacetime` CLI 登录态调用 `authorize_database_migration_operator`，授权这个临时 identity。
-3. 使用 `Authorization: Bearer <临时 token>` 调用 `import_database_migration_from_file`，把完整迁移 JSON 放在 HTTP body 中。
-4. 导入请求结束后，脚本会用同一个临时 Web API token 调用 `revoke_database_migration_operator`，撤销该临时 identity。
+3. 使用 `Authorization: Bearer <临时 token>` 导入迁移 JSON。文件不超过 `--chunk-size` 时直接调用 `import_database_migration_from_file`；超过阈值或直接导入触发 HTTP 413 时，先逐片调用 `put_database_migration_import_chunk`，再调用 `import_database_migration_from_chunks` 或 `import_database_migration_incremental_from_chunks`。
+4. 分片上传或提交失败时，脚本会尽量调用 `clear_database_migration_import_chunks` 清理临时分片。
+5. 导入请求结束后，脚本会用同一个临时 Web API token 调用 `revoke_database_migration_operator`，撤销该临时 identity。

 所有直接访问 SpacetimeDB Web API 的 POST 请求必须显式发送 `Content-Type: application/json`。部分 SpacetimeDB 版本不会接受省略 content type 或附带非预期 media type 的请求，即使 body 本身是合法 JSON，也会返回 `HTTP 415`。

@@ -265,6 +285,8 @@ node scripts/spacetime-import-migration-json.mjs \

 `--dry-run` 不会模拟目标库主键或唯一约束冲突，因此增量模式的 `skipped_row_count` 只有真实导入时才准确。

+如果 Jenkins 或 SpacetimeDB 返回 `HTTP 413`，优先降低导入流水线的 `CHUNK_SIZE`，例如 `262144`。该参数只影响上传到 procedure 的单片 request body，不改变迁移 JSON 的表范围和导入语义。
+
 不要在只想追加数据时使用 `--replace-existing`。该参数会先删除覆盖范围内的目标表旧数据，再插入迁移文件中的数据；如果源文件不是完整快照，会造成目标表数据丢失。

 如需分批迁移，可用逗号分隔表名：
@@ -303,6 +325,6 @@ node scripts/spacetime-export-migration-json.mjs \

 ## 风险与限制

-迁移 JSON 作为 procedure 返回值和 HTTP request body 传递，会受 SpacetimeDB 调用响应体、请求体以及中间代理大小限制。数据量较大时，先按 `include_tables` 分批迁移；若单表本身过大，再补充分片 procedure，而不是恢复 HTTP 文件桥。
+迁移 JSON 作为 procedure 返回值和 HTTP request body 传递，会受 SpacetimeDB 调用响应体、请求体以及中间代理大小限制。导入端已经内置分片上传来规避 `HTTP 413` 请求体限制；如果导出响应本身过大，仍需先按 `include_tables` 分批导出。

 `spacetime call` 在 PowerShell 中手写 JSON 容易被剥掉双引号。导入大文件时也不能把完整 JSON 放进命令行参数，否则 Linux 会在启动子进程时返回 `spawn E2BIG`。推荐使用仓库里的 Node 脚本，由脚本直接走 Web API request body，避免 shell 二次处理和命令行长度限制。
--- a/docs/technical/SPACETIMEDB_TABLE_CATALOG.md
+++ b/docs/technical/SPACETIMEDB_TABLE_CATALOG.md
@@ -30,6 +30,22 @@ spacetime sql <db> "SELECT * FROM custom_world_gallery_entry"
 | 大鱼吃小鱼 | `big_fish_creation_session`, `big_fish_agent_message`, `big_fish_asset_slot`, `big_fish_runtime_run`                                                                                                                 |
 | 资产       | `asset_object`, `asset_entity_binding`                                                                                                                                                                               |
 | AI 任务    | `ai_task`, `ai_task_stage`, `ai_text_chunk`, `ai_result_reference`                                                                                                                                                   |
+| 运维迁移   | `database_migration_operator`, `database_migration_import_chunk`                                                                                                                                                     |
+
+## 运维迁移表
+
+### `database_migration_operator`
+
+- 作用：迁移操作员白名单，控制导出、导入、授权和撤销迁移 procedure 的调用权限。
+- 结构：`operator_identity PK: Identity`, `created_at: Timestamp`, `created_by: Identity`, `note: String`。
+- 索引：主键 `operator_identity`。
+
+### `database_migration_import_chunk`
+
+- 作用：大迁移 JSON 分片导入的私有临时表，用于规避单次 HTTP request body 过大导致的 `HTTP 413`；提交成功后由导入 procedure 自动清理，失败时由脚本尽量清理。
+- 结构：`chunk_key PK: String`, `upload_id: String`, `chunk_index: u32`, `chunk_count: u32`, `operator_identity: Identity`, `created_at: Timestamp`, `chunk: String`。
+- 索引：主键 `chunk_key`，`upload_id`。
+- 迁移边界：不加入迁移白名单，不导出到业务迁移 JSON。

 ## 认证表