176 lines
6.5 KiB
Markdown
176 lines
6.5 KiB
Markdown
# 旅行知识图谱管理系统
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
面向贵州、贵阳旅行场景的知识图谱管理系统。项目包含 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)。
|