单Dockerfile容器化Laravel应用遇数据库迁移连接拒绝问题

以下是针对Kubernetes环境下，Laravel容器启动正常但执行php artisan migrate报SQLSTATE[HY000] [2002] Connection refused的排查和解决步骤：

1. 修正数据库主机配置 #

容器内的localhost指向自身，而非外部数据库服务。在.env文件中，将DB_HOST设置为Kubernetes中数据库服务的名称，而非localhost或127.0.0.1：

DB_HOST=mysql-service # 替换为你的数据库Service名称

你可以在Laravel容器内执行以下命令验证连通性：

telnet $DB_HOST $DB_PORT
# 或使用nc工具
nc -zv $DB_HOST $DB_PORT

2. 确保数据库服务完全就绪 #

数据库容器启动通常比Laravel慢，迁移可能在数据库未完全初始化时执行。可通过两种方式处理：

• 在Kubernetes中使用InitContainer：在Laravel Pod的配置中添加InitContainer，等待数据库端口开放后再启动主容器：

  initContainers:
  - name: wait-for-db
    image: busybox:1.35
    command: ['sh', '-c', 'until nc -zv mysql-service 3306; do echo waiting for db; sleep 2; done;']
  

• 在start.sh脚本中添加等待逻辑：修改启动脚本，先等待数据库就绪再执行迁移：

  # start.sh中迁移前的等待代码
  until nc -z -v -w30 $DB_HOST $DB_PORT
  do
    echo "等待数据库服务启动..."
    sleep 5
  done
  
  # 执行迁移
  php artisan migrate --force
  

3. 验证数据库配置合法性 #

检查.env中的核心配置项是否正确：

• DB_PORT：确认与数据库容器暴露的端口一致（默认3306）
• DB_USERNAME/DB_PASSWORD：确保拥有目标数据库的读写权限
• DB_DATABASE：确认该数据库已提前创建（部分数据库镜像不会自动生成，需手动初始化）

可在Laravel容器内直接用mysql命令测试连接：

mysql -h $DB_HOST -P $DB_PORT -u $DB_USERNAME -p$DB_PASSWORD $DB_DATABASE

如果能成功连接，说明配置本身无问题，需排查迁移时机或配置缓存。

4. 清除Laravel配置缓存 #

若之前生成过配置缓存，容器启动时可能加载旧配置。在执行迁移前添加清除缓存的命令：

php artisan config:clear
php artisan migrate --force

5. 检查Kubernetes网络策略 #

如果集群中配置了NetworkPolicy，需确保允许Laravel Pod访问数据库服务的端口。例如，添加允许同命名空间内Pod访问数据库的策略：

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: allow-laravel-to-db
spec:
  podSelector:
    matchLabels:
      app: laravel # 你的Laravel Pod标签
  policyTypes:
  - Egress
  egress:
  - to:
    - podSelector:
        matchLabels:
          app: mysql # 你的数据库Pod标签
    ports:
    - protocol: TCP
      port: 3306

内容的提问来源于stack exchange，提问作者Ramses Kouam