【Linux / Docker】Nginxの404地獄や肥大化Dockerfileとサヨナラする:本番運用のための設定ベストプラクティス4選
1. はじめに
フロントエンド・バックエンド・インフラを問わず、モダンな Web アプリケーション開発において Docker と Nginx は避けて通れない基盤技術です。
しかし、実際の現場では以下のような「地味に時間を溶かすトラブル」が頻発していませんか?
- SPA(React / Vue / Next.js)を Nginx でホストしたらリロード時に 404 が出る
- WebSocket 通信(リアルタイム通知など)が Nginx のプロキシ配下で切断される
- とりあえず作った Dockerfile のイメージサイズが 1.2GB を超えてデプロイが遅い
- コマンドラインで動かした
docker runのオプションが迷子になり、再現できない
本記事では、筆者が本番環境の構築や個人開発の現場で培った Docker & Nginx 運用の実践的ベストプラクティス をコード例付きで整理します。
2. 実践ベストプラクティス 4 選
① Nginx: SPA のリロード 404 を防ぎ、静的アセットを強力にキャッシュする
Single Page Application では、ブラウザ側のルーター(react-router や Next.js のクライアントルーティング)がパスを管理するため、Nginx 側で未設定のままリロードすると Web サーバーが実体ファイルを探索して 404 を返してしまいます。
server {
listen 80;
server_name example.com;
root /var/www/my-app/dist;
index index.html;
# 1. すべてのルーティングを index.html へフォールバック
location / {
try_files $uri $uri/ /index.html;
}
# 2. ハッシュ付き静的アセット(JS / CSS / 画像)は 1 年間イミュータブルキャッシュ
location ~* \.(?:js|css|png|jpg|jpeg|gif|svg|ico|woff2?)$ {
expires 1y;
add_header Cache-Control "public, immutable";
access_log off;
}
}
② Nginx: リバースプロキシでの「WebSocket 握手」と「Keepalive」の必須設定
Node.js や Go のバックエンドへリクエストを転送する際、単純に proxy_pass だけを書いていると、接続のたびに TCP 3-way ハンドシェイクが発生し、高負荷時にファイルディスクリプタが枯渇します。
# 1. 上流サーバーとの接続プールを保持
upstream backend_api {
server 127.0.0.1:3000 max_fails=3 fail_timeout=10s;
keepalive 64; # アイドル接続をプーリング
}
# 2. WebSocket 接続アップグレード用マップ定義
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
server {
listen 443 ssl http2;
server_name api.example.com;
location / {
proxy_pass http://backend_api;
proxy_http_version 1.1; # HTTP/1.1 は keepalive と websocket に必須
# ヘッダーの透過転送
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;
# WebSocket サポート
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_connect_timeout 60s;
proxy_read_timeout 120s;
}
}
ツール紹介:
多様なフレームワーク(Node, Go, Python, PHP)や SSL、セキュリティヘッダー(HSTS, CSP)を網羅した設定は、ブラウザ上でGUIから安全に生成できる Nginx 設定ジェネレーター (MiniToolDesk) も便利です。
③ Docker: マルチステージビルドでイメージサイズを 90% 以上削る
ビルドツール(npm、TypeScript コンパイラ、Go ツールチェーン等)を最終イメージに含めると、イメージ肥大化だけでなく脆弱性スキャン(CVE)の検知対象が増加します。
Go の極小イメージ例(約 15MB):
# Stage 1: ビルド環境
FROM golang:1.22-alpine AS builder
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -ldflags="-w -s" -o server .
# Stage 2: 最小の実行環境(scratch)
FROM scratch
COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
COPY --from=builder /app/server /server
# root 以外のユーザーで実行(セキュリティ必須要件)
USER 10001:10001
EXPOSE 8080
ENTRYPOINT ["/server"]
④ Docker Compose: 一時的な docker run コマンドを放置しない
検証時にターミナルで叩いた以下のコマンドは、時間が経つと「どのポートをマップしたか」「どのボリュームをバインドしたか」が必ず失われます。
docker run -d --name redis-prod -p 6379:6379 -v /data/redis:/data --restart unless-stopped redis:7-alpine
本番・ステージング環境へ反映する際は、直ちに Git 管理可能な compose.yaml へ落とし込みましょう。
services:
redis-prod:
image: redis:7-alpine
container_name: redis-prod
ports:
- "6379:6379"
volumes:
- /data/redis:/data
restart: unless-stopped
便利ツール:
複雑な引数を手動で YAML に書き写す手間は、ブラウザ内で 100% ローカル完結する Docker Run to Compose 変換ツール を使うと一瞬で正確に変換できます(通信ゼロのため社内パスワード付きコマンドも安心です)。
3. まとめ
インフラの安定性は、奇をてらった設計ではなく、こうした細部のコード化と自動化の積み重ねによって作られます。
- SPA のルーティングと静的配信キャッシュ を適切に切り分ける
- Nginx の Keepalive と WebSocket 透過 を標準設定化する
- Dockerfile はマルチステージビルド で軽量かつセキュアに保つ
-
docker runを撲滅し、すべてを宣言的な Compose コードで Git 管理する
日常の開発・検証を少しでもスムーズにするため、上記のような DevOps 支援ツール(全 183 種類以上)を 「広告なし・通信ゼロ・完全無料」 のオープンソースプロジェクトとして公開しています。
- MiniToolDesk 日本語版: https://minitooldesk.com/ja/
- GitHub: https://github.com/minitooldesk/minitooldesk
ぜひブックマークして、日々の開発のお供に活用してみてください!