Polish project documentation and runtime config

docs/DATA_SNAPSHOTS.md

@@ -0,0 +1,103 @@
+# 数据快照说明
+
+仓库内置数据库快照，目的是让用户 clone 后可以直接恢复 `new2` 图谱系统，而不需要重新采集、抽取和发布数据。
+
+## 快照文件
+
+| 文件 | 类型 | 用途 |
+| --- | --- | --- |
+| `snapshots/postgres/kg_admin_new2.dump` | PostgreSQL custom dump | 恢复后台业务库、账号、项目、候选实体、审核数据等 |
+| `snapshots/falkordb/dump.rdb` | FalkorDB RDB | 恢复图数据库中的业务图和空间图 |
+
+默认数据：
+
+| 项 | 值 |
+| --- | --- |
+| PostgreSQL database | `kg_admin` |
+| PostgreSQL schema | `kg_admin_new2` |
+| FalkorDB 业务图 | `guiyang_new2` |
+| FalkorDB 空间图 | `guiyang_spatial_v1` |
+| 空间 POI | 约 `80609` 条 |
+| 候选实体 | 约 `37457` 条 |
+
+## 恢复流程
+
+Docker Compose 首次启动时会自动恢复：
+
+1. `postgres` 容器创建数据卷。
+2. `docker/postgres-init/01-restore-snapshot.sh` 使用 `pg_restore` 恢复 PostgreSQL 快照。
+3. 脚本把演示管理员密码重置为 `change-me`。
+4. `falkordb-seed` 容器把 `dump.rdb` 复制到 FalkorDB 数据卷。
+5. `falkordb` 容器读取 RDB 并加载图数据。
+
+如果数据卷已存在，初始化不会重复执行。需要重置时运行：
+
+```bash
+docker compose down -v
+docker compose up -d --build
+```
+
+## 校验数据
+
+PostgreSQL：
+
+```bash
+docker compose exec postgres psql -U admin -d kg_admin \
+  -c "SELECT COUNT(*) FROM kg_admin_new2.amap_spatial_pois;"
+```
+
+候选实体：
+
+```bash
+docker compose exec postgres psql -U admin -d kg_admin \
+  -c "SELECT COUNT(*) FROM kg_admin_new2.candidate_entities;"
+```
+
+FalkorDB 图列表：
+
+```bash
+docker compose exec falkordb redis-cli -p 6379 GRAPH.LIST
+```
+
+快照文件哈希：
+
+```bash
+shasum -a 256 snapshots/postgres/kg_admin_new2.dump snapshots/falkordb/dump.rdb
+```
+
+当前发布快照的参考哈希：
+
+```text
+c70a3fe2730cd40a96e729097cef1eb39c66498371b88b2e36e985c923043e75  snapshots/postgres/kg_admin_new2.dump
+dde96ac99bff58d18bb00e84939772d8a4efc4893aeeae02329aa893ae51f247  snapshots/falkordb/dump.rdb
+```
+
+## 重新导出快照
+
+如果本机仍保留 `new2` 原始容器，可以运行：
+
+```bash
+bash scripts/export_snapshots.sh
+```
+
+脚本默认从以下容器导出：
+
+| 容器 | 用途 |
+| --- | --- |
+| `zn-kg-new2-postgres` | 导出 `kg_admin_new2` schema |
+| `zn-kg-new2-falkordb` | 触发 `BGSAVE` 并复制 `dump.rdb` |
+
+导出后请验证：
+
+```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
+```
+
+## 仓库边界
+
+`data/`、浏览器 profile、日志、缓存和本地 Docker 数据卷不进入 Git。它们是运行过程或采集过程中的临时产物，不适合作为 GitHub 项目内容。系统可复现所需的数据已经收敛到 `snapshots/`、`schema搭建/`、`docs/` 和源码目录中。
+
+## GitHub 文件大小提醒
+
+GitHub 单文件硬限制为 100 MB。当前两个快照均低于该限制。后续如果快照继续增大，建议改用 Git LFS、Release Asset 或对象存储，并在 README 中保留下载和恢复说明。