数据库连接失败十有八九不是 CMS 的问题，而是「连接参数、账号权限、网络/服务监听、PHP 扩展」这四类原因之一。按顺序排查，通常 10 分钟内能定位：先读报错原文判断属于哪一类，再针对性验证，不要反复重装 CMS 或重装数据库。
数据库连接失败时，报错信息该怎么读？
结论：报错原文的分工很明确——「Unknown MySQL server host」是主机名/端口问题，「Access denied for user」是账号密码或授权问题，「Can't connect to local MySQL server through socket」是 socket 路径或数据库服务没启动，「could not find driver」是 PHP 扩展没装。四类报错对应四套解法，先分类再动手。
具体来说：Access denied 一定是账号、密码、授权主机三者不匹配；Connection refused 是服务没监听或防火墙拦了；No such file or directory 通常是 socket 文件路径不对。把报错原文整段复制去搜，比截图问人快得多。
localhost 和 127.0.0.1 有什么区别？
结论：在 MySQL 客户端和多数 CMS 安装程序里，localhost 会优先走 Unix socket（Linux 下通常是 /var/lib/mysql/mysql.sock 或 /tmp/mysql.sock），而 127.0.0.1 强制走 TCP 3306 端口。所以「填 localhost 报 socket 错、改成 127.0.0.1 就好了」是极常见的现象。
反过来，如果数据库跑在 Docker 容器里，宿主机上的 CMS 填 127.0.0.1 也不行——要填宿主机的内网 IP 或容器网络里的服务名，并且容器启动时要做端口映射 -p 3306:3306。排查时统一先用 127.0.0.1 试一次，可以把 socket 干扰排除掉。
账号密码都对，为什么还提示拒绝访问？
结论：MySQL 的账号是「用户名 + 授权主机」的组合，'user'@'localhost' 和 'user'@'%' 是两个不同的账号，权限也各算各的。很多面板会创建只允许 localhost 登录的账号，远程连接就必然失败。
排查步骤：
- 用命令行直接验证：
mysql -h 127.0.0.1 -P 3306 -u 数据库用户名 -p，输入密码。如果这里就失败，问题不在 CMS。
- 查看授权：
SHOW GRANTS FOR '用户名'@'%';，确认有 ALL PRIVILEGES ON 数据库名.*。
- 主机填的不是本机时，授权主机要放开：
GRANT ALL PRIVILEGES ON dbname.* TO 'user'@'%' IDENTIFIED BY '强密码'; FLUSH PRIVILEGES;
- 如果报
caching_sha2_password 相关错误，说明是 MySQL 8.0 默认加密插件与老版本 PHP 驱动不兼容，执行 ALTER USER 'user'@'%' IDENTIFIED WITH mysql_native_password BY '强密码'; 后刷新权限。
- 确认服务在监听：
ss -lntp | grep 3306，没输出就是没启动或被 bind-address = 127.0.0.1 限制成只允许本机。
PHP 环境缺扩展会导致什么现象？
结论：PHP 系 CMS 通过 PDO 或 mysqli 连接数据库，缺少 pdo_mysql 或 mysqli 扩展时，安装页会直接报「could not find driver」或「您的 PHP 似乎没有安装运行 WordPress 所需的 MySQL 扩展」这类提示，跟账号密码毫无关系。
用 php -m | grep -i mysql 查看已加载扩展，输出里应有 pdo_mysql 和 mysqli。缺了就装：Debian/Ubuntu 系 apt install php-mysql，CentOS 系 yum install php-mysqlnd，装完必须重启 PHP-FPM 和 Web 服务器。另外确认 PHP 版本与 CMS 要求的最低版本匹配，PHP 8.0 以上建议用 utf8mb4 字符集建库，避免后续出现乱码。
一套 5 分钟的排查顺序
结论：按「服务是否在跑 → 端口是否可达 → 命令行能否登录 → CMS 参数是否一致 → PHP 扩展是否齐全」这个顺序走，每一步都能把问题范围砍一半。
systemctl status mysqld（或 mariadb）确认服务运行；ss -lntp | grep 3306 确认监听地址是 0.0.0.0:3306 而不是 127.0.0.1:3306；- 用
mysql -h 命令行登录，验证账号密码权限；
- 核对 CMS 配置里的主机、端口、库名、用户名、密码、表前缀，注意密码里的特殊字符
#、@ 是否需要转义；
- 最后看错误日志：MySQL 侧
/var/log/mysqld.log，Web 侧 /var/log/nginx/error.log 或 PHP-FPM 的 error log，日志里的时间戳能直接对应你点「下一步」的那一刻。
按这个顺序排查，绝大多数连接失败都能在 10 分钟内定位到具体那一步，不需要重装 CMS，更不需要重装系统。
