# 数据快照说明

仓库内置数据库快照，目的是让用户 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 中保留下载和恢复说明。