bxh/docs/DEPLOYMENT.md

部署指南

本文档说明如何用 Docker 启动、重置、配置和排查旅行知识图谱管理系统。

环境要求

• Docker Desktop 或 Docker Engine
• Docker Compose v2
• 至少 4 GB 可用内存
• 至少 3 GB 可用磁盘空间

一键启动

docker compose up -d --build

启动后访问：

http://localhost:8102/admin

默认账号：

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 健康后启动。

常用命令

查看服务状态：

docker compose ps

查看 API 日志：

docker compose logs -f api

停止服务：

docker compose down

停止并删除数据卷，下一次启动将重新恢复快照：

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

端口配置

可以在启动时覆盖端口：

API_PORT=18102 \
POSTGRES_PORT=15433 \
FALKORDB_PORT=16380 \
FALKORDB_BROWSER_PORT=13002 \
docker compose up -d --build

默认端口：

变量	默认值	说明
API_PORT	8102	FastAPI 与管理后台
POSTGRES_PORT	5433	PostgreSQL 映射端口
FALKORDB_PORT	6380	FalkorDB Redis 协议端口
FALKORDB_BROWSER_PORT	3002	FalkorDB Browser

环境变量

Docker Compose 已提供可运行默认值。生产部署时建议改成 .env 文件或部署平台的环境变量。

变量	说明
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	采集/构图脚本导出目录

健康检查

API：

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

PostgreSQL：

docker compose exec postgres pg_isready -U admin -d kg_admin

FalkorDB：

docker compose exec falkordb redis-cli -p 6379 PING

常见问题

管理后台 404

确认镜像已重新构建：

docker compose up -d --build api

前端静态资源由 FastAPI 挂载在 /admin，直接访问根路径不会进入后台。

数据没有恢复

PostgreSQL 初始化脚本只在数据卷首次创建时运行。如果已经创建过数据卷，需要先删除卷：

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

端口被占用

使用端口变量覆盖默认端口，例如：

API_PORT=18102 docker compose up -d

登录失败

初始化脚本会把 admin@example.com 的演示密码设置为 change-me。如果仍失败，先确认 PostgreSQL 已重新恢复快照，再查看 API 日志。

生产加固建议

• 修改 AUTH_SECRET、数据库密码和默认管理员密码。
• 不要把真实 .env、LLM key、高德 key 提交到仓库。
• 用反向代理提供 HTTPS。
• 给 PostgreSQL 和 FalkorDB 配置持久化备份。
• 如果面向公网，限制数据库端口暴露，只暴露 API/前端。
• 开启日志采集和容器监控。