101 lines
5.8 KiB
Markdown
101 lines
5.8 KiB
Markdown
# 大图谱 JSON 文件导入
|
||
|
||
## 本次修复范围
|
||
|
||
旧创建向导在浏览器中对整个文件执行 `file.text()`、`JSON.parse()`、
|
||
`JSON.stringify()`，再将全文放进受控文本框；下一步和提交还会再次解析。
|
||
文件在磁盘上是 280 MB，不代表浏览器只需要 280 MB 内存。
|
||
|
||
另一层限制是仓库 Nginx 示例的 `client_max_body_size 55m`。
|
||
使用该配置的服务器会拒绝大文件；代码审查并不能证明生产服务器已使用或更新了这份配置。
|
||
|
||
这次仅增加请求内的文件导入通道，不增加后台守护进程、持久任务队列或应用启动逻辑。
|
||
地图模板、图标、项目隔离和原有事务/失败补偿机制不变。
|
||
|
||
## 使用方式
|
||
|
||
1. 创建项目，填写名称、英文标识、地图开关及所选地区。
|
||
2. 选择 Schema JSON。Schema 仍是小文件，不超过 2 MiB。
|
||
3. 选择图谱 data JSON。超过 2 MiB 时只显示文件名称和大小，不将全文放进文本框。
|
||
4. 确认创建后上传原始文件，页面显示上传进度及服务器的校验、节点导入、关系导入阶段。
|
||
5. 只有收到最终成功结果才视为完成。上传 100% 不等于图谱创建完成。
|
||
|
||
需要保持页面和网络连接。当前通道**不提供断点续传或断线后的任务进度恢复**。
|
||
连接中断时，服务器可能仍在完成当前请求或补偿清理；先刷新项目列表确认结果，勿重复创建。
|
||
已有项目和图名仍受冲突保护，不会被上传文件覆盖。
|
||
|
||
## 处理及安全边界
|
||
|
||
- 管理员鉴权通过后才接收上传正文。
|
||
- multipart 文件使用系统临时目录的磁盘暂存；图谱内容不整体读入 Python 内存。
|
||
- 增量解析每条节点/关系，使用请求私有的 SQLite 临时索引校验重复 ID、Schema 类型及关系端点。
|
||
- 全部校验通过后才写 FalkorDB，按最多 250 条或约 2 MiB 记录文本分批提交。
|
||
- 多标签、原始属性、平行关系均保留。启用地图时检查坐标和地区，`map_poi: false` 的辅助知识节点不计入地图点。
|
||
- 写入数量与校验数量一致后，复用原有项目元数据事务发布；失败则执行原有补偿逻辑。
|
||
- 请求结束会关闭上传文件、清理临时索引；数据库工作线程未停止前不会先删除其文件。
|
||
- 每个 API 进程同时只处理一个文件导入。多进程部署需按总并发规划磁盘和数据库容量。
|
||
- 日志只记录项目、阶段、结果数量或错误类别，不记录上传的完整 JSON、凭据和记录正文。
|
||
|
||
SQLite 在这里仅是临时校验索引，**不是新增业务数据库**。图谱最终存储仍为 FalkorDB。
|
||
|
||
## 容量限制与部署
|
||
|
||
| 项目 | 限制 |
|
||
| --- | --- |
|
||
| 浏览器 JSON 编辑器 / Schema | 2 MiB |
|
||
| 旧 `/v1/admin/projects/provision` JSON 请求体 | 8 MiB，解析前拦截 |
|
||
| 文件接口 `/v1/admin/projects/provision-file` | `GRAPH_IMPORT_MAX_BYTES`，默认 5 GiB（5,368,709,120 字节） |
|
||
| 单条记录 / 单个字符串 / 嵌套 | 约 8 MiB 字符计数 / 4 MiB 原始字节 / 64 层 |
|
||
|
||
默认 5 GiB 是单个图谱数据文件的应用层上限，**不是所有硬件都已通过 5 GiB 验收的承诺**。
|
||
更大的文件应先评估 RAM、FalkorDB 容量、临时盘及代理限制，再进行对应体量的测试，不能仅无限放大上限。
|
||
|
||
如需显式配置约定值：
|
||
|
||
```env
|
||
GRAPH_IMPORT_MAX_BYTES=5368709120
|
||
```
|
||
|
||
部署前需要：
|
||
|
||
1. 安装更新后的 Python 依赖，包含 `ijson==3.5.1`，并构建前端。
|
||
2. 对照 `deploy/nginx/travel-kg.conf.example` 添加**仅文件导入路径**的配置。
|
||
该路径默认允许 6 GiB 请求（为 5 GiB 文件及 multipart 元数据留出空间）、关闭请求和响应缓冲，
|
||
其他接口仍保留原限制；应用层依然严格限制单个图谱文件不超过 5 GiB。
|
||
由运维执行 Nginx 配置检查并重载；如果前方还有 CDN/负载均衡，也必须核对其请求限制。
|
||
3. 临时目录需为可写、私有、容量充足的数据卷。可在启动 API 前通过 `TMPDIR` 指向管理员准备好的目录；
|
||
容器中须保证该目录实际挂载且属主匹配，不能只改目录名称。不要放在公开静态文件目录。
|
||
4. 已知 Content-Length 时，预检估算至少需要 `请求大小 × 3 + 512 MiB` 的可用空间。
|
||
这是估算，不保证覆盖所有 JSON 结构及并发写入。处理中仍保留至少 512 MiB 磁盘余量；
|
||
资源不足会明确中止而不是发布半成品图谱。FalkorDB 内存、持久化、备份空间另行预留。
|
||
5. 本次代码修改不会自动改动或重启生产服务器，也不将业务 JSON 或凭据提交到 Git。
|
||
|
||
## 验证及复测
|
||
|
||
自动化回归：
|
||
|
||
```sh
|
||
python3 -m unittest tests.test_graph_file_import tests.test_project_lifecycle tests.test_plaza_graph_fallback
|
||
cd admin-web
|
||
node --experimental-strip-types --test tests/graphFileUpload.test.ts tests/projectCreationMultiLabel.test.ts tests/projectCatalog.test.ts
|
||
```
|
||
|
||
真实文件验证脚本（请在容量充足的本地测试环境执行）：
|
||
|
||
```sh
|
||
python3 scripts/verify_graph_file_import.py \
|
||
--schema /absolute/path/schema.json \
|
||
--data /absolute/path/data.json \
|
||
--report /absolute/path/new-verification-report.json \
|
||
--import-falkor
|
||
```
|
||
|
||
脚本的地区配置为本次贵阳市样本；其他地区需采用匹配的测试配置。
|
||
它通过独立 ASGI 测试应用验证 multipart 接收、流式校验、真实本机 FalkorDB 分批写入和地图 POI 读取。
|
||
只创建 UUID 临时图并在结束时删除。系统项目元数据与登录身份使用测试替身，
|
||
因此**不替代浏览器、生产 Nginx、真实元数据事务和服务器部署的端到端验收**。
|
||
未加 `--import-falkor` 时只测接收和校验，不写图谱。
|
||
|
||
报告包含成功/失败、阶段、原文件大小、内存峰值、临时索引占用和磁盘余量。
|
||
失败的报告不应表述为全量导入成功。
|