ContextualWisdomLab/pg-erd-cloud
GitHub: ContextualWisdomLab/pg-erd-cloud
一个基于云端的 PostgreSQL/Snowflake schema 逆向工程与 ERD 协作分享服务，支持 DDL 导出、跨方言类型映射及 LLM 辅助规格说明书生成。
Stars: 1 | Forks: 0
# pg-erd-cloud (MVP 骨架)
这是一个以 PostgreSQL 为核心的云端 ERD（协作/共享）软件的**可运行 MVP 骨架**。
## 当前提供的功能
- **Backend DB = PostgreSQL**（用于存储应用元数据）
- **Reverse engineering（逆向工程）**：连接到目标 PostgreSQL 后
- schema/table/column
- PK/FK/UNIQUE/CHECK
- index（包含 access method，例如：btree/hash/gist/gin/spgist/brin + extension AM）
基于 pg_catalog 进行收集，并保存为快照
- **Snowflake reverse engineering（可选）**：如果使用
`snowflake://user:password@account/database/schema` 格式的 DSN，
将从 Snowflake 的 `INFORMATION_SCHEMA` 中收集 schema/table/column、
PK/UNIQUE/FK 元数据，并将其保存为 `source_dialect: "snowflake"` 的快照。
运行环境中需要可选依赖项 `snowflake-connector-python`。
- **ERD UI**：使用 React Flow（MIT）以图形化方式渲染 PK/FK
- **Forward engineering（正向工程）**：在 MVP 阶段，主要侧重于“基于快照的 DDL（导出）”
（基于 diff/生成变更 SQL 的功能在路线图中）
- SQL export：`GET /api/snapshots/{snapshot_uuid}/export.sql`
- Target dialect：`?dialect=postgresql`（默认）或 `?dialect=snowflake`
- 将 PostgreSQL 快照转换为 Snowflake DDL 时，会映射主要的 column type，
并将 PostgreSQL 专用的 index/tablespace/partition/check constraint 以注释形式保留。
- Snowflake reverse snapshot JSON（`source_dialect: "snowflake"`）在导出为 PostgreSQL
DDL 时也会映射主要的 type。
- **生成 DB Reversing 规格说明书**：
- Markdown draft：`GET /api/snapshots/{snapshot_uuid}/reversing-spec.md`
- LLM prompt：`GET /api/snapshots/{snapshot_uuid}/reversing-spec.md?mode=llm-prompt`
- Live LLM draft：`GET /api/snapshots/{snapshot_uuid}/reversing-spec.md?mode=llm-draft`
- 调用配置了 `LLM_API_BASE_URL`、`LLM_API_KEY`、`LLM_MODEL` 的 OpenAI 兼容
chat-completions provider。
- 在 Share link 中也可以使用相同的
`/api/share/{share_uuid}/snapshots/{snapshot_uuid}/...` 路径。
- **列示例值提示**：在逆向工程快照的每一列中添加 `example_value`。
由于这是利用列名/类型元数据生成的合成示例，而非对实际表数据进行采样，
因此可以在 ERD、PlantUML/SVG export、规格说明书和 LLM prompt 中安全地参考。
## 共享（向同事分享链接）
项目所有者可以创建共享链接。
```
curl -X POST "http://localhost:8000/api/projects//share-links"
```
同事可以通过返回的 `url_path` 查看最新的快照列表/快照 JSON/DDL export。
`/api/share/*` 公开查看/导出路径应用了比全局 `/api/*` 限制更严格的独立
基于 IP 的 rate limit。
## 索引类型支持原则
在 PostgreSQL 中，`CREATE INDEX ... USING ` 中的 ``
不仅限于内置类型（btree/hash/gist/gin/spgist/brin），还可以是**通过 extension（扩展）添加的 access method**。
因此，本项目**不硬编码固定列表**，
而是通过以下方式广泛支持“现存（已安装在该数据库中）的索引类型”：
- 使用 `pg_am` + `pg_class.relam` 收集“当前数据库中实际存在的 access method
(amname)”
- 使用 `pg_get_indexdef()` **无损**保留 DDL
依据（官方文档）：
- Index types / extension bloom 示例：
- CREATE INDEX（用户安装的 access methods）：
- pg_am / pg_class / pg_index：
- pg_get_indexdef / pg_get_expr：
## 运行（本地，Docker）
```
cp .env.example .env
docker compose up -d --build
```
- Frontend：
- Backend：（health：/healthz）
## 运行（生产环境风格，Docker）
使用 Traefik 作为 edge router。将 `/api/*` 和 `/healthz` 路由到后端，
将其余路径路由到静态构建的 frontend SPA。
```
cp .env.example .env
# 在生产模式中，通过 Docker secret 文件注入 APP_SECRET。
# (禁止提交此文件：在 .gitignore 中包含 **/secrets/**)
mkdir -p secrets
python - <<'PY'
import secrets
with open('secrets/app_secret', 'w', encoding='utf-8') as f:
f.write(secrets.token_urlsafe(48) + "\n")
PY
# 限制 secret 文件权限（仅所有者可读写）
chmod 600 secrets/app_secret
docker compose -f compose.prod.yaml up -d --build
```
- 应用入口：（可通过 `TRAEFIK_HTTP_PORT` 修改）
- Health：
### Azure VMSS 状态探测（可选）
如果使用 VMSS Application Health Extension，有关 `/healthz` 探测配置示例请
参考以下文档。
- [Azure VMSS Application Health Extension 指南](docs/azure-vmss-health-extension.md)
## 开发（非 Docker）
### Backend
```
cd backend
python -m venv .venv && source .venv/bin/activate
pip install -U pip
pip install -e .
alembic upgrade head
hypercorn --config python:app.hypercorn_config app.main:app \
--bind 0.0.0.0:8000 --reload \
--access-logfile - --error-logfile -
```
在需要使用 Snowflake reverse engineering 的开发环境中，请在后端虚拟环境中
一并安装可选依赖项。
```
pip install -e ".[snowflake]"
```
#### 运维提示
- Hypercorn worker 数量可通过 `HYPERCORN_WORKERS`（或 `WEB_CONCURRENCY`）进行调整。
- `APP_SECRET` 用作应用 DB 中存储的 DSN 加密密钥，因此更改它可能会
影响现有数据的解密。请尽可能通过 `APP_SECRET_FILE`（例如：
`/run/secrets/app_secret`）方式进行安全注入。
### Frontend
```
cd frontend
npm ci
npm run dev
```
## 安全/运维注意事项
- 禁止提交 `.env`（已包含在 .gitignore 中）。
- 目标数据库连接信息 (DSN) 基于 **APP_SECRET** 进行加密并存储在应用 DB 中。
- 逆向工程操作不在请求路径中同步等待，而是通过 job queue 进行异步处理。
- API 安全检查清单（项目标准）：[docs/api-security-checklist.md](docs/api-security-checklist.md)
## 路线图（摘要）
- Casdoor OIDC 登录 UI/重定向流程（目前仅支持 token 验证/DEV 模式）
- 实时协作（光标/评论/基于 CRDT 的协同编辑）
- 正向工程（基于 diff 生成/验证变更 SQL）
标签：DDL生成, ERD, PostgreSQL, Snowflake, 云资产清单, 数据库工具, 测试用例, 请求拦截, 逆向工具, 逆向工程