124 lines
3.8 KiB
Markdown
124 lines
3.8 KiB
Markdown
# 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
|
||
bash 01_copy_files.sh
|
||
```
|
||
|
||
该脚本通过 rsync 从旧服务器拉取：
|
||
- `/app/files/`（原始文档）
|
||
- `/app/files/uploads_v1/`（高亮注释 PDF，溯源链接的实际目标）
|
||
- `/app/kg_output/`（实体关系抽取 JSON）
|
||
- `kg_snapshot.json`（全量快照，含 Embedding）
|
||
- 所有代码文件
|
||
|
||
### 步骤 2：重建 Neo4j 图谱
|
||
|
||
在**新服务器**上执行：
|
||
|
||
```bash
|
||
bash 02_load_neo4j.sh
|
||
```
|
||
|
||
该脚本调用 `batch_kg_build.py --phase load_snapshot` 将 `kg_snapshot.json` 导入新 Neo4j。
|
||
|
||
> 注意：此方式不保留节点的 `*_timeline` 历史字段。
|
||
> 如需完整历史，改用 `neo4j-admin database dump/load` 做数据库级备份（需停服）。
|
||
|
||
### 步骤 3：批量更新溯源 URL
|
||
|
||
在**新服务器**上执行：
|
||
|
||
```bash
|
||
python 03_update_neo4j_urls.py
|
||
```
|
||
|
||
该脚本将 Neo4j 中所有节点 `knowledge_source` 字段里的旧服务器地址替换为新地址。
|
||
|
||
### 步骤 4：更新配置文件
|
||
|
||
在**新服务器**上执行：
|
||
|
||
```bash
|
||
bash 04_update_config.sh
|
||
```
|
||
|
||
该脚本更新 `config.py`、`batch_kg_build.py`、`app.py` 中的硬编码 IP 地址。
|
||
|
||
### 步骤 5：验证迁移结果
|
||
|
||
在**新服务器**上执行：
|
||
|
||
```bash
|
||
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）避免占满带宽，或分批执行。
|