Polish project documentation and runtime config

docs/DEPLOYMENT.md

@@ -0,0 +1,169 @@
+# 部署指南
+
+本文档说明如何用 Docker 启动、重置、配置和排查旅行知识图谱管理系统。
+
+## 环境要求
+
+- Docker Desktop 或 Docker Engine
+- Docker Compose v2
+- 至少 4 GB 可用内存
+- 至少 3 GB 可用磁盘空间
+
+## 一键启动
+
+```bash
+docker compose up -d --build
+```
+
+启动后访问：
+
+```text
+http://localhost:8102/admin
+```
+
+默认账号：
+
+```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
+```
+
+## 端口配置
+
+可以在启动时覆盖端口：
+
+```bash
+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：
+
+```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/前端。
+- 开启日志采集和容器监控。