AIGC/demo/VIDEO_GENERATION_DIAGNOSTIC.md

# 视频生成失败诊断报告

## 问题分析

根据代码分析，视频生成失败可能的原因包括：

### 1. 图片传输问题

#### 可能的问题点：
- **图片文件路径错误**: 相对路径无法找到文件
- **图片文件不存在**: 上传后文件丢失或路径错误
- **图片格式不支持**: 外部API不支持特定格式
- **图片大小超限**: 超过API限制

#### 检查方法：
```bash
# 检查队列状态
curl -X GET http://localhost:8080/api/diagnostic/queue-status

# 检查特定任务的图片文件
curl -X GET http://localhost:8080/api/diagnostic/check-image/{taskId}

# 获取失败任务列表
curl -X GET http://localhost:8080/api/diagnostic/failed-tasks
```

### 2. 队列处理问题

#### 可能的问题点：
- **任务状态更新失败**: 数据库事务问题
- **外部API调用失败**: 网络或认证问题
- **积分系统错误**: 积分冻结/扣除失败
- **任务超时**: 处理时间过长

#### 检查方法：
```bash
# 检查队列状态统计
curl -X GET http://localhost:8080/api/diagnostic/queue-status
```

### 3. 外部API问题

#### 可能的问题点：
- **API认证失败**: API密钥无效或过期
- **API服务不可用**: 外部服务宕机
- **请求格式错误**: 参数格式不符合API要求
- **响应解析失败**: API返回格式变化

## 诊断步骤

### 1. 检查队列状态
```bash
GET /api/diagnostic/queue-status
```
**返回信息**：
- 总任务数
- 待处理任务数
- 处理中任务数
- 已完成任务数
- 失败任务数
- 超时任务数

### 2. 检查图片文件
```bash
GET /api/diagnostic/check-image/{taskId}
```
**返回信息**：
- 图片文件路径
- 文件是否存在
- 文件大小
- 文件是否可读
- 检查的路径列表

### 3. 获取失败任务详情
```bash
GET /api/diagnostic/failed-tasks
```
**返回信息**：
- 失败任务列表
- 错误信息
- 失败时间

### 4. 重试失败任务
```bash
POST /api/diagnostic/retry-task/{taskId}
```
**功能**：
- 重置任务状态为待处理
- 清除错误信息
- 重新加入队列

## 常见问题解决方案

### 1. 图片文件不存在
**问题**: `图片文件不存在: uploads/taskId/first_frame.jpg`
**解决**：
- 检查上传目录权限
- 确认文件路径正确
- 检查文件是否被删除

### 2. 外部API调用失败
**问题**: `API提交失败: Connection timeout`
**解决**：
- 检查网络连接
- 验证API密钥
- 检查API服务状态

### 3. 积分系统错误
**问题**: `可用积分不足`
**解决**：
- 检查用户积分
- 验证积分冻结逻辑
- 重置用户积分

### 4. 任务超时
**问题**: `任务处理超时`
**解决**：
- 检查外部API响应时间
- 调整超时设置
- 优化图片处理

## 监控建议

### 1. 实时监控
- 监控队列状态变化
- 跟踪失败任务数量
- 检查图片文件完整性

### 2. 日志分析
- 查看任务处理日志
- 分析错误信息模式
- 监控API调用成功率

### 3. 性能优化
- 优化图片处理流程
- 改进错误处理机制
- 增强重试逻辑

## 总结

通过诊断工具可以快速定位视频生成失败的原因：

1. **图片传输问题** - 使用 `/check-image/{taskId}` 检查
2. **队列处理问题** - 使用 `/queue-status` 监控
3. **外部API问题** - 查看失败任务详情
4. **系统配置问题** - 检查日志和配置

建议定期使用这些诊断接口来监控系统健康状态，及时发现和解决问题。