修改

2026-01-06 23:45:28 +08:00
parent e466f59b84
commit f7b1e9433c
4 changed files with 392 additions and 83 deletions
--- a/TROUBLESHOOTING.md
+++ b/TROUBLESHOOTING.md
@@ -0,0 +1,139 @@
+# 故障排查指南
+
+## 查询超时问题诊断
+
+如果遇到"查询超时，已查询XX次"的问题，请按以下步骤排查：
+
+### 1. 检查任务ID是否正确
+
+**症状**：查询时返回404错误或任务未找到
+
+**解决方法**：
+- 查看控制台输出的"完整响应数据"，确认任务ID是否正确获取
+- 检查任务ID的类型和格式（应该是数字）
+- 确认生图接口返回的响应格式是否符合预期
+
+**调试命令**：
+```bash
+# 运行时会输出完整的API响应，检查任务ID字段
+npm start
+```
+
+### 2. 检查API响应格式
+
+**症状**：查询返回的数据格式不符合预期
+
+**解决方法**：
+- 查看控制台输出的"完整API响应"
+- 确认 `data.code` 是否为 200
+- 确认 `data.data.status` 是否存在
+- 确认 `data.data.image_url` 字段名称是否正确
+
+**常见问题**：
+- API响应格式可能已更新，需要调整代码中的字段名
+- 某些情况下 `image_url` 可能是 `imageUrl` 或其他名称
+
+### 3. 检查图片生成状态
+
+**症状**：状态一直显示"排队中"或"生成中"，从未变为"成功"
+
+**可能原因**：
+1. **图片生成时间过长**：高分辨率（2K/4K）或复杂prompt需要更长时间
+2. **API服务繁忙**：排队任务较多
+3. **任务实际已失败**：但状态未更新为失败
+
+**解决方法**：
+- 增加 `MAX_QUERY_COUNT` 到 180 或更高
+- 增加 `QUERY_INTERVAL` 到 10000（10秒）
+- 检查API服务状态
+- 尝试降低图片分辨率（使用1K而不是2K）
+
+### 4. 检查API密钥和权限
+
+**症状**：返回401或403错误
+
+**解决方法**：
+- 确认 `.env` 文件中的 `API_KEY` 正确
+- 检查API密钥是否过期
+- 确认账户余额是否充足
+- 检查API密钥是否有查询接口的权限
+
+### 5. 检查网络连接
+
+**症状**：请求超时或网络错误
+
+**解决方法**：
+- 检查网络连接
+- 确认可以访问 `https://api.wuyinkeji.com`
+- 检查防火墙设置
+- 尝试增加请求超时时间
+
+### 6. 手动测试API
+
+**使用curl测试查询接口**：
+```bash
+# 替换 YOUR_API_KEY 和 TASK_ID
+curl -X GET "https://api.wuyinkeji.com/api/img/drawDetail?id=TASK_ID" \
+  -H "Authorization: YOUR_API_KEY" \
+  -H "Content-Type: application/json;charset:utf-8;"
+```
+
+**使用curl测试生图接口**：
+```bash
+curl -X POST "https://api.wuyinkeji.com/api/img/nanoBanana-pro" \
+  -H "Authorization: YOUR_API_KEY" \
+  -H "Content-Type: application/json;charset:utf-8;" \
+  -d '{
+    "prompt": "test prompt",
+    "imageSize": "1K",
+    "aspectRatio": "1:1"
+  }'
+```
+
+### 7. 查看详细日志
+
+代码已增强日志输出，运行时会显示：
+- ✅ 任务提交时的完整响应
+- ✅ 每次查询的详细状态
+- ✅ 每10次查询的完整API响应
+- ✅ 所有错误信息
+
+**关键日志位置**：
+1. 任务提交后：查看"完整响应数据"，确认任务ID
+2. 查询过程中：查看"查询结果详情"，确认状态值
+3. 错误时：查看"完整错误响应"，了解具体错误原因
+
+### 8. 常见错误码说明
+
+| 错误码 | 说明 | 解决方法 |
+|--------|------|----------|
+| 200 | 成功 | - |
+| 400 | 请求参数错误 | 检查请求参数格式 |
+| 401 | 认证失败 | 检查API密钥 |
+| 403 | 权限不足 | 检查API密钥权限 |
+| 404 | 任务未找到 | 检查任务ID是否正确 |
+| 500 | 服务器错误 | 稍后重试或联系API服务商 |
+
+### 9. 推荐配置
+
+对于稳定的图片生成，建议使用以下配置：
+
+```env
+# 查询间隔：10秒（减少API调用频率）
+QUERY_INTERVAL=10000
+
+# 最大查询次数：180次（对应30分钟）
+MAX_QUERY_COUNT=180
+
+# 图片尺寸：1K（生成速度更快，适合测试）
+IMAGE_SIZE=1K
+```
+
+### 10. 联系支持
+
+如果以上方法都无法解决问题：
+1. 收集完整的日志输出
+2. 记录任务ID和错误信息
+3. 联系速创API技术支持
+4. 提供复现步骤和错误详情
+