Debian虚拟机中WordPress+Docker Compose数据库连接错误求助

问题背景 #

在基于Debian的虚拟机上通过SSH操作，参照Docker官方示例搭建WordPress+Docker Compose项目，访问localhost:8080时出现「Error establishing a database connection」错误。相关配置如下：

Dockerfile #

FROM wordpress:latest

COPY --chown=www-data:www-data wp-config.php /var/www/html/

wp-config.php #

<?php

define( 'DB_NAME', 'wordpress' );
define( 'DB_USER', 'wordpress' );
define( 'DB_PASSWORD', 'wordpress' );
define( 'DB_HOST', 'my-awesome-database:3306' );
define( 'DB_CHARSET', 'utf8' );
define( 'DB_COLLATE', '' );

define( 'AUTH_KEY',         'put your unique phrase here' );
define( 'SECURE_AUTH_KEY',  'put your unique phrase here' );
define( 'LOGGED_IN_KEY',    'put your unique phrase here' );
define( 'NONCE_KEY',        'put your unique phrase here' );
define( 'AUTH_SALT',        'put your unique phrase here' );
define( 'SECURE_AUTH_SALT', 'put your unique phrase here' );
define( 'LOGGED_IN_SALT',   'put your unique phrase here' );
define( 'NONCE_SALT',       'put your unique phrase here' );

$table_prefix = 'wp_';

define( 'WP_DEBUG', false );

if ( ! defined( 'ABSPATH' ) ) {
        define( 'ABSPATH', __DIR__ . '/' );
}

require_once ABSPATH . 'wp-settings.php';

docker-compose.yml #

version: "3"
services:
  my-awesome-database: # My database service
    image: mysql:5.7
    container_name: my-awesome-database
    environment:
      - MYSQL_ROOT_PASSWORD=somewordpress # Mandatory env
      - MYSQL_DATABASE=wordpress
      - MYSQL_USER=wordpress
      - MYSQL_PASSWORD=wordpress
    networks: # Adding two containers to one bridge net to communicate each other
      - my-awesome-network 
    restart: unless-stopped
    command: '--default-authentication-plugin=mysql_native_password'
    volumes: # To save database configs after restart container
      - mysql:/var/lib/mysql

  my-awesome-wordpress:
    build: . # Build image from Dockerfile
    container_name: my-awesome-wordpress
    networks:
      - my-awesome-network
    restart: unless-stopped
    volumes: # Saving wp-config.php file, if reboot container
      - wordpress:/var/www/html
    depends_on:
      - my-awesome-database
    ports:
      - "8080:80"

networks:
  my-awesome-network:
    driver: bridge

volumes:
  wordpress:
    driver: local
  mysql:
    driver: local

排查步骤 #

1. 检查自定义wp-config.php是否被卷覆盖 #

你的docker-compose.yml中给WordPress容器挂载了wordpress:/var/www/html卷，Docker卷挂载时会替换容器内目标目录的原有内容，导致Dockerfile中复制的自定义wp-config.php被覆盖，WordPress实际使用的是默认生成的配置文件，数据库连接参数不匹配。

解决方法：

• 方案一：缩小卷挂载范围，仅持久化需要保留的目录：

  volumes:
    - wordpress:/var/www/html/wp-content
  

• 方案二：单独挂载自定义配置文件：
  1. 在项目目录创建config文件夹，放入自定义wp-config.php
  2. 修改docker-compose.yml的volumes配置：

     volumes:
       - wordpress:/var/www/html
       - ./config/wp-config.php:/var/www/html/wp-config.php:ro
     

2. 验证数据库服务是否就绪 #

depends_on仅保证容器启动顺序，不确保MySQL服务完全初始化完成（MySQL启动需要时间加载数据、初始化权限），如果WordPress先启动，会因数据库未就绪导致连接失败。

验证/解决方法：

• 手动重启WordPress容器，等待几秒后重新访问：

  docker-compose restart my-awesome-wordpress
  

• 添加健康检查，让WordPress仅在数据库就绪后启动：
  修改docker-compose.yml中my-awesome-database的配置：

  my-awesome-database:
    # ... 原有配置
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-u", "wordpress", "-pwordpress"]
      interval: 5s
      timeout: 5s
      retries: 5
  

  同时更新my-awesome-wordpress的depends_on：

  my-awesome-wordpress:
    # ... 原有配置
    depends_on:
      my-awesome-database:
        condition: service_healthy
  

3. 直接验证容器间数据库连接 #

进入WordPress容器，用MySQL客户端测试连接，确认参数和网络是否正常：

# 进入WordPress容器
docker exec -it my-awesome-wordpress bash

# 安装MySQL客户端（容器默认无此工具）
apt update && apt install -y mysql-client

# 尝试连接数据库
mysql -h my-awesome-database -u wordpress -pwordpress wordpress

如果连接成功，说明数据库参数没问题，问题出在WordPress配置文件；如果连接失败，检查MySQL容器环境变量或网络连通性。

4. 检查MySQL容器日志 #

查看MySQL启动日志，排查初始化错误：

docker-compose logs my-awesome-database

如果日志显示权限错误、初始化失败，可清理现有MySQL卷后重新启动（注意：会丢失现有数据）：

# 停止容器
docker-compose down

# 删除MySQL卷
docker volume rm $(basename $(pwd))_mysql

# 重新启动服务
docker-compose up -d

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