SSD Nodes Learn Hosting plans →
指南 Matt Connor作者: Matt Connor

nginx 反向代理配置详解:proxy_pass 与请求头

逐行配置 nginx 反向代理 server 块,说明 proxy_pass、4 个关键请求头、WebSocket、路径末尾斜杠、上传处理,以及 Ubuntu 24.04 的配置位置。

nginx 反向代理配置的作用

nginx 反向代理接收来自 80 和 443 端口的请求,将每个请求转发给已经监听本地端口的应用,然后把应用的响应返回给浏览器。配置由一个 server 块组成,内容很短。大部分难点集中在其中五六行配置上。这些配置用于告诉应用真实客户端的身份,以及客户端使用的协议。

以下内容从空配置开始,基于 Ubuntu 24.04 和发行版提供的 nginx 软件包完成。起点是一个已经在 127.0.0.1:3000 上提供响应的应用。如果您还没有决定使用哪种代理,请先阅读 nginx 与 Caddy 和 Traefik 的对比。下面将逐行说明 nginx 配置的写法。

请在您自己的服务器上运行这些配置。重新加载前,先使用 sudo nginx -t 测试每次修改,并查看其输出。

Ubuntu 上 nginx 保存配置的位置

sudo apt update
sudo apt install -y nginx
ls -l /etc/nginx/sites-enabled/

主配置文件是 /etc/nginx/nginx.conf。它在 http { } 块中设置全局选项,然后引入两个目录:/etc/nginx/conf.d/*.conf 和 /etc/nginx/sites-enabled/*。在 Ubuntu 和 Debian 上,每个站点都应在 /etc/nginx/sites-available/ 中创建一个文件,并通过创建指向 /etc/nginx/sites-enabled/ 的符号链接来启用该站点。删除符号链接即可禁用站点,同时保留配置文件。

后文使用的两个指令只能在 http 上下文中生效,不能放在 server 块中:map 和 upstream。请将它们放在 /etc/nginx/conf.d/ 下的独立文件中,因为该目录会在 http 级别被引入。

软件包会附带一个已启用的站点,名为 default。它标记为 default_server,表示当请求的 Host 请求头与配置中的任何 server_name 都不匹配时,该站点会响应请求。在它保持启用的情况下,未匹配到您站点的请求会落到该站点,而不是您的应用。确认自有站点正常工作后,请删除该符号链接。

sudo rm /etc/nginx/sites-enabled/default
sudo nginx -t
sudo systemctl reload nginx

代理单个应用的最小 server 块

server {
    listen 80;
    listen [::]:80;
    server_name app.example.com;

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

将其保存为 /etc/nginx/sites-available/app.example.com,然后启用并加载它。

sudo ln -s /etc/nginx/sites-available/app.example.com /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
curl -sI -H 'Host: app.example.com' http://127.0.0.1/

listen 80; 绑定 IPv4,listen [::]:80; 绑定 IPv6。删除第二行后,所有连接到服务器的 IPv6 连接都会被拒绝。双栈浏览器的 DNS(域名系统)查询通常会返回 AAAA 记录,然后回退到 IPv4,因此问题可能被掩盖。但仅支持 IPv6 的访问者,或只尝试收到的第一个地址的客户端,会看到连接被拒绝,而所有使用 IPv4 的用户看到的站点都能正常工作。你收到的错误报告会是“我这里可以正常访问”。

server_name 会与浏览器发送的 Host 标头进行匹配。可以列出多个名称,并用空格分隔。如果没有任何块匹配,nginx 会使用 default_server 的块,这就是必须移除预置站点的原因。

location / 会对请求路径执行前缀匹配,/ 会匹配所有路径。proxy_pass 是 nginx 建立连接的地址。让应用保持绑定到 127.0.0.1,这样进入应用的唯一途径就是 nginx。如果应用运行在容器中,请将其发布为 127.0.0.1:3000:3000,不要发布为 3000:3000,因为 Docker 会自行写入规则,并绕过 ufw 直接发布端口,所以无论 ufw 如何配置,裸露的已发布端口都可从互联网访问。Docker 将其 DOCKER-USER 链定义为过滤此类流量的位置,但绑定到 127.0.0.1 是更简单的修复方法。

curl 行会让服务器自身发送正确的 Host 标头,因此在 DNS 指向任何位置之前,你就可以测试该块。

仅配置以下内容时,nginx 会向上游发送什么

单独配置 proxy_pass 会隐藏应用需要知道的 4 项信息。

Ubuntu 24.04 随附的 nginx 1.24.0 软件包默认使用 HTTP/1.0 与后端通信,并发送 Connection: close,因此每个请求都会新建一个上游连接,也无法进行协议升级。nginx 1.29.7 于 2026 年 3 月发布,修改了这些默认值:从该版本开始,nginx 使用 HTTP/1.1 与上游通信,不发送 Connection 标头,并复用连接池中的连接,而不是每个请求都新建连接。即使如此,WebSocket 升级仍需要下文所示的标头。

Host 标头会被改写为 proxy_pass 中的值,即 127.0.0.1:3000。如果应用根据 Host 生成绝对链接,生成的链接就无法从服务器外部打开。

到达应用的连接来自 nginx,因此应用看到的客户端地址是 127.0.0.1。此后,应用中的每条日志和每个速率限制都会记录代理地址,而不是访问者地址。

应用无法判断浏览器使用了 HTTPS,因为它收到的连接是在回环地址上的普通 HTTP 连接。

4 行配置即可修复这些问题。

需要设置的 4 个请求头,以及每个请求头能让后端看到什么

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

Host 携带访问者输入的名称。$host 是请求中的名称,已移除端口并转换为小写。设置它后,应用才能生成正确的绝对 URL,例如登录后的重定向地址,或密码重置邮件中的链接。如果省略它,应用会将 127.0.0.1:3000 视为自己的名称。nginx 的默认 proxy_redirect 会改写指向 proxy_pass 地址的 Location 或 Refresh 请求头,因此登录后的普通重定向通常仍会指向正确位置。但应用写入页面和邮件的绝对 URL(例如密码重置链接)会指向 127.0.0.1:3000,访问者的浏览器无法打开该地址。如果应用还需要端口信息(例如通过 8080 提供服务),请使用 $http_host;它会保留客户端发送的完整请求头值。

X-Real-IP 只携带一个值:$remote_addr,即 nginx 接受连接时对端的地址。应用可使用它记录自己的访问日志,并执行自己的速率限制。

X-Forwarded-For 携带一个列表。$proxy_add_x_forwarded_for 会将 $remote_addr 追加到客户端已放入该请求头的内容之后,因此值以逗号分隔,nginx 添加的条目位于最后。这个细节决定了该请求头是否可信:客户端可以发送任意 X-Forwarded-For,因此读取第一项的应用可能被告知任意地址。如果 nginx 是边缘服务器,请改为写入 $remote_addr,丢弃客户端发送的版本。如果前面还有 CDN 或其他代理,请使用 set_real_ip_from 和 realip 模块中的 real_ip_header,这样 $remote_addr 本身才会变成真实的客户端地址。

X-Forwarded-Proto 携带 http 或 https。框架会读取它,以决定是否将 Cookie 标记为 Secure,以及是否强制重定向到 HTTPS。在 TLS 站点上省略它时,配置为强制使用 HTTPS 的应用会看到 http,并响应一个指向 HTTPS 地址的重定向。下一次请求仍经由 nginx 到达,应用依然看到 http,于是再次重定向。最终浏览器会放弃,并显示 ERR_TOO_MANY_REDIRECTS。

在每个 location 中重复这 4 行,会导致它们逐渐不一致。请将它们放入一个文件,然后 include 该文件。

# /etc/nginx/snippets/proxy-headers.conf
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 / {
    include snippets/proxy-headers.conf;
    proxy_pass http://127.0.0.1:3000;
}

这里的继承机制有一个陷阱。只有在 location 未定义任何自身指令时,它才会从所属 server 块继承 proxy_set_header 指令。在 location 中添加一个 proxy_set_header 后,server 级别定义的所有请求头都会从该 location 中清除。因此,应将它们全部放在同一层级,或在每个执行代理转发的 location 中 include 该片段。

为什么我的 WebSocket 应用连接后又断开?

因为默认配置禁止协议升级,而且默认读取超时会在 60 秒后关闭空闲隧道。WebSocket 首先是一个携带 Upgrade: websocket 和 Connection: Upgrade 的 HTTP 请求。这些是逐跳标头,代理应当使用它们,而不是将其转发给上游;此外,在 Ubuntu 24.04 的 nginx 1.24.0 中,上游协议默认为 HTTP/1.0,而 HTTP/1.0 根本不支持升级机制。两项配置都必须手动补回。

map 应放在 http 上下文中,并单独保存到一个文件。

# /etc/nginx/conf.d/websocket.conf
map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

然后配置 location。

location / {
    include snippets/proxy-headers.conf;
    proxy_pass http://127.0.0.1:3000;

    proxy_http_version 1.1;
    proxy_set_header Upgrade    $http_upgrade;
    proxy_set_header Connection $connection_upgrade;

    proxy_read_timeout 3600s;
    proxy_send_timeout 3600s;
}

使用 map 是为了让一个 location 同时处理这两类流量。对于普通请求,$http_upgrade 为空,因此 $connection_upgrade 会变成 close。对于升级请求,它的值为 websocket,因此发送给上游的标头是 Connection: upgrade。硬编码 proxy_set_header Connection "upgrade"; 会导致每个普通页面请求也发送该标头,而某些后端会以 400 响应此类请求。

proxy_http_version 1.1; 是 nginx 1.29.7 及更高版本中的默认值,因此在这些版本中,这一行不会改变任何行为,也不会造成问题。在 1.24.0 软件包中,该配置是必需的。Upgrade 和 Connection 在所有版本中都必需,因为 nginx 不会自行转发这两个标头。

proxy_read_timeout 会导致“页面能加载,但之后不再更新”这类问题。它的默认值为 60 秒,计算的是两次从后端读取数据之间的间隔,而不是连接的生命周期。保持静默 60 秒的 WebSocket 会被 nginx 关闭,浏览器控制台会显示套接字以代码 1006 关闭。每分钟发送心跳次数超过 1 次的应用不会遇到此问题。不发送心跳的应用会在整整 1 分钟后断开。在线编辑器和监控面板最容易出现这一问题,通过 HTTPS 运行的自托管 n8n 实例就是常见示例。

proxy_pass 末尾的斜杠为什么会改变 URL?

规则只有一句话。如果 proxy_pass 以 URI(统一资源标识符)结尾,即使只是一个单独的 /,nginx 也会移除请求路径中与 location 前缀匹配的部分,并将该 URI 放在原位置。如果 proxy_pass 只写到主机和端口,请求路径会原样传递。

location /app/ {
    proxy_pass http://127.0.0.1:3000/;
}

对 /app/status 的请求到达后端时为 /status。

location /app/ {
    proxy_pass http://127.0.0.1:3000;
}

对 /app/status 的请求到达后端时为 /app/status。

具体使用哪种形式取决于应用。带有 base-path 或子目录设置的应用需要第二种形式,并将 /app 配置到该设置中。不识别前缀的应用需要第一种形式。第一种形式的影响会立即出现:应用返回的 HTML 仍包含 /static/main.css 这样的绝对路径,浏览器会从站点根路径请求这些资源,但没有任何 location 匹配,因此页面不会加载样式。浏览器的网络面板会显示这些资源请求返回 404。解决方法是配置应用自身的 base-path,或添加第二个 location /static/,将其指向同一个后端。

正则表达式 location 不能在 proxy_pass 中携带 URI。sudo nginx -t 会拒绝该配置,并说明原因:"proxy_pass" cannot have URI part in location given by regular expression, or inside named location, or inside "if" statement, or inside "limit_except" block。

如果为每个应用分配独立的名称 app.example.com,再从 location / 进行反向代理,这类问题就会消失。只有在无法添加 DNS 记录时,才值得使用子路径。

如何让一个名称后面对应多个后端?

使用 upstream 块。它属于 http 上下文,因此应将其写在同一文件中的 server 块之前,或写入 /etc/nginx/conf.d/。

upstream app_backend {
    least_conn;
    server 127.0.0.1:3000 max_fails=3 fail_timeout=30s;
    server 127.0.0.1:3001 max_fails=3 fail_timeout=30s;
    keepalive 32;
}

然后在 location 中引用它:proxy_pass http://app_backend;。

默认方法是轮询。least_conn 将每个请求发送到当前活动连接数最少的后端,适合请求处理时长不均匀的场景。ip_hash 会将一个客户端地址固定到一个后端。当应用在自身内存中保存会话时,需要使用 ip_hash,因为两个此类后端采用轮询后,用户的请求可能随机落到从未处理过该用户请求的实例上,导致用户被随机登出。更好的做法是将会话迁移到共享存储中。

max_fails=3 fail_timeout=30s 表示在 30 秒内失败三次后,该服务器会被移出 30 秒。当块中的所有服务器都处于此状态时,客户端会收到 502,错误日志会显示 no live upstreams while connecting to upstream。

keepalive 32 会为每个 worker 进程保持最多 32 个与后端的空闲连接,从而使大多数请求无需重新执行 TCP 握手。在 Ubuntu 24.04 的 1.24.0 版本中,该行用于启用缓存。自 nginx 1.29.7 起,缓存默认启用,但文档规定的默认值是 keepalive 32 local;;local 参数用于阻止不同 location 之间共享缓存连接。因此,在 1.29.7 及更高版本中,单独写 keepalive 32; 不只是重复默认设置:省略 local 后,代理到同一上游服务器的任意 location 都可以复用池中的连接,这与默认行为不同。在这些版本中,省略该行,或写入 keepalive 32 local;,即可保持默认设置;只有需要启用这种共享时,才应单独写该指令。local 参数是在 1.29.7 中新增的,因此 1.24.0 软件包不接受该参数。对于 HTTP 后端,nginx 建议的连接池配置是将 proxy_http_version 设置为 1.1(在 nginx 1.29.4 及更高版本中也可以设置为 2),并清除发往上游的 Connection 请求头。nginx 还记录了 HTTP/1.0 持久连接的配置方法:向支持该功能的后端发送 Connection: Keep-Alive;但 nginx 表示不推荐这种方法。从 1.29.7 起,推荐配置的两部分都已是默认设置。在 1.24.0 中,应自行将 proxy_http_version 1.1; 和 proxy_set_header Connection ""; 添加到 location 中,否则 nginx 会继续使用 Connection: close 发送 HTTP/1.0,请求池也永远不会被复用。如果同一 location 还使用 WebSocket map,应将空值从 close 改为空字符串,使普通请求不携带 Connection 请求头,并复用池中的连接。

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      '';
}

upstream 块中的名称会在 nginx 启动时解析。如果后端是容器,并且容器重启后会获得新地址,nginx 会继续使用旧地址,直到重新加载配置。nginx 1.27.3 及更高版本可以通过 resolver 跟踪此类变化而无需重新加载:在 upstream 块中配置 zone,并在每个 server 行中使用 resolve 参数;但 1.24.0 软件包早于该功能。在 Docker 网络中,可以使用内置 resolver 将解析移到请求处理时。

resolver 127.0.0.11 valid=10s;
set $backend http://app:3000;
proxy_pass $backend;

当容器频繁创建和删除,以至于您需要不断编辑 nginx 配置来跟上变化时,使用能够读取容器标签的代理会更合适。在多个 Docker Compose 应用前使用 Traefik 会直接根据容器构建路由。

为什么上传会因 413 Request Entity Too Large 失败?

client_max_body_size默认为 1 megabyte。请求正文较大时,nginx 会拒绝请求并返回 413,错误日志会记录 client intended to send too large body。请在 server 块中提高该值,或在处理上传的 location 中提高。

client_max_body_size 512m;

将 0 设置为可完全关闭检查。即使设置了 512m,nginx 仍会拒绝超过该限制的请求正文。因此,修改后仍出现 413,并不能说明错误来自后端。请先检查处理上传的 location 中实际生效的 client_max_body_size,以及 nginx 的错误日志,再检查应用自身的上传限制。

默认情况下,nginx 会在打开上游连接前读取完整的请求正文,并先将较大的正文写入磁盘上的临时文件。这样可以避免慢速客户端拖累应用,因为后端会以本地网络的全速接收上传内容。对于非常大的上传,可以改用流式传输。

proxy_request_buffering off;

对于 1.24.0 package 中的 HTTP/1.1 分块上传,还要在该 location 中设置 proxy_http_version 1.1;,否则 nginx 仍会缓冲请求正文。之后,后端会在正文到达时接收内容,因此必须能够处理这种传输方式。nginx 开始向上游发送正文后,无法将该请求重试到其他上游。

client_body_timeout默认为 60 seconds,适用于正文两次连续读取之间的间隔,而不是整个上传过程。速度较慢但持续进行的上传可以完成。停止传输的上传会被中断。

响应缓冲,以及会破坏实时输出的设置

proxy_buffering默认启用,通常也正是您需要的设置。nginx 会以应用写入响应的速度读取响应,将其暂存,然后按慢速客户端自身的速度发送。应用工作进程会提前结束,而不必在整个慢速下载期间持续占用。

这会破坏流式响应。服务器发送事件和实时日志输出在缓冲区填满前不会向读取方显示任何内容。仅在该位置关闭缓冲。

proxy_buffering off;

如果您可以控制应用,更好的做法是仅在流式响应中发送 X-Accel-Buffering: no 响应头。nginx 会逐个响应读取该响应头,仅为该响应禁用缓冲,因此普通页面仍可获得缓冲的好处。

当错误日志显示 upstream sent too big header while reading response header from upstream 时,表示响应头无法放入单个缓冲区。proxy_buffer_size 默认为一个内存页,具体为 4 或 8 kilobytes,取决于平台;较长的 cookie 或较大的身份验证响应头会使其溢出。请同时增大这两个值。

proxy_buffer_size 16k;
proxy_buffers 8 16k;

TLS 应配置在哪里?

配置在 nginx 上,位于上述所有内容的前面。TLS(传输层安全)在代理处终止,nginx 到应用的连接通过回环地址保持为普通 HTTP,网络中的其他设备无法读取该连接。应用通过 X-Forwarded-Proto 获知访问者使用了 HTTPS;这是四个标头中的第四个。

不要手动填写证书路径。将 DNS 记录指向服务器,开放防火墙端口,然后让 Certbot 修改同一个 server block:它会添加 listen 443 ssl 行和 ssl_certificate 路径,并将端口 80 重定向到 HTTPS。使用 Certbot 为 nginx 签发 Let's Encrypt 证书介绍证书签发过程和续期计时器。

sudo ufw allow 'Nginx Full'
sudo ufw status

Nginx Full 是 nginx 软件包安装的应用配置,它会同时开放端口 80 和端口 443。即使所有访问者都会被重定向到 HTTPS,端口 80 仍必须保持开放,以便通过 HTTP-01 完成续期验证。

测试配置,然后重新加载

sudo nginx -t
sudo systemctl reload nginx

nginx -t 会解析所有包含的文件,并报告测试是否成功;如果失败,则输出停止位置所在的文件和行号。重新加载前先阅读该输出。配置损坏时重新加载不会生效:nginx 会继续使用之前的配置提供服务,因此网站仍保持在线,但您的修改会静默失效。systemctl restart 的行为不同,而且后果更严重,因为重启会先停止正在运行的服务器;配置错误会导致 nginx 完全无法运行。默认使用重新加载,仅在确实需要时才重启。

sudo tail -f /var/log/nginx/error.log
sudo ss -lntp | grep -E ':(80|443|3000)'

ss 行会显示每个端口由哪个进程占用,因此您可以确认应用确实在 proxy_pass 所指向的位置监听。

实际会遇到的故障

502 Bad Gateway,错误日志中包含 connect() failed (111: Connection refused) while connecting to upstream。 proxy_pass 中的地址没有任何进程监听。应用已停止、绑定到了其他端口,或绑定到了主机无法访问的容器内部地址。

502,错误日志中包含 no live upstreams while connecting to upstream。 upstream 块中的所有服务器当前都已被 max_fails 标记为失败。请修复后端。fail_timeout 到期后,nginx 会重试这些后端。

504 Gateway Time-out,错误日志中包含 upstream timed out (110: Connection timed out) while reading response header from upstream。 后端已接受连接,但在 proxy_read_timeout 秒内没有发送任何内容。对于确实运行缓慢的报表,提高超时值是正确的;对于已卡住的应用,这样做无法解决问题。

每个路径都由应用返回 404。 末尾斜杠规则重写了路径。比较应用日志记录的路径和您请求的路径。

由其他站点响应。 server_name 与 Host 标头不匹配,因此请求落入了 default_server 块。

页面可以加载,但大约 1 分钟后界面冻结。 这是 WebSocket 问题:缺少 Upgrade 处理,或 proxy_read_timeout 仍为 60 秒。

FAQ

为什么添加 proxy_pass 后 nginx 返回 502 Bad Gateway?

nginx 无法连接到 proxy_pass 中的地址。/var/log/nginx/error.log 处的错误日志会说明原因:connect() failed (111: Connection refused) while connecting to upstream 表示该地址没有进程监听,no live upstreams 表示 upstream 块中的每台服务器都已被标记为失败。运行 sudo ss -lntp | grep 3000,查看哪个进程占用了该端口,以及该进程绑定了哪个地址。应用绑定到容器内部地址,或绑定到与配置中不同的端口,都会导致此错误。

为什么我的应用在 nginx 后运行约 1 分钟后断开连接?

该连接是 WebSocket,而 proxy_read_timeout 仍使用默认值 60 秒。此值衡量后端两次读取之间的间隔。空闲 socket 会被 nginx 关闭,浏览器控制台会报告关闭代码 1006。设置 proxy_http_version 1.1(这是 nginx 1.29.7 起的默认值,但 Ubuntu 24.04 提供的 1.24.0 软件包未包含该默认值),通过 map 将 Upgrade 和 Connection 传递到 $http_upgrade,并将 proxy_read_timeout 提高到类似 3600s 的值。如果没有 Upgrade header,升级根本不会发生,因此应用会回退到轮询,或不再显示实时更新。

proxy_pass 末尾的斜杠重要吗?

重要,而且它会改变后端收到的路径。使用 location /app/ 和 proxy_pass http://127.0.0.1:3000/ 时,对 /app/status 的请求到达后端后会变为 /status,因为主机和端口后的任何 URI 都会替换匹配到的 location 前缀。删除最后的斜杠后,同一请求会变为 /app/status。删除前缀通常会破坏应用自身的资源链接。这些链接仍是绝对路径,随后会在站点根路径返回 404。因此,对于设置了 base-path 的应用,最好使用会保留该路径的写法。

为什么我的应用将 127.0.0.1 记录为所有访问者的 IP 地址?

因为应用实际收到的连接确实来自 loopback 地址上的 nginx。访问者的地址只有在你设置了相应 header 后才会传递给应用:单个地址使用 proxy_set_header X-Real-IP $remote_addr;,追加后的地址链使用 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;。随后还必须将应用配置为信任这些 header。请注意,客户端可以自行发送 X-Forwarded-For。因此,当 nginx 是边缘服务器时,应使用 $remote_addr 覆盖该值,而不是追加。

nginx 与应用之间的连接需要使用 TLS 吗?

如果应用运行在同一台服务器上,并绑定到 127.0.0.1,则不需要,因为这部分流量不会离开本机。在 nginx 处终止 TLS,让 proxy_pass 通过 loopback 使用普通 HTTP,并发送 X-Forwarded-Proto $scheme,使应用知道访问者使用了 HTTPS。如果后端位于另一台主机上,且中间网络不受你控制,则该跳转需要单独保护。可以使用到后端的 HTTPS,或在两台机器之间建立私有隧道。

这篇文章对您有帮助吗?