# 旅行知识图谱管理系统

![Python](https://img.shields.io/badge/Python-3.12-blue)
![FastAPI](https://img.shields.io/badge/FastAPI-0.136-green)
![React](https://img.shields.io/badge/React-18-61dafb)
![Docker](https://img.shields.io/badge/Docker-Compose-2496ed)
![Graph](https://img.shields.io/badge/Graph-FalkorDB-purple)

面向贵州、贵阳旅行场景的知识图谱管理系统。项目包含 FastAPI 后端、React 管理后台、PostgreSQL 管理库、FalkorDB 图数据库、图谱 schema、采集/抽取脚本和可恢复的数据快照。用户 clone 仓库后可以直接用 Docker 启动完整系统，并恢复随仓库发布的图谱数据。

## 项目亮点

- 完整后台：数据源、批次、实体审核、证据质量、图谱广场、发布回滚、权限、任务和通知模块。
- 双数据库架构：PostgreSQL 保存后台业务数据与审核流程，FalkorDB 保存可查询图谱。
- 可复现数据：仓库内置 PostgreSQL 与 FalkorDB 快照，下载后可恢复图谱数据。
- Docker 一键启动：`docker compose up -d --build` 同时启动 API、管理后台、PostgreSQL 和 FalkorDB。
- 旅行客服场景：内置固定线路、周边资源、酒店报价、车辆、行程推荐和图谱问答相关接口。
- 可扩展 Agent：保留高德、网页、小红书、抖音、事件抽取、多源对齐、审计等 Agent 代码。

## 系统架构

```mermaid
flowchart LR
    U["运营/标注/客服用户"] --> W["React 管理后台 /admin"]
    W --> A["FastAPI 后端 /v1/admin"]
    A --> P[("PostgreSQL\nkg_admin_new2")]
    A --> F[("FalkorDB\nguiyang_new2\nguiyang_spatial_v1")]
    A --> S["Schema 与采集脚本"]
    A --> L["OpenAI 兼容 LLM\n可选"]
    A --> M["高德地图 API\n可选"]
```

更详细的模块说明见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。

## 快速启动

需要先安装并启动 Docker Desktop。

```bash
git clone https://github.com/3452078359-xuexue/travel-knowledge-graph.git
cd travel-knowledge-graph
docker compose up -d --build
```

启动完成后打开：

```text
http://localhost:8102/admin
```

演示账号：

```text
用户名：admin@example.com
密码：change-me
```

常用服务端口：

| 服务 | 默认地址 |
| --- | --- |
| 管理后台/API | `http://localhost:8102` |
| 管理后台页面 | `http://localhost:8102/admin` |
| API 文档 | `http://localhost:8102/docs` |
| PostgreSQL | `localhost:5433` |
| FalkorDB Redis 协议 | `localhost:6380` |
| FalkorDB Browser | `http://localhost:3002` |

## 数据快照

仓库包含可恢复快照：

| 数据库 | 快照文件 | 默认库/图 |
| --- | --- | --- |
| PostgreSQL | `snapshots/postgres/kg_admin_new2.dump` | database `kg_admin`, schema `kg_admin_new2` |
| FalkorDB | `snapshots/falkordb/dump.rdb` | graph `guiyang_new2`, `guiyang_spatial_v1` |

当前快照包含约 `80609` 条空间 POI、`37457` 条候选实体，以及 FalkorDB 中的贵阳与旅行社相关图谱。详细结构见 [docs/reports/new2_current_kg_schema_snapshot.md](docs/reports/new2_current_kg_schema_snapshot.md) 和 [docs/DATA_SNAPSHOTS.md](docs/DATA_SNAPSHOTS.md)。

PostgreSQL 初始化脚本只会在 Docker 数据卷首次创建时执行。如果要丢弃本地修改并从仓库快照重新恢复：

```bash
docker compose down -v
docker compose up -d --build
```

## 验证命令

检查 API：

```bash
curl http://localhost:8102/v1/admin/health
```

检查 PostgreSQL：

```bash
docker compose exec postgres psql -U admin -d kg_admin \
  -c "SELECT COUNT(*) FROM kg_admin_new2.amap_spatial_pois;"
```

检查 FalkorDB 图列表：

```bash
docker compose exec falkordb redis-cli -p 6379 GRAPH.LIST
```

## 项目结构

```text
.
├── app/                         # FastAPI 后端、API 路由、Agent、图谱核心逻辑
├── admin-web/                   # React + Vite 管理后台源码
├── docker/                      # Docker 初始化脚本
├── docs/                        # 项目说明、架构、部署、数据和报告文档
├── schema搭建/                  # 图谱 schema、百科样例数据和 DSL 资料
├── scripts/                     # 采集、构建、发布和快照导出脚本
├── snapshots/                   # 可恢复数据库快照
├── Dockerfile                   # 后端镜像与前端静态资源构建
├── docker-compose.yml           # 一键启动完整系统
├── .env.example                 # 本地配置模板
└── requirements.txt             # Python 后端依赖
```

不会上传 `.env`、`node_modules/`、运行日志、浏览器缓存、本地 Docker 数据卷和临时文件。仓库保留系统源码、Docker 配置、schema、脚本、必要报告和数据库快照。

## 文档导航

| 文档 | 内容 |
| --- | --- |
| [docs/PROJECT_OVERVIEW.md](docs/PROJECT_OVERVIEW.md) | 系统定位、业务能力和功能地图 |
| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | 容器、后端、前端和数据架构 |
| [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) | Docker 部署、端口、环境变量和常见问题 |
| [docs/DATA_SNAPSHOTS.md](docs/DATA_SNAPSHOTS.md) | 数据快照、恢复、重导出和校验 |
| [docs/API_REFERENCE.md](docs/API_REFERENCE.md) | API 分组、常用接口和调用示例 |
| [docs/MAINTENANCE.md](docs/MAINTENANCE.md) | 维护流程、发布检查和仓库边界 |
| [CONTRIBUTING.md](CONTRIBUTING.md) | 开发参与和提交规范 |
| [SECURITY.md](SECURITY.md) | 演示账号、密钥和生产安全建议 |
| [CHANGELOG.md](CHANGELOG.md) | 版本记录 |

## 本地开发

后端开发：

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
python -m uvicorn app.main:app --host 0.0.0.0 --port 8102 --reload
```

前端开发：

```bash
cd admin-web
npm install
npm run dev
```

前端构建产物会输出到 `app/static/admin/`，Docker 镜像构建时会自动完成这一步。

## 更新快照

如果本机已有 `zn-kg-new2-postgres` 和 `zn-kg-new2-falkordb` 容器，并且想把最新数据重新导出到仓库：

```bash
bash scripts/export_snapshots.sh
```

然后提交 `snapshots/` 中更新后的 dump 文件即可。快照文件接近 GitHub 单文件建议上限，更新前请先确认文件大小不超过 GitHub 的 100 MB 单文件限制。

## 生产使用提醒

默认账号、数据库密码和 `AUTH_SECRET` 仅用于演示。正式部署前请修改 `.env` 或 compose 环境变量，并为 LLM、高德等外部服务单独配置密钥。更多建议见 [SECURITY.md](SECURITY.md)。