Debian上ThinkPHP数据库连接问题的排查与修复
一、快速定位流程
- 核对配置文件：确认数据库类型、主机、端口、库名、账号、密码、字符集等是否正确；建议字符集使用utf8mb4。示例（ThinkPHP 5/6 常见写法）：
return [
‘type’ => ‘mysql’,
‘hostname’ => ‘127.0.0.1’,
‘username’ => ‘root’,
‘password’ => ‘your_password’,
‘database’ => ‘test_db’,
‘hostport’ => ‘3306’,
‘charset’ => ‘utf8mb4’
];
如为ThinkPHP 3.2，常见键名为：DB_TYPE、DB_HOST、DB_NAME、DB_USER、DB_PWD、DB_PORT、DB_PREFIX。修改后保存并重试。
- 检查数据库服务：确认MySQL/MariaDB已启动，并能用命令行登录：
sudo systemctl status mysql
mysql -u root -p
若未启动：sudo systemctl start mysql。
- 验证PHP扩展：确保启用mysqli或pdo_mysql。执行：php -m | grep -E ‘mysqli|pdo_mysql’；若缺失，安装并启用扩展，然后重启Web服务。
- 查看错误日志：优先查看PHP错误日志与Web服务错误日志（如：/var/log/apache2/error.log 或 /var/log/nginx/error.log），获取具体报错关键词（如 Access denied、Unknown database、Connection refused）。
- 网络与防火墙：确认应用与数据库之间的网络可达，放行3306端口（云服务器需配置安全组）。
二、常见原因与对应修复
- 配置项错误：核对hostname、username、password、database、hostport、charset；密码含特殊字符时确保正确引用；库名需事先存在；字符集建议utf8mb4。
- 服务未运行：使用 systemctl 启动 MySQL/MariaDB，确认监听端口（默认3306）处于监听状态。
- 权限与绑定地址：
- 远程连接被拒时，授予权限（示例）：GRANT ALL PRIVILEGES ON test_db.* TO ‘root’@‘%’ IDENTIFIED BY ‘your_password’; 并执行 FLUSH PRIVILEGES;
- 检查数据库配置（如 my.cnf）中的bind-address，若仅 127.0.0.1 将限制远程访问，按需调整为0.0.0.0（注意安全）。
- 扩展未安装或驱动不可用：安装php-mysql（Debian 包名），确保启用mysqli/pdo_mysql；重启Apache或php-fpm/Nginx使配置生效。
- 防火墙/安全组拦截：在服务器防火墙（如 ufw/firewalld/iptables）放行3306；云环境在控制台安全组入站规则放行对应端口。
三、版本差异与配置路径
- ThinkPHP 5/6：数据库配置通常位于config/database.php，键名如 type、hostname、username、password、database、hostport、charset。
- ThinkPHP 3.2：数据库配置通常位于Application/Common/Conf/config.php，键名如 DB_TYPE、DB_HOST、DB_NAME、DB_USER、DB_PWD、DB_PORT、DB_PREFIX。
- 修改配置后，务必重启Web服务或php-fpm以生效。
四、Debian 常用命令清单
- 服务与端口：
- 启动/状态：sudo systemctl start|status mysql
- 监听端口：ss -lntp | grep 3306
- PHP与扩展：
- 查看模块：php -m | grep -E ‘mysqli|pdo_mysql’
- 安装扩展：sudo apt install php-mysql
- 重启服务：sudo systemctl restart apache2 或 sudo systemctl restart php-fpm（Nginx 场景同时 sudo systemctl restart nginx）
- 防火墙（按需选择其一）：
- UFW：sudo ufw allow 3306/tcp
- firewalld：sudo firewall-cmd --add-port=3306/tcp --permanent && sudo firewall-cmd --reload
- 数据库运维：
- 登录：mysql -u root -p
- 授权：GRANT ALL PRIVILEGES ON db.* TO ‘user’@‘%’ IDENTIFIED BY ‘pwd’; FLUSH PRIVILEGES;
- 日志路径：
- Web/错误日志：/var/log/apache2/error.log 或 /var/log/nginx/error.log
- PHP错误日志：由 php.ini 的 error_log 指定
五、最小连通性自测脚本
- 纯PHP直连MySQL（排除框架因素），保存为 test_db.php 并访问： PDO::ERRMODE_EXCEPTION
]);
echo "PDO连接成功\n";
} catch (Exception $e) {
echo "连接失败: " . $e->getMessage() . "\n";
}
若此脚本也失败，说明问题在环境/网络/权限/扩展层面；若成功，再回到框架配置与日志深入排查。