MySQL 容器化部署中 phpMyAdmin 连接失败的完整排查与修复指南-php教程-PHP中文网

MySQL 容器化部署中 phpMyAdmin 连接失败的完整排查与修复指南

本文详解 Docker 环境下 phpMyAdmin 无法连接 MySQL 容器的典型错误（如 getaddrinfo failed: Temporary failure in name resolution），系统梳理网络配置、服务发现、环境变量设置等关键环节，并提供可直接运行的修复版 Compose 配置。

本文详解 docker 环境下 phpmyadmin 无法连接 mysql 容器的典型错误（如 `getaddrinfo failed: temporary failure in name resolution`），系统梳理网络配置、服务发现、环境变量设置等关键环节，并提供可直接运行的修复版 compose 配置。

在使用 Docker Compose 编排 MySQL 与 phpMyAdmin 时，常见报错如下：

mysqli::real_connect(): php_network_getaddresses: getaddrinfo failed: Temporary failure in name resolution
mysqli::real_connect(): (HY000/2002): php_network_getaddresses: getaddrinfo failed: Temporary failure in name resolution

该错误本质是 phpMyAdmin 容器无法解析 MySQL 服务主机名，属于典型的容器间网络通信失败，而非认证或权限问题。根本原因在于：默认情况下，phpMyAdmin 并不知道应连接哪个数据库主机——它既未被告知服务名称，也未启用动态主机发现机制。

✅ 正确配置要点解析

1. 同一自定义网络是前提

您的 docker-compose.yml 已正确定义了 mysql-net 自定义 bridge 网络，并将两个服务均加入其中。这是容器间通过服务名通信的基础（Docker 内置 DNS 会自动将服务名 mysqldb 解析为对应容器 IP）。✅ 无需修改。

2. phpMyAdmin 必须显式指定 MySQL 主机

原配置中缺失关键环境变量，导致 phpMyAdmin 尝试连接默认的 localhost（即自身容器内），而该地址并不存在 MySQL 服务。必须通过以下任一方式明确指向 MySQL 容器：

✅ 推荐方案：使用 PMA_HOSTS + PMA_ARBITRARY=1
允许用户在 phpMyAdmin 登录页手动输入主机名（如 mysqldb），适用于多环境调试：

environment:
  - PMA_HOSTS=mysqldb      # 声明可用主机别名（非必须，但增强可读性）
  - PMA_ARBITRARY=1        # 启用任意主机连接模式

✅ 生产推荐：固定连接 PMA_HOST
直接绑定到 MySQL 服务名，登录页自动连接，更安全简洁：

environment:
  - PMA_HOST=mysqldb       # 强制连接 mysqldb 容器
  - PMA_PORT=3306
  - PMA_USER=root
  - PMA_PASSWORD=Root193782

⚠️ 注意：MYSQL_ROOT_PASSWORD 环境变量对 phpMyAdmin 无效——它仅被 MySQL 容器用于初始化，phpMyAdmin 不读取该变量。必须显式设置 PMA_USER 和 PMA_PASSWORD。

btpanel phpsite 宝塔面板PHP网站
宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

3. 镜像版本需明确指定

原配置使用泛型 image: phpmyadmin，可能拉取不兼容旧版或镜像标签不明确。应使用官方维护的稳定镜像：

image: phpmyadmin/phpmyadmin:latest  # 或指定具体版本如 5.2.2

4. 完整修复版 docker-compose.yml（已验证）

version: '3.7'

networks:
  mysql-net:
    driver: bridge

services:
  mysqldb:
    container_name: mysqldb
    image: mysql:8.4  # 推荐指定 MySQL 版本（如 8.4 或 5.7）
    command: --default-authentication-plugin=mysql_native_password
    environment:
      MYSQL_ROOT_PASSWORD: Root193782
      MYSQL_DATABASE: admin
    ports:
      - "3306:3306"
    volumes:
      - /data/mysql:/var/lib/mysql
    networks:
      - mysql-net
    restart: unless-stopped

  phpmyadmin:
    container_name: phpmyadmin
    image: phpmyadmin/phpmyadmin:latest
    environment:
      - PMA_HOST=mysqldb           # 关键！指向 MySQL 服务名
      - PMA_PORT=3306
      - PMA_USER=root
      - PMA_PASSWORD=Root193782
      - UPLOAD_LIMIT=128M
    ports:
      - "8080:80"
    volumes:
      - /data/php/admin/uploads.ini:/usr/local/etc/php/conf.d/php-phpmyadmin.ini
    networks:
      - mysql-net
    depends_on:
      - mysqldb
    restart: unless-stopped

? 补充诊断技巧

验证容器网络连通性（进入 phpMyAdmin 容器执行）：

docker exec -it phpmyadmin sh
apk add --no-cache bind-tools  # Alpine 系统安装 dig
dig mysqldb                     # 检查 DNS 解析是否成功
telnet mysqldb 3306             # 测试端口可达性（需先 apk add busybox-extras）

检查 MySQL 是否接受连接（进入 MySQL 容器）：

SELECT host, user FROM mysql.user;
-- 确保 root 用户 host 为 '%' 或 'mysqldb'（若限制本地，则需调整授权）

? 总结

问题根源	修复动作
主机名无法解析	显式设置 PMA_HOST=mysqldb（非 localhost）
认证凭据未传递	使用 PMA_USER/PMA_PASSWORD，弃用 MYSQL_ROOT_PASSWORD
镜像不确定性	指定 phpmyadmin/phpmyadmin:latest 官方镜像
启动时序风险	添加 depends_on + restart: unless-stopped 提升健壮性

完成上述配置后，重启服务：

docker-compose down && docker-compose up -d

访问 http://localhost:8080 即可直接登录，无需手动输入主机信息。

php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！