Windows10下Laravel Sail环境PHPMyAdmin无法连接MariaDB排查

问题场景 #

Windows10系统的Laravel Sail Docker环境中，PHPMyAdmin无法连接MariaDB数据库，报错截图如下：

提供的docker-compose.yml配置如下：

services:
    laravel.test:
        build:
            context: ./vendor/laravel/sail/runtimes/8.1
            dockerfile: Dockerfile
            args:
                WWWGROUP: '${WWWGROUP}'
        image: sail-8.1/app
        extra_hosts:
            - 'host.docker.internal:host-gateway'
        ports:
            - '${APP_PORT:-80}:80'
            - '${VITE_PORT:-5173}:${VITE_PORT:-5173}'
        environment:
            WWWUSER: '${WWWUSER}'
            LARAVEL_SAIL: 1
            XDEBUG_MODE: '${SAIL_XDEBUG_MODE:-off}'
            XDEBUG_CONFIG: '${SAIL_XDEBUG_CONFIG:-client_host=host.docker.internal}'
            IGNITION_LOCAL_SITES_PATH: '${PWD}'
        volumes:
            - '.:/var/www/html'
        networks:
            - sail
        depends_on:
            - mariadb
            # - redis
            - mailpit
            - phpmyadmin
    mariadb:
        image: 'mariadb:10'
        ports:
            - '${FORWARD_DB_PORT:-3306}:3306'
        environment:
            MYSQL_ROOT_PASSWORD: '${DB_PASSWORD}'
            MYSQL_ROOT_HOST: '%'
            MYSQL_DATABASE: '${DB_DATABASE}'
            MYSQL_USER: '${DB_USERNAME}'
            MYSQL_PASSWORD: '${DB_PASSWORD}'
            MYSQL_ALLOW_EMPTY_PASSWORD: 'yes'
        volumes:
            - 'sail-mariadb:/var/lib/mysql'
            - './vendor/laravel/sail/database/mysql/create-testing-database.sh:/docker-entrypoint-initdb.d/10-create-testing-database.sh'
        networks:
            - sail
        healthcheck:
            test:
                - CMD
                - mysqladmin
                - ping
                - '-p${DB_PASSWORD}'
            retries: 3
            timeout: 5s
    # redis:
    #     image: 'redis:alpine'
    #     ports:
    #         - '${FORWARD_REDIS_PORT:-6379}:6379'
    #     volumes:
    #         - 'sail-redis:/data'
    #     networks:
    #         - sail
    #     healthcheck:
    #         test:
    #             - CMD
    #             - redis-cli
    #             - ping
    #         retries: 3
    #         timeout: 5s
    mailpit:
        image: 'axllent/mailpit:latest'
        ports:
            - '${FORWARD_MAILPIT_PORT:-1025}:1025'
            - '${FORWARD_MAILPIT_DASHBOARD_PORT:-8025}:8025'
        networks:
            - sail
    phpmyadmin:
        image: 'phpmyadmin:latest'
        ports:
            - 8080:80
        networks:
            - sail
        environment:
            - PMA_ARBITRARY=1
networks:
    sail:
        driver: bridge
volumes:
    sail-mariadb:
        driver: local
    # sail-redis:
    #     driver: local

排查与修复方案 #

1. 补充PHPMyAdmin的数据库连接配置 #

当前PHPMyAdmin服务未指定目标数据库的连接信息，在Docker内部网络中，服务间可通过服务名直接访问。修改phpmyadmin服务的环境变量：

phpmyadmin:
    image: 'phpmyadmin:latest'
    ports:
        - 8080:80
    networks:
        - sail
    environment:
        - PMA_ARBITRARY=1
        - PMA_HOST=mariadb  # 使用MariaDB服务名作为主机地址
        - PMA_PORT=3306     # MariaDB容器内部端口
        - PMA_USER=root     # 数据库用户名，可替换为你的DB_USERNAME
        - PMA_PASSWORD=${DB_PASSWORD}  # 对应.env中的数据库密码
    depends_on:
        - mariadb  # 确保MariaDB先启动

2. 调整服务启动依赖 #

原配置中laravel.test依赖phpmyadmin，这是不必要的，且可能导致启动顺序混乱。修改laravel.test的depends_on，移除phpmyadmin：

laravel.test:
    # ... 其他配置
    depends_on:
        - mariadb
        # - redis
        - mailpit

3. 连接PHPMyAdmin时的正确参数 #

访问http://localhost:8080后，填写以下连接信息：

• 主机名/地址：mariadb（不是localhost或127.0.0.1，因为PHPMyAdmin在容器内，需要访问Docker网络中的MariaDB服务）
• 用户名：root或你在.env中设置的DB_USERNAME
• 密码：.env文件中的DB_PASSWORD

4. 验证数据库服务状态 #

如果仍无法连接，可通过以下命令检查MariaDB是否正常运行：

• 进入MariaDB容器，登录数据库：

  sail exec mariadb mysql -u root -p
  

• 查看容器日志，排查启动错误：

  sail logs mariadb
  sail logs phpmyadmin
  

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