跳到正文
零到全栈 · 卷 7 · 上线与运维

Nginx 反向代理

本合集目录
本章目录

单册说明:本文件是卷 7 的第 4 章,可独立阅读。前置:第 3 章(systemd 常驻)。本章把 80 端口接过来,让静态文件由 Nginx 直接发、/api 转给 8000 上的 uvicorn,并学会用状态码判断"是谁在报错"。

项 内容
所属卷 卷 7 · 上线与运维(第 4 / 8 章)
前置章节 7.3 systemd 让进程常驻;1.6 让世界看到你的文件
本章产出 一份完整的 dudao 站点配置 + 502/504/413 分诊表 + 一次 curl -I 自证
对应代码 /etc/nginx/sites-available/dudao(见 7.4.3)
配图 无(后续统一制图)
读完的判定 curl -I http://你的域名/ 返回 200,curl -I http://你的域名/api/notes 也返回 200,且两者响应头里的 Server 都是 nginx

7.4.1 一句话结论:Nginx 管"连接",应用管"业务",中间那条线画错了就全是 502

本章的典型开场是这样的:systemd 里 active (running),服务器上 curl 127.0.0.1:8000/healthz 返回 200,浏览器打开域名却是:

502 Bad Gateway

Nginx 的错误日志里写着:

2026/11/17 04:02:11 [error] 1203#1203: *18 connect() failed (111: Connection refused)
while connecting to upstream, client: 203.0.113.77, server: dudao.example.com,
request: "GET /api/notes HTTP/1.1", upstream: "http://127.0.0.1:8000/api/notes",
host: "dudao.example.com"

Connection refused 的意思是"我敲了 8000 的门,没人应"。可你明明刚 curl 通过。两种可能:应用在那一刻重启了(7.3 的 RestartSec=3 正好制造这三秒空窗),或者 Nginx 连的地址和你 curl 的不是同一个。

502 永远是 Nginx 发的,不是应用发的。 这句话记住,能省掉一半排查时间。

7.4.2 原理与方法

① 为什么不让 uvicorn 直接对外

uvicorn 也能监听 80 端口,技术上完全可行。不上它,是因为 Nginx 替它扛了五件事:

事项 Nginx uvicorn 自己干
TLS 终止 配几行就行,证书热加载 要改 Python 启动参数,重启才生效
静态文件 sendfile 直接零拷贝,几万 QPS 不吃 CPU 每个 CSS 请求都进 Python,白白占用事件循环
慢客户端 缓冲请求体,应用只处理完整请求 一个慢连接能占住一个 worker
多应用共存 一个 80 端口按路径分给多个 upstream 一个端口只能一个进程
访问日志 统一格式、统一轮转 要自己写中间件

反过来,uvicorn 该干的只有一件:处理 /api 下的业务逻辑。分界线画在"这个请求需不需要读数据库"上。

浏览器
  │ http://dudao.example.com/api/notes
  ▼
Nginx :80
  ├─ /            → /srv/dudao/web 下的静态文件(直接读磁盘,不进 Python)
  └─ /api/        → proxy_pass http://127.0.0.1:8000
                       ▼
                    uvicorn :8000(只监听回环)
                       ▼
                    /srv/dudao/data/dudao.db

② server 块逐行

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

    root /srv/dudao/web;
    index index.html;

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

    location / {
        try_files $uri $uri.html $uri/ =404;
    }
}
指令 作用 写错的后果
listen 80 监听 IPv4 的 80 少了就没人接
listen [::]:80 同时监听 IPv6 有 AAAA 记录时部分用户连不上
server_name 匹配请求头里的 Host 写成 IP 或拼错,会落到默认站点
root URL 路径拼到这个目录 指向家目录会把 .ssh 暴露出去
index 请求目录时找哪个文件 缺了就 403(禁止列目录)
location /api/ 前缀匹配 /api/ 开头的请求 少写结尾斜杠会连 /apix 也匹配
proxy_pass 转给谁 见第 ④ 节,结尾斜杠语义不同
try_files 依次尝试,全不中返回最后的码 见下面

try_files $uri $uri.html $uri/ =404; 里的 $uri.html 是给 Next 静态导出用的:/notes 这个路径在磁盘上对应的是 notes.html,不是 notes/index.html。少了这一段,直接访问 /notes 就是 404,而首页却正常——这种"只有内页打不开"的现象非常好认。

=404 是兜底。不要写成 /index.html:那会让所有不存在的路径都返回首页和 200,搜索引擎会收录一堆垃圾页面,你自己也分不清哪个链接真的坏了。

③ location 的匹配顺序

有四类写法,优先级从高到低:

写法 类型 例子 优先级
location = /healthz 精确匹配 只匹配这一个路径 1(最高)
location ^~ /static/ 前缀且不再正则 命中就停 2
location ~ \.php$ 正则(区分大小写) 按出现顺序 3
location /api/ 普通前缀 最长前缀胜出 4(最低)

本书的配置只用到精确和普通前缀,够用。但要知道一件事:普通前缀是"最长匹配",所以 location /api/ 和 location / 同时存在时,/api/notes 走前者,/notes 走后者。这就是"静态和接口分开"的实现原理。

④ proxy_pass 结尾那个斜杠,语义完全不同

这是 Nginx 最容易出错的一行,没有之一。

写法 客户端请求 后端收到 说明
proxy_pass http://127.0.0.1:8000; /api/notes /api/notes 原样转发,路径不变
proxy_pass http://127.0.0.1:8000/; /api/notes /notes 剥掉 location 前缀
proxy_pass http://127.0.0.1:8000/v1; /api/notes /v1/api/notes 带路径但不带斜杠:整个替换
proxy_pass http://127.0.0.1:8000/v1/; /api/notes /v1/notes 带路径带斜杠:替换前缀

判断规则只有一句:proxy_pass 后面有没有 URI 部分。有,就把 location 匹配到的那段换掉;没有,就原样传。

本书后端路由自带 /api 前缀(@app.get("/api/notes")),所以用不带斜杠的写法。如果你后端路由是 /notes,就要用带斜杠的那种。两边必须对上一个,对不上就是 404——而 404 看起来像"接口不存在",很容易去改后端代码,其实改一行 Nginx 就好。

⑤ 四个必须传的头

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 生成绝对 URL、拼重定向地址、判断 Cookie 域 重定向到 http://127.0.0.1:8000/login,用户直接失联
X-Real-IP 记日志、限流、风控 日志里所有访客都是 127.0.0.1,出事后查不到人
X-Forwarded-For 多层代理时保留链路 过一层 CDN 后真实 IP 丢失
X-Forwarded-Proto 判断当前是不是 HTTPS 应用以为自己是 http,生成 http 链接 → 混合内容;Secure Cookie 不生效 → 登录状态存不住

$host 和 $http_host 的区别值得记一句:$http_host 是客户端发来的原始值(可能带端口、可能被伪造),$host 优先取 server_name,没有端口,更安全。用它。

$proxy_add_x_forwarded_for 的语义是"在已有的 XFF 后面追加 $remote_addr"。所以后端收到的可能是一串 客户端IP, 代理1, 代理2。取哪一段,7.7 会专门讲,现在只要知道它是一串而不是一个值。

⑥ 超时与体积

指令 默认 本书取值 超了会怎样
proxy_connect_timeout 60s 5s 连不上上游 → 502
proxy_send_timeout 60s 30s 发请求给上游太慢 → 504
proxy_read_timeout 60s 30s 等上游响应太久 → 504
client_max_body_size 1m 10m 请求体太大 → 413

三个超时别设成一样长。connect 应该短(本机连本机,5 秒还没连上就是没起),read 要看最慢的接口——「读到」的 /api/notes?q= 关键词统计在数据量大时会慢,30 秒是个合理上限。

client_max_body_size 默认只有 1 MB。用户粘一篇长文进来,或者导入一个 JSON,很容易超。413 的报错页面是 Nginx 自己的,你的应用根本没收到请求,所以后端日志里一片空白——这一点在排障时特别容易误判。

⑦ 校验与生效的顺序

sudo nginx -t          # 只检查语法
sudo systemctl reload nginx

reload 是平滑重载:老 worker 处理完手头的连接再退出,新 worker 用新配置接新连接。不会断用户。

绝不能跳过 -t 直接 restart。配置有语法错误时,restart 会先杀掉正在跑的进程,再发现起不来,于是整站下线。reload 遇到错误配置会保留旧进程继续服务,代价只是新配置没生效。

⑧ 状态码分诊表

这张表是本章最该背下来的东西:

码 谁发的 含义 第一步查什么
200 任一方 成功 —
301 / 308 Nginx 跳转(强制 HTTPS、目录补斜杠) 响应头 Location
403 Nginx 有文件但不许读 namei -l、sudo -u www-data cat
404 任一方 路径不存在 看 access log 里 upstream 有没有收到请求
413 Nginx 请求体超限 client_max_body_size
499 Nginx 客户端主动断开 用户等不及关了页面,通常伴随慢接口
500 应用 代码抛异常 journalctl -u dudao
502 Nginx 连不上上游 systemctl status dudao、ss -lntp | grep 8000
504 Nginx 连上了但超时 应用日志里的慢查询、外部调用

404 是最需要区分的一个。 同样是 404,可能是 Nginx 找不到静态文件(请求没进 Python),也可能是 FastAPI 说"这个路由不存在"(请求进了 Python)。区分方法:看 access log 里的 upstream 字段——为空说明没转发,有值说明转发了。

7.4.3 动手:80 端口配好,静态加接口,用 curl -I 自证

第一步:确认前端产物在位

ls -l /srv/dudao/web | head

预期能看到 index.html、notes.html、_next/ 之类。如果目录是空的,先在本地 npm run build,再把产物传上去:

rsync -av --delete web/ dudao:/tmp/web-build/
ssh dudao 'sudo rsync -a --delete /tmp/web-build/ /srv/dudao/web/ && \
  sudo chown -R dudao:www-data /srv/dudao/web'

走两步是因为 /srv/dudao/web 的属主是 dudao,你的登录用户(ubuntu 之类)直接往里写会被拒绝。先落到 /tmp,再用 sudo 搬进去,属主统一改回来。

--delete 很重要:Next 每次构建会给静态资源生成带哈希的新文件名,旧文件不清掉,web/ 会越积越大,而且可能被旧页面引用到。第一次用先加 --dry-run 看一眼它打算删什么。

第二步:检查权限

Nginx 以 www-data 读文件,所以 web/ 及其所有父目录都要有 x:

namei -l /srv/dudao/web/index.html

预期每一级都是 drwxr-xr-x(/srv、/srv/dudao、/srv/dudao/web),文件是 -rw-r--r--。

第三步:写站点配置

sudo tee /etc/nginx/sites-available/dudao >/dev/null <<'EOF'
server {
    listen 80;
    listen [::]:80;
    server_name dudao.example.com;

    root /srv/dudao/web;
    index index.html;

    access_log /var/log/nginx/dudao.access.log;
    error_log  /var/log/nginx/dudao.error.log;

    client_max_body_size 10m;

    location /api/ {
        proxy_pass http://127.0.0.1:8000;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        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;
        proxy_connect_timeout 5s;
        proxy_send_timeout    30s;
        proxy_read_timeout    30s;
    }

    location / {
        try_files $uri $uri.html $uri/ =404;
    }
}
EOF

两行值得单独解释:

proxy_http_version 1.1 加 proxy_set_header Connection ""; 是一对。Nginx 默认用 HTTP/1.0 连上游且不带 keep-alive,每个请求都新建一次 TCP 连接。改成 1.1 并把 Connection 清空,才能复用连接。对本机回环来说收益不大,但习惯要一开始就对。

access_log 和 error_log 单独指定,是为了让「读到」的日志和系统里其它站点分开。7.7 会在这里加自定义格式。

第四步:启用并校验

sudo ln -sf /etc/nginx/sites-available/dudao /etc/nginx/sites-enabled/dudao
sudo rm -f /etc/nginx/sites-enabled/default
sudo nginx -t

预期:

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

ln -sf 里的 -f 让重复执行不报错(链接已存在时会覆盖)。rm default 是必须的:Ubuntu 的默认站点带 default_server,它会抢走所有没匹配上 server_name 的请求,表现就是"我配了但打开还是欢迎页"。

第五步:重载

sudo systemctl reload nginx
systemctl is-active nginx

第六步:三层自证

按"从里到外"的顺序验,每层只引入一个变量:

# 1. 应用本身
curl -s -o /dev/null -w 'app   %{http_code}\n' http://127.0.0.1:8000/healthz

# 2. Nginx 的静态
curl -s -o /dev/null -w 'static %{http_code}\n' -H 'Host: dudao.example.com' http://127.0.0.1/

# 3. Nginx 的接口
curl -s -o /dev/null -w 'api    %{http_code}\n' -H 'Host: dudao.example.com' http://127.0.0.1/api/notes

预期三行都是 200。

第二条带 -H 'Host: ...' 是关键:直接 curl 127.0.0.1 时,Host 头是 127.0.0.1,匹配不上 server_name dudao.example.com,会落到默认站点。很多人第一次配完 Nginx 在本机 curl 到的是欢迎页,就是这个原因。

再验一次公网:

curl -I http://你的公网IP/

如果返回 200 但内容是默认页,说明 Host 没匹配上——把 server_name 改成 _ 兜底,或者直接用域名访问。

第七步:看响应头,确认是谁在回答

curl -sI -H 'Host: dudao.example.com' http://127.0.0.1/api/notes | head -n 8

预期:

HTTP/1.1 200 OK
Server: nginx/1.24.0 (Ubuntu)
Date: Mon, 17 Nov 2026 04:10:33 GMT
Content-Type: application/json
Content-Length: 482
Connection: keep-alive

Server: nginx 说明这一跳是 Nginx 答的(它转发后把上游的头合并回来了)。如果 Server 是 uvicorn,说明你绕过了 Nginx 直接打到了应用——检查一下是不是把 8000 端口开到了公网。

第八步:读一次日志

sudo tail -n 3 /var/log/nginx/dudao.access.log

形如:

203.0.113.77 - - [17/Nov/2026 04:10:33 +0800] "GET /api/notes HTTP/1.1" 200 482 "-" "curl/8.5.0"
203.0.113.77 - - [17/Nov/2026 04:10:35 +0800] "GET /_next/static/css/8f2a.css HTTP/1.1" 200 12044 "http://dudao.example.com/" "Mozilla/5.0 ..."

第一列是客户端 IP。如果这里全是 127.0.0.1,说明 X-Real-IP 没传到,或者你看的是应用日志而不是 Nginx 日志。 7.7 会把这行扩成八个字段。

7.4.4 三个坑

坑 1:502,connect() failed (111: Connection refused)

症状:

2026/11/17 04:02:11 [error] 1203#1203: *18 connect() failed (111: Connection refused)
while connecting to upstream, client: 203.0.113.77, request: "GET /api/notes HTTP/1.1",
upstream: "http://127.0.0.1:8000/api/notes"

成因:三种,按概率排。

成因 判断方法
应用没起 / 正在重启 systemctl status dudao 看 Active 和 NRestarts
端口不一致 ss -lntp | grep 8000 与配置里的 proxy_pass 对比
应用监听在别的地方 ss -lntp 看到的是 127.0.0.1:8000 还是 [::1]:8000

第三种最容易漏:如果 uvicorn 只监听了 IPv6 回环 [::1]:8000,而 proxy_pass 写的是 127.0.0.1,就会稳定 502,且 systemctl status 一切正常。

修法:先在服务器上手工确认端口有人听:

ss -lntp | grep 8000
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8000/healthz

两条都通,再来看 Nginx。先证明上游活着,再怀疑代理——这个顺序能省掉大量时间。

如果确认是"重启那三秒"造成的,不必改配置。7.3 的 RestartSec=3 注定有这段空窗,7.8 会用"发布前先摘流量"来减少它。

坑 2:proxy_pass 多了个斜杠,接口全 404

症状:/api/notes 返回 404,但响应体是应用自己的 JSON 格式(说明请求确实进了 FastAPI),后端日志里能看到 GET /notes 404。

成因:写成了 proxy_pass http://127.0.0.1:8000/;。结尾的 / 让 Nginx 把 location /api/ 匹配到的 /api/ 剥掉,后端收到的是 /notes,而路由定义是 /api/notes。

修法:二选一,不要混。

后端路由 Nginx 写法
@app.get("/api/notes") proxy_pass http://127.0.0.1:8000;(无斜杠)
@app.get("/notes") proxy_pass http://127.0.0.1:8000/;(有斜杠)

判断依据不是猜,看日志里后端收到什么路径:

sudo journalctl -u dudao -n 20 --no-pager | grep -E 'GET|POST'

uvicorn 默认会打印每条请求,形如 INFO: 127.0.0.1:53210 - "GET /notes HTTP/1.1" 404 Not Found。看到 /notes 而不是 /api/notes,就知道是斜杠的问题。

坑 3:上传长摘录时 413

症状:用户在页面上粘一篇一万字的文章,点保存,浏览器显示:

<html>
<head><title>413 Request Entity Too Large</title></head>
<body>
<center><h1>413 Request Entity Too Large</h1></center>
<hr><center>nginx/1.24.0 (Ubuntu)</center>
</body>
</html>

成因:client_max_body_size 默认 1 MB。这个限制在 Nginx 就生效,请求根本没到 FastAPI,所以后端日志里什么都没有,前端也拿不到你定义的错误 JSON——它收到的是 Nginx 的 HTML 错误页,response.json() 会直接抛解析异常。

修法:

client_max_body_size 10m;

放在 server 块里对所有 location 生效,也可以只放在 location /api/ 里精确控制。改完仍然是 nginx -t → reload。

加完之后,前端也要能处理非 JSON 的错误响应。这是 7.4 之外的事,但值得记一句:只要前面有 Nginx,前端就不能假设所有错误响应都是 JSON。

坑 关键报错 一句话修法
502 connect() failed (111: Connection refused) 先 ss -lntp 证明上游在听,再查端口/地址
接口 404 后端日志收到 /notes 而不是 /api/notes proxy_pass 去掉结尾斜杠
413 Nginx 自己的 HTML 错误页 client_max_body_size 10m;

本章验收

  • nginx -t 通过,systemctl reload nginx 后 is-active 是 active
  • curl -I -H 'Host: 你的域名' http://127.0.0.1/ 返回 200,内容是前端首页
  • curl -I -H 'Host: 你的域名' http://127.0.0.1/api/notes 返回 200,Content-Type 是 application/json
  • /var/log/nginx/dudao.access.log 里有真实客户端 IP,不是 127.0.0.1
  • 能说出 502、504、413 分别是谁发的、第一步查什么
  • 能解释 proxy_pass 结尾有斜杠和没斜杠的区别

自测

Q1:为什么 curl 127.0.0.1 在本机拿到的是 Nginx 默认页,而不是你配的站点?

看答案 因为 HTTP 请求头里的 Host 是 127.0.0.1,匹配不上 server_name dudao.example.com,Nginx 就落到带 default_server 的那个 server 块,通常是 Ubuntu 自带的默认站点。加 -H 'Host: dudao.example.com' 就能命中你的配置。这也解释了为什么用域名访问正常、用 IP 访问却是欢迎页。

Q2:502 和 504 都是 Nginx 报的,它们的根本区别是什么?

看答案 502 是"连不上"——TCP 层就没建立,上游没起、端口不对、监听地址不匹配。504 是"连上了但没等到回应"——TCP 建立了、请求发出去了,上游在 proxy_read_timeout 内没返回。所以 502 去查进程和端口,504 去查应用为什么慢(慢查询、死锁、外部调用没设超时)。两者排查方向完全相反。

Q3:X-Forwarded-Proto 不传会出什么问题?举一个具体的现象。

看答案 应用会认为当前请求是 http。如果代码里根据协议决定是否给 Cookie 加 Secure 属性,那 Secure 就不会加,登录态在 HTTPS 站点上反而不安全;如果代码用 request.url 生成重定向或邮件里的链接,会生成 http:// 的地址,用户点开后被浏览器拦成混合内容或直接降级。典型现象是"登录后跳转回 http 页面,然后又被强制跳 https,来回循环"。

下一步

80 端口通了,但现在只能用 IP 或改 hosts 访问。下一章讲域名:记录怎么加、为什么改了不生效,以及中国大陆服务器那道绕不过去的备案门槛。

→ 卷7-05-域名备案与DNS.md