271 lines
7.2 KiB
Markdown
271 lines
7.2 KiB
Markdown
# 部署指南
|
||
|
||
本文档说明如何用 Docker 启动、重置、配置和排查旅行知识图谱管理系统。
|
||
|
||
## 环境要求
|
||
|
||
- Docker Desktop 或 Docker Engine
|
||
- Docker Compose v2
|
||
- 至少 4 GB 可用内存
|
||
- 至少 3 GB 可用磁盘空间
|
||
|
||
## 一键启动
|
||
|
||
```bash
|
||
docker compose up -d --build
|
||
```
|
||
|
||
启动后访问：
|
||
|
||
```text
|
||
http://localhost:8102/admin
|
||
```
|
||
|
||
服务器部署后把 `localhost` 换成服务器 IP 或域名。例如本项目迁移到 `8.163.40.99` 后：
|
||
|
||
```text
|
||
http://8.163.40.99:8102/admin
|
||
http://8.163.40.99:8102/docs
|
||
http://8.163.40.99:8102/openapi.json
|
||
```
|
||
|
||
默认账号：
|
||
|
||
```text
|
||
admin@example.com / change-me
|
||
```
|
||
|
||
## 首次启动会发生什么
|
||
|
||
1. 构建 API 镜像，并打包 React 管理后台。
|
||
2. 创建 PostgreSQL 数据卷。
|
||
3. PostgreSQL 初始化脚本恢复 `snapshots/postgres/kg_admin_new2.dump`。
|
||
4. `falkordb-seed` 把 `snapshots/falkordb/dump.rdb` 写入 FalkorDB 数据卷。
|
||
5. FastAPI 服务等待 PostgreSQL 和 FalkorDB 健康后启动。
|
||
|
||
## 常用命令
|
||
|
||
查看服务状态：
|
||
|
||
```bash
|
||
docker compose ps
|
||
```
|
||
|
||
查看 API 日志：
|
||
|
||
```bash
|
||
docker compose logs -f api
|
||
```
|
||
|
||
停止服务：
|
||
|
||
```bash
|
||
docker compose down
|
||
```
|
||
|
||
停止并删除数据卷，下一次启动将重新恢复快照：
|
||
|
||
```bash
|
||
docker compose down -v
|
||
docker compose up -d --build
|
||
```
|
||
|
||
## 无 sudo 服务器的 rootless Docker 启动
|
||
|
||
如果服务器账号不能使用 `sudo`，并且 `loginctl show-user <用户> -p Linger` 显示 `Linger=no`，用户级 `docker.service` 可能会在 SSH 退出后停止。此时可以使用项目脚本把 rootless Docker 的 socket 固定到用户目录：
|
||
|
||
```bash
|
||
cd /home/dockerop/travel-knowledge-graph
|
||
./scripts/server_rootless_docker.sh start
|
||
./scripts/server_rootless_docker.sh up
|
||
./scripts/server_rootless_docker.sh ps
|
||
./scripts/server_rootless_docker.sh health
|
||
```
|
||
|
||
本项目在 `8.163.40.99` 的当前部署使用：
|
||
|
||
```bash
|
||
DOCKER_HOST=unix:///home/dockerop/.docker/run/docker.sock
|
||
```
|
||
|
||
如果服务器重启，重新执行：
|
||
|
||
```bash
|
||
cd /home/dockerop/travel-knowledge-graph
|
||
./scripts/server_rootless_docker.sh up
|
||
```
|
||
|
||
更推荐的长期方式是让服务器管理员执行：
|
||
|
||
```bash
|
||
sudo loginctl enable-linger dockerop
|
||
```
|
||
|
||
这样 rootless Docker 可以由 systemd 用户服务长期托管。
|
||
|
||
## 端口配置
|
||
|
||
可以在启动时覆盖端口：
|
||
|
||
```bash
|
||
API_PORT=18102 \
|
||
POSTGRES_PORT=15433 \
|
||
FALKORDB_PORT=16380 \
|
||
FALKORDB_BROWSER_PORT=13002 \
|
||
docker compose up -d --build
|
||
```
|
||
|
||
默认端口：
|
||
|
||
| 变量 | 默认值 | 说明 |
|
||
| --- | --- | --- |
|
||
| `API_HOST_BIND` | `0.0.0.0` | API/后台监听地址 |
|
||
| `API_PORT` | `8102` | FastAPI 与管理后台 |
|
||
| `POSTGRES_HOST_BIND` | `127.0.0.1` | PostgreSQL 只绑定服务器本机 |
|
||
| `POSTGRES_PORT` | `5433` | PostgreSQL 映射端口 |
|
||
| `FALKORDB_HOST_BIND` | `127.0.0.1` | FalkorDB Redis 协议只绑定服务器本机 |
|
||
| `FALKORDB_PORT` | `6380` | FalkorDB Redis 协议端口 |
|
||
| `FALKORDB_BROWSER_HOST_BIND` | `127.0.0.1` | FalkorDB Browser 只绑定服务器本机 |
|
||
| `FALKORDB_BROWSER_PORT` | `3002` | FalkorDB Browser |
|
||
|
||
## 环境变量
|
||
|
||
Docker Compose 已提供可运行默认值。生产部署时建议改成 `.env` 文件或部署平台的环境变量。
|
||
|
||
服务器首次部署建议复制模板后修改：
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
至少修改：
|
||
|
||
```env
|
||
AUTH_SECRET=换成32位以上随机字符串
|
||
AUTH_DEFAULT_PASSWORD=换成后台管理员密码
|
||
INGEST_API_KEYS=换成给外部系统的接口Key
|
||
LLM_API_BASE=你的OpenAI兼容模型地址
|
||
LLM_API_KEY=你的模型Key
|
||
```
|
||
|
||
| 变量 | 说明 |
|
||
| --- | --- |
|
||
| `POSTGRES_USER`、`POSTGRES_PASSWORD`、`POSTGRES_DB` | PostgreSQL 容器账号、密码、库名 |
|
||
| `DATABASE_URL` | 后端连接 PostgreSQL 的 URL |
|
||
| `DB_SCHEMA` | 默认 `kg_admin_new2` |
|
||
| `DB_MIGRATIONS_ENABLED` | 快照部署默认 `false` |
|
||
| `FALKORDB_HOST` | Docker 内默认 `falkordb` |
|
||
| `FALKORDB_GRAPH` | 默认业务图 `guiyang_new2` |
|
||
| `AUTH_SECRET` | JWT 签名密钥，生产必须替换 |
|
||
| `AUTH_DEFAULT_USERNAME` | 默认管理员用户名 |
|
||
| `AUTH_DEFAULT_PASSWORD` | 默认管理员密码 |
|
||
| `LLM_API_BASE` | OpenAI 兼容模型服务地址，可选 |
|
||
| `LLM_API_KEY` | LLM 密钥，可选 |
|
||
| `LLM_EXTRACTION_ENABLED` | 是否启用 LLM 抽取 |
|
||
| `AMAP_WEB_KEY`、`AMAP_JS_KEY` | 高德地图密钥，可选 |
|
||
| `GAODE_CRAWLER_PATH` | 外部高德采集脚本路径，可选 |
|
||
| `TRAVEL_AGENCY_SOURCE_ROOT` | 旅行社原始资料目录，仅运行采集/构图脚本时需要 |
|
||
| `TRAVEL_DELIVERY_ROOT` | POI 交付 CSV 目录，仅运行采集/增强脚本时需要 |
|
||
| `TRAVEL_KG_EXPORT_ROOT` | 采集/构图脚本导出目录 |
|
||
|
||
## 百姓惠智能客服接口
|
||
|
||
给外部系统对接时，只开放这个接口即可：
|
||
|
||
```text
|
||
POST http://8.163.40.99:8102/v1/admin/travel/customer-service-query
|
||
```
|
||
|
||
服务器安全组需要放行 TCP `8102`。如果服务器本机 `curl http://127.0.0.1:8102/v1/admin/health` 正常，但外部访问 `http://8.163.40.99:8102` 超时，优先检查云控制台安全组/防火墙入方向规则。
|
||
不要把 `5433`、`6380`、`3002` 暴露到公网；默认 Compose 已把这些数据端口绑定到 `127.0.0.1`。
|
||
|
||
请求示例：
|
||
|
||
```bash
|
||
curl http://8.163.40.99:8102/v1/admin/travel/customer-service-query \
|
||
-H 'Content-Type: application/json' \
|
||
-H 'X-KG-API-Key: 你的INGEST_API_KEYS之一' \
|
||
-d '{
|
||
"question": "黄小西三日游多少钱？",
|
||
"knowledge_graph": "百姓惠",
|
||
"session_id": "demo-001",
|
||
"use_llm": true,
|
||
"llm_fusion": true
|
||
}'
|
||
```
|
||
|
||
`llm_fusion=true` 需要配置 `LLM_API_BASE` 和 `LLM_API_KEY`。未配置 key 时，接口仍会返回图谱模板答案，但不会调用 LLM 融合。
|
||
|
||
主要返回字段：
|
||
|
||
| 字段 | 说明 |
|
||
| --- | --- |
|
||
| `answer` | 给外部系统展示的完整回答 |
|
||
| `customer_reply` | 可以直接发给客户的话术 |
|
||
| `follow_up_questions` | 建议追问 |
|
||
| `risk_notes` | 需要二次核实或不可直接承诺的事项 |
|
||
| `knowledge.plans` | 图谱命中的线路/方案 |
|
||
| `knowledge.evidence` | 图谱证据 |
|
||
|
||
## 健康检查
|
||
|
||
API：
|
||
|
||
```bash
|
||
curl http://localhost:8102/v1/admin/health
|
||
```
|
||
|
||
PostgreSQL：
|
||
|
||
```bash
|
||
docker compose exec postgres pg_isready -U admin -d kg_admin
|
||
```
|
||
|
||
FalkorDB：
|
||
|
||
```bash
|
||
docker compose exec falkordb redis-cli -p 6379 PING
|
||
```
|
||
|
||
## 常见问题
|
||
|
||
### 管理后台 404
|
||
|
||
确认镜像已重新构建：
|
||
|
||
```bash
|
||
docker compose up -d --build api
|
||
```
|
||
|
||
前端静态资源由 FastAPI 挂载在 `/admin`，直接访问根路径不会进入后台。
|
||
|
||
### 数据没有恢复
|
||
|
||
PostgreSQL 初始化脚本只在数据卷首次创建时运行。如果已经创建过数据卷，需要先删除卷：
|
||
|
||
```bash
|
||
docker compose down -v
|
||
docker compose up -d --build
|
||
```
|
||
|
||
### 端口被占用
|
||
|
||
使用端口变量覆盖默认端口，例如：
|
||
|
||
```bash
|
||
API_PORT=18102 docker compose up -d
|
||
```
|
||
|
||
### 登录失败
|
||
|
||
初始化脚本会把 `admin@example.com` 的演示密码设置为 `change-me`。如果仍失败，先确认 PostgreSQL 已重新恢复快照，再查看 API 日志。
|
||
|
||
## 生产加固建议
|
||
|
||
- 修改 `AUTH_SECRET`、数据库密码和默认管理员密码。
|
||
- 不要把真实 `.env`、LLM key、高德 key 提交到仓库。
|
||
- 用反向代理提供 HTTPS。
|
||
- 给 PostgreSQL 和 FalkorDB 配置持久化备份。
|
||
- 如果面向公网，限制数据库端口暴露，只暴露 API/前端。
|
||
- 开启日志采集和容器监控。
|