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 插件配置参数

参数	说明	示例值
db_type	数据库类型	mysql
db_host	数据库地址	host.docker.internal
db_port	端口	3306
db_username	用户名	root
db_password	密码	你的密码
db_name	数据库名	要查询的库名
db_properties	额外属性（可选）	留空
query_sql	SQL 查询语句	SELECT * FROM table_name
output_format	输出格式	markdown 或 json

---

备选方案（如果 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 解析