数据库脚本（版本化迁移）
目录结构
migrations/：按版本顺序的升级脚本（只增不改）rollback/：与 migration 一一对应的回滚脚本（按版本号匹配）migrate.sh：按顺序执行未应用的 migrationsrollback.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 授权） |
校验脚本映射（与 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 |
校验密码重置权限码种子 |
执行方式
环境变量：
DATABASE_URL：必填（也可放在项目根目录.env中） 依赖：- 需要安装 PostgreSQL 客户端工具（
psql）；可选pg_dump（仅当你要做备份）。
执行迁移：
./scripts/db/migrate.sh
./scripts/db/verify.sh
开发/测试环境清库重置（危险）：
CONFIRM=1 ./scripts/db/reset.sh
回滚到指定版本（示例：回滚到 0001）：
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）
在具有足够权限的数据库账号下执行（示例）：
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
验证方式：
psql --version