Dify db_query 插件连接本地 MySQL 故障排查

问题现象

Dify 使用junjiem/db_query插件执行 SQL 查询时，报错：

RuntimeError: Error executing SQL: (pymysql.err.OperationalError) (2003, "Can't connect to MySQL server on 'host.docker.internal' ([Errno -2] Name or service not known)")

根本原因：plugin_daemon容器内部无法解析host.docker.internal，导致无法连接到宿主机上的 MySQL。

解决方案

步骤 1：修改 docker-compose.yaml

找到 Dify 项目下的docker-compose.yaml（通常位于 Dify 项目根目录的docker/文件夹内）。

找到plugin_daemon服务配置，在restart: always下方添加extra_hosts：

plugin_daemon: image: langgenius/dify-plugin-daemon:0.6.3-local restart: always extra_hosts: # ← 添加此行 - "host.docker.internal:host-gateway" # ← 添加此行 env_file: - path: ./envs/core-services/shared.env required: false # ... 以下保持不变

步骤 2：重启 plugin_daemon 容器

cd Dify项目目录/docker docker-compose up -d plugin_daemon

步骤 3：验证修复

确认容器内可解析host.docker.internal：

docker exec docker-plugin_daemon-1 sh -c "getent ahosts host.docker.internal"

正常应返回192.168.65.254（IPv4）地址。

Dify App 中 db_query 插件配置参数

备选方案（如果extra_hosts不生效）

方案 A：使用宿主机真实 IP

1. 在宿主机运行ipconfig获取本机局域网 IP（如192.168.x.x）

2. 在 db_query 插件参数中将db_host设为该 IP 地址

方案 B：检查 MySQL 配置

确保宿主机 MySQL 允许远程连接：

-- 允许 root 从任意主机连接 ALTER USER 'root'@'%' IDENTIFIED WITH mysql_native_password BY '密码'; FLUSH PRIVILEGES;

同时检查：

• MySQL 监听0.0.0.0:3306（不是127.0.0.1）

• Windows 防火墙允许 3306 端口入站

排查命令速查

# 查看容器日志 docker logs docker-plugin_daemon-1 ​ # 测试容器内 DNS 解析 docker exec docker-plugin_daemon-1 sh -c "getent hosts host.docker.internal" ​ # 查看容器网络 docker inspect docker-plugin_daemon-1 --format '{{range $net, $v := .NetworkSettings.Networks}}{{$net}}: {{$v.IPAddress}}{{"\n"}}{{end}}' ​ # 进入容器内部 docker exec -it docker-plugin_daemon-1 sh ​ # 查看容器环境变量 docker inspect docker-plugin_daemon-1 --format '{{json .Config.Env}}' | ConvertFrom-Json ​ # 查看 db_query 插件代码 docker exec docker-plugin_daemon-1 cat "/app/storage/cwd/junjiem/db_query-*/tools/sql_query.py" ​ # 查看 db_util 工具类（SQLAlchemy 连接逻辑） docker exec docker-plugin_daemon-1 cat "/app/storage/cwd/junjiem/db_query-*/tools/db_util.py"

原理说明

• host.docker.internal是 Docker Desktop 提供的特殊 DNS 名称，用于从容器访问宿主机服务

• Docker Desktop for Windows 通过host-gateway自动解析为网关 IP（192.168.65.254或fdc4:f303:9324::254）

• 早于 18.03 的 Docker Desktop 版本或特定网络配置下可能不支持，需通过extra_hosts手动注入

• db_query插件是 Dify 插件市场中的社区插件，运行在plugin_daemon容器内，该容器默认不带host.docker.internal解析