必须挂载config.user.inc.php到/etc/phpmyadmin/config.user.inc.php，用foreach循环配置$cfg['Servers']数组（索引从1开始连续），并设$cfg['ServerDefault'] = 0，否则多服务器下拉列表无法正常显示或失效。
挂载 config.user.inc.php 是唯一可靠方式
直接靠 PMA_HOSTS 环境变量实现多服务器下拉列表，90% 的情况会失效——它只在镜像启动时读取、只影响登录页 UI 渲染，不参与认证逻辑，也不自动填充端口或用户。真正起作用的是 PHP 配置文件里的 $cfg['Servers'] 数组。所以必须挂载自定义配置，且路径必须是 /etc/phpmyadmin/config.user.inc.php（注意不是 config.inc.php，后者会被官方镜像覆盖）。
- 挂载命令必须写全路径：
./config.user.inc.php:/etc/phpmyadmin/config.user.inc.php - 文件末尾不能有
?>PHP closing tag，否则容器启动失败 - 权限要确保容器内可读（
644即可，不用755） - 如果用
docker compose up启动后 phpMyAdmin 页面空白或 500 错误，先检查日志：docker compose logs phpmyadmin，大概率是配置语法错误或路径不对
配置文件里 $cfg['Servers'] 必须从 1 开始连续索引
phpMyAdmin 登录页下拉框是否显示、能否切换服务器，取决于 $cfg['Servers'][1]、$cfg['Servers'][2]… 是否存在且结构完整。跳号（比如只有 [1] 和 [3]）、索引从 0 开始、或用了动态变量拼索引（如 $i++ 漏执行），都会导致部分服务器不显示或登录报错。
- 推荐用固定数组 + foreach 构建，避免手写索引出错
- 每个
$cfg['Servers'][$i]至少包含：'host'、'auth_type'、'verbose'（显示名） -
'port'和'user'可选，但若集群中各实例端口不同（如 3306/3307/3308），必须显式写上 - 设
$cfg['ServerDefault'] = 0;，否则默认选中第一个服务器，下拉框可能被隐藏
所有 MySQL 容器必须在同一 Docker 网络且能互相解析
即使配置写对了，如果 phpMyAdmin 容器 ping 不通 db-master 或 db-slave，登录时就会卡在“无法连接到 MySQL 服务器”。PMA_HOSTS=db-master,db-slave 这类写法只在容器名能被 DNS 解析的前提下才有效。
- Docker Compose 默认为 services 创建一个网络，只要没显式指定
network_mode: host或bridge，就天然互通 - 检查方法：进 phpMyAdmin 容器执行
nslookup db-master，应返回容器 IP；再试nc -zv db-master 3306确认端口可达 - 若用自定义网络（如
networks: [my-net]），需确保所有 MySQL 服务和 phpMyAdmin 都声明加入该网络 - MySQL 容器的
my.cnf中不能绑定127.0.0.1，得用0.0.0.0或留空，否则外部容器连不上
混合认证方式（如 signon + cookie）必须手写完整配置
当你需要让 phpMyAdmin 对主库用 root 密码直连、对从库走 signon 认证（比如对接单点登录系统），PMA_HOSTS 完全无能为力。这时每个 $cfg['Servers'][$i] 的 'auth_type'、'user'、'password'、'SignonScript' 都得单独配。
立即学习“PHP免费学习笔记（深入）”；
-
auth_type可取值：'cookie'、'http'、'signon'、'config'，不能混用同一套凭据 - 若某服务器用
'config'，必须同时提供'user'和'password'，且密码明文存储，仅限测试环境 - 用
'signon'时，SignonScript路径必须是容器内可访问的 PHP 脚本（如/var/www/html/signon.php），并需额外挂载该脚本 - 任何涉及非标准端口、SSL、socket 连接的场景，都绕不开手写
$cfg['Servers']
