# 模板系统优化 - 部署说明 ## 概述 本文档说明如何将模板系统优化部署到生产环境。部署使用Harbor Registry和现有的 `deploy-new-fixed.ps1` 脚本。 ## 部署架构 ``` 本地开发环境 ↓ (构建镜像) ↓ Harbor Registry (harbor.flnxi.com) ↓ (拉取镜像) ↓ 生产服务器 (45.249.208.118) ``` ## 快速开始 ### 1. 本地部署（一键） ```powershell # 在项目根目录执行 .\deploy-new-fixed.ps1 -Registry harbor ``` 这个命令会自动： - ✓ 运行代码检查 - ✓ 构建Docker镜像 - ✓ 推送到Harbor - ✓ SSH到服务器部署 ### 2. 服务器数据迁移 ```bash # 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 检查代码状态 ```powershell # 运行测试 npm test # 代码检查 npm run check # 查看Git状态 git status ``` 确认： - [ ] 所有测试通过（118个） - [ ] 代码已提交 - [ ] 无未跟踪的重要文件 #### 1.2 备份数据库 ```bash # 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 使用部署脚本 ```powershell # 基本部署 .\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迁移 ```bash # 在服务器上执行 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 运行数据迁移脚本 ```bash # 迁移旧数据 docker exec flnxi-material npm run migrate:template-data ``` 脚本会： 1. 检查模板version字段 2. 为没有templateId的素材分配默认模板 3. 验证数据完整性 4. 生成迁移报告 #### 3.3 验证数据 ```bash # 验证数据完整性 docker exec flnxi-material npm run verify:template-data ``` 验证内容： - 模板数据完整性 - 素材templateId引用 - 字段数据完整性 - 字段池数据 - 孤立数据检查 ### 步骤 4: 验证部署 #### 4.1 健康检查 ```bash # 检查应用状态 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 性能检查 ```bash # 查看资源使用 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 查看日志 ```bash # 实时日志 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. 立即回滚 ```bash # 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. 验证回滚 ```bash # 检查应用状态 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` 参数重新运行 **解决方案**: ```powershell # 启动Docker Desktop # 然后重新运行 .\deploy-new-fixed.ps1 -Registry harbor -Debug ``` ### Q2: Harbor推送失败 **症状**: 推送镜像到Harbor时失败 **排查步骤**: 1. 检查Harbor服务是否正常 2. 验证Harbor凭据 3. 检查网络连接 **解决方案**: ```powershell # 手动登录测试 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. 检查防火墙设置 **解决方案**: ```powershell # 使用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. 验证数据完整性 **解决方案**: ```bash # 检查数据库连接 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. 验证数据库连接 **解决方案**: ```bash # 查看详细日志 docker logs flnxi-material # 检查环境变量 docker exec flnxi-material env | grep DATABASE_URL # 重启容器 docker-compose restart app ``` ## 部署检查清单 ### 部署前 - [ ] 代码已提交到Git - [ ] 所有测试通过（118个） - [ ] 代码检查通过 - [ ] 已创建数据库备份 - [ ] 已通知相关人员 - [ ] 已准备回滚方案 ### 部署中 - [ ] 部署脚本执行成功 - [ ] 镜像推送到Harbor成功 - [ ] 服务器拉取镜像成功 - [ ] 应用容器启动成功 - [ ] 数据库迁移成功 - [ ] 数据验证通过 ### 部署后 - [ ] 健康检查通过 - [ ] 功能测试通过 - [ ] 性能指标正常 - [ ] 无错误日志 - [ ] 用户反馈正常 - [ ] 监控30分钟无异常 ## 相关文档 - [快速部署指南](./quick-deployment-guide.md) - 简化的部署步骤 - [部署前检查清单](./pre-deployment-checklist.md) - 详细的检查清单 - [项目总结](../template-system-optimization-summary.md) - 完整的项目总结 - [API文档](../api/template-system-api.md) - API接口文档 - [用户手册](../user-guide/template-system-guide.md) - 用户使用指南 - [脚本说明](../../scripts/README.md) - 数据迁移脚本说明 ## 联系方式 如有问题，请联系： - **技术负责人**: [姓名] - [联系方式] - **运维负责人**: [姓名] - [联系方式] - **产品负责人**: [姓名] - [联系方式]