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 访问。下一章讲域名:记录怎么加、为什么改了不生效,以及中国大陆服务器那道绕不过去的备案门槛。