# 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）避免占满带宽，或分批执行。