维护指南

本文档记录项目维护、发布和提交前检查流程，帮助仓库长期保持可下载、可启动、可理解。

提交前检查

git status --short
python -m compileall app
cd admin-web && npm run build
cd ..
docker compose config

如果修改 Docker 或数据库快照，建议再做一次完整启动验证：

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

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

docker compose down -v

更新系统代码

后端 API 放在 app/api/。
Agent 和抽取流程放在 app/agents/。
图谱核心能力放在 app/kg_core/。
前端页面和面板放在 admin-web/src/。
配置项统一从 app/config.py 和环境变量读取。

历史采集/构图脚本的本地资料路径统一在 scripts/common_paths.py 中配置，默认指向仓库内 data/source 和 data/exports。需要接入自己的原始资料时，可通过 TRAVEL_AGENCY_SOURCE_ROOT、TRAVEL_DELIVERY_ROOT、TRAVEL_KG_EXPORT_ROOT、GAODE_CRAWLER_PATH 覆盖。

新增功能时请同步更新：

README 的功能说明或项目结构。
docs/API_REFERENCE.md 中的接口列表。
需要运行环境变量时更新 .env.example 和 docs/DEPLOYMENT.md。

更新图谱 schema

图谱 schema 和 DSL 资料主要放在 schema搭建/。如果 schema 已经发布到数据库或 FalkorDB，建议同时更新：

schema 文件
发布脚本
docs/reports/new2_current_kg_schema_snapshot.md
数据快照

更新数据快照

从本地 new2 容器导出：

bash scripts/export_snapshots.sh

导出后检查：

ls -lh snapshots/postgres/kg_admin_new2.dump snapshots/falkordb/dump.rdb
shasum -a 256 snapshots/postgres/kg_admin_new2.dump snapshots/falkordb/dump.rdb

快照更新后必须执行 Docker 恢复验证，确保新用户 clone 仓库后可以直接使用。

仓库不应包含

.env 和真实密钥
node_modules/
Python 虚拟环境
Playwright/浏览器 profile
Docker 数据卷
临时日志、截图和缓存
超过 GitHub 限制的大文件

发布建议

成熟发布建议包含：

代码和文档已提交。
Docker 可以从零构建。
PostgreSQL 和 FalkorDB 快照可以恢复。
默认账号可以登录。
README 中的启动命令与端口正确。
GitHub 仓库首页可以看到系统定位、架构、数据和部署方式。

当前验证记录

本地已用非默认端口完成 Docker 验证：

API 健康检查返回 {"status":"ok"}。
管理后台 /admin/ 返回 200。
PostgreSQL 恢复后 kg_admin_new2.amap_spatial_pois 为 80609 条。
PostgreSQL 恢复后 kg_admin_new2.candidate_entities 为 37457 条。
FalkorDB 可列出 guiyang_new2、guiyang_spatial_v1 等图。
admin@example.com / change-me 登录成功。

2.9 KiB Raw Blame History Unescape Escape