3.8 KiB
kgrag 迁移指南
概述
本目录包含将 kgrag 图谱系统从旧服务器完整迁移到新服务器的脚本。
迁移采用方案A：迁移高亮PDF文件 + 批量更新 Neo4j 中的溯源 URL。
迁移前准备
在执行任何脚本前，先修改各脚本顶部的变量配置区。
需要确认的信息
| 信息 | 说明 | 示例 |
|---|---|---|
| 旧服务器 SSH 地址 | 用于 rsync 拉取文件 | root@192.168.0.46 |
| 旧服务器 APP 目录 | kgrag 部署根目录 | /app |
| 新服务器 APP 目录 | 目标部署根目录 | /app |
| 旧服务 BASE URL | 写入 Neo4j 的 URL 前缀 | http://192.168.0.46:59085 |
| 新服务 BASE URL | 迁移后对外服务的 URL 前缀 | http://192.168.1.100:59085 |
| 旧 Neo4j 连接地址 | 用于导出快照（可选） | bolt://192.168.0.46:57687 |
| 新 Neo4j 连接地址 | 用于导入和更新 URL | bolt://localhost:7687 |
执行步骤
步骤 1：迁移文件
在新服务器上执行：
bash 01_copy_files.sh
该脚本通过 rsync 从旧服务器拉取：
/app/files/（原始文档）/app/files/uploads_v1/（高亮注释 PDF，溯源链接的实际目标）/app/kg_output/（实体关系抽取 JSON）kg_snapshot.json（全量快照，含 Embedding）- 所有代码文件
步骤 2：重建 Neo4j 图谱
在新服务器上执行：
bash 02_load_neo4j.sh
该脚本调用 batch_kg_build.py --phase load_snapshot 将 kg_snapshot.json 导入新 Neo4j。
注意：此方式不保留节点的
*_timeline历史字段。
如需完整历史，改用neo4j-admin database dump/load做数据库级备份（需停服）。
步骤 3：批量更新溯源 URL
在新服务器上执行：
python 03_update_neo4j_urls.py
该脚本将 Neo4j 中所有节点 knowledge_source 字段里的旧服务器地址替换为新地址。
步骤 4：更新配置文件
在新服务器上执行：
bash 04_update_config.sh
该脚本更新 config.py、batch_kg_build.py、app.py 中的硬编码 IP 地址。
步骤 5：验证迁移结果
在新服务器上执行：
python 05_verify_migration.py
该脚本检查文件完整性、Neo4j 节点数量、溯源 URL 可访问性。
目录结构说明
迁移完成后，新服务器上的文件布局应与旧服务器一致：
/app/
├── files/ # 原始文档（PDF/DOCX/XLSX等）
│ └── uploads_v1/ # 高亮注释 PDF（溯源跳转目标）
├── kg_output/ # 每个文档的实体关系 JSON（断点续跑用）
├── kg_snapshot.json # 全量图谱快照（重建 Neo4j 的输入）
├── fault_wenjian/ # 超时/失败文件记录
├── entity_registry.json # 动态实体类型注册表
├── tree_data.json # 树状结构数据
├── config.py # 模型/服务地址配置（迁移后需修改）
├── app.py # FastAPI 主程序
├── batch_kg_build.py # 批量图谱构建脚本
├── graph_search/ # 图检索模块
├── kg_build/ # 图谱构建模块
└── ... # 其他代码模块
常见问题
Q：迁移后溯源点击没有跳转到正确页面？
A：检查步骤3是否执行成功，确认新服务的 PREFIX_URL 与 NEW_BASE_URL 一致。
Q：01_copy_files.sh 报 Permission denied？
A：确保新服务器已添加旧服务器的 SSH 公钥，或改用密码认证（rsync 会提示输入）。
Q：02_load_neo4j.sh 报模块找不到？
A：先在新服务器上安装依赖：pip install -r requirements.txt。
Q：高亮 PDF 文件很多，rsync 很慢？
A：可加 --bwlimit=50000（限速 50MB/s）避免占满带宽，或分批执行。