108 lines
4.1 KiB
Markdown
108 lines
4.1 KiB
Markdown
# 数据库脚本（版本化迁移）
|
||
|
||
## 目录结构
|
||
|
||
- `migrations/`：按版本顺序的升级脚本（只增不改）
|
||
- `rollback/`：与 migration 一一对应的回滚脚本（按版本号匹配）
|
||
- `migrate.sh`：按顺序执行未应用的 migrations
|
||
- `rollback.sh`：按版本回滚（需要显式确认）
|
||
- `verify.sh`：执行校验脚本，确认表结构与种子数据满足要求
|
||
- `reset.sh`：开发/测试用清库重置（会删除所有 IAM 表与迁移记录，需显式确认）
|
||
- `rebuild_iam_db.sh`：开发环境一键重建（会清库重建，不适合生产）
|
||
|
||
## 版本与执行顺序
|
||
|
||
| 版本 | 脚本 | 说明 |
|
||
|---|---|---|
|
||
| 0001 | `migrations/0001_core.sql` | IAM 核心表（tenant/user/role/permission 等）与基础种子数据 |
|
||
| 0002 | `migrations/0002_enabled_apps.sql` | enabled_apps（租户应用开通）、平台租户与平台权限（SuperAdmin） |
|
||
| 0003 | `migrations/0003_app_lifecycle.sql` | apps 生命周期管理（扩展字段、变更记录、上下线审批） |
|
||
| 0004 | `migrations/0004_password_reset.sql` | 密码重置（权限码与 Admin/SuperAdmin 授权） |
|
||
| 0005 | `migrations/0005_refresh_token_fingerprint.sql` | refresh token 指纹索引（支持刷新时安全查找） |
|
||
| 0006 | `migrations/0006_cms_permissions.sql` | CMS 最小必要权限（permissions 种子） |
|
||
|
||
校验脚本映射（与 migrations 一一对应）：
|
||
|
||
| 版本 | 校验脚本 | 说明 |
|
||
|---|---|---|
|
||
| 0001 | `scripts/db/verify/0001_core.sql` | 校验核心表、索引与基础种子 |
|
||
| 0002 | `scripts/db/verify/0002_enabled_apps.sql` | 校验 enabled_apps 相关表与平台种子 |
|
||
| 0003 | `scripts/db/verify/0003_app_lifecycle.sql` | 校验 apps 生命周期管理相关表与权限种子 |
|
||
| 0004 | `scripts/db/verify/0004_password_reset.sql` | 校验密码重置权限码种子 |
|
||
| 0005 | `scripts/db/verify/0005_refresh_token_fingerprint.sql` | 校验 refresh_tokens 指纹字段 |
|
||
| 0006 | `scripts/db/verify/0006_cms_permissions.sql` | 校验 CMS 权限种子 |
|
||
|
||
## 执行方式
|
||
|
||
环境变量：
|
||
- `DATABASE_URL`：必填（也可放在项目根目录 `.env` 中）
|
||
依赖：
|
||
- 需要安装 PostgreSQL 客户端工具（`psql`）；可选 `pg_dump`（仅当你要做备份）。
|
||
|
||
执行迁移：
|
||
|
||
```bash
|
||
./scripts/db/migrate.sh
|
||
./scripts/db/verify.sh
|
||
```
|
||
|
||
开发/测试环境清库重置（危险）：
|
||
|
||
```bash
|
||
CONFIRM=1 ./scripts/db/reset.sh
|
||
```
|
||
|
||
回滚到指定版本（示例：回滚到 0001）：
|
||
|
||
```bash
|
||
CONFIRM=1 TARGET_VERSION=0001 ./scripts/db/rollback.sh
|
||
./scripts/db/verify.sh
|
||
```
|
||
|
||
验证步骤
|
||
|
||
- 执行 `./scripts/db/verify.sh`，应无错误退出
|
||
- 启动服务后通过 Scalar 访问 `/scalar`，检查 OpenAPI 中包含：
|
||
- `/platform/tenants/{tenant_id}/enabled-apps`
|
||
- `/users/{id}/roles`
|
||
|
||
## 首次环境准备（DB/User）
|
||
|
||
在具有足够权限的数据库账号下执行（示例）：
|
||
|
||
```sql
|
||
CREATE USER iam_service_user WITH PASSWORD 'iam_service_password';
|
||
CREATE DATABASE iam_service_db OWNER iam_service_user;
|
||
GRANT ALL PRIVILEGES ON DATABASE iam_service_db TO iam_service_user;
|
||
```
|
||
|
||
说明：
|
||
- 生产环境不要在仓库内硬编码密码；应由密钥管理系统注入并轮换。
|
||
- 如需启用扩展（如 `uuid-ossp`），请确认应用账号是否有权限，或由 DBA 预先安装。
|
||
|
||
## 常见问题
|
||
|
||
### `.env` 配了 DATABASE_URL 但脚本报 “DATABASE_URL is required”
|
||
|
||
`.env` 只是文件，不会自动变成进程环境变量。Rust 程序会通过 `dotenvy` 读取 `.env`，但 bash 脚本默认不会。
|
||
|
||
解决方式：
|
||
- 直接 `export DATABASE_URL=...` 后再执行脚本；或
|
||
- 保持项目根目录存在 `.env`，脚本会尝试读取其中的 `DATABASE_URL`。
|
||
|
||
### 执行脚本报 “psql not found”
|
||
|
||
原因：系统未安装 PostgreSQL 客户端工具（`psql`/`pg_dump`），或不在 `PATH` 中。
|
||
|
||
安装方式：
|
||
- Ubuntu/Debian：`sudo apt-get update && sudo apt-get install -y postgresql-client`
|
||
- RHEL/CentOS/Fedora：`sudo dnf install -y postgresql`
|
||
- Alpine：`sudo apk add postgresql-client`
|
||
- macOS（Homebrew）：`brew install libpq && brew link --force libpq`
|
||
|
||
验证方式：
|
||
|
||
```bash
|
||
psql --version
|
||
```
|