Laravel+Nginx+MySQL的Docker Compose生产级配置详解

最新推荐文章于 2026-06-21 16:13:00 发布

原创

最新推荐文章于 2026-06-21 16:13:00 发布 · 438 阅读

1. 为什么不用“一键安装脚本”，而要亲手写 Docker Compose 文件

Laravel、Nginx 和 MySQL 这套组合，是 PHP Web 开发里最经典、最稳当的“铁三角”。但凡做过三年以上后端或全栈的人，都经历过在本地反复重装环境的痛苦：PHP 版本不兼容、MySQL 配置文件路径记错、Nginx 的 root 指向漏了个斜杠导致 404……更别说团队协作时，同事的“我本地跑得好好的”成了高频口头禅。过去我们靠文档、靠截图、靠口头约定来对齐环境，结果就是——开发效率卡在环境配置这道窄门上。

而 Docker Compose 不是魔法，它是一份 可执行、可版本化、可复现的环境契约 。它把“Laravel 应用该用什么 PHP 扩展”“Nginx 必须监听 80 端口并启用 gzip”“MySQL 的字符集必须是 utf8mb4_unicode_ci”这些隐性规则，全部显性地写进 docker-compose.yml 里。你 push 到 Git，别人 clone 下来 docker-compose up -d ，5 秒内就能获得和你一模一样的运行时环境——不是“差不多”，是 md5 校验级的一致。

这不是为了炫技。我去年带一个 7 人小团队做教育 SaaS，上线前两周，3 个前端、2 个后端、1 个测试、1 个产品，每人本地环境平均重装过 4.2 次（这是运维日志里统计的真实数字）。后来我们统一迁到 Compose 方案，环境初始化时间从平均 47 分钟压缩到 92 秒，且零配置冲突。关键在于： Compose 文件不是部署清单，而是环境说明书 + 启动脚本 + 隔离边界三者的融合体 。

所以，这篇不讲“如何下载 Docker Desktop”，也不教“怎么在 Windows 上开 WSL2”——那些是前置条件，网上教程汗牛充栋。我们要做的是：逐行拆解一份生产就绪（production-ready）的 docker-compose.yml ，告诉你每一行为什么这么写，删掉哪一行会导致 Laravel 报 Class 'PDO' not found ，改错哪个参数会让 Nginx 返回 502 Bad Gateway ，以及 MySQL 容器重启后数据为何没丢——不是靠运气，是靠设计。

核心关键词已经非常清晰： Laravel、Nginx、MySQL、Docker Compose 。它们不是孤立组件，而是一个有严格依赖顺序、数据流向和权限边界的微型系统。接下来所有内容，都围绕这个系统如何被精准定义、可靠启动、稳定协同展开。

2. `docker-compose.yml` 的骨架设计：服务分层与依赖锚点

很多人写 Compose 文件，第一反应是“先写 PHP 服务，再写 Nginx，最后写 MySQL”，结果跑起来发现 Laravel 总连不上数据库。问题不在代码，而在 Compose 的服务编排逻辑本身——它默认不保证启动顺序， depends_on 只控制容器创建先后，不等待服务就绪。这就要求我们必须用 分层架构思维 来组织服务，而不是简单罗列。

我把整个栈拆成三层： 数据层（Data Layer）、运行时层（Runtime Layer）、接入层（Ingress Layer） 。每层有明确职责、独立生命周期、清晰的对外接口。这种分层不是为了好看，而是为了故障隔离和弹性伸缩——比如未来想把 MySQL 换成云 RDS，只需替换数据层，其他两层完全不动。

2.1 数据层：MySQL 容器的持久化与初始化双保险

MySQL 服务不能只写 image: mysql:8.0 就完事。真实项目中，你必须同时解决两个问题： 数据持久化 和 首次初始化 。前者防止容器重启后数据库清空；后者确保 Laravel 迁移命令能直接执行，无需手动建库、设用户。

services:
  db:
    image: mysql:8.0.33
    restart: unless-stopped
    environment:
      MYSQL_ROOT_PASSWORD: rootpass123
      MYSQL_DATABASE: laravel_app
      MYSQL_USER: laravel
      MYSQL_PASSWORD: laravel123
    volumes:
      - db_data:/var/lib/mysql
      - ./mysql/init:/docker-entrypoint-initdb.d:ro
    command: --default-authentication-plugin=mysql_native_password
    healthcheck:
      test: ["CMD", "mysqladmin", "-u", "laravel", "-p$${MYSQL_PASSWORD}", "ping", "-h", "localhost"]
      interval: 30s
      timeout: 10s
      retries: 5
      start_period: 40s
volumes:
  db_data:

这里的关键细节远超表面：

volumes 中的 db_data 是命名卷（named volume），不是主机路径绑定。它由 Docker 管理，自动处理权限、跨平台路径映射，比 ./data/mysql 更可靠。我试过在 macOS 上用主机路径，结果 MySQL 启动失败报 Permission denied ，因为 macOS 的 /var 目录权限机制和 Linux 不同。
./mysql/init 目录下放 SQL 初始化脚本（如 01-create-tables.sql ），Docker MySQL 官方镜像会在首次启动时自动执行 /docker-entrypoint-initdb.d/ 下所有 .sql 或 .sh 文件。注意 :ro 标志——只读挂载，避免容器内误删初始化脚本。
command 行强制使用 mysql_native_password 认证插件。这是 Laravel 10+ 默认 PDO 驱动的要求。如果省略，MySQL 8.0 默认用 caching_sha2_password ，Laravel 会报 SQLSTATE[HY000] [2054] The server requested authentication method unknown to the client 。这个错误在 Stack Overflow 上有 1.2 万条提问，根源就在这行缺失。
healthcheck 不是可选项。它让 Docker 能真正判断 MySQL 是否“就绪”，而不仅是容器进程存活。 start_period: 40s 给 MySQL 充足的冷启动时间（InnoDB 缓冲池预热、日志恢复等），避免 Nginx 或 PHP 在 MySQL 还没准备好时就发起连接。

提示： MYSQL_PASSWORD 使用 ${MYSQL_PASSWORD} 语法，表示从宿主机环境变量读取。这样你可以在 .env 文件里统一管理密码，避免硬编码在 YAML 中。 .env 文件内容示例：
MYSQL_PASSWORD=laravel123
APP_KEY=base64:your-laravel-app-key-here

2.2 运行时层：PHP-FPM 容器的扩展与性能调优

Laravel 运行在 PHP-FPM 上，不是 Apache 的 mod_php。这意味着 PHP 容器必须提供 FPM socket 接口，并预装所有 Laravel 依赖扩展。很多人直接 FROM php:8.2-fpm ，结果发现 php artisan migrate 报错 Class 'PDO' not found ——因为官方 PHP 镜像默认不装任何扩展。

  app:
    build:
      context: .
      dockerfile: Dockerfile.php
    restart: unless-stopped
    volumes:
      - ./:/var/www/html:delegated
      - ./php/php.ini:/usr/local/etc/php/php.ini:ro
    environment:
      APP_ENV: local
      APP_DEBUG: 'true'
      APP_KEY: ${APP_KEY}
      DB_HOST: db
      DB_PORT: 3306
      DB_DATABASE: laravel_a

标签