Master Nginx Load Balancing and Reverse Proxy: Complete Configuration Guide

1. Load Balancing Configuration

As a proxy server, you typically forward requests to an upstream server cluster; load balancing selects a strategy to distribute requests evenly across the upstream servers.

1.1 upstream block

Syntax: upstream name { ... } (http context)

The upstream block defines a cluster of upstream servers for use with proxy_pass :

upstream backend {
    server backend1.example.com;
    server backend2.example.com;
    server backend3.example.com;
}

server {
    location / {
        proxy_pass http://backend;
    }
}

1.2 server

Syntax: server name [parameters]; (upstream context)

The server directive specifies an upstream server name, which can be a domain, IP address, port, or UNIX socket, followed by optional parameters such as:

weight=number – sets the request weight (default 1).

max_fails=number – combined with fail_timeout, marks a server unavailable after a number of failures.

fail_timeout=time – time period after which failures are counted (default 10s).

down – permanently disables the server (used with ip_hash).

backup – marks the server as a backup, used only when all non‑backup servers fail.

upstream backend {
    server backendl.example.com weight=5;
    server 127.0.0.1:8080 max_fails=3 fail_timeout=30s;
    server unix:/tmp/backend3;
}

1.3 ip_hash

Syntax: ip_hash; (upstream context)

Ensures that requests from the same client IP are consistently routed to the same upstream server, useful for caching scenarios. ip_hash cannot be used together with weight.

upstream backend {
    ip_hash;
    server backend1.example.com;
    server backend2.example.com;
    server backend3.example.com down;
    server backend4.example.com;
}

1.4 Variables for logging

If you want to record load‑balancing details in access_log, you can use the following variables: $upstream_addr – address of the upstream server that handled the request. $upstream_cache_status – cache status (MISS, EXPIRED, UPDATING, STALE, HIT). $upstream_status – HTTP status code returned by the upstream. $upstream_response_time – response time of the upstream (ms). $upstream_http_$HEADER – value of a specific upstream HTTP header.

log_format timing '$remote_addr - $remote_user [$time_local] $request' 'upstream_response_time $upstream_response_time' 'msec $msec request_time $request time';
log_format up_head '$remote_addr - $remote_user [$time_local] $request' 'upstream_http_content_type $upstream_http_content_type';

2. Reverse Proxy Basic Configuration

2.1 proxy_pass

Syntax: proxy_pass URL; (location, if contexts)

Forwards the current request to the server specified by URL. Examples:

proxy_pass http://localhost:8000/uri/;
proxy_pass http://unix:/path/to/backend.socket:/uri/;
proxy_pass http://backend;
proxy_pass https://192.168.0.1;
proxy_set header Host $host;

2.2 proxy_method

Syntax: proxy_method method;

Changes the HTTP method used when forwarding a request, e.g.:

proxy_method POST;

2.3 proxy_hide_header

Syntax: proxy_hide_header the_header;

Prevents specified response headers from being forwarded to the client. Example:

proxy_hide_header Cache-Control;
proxy_hide_header MicrosoftofficeWebServer;

2.4 proxy_pass_header

Syntax: proxy_pass_header the_header;

Allows a header that is normally hidden to be passed to the client, e.g.:

proxy_pass_header X-Accel-Redirect;

2.5 proxy_pass_request_body

Syntax: proxy_pass_request_body on|off; (default on)

Controls whether the request body is sent to the upstream server.

2.6 proxy_pass_request_headers

Syntax: proxy_pass_request_headers on|off; (default on)

Controls whether request headers are forwarded.

2.7 proxy_redirect

Syntax: proxy_redirect [default|off|redirect replacement];

Rewrites Location or Refresh headers in upstream redirects. Examples:

proxy_redirect http://localhost:8000/two/ http://frontend/one/;
proxy_redirect http://localhost:8000/two/ /one/;
proxy_redirect off;
proxy_redirect default;

2.8 proxy_next_upstream

Syntax: proxy_next_upstream error timeout ... off; (default error timeout )

Specifies conditions under which Nginx will retry the request with another upstream server, such as connection errors, timeouts, invalid headers, or specific HTTP status codes (500, 502, 503, 504, 404). Setting off disables the retry mechanism.

Nginx also offers many other reverse‑proxy settings, including connection timeouts, temporary file handling, and response caching.

Source: https://www.cnblogs.com/ccblblog/p/17956729 (© original author)