我把前端从 /ais 改到 /kb 后，连续踩了 7 个 Nginx 坑（含 405/413/502/404 终极解法）

作者：袖梨 2026-09-01

大家好我是舒一笑不秃头，喜欢写作和分享，更多精彩内容～

一句话总结：前端路径前缀、网关转发前缀、后端真实路径 这三件事如果没彻底对齐，线上一定会“随机炸”。

1. 背景：看起来只是改个前缀，实际上是链路重构

项目原来跑在 /ais，现在要挂到网关 :8000/kb/。

同时后端有两套服务：

主后端：188.104.159.164:10003
预览服务：188.104.159.164:8012

前端请求统一走 /aiskb/...，再由 Nginx 分发到不同 upstream。

2. 我遇到的典型故障（你大概率也会遇到）

502 Connection refused
原因：容器里转发到了 127.0.0.1:10003，但后端不在容器内。
405 Not Allowed
原因：请求没命中 API location，掉进了静态 location /kb/，POST 被静态资源处理逻辑拒绝。
413 Request Entity Too Large
原因：Nginx 默认 body 太小（常见 1m）。
前端登录页 404
原因：后端返回 Location: /login，但前端实际部署在 /kb/login。
/kb/license/validate 被重写成 /license/validate
原因：rewrite 写猛了，把后端真实需要的 /kb 也干掉了。
预览接口走错后端
原因：/kl/api/saas/element/preview/* 应该去 8012，却被通用规则发到 10003。
以为是 Host 丢失导致 405
结论：不是。405 多数是路由命中错误，不是 Host 头问题。

3. 核心原则（非常关键）

前端前缀、网关前缀、后端真实路径，必须逐条列清楚。
精确路由必须放在通用路由之前（^~ + 顺序）。
只改该改的前缀，不要全局无脑 rewrite。
登录跳转要做 proxy_redirect 或兜底重定向兼容。
上传场景必须显式设置 client_max_body_size。

4. 可直接落地的 Nginx 配置（我线上用的结构）

upstream ais_backend {    server 188.104.159.164:10003;}upstream ais_preview {    server 188.104.159.164:8012;}server {    listen 8000;    server_name _;    root /usr/share/nginx/html;    index index.html index.htm;    client_max_body_size 2g;    location = / { return 301 /kb/; }    location = /kb { return 301 /kb/; }    # 预览服务：必须放在通用 /aiskb/ 之前    location ^~ /aiskb/kl/api/saas/element/preview/ {        rewrite ^/aiskb/(.*)$ /$1 break;        proxy_pass http://ais_preview;        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;    }    # 通用 API    location ^~ /aiskb/ {        rewrite ^/aiskb/(.*)$ /$1 break;        proxy_pass http://ais_backend;        proxy_redirect ~^/(login|register|sso|home)(/.*)?$ /kb/$1$2;        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;    }    # 兼容后端真实需要 /kb 的接口（不要 rewrite 掉 /kb）    location ^~ /kb/license/ {        proxy_pass http://ais_backend;        proxy_redirect ~^/(login|register|sso|home)(/.*)?$ /kb/$1$2;        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 ^~ /kb/ais/ {        rewrite ^/kb/(ais/.*)$ /$1 break;        proxy_pass http://ais_backend;        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 ^~ /ais/ {        proxy_pass http://ais_backend;        proxy_redirect ~^/(login|register|sso|home)(/.*)?$ /kb/$1$2;        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;    }    # 后端返回 /login 时的前端兼容    location ~ ^/(login|register|sso|home)(/.*)?$ {        return 302 /kb$uri$is_args$args;    }    # 前端 SPA    location /kb/ {        rewrite ^/kb/(.*)$ /$1 break;        try_files $uri $uri/ /index.html;    }}