flnxi-Wu/docs/deployment/DEPLOYMENT.md

# 模板系统优化 - 部署说明

## 概述

本文档说明如何将模板系统优化部署到生产环境。部署使用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) - 数据迁移脚本说明

## 联系方式

如有问题，请联系：
- **技术负责人**: [姓名] - [联系方式]
- **运维负责人**: [姓名] - [联系方式]
- **产品负责人**: [姓名] - [联系方式]