Mastering Nginx proxy_pass: When to Use / vs No Slash and Load‑Balancing Tips

Nginx is one of the most widely used reverse‑proxy tools, and the proxy_pass directive is essential for interface proxying and load balancing, but the parameter after proxy_pass is subtle—adding or omitting a trailing slash can lead to very different results.

Examples of proxy_pass with and without a trailing slash

Assume the upstream URL http://192.168.1.8/proxy/test.html is accessed. Four configurations illustrate the effect:

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

Resulting URL:

http://127.0.0.1/test.html

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

Resulting URL:

http://127.0.0.1/proxy/test.html

location /proxy/ {
    proxy_pass http://127.0.0.1/aaa/;
}

Resulting URL:

http://127.0.0.1/aaa/test.html

location /proxy/ {
    proxy_pass http://127.0.0.1/aaa;
}

Resulting URL: http://127.0.0.1/aaatest.html Summary: if the URI in proxy_pass ends with /, it is treated as an absolute root path; without /, it is a relative path that appends the matched location part.

Does not affect the URL shown in the browser address bar.

Sets the protocol and address of the upstream server.

Protocol can be http or https.

Address can be a domain name or IP.

Two modules that provide proxy_pass

ngx_http_proxy_module (used in location, if inside location, limit_except)

syntax: proxy_pass URL;

Sets the upstream server's protocol, address, and an optional URI. The protocol may be http or https; the address can be a domain, IP, port, or a Unix‑domain socket path.

ngx_stream_proxy_module (used in server block)

syntax: proxy_pass address;

Sets only the upstream server's address (domain, IP, port, or Unix‑domain socket). This module is suitable for TCP/UDP port forwarding.

Both modules perform backend proxying, but the stream module works at the transport layer and cannot include a URI part when the location is a regular expression.

Specific usage of proxy_pass

ngx_stream_proxy_module examples:

server {
    listen 127.0.0.1:12345;
    proxy_pass 127.0.0.1:8080;
}

server {
    listen 12345;
    proxy_connect_timeout 1s;
    proxy_timeout 1m;
    proxy_pass example.com:12345;
}

server {
    listen 53 udp;
    proxy_responses 1;
    proxy_timeout 20s;
    proxy_pass dns.example.com:53;
}

server {
    listen [::1]:12345;
    proxy_pass unix:/tmp/stream.socket;
}

ngx_http_proxy_module examples (including rewrites and conditional if statements):

server {
    listen 80;
    server_name www.test.com;

    # Normal proxy, no URL rewrite
    location /some/path/ {
        proxy_pass http://127.0.0.1;
    }

    # Proxy with trailing slash in backend URL
    location /testb {
        proxy_pass http://www.other.com:8801/;
    }

    # Conditional proxy based on country code
    location /google {
        if ($geoip_country_code ~ (RU|CN)) {
            proxy_pass http://www.google.hk;
        }
    }

    # Unix‑socket proxy with limit_except
    location /yongfu/ {
        proxy_pass http://unix:/tmp/backend.socket:/uri/;;
        limit_except PUT DELETE {
            proxy_pass http://127.0.0.1:9080;
        }
    }
}

Analyzing request_uri after proxy_pass

Various scenarios (A–G) show how the presence of a trailing slash, regular‑expression locations, and rewrites affect the backend request_uri. Key points:

In regular‑expression locations, proxy_pass must not contain a URI part.

Appending $request_uri or other variables can rewrite the backend request path.

When a rewrite with break is used, the URI part of proxy_pass is ignored.

Load‑balancing practice

To enable load balancing, define an upstream pool and use proxy_pass to forward requests to the pool.

# ngx_http_upstream_module syntax
upstream backend_pool {
    server 172.16.1.8:80;
    server 172.16.1.7:80;
}

server {
    server_name game1.test.com;
    listen 80;
    location / {
        proxy_pass http://backend_pool;
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_connect_timeout 10s;
        proxy_read_timeout 10s;
        proxy_send_timeout 10s;
        proxy_buffering on;
        proxy_buffer_size 8k;
        proxy_buffers 8 8k;
        proxy_next_upstream http_404 http_500 http_502 http_503 http_504 http_403 http_429;
    }
}

Alternatively, place common proxy parameters in a separate file and include it, which simplifies maintenance.

# proxy_params file example
proxy_set_header Host $http_host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_connect_timeout 10s;
proxy_read_timeout 10s;
proxy_send_timeout 10s;
proxy_buffering on;
proxy_buffer_size 8k;
proxy_buffers 8 8k;
proxy_next_upstream http_404 http_500 http_502 http_503 http_504 http_403 http_429;

Then the server block becomes:

upstream game {
    server 172.16.1.8:80;
    server 172.16.1.7:80;
}

server {
    server_name game1.test.com;
    listen 80;
    location / {
        proxy_pass http://game;
        include proxy_params;
    }
}

This approach ensures a single source of truth for proxy settings.

Original source: https://www.cnblogs.com/xiongzaiqiren/p/16970515.html