Laravel部署报SQLSTATE[HY000] [2002] Connection refused错误如何解决

SQLSTATE[HY000] [2002] Connection refused (SQL: select * from sessions where id = RlKtbVl23GJ84G2vXmLdwp7KGokTyBD6QM0HlaBN limit 1)

该错误本质是Laravel应用到数据库服务的TCP连接被直接拒绝，和session表是否存在、账号权限是否正确等上层逻辑无关，优先排查网络、数据库服务状态、配置匹配类问题

• Laravel数据库配置不匹配：.env文件内的DB_HOST、DB_PORT参数和实际数据库部署信息不一致，比如Docker环境错填127.0.0.1、独立数据库服务器填了本地地址等
• 数据库服务状态异常：服务器上MySQL/MariaDB服务未启动，或服务启动后端口未正常监听
• 网络拦截：服务器防火墙、云服务商安全组未放开数据库端口（默认3306）的访问权限，或数据库配置了仅允许本地IP访问
• Laravel配置缓存未更新：修改.env后未清除旧配置缓存，Laravel仍读取历史错误配置
• 特殊部署场景适配错误：使用unix socket连接数据库时未配置对应参数，仍走TCP连接逻辑

1. 校验数据库配置参数 #

核对项目根目录.env文件的数据库配置项，和实际部署信息保持一致：

• 普通单服务器部署：DB_HOST填127.0.0.1，DB_PORT默认填3306
• Docker Compose部署：DB_HOST填数据库服务的容器名称（比如docker-compose.yml内定义的mysql服务名）
• 独立数据库服务器部署：DB_HOST填数据库服务器的公网/内网IP
• 使用unix socket连接：新增DB_SOCKET=/var/run/mysqld/mysqld.sock配置，DB_HOST填localhost

2. 验证数据库服务状态与连通性 #

• 登录应用所在服务器，执行命令行连接测试：mysql -h <你的DB_HOST> -P <你的DB_PORT> -u <DB_USERNAME> -p，输入密码后如果能正常进入数据库命令行，说明网络和账号正常，否则继续排查
• 检查数据库服务是否启动：执行systemctl status mysql（或systemctl status mariadb），如果显示未运行，执行systemctl start mysql启动服务，可同时执行systemctl enable mysql设置开机自启
• 检查端口监听与访问权限：执行ss -tunlp | grep 3306确认数据库端口正常监听；检查服务器防火墙与云服务安全组，确保3306端口对应用服务器IP放开
• 调整数据库绑定地址：编辑数据库配置文件（一般为/etc/mysql/mysql.conf.d/mysqld.cnf），将bind-address从127.0.0.1改为0.0.0.0（允许所有IP访问）或应用服务器的固定IP，修改后重启数据库服务生效

3. 刷新Laravel配置缓存 #

到项目根目录执行以下命令清除旧配置缓存：

php artisan config:clear

生产环境可在配置确认无误后执行php artisan config:cache生成配置缓存，提升访问性能

4. 补充session依赖配置（连接正常后操作） #

如果是首次使用database驱动存储session，需要先执行以下命令生成session表：

php artisan session:table
php artisan migrate

避免连接正常后出现表不存在的报错

内容的提问来源于stack exchange，提问作者HADDAD Zineddine