Nginx 反向代理 checklist：从能访问到可维护

站点「能打开」和「代理配得对」不是一回事。HTTPS 证书装上了，还可能出现错误跳转、上传失败、WebSocket 断连、真实 IP 丢失。下面是一份可以反复核对的 checklist，适合个人站同机多项目场景。建议每次改配置或加新域名时从头过一遍，而不是凭记忆「好像设过了」。

1. 监听与证书

• 80 只做跳转或 ACME；业务尽量只在 443 对外
• 证书文件路径正确，ssl_certificate 指向全链（含中间证）
• SAN 覆盖你实际使用的所有域名（裸域与 www 都要）
• nginx -t 后再 reload；语法错不要硬 reload

跳转建议保留原 Host：

return 301 https://$host$request_uri;

除非你明确要做域名规范化（例如全部跳到 www），否则不要写死单一域名，避免用户从另一个合法域名进来被改 Host。证书过期监控最好自动化；个人站最尴尬的事故之一，就是证书到期后才在社交分享里被朋友提醒。

只装叶子证书、漏了中间证书时，某些客户端能开、某些报链不完整。用 SSL 检查工具或 openssl s_client -connect host:443 -servername host 看返回链，比只看浏览器「偶尔正常」靠谱。

2. upstream 绑定本机回环

proxy_pass http://127.0.0.1:13000;

不要指向 0.0.0.0 上误开放的端口，也不要让容器直接映射公网 80。应用端口只给本机 Nginx 用。若 upstream 挂了，Nginx 应返回 502，这时先 curl -I 127.0.0.1:端口 区分「网关坏了」还是「应用坏了」。

多个站点就写多个 server 块，凭 server_name 分流。默认 server 要有意识地指定，避免「未知 Host 落到了错误站点」——有人用 IP 访问时尤其容易暴露这一点。

3. 头字段

必备：

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;

应用若依赖客户端 IP 做限流或日志，缺前两个头会让你以为全世界都从 127.0.0.1 来。缺 X-Forwarded-Proto 时常出现错误绝对 URL 或重定向环。前端框架若根据环境变量生成绝对链接，还要确保构建参数与反代协议一致，否则会出现「Nginx 明明是 HTTPS，页面资源仍指向 http」。

4. 路径与多 location

常见拆分：

• / → 前端
• /api/ → 后端
• /uploads/ → 静态上传目录或后端静态服务

注意尾部斜杠与 proxy_pass 的拼接规则：多一个或少一个 /，路径就会错一位。改完用真实 URL 测，不要只测首页。API 404 和前端 404 看起来都像「页面没有」，要先看响应头是 Next 还是 Gin，避免改错服务。

若曾使用 basePath（例如 /blog），去掉它时要同步清理前端构建与所有内部链接。残留 basePath 会让静态资源 404，表现为「样式全没了但 HTML 还在」。

5. 上传体大小

client_max_body_size 20m;

按业务调整。只改应用限制、不改 Nginx，是线上上传失败的经典原因。也可以按 location 精细化：只有上传接口放大，其余保持较小，降低被滥用上传打满磁盘的风险。

6. 超时与缓冲

大响应、慢接口可适当调 proxy_read_timeout。SSE / 长连接要关闭或不正确设置缓冲。问题表现为「接口偶发切断」时，先对比直接 curl 本机端口与经 Nginx 的差异：直连正常、经代理失败，问题就缩到网关层。

静态资源可以在 Nginx 层设缓存头；动态 API 则避免被中间层缓存成脏数据。个人站有时会在前端 CDN 或浏览器强缓存上踩坑，改完接口却看不到新数据——先查缓存再查逻辑。

7. 日志与排障顺序

建议顺序：

1. 浏览器 Network：状态码、最终 URL、是否混合内容
2. 宿主机 Nginx access/error
3. 直接请求 127.0.0.1:端口 是否正常
4. 容器日志

502 多半是上游没起来或端口绑错；504 是上游太慢或超时过短；413 是体太大；301/302 循环看 Proto 与应用强制 HTTPS 逻辑。把这个顺序印在脑子里，比抓住一个错误状态码空想快得多。

小结

Nginx 配置的目标不是「抄一段能跑的 server 块」，而是形成可重复检查的习惯：证书覆盖面、回环 upstream、头字段、路径拼接、上传限制、超时。每次加新站点就把这份 checklist 过一遍，故障会从玄学变成定位题。配置可以简单，流程不要随便。