102 lines
2.9 KiB
Markdown
102 lines
2.9 KiB
Markdown
# 维护指南
|
||
|
||
本文档记录项目维护、发布和提交前检查流程，帮助仓库长期保持可下载、可启动、可理解。
|
||
|
||
## 提交前检查
|
||
|
||
```bash
|
||
git status --short
|
||
python -m compileall app
|
||
cd admin-web && npm run build
|
||
cd ..
|
||
docker compose config
|
||
```
|
||
|
||
如果修改 Docker 或数据库快照，建议再做一次完整启动验证：
|
||
|
||
```bash
|
||
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
|
||
bash scripts/export_snapshots.sh
|
||
```
|
||
|
||
导出后检查：
|
||
|
||
```bash
|
||
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 限制的大文件
|
||
|
||
## 发布建议
|
||
|
||
成熟发布建议包含：
|
||
|
||
1. 代码和文档已提交。
|
||
2. Docker 可以从零构建。
|
||
3. PostgreSQL 和 FalkorDB 快照可以恢复。
|
||
4. 默认账号可以登录。
|
||
5. README 中的启动命令与端口正确。
|
||
6. 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` 登录成功。
|