Docker部署PHP应用教程（Nginx+PHP-FPM）

本文深入剖析了Docker环境下Nginx与PHP-FPM协同部署的核心痛点，直击fastcgi_pass配置错误导致的502/404/500等顽固问题，系统揭示了容器网络对齐、服务发现、监听地址匹配、权限控制及路径一致性等关键细节——从docker-compose网络声明、service名称严格一致、Unix socket与TCP选型权衡，到PHP-FPM监听配置、日志排查、多实例upstream手动编排，每一步都强调“先验证连通性，再调试逻辑”，帮你绕过90%的部署陷阱，真正实现开箱即用的稳定PHP应用容器化。

fastcgi_pass 配置错，Nginx 就根本不会把 PHP 请求发出去——不是 502，而是直接 404 或 500，因为 SCRIPT_FILENAME 路径没对上、socket 连不上、或容器名压根解析失败。别猜，先确认通信链路是否真实可达。

用 docker-compose.yml 启动 Nginx + PHP-FPM 是最稳的起点

所有服务必须定义在同一个 docker-compose.yml 文件里，且共用一个自定义网络，否则 fastcgi_pass php:9000 会报 host not found。

• networks 必须显式声明，不能依赖默认 bridge；例如：networks: [app-net]
• PHP-FPM service 名（如 php）就是 Nginx 配置里 fastcgi_pass 的主机名，大小写和连字符都要完全一致
• Nginx 容器启动前，PHP-FPM 容器必须已就绪；加 depends_on 不够，建议在 Nginx 配置里用 health_check 或启动脚本做探活
• 挂载代码路径要统一：Nginx 的 root 和 PHP-FPM 的 SCRIPT_FILENAME 必须指向同一宿主机目录，比如都映射 ./src:/var/www/html

fastcgi_pass 该用 IP、端口还是 Unix socket？

优先选 Unix socket（fastcgi_pass unix:/var/run/php/php-fpm.sock），性能高、权限可控；但前提是 socket 文件路径被 volume 挂载，且属主是 www-data:www-data。

• TCP 方式（如 fastcgi_pass php:9000）更简单，适合开发；但注意 PHP-FPM 容器必须监听 0.0.0.0:9000，而非默认的 127.0.0.1:9000（后者只接受本地连接）
• 如果用宿主机 Nginx（非容器），只能走 TCP 映射，比如 fastcgi_pass 127.0.0.1:9000，此时 PHP-FPM 容器需带 -p 9000:9000，且 SCRIPT_FILENAME 要对应宿主机上的代码路径
• 别混用：Nginx 在容器里就别去连宿主机的 127.0.0.1:9000，那是环回地址，进不了 Docker 网络

PHP-FPM 容器启动后，Nginx 仍报 502？查这三处

502 多半是 FastCGI 层连通了但 PHP-FPM 没响应，常见于配置不匹配或权限问题。

• 检查 PHP-FPM 日志：docker logs php，看是否有 unable to bind socket 或 failed to listen on address
• 确认 www.conf 中的 listen 值：TCP 场景下应为 0.0.0.0:9000，Unix socket 场景下应为 /var/run/php/php-fpm.sock，且路径与 Nginx 配置中 fastcgi_pass 严格一致
• 验证 socket 权限：docker exec -it php ls -l /var/run/php/，确保 php-fpm.sock 属主是 www-data，且权限为 srw-rw----
• 如果用了 chroot 或 chdir，SCRIPT_FILENAME 路径要按 chroot 后的根目录算，不是宿主机路径

多个 PHP-FPM 实例时，upstream 必须手动写死，不能靠 DNS 轮询

Docker Compose 的 DNS 只做 A 记录解析，不提供负载均衡能力；Nginx 的 upstream 块必须显式列出每个 service，并配策略。

• upstream 名称要和 fastcgi_pass 引用的一致，例如：fastcgi_pass fpm_backend; 对应 upstream fpm_backend { ... }
• 无状态服务用 least_conn；有本地 session 文件的旧项目必须加 ip_hash，否则用户反复登出
• 每个 PHP-FPM service 的配置（www.conf）、日志路径、socket 路径都得独立挂载，否则改一个崩全部
• 别漏 keepalive 32;，否则每请求建一次 TCP 连接，QPS 上不去

真正卡住的往往不是镜像或命令，而是 Nginx 启动那一刻——它会立即尝试解析 fastcgi_pass 后面的 host，失败就拒绝加载配置。所以 network、service 名、listen 地址、挂载路径，四者必须在 docker-compose up 前就对齐。

到这里，我们也就讲完了《Docker部署PHP应用教程（Nginx+PHP-FPM）》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于的知识点！