【Docker】Nginx + PHP-FPM完全ガイド｜FastCGI・pm.max_children計算・OPcache/JIT・Xdebug 3・フレームワーク別rewrite

ブラウザ
   ↓ HTTP
Nginx（静的ファイルならここで配信完了）
   ↓ FastCGIプロトコル（TCPまたはUnix socket）
PHP-FPMプロセスプール
   ↓ PHP実行
アプリケーション（Laravel等）
   ↓ DB/Redis/外部API等
結果をFastCGI経由でNginxに返す
   ↓ HTTPレスポンス
ブラウザ

project/
├─ compose.yml
├─ docker/
│  ├─ nginx/
│  │  └─ default.conf
│  └─ php/
│     ├─ Dockerfile
│     ├─ php.ini
│     └─ www.conf
└─ app/
   └─ public/
      └─ index.php

services:
  nginx:
    image: nginx:1.27-alpine
    ports: ["8080:80"]
    volumes:
      - ./app:/var/www/html
      - ./docker/nginx/default.conf:/etc/nginx/conf.d/default.conf:ro
    depends_on:
      php:
        condition: service_healthy

  php:
    build: ./docker/php
    volumes:
      - ./app:/var/www/html
    healthcheck:
      test: ["CMD", "php-fpm", "-t"]
      interval: 10s
      retries: 5

FROM php:8.3-fpm-alpine

RUN apk add --no-cache \
    icu-dev libpng-dev libjpeg-turbo-dev libzip-dev oniguruma-dev \
 && docker-php-ext-configure intl \
 && docker-php-ext-install -j$(nproc) intl opcache pdo pdo_mysql mbstring zip gd

COPY php.ini /usr/local/etc/php/conf.d/zzz-custom.ini
COPY www.conf /usr/local/etc/php-fpm.d/zzz-www.conf

WORKDIR /var/www/html

server {
  listen 80;
  server_name localhost;

  root /var/www/html/public;
  index index.php;

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

  location ~ \.php$ {
    fastcgi_pass php:9000;
    fastcgi_index index.php;
    include fastcgi_params;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    fastcgi_read_timeout 60s;
  }
}

<?php
phpinfo();

docker compose up -d --build
# http://localhost:8080 で phpinfo() が表示されれば成功

# ステージ1: Composer依存解決（CI/本番で変更頻度低い）
FROM composer:2 AS composer

WORKDIR /app
COPY composer.json composer.lock ./
RUN composer install \
    --no-dev --no-interaction --no-progress --no-scripts \
    --prefer-dist --optimize-autoloader

# ステージ2: PHP-FPM本体
FROM php:8.3-fpm-alpine

# 必要拡張を一括インストール
RUN apk add --no-cache \
    icu-dev libpng-dev libjpeg-turbo-dev libzip-dev oniguruma-dev \
    postgresql-dev linux-headers \
 && docker-php-ext-configure intl \
 && docker-php-ext-install -j$(nproc) \
    intl opcache pdo pdo_mysql pdo_pgsql mbstring zip gd bcmath pcntl sockets \
 && pecl install redis \
 && docker-php-ext-enable redis \
 && apk del --no-cache icu-dev libpng-dev libjpeg-turbo-dev libzip-dev postgresql-dev linux-headers

# Composerのバイナリをコピー
COPY --from=composer /usr/bin/composer /usr/bin/composer

# 設定ファイル
COPY php.ini /usr/local/etc/php/conf.d/zzz-custom.ini
COPY www.conf /usr/local/etc/php-fpm.d/zzz-www.conf

WORKDIR /var/www/html

# 非rootユーザーで起動
USER www-data

EXPOSE 9000

services:
  nginx:
    image: nginx:1.27-alpine
    ports: ["8080:80"]
    volumes:
      - ./app:/var/www/html
      - ./docker/nginx/default.conf:/etc/nginx/conf.d/default.conf:ro
      - ./docker/nginx/snippets:/etc/nginx/snippets:ro
      - nginx-cache:/var/cache/nginx
    depends_on:
      php:
        condition: service_healthy
    healthcheck:
      test: ["CMD-SHELL", "wget -qO- http://localhost/healthz || exit 1"]
      interval: 10s
      retries: 5
    networks: [app-net]

  php:
    build:
      context: ./docker/php
      target: dev                    # multi-stageのdev段階
    environment:
      PHP_IDE_CONFIG: "serverName=docker"
      TZ: "Asia/Tokyo"
    volumes:
      - ./app:/var/www/html
    healthcheck:
      test: ["CMD", "php-fpm", "-t"]
      interval: 10s
      retries: 5
    networks: [app-net]

  db:
    image: mariadb:11
    environment:
      MARIADB_DATABASE: app
      MARIADB_USER: app
      MARIADB_PASSWORD: app
      MARIADB_ROOT_PASSWORD: root
    volumes:
      - db_data:/var/lib/mysql
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect"]
      interval: 5s
      retries: 10
    networks: [app-net]

  redis:
    image: redis:7-alpine
    networks: [app-net]

volumes:
  db_data:
  nginx-cache:

networks:
  app-net:

server {
  listen 80;
  server_name localhost;

  root /var/www/html/public;
  index index.php;

  charset utf-8;
  client_max_body_size 20M;
  sendfile on;
  tcp_nopush on;
  tcp_nodelay on;

  # ヘルスチェック（depends_onのhealthcheck用）
  location = /healthz {
    access_log off;
    return 200 "ok";
    add_header Content-Type text/plain;
  }

  # 静的ファイルは長期キャッシュ
  location ~* \.(?:css|js|woff2?|ttf|otf|ico|png|jpg|jpeg|gif|webp|svg)$ {
    expires 1y;
    add_header Cache-Control "public, immutable";
    access_log off;
    try_files $uri =404;
  }

  # フロントコントローラ（Laravel等）
  location / {
    try_files $uri $uri/ /index.php?$query_string;
  }

  # PHP実行
  location ~ \.php$ {
    try_files $uri =404;                # 存在しないphpは404
    fastcgi_split_path_info ^(.+\.php)(/.+)$;
    fastcgi_pass php:9000;
    fastcgi_index index.php;
    include fastcgi_params;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    fastcgi_param PATH_INFO $fastcgi_path_info;
    fastcgi_read_timeout 60s;
    fastcgi_buffers 16 16k;
    fastcgi_buffer_size 32k;
  }

  # .htaccess等を外部から見せない
  location ~ /\.(?!well-known).* {
    deny all;
  }
}

# Laravel / Symfony（/index.phpへフロントコントローラ）
location / {
  try_files $uri $uri/ /index.php?$query_string;
}

# WordPress（index.phpへ、?にパスを渡さない）
location / {
  try_files $uri $uri/ /index.php?$args;
}

# CodeIgniter 4（publicディレクトリから）
location / {
  try_files $uri $uri/ /index.php?$uri&$args;
}

# Yii2（statselbypublic）
location / {
  try_files $uri $uri/ /index.php$is_args$args;
}

# 複数serverブロックで同じPHP設定を使う
fastcgi_split_path_info ^(.+\.php)(/.+)$;
fastcgi_pass php:9000;
fastcgi_index index.php;
include fastcgi_params;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
fastcgi_param PATH_INFO $fastcgi_path_info;
fastcgi_read_timeout 60s;

# default.conf内で使う
# location ~ \.php$ {
#   include /etc/nginx/snippets/fastcgi-php.conf;
# }

[www]
user = www-data
group = www-data
listen = 9000
listen.allowed_clients = 127.0.0.1

; プロセスマネージャ
pm = dynamic
pm.max_children = 10            ; 最大プロセス数
pm.start_servers = 3            ; 起動時のプロセス数
pm.min_spare_servers = 2        ; アイドル最小
pm.max_spare_servers = 5        ; アイドル最大
pm.max_requests = 500           ; メモリリーク予防でN回で再起動

; ステータスページ（監視用）
pm.status_path = /fpm-status

; ping（healthcheck用）
ping.path = /fpm-ping

; ログ
access.log = /proc/self/fd/2
catch_workers_output = yes
decorate_workers_output = no

; タイムアウト
request_terminate_timeout = 60s
request_slowlog_timeout = 10s
slowlog = /proc/self/fd/2

pm.max_children = (利用可能RAM - 予約分) / 1プロセスの平均メモリ

例: コンテナメモリ1GB、1プロセス50MB使用、OSとopcache等で200MB予約
    (1024 - 200) / 50 = 16プロセス → 切り下げて pm.max_children = 14

# プロセスの実メモリを確認
docker compose exec php ps -o pid,rss,cmd ax

; === OPcache 開発用 ===
opcache.enable = 1
opcache.enable_cli = 0
opcache.validate_timestamps = 1      ; ファイル更新チェック
opcache.revalidate_freq = 0          ; 即時反映（開発向き）
opcache.memory_consumption = 128
opcache.interned_strings_buffer = 16
opcache.max_accelerated_files = 10000
opcache.fast_shutdown = 1

; === 開発で役立つ設定 ===
display_errors = On
display_startup_errors = On
error_reporting = E_ALL
log_errors = On
error_log = /proc/self/fd/2          ; Dockerログへ

; === OPcache 本番用 ===
opcache.enable = 1
opcache.enable_cli = 1
opcache.validate_timestamps = 0      ; ファイルチェック無効（超速）
opcache.memory_consumption = 256
opcache.interned_strings_buffer = 32
opcache.max_accelerated_files = 20000
opcache.fast_shutdown = 1
opcache.save_comments = 1            ; attribute等で必要
opcache.preload = /var/www/html/preload.php
opcache.preload_user = www-data

; === JIT（PHP 8+） ===
opcache.jit_buffer_size = 128M
opcache.jit = tracing                ; tracing が一般的

; === セキュリティ ===
expose_php = Off
display_errors = Off
log_errors = On
error_log = /proc/self/fd/2

# 既存の拡張インストールに続けて追加
RUN pecl install xdebug \
 && docker-php-ext-enable xdebug

COPY xdebug.ini /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini

zend_extension=xdebug

; Xdebug 3 の新形式
xdebug.mode = debug,develop
xdebug.start_with_request = yes
xdebug.client_host = host.docker.internal
xdebug.client_port = 9003
xdebug.idekey = VSCODE
xdebug.log = /tmp/xdebug.log

; 開発では discover_client_host をOFFで固定
xdebug.discover_client_host = 0

services:
  php:
    build: ./docker/php
    extra_hosts:
      - "host.docker.internal:host-gateway"   # Linux対応
    # Xdebug用ポートは不要（phpからホストへ接続する方向）

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Listen for Xdebug (Docker)",
      "type": "php",
      "request": "launch",
      "port": 9003,
      "pathMappings": {
        "/var/www/html": "${workspaceFolder}/app"
      },
      "xdebugSettings": {
        "max_children": 128,
        "max_data": 1024,
        "max_depth": 5
      }
    }
  ]
}

# 前述のmulti-stage Dockerfile参照
# composerステージでインストール → php-fpmステージにvendor/をCOPY

COPY --from=composer --chown=www-data:www-data /app/vendor /var/www/html/vendor

# phpコンテナ内でcomposerも使えるように
RUN curl -sS https://getcomposer.org/installer | php -- \
    --install-dir=/usr/local/bin --filename=composer

# 実行例
docker compose exec php composer install
docker compose exec php composer require monolog/monolog
docker compose exec php composer dump-autoload

services:
  php:
    # ... 本体

  composer:
    image: composer:2
    volumes:
      - ./app:/app
    working_dir: /app
    profiles: ["tools"]          # 通常起動しない
    command: install

# 依存インストール
docker compose run --rm composer install

# パッケージ追加
docker compose run --rm composer require laravel/sanctum

# ① nginx.conf（最優先で弾かれる）
http {
  client_max_body_size 128M;
}
# または server{} / location{} 個別指定も可

# ② php.ini
upload_max_filesize = 128M
post_max_size = 130M                 ; upload_max_filesize より大きく
memory_limit = 256M                  ; post_max_size以上が望ましい

# ③ php-fpm www.conf
; request_terminate_timeout が短いと大ファイルで中断
request_terminate_timeout = 300

# ④ フレームワーク側（Laravel例）
# Laravelの form validation でも max:131072 (KB) 設定
# WordPress wp-admin → 設定 → メディア でサーバー上限表示

; PHPバージョンを隠す（Server: PHP/8.3.xを消す）
expose_php = Off

; ディレクトリ制限（アップロード先／キャッシュだけ許可）
open_basedir = "/var/www/html:/tmp:/usr/share/php"

; 危険な関数を無効化
disable_functions = exec,passthru,shell_exec,system,proc_open,popen,curl_multi_exec,parse_ini_file,show_source

; セッションのセキュア設定
session.cookie_httponly = 1
session.cookie_secure = 1            ; HTTPS必須
session.cookie_samesite = Lax
session.use_strict_mode = 1
session.sid_length = 48
session.sid_bits_per_character = 6

; ファイルアップロードの制限
file_uploads = On
upload_tmp_dir = /var/www/html/tmp

; エラー情報を外部に漏らさない
display_errors = Off
display_startup_errors = Off
log_errors = On

# 共通セキュリティヘッダー
add_header X-Content-Type-Options "nosniff" always;
add_header X-Frame-Options "SAMEORIGIN" always;
add_header Referrer-Policy "strict-origin-when-cross-origin" always;
add_header Permissions-Policy "geolocation=(), camera=(), microphone=()" always;

# PHPのServer: PHP/... を消す（expose_php=Offとの二重対策）
fastcgi_hide_header X-Powered-By;
more_clear_headers Server;            # headers-more モジュール必要

# HTTPS時
add_header Strict-Transport-Security "max-age=63072000; includeSubDomains" always;

# php-fpm.conf
listen = /var/run/php-fpm.sock
listen.owner = www-data
listen.group = www-data
listen.mode = 0660

# nginx.conf
fastcgi_pass unix:/var/run/php-fpm.sock;

# compose.ymlでsocketディレクトリを両コンテナで共有
volumes:
  - php-socket:/var/run

# 一時的に display_errors を ON
docker compose exec php sh -c "echo 'display_errors=On' > /usr/local/etc/php/conf.d/temp-errors.ini"
docker compose restart php

# PHP-FPMのエラーログを追跡
docker compose logs -f php

# プロセス中で直接エラーを吐き出す
docker compose exec php tail -f /proc/self/fd/2

# ① nginx側
fastcgi_read_timeout 300s;

# ② php.ini
max_execution_time = 300
max_input_time = 300

# ③ php-fpm www.conf
request_terminate_timeout = 300

# ④ フレームワーク側のタイムアウト設定

# opcache.validate_timestamps=0 の本番で
docker compose exec php php -r "opcache_reset();"

# または FPMプロセスをreload（graceful restart）
docker compose exec php kill -USR2 1

# コンテナを再起動してもOK
docker compose restart php