大图谱 JSON 文件导入

本次修复范围

旧创建向导在浏览器中对整个文件执行 file.text()、JSON.parse()、 JSON.stringify()，再将全文放进受控文本框；下一步和提交还会再次解析。文件在磁盘上是 280 MB，不代表浏览器只需要 280 MB 内存。

另一层限制是仓库 Nginx 示例的 client_max_body_size 55m。使用该配置的服务器会拒绝大文件；代码审查并不能证明生产服务器已使用或更新了这份配置。

这次仅增加请求内的文件导入通道，不增加后台守护进程、持久任务队列或应用启动逻辑。地图模板、图标、项目隔离和原有事务/失败补偿机制不变。

使用方式

创建项目，填写名称、英文标识、地图开关及所选地区。
选择 Schema JSON。Schema 仍是小文件，不超过 2 MiB。
选择图谱 data JSON。超过 2 MiB 时只显示文件名称和大小，不将全文放进文本框。
确认创建后上传原始文件，页面显示上传进度及服务器的校验、节点导入、关系导入阶段。
只有收到最终成功结果才视为完成。上传 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 容量、临时盘及代理限制，再进行对应体量的测试，不能仅无限放大上限。

如需显式配置约定值：

GRAPH_IMPORT_MAX_BYTES=5368709120

部署前需要：

安装更新后的 Python 依赖，包含 ijson==3.5.1，并构建前端。
对照 deploy/nginx/travel-kg.conf.example 添加仅文件导入路径的配置。该路径默认允许 6 GiB 请求（为 5 GiB 文件及 multipart 元数据留出空间）、关闭请求和响应缓冲，其他接口仍保留原限制；应用层依然严格限制单个图谱文件不超过 5 GiB。由运维执行 Nginx 配置检查并重载；如果前方还有 CDN/负载均衡，也必须核对其请求限制。
临时目录需为可写、私有、容量充足的数据卷。可在启动 API 前通过 TMPDIR 指向管理员准备好的目录；容器中须保证该目录实际挂载且属主匹配，不能只改目录名称。不要放在公开静态文件目录。
已知 Content-Length 时，预检估算至少需要 请求大小 × 3 + 512 MiB 的可用空间。这是估算，不保证覆盖所有 JSON 结构及并发写入。处理中仍保留至少 512 MiB 磁盘余量；资源不足会明确中止而不是发布半成品图谱。FalkorDB 内存、持久化、备份空间另行预留。
本次代码修改不会自动改动或重启生产服务器，也不将业务 JSON 或凭据提交到 Git。

验证及复测

自动化回归：

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

真实文件验证脚本（请在容量充足的本地测试环境执行）：

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 时只测接收和校验，不写图谱。

报告包含成功/失败、阶段、原文件大小、内存峰值、临时索引占用和磁盘余量。失败的报告不应表述为全量导入成功。

5.8 KiB Raw Permalink Blame History Unescape Escape