# 模板系统优化 - 快速部署指南

## 使用Harbor部署（推荐）

本项目使用 `deploy-new-fixed.ps1` 脚本通过Harbor进行部署。

### 部署步骤

#### 1. 本地构建并推送到Harbor

```powershell
# 使用Harbor部署（默认）
.\deploy-new-fixed.ps1 -Registry harbor

# 或指定Harbor配置
.\deploy-new-fixed.ps1 `
  -Registry harbor `
  -HarborUrl "harbor.flnxi.com" `
  -HarborProjectName "flnxi" `
  -HarborUsername "admin" `
  -HarborPassword "Harbor12345"
```

**脚本会自动完成**:
- ✓ 代码检查（npm run check）
- ✓ Docker镜像构建
- ✓ 推送到Harbor Registry
- ✓ SSH连接到服务器
- ✓ 拉取镜像并部署

#### 2. 服务器上执行数据库迁移

部署完成后，SSH连接到服务器执行数据库迁移：

```bash
# SSH连接到服务器
ssh root@45.249.208.118

# 进入部署目录
cd /root/deploy

# 应用数据库迁移（Prisma）
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
- 管理后台: http://45.249.208.118:4320/admin
- 模板管理: http://45.249.208.118:4320/admin/templates

快速测试：
- [ ] 模板管理页面正常
- [ ] 创建新模板
- [ ] 上传素材测试
- [ ] 首页筛选功能正常

## 部署参数说明

### 常用参数

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

# 只构建不部署（测试构建）
.\deploy-new-fixed.ps1 -SkipUpload

# 清理旧镜像（节省空间）
.\deploy-new-fixed.ps1 -CleanImages -KeepImageCount 5

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

### 完整参数列表

```powershell
-Server              # 服务器地址（默认: 45.249.208.118）
-Username            # SSH用户名（默认: root）
-KeyPath             # SSH密钥路径
-Registry            # Registry类型: harbor 或 default（默认: harbor）
-HarborUrl           # Harbor地址（默认: harbor.flnxi.com）
-HarborProjectName   # Harbor项目名称（默认: flnxi）
-HarborUsername      # Harbor用户名（默认: admin）
-HarborPassword      # Harbor密码
-SkipCheck           # 跳过代码检查
-SkipBuild           # 跳过Docker构建
-SkipUpload          # 跳过推送和部署
-CleanImages         # 清理旧镜像
-KeepImageCount      # 保留镜像数量（默认: 5）
-Debug               # 调试模式
-Help                # 显示帮助
```

## 生产环境部署注意事项

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

### 部署前检查

- [ ] 代码已提交并推送到Git
- [ ] 所有测试通过（118个单元测试）
- [ ] 已在测试环境验证
- [ ] 已创建数据库备份
- [ ] 已通知相关人员

### 数据库备份

```bash
# SSH到服务器
ssh root@45.249.208.118

# 备份数据库
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

# 或使用外部备份
pg_dump -h 45.249.208.118 -U postgres -d flnxi_material -F c -f backup_$(date +%Y%m%d_%H%M%S).dump
```

### 部署流程

1. **本地构建推送**
   ```powershell
   .\deploy-new-fixed.ps1 -Registry harbor
   ```

2. **服务器数据迁移**
   ```bash
   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. **验证部署**
   - 检查应用是否正常运行
   - 执行冒烟测试
   - 查看日志确认无错误

4. **监控观察**
   - 持续监控30分钟
   - 关注错误日志
   - 收集用户反馈

## 回滚方案

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

### 1. 停止当前版本

```bash
ssh root@45.249.208.118
cd /root/deploy
docker-compose stop app
```

### 2. 恢复数据库

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

### 3. 部署旧版本

```bash
# 拉取旧版本镜像
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
```

### 4. 验证回滚

- 检查应用是否正常
- 验证数据完整性
- 确认功能正常

## 常见问题

### Q: Docker构建失败？
**A**: 检查 `.env.production` 文件是否存在，或使用 `-EnvFile` 参数指定环境变量文件。

### Q: SSH连接失败？
**A**: 使用 `-KeyPath` 参数指定SSH密钥路径，或检查SSH密钥权限。

### Q: Harbor推送失败？
**A**: 检查Harbor凭据是否正确，确认Harbor服务是否正常运行。

### Q: 数据迁移失败？
**A**: 查看错误日志，检查数据库连接，必要时手动修复数据后重新运行。

### Q: 健康检查超时？
**A**: 应用可能需要更长时间启动，手动访问 http://45.249.208.118:4320/api/health 确认。

## 查看日志

```bash
# 应用日志
docker logs -f flnxi-material

# 数据库日志
docker logs -f flnxi-postgres

# 实时监控
docker stats flnxi-material
```

## 需要帮助？

- 完整检查清单: `docs/deployment/pre-deployment-checklist.md`
- 项目总结: `docs/template-system-optimization-summary.md`
- API文档: `docs/api/template-system-api.md`
- 用户手册: `docs/user-guide/template-system-guide.md`