nginxリバースプロキシの設定|proxy_passの末尾スラッシュとHost

  • nginx でアプリへ転送したら、アプリ側で Host やアクセス元の IP がおかしい
  • proxy_pass の最後に / を付けるかどうかで、転送先のパスが変わって混乱している
  • /api/ だけ別のアプリに送りたい。管理画面は外から開けないようにしたい

nginx のリバースプロキシは、proxy_pass の1行でも動きます。ただ、それだけだとアプリに届くパスやヘッダーが、思っていたものと違うことがあります。

押さえるところは2つです。proxy_pass の末尾の / で転送先のパスが変わることと、ヘッダーを足さないと元のドメインや IP がアプリに伝わらないことです。

この記事では、手元の Docker で nginx 1.30.6 を動かし、アプリが実際に受け取ったパスとヘッダーを見ながら説明します。

設定ファイルの場所と、server・location の基本の書き方は、こちらの記事にまとめています。

項目内容
nginxnginx 1.30.6(Docker の nginx:1.30-alpine)
受け側のアプリpython:3.12-alpine で動かした、受け取った内容を返すだけの小さなサーバー
動かした場所Mac の Docker Desktop(docker compose)
確かめ方curl 8.7.1 で送り、アプリの返事と nginx のログを見る
この記事の環境(2026年11月19日に確認)

ドメインは例として example.test を使っています。

リバースプロキシとは

リバースプロキシは、利用者からのリクエストを nginx がいったん受け取り、裏にあるアプリへ渡す仕組みです。アプリの返事は、nginx を通って利用者に返ります。

順番やりとり
1ブラウザが nginx(80番・443番)にアクセスする
2nginx が、location の設定に合わせてアプリ(8000番など)へ転送する
3アプリの返事を、nginx がブラウザへ返す
リバースプロキシの流れ

アプリを直接インターネットに出さずに、前に nginx を置く理由は次のとおりです。

  • HTTPS の証明書を nginx でまとめて扱える
  • 1台のサーバーで、ドメインやパスごとに別のアプリへ振り分けられる
  • 管理画面を閉じる、送れる大きさを決めるなど、アプリに届く前に断れる
  • 画像や CSS などの静的なファイルは nginx が直接返せる

僕の VPS での使い方

僕の VPS では、Docker で動かしている nginx を1つだけ入口にしています。

1つのドメインの中で、/ はフロントのアプリへ、/api/ は API のアプリへ転送しています。/admin/ は nginx で 403 にして、アプリまで届かないようにしています。

この記事の例は、この設定を元にしています。nginx の役割そのものから知りたい場合は、入門記事をどうぞ。

最小の設定

まずは、ヘッダーを何も足さない、いちばん短い設定です。

127.0.0.1 へ転送する(apt で入れた nginx)

apt で入れた nginx と、同じサーバーで動かしているアプリなら、転送先は 127.0.0.1 とポート番号です。

Nginx
server {
    listen 80;
    server_name example.test;

    location / {
        proxy_pass http://127.0.0.1:8000;
    }
}

6行目で、すべてのパスを 8000番で待っているアプリへ渡しています。Django を Gunicorn で動かす場合は、ここが Gunicorn の待ち受け先になります。

Gunicorn の起動と systemd での常駐は、こちらの記事で書いています。

Docker ではサービス名へ転送する

nginx もアプリも Docker Compose で動かしている場合は、転送先にサービス名を書きます。今回の実験の compose.yaml は次のとおりです。

YAML
services:
  app:
    image: python:3.12-alpine
    command: python /app.py
    volumes: ["./app.py:/app.py:ro"]
  nginx:
    image: nginx:1.30-alpine
    volumes: ["./nginx.conf:/etc/nginx/nginx.conf:ro"]
    ports: ["127.0.0.1:18080:80"]
    depends_on: [app]

同じ Compose のネットワークにいるので、nginx からは app という名前でアプリにつながります。

Nginx
location /plain/ {
    proxy_pass http://app:8000;
}

この設定で /plain/x にアクセスすると、アプリには次の内容が届きました。

Plaintext
path: /plain/x
  Host: app:8000
  User-Agent: curl/8.7.1
  Accept: */*

転送はできています。ただ、Host が app:8000 になっています。利用者が開いたのは example.test なのに、アプリにはそれが伝わっていません。

これを直すのが、次の章のヘッダーです。

Docker の中で 127.0.0.1 へ転送すると 502 になる

apt 版の感覚で、Docker の nginx にも 127.0.0.1 を書くと、つながりません。

Nginx
location /local/ {
    proxy_pass http://127.0.0.1:8000;
}

実際に試すと、ステータスは 502 でした。エラーログには次の行が出ています。

Plaintext
connect() failed (111: Connection refused) while connecting to upstream, client: 172.18.0.1, server: example.test, request: "GET /local/x HTTP/1.1", upstream: "http://127.0.0.1:8000/local/x", host: "example.test"

コンテナの中の 127.0.0.1 は、nginx のコンテナ自身を指します。nginx のコンテナの 8000番では誰も待っていないので、接続を断られて 502 になります。

Docker で 502 が出たら、まず upstream: の宛先を見てください。127.0.0.1 になっていたら、サービス名に直します。

Compose のネットワークとサービス名の仕組みは、こちらの記事で詳しく書いています。

proxy_set_header で元の情報を渡す

nginx が転送するとき、アプリから見た相手は nginx です。そのままでは、利用者が開いたドメインやアクセス元の IP がアプリに分かりません。

そこで proxy_set_header で、元の情報をヘッダーに入れて渡します。よく使うのは次の4行です。

Nginx
location /hdr/ {
    proxy_pass http://app: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;
}

この設定で /hdr/x にアクセスすると、アプリには次のように届きました。

Plaintext
path: /hdr/x
  Host: example.test
  X-Real-IP: 172.18.0.1
  X-Forwarded-For: 172.18.0.1
  X-Forwarded-Proto: http
  User-Agent: curl/8.7.1
  Accept: */*

最小の設定と比べると、Host が example.test に変わり、3つのヘッダーが増えています。それぞれの意味は次のとおりです。

ヘッダー入れる値アプリに伝わること
Host$host利用者が開いたドメイン
X-Real-IP$remote_addrnginx に直接つないできた相手の IP
X-Forwarded-For$proxy_add_x_forwarded_for通ってきた IP の一覧(最後に nginx が見た相手を足す)
X-Forwarded-Proto$scheme利用者が http と https のどちらで来たか
proxy_set_header の4行

手元の実験では、Mac から送ったリクエストが 172.18.0.1 として届いています。VPS で公開すれば、ここに利用者の IP が入ります。

Host:足さないとアプリにはサービス名が届く

proxy_set_header で Host を書かないと、nginx は proxy_pass に書いた名前を Host にして送ります。最小の設定で Host: app:8000 になったのは、このためです。

$host を入れると、利用者が送ってきたドメインがそのまま届きます。$host にはポート番号は付きません。

Host が違うと、アプリでは次のようなことが起きます。

  • Django では、ALLOWED_HOSTS に入っていない名前として 400 で断られる
  • アプリが作るリダイレクト先や URL が、app:8000 のような内部の名前になる
  • ドメインで処理を分けているアプリで、どのサイトか判断できない

サービス名に _(アンダースコア)が入っていると、Django では ALLOWED_HOSTS をすべて許可にしても 400 になります。

Host を足していれば、nginx から転送する分は公開ドメインが届くので、この問題は起きません。

_ の入った名前で 400 になった実例と直し方は、こちらにまとめています。

X-Real-IP と X-Forwarded-For

どちらも、アクセス元の IP をアプリに伝えるためのヘッダーです。

X-Real-IP には、nginx に直接つないできた相手の IP が1つだけ入ります。X-Forwarded-For は、途中で通ってきた IP を , 区切りで並べるヘッダーです。

$proxy_add_x_forwarded_for は、届いた X-Forwarded-For の後ろに、nginx が見た相手の IP を足します。

試しに、curl で X-Forwarded-For を付けて送ってみました。

ShellScript
curl -H 'Host: example.test' -H 'X-Forwarded-For: 203.0.113.5' http://127.0.0.1:18080/hdr/x

アプリに届いた値は次のとおりです。

Plaintext
X-Forwarded-For: 203.0.113.5, 172.18.0.1

送った 203.0.113.5 が先頭に残り、nginx が見た 172.18.0.1 が後ろに足されています。

先頭の値は、利用者が好きな値を書いて送れます。アクセス元を記録したり制限したりするときに、X-Forwarded-For の先頭をそのまま信じないでください。

nginx の前に別のプロキシ(ロードバランサーなど)がある構成なら、$proxy_add_x_forwarded_for で後ろに足していくのが合っています。

nginx がいちばん外側の入口なら、X-Forwarded-For に $remote_addr を入れる書き方もあります。僕の VPS の設定も、この形です。

Nginx
proxy_set_header X-Forwarded-For $remote_addr;

こうすると、利用者が送ってきた X-Forwarded-For は、nginx が見た IP に置き換わります。上の例なら 203.0.113.5 は残らず、偽の値をアプリに渡さずに済みます。

今回の実験で試したのは $proxy_add_x_forwarded_for のほうだけです。$remote_addr の書き方は、nginx の仕様からの一般的な説明です。

X-Forwarded-Proto

$scheme には、利用者が nginx に来たときの http か https が入ります。今回の実験は http で送ったので、http になっています。

HTTPS を nginx で受けて、アプリへは http で転送する構成はよくあります。このときアプリから見ると、通信はいつも http です。

X-Forwarded-Proto がないと、アプリは利用者が https で来たことを知れません。https へのリダイレクトがくり返されたり、http の URL を作ってしまったりすることがあります。

Django では、SECURE_PROXY_SSL_HEADER を設定すると、このヘッダーを見て https と判断します。

nginx で HTTPS にする手順は、こちらの記事にあります。

location ごとに4行を書く理由

nginx の仕様では、proxy_set_header は、その location に1行でも proxy_set_header があると、server などの外側に書いたものを引き継ぎません。

外側に4行を書いておき、ある location で1行だけ足すと、その location ではほかの3行が消えます。

僕の設定でも、外側にはまとめず、proxy_pass を書く location ごとに4行を書いています。

パスで振り分ける

1つのドメインの中で、パスごとに別のアプリへ送ることもできます。

/api/ だけ別のアプリへ送る

僕の VPS と同じように、/api/ を API のアプリへ、それ以外をフロントのアプリへ送る例です。

Nginx
location /api/ {
    proxy_pass http://api: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;
}

location / {
    proxy_pass http://web:3000;
    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;
}

/api/users/1 は、/api/ と / のどちらにも当てはまります。前方一致の location は、長く一致したほうが選ばれます。そのため /api/ のほうが使われます。書いた順番は関係ありません。

proxy_pass に http://api:8000 のようにパスを書いていないので、アプリには /api/users/1 がそのまま届きます。実験でも、同じ形の設定で /api/users/1 が届きました。

API のアプリが /api/ なしのパスで待っている場合は、次の末尾の / の書き方で変えられます。

proxy_pass の末尾の / で転送先のパスが変わる

proxy_pass の書き方で、アプリに届くパスは変わります。決まりは次の2つです。

  • proxy_pass にパスがない(http://app:8000)なら、リクエストのパスをそのまま渡す
  • proxy_pass にパスがある(http://app:8000/ や http://app:8000/v1/)なら、location に一致した部分をそのパスに置き換える

最後の / 1文字でも「パスがある」になる点が、間違えやすいところです。

4つの書き方で試しました。受け側には、受け取ったリクエストの1行目をそのまま返すだけのサーバーを使っています。

locationproxy_passリクエストアプリが受けたパス
/api/http://app:8000/api/users/1/api/users/1
/api/http://app:8000//api/users/1/users/1
/apihttp://app:8000//api/users/1//users/1
/apihttp://app:8000//apix/users/x/users
/api/http://app:8000/v1//api/users/1/v1/users/1
proxy_pass の末尾の / とアプリが受けたパス(nginx 1.30.6)

1行目は proxy_pass にパスがないので、/api/users/1 がそのまま届きました。

2行目は、location の /api/ が proxy_pass の / に置き換わり、/users/1 になっています。API のアプリが /api/ なしのパスで待っているなら、この書き方です。

最後の行は、/api/ が /v1/ に置き換わりました。アプリ側のパスの前に何か付けたいときは、この書き方です。

location /api だと //users や /apix まで拾ってしまう

間違えやすいのが3行目と4行目です。location は /api(最後の / なし)、proxy_pass は http://app:8000/(/ あり)です。

Nginx
# よくない例:location に最後の / がない
location /api {
    proxy_pass http://app:8000/;
}

/api/users/1 の /api の部分が / に置き換わるので、残りの /users/1 と合わせて //users/1 になります。/ が2つ続いたパスが、アプリに届いています。

もう1つの落とし穴は、location /api が「/api で始まるパスすべて」に一致することです。/apix/users も一致して、/x/users として届きました。

/apikey や /api-docs のようなパスまで、同じアプリに送られることになります。

この実験では、最初に Python の http.server で作った確認用のアプリでも試しました。そのアプリは同じリクエストを /users/1 と表示していて、二重の / に気づけませんでした。

受け側が // を1つにまとめて見せることがあるので、アプリの表示だけでは分かりません。パスがおかしいと思ったら、location と proxy_pass の / の付け方を先に見直します。

直し方は、location の最後にも / を付けて、proxy_pass とそろえることです。

Nginx
# location と proxy_pass の最後の / をそろえる
location /api/ {
    proxy_pass http://app:8000/;
}

こうすると、/api/users/1 は表の2行目と同じく /users/1 で届き、/apix/users はこの location に一致しなくなります。

nginx で閉じる

リバースプロキシの nginx は、アプリに届く前にリクエストを断る場所としても使えます。

/admin/ を 403 にする

外から開く必要のない管理画面は、nginx で閉じています。僕の VPS の設定と同じ形です。

Nginx
location ^~ /admin/ {
    return 403;
}

return 403; だけを書き、proxy_pass は書きません。nginx がその場で 403 を返すので、リクエストはアプリまで届きません。

実験でも /admin/ は 403 になり、アクセスログの転送先は upstream=-(どこにも転送していない)でした。

^~ を付けているのは、正規表現の location に横取りされないためです。正規表現で /admin/ の下にも当てはまる location を書いていると、^~ がなければそちらが選ばれることがあります。

同じ考え方で、フロントだけを公開しているサイトでは、/api/ を return 404; で閉じています。そのサイトのアプリには /api/ がありませんが、裏の API を外へ出さないよう、入口でも閉じています。

client_max_body_size を超えると 413 になる

client_max_body_size は、リクエストの本文(POST で送るデータなど)の大きさの上限です。超えると、nginx は 413 を返して、アプリへは渡しません。

nginx の既定は 1m(1MB)です。僕の VPS では、全体を 10m にして、ご意見フォームの location だけ 8k に絞っています。

Nginx
http {
    client_max_body_size 10m;

    server {
        location = /feedback {
            client_max_body_size 8k;
            proxy_pass http://web:3000;
        }
    }
}

http・server・location のどこにも書けて、内側に書いたものが使われます。画像を送る画面があるなら広げ、短い文章しか来ないフォームは狭くする、という使い分けです。

実験では server に client_max_body_size 1k; を書き、2KB と 500B の POST を送りました。

ShellScript
head -c 2048 /dev/zero | curl -s -o /dev/null -w 'status=%{http_code}\n' -H 'Host: example.test' --data-binary @- http://127.0.0.1:18080/hdr/x
head -c 500 /dev/zero | curl -s -o /dev/null -w 'status=%{http_code}\n' -H 'Host: example.test' --data-binary @- http://127.0.0.1:18080/hdr/x

2KB は status=413、500B は status=200 でした。413 のときは、エラーログに次の行が出ます。

Plaintext
client intended to send too large body: 2048 bytes, client: 172.18.0.1, server: example.test, request: "POST /hdr/x HTTP/1.1", host: "example.test"

ファイルのアップロードが急に失敗するようになったら、このメッセージを探してください。送られた大きさがバイトで書かれているので、上限をどこまで広げればよいかの目安にもなります。

curl とログで確かめる

設定を変えたら、ブラウザで開く前に curl とログで確かめると、どこで止まっているかが分かります。

curl で Host を付けて送る

DNS をまだ向けていないときや、手元で試すときは、-H 'Host: ...' でドメインを指定して送ります。

ShellScript
curl -H 'Host: example.test' http://127.0.0.1:18080/hdr/x
curl -s -o /dev/null -w 'status=%{http_code}\n' -H 'Host: example.test' http://127.0.0.1:18080/admin/

1行目は返事の中身を、2行目はステータスコードだけを表示します。2行目の結果は status=403 でした。

アクセスログに転送先と応答を出す

nginx のアクセスログに、転送先とアプリの返事を足しておくと、nginx が自分で返したのか、アプリが返したのかが分かります。実験では次の log_format にしました。

Nginx
log_format main '$remote_addr "$request" $status upstream=$upstream_addr upstream_status=$upstream_status rt=$request_time';
access_log /dev/stdout main;

この記事で試したリクエストのログの一部です。

Plaintext
172.18.0.1 "GET /hdr/x HTTP/1.1" 200 upstream=172.18.0.2:8000 upstream_status=200 rt=0.001
172.18.0.1 "GET /admin/ HTTP/1.1" 403 upstream=- upstream_status=- rt=0.000
172.18.0.1 "POST /hdr/x HTTP/1.1" 413 upstream=- upstream_status=- rt=0.001
172.18.0.1 "GET /local/x HTTP/1.1" 502 upstream=127.0.0.1:8000 upstream_status=502 rt=0.000
ログ読み方
upstream=172.18.0.2:8000アプリのコンテナへ転送し、アプリが 200 を返した
403 upstream=-nginx がその場で返した(/admin/ を閉じた)
413 upstream=-本文が大きすぎて、nginx がアプリへ渡さずに断った
502 upstream=127.0.0.1:8000転送しようとしたが、宛先につながらなかった
ログの読み方

upstream=- なら、アプリのログを見ても何も出ていません。調べる場所を間違えずに済みます。

僕の VPS では、同じ項目を JSON で1行ずつ出しています。転送先の状態($upstream_status)と応答時間($upstream_response_time)も入れています。

ログの中から 502 や 413 の行だけを探すときは、grep が便利です。

よくある質問

proxy_pass の最後の / は、付けるのと付けないのとどちらがいいですか?

アプリがどのパスで待っているかで決めます。/api/ を付けたまま受けるアプリなら付けず、/api/ を外して受けるアプリなら付けます。

付けるときは、location の最後にも / を付けてそろえてください。片方だけだと、// や想定外のパスが届きます。

proxy_set_header を書いたのに、アプリに届きません。

その location に、別の proxy_set_header が1行でもないか見てください。1行でもあると、外側に書いた proxy_set_header は引き継がれません。

設定を変えたあとに reload しているかも確かめます。

Docker で動かしている nginx から、ホストで動いているアプリへ転送するには?

コンテナの中の 127.0.0.1 は nginx のコンテナ自身なので、そのままでは届きません。実験でも 502 でした。

アプリもコンテナにして同じ Compose のネットワークに置き、サービス名で転送するのがいちばん分かりやすいです。

まとめ:末尾の / とヘッダー4行を押さえる

  • proxy_pass にパスがなければ、リクエストのパスがそのまま届く
  • proxy_pass に / などのパスがあれば、location に一致した部分が置き換わる
  • location と proxy_pass の最後の / はそろえる。location /api だと //users/1 や /apix まで拾う
  • Host を足さないと、アプリには app:8000 のような内部の名前が届く
  • X-Forwarded-For の先頭は利用者が書き換えられる。いちばん外側の nginx なら $remote_addr で置き換えられる(一般論)
  • /admin/ は return 403 で閉じ、client_max_body_size を超えた本文は 413 で断る
  • Docker の中で 127.0.0.1 へ転送すると、nginx 自身を指して 502 になる

設定を変えたら、curl で送り、アクセスログの upstream を見て、アプリまで届いているかを確かめてください。

Docker の nginx 1つで、複数のサイトを HTTPS で公開する構成は、こちらで紹介しています。

VPS を借りてから Web サイトを公開し、Docker で運用するまでの流れは、こちらにまとめています。

よかったらシェアしてね!
  • URLをコピーしました!
  • URLをコピーしました!

この記事を書いた人

普段は主にPython開発をしています。
最近はAI駆動開発にも関わっています。