flnxi-Wu/docs/deployment/DEPLOYMENT.md

模板系统优化 - 部署说明

概述

本文档说明如何将模板系统优化部署到生产环境。部署使用Harbor Registry和现有的 deploy-new-fixed.ps1 脚本。

部署架构

本地开发环境
    ↓ (构建镜像)
    ↓
Harbor Registry (harbor.flnxi.com)
    ↓ (拉取镜像)
    ↓
生产服务器 (45.249.208.118)

快速开始

1. 本地部署（一键）

# 在项目根目录执行
.\deploy-new-fixed.ps1 -Registry harbor

这个命令会自动：

• ✓ 运行代码检查
• ✓ 构建Docker镜像
• ✓ 推送到Harbor
• ✓ SSH到服务器部署

2. 服务器数据迁移

# SSH连接
ssh root@45.249.208.118

# 执行迁移
cd /root/deploy
docker exec flnxi-material npx prisma migrate deploy
docker exec flnxi-material npm run migrate:template-data
docker exec flnxi-material npm run verify:template-data

3. 验证

访问: http://45.249.208.118:4320/admin/templates

详细步骤

步骤 1: 部署前准备

1.1 检查代码状态

# 运行测试
npm test

# 代码检查
npm run check

# 查看Git状态
git status

确认：

• 所有测试通过（118个）
• 代码已提交
• 无未跟踪的重要文件

1.2 备份数据库

# SSH到服务器
ssh root@45.249.208.118

# 创建备份目录
mkdir -p /backup

# 备份数据库
docker exec flnxi-postgres pg_dump -U postgres -d flnxi_material -F c -b -v -f /backup/backup_$(date +%Y%m%d_%H%M%S).dump

# 验证备份文件
ls -lh /backup/

步骤 2: 构建和推送

2.1 使用部署脚本

# 基本部署
.\deploy-new-fixed.ps1 -Registry harbor

# 使用SSH密钥
.\deploy-new-fixed.ps1 `
  -Registry harbor `
  -KeyPath "C:\Users\YourUsername\.ssh\youyidian_prod_ed25519"

# 跳过代码检查（快速部署）
.\deploy-new-fixed.ps1 -Registry harbor -SkipCheck

# 清理旧镜像
.\deploy-new-fixed.ps1 -Registry harbor -CleanImages -KeepImageCount 5

2.2 脚本执行流程

1. 检查阶段 (可选)

   • 运行 npm run check
   • 验证代码质量

2. 构建阶段

   • 准备 .env.production
   • 执行 docker build
   • 验证镜像

3. 推送阶段

   • 登录Harbor
   • 推送镜像到 harbor.flnxi.com/flnxi/flnxi-material:local-deploy

4. 部署阶段

   • SSH连接到服务器
   • 拉取镜像
   • 重启应用容器

步骤 3: 数据库迁移

3.1 应用Prisma迁移

# 在服务器上执行
docker exec flnxi-material npx prisma migrate deploy

这会应用以下迁移：

• 20251201133500_add_material_kind_to_templates
• 20251202000000_add_material_kind_to_materials
• 20251202091500_add_material_ownership_fields
• 20251213073100_add_template_system_indexes

3.2 运行数据迁移脚本

# 迁移旧数据
docker exec flnxi-material npm run migrate:template-data

脚本会：

1. 检查模板version字段
2. 为没有templateId的素材分配默认模板
3. 验证数据完整性
4. 生成迁移报告

3.3 验证数据

# 验证数据完整性
docker exec flnxi-material npm run verify:template-data

验证内容：

• 模板数据完整性
• 素材templateId引用
• 字段数据完整性
• 字段池数据
• 孤立数据检查

步骤 4: 验证部署

4.1 健康检查

# 检查应用状态
curl http://45.249.208.118:4320/api/health

# 查看容器状态
docker ps | grep flnxi-material

# 查看日志
docker logs -f flnxi-material --tail 100

4.2 功能测试

访问以下页面进行测试：

1. 模板管理 (http://45.249.208.118:4320/admin/templates)

   • 页面正常加载
   • 可以查看模板列表
   • 可以创建新模板
   • 可以编辑模板字段
   • 字段拖拽排序正常

2. 素材上传 (http://45.249.208.118:4320/upload)

   • 可以选择模板
   • 自定义字段显示正确
   • 可以上传素材
   • 素材详情页正常

3. 首页筛选 (http://45.249.208.118:4320)

   • Tag按钮显示正常
   • 筛选功能正常
   • 筛选结果正确

4.3 性能检查

# 查看资源使用
docker stats flnxi-material --no-stream

# 检查响应时间
time curl -s http://45.249.208.118:4320/api/admin/upload-templates > /dev/null

预期指标：

• 模板列表加载 < 500ms
• 素材上传验证 < 100ms
• 内存使用 < 1GB
• CPU使用 < 50%

步骤 5: 监控

5.1 查看日志

# 实时日志
docker logs -f flnxi-material

# 最近100行
docker logs flnxi-material --tail 100

# 错误日志
docker logs flnxi-material 2>&1 | grep -i error

# 特定时间段
docker logs flnxi-material --since 30m

5.2 监控指标

持续监控30分钟，关注：

• 错误日志数量
• 响应时间
• 内存使用趋势
• CPU使用率
• 用户反馈

回滚方案

如果部署出现严重问题，按以下步骤回滚：

1. 立即回滚

# SSH到服务器
ssh root@45.249.208.118
cd /root/deploy

# 停止当前版本
docker-compose stop app

# 恢复数据库
docker exec flnxi-postgres pg_restore -U postgres -d flnxi_material -c /backup/backup_YYYYMMDD_HHMMSS.dump

# 拉取旧版本镜像（假设之前的tag是 previous-tag）
docker pull harbor.flnxi.com/flnxi/flnxi-material:previous-tag
docker tag harbor.flnxi.com/flnxi/flnxi-material:previous-tag flnxi-material:local-deploy

# 重启应用
docker-compose up -d app

2. 验证回滚

# 检查应用状态
curl http://45.249.208.118:4320/api/health

# 查看日志
docker logs flnxi-material --tail 50

# 验证功能
# 访问关键页面确认正常

3. 通知相关人员

• 通知技术团队回滚完成
• 通知产品团队暂停新功能使用
• 记录回滚原因和问题

常见问题

Q1: 部署脚本执行失败

症状: deploy-new-fixed.ps1 执行出错

排查步骤:

1. 检查Docker Desktop是否运行
2. 检查网络连接
3. 查看错误信息
4. 使用 -Debug 参数重新运行

解决方案:

# 启动Docker Desktop
# 然后重新运行
.\deploy-new-fixed.ps1 -Registry harbor -Debug

Q2: Harbor推送失败

症状: 推送镜像到Harbor时失败

排查步骤:

1. 检查Harbor服务是否正常
2. 验证Harbor凭据
3. 检查网络连接

解决方案:

# 手动登录测试
docker login harbor.flnxi.com -u admin -p Harbor12345

# 手动推送
docker tag flnxi-material:local-deploy harbor.flnxi.com/flnxi/flnxi-material:local-deploy
docker push harbor.flnxi.com/flnxi/flnxi-material:local-deploy

Q3: SSH连接失败

症状: 无法SSH到服务器

排查步骤:

1. 检查SSH密钥路径
2. 验证服务器地址
3. 检查防火墙设置

解决方案:

# 使用SSH密钥
.\deploy-new-fixed.ps1 `
  -Registry harbor `
  -KeyPath "C:\Users\YourUsername\.ssh\youyidian_prod_ed25519"

# 或手动SSH测试
ssh -i "C:\Users\YourUsername\.ssh\youyidian_prod_ed25519" root@45.249.208.118

Q4: 数据迁移失败

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

排查步骤:

1. 查看错误日志
2. 检查数据库连接
3. 验证数据完整性

解决方案:

# 检查数据库连接
docker exec flnxi-material npx prisma db pull

# 查看详细错误
docker exec flnxi-material npm run migrate:template-data 2>&1 | tee migration.log

# 手动修复数据后重新运行
docker exec flnxi-material npm run migrate:template-data

Q5: 应用启动失败

症状: 容器启动后立即退出

排查步骤:

1. 查看容器日志
2. 检查环境变量
3. 验证数据库连接

解决方案:

# 查看详细日志
docker logs flnxi-material

# 检查环境变量
docker exec flnxi-material env | grep DATABASE_URL

# 重启容器
docker-compose restart app

部署检查清单

部署前

• 代码已提交到Git
• 所有测试通过（118个）
• 代码检查通过
• 已创建数据库备份
• 已通知相关人员
• 已准备回滚方案

部署中

• 部署脚本执行成功
• 镜像推送到Harbor成功
• 服务器拉取镜像成功
• 应用容器启动成功
• 数据库迁移成功
• 数据验证通过

部署后

• 健康检查通过
• 功能测试通过
• 性能指标正常
• 无错误日志
• 用户反馈正常
• 监控30分钟无异常

相关文档

• 快速部署指南 - 简化的部署步骤
• 部署前检查清单 - 详细的检查清单
• 项目总结 - 完整的项目总结
• API文档 - API接口文档
• 用户手册 - 用户使用指南
• 脚本说明 - 数据迁移脚本说明

联系方式

如有问题，请联系：

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