1818web-hoduan/DEPLOYMENT_CHECKLIST.md

# RunningHub集成部署检查清单

**版本：** v2.1.0  
**日期：** 2025-10-20

---

## ✅ 部署前检查

### 1. 代码文件完整性

- [ ] **Provider核心接口** (5个文件)
  - [ ] `src/main/java/com/dora/service/provider/AIProvider.java`
  - [ ] `src/main/java/com/dora/dto/provider/ProviderTaskRequest.java`
  - [ ] `src/main/java/com/dora/dto/provider/ProviderTaskResponse.java`
  - [ ] `src/main/java/com/dora/dto/provider/ProviderTaskStatus.java`
  - [ ] `src/main/java/com/dora/dto/provider/ProviderTaskResult.java`

- [ ] **Provider实现** (2个文件)
  - [ ] `src/main/java/com/dora/service/provider/impl/OpenAIProviderImpl.java`
  - [ ] `src/main/java/com/dora/service/provider/impl/RunningHubProviderImpl.java`

- [ ] **RunningHub DTO** (5个文件)
  - [ ] `src/main/java/com/dora/dto/runninghub/RunningHubSubmitRequest.java`
  - [ ] `src/main/java/com/dora/dto/runninghub/RunningHubNodeInfo.java`
  - [ ] `src/main/java/com/dora/dto/runninghub/RunningHubSubmitResponse.java`
  - [ ] `src/main/java/com/dora/dto/runninghub/RunningHubStatusResponse.java`
  - [ ] `src/main/java/com/dora/dto/runninghub/RunningHubOutputResponse.java`

- [ ] **核心服务** (2个文件)
  - [ ] `src/main/java/com/dora/service/AIProviderService.java`
  - [ ] `src/main/java/com/dora/scheduler/RunningHubPollingScheduler.java`

- [ ] **修改的文件** (7个文件)
  - [ ] `src/main/resources/application.yml` - 添加providers配置
  - [ ] `src/main/java/com/dora/entity/AiTask.java` - 添加provider字段
  - [ ] `src/main/java/com/dora/entity/PointsConfig.java` - 添加provider字段
  - [ ] `src/main/java/com/dora/mapper/AiTaskMapper.java` - 添加查询方法
  - [ ] `src/main/resources/mapper/AiTaskMapper.xml` - 更新SQL
  - [ ] `src/main/java/com/dora/service/impl/AiTaskServiceImpl.java` - 集成Provider
  - [ ] `V5__add_provider_support.sql` - 数据库迁移脚本

### 2. 配置文件检查

```bash
# 检查application.yml中的RunningHub配置
grep -A 10 "runninghub:" src/main/resources/application.yml
```

**必须包含：**
```yaml
runninghub:
  enabled: true
  base-url: https://www.runninghub.cn
  submit-url: /task/openapi/ai-app/run
  status-url: /task/openapi/status
  output-url: /task/openapi/outputs
  default-webapp-id: "1973555977595301890"
  api-key: "5c44cef12da3470e9f24da70c63787dc"
  polling-interval: 5000
  max-polling-times: 120
```

---

## 🗄️ 数据库部署

### 1. 执行迁移脚本

```bash
# 1. 备份数据库
mysqldump -u root -p 1818ai > backup_before_v5_$(date +%Y%m%d_%H%M%S).sql

# 2. 执行迁移
mysql -u root -p 1818ai < V5__add_provider_support.sql

# 3. 验证表结构
mysql -u root -p 1818ai -e "DESC ai_task;" | grep provider
mysql -u root -p 1818ai -e "DESC points_config;" | grep provider
```

**预期输出：**
```
provider_type       | varchar(50)  | YES  |     | NULL    |
provider_task_id    | varchar(100) | YES  |     | NULL    |
provider_response   | text         | YES  |     | NULL    |
```

### 2. 验证模型配置

```sql
-- 查看插入的RunningHub模型数量
SELECT COUNT(*) as rh_model_count
FROM points_config
WHERE provider_type = 'runninghub';
-- 预期结果：12

-- 查看所有模型
SELECT model_name, description, points_cost, provider_type
FROM points_config
WHERE provider_type = 'runninghub'
ORDER BY points_cost;
```

---

## 🔧 编译部署

### 1. 编译项目

```bash
# 清理并编译
mvn clean package -DskipTests

# 检查编译结果
ls -lh target/1818_user_server-1.0-SNAPSHOT.jar
```

### 2. 部署到服务器

```bash
# 1. 停止服务
sudo systemctl stop spring_1818_user_server

# 2. 备份当前版本
sudo cp /www/wwwroot/1818_user_server/1818_user_server-1.0-SNAPSHOT.jar \
         /www/wwwroot/1818_user_server/backups/1818_user_server-$(date +%Y%m%d_%H%M%S).jar

# 3. 部署新版本
sudo cp target/1818_user_server-1.0-SNAPSHOT.jar \
         /www/wwwroot/1818_user_server/

# 4. 启动服务
sudo systemctl start spring_1818_user_server

# 5. 查看启动日志
sudo journalctl -u spring_1818_user_server -f --lines=100
```

---

## ✅ 部署后验证

### 1. 服务启动检查

```bash
# 1. 检查进程
ps aux | grep spring_1818_user_server

# 2. 检查端口
netstat -tlnp | grep 8081

# 3. 检查日志中的Provider注册
sudo journalctl -u spring_1818_user_server | grep "注册AI Provider"
```

**预期日志输出：**
```
注册AI Provider: openai, 异步: false
注册AI Provider: runninghub, 异步: true
```

### 2. Provider初始化检查

```bash
# 查看日志确认Provider初始化成功
sudo journalctl -u spring_1818_user_server | grep -E "(Provider|AIProviderService)" | tail -20
```

**预期日志：**
```
INFO  AIProviderService - 注册AI Provider: openai, 异步: false
INFO  AIProviderService - 注册AI Provider: runninghub, 异步: true
INFO  RunningHubPollingScheduler - RunningHub轮询调度器已启动
```

### 3. API健康检查

```bash
# 检查服务健康
curl http://localhost:8081/actuator/health

# 预期响应
{"status":"UP"}
```

---

## 🧪 功能测试

### 测试1：OpenAI模型（兼容性测试）

```bash
# 提交OpenAI模型任务
curl -X POST "http://localhost:8081/user/ai/tasks/submit" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "modelName": "sora_image",
    "prompt": "测试猫咪图片"
  }' | jq '.'
```

**验证点：**
- [ ] 返回200状态码
- [ ] 返回taskNo
- [ ] status为"queued"或"processing"
- [ ] 30秒内任务完成

### 测试2：RunningHub文生视频

```bash
# 提交RunningHub文生视频任务
RESPONSE=$(curl -X POST "http://localhost:8081/user/ai/tasks/submit" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "modelName": "rh_sora2_text_portrait",
    "prompt": "一个人在海边奔跑"
  }')

echo $RESPONSE | jq '.'

# 提取taskNo
TASK_NO=$(echo $RESPONSE | jq -r '.data.taskNo')
echo "TaskNo: $TASK_NO"
```

**验证点：**
- [ ] 返回200状态码
- [ ] 返回taskNo
- [ ] status为"processing"
- [ ] 查看数据库确认provider_type='runninghub'

```sql
SELECT task_no, model_name, provider_type, provider_task_id, status
FROM ai_task
WHERE task_no = 'YOUR_TASK_NO';
```

### 测试3：RunningHub图生视频

```bash
# 提交RunningHub图生视频任务
curl -X POST "http://localhost:8081/user/ai/tasks/submit" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "modelName": "rh_sora2_img_landscape",
    "prompt": "让场景动起来",
    "imageUrl": "https://example.com/test-image.jpg"
  }' | jq '.'
```

**验证点：**
- [ ] 返回200状态码
- [ ] 任务提交成功
- [ ] 查看日志确认image节点包含完整URL

```bash
sudo journalctl -u spring_1818_user_server | grep "RunningHub Provider - 请求体" | tail -1
```

### 测试4：轮询机制

```bash
# 实时查看轮询日志
sudo journalctl -u spring_1818_user_server -f | grep "RunningHub轮询"
```

**验证点：**
- [ ] 每5秒输出一次轮询日志
- [ ] 显示待处理任务数量
- [ ] 任务状态正确更新（QUEUED → RUNNING → SUCCESS）

---

## 📊 监控指标

### 1. 任务状态分布

```sql
SELECT 
    provider_type,
    status,
    COUNT(*) as count
FROM ai_task
WHERE create_time > DATE_SUB(NOW(), INTERVAL 1 HOUR)
GROUP BY provider_type, status;
```

### 2. 平均处理时间

```sql
SELECT 
    provider_type,
    model_name,
    AVG(TIMESTAMPDIFF(SECOND, start_time, complete_time)) as avg_seconds,
    COUNT(*) as total_tasks
FROM ai_task
WHERE status = 'completed'
  AND create_time > DATE_SUB(NOW(), INTERVAL 24 HOUR)
GROUP BY provider_type, model_name;
```

### 3. 失败任务分析

```sql
SELECT 
    provider_type,
    error_message,
    COUNT(*) as error_count
FROM ai_task
WHERE status = 'failed'
  AND create_time > DATE_SUB(NOW(), INTERVAL 24 HOUR)
GROUP BY provider_type, error_message
ORDER BY error_count DESC;
```

---

## 🔧 常见问题排查

### 问题1：Provider未注册

**症状：** 日志中没有"注册AI Provider"
**排查：**
```bash
# 检查是否有编译错误
sudo journalctl -u spring_1818_user_server | grep -i "error" | tail -20

# 检查Provider类是否加载
sudo journalctl -u spring_1818_user_server | grep "Provider" | tail -30
```

### 问题2：RunningHub任务卡在processing

**排查：**
```bash
# 1. 检查轮询是否正常
sudo journalctl -u spring_1818_user_server | grep "轮询" | tail -10

# 2. 检查网络连接
curl -I https://www.runninghub.cn/task/openapi/status

# 3. 手动查询任务状态
curl -X POST "https://www.runninghub.cn/task/openapi/status" \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "YOUR_API_KEY",
    "taskId": "PROVIDER_TASK_ID"
  }' | jq '.'
```

### 问题3：图生视频失败

**排查：**
```bash
# 查看详细错误日志
sudo journalctl -u spring_1818_user_server | grep -A 5 "图生视频"

# 检查提交的请求体
sudo journalctl -u spring_1818_user_server | grep "RunningHub Provider - 请求体"
```

**常见原因：**
- 图片URL无法访问
- 图片包含真人（RunningHub不支持）
- 未提供imageUrl或imageBase64

---

## 📋 回滚方案

如果部署后发现问题，可以快速回滚：

```bash
# 1. 停止服务
sudo systemctl stop spring_1818_user_server

# 2. 恢复旧版本
sudo cp /www/wwwroot/1818_user_server/backups/1818_user_server_BACKUP_TIME.jar \
         /www/wwwroot/1818_user_server/1818_user_server-1.0-SNAPSHOT.jar

# 3. 回滚数据库（如果需要）
mysql -u root -p 1818ai < backup_before_v5_TIMESTAMP.sql

# 4. 启动服务
sudo systemctl start spring_1818_user_server
```

---

## ✅ 部署成功标志

全部验证通过后，确认以下所有项：

- [x] **服务正常启动**
  - 进程存在
  - 端口8081监听
  - 日志无ERROR

- [x] **Provider注册成功**
  - 日志显示openai和runninghub都已注册
  - AIProviderService初始化完成

- [x] **数据库表结构正确**
  - ai_task包含provider_*字段
  - points_config包含provider_*字段
  - 12个RunningHub模型已插入

- [x] **OpenAI模型正常**（兼容性）
  - 能提交任务
  - 能正常完成
  - 积分正确扣除

- [x] **RunningHub文生视频正常**
  - 能提交任务
  - provider_task_id正确保存
  - 轮询机制工作
  - 2-5分钟后获得结果

- [x] **RunningHub图生视频正常**
  - 支持imageUrl参数
  - image节点正确构建
  - 能够完成任务

- [x] **轮询调度器正常**
  - 每5秒执行一次
  - 正确更新任务状态
  - 失败任务自动退款

---

## 📞 技术支持

如有问题，请提供以下信息：

1. 错误日志（最近100行）
2. 数据库中的任务记录
3. 具体的API请求和响应
4. 环境信息（Java版本、MySQL版本等）

**祝部署顺利！** 🚀