在compose.yml添加Composer命令后NGinX出现502 Bad Gateway错误

问题概述 #

原本PHP+Nginx栈运行正常，phpinfo测试页面可正常访问。但在docker-compose.yml的PHP服务中添加command: composer run-script serve命令后，页面出现502 Bad Gateway错误；注释该命令后服务恢复正常。

相关配置 #

Nginx配置文件 #

server {
    listen 80 default_server;
    listen [::]:80 default_server;
    
    server_name localhost;

    root /app;
    index index.php index.html;

    location / {
        fastcgi_buffers 8 16k; # increase the buffer size for PHP-FTP
        fastcgi_buffer_size 32k; # increase the buffer size for PHP-FTP
        fastcgi_connect_timeout 60;
        fastcgi_send_timeout 300;
        fastcgi_read_timeout 300;
  
        try_files $uri $uri/ /index.php?$args;
    }

    location ~* \.php$ {
        fastcgi_pass php:9000;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_param SCRIPT_NAME $fastcgi_script_name;
    }
    
    # Logs for Nginx access and errors
    access_log /var/log/nginx/access.log;
    error_log /var/log/nginx/error.log;
    
    # deny access to .htaccess/.htpasswd files
    location ~ /\.ht {
        deny all;
    }
}

Docker Compose配置 #

version: '3.8'

services:
    NGinX:
        image: nginx:latest
        container_name: NGinX
        hostname: NGinX
        security_opt:
            - no-new-privileges:true
        ports:
            - 6080:80/tcp
            - 6443:443/tcp
        dns:
            - 8.8.8.8
            - 1.1.1.1
        environment:
            - PUID=1000
            - PGID=100
            - TZ=Europe/London
            - UMASK=022
        volumes:
            - /volume1/docker/WebDev/NGinX/nginx.conf:/etc/nginx/conf.d/nginx.conf
            - /volume1/docker/WebDev/NGinX/Logs:/var/log/nginx
            - /volume1/docker/WebDev/WWW:/app
        restart: unless-stopped
        depends_on:
            - php

    php:
        build:
            context: .
            dockerfile: PHP.dockerfile
        tty: true
        container_name: PHP
        hostname: PHP
        security_opt:
            - no-new-privileges:true
        ports:
            - 9000:9000
        environment:
            - PUID=1000
            - PGID=100
            - TZ=Europe/London
            - UMASK=022
        volumes:
            - /volume1/docker/WebDev/WWW:/app
            - /volume1/docker/WebDev/PHP/local-php.ini:/usr/local/etc/php/conf.d/local.ini
        # run composer install command here instead of in the dockerfile to avoid volume mounting overwriting the vendor folder
        command: composer run-script serve
        restart: unless-stopped

Nginx错误日志 #

2024/07/20 12:48:32 [error] 23#23: *30 connect() failed (111: Connection refused) while connecting to upstream, client: 192.168.64.1, server: localhost, request: "GET / HTTP/1.1", upstream: "fastcgi://192.168.64.2:9000", host: "192.168.1.152:6080"
2024/07/20 12:48:32 [error] 23#23: *30 connect() failed (111: Connection refused) while connecting to upstream, client: 192.168.64.1, server: localhost, request: "GET /favicon.ico HTTP/1.1", upstream: "fastcgi://192.168.64.2:9000", host: "192.168.1.152:6080", referrer: "http://192.168.1.152:6080/"

原因分析 #

PHP容器默认启动的是PHP-FPM服务，该服务监听9000端口，与Nginx的fastcgi_pass php:9000配置匹配。而添加的composer run-script serve命令会启动PHP内置的开发服务器（通常监听8000端口），这个命令会替换掉容器原本的主进程（PHP-FPM），导致9000端口没有服务监听，Nginx无法建立连接，从而抛出连接拒绝的502错误。

解决方案 #

方案1：改用PHP内置开发服务器配合Nginx反向代理 #

如果确实需要使用composer run-script serve启动的开发服务器，需修改Nginx配置，将请求转发到开发服务器的端口（默认8000）：

1. 修改Nginx配置中的location /块，替换为反向代理配置：

location / {
    proxy_pass http://php:8000;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

2. 删除原有的location ~* \.php$块，因为PHP内置开发服务器会自行处理PHP文件请求。
3. 确保composer.json中的serve脚本确实监听8000端口，例如：

"scripts": {
    "serve": "php -S 0.0.0.0:8000"
}

方案2：保留PHP-FPM作为主进程，执行Composer初始化命令 #

如果要继续使用Nginx+PHP-FPM的架构，需让PHP容器优先启动PHP-FPM，同时执行Composer相关命令（比如安装依赖）：
修改Docker Compose中PHP服务的command为：

command: sh -c "composer install && php-fpm"

这样容器会先执行composer install安装依赖，然后启动PHP-FPM服务，保持9000端口正常监听，Nginx可以正常连接。

内容的提问来源于stack exchange，提问作者PHP Addict