Dify Custom Tool 调用超时问题排查与解决方案（claude-4.5-opus-high）

在使用 Dify 的 Custom Tool（自定义工具）功能调用外部 API 时，你是否遇到过这样的问题：

• 工具调用反复重试，日志中出现多次相同请求
• API 明明执行成功了，但 Dify 显示超时失败
• 复杂的 AI 处理流程总是在中途断开

如果你正在被这些问题困扰，这篇文章将帮你彻底解决！

---

🔍 问题现象

场景描述

开发了一个基于 MCP（Model Context Protocol）的 API 服务，用于分析防火墙日志并自动生成安全策略。该 API 内部会进行 两次 LLM 调用：

1. Stage 1：解析日志，提取五元组信息
2. Stage 2：基于分析结果，调用工具创建防火墙规则

整个过程在本地 CPU 推理下大约需要 2-3 分钟。

异常日志

在 Dify 中通过 Custom Tool 调用该 API 时，发现日志出现异常：

2025-12-11 10:36:10 - 📋 [Stage 1] 解析防火墙日志，提取五元组...
2025-12-11 10:37:11 - 📋 [Stage 1] 解析防火墙日志，提取五元组...
2025-12-11 10:38:12 - 📋 [Stage 1] 解析防火墙日志，提取五元组...

问题分析：请求每隔约 60 秒就重新开始，说明 Dify 在 60 秒后认为请求超时，自动重试。

---

🎯 问题根因

Dify 的 API Tool 超时配置

Dify 对 Custom Tool 的 HTTP 请求有默认超时限制，配置在 .env 文件中：

# API Tool configuration
API_TOOL_DEFAULT_CONNECT_TIMEOUT=10   # 连接超时：10秒
API_TOOL_DEFAULT_READ_TIMEOUT=60      # 读取超时：60秒（这是问题所在！）

当你的 API 处理时间超过 60 秒 时，Dify 会：

1. 认为请求超时失败
2. 自动重试请求
3. 导致后端收到重复请求

对于涉及 LLM 推理的复杂 API，60 秒远远不够！

---

✅ 解决方案

Step 1：修改 Dify 的 .env 配置

找到 Dify 部署目录下的 .env 文件，修改超时配置：

# API Tool configuration
API_TOOL_DEFAULT_CONNECT_TIMEOUT=10
API_TOOL_DEFAULT_READ_TIMEOUT=300     # 修改为 300 秒（5分钟）

推荐值参考：

场景	建议超时时间
简单 API 调用	60 秒（默认）
单次 LLM 推理（GPU）	120 秒
单次 LLM 推理（CPU）	180 秒
多次 LLM 推理（如本文场景）	300-600 秒

Step 2：重新创建容器

⚠️ 重要 ：docker-compose restart 不会重新加载 .env 文件！

必须使用以下方式之一：

# 方式1：重新创建所有容器
cd /path/to/dify
docker-compose down
docker-compose up -d

# 方式2：只重建 api 服务（推荐，更快）
docker-compose up -d --force-recreate api

Step 3：验证配置生效

进入容器检查环境变量：

# 方式1：直接查看
docker-compose exec api env | grep -i API_TOOL

# 方式2：进入容器后查看
docker exec -it dify-api sh
env | grep -i timeout

正确输出：

API_TOOL_DEFAULT_CONNECT_TIMEOUT=10
API_TOOL_DEFAULT_READ_TIMEOUT=300

---

🧪 验证修复效果

修复后重新测试，观察日志：

2025-12-11 11:00:00 - 📋 [Stage 1] 解析防火墙日志...
2025-12-11 11:01:30 - ✅ [Stage 1] 五元组提取成功
2025-12-11 11:01:30 - 🔒 [Stage 2] 创建阻断规则...
2025-12-11 11:02:45 - ✅ [Stage 2] 工具执行完成

请求不再重复，完整流程执行成功！🎉

---

📚 延伸知识

为什么 restart 不生效？

Docker Compose 的工作机制：

命令	行为	是否重新加载 .env
docker-compose restart	重启现有容器	❌ 不会
docker-compose stop && start	停止并启动	❌ 不会
docker-compose down && up	删除并重建容器	✅ 会
docker-compose up --force-recreate	强制重建容器	✅ 会

原理：容器的环境变量在创建时就已固定，restart 只是重启进程，不会重新注入环境变量。

其他可能的优化方向

如果不方便修改 Dify 配置，也可以从 API 端优化：

1. 精简 Prompt：减少 LLM 处理的 token 数量
2. 使用 GPU 推理：显著提升 LLM 响应速度
3. 拆分 API：将复杂流程拆分为多个简单 API
4. 异步处理：API 立即返回任务 ID，客户端轮询结果

---

📝 总结

问题	Custom Tool 调用超时，请求反复重试
原因	Dify 默认 API_TOOL_DEFAULT_READ_TIMEOUT=60 秒
解决	修改 .env 增大超时时间
关键	必须用 --force-recreate 或 down/up 重建容器

希望这篇文章能帮助遇到同样问题的开发者节省排查时间！