diff --git a/backend/services/admin-service/database/README.md b/backend/services/admin-service/database/README.md new file mode 100644 index 00000000..b6d94537 --- /dev/null +++ b/backend/services/admin-service/database/README.md @@ -0,0 +1,154 @@ +# Database 目录说明 + +## 目录用途 + +`database/` 目录用于存放数据库相关的初始化脚本和迁移文件。 + +## 文件说明 + +### init.sql +**用途**: 数据库初始化脚本 + +**使用场景**: +- 在数据库首次创建后,需要插入初始数据时使用 +- 在 Docker Compose 启动时自动执行 +- 在测试环境中初始化测试数据 + +**执行方式**: +```bash +# 手动执行(如果需要) +psql -U postgres -d admin_service -f database/init.sql + +# 或通过 Docker Compose volume 映射自动执行 +``` + +## 与 Prisma 的关系 + +### Prisma Migrations +- **位置**: `prisma/migrations/` +- **用途**: 创建和管理数据库表结构 +- **执行**: `npx prisma migrate deploy` + +### database/init.sql +- **位置**: `database/init.sql` +- **用途**: 在表结构创建后,插入初始数据 +- **执行**: 在 migrations 之后手动或自动执行 + +## 执行顺序 + +正确的数据库初始化顺序: + +``` +1. Prisma Migrations (创建表结构) + ↓ +2. database/init.sql (插入初始数据) +``` + +## Docker Compose 集成 + +如果需要在 Docker Compose 中使用初始化脚本,可以这样配置: + +```yaml +services: + postgres: + image: postgres:16-alpine + volumes: + - ./database/init.sql:/docker-entrypoint-initdb.d/01-init.sql + - postgres_data:/var/lib/postgresql/data +``` + +**注意**: PostgreSQL Docker 镜像会自动执行 `/docker-entrypoint-initdb.d/` 目录中的 `.sql` 文件。 + +## 当前状态 + +### Admin Service +- ✅ Prisma schema 定义完成 +- ✅ Migrations 已创建 +- ⚠️ 目前不需要初始数据 +- ✅ init.sql 文件已创建(保留用于未来需求) + +## 使用示例 + +### 添加初始版本记录 + +如果需要在数据库初始化时插入默认版本,可以编辑 `init.sql`: + +```sql +INSERT INTO "AppVersion" ( + id, + platform, + "versionCode", + "versionName", + "buildNumber", + "downloadUrl", + "fileSize", + "fileSha256", + changelog, + "isEnabled", + "isForceUpdate", + "createdBy", + "createdAt", + "updatedAt" +) +VALUES ( + 'initial-android', + 'android', + 1, + '1.0.0', + '1', + 'https://example.com/app-v1.apk', + 10485760, + 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855', + 'Initial release', + true, + false, + 'system', + NOW(), + NOW() +) +ON CONFLICT (id) DO NOTHING; +``` + +## 参考其他服务 + +### identity-service +- 使用 `init.sql` 初始化账户序列号生成器 +- 示例: `INSERT INTO account_sequence_generator` + +### mpc-service +- 使用 `database/migrations/` 存放自定义迁移 + +## 最佳实践 + +1. **幂等性**: 所有 SQL 脚本都应该是幂等的(可重复执行) + - 使用 `ON CONFLICT DO NOTHING` + - 使用 `IF NOT EXISTS` + +2. **注释**: 为所有初始化脚本添加清晰的注释 + +3. **版本控制**: 将 `database/` 目录纳入 Git 版本控制 + +4. **测试**: 确保初始化脚本在测试环境中正常工作 + +## 故障排查 + +### 初始化脚本未执行 + +**原因**: PostgreSQL 只在首次创建数据库时执行 initdb 脚本 + +**解决方案**: +```bash +# 删除 volume 重新创建 +docker-compose down -v +docker-compose up +``` + +### 重复执行错误 + +**原因**: 脚本不是幂等的 + +**解决方案**: 使用 `ON CONFLICT` 或 `IF NOT EXISTS` + +--- + +*最后更新: 2025-12-03* diff --git a/backend/services/admin-service/database/init.sql b/backend/services/admin-service/database/init.sql new file mode 100644 index 00000000..14261b97 --- /dev/null +++ b/backend/services/admin-service/database/init.sql @@ -0,0 +1,14 @@ +-- ============================================ +-- Admin Service 数据库初始化 (PostgreSQL) +-- ============================================ + +-- 此文件用于在数据库首次创建时初始化必要的数据 +-- 由 Prisma migrations 创建表结构后执行 + +-- 示例:插入初始版本记录(如果需要) +-- INSERT INTO "AppVersion" (id, platform, "versionCode", "versionName", "buildNumber", "downloadUrl", "fileSize", "fileSha256", changelog, "isEnabled", "isForceUpdate", "createdBy", "createdAt", "updatedAt") +-- VALUES ('initial-version-id', 'android', 1, '1.0.0', '1', 'https://example.com/app.apk', 10485760, 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855', 'Initial version', true, false, 'system', NOW(), NOW()) +-- ON CONFLICT (id) DO NOTHING; + +-- 注意:目前 admin-service 不需要初始数据 +-- 此文件保留用于未来可能的初始化需求