flnxi-Wu/docs/deployment/pre-deployment-checklist.md

模板系统优化 - 部署前检查清单

概述

本文档提供了部署模板系统优化到测试和生产环境的完整检查清单。

部署前准备

1. 代码检查

• 所有代码已提交到Git仓库
• 所有单元测试通过（118个测试用例）
• 代码已通过TypeScript类型检查
• 代码已通过ESLint检查
• 核心功能代码覆盖率达标（>80%）

# 运行检查
npm run check
npm test

2. 数据库准备

• 已创建数据库备份
• 已检查数据库迁移文件
• 已在本地测试数据库迁移
• 已准备回滚脚本

# 检查迁移文件
ls prisma/migrations

# 验证schema
npm run prisma:validate

3. 数据迁移准备

• 已准备数据迁移脚本（migrate-template-data.ts）
• 已准备数据验证脚本（verify-template-data.ts）
• 已在测试数据上验证迁移脚本
• 已准备迁移失败的回滚方案

# 测试迁移脚本（在测试环境）
npm run migrate:template-data

# 验证数据完整性
npm run verify:template-data

4. 文档检查

• API文档已更新（docs/api/template-system-api.md）
• 用户手册已更新（docs/user-guide/template-system-guide.md）
• 部署文档已准备
• 回滚文档已准备

测试环境部署

步骤 1: 备份数据库

# PostgreSQL备份示例
pg_dump -h <host> -U <user> -d <database> -F c -b -v -f backup_$(date +%Y%m%d_%H%M%S).dump

# 或使用Prisma Studio导出关键数据
npm run prisma:studio

步骤 2: 运行数据库迁移

# 生成Prisma客户端
npm run prisma:generate

# 应用数据库迁移
npx prisma migrate deploy

# 验证迁移结果
npm run verify:template-data

步骤 3: 运行数据迁移脚本

# 迁移旧数据
npm run migrate:template-data

# 再次验证数据完整性
npm run verify:template-data

步骤 4: 部署新代码

# 构建应用
npm run build

# 启动应用
npm start

# 或使用Docker
docker-compose up -d

步骤 5: 执行冒烟测试

5.1 模板管理测试

• 访问模板管理页面（/admin/templates）
• 创建新模板
• 编辑模板字段
• 测试字段拖拽排序
• 测试select字段选项管理
• 删除测试模板

5.2 素材上传测试

• 访问素材上传页面
• 选择模板
• 填写自定义字段
• 上传素材文件
• 验证素材详情页显示

5.3 字段池同步测试

• 创建带有select字段的模板
• 验证字段池自动同步
• 访问分类管理页面
• 验证字段和选项显示正确

5.4 首页筛选测试

• 访问首页
• 验证Tag按钮显示
• 测试单选筛选
• 测试多选筛选
• 验证筛选结果正确

5.5 性能测试

• 模板列表加载时间 < 500ms
• 素材上传验证时间 < 100ms
• 字段池同步时间 < 1s
• 首页Tag按钮响应时间 < 100ms

步骤 6: 监控和日志

# 查看应用日志
docker logs -f <container_name>

# 或使用PM2
pm2 logs

# 监控数据库性能
# 检查慢查询日志

生产环境部署

部署前最终检查

• 测试环境已稳定运行至少24小时
• 所有冒烟测试通过
• 没有发现严重bug
• 性能指标达标
• 已通知相关人员部署计划
• 已准备回滚方案

部署窗口

• 推荐时间: 非业务高峰期（如凌晨2-6点）
• 预计时长: 30-60分钟
• 回滚时间: 15分钟

部署步骤

与测试环境部署步骤相同，但需要额外注意：

1. 数据库备份: 必须创建完整备份
2. 灰度发布: 如果可能，先部署到部分服务器
3. 监控: 密切监控系统指标和错误日志
4. 用户通知: 如需停机，提前通知用户

部署后验证

• 所有冒烟测试通过
• 数据完整性验证通过
• 性能指标正常
• 错误日志无异常
• 用户反馈正常

回滚方案

何时回滚

• 发现严重bug影响核心功能
• 性能严重下降
• 数据完整性问题
• 用户无法正常使用

回滚步骤

1. 停止应用

   docker-compose down
   # 或
   pm2 stop all
   

2. 恢复数据库

   # PostgreSQL恢复示例
   pg_restore -h <host> -U <user> -d <database> -v backup_YYYYMMDD_HHMMSS.dump
   

3. 部署旧版本代码

   git checkout <previous_version>
   npm run build
   npm start
   

4. 验证回滚

   • 检查应用是否正常运行
   • 验证数据完整性
   • 执行基本功能测试

监控指标

应用指标

• 响应时间
• 错误率
• 请求量
• CPU使用率
• 内存使用率

数据库指标

• 查询响应时间
• 连接数
• 慢查询数量
• 锁等待时间

业务指标

• 模板创建数量
• 素材上传数量
• 字段池同步次数
• 用户活跃度

常见问题处理

问题 1: 数据迁移失败

症状: migrate-template-data.ts 执行失败

解决方案:

1. 检查错误日志
2. 验证数据库连接
3. 检查数据完整性
4. 手动修复问题数据
5. 重新运行迁移脚本

问题 2: 字段池同步失败

症状: 分类管理页面显示不正确

解决方案:

1. 检查字段池同步日志
2. 手动触发同步：调用 /api/admin/sync-field-pool
3. 验证字段定义和选项

问题 3: 性能下降

症状: 页面加载缓慢

解决方案:

1. 检查数据库索引是否正确创建
2. 检查慢查询日志
3. 优化查询语句
4. 增加缓存

问题 4: 版本冲突

症状: 模板更新时出现409错误

解决方案:

1. 这是正常的并发控制机制
2. 提示用户刷新页面重新编辑
3. 检查是否有多人同时编辑

联系人

• 技术负责人: [姓名] - [联系方式]
• 运维负责人: [姓名] - [联系方式]
• 产品负责人: [姓名] - [联系方式]

附录

A. 数据库迁移文件列表

prisma/migrations/
├── 20251201133500_add_material_kind_to_templates/
├── 20251202000000_add_material_kind_to_materials/
├── 20251202091500_add_material_ownership_fields/
└── 20251213073100_add_template_system_indexes/

B. 关键API端点

• GET /api/admin/upload-templates - 获取模板列表
• POST /api/admin/upload-templates - 创建模板
• GET /api/admin/upload-templates/[id] - 获取模板详情
• PUT /api/admin/upload-templates/[id] - 更新模板
• DELETE /api/admin/upload-templates/[id] - 删除模板
• POST /api/admin/sync-field-pool - 同步字段池

C. 环境变量检查

# 必需的环境变量
DATABASE_URL=postgresql://...
NEXTAUTH_SECRET=...
NEXTAUTH_URL=...
S3_ENDPOINT=...
S3_ACCESS_KEY_ID=...
S3_SECRET_ACCESS_KEY=...
S3_BUCKET_NAME=...

D. 性能基准

操作	目标时间	可接受时间
模板列表加载	< 300ms	< 500ms
模板详情加载	< 200ms	< 400ms
素材上传验证	< 50ms	< 100ms
字段池同步	< 500ms	< 1s
首页Tag响应	< 50ms	< 100ms