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. 配置文件检查

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

必须包含：

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. 执行迁移脚本

# 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. 验证模型配置

-- 查看插入的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. 编译项目

# 清理并编译
mvn clean package -DskipTests

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

2. 部署到服务器

# 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. 服务启动检查

# 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初始化检查

# 查看日志确认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健康检查

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

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

---

🧪 功能测试

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

# 提交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文生视频

# 提交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'

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

测试3：RunningHub图生视频

# 提交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

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

测试4：轮询机制

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

验证点：

• 每5秒输出一次轮询日志
• 显示待处理任务数量
• 任务状态正确更新（QUEUED → RUNNING → SUCCESS）

---

📊 监控指标

1. 任务状态分布

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. 平均处理时间

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. 失败任务分析

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" 排查：

# 检查是否有编译错误
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

排查：

# 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：图生视频失败

排查：

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

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

常见原因：

• 图片URL无法访问
• 图片包含真人（RunningHub不支持）
• 未提供imageUrl或imageBase64

---

📋 回滚方案

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

# 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

---

✅ 部署成功标志

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

• 服务正常启动

  • 进程存在
  • 端口8081监听
  • 日志无ERROR

• Provider注册成功

  • 日志显示openai和runninghub都已注册
  • AIProviderService初始化完成

• 数据库表结构正确

  • ai_task包含provider_*字段
  • points_config包含provider_*字段
  • 12个RunningHub模型已插入

• OpenAI模型正常（兼容性）

  • 能提交任务
  • 能正常完成
  • 积分正确扣除

• RunningHub文生视频正常

  • 能提交任务
  • provider_task_id正确保存
  • 轮询机制工作
  • 2-5分钟后获得结果

• RunningHub图生视频正常

  • 支持imageUrl参数
  • image节点正确构建
  • 能够完成任务

• 轮询调度器正常

  • 每5秒执行一次
  • 正确更新任务状态
  • 失败任务自动退款

---

📞 技术支持

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

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

祝部署顺利！ 🚀