Nginx配置下Laravel API POST请求返回502错误求助

问题现象 #

Laravel API部署在Docker环境中，GET请求可正常响应，但POST请求返回502 Bad Gateway错误。环境采用Nginx作为反向代理，PHP-FPM处理PHP请求。

环境配置 #

Nginx配置 #

server {
    listen 8080;
    server_name remote_addr;
    index index.php index.html;
    error_log  /var/log/nginx/error.log;
    access_log /var/log/nginx/access.log;
    root /var/www/app/public;

    location /api {
        try_files $uri /index.php?$query_string;
    }

    location ~ \.php$ {
        include fastcgi_params;
        fastcgi_pass php:9000;  # Changed to local PHP-FPM
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_param PATH_INFO $path_info;
    }
} 

docker-compose.yaml #

version: '3.8'

services:
  # Landing service (Next.js)
  landing:
    build:
      context: ./landing
      dockerfile: Dockerfile
    container_name: landing_page
    ports:
      - "3002:3000"
    networks:
      - app-network

  # Chat service (Next.js )
  chat:
    build:
      context: ./chat
      dockerfile: Dockerfile
    container_name: chat_app
    ports:
      - "3001:3000"
    networks:
      - app-network

  # Go service (for go-chat)
  go-chat:
    build:
      context: ./go-chat
      dockerfile: Dockerfile
    container_name: go_chat
    ports:
      - "7070:7070"
    networks:
      - app-network

  # Laravel backend service
  php:
    build:
      context: ./backend  # Backend dizini
      dockerfile: Dockerfile
    container_name: laravel_backend
    restart: unless-stopped
    tty: true
    ports:
        - "9000:9000"
    volumes:
      - ./backend:/var/www/app:delegated  # Uygulama dosyalarını bağlama
    networks:
      - app-network
   
  # PostgreSQL service
  postgres:
    image: postgres:15
    container_name: postgres_db
    environment:
      POSTGRES_DB: "project"
      POSTGRES_USER: "user"
      POSTGRES_PASSWORD: "pass"
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - app-network

  # Nginx service
  nginx:
    image: nginx:alpine
    container_name: nginx_proxy
    restart: unless-stopped
    ports:
      - "8080:80"
    volumes:
      - ./backend:/var/www/app
      - ./nginx/conf.d/:/etc/nginx/conf.d/
    networks:
      - app-network
    depends_on:
      - chat
      - landing
      - php

networks:
  app-network:
    driver: bridge

volumes:
  postgres_data:

Laravel Dockerfile #

# Base image
FROM php:8.2-fpm

# Install system dependencies
RUN apt-get update && apt-get install -y \
    build-essential \
    libpng-dev \
    libjpeg62-turbo-dev \
    libfreetype6-dev \
    locales \
    zip \
    jpegoptim optipng pngquant gifsicle \
    vim \
    unzip \
    git \
    curl \
    libpq-dev \
    && apt-get clean && rm -rf /var/lib/apt/lists/*

# Install PHP extensions
RUN docker-php-ext-install pdo pdo_pgsql

# Set working directory
WORKDIR /var/www/app

# Copy application files
COPY . ./

# Install Composer
RUN curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer

# Install PHP dependencies
RUN composer install --no-dev --optimize-autoloader

# Set permissions
RUN chown -R www-data:www-data /var/www/app/storage /var/www/app/bootstrap/cache \
    && chmod -R 775 /var/www/app/storage /var/www/app/bootstrap/cache

# Expose port 9000 and start php-fpm server
EXPOSE 9000
CMD ["php-fpm"]

排查与解决方案 #

1. 修复Nginx FastCGI配置 #

POST请求失败的常见原因是FastCGI参数干扰请求体解析，修改Nginx配置如下：

server {
    listen 80; # Docker映射8080:80，容器内监听80即可
    server_name _;
    index index.php index.html;
    error_log  /var/log/nginx/error.log;
    access_log /var/log/nginx/access.log;
    root /var/www/app/public;

    location /api {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        include fastcgi_params;
        fastcgi_pass php:9000;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        # 移除PATH_INFO参数，Laravel不需要该参数，会干扰POST请求解析
        # 显式传递POST请求必需的Content参数（fastcgi_params通常已包含，此处确保生效）
        fastcgi_param CONTENT_TYPE $content_type;
        fastcgi_param CONTENT_LENGTH $content_length;
        # 延长FastCGI超时时间，避免大请求超时返回502
        fastcgi_connect_timeout 300s;
        fastcgi_send_timeout 300s;
        fastcgi_read_timeout 300s;
    }
}

2. 确保PHP-FPM监听容器全局IP #

默认PHP-FPM仅监听127.0.0.1:9000，容器间通信需要监听0.0.0.0:9000，修改Laravel Dockerfile：

# ... 原有内容 ...

# 修改PHP-FPM监听地址，允许容器外部访问
RUN echo "listen = 0.0.0.0:9000" >> /usr/local/etc/php-fpm.d/www.conf

# Expose port 9000 and start php-fpm server
EXPOSE 9000
CMD ["php-fpm"]

3. 同步文件权限 #

Nginx和PHP容器共享挂载目录，确保宿主机与容器内权限一致：

# 在宿主机执行
chown -R www-data:www-data ./backend/storage ./backend/bootstrap/cache
chmod -R 775 ./backend/storage ./backend/bootstrap/cache

4. 验证容器网络连通性 #

在Nginx容器内测试与PHP容器的连通性：

# 测试ping
docker exec -it nginx_proxy ping php
# 测试端口连通
docker exec -it nginx_proxy telnet php 9000

如果端口不通，重启容器重建网络：

docker-compose down
docker-compose up -d --build

5. 查看日志定位具体错误 #

查看Nginx错误日志：

docker exec -it nginx_proxy tail -n 20 /var/log/nginx/error.log

添加PHP-FPM日志配置（可选）：
在Laravel Dockerfile中添加：

RUN echo "error_log = /var/log/php-fpm.log" >> /usr/local/etc/php-fpm.conf
RUN touch /var/log/php-fpm.log && chown www-data:www-data /var/log/php-fpm.log

查看PHP-FPM日志：

docker exec -it laravel_backend tail -n 20 /var/log/php-fpm.log

内容的提问来源于stack exchange，提问作者inanc eroglu