418aa57ea8
一、超管端设计优化 - 文档管理SOP体系建立，docs目录重组 - 统一用户管理：跨租户全局视角，合并用户管理+公众用户 - 活动监管全模块重构：全部活动（统计卡片+阶段筛选+SuperDetail详情页）、报名数据/作品数据/评审进度（两层合一扁平列表）、成果发布（去Tab+统计+隐藏写操作） - 菜单精简：移除评委管理/评审规则/通知管理 - Bug修复：租户编辑丢失隐藏菜单、pageSize限制、主色统一 二、UGC绘本创作社区P0 - 数据库：10张新表（user_works/user_work_pages/work_tags等） - 子女账号独立化：Child升级为独立User，家长切换+独立登录 - 用户作品库：CRUD+发布审核，8个API - AI创作流程：提交→生成→保存到作品库，4个API - 作品广场：首页改造为推荐流，标签+搜索+排序 - 内容审核（超管端）：作品审核+作品管理+标签管理 - 活动联动：WorkSelector作品选择器 - 布局改造：底部5Tab（发现/创作/活动/作品库/我的） Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
313 lines
7.5 KiB
Markdown
313 lines
7.5 KiB
Markdown
# Prisma 增量迁移指南
|
||
|
||
## 📋 概述
|
||
|
||
Prisma 的迁移机制**已经内置了增量执行功能**。当你运行迁移命令时，Prisma 会自动：
|
||
|
||
- ✅ 只执行**新增的、未应用的**迁移
|
||
- ✅ **跳过**已经执行过的迁移
|
||
- ✅ 通过 `_prisma_migrations` 表跟踪迁移状态
|
||
|
||
---
|
||
|
||
## 🔍 Prisma 如何跟踪迁移状态
|
||
|
||
Prisma 在数据库中维护一个特殊的表 `_prisma_migrations`，用于记录：
|
||
|
||
- 迁移名称（migration_name）
|
||
- 应用时间（applied_at）
|
||
- 迁移文件内容（checksum）
|
||
- 其他元数据
|
||
|
||
每次迁移执行后，Prisma 会在这个表中记录一条记录，确保不会重复执行。
|
||
|
||
---
|
||
|
||
## 🚀 迁移命令对比
|
||
|
||
### 1. `prisma migrate deploy`（生产环境推荐）
|
||
|
||
**特点**：
|
||
|
||
- ✅ **只执行未应用的迁移**
|
||
- ✅ 不会创建新迁移
|
||
- ✅ 不会重置数据库
|
||
- ✅ 适合生产环境
|
||
|
||
**使用场景**：
|
||
|
||
- 生产环境部署
|
||
- CI/CD 流程
|
||
- 多环境同步
|
||
|
||
**示例**：
|
||
|
||
```bash
|
||
# 生产环境
|
||
npm run prisma:migrate:deploy
|
||
|
||
# 或直接使用
|
||
NODE_ENV=production prisma migrate deploy
|
||
```
|
||
|
||
**执行逻辑**：
|
||
|
||
1. 读取 `prisma/migrations` 目录中的所有迁移文件
|
||
2. 查询数据库中的 `_prisma_migrations` 表
|
||
3. 对比找出未应用的迁移
|
||
4. **只执行未应用的迁移**
|
||
5. 在 `_prisma_migrations` 表中记录新应用的迁移
|
||
|
||
---
|
||
|
||
### 2. `prisma migrate dev`（开发环境推荐）
|
||
|
||
**特点**：
|
||
|
||
- ✅ 创建新迁移（如果有 schema 变更）
|
||
- ✅ **只执行未应用的迁移**
|
||
- ✅ 可能会重置开发数据库（如果使用 shadow database）
|
||
- ✅ 适合开发环境
|
||
|
||
**使用场景**：
|
||
|
||
- 本地开发
|
||
- Schema 变更后创建迁移
|
||
|
||
**示例**：
|
||
|
||
```bash
|
||
# 开发环境
|
||
npm run prisma:migrate
|
||
|
||
# 或直接使用
|
||
prisma migrate dev
|
||
```
|
||
|
||
**执行逻辑**：
|
||
|
||
1. 检查 schema.prisma 是否有变更
|
||
2. 如果有变更，创建新迁移文件
|
||
3. 查询 `_prisma_migrations` 表找出未应用的迁移
|
||
4. **只执行未应用的迁移**（包括新创建的）
|
||
5. 记录到 `_prisma_migrations` 表
|
||
|
||
---
|
||
|
||
## 📊 查看迁移状态
|
||
|
||
### 检查哪些迁移已应用
|
||
|
||
```bash
|
||
# 查看迁移状态
|
||
npx prisma migrate status
|
||
|
||
# 输出示例：
|
||
# ✅ Database schema is up to date!
|
||
#
|
||
# The following migrations have been applied:
|
||
# - 20251118035205_init
|
||
# - 20251118041000_add_comments
|
||
# - 20251118211424_change_log_content_to_text
|
||
```
|
||
|
||
### 直接查询数据库
|
||
|
||
```sql
|
||
-- 查看所有已应用的迁移
|
||
SELECT * FROM _prisma_migrations ORDER BY applied_at DESC;
|
||
|
||
-- 查看迁移名称和状态
|
||
SELECT migration_name, applied_at, finished_at
|
||
FROM _prisma_migrations
|
||
ORDER BY applied_at DESC;
|
||
```
|
||
|
||
---
|
||
|
||
## 🎯 实际使用场景
|
||
|
||
### 场景 1：生产环境部署
|
||
|
||
**情况**：生产数据库已经有部分迁移，现在要部署新版本
|
||
|
||
```bash
|
||
# 1. 部署新代码（包含新的迁移文件）
|
||
|
||
# 2. 运行迁移（只会执行新增的迁移）
|
||
npm run prisma:migrate:deploy
|
||
|
||
# Prisma 会自动：
|
||
# - 检查 _prisma_migrations 表
|
||
# - 找出未应用的迁移（如：20251120000000_new_feature）
|
||
# - 只执行这个新迁移
|
||
# - 跳过已执行的迁移（如：20251118035205_init）
|
||
```
|
||
|
||
**结果**：
|
||
|
||
- ✅ 已执行的迁移不会重复执行
|
||
- ✅ 只执行新增的迁移
|
||
- ✅ 数据库结构同步到最新状态
|
||
|
||
---
|
||
|
||
### 场景 2：多环境同步
|
||
|
||
**情况**：开发环境有 3 个迁移，生产环境只有 2 个
|
||
|
||
```bash
|
||
# 开发环境迁移：
|
||
# - 20251118035205_init ✅
|
||
# - 20251118041000_add_comments ✅
|
||
# - 20251118211424_change_log_content_to_text ✅
|
||
|
||
# 生产环境迁移：
|
||
# - 20251118035205_init ✅
|
||
# - 20251118041000_add_comments ✅
|
||
# - 20251118211424_change_log_content_to_text ❌（未应用）
|
||
|
||
# 在生产环境运行：
|
||
npm run prisma:migrate:deploy
|
||
|
||
# Prisma 会：
|
||
# - 跳过前两个已应用的迁移
|
||
# - 只执行最后一个未应用的迁移
|
||
```
|
||
|
||
---
|
||
|
||
### 场景 3：回滚和修复
|
||
|
||
**情况**：某个迁移执行失败，需要修复
|
||
|
||
```bash
|
||
# 1. 检查迁移状态
|
||
npx prisma migrate status
|
||
|
||
# 2. 如果迁移失败，_prisma_migrations 表中不会有记录
|
||
# 3. 修复迁移文件后，重新运行
|
||
npm run prisma:migrate:deploy
|
||
|
||
# Prisma 会：
|
||
# - 检查失败的迁移是否已记录
|
||
# - 如果没有记录，会重新执行
|
||
# - 如果已记录，会跳过
|
||
```
|
||
|
||
---
|
||
|
||
## ⚠️ 注意事项
|
||
|
||
### 1. 不要手动修改 `_prisma_migrations` 表
|
||
|
||
这个表由 Prisma 自动管理，手动修改可能导致迁移状态不一致。
|
||
|
||
### 2. 迁移文件不要删除
|
||
|
||
即使迁移已执行，也不要删除 `prisma/migrations` 目录中的迁移文件。这些文件是迁移历史的一部分。
|
||
|
||
### 3. 生产环境使用 `migrate deploy`
|
||
|
||
```bash
|
||
# ✅ 正确：生产环境
|
||
prisma migrate deploy
|
||
|
||
# ❌ 错误：生产环境不要使用
|
||
prisma migrate dev # 可能会重置数据库
|
||
```
|
||
|
||
### 4. 迁移文件顺序很重要
|
||
|
||
Prisma 按照迁移文件名（时间戳）的顺序执行迁移。确保迁移文件名的时间戳顺序正确。
|
||
|
||
---
|
||
|
||
## 🔧 故障排查
|
||
|
||
### 问题 1：迁移状态不一致
|
||
|
||
**症状**：`prisma migrate status` 显示状态不一致
|
||
|
||
**解决**：
|
||
|
||
```bash
|
||
# 1. 检查 _prisma_migrations 表
|
||
SELECT * FROM _prisma_migrations;
|
||
|
||
# 2. 检查迁移文件
|
||
ls -la prisma/migrations/
|
||
|
||
# 3. 如果迁移文件存在但未记录，手动标记（谨慎操作）
|
||
# 或者重新运行迁移
|
||
prisma migrate deploy
|
||
```
|
||
|
||
### 问题 2：迁移重复执行
|
||
|
||
**症状**：迁移被重复执行
|
||
|
||
**原因**：`_prisma_migrations` 表中没有记录
|
||
|
||
**解决**：
|
||
|
||
```bash
|
||
# 检查迁移记录
|
||
npx prisma migrate status
|
||
|
||
# 如果显示迁移未应用，但数据库结构已存在
|
||
# 可能需要手动标记迁移为已应用（谨慎操作）
|
||
```
|
||
|
||
### 问题 3：迁移文件丢失
|
||
|
||
**症状**：迁移文件被删除，但数据库中有记录
|
||
|
||
**解决**：
|
||
|
||
```bash
|
||
# 1. 从版本控制恢复迁移文件
|
||
git checkout prisma/migrations/
|
||
|
||
# 2. 重新运行迁移检查
|
||
npx prisma migrate status
|
||
```
|
||
|
||
---
|
||
|
||
## 📚 相关命令速查
|
||
|
||
| 命令 | 说明 | 使用场景 |
|
||
| ----------------------- | ---------------------- | -------- |
|
||
| `prisma migrate deploy` | 只执行未应用的迁移 | 生产环境 |
|
||
| `prisma migrate dev` | 创建并执行迁移 | 开发环境 |
|
||
| `prisma migrate status` | 查看迁移状态 | 所有环境 |
|
||
| `prisma migrate reset` | 重置数据库（开发环境） | 开发环境 |
|
||
| `prisma db push` | 直接同步 schema | 快速原型 |
|
||
|
||
---
|
||
|
||
## ✅ 总结
|
||
|
||
**Prisma 迁移机制的核心特点**：
|
||
|
||
1. ✅ **自动增量执行**：只执行未应用的迁移
|
||
2. ✅ **状态跟踪**：通过 `_prisma_migrations` 表跟踪
|
||
3. ✅ **安全可靠**：不会重复执行已应用的迁移
|
||
4. ✅ **环境区分**：`migrate deploy` 用于生产，`migrate dev` 用于开发
|
||
|
||
**最佳实践**：
|
||
|
||
- 🎯 生产环境：使用 `prisma migrate deploy`
|
||
- 🎯 开发环境：使用 `prisma migrate dev`
|
||
- 🎯 定期检查：使用 `prisma migrate status` 查看状态
|
||
- 🎯 版本控制：提交所有迁移文件到 Git
|
||
|
||
---
|
||
|
||
## 🔗 相关文档
|
||
|
||
- [Prisma 官方迁移文档](https://www.prisma.io/docs/concepts/components/prisma-migrate)
|
||
- [SCHEMA_CHANGE_GUIDE.md](./SCHEMA_CHANGE_GUIDE.md) - Schema 修改指南
|
||
- [DATABASE_SETUP.md](./DATABASE_SETUP.md) - 数据库设置指南
|