反向代理基础

这一课你将能做到

1. 正确写出两种 proxy_pass（末尾有/无 /），并推演 /api/tracks 到达 Spring Boot 后的路径
2. 配齐 Host、X-Real-IP、X-Forwarded-For、X-Forwarded-Proto，说明 Spring / Next 为何需要它们
3. 为经 Nginx 的 Next 开发态补上 Upgrade / Connection，避免 WebSocket/HMR 失败

为什么要学

反向代理是本 track 的核心技能：CodeRoadMap 所有公网 /api 与页面流量都经 proxy_pass 进入上游。
写错尾斜杠 → 404；丢了转发头 → 后端以为自己是 http、限流记错 IP、redirect 跳错域；缺 Upgrade → 本地经 Nginx 调试时热更新挂掉。
本课把「转发语义 + 必备头 + 超时/体大小」一次钉牢，下一课再组装完整双 upstream。

先建立图像

客户端请求
  Host: www.coderoadmap.cn
  URL:  /api/tracks
        │
        ▼
location /api/  +  proxy_pass http://backend/;
        │  去掉 /api/ 前缀
        ▼
上游收到
  URL:  /tracks
  额外头: X-Forwarded-Proto=https, X-Real-IP=客户端, …

写法	行为直觉	本站用法
proxy_pass http://upstream/;（有尾 /）	常与 location 前缀替换相关	/api/ → 剥前缀进 Spring
proxy_pass http://upstream;（无尾 /）	更常保留原 URI	/ → 原样进 Next

人话：proxy_pass 的尾斜杠像「是否撕掉信封上的部门代号再投递」。撕错了，收件人桌牌对不上。

跟着做

步骤 1：读官方 proxy_pass 说明

打开 ngx_http_proxy_module — proxy_pass，关注：当 proxy_pass 带 URI 时，location 匹配部分会被替换。
用中文记：「带路径的 proxy_pass 会改写 URI；只写 scheme+host（可含 upstream 名）时通常保留原请求 URI。」

步骤 2：对照生产两段

打开 deploy/nginx/prod.conf.example：

location /api/ {
    # 尾 / ：/api/tracks → 上游 /tracks（Spring 映射不含 /api 前缀）
    proxy_pass http://coderoadmap_backend/;
    proxy_http_version 1.1;
    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 / {
    # 无尾 / ：/tracks/foo → 上游 /tracks/foo
    proxy_pass http://coderoadmap_platform;
    proxy_http_version 1.1;
    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;
    # Next 开发 HMR / WebSocket 需要
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}