1. 环境准备与目标
1.1 目标与范围
本指南的目标是通过 从零开始用 Docker 搭建 PHP+MySQL 环境，实现一个可移植、可扩展的开发环境。利用 Docker Compose 将 PHP、MySQL、Nginx 等组件整合在一个可重复的流程中，便于团队协作与版本控制。
核心组件包括 PHP-FPM、Nginx、MySQL、以及数据卷和网络配置。通过这样的结构，可以将应用代码、数据库以及前端服务解耦，提升开发效率与部署一致性。
1.2 风险与前置条件
在执行前，请确认你的系统具备 Docker 环境和基本的命令行操作能力。对于 Windows、macOS 用户，建议使用 Docker Desktop，Linux 用户可直接安装 Docker Engine。版本兼容性会影响镜像拉取与网络通信，务必保持镜像版本在目标项目的范围内。
此外，确保你具备一个简单的应用目录结构，用于放置 index.php、nginx 配置、以及初始化脚本等文件。通过这一步，你可以避免后续路径与挂载问题带来的困扰。
2. 系统与依赖准备
2.1 安装 Docker 与 Docker Compose
第一步是获取稳定的 Docker 和 Docker Compose。对于 Ubuntu、Debian、CentOS 等 Linux 发行版，通常通过包管理器安装；Windows/macOS 用户可直接使用 Docker Desktop。以下命令仅作示例，实际请结合系统文档执行。
# 在 Ubuntu 上安装 Docker 与 Compose 的示例
sudo apt-get update
sudo apt-get install -y docker.io
sudo systemctl enable --now docker# 安装最新版本的 Docker Compose（若系统自带版本较旧，可直接从官方获取二进制）
sudo curl -L "https://github.com/docker/compose/releases/download/2.21.0/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
安装完成后，你可以通过 docker --version 和 docker-compose --version 验证是否成功安装。
2.2 验证安装
安装完成后，请执行以下命令进行验证，确保环境就绪。若命令返回版本信息，表示安装成功，后续步骤即可继续。
docker --version
docker-compose --version
注意：不同系统的默认路径可能略有差异，请以你实际环境为准。如果遇到权限问题，可能需要将当前用户加入 docker 组，或以 root 用户执行相关命令。
3. 使用 Docker Compose 搭建 PHP+MySQL
3.1 docker-compose.yml 的结构与字段解读
核心文件 docker-compose.yml 将所有服务以声明式方式定义，包含 php、nginx、mysql 三大服务。版本、镜像、卷、网络、环境变量等字段共同组成一个可重复的开发环境。
在该文件中，你会看到通过 volumes 将宿主机目录挂载到容器内，以实现代码热更新与数据持久化。镜像选择通常为 PHP-FPM、Nginx 与 MySQL 的官方镜像，便于维护与安全性。
version: '3.8'
services:php:image: php:8.2-fpmcontainer_name: app_phpvolumes:- ./app:/var/www/htmlnetworks:- app-networknginx:image: nginx:stable-alpinecontainer_name: app_nginxports:- "8080:80" # 本地端口 8080 映射到容器 80volumes:- ./nginx.conf:/etc/nginx/conf.d/default.conf- ./app:/var/www/htmldepends_on:- phpnetworks:- app-networkmysql:image: mysql:8.0container_name: app_mysqlenvironment:MYSQL_ROOT_PASSWORD: rootMYSQL_DATABASE: appdbMYSQL_USER: appuserMYSQL_PASSWORD: apppassvolumes:- db_data:/var/lib/mysql- ./init.sql:/docker-entrypoint-initdb.d/init.sqlports:- "3306:3306"networks:- app-networkvolumes:db_data:networks:app-network:
初始化脚本 init.sql 放在宿主机，挂载到 /docker-entrypoint-initdb.d/，MySQL 启动时会自动执行，快速初始化数据库结构与数据。
3.2 数据库初始化脚本与环境变量的结合
为了确保数据库在第一次启动时就已经具备初始数据结构，你可以在 init.sql 中定义建库、建表、以及初始数据。配合 docker-compose.yml 的环境变量，数据库的用户名和密码也将被安全地注入容器内。
CREATE DATABASE IF NOT EXISTS appdb;
CREATE USER 'appuser'@'%' IDENTIFIED BY 'apppass';
GRANT ALL PRIVILEGES ON appdb.* TO 'appuser'@'%';
FLUSH PRIVILEGES;
在容器启动时，MySQL 初始化脚本会被执行，确保数据库结构与初始数据就位，方便后续开发对接。
4. 配置 PHP 与 Web 服务器
4.1 Nginx 作为前端反向代理的配置要点
Nginx 作为反向代理/静态资源服务器，负责将对 80 端口的请求转发到 PHP-FPM，并处理静态资源。为了实现对 PHP 的正确解析，需要在 nginx.conf 中配置 FastCGI 参数。
server {listen 80;server_name localhost;root /var/www/html;index index.php index.html;location / {try_files $uri $uri/ /index.php?$query_string;}location ~ \\.php$ {include fastcgi_params;fastcgi_pass php:9000;fastcgi_index index.php;fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;}location ~ /\. {deny all;}
}
关键点：确保 fastcgi_pass 指向 php:9000，即 PHP-FPM 容器的 FastCGI 监听端口。挂载的应用目录应与 PHP 代码结构一致，避免路径错配。
4.2 PHP 应用结构与简单测试
把应用代码放在宿主机的 ./app 目录下，Nginx 通过挂载点能够直接访问。一个最简单的测试页面 index.php 可以帮助你确认环境就绪。
<?php
// index.php 示例
echo 'Hello from PHP running in Docker!';
?>
完整 URL 测试：打开浏览器访问 http://localhost:8080/index.php，即可看到输出。若看到页面输出，说明 Nginx 和 PHP-FPM 的对接正常。
5. 数据库初始化与安全
5.1 设置根密码与数据库用户
在 docker-compose.yml 的 environment 字段中设置 MYSQL_ROOT_PASSWORD、MYSQL_DATABASE、MYSQL_USER、MYSQL_PASSWORD，确保在容器创建时就具备初始的安全凭证与数据库对象。这样可以避免后续对数据库的手动初始化带来的重复工作。
environment:MYSQL_ROOT_PASSWORD: rootMYSQL_DATABASE: appdbMYSQL_USER: appuserMYSQL_PASSWORD: apppass
安全性提示：在生产环境中应避免使用简单明文密码，建议通过环境变量管理工具或密钥管理服务来注入敏感信息。
5.2 数据备份与恢复
数据库数据通过 volume 实现持久化，备份可以通过 MySQL 的 mysqldump 工具完成，结合 Docker 来执行跨容器备份。下面给出一个常用的备份命令示例。
# 备份 MySQL 数据库到 backup.sql
docker exec app_mysql mysqldump -u appuser -p'apppass' appdb > backup.sql
恢复时的要点：确保目标数据库名和用户存在，恢复命令中的数据库名称要与初始化时的一致，以避免数据结构错乱。
6. 运行与调试
6.1 启动容器与检查状态
在完成配置后，使用 docker-compose up -d 启动所有服务。你可以通过查看日志快速排错，确保各服务正确启动并连接。
docker-compose up -d
注意点：如果某个服务无法启动，请使用 docker-compose logs -f 查看实时日志，从而定位问题。确保端口映射（例如 8080 映射到 80）没有被其他进程占用。
6.2 验证访问与连通性
启动完成后，通过浏览器访问 http://localhost:8080，应能看到默认的 PHP 页面，或者通过 index.php 的输出进行验证。若页面能正常显示，说明前端与后端之间的通信正常。
# 直接请求示例
curl -s http://localhost:8080/index.php
数据库连通性验证：在应用中添加一个简单的 PDO/mysqli 连接测试，确保应用能够成功连接到 app_mysql 所暴露的 3306 端口，并使用数据库 appdb、用户 appuser、密码 apppass。
6.3 运行时维护与日志排错
日常运维中，建议关注 容器日志、卷的大小、以及 网络连通性。使用 docker-compose logs -f 能实时查看应用、数据库及前端服务的输出，帮助排查错误。
docker-compose logs -f
7. 实操要点与常见问题
7.1 端口映射、网络与资源限制
在 docker-compose.yml 中，端口映射是最常见的外部访问点。将 宿主机端口映射到容器端口时，确保端口未被其他应用占用。同一个网络（如 app-network）上的容器可以通过服务名相互访问，例如 nginx 通过 php:9000 与 php-fpm 通信。
另外要关注 资源限制，如 CPU、内存等，避免在本地开发环境中因为资源不足而导致容器频繁重启或性能下降。你可在 compose 文件中为服务添加 deploy 段（如仅在 swarm 模式有效）或使用宿主机管理策略实现平衡。
7.2 数据卷与持久化管理
数据卷确保数据库数据在容器重建后仍然可用。将数据库数据目录挂载到宿主机，避免 临时性文件丢失。对生产环境，建议定期备份并实现 增量备份 与 冷/热备份策略。
在开发阶段，务必保持 init.sql 与初始 SQL 文件可版本化，以便在需要重新初始化数据库时快速重建一致的初始状态。
7.3 常见问题排查要点
若遇到连接失败、端口占用、或服务不可用等问题，请先排查以下要点：镜像版本兼容性、容器日志、网络连通性以及 卷挂载路径正确性。逐步缩小范围，通常可以在 15-30 分钟内定位到问题来源。
在排错过程中，保持代码与配置的版本化，使用 git 对改动进行记录，确保你可以快速回退到稳定版本以便继续迭代。
