本地Docker环境下WP-CLI无法连接数据库的问题求助

核心原因 #

容器内的WordPress能通过database访问数据库，是因为Docker桥接网络的内部DNS解析生效，但主机的WP-CLI不在这个Docker网络中，无法直接解析database；同时MariaDB默认可能只允许容器内部（localhost）的连接请求，拒绝外部（主机）的访问。

解决步骤 #

1. 确认MariaDB端口映射正常 #

你的docker-compose.yml已经将容器的3306端口映射到主机的3306端口，先验证端口未被其他程序占用：

# Linux/macOS
netstat -tulpn | grep 3306
# 或者
lsof -i :3306

# Windows
netstat -ano | findstr :3306

如果输出中能看到docker-proxy相关进程，说明端口映射正常。

2. 调整MariaDB用户权限 #

默认情况下，MariaDB的root用户（或WordPress专用数据库用户）仅允许从localhost（容器内部）访问，需要修改权限允许主机连接：

1. 进入MariaDB容器：

docker exec -it database mysql -uroot -ppassword

2. 执行SQL修改用户权限（以root用户为例，也可以用你的WordPress数据库用户）：

-- 允许root用户从任意地址连接
GRANT ALL PRIVILEGES ON *.* TO 'root'@'%' IDENTIFIED BY 'password' WITH GRANT OPTION;
-- 刷新权限生效
FLUSH PRIVILEGES;

如果用的是专门的WordPress数据库用户（比如wp_user），替换上述语句中的root为对应的用户名即可。

3. 配置wp-config.php兼容两种环境 #

为了让容器内的Web服务和主机的WP-CLI都能正常连接数据库，在wp-config.php中添加环境判断：

// 根据运行环境选择数据库主机
if (php_sapi_name() === 'cli') {
    // WP-CLI运行在主机，用主机映射的端口地址
    define('DB_HOST', '127.0.0.1');
} else {
    // Web服务运行在容器，用Docker内部DNS解析
    define('DB_HOST', 'database');
}

4. 测试WP-CLI连接 #

在主机上进入你的WordPress站点目录（对应容器内的/var/www/html下的站点文件夹），执行：

wp db check

如果返回“Success: Database is healthy.”，说明连接成功。

额外排查点 #

• 检查主机防火墙是否允许3306端口的入站请求，比如Ubuntu的ufw需要执行ufw allow 3306，Windows需在防火墙规则中开放该端口。
• 确保WP-CLI使用的数据库用户名、密码和wp-config.php中的一致，避免凭据错误。

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