Ubuntu 下 ThinkPHP 数据库连接失败的排查与修复
一 快速自检清单
- 核对配置文件：在 config/database.php 中确认关键项是否正确（以 ThinkPHP 6 为例）
- type：mysql
- hostname：127.0.0.1（本地）或服务器 IP/域名（远程）
- database：已存在的数据库名
- username / password：确保正确，特殊字符需正确转义
- hostport：3306（如修改过需一致）
- charset：utf8mb4（推荐）
- 检查 MySQL 服务：执行 systemctl status mysql，未运行则 sudo systemctl start mysql；用命令行 mysql -u 用户名 -p 验证能否登录。
- 验证 PHP 扩展：执行 php -m | grep -E ‘pdo_mysql|mysqli’，确保启用；如缺失，安装并启用对应扩展。
- 远程连接时：确认数据库用户允许从你的主机连接（如 ‘user’@‘%’），并在 my.cnf 中检查 bind-address（需要远程访问时不要仅绑定 127.0.0.1），同时放行 3306 端口（系统防火墙与云安全组）。
二 常见错误与对应处理
- SQLSTATE[HY000] [2002] No such file or directory（Unix Socket 问题）
原因：PHP 通过 socket 连接 MySQL，但 php.ini 中的 socket 路径与 MySQL 实际 socket 不一致。
处理：在 php.ini 设置正确的 socket 路径，例如：
- mysql.default_socket = /var/run/mysqld/mysqld.sock
- pdo_mysql.default_socket = /var/run/mysqld/mysqld.sock
- mysqli.default_socket = /var/run/mysqld/mysqld.sock
获取实际路径可用：在 phpinfo() 查找 MYSQL_SOCKET，或执行 find / -name mysql.sock；修改后重启 PHP-FPM/Apache 生效。
- Access denied / 1045（用户名或密码错误、主机限制）
处理：用命令行先验证登录；若远程连接失败，给对应用户授予权限，例如：
- GRANT ALL PRIVILEGES ON test_db.* TO ‘root’@‘%’ IDENTIFIED BY ‘your_password’;
- FLUSH PRIVILEGES;
同时确保 bind-address 允许远程来源（如设为 0.0.0.0 或注释掉该行）。
- Can’t connect to MySQL server on ‘x.x.x.x’（服务未启动或端口不通）
处理：确认 MySQL 已启动；检查 hostport 是否为 3306；排查 ufw/firewalld 与云服务器安全组是否放行 3306。
- The server requested authentication method unknown to the client（认证插件问题）
处理：在 MySQL 为相应用户切换为 mysql_native_password：
- ALTER USER ‘user’@‘%’ IDENTIFIED WITH mysql_native_password BY ‘your_password’;
- FLUSH PRIVILEGES;
- 扩展未启用（Class ‘PDO’ not found / mysqli missing）
处理：安装并启用 pdo_mysql 与 mysqli，在 php.ini 取消注释对应 extension=，或包管理器安装后重启 PHP。
三 Ubuntu 上的关键配置与命令
- 服务与端口：
- 查看状态：systemctl status mysql；启动：sudo systemctl start mysql
- 监听端口：确认 3306 处于监听（如 ss -tlnp | grep 3306）
- Socket 路径核对：
- 常见路径：/var/run/mysqld/mysqld.sock；命令行登录后执行 status 可见 “UNIX socket” 项
- 在 php.ini 同步设置 default_socket 三项，重启 PHP-FPM/Apache
- 远程访问与防火墙：
- 配置文件路径（常见）：/etc/mysql/mysql.conf.d/mysqld.cnf，检查 bind-address
- 防火墙：sudo ufw allow 3306 或 sudo firewall-cmd --add-port=3306/tcp --permanent && sudo firewall-cmd --reload
- 云服务器：在控制台安全组放行 3306 入站规则。
四 ThinkPHP 配置示例与验证
- 示例（config/database.php，TP6）：
- ‘type’ => ‘mysql’,
- ‘hostname’ => ‘127.0.0.1’,
- ‘database’ => ‘test_db’,
- ‘username’ => ‘root’,
- ‘password’ => ‘your_password’,
- ‘hostport’ => ‘3306’,
- ‘charset’ => ‘utf8mb4’
- 验证步骤：
- 命令行先连：mysql -h 127.0.0.1 -P 3306 -u root -p
- 在 Web 环境内做一个最简单的查询接口或临时路由打印 Db::query(‘SELECT 1’)，确认是否能正常返回。
- 旧版路径提示：若使用 ThinkPHP 5.1 等旧版本，配置可能在 Application/Common/Conf/config.php，字段名如 DB_HOST/DB_USER/DB_PWD/DB_NAME/DB_PORT 等，请按实际版本核对。
