一次 413 排查实录：改了 nginx 配置为什么没生效？

2.1 一次上传请求在 K8s 里要经过几层#

1
浏览器
2
  │  ①DNS / 域名
3
  ▼
4
APISIX 网关（API 网关，OpenResty/nginx + Lua）
5
  │  ②按路由转发
6
  ▼
7
平台网关 nginx（compute-maas-nginx，一个 Pod 代理多个前端 + 多个后端网关）
8
  │  ③按 location 前缀转发
9
  ├──► /admin/**          → compute-maas-admin-frontend:8000   （前端静态服务 nginx）
10
  ├──► /console/**        → compute-maas-console-frontend:8000 （另一个前端）
11
  ├──► /server-gateway/** → dispatch-server-gateway-svc:8001   （后端网关）
12
  └──► /client-gateway/** → dispatch-client-gateway-svc:8002   （后端网关）
13
                                    │
14
                                    ▼
15
                              后端微服务（Spring）

关键认知：链路上有多个 nginx，每一个都有自己的 client_max_body_size。 只要其中任何一层是默认 1m，1.7M 的请求就会在那里被拒绝。 “我改了 nginx 配置”必须回答一个问题：我改的，是不是真正在链路上生效的那个 nginx？

2.2 每一层可能出现的大小限制#

client_max_body_size 是 nginx 的内置固定指令（属于 ngx_http_core_module）：

• 名称固定，不能改名，也不支持变量（不能做成运行时可变）
• 值可以写字节数，也可以带单位 k/K、m/M、g/G（大小写都认）
• 写在 server 块里，该 server 下所有 location 都继承；写在 http 里全局生效

2.3 涉及的 K8s 概念（对照本次排查）#

2.4 为什么”改了仓库里的配置却不生效”#

这是本次最容易误判的一点，链条如下：

1. 项目 Dockerfile 把仓库的 nginx.conf 拷到镜像的 /etc/nginx/conf.d/default.conf
2. 官方 nginx 镜像的 /etc/nginx/nginx.conf 里本来有 include /etc/nginx/conf.d/*.conf;，所以 conf.d 会被加载
3. 但线上那个 Pod 的 /etc/nginx/nginx.conf 是被整份替换的（来自 ConfigMap 挂载），内容里是这台网关自己的 upstream 列表
4. 而这份被替换的 nginx.conf 没有 include /etc/nginx/conf.d/*.conf;
5. 于是 conf.d/default.conf（也就是你改的那份）从头到尾没有被加载——它是一份”死配置”

验证手段：nginx -T 会把它实际加载的每一份配置文件都打印出来，并带 # configuration file <路径>: 头。如果输出里只有 /etc/nginx/nginx.conf，就说明 conf.d 没被 include。

1
nginx -T 2>&1 | grep -n -E "client_max_body_size|server_name|include|# configuration file"

2.5 怎么判断”413 到底是谁发的”#

排查时不要靠猜，有四个可观测的线索：

线索一：响应头 Server

⚠️ 坑点：APISIX 会改写所有响应的 Server 头（包括来自上游的响应），所以看到 Server: APISIX 不等于 413 是 APISIX 发的。

线索二：错误页的签名

• OpenResty（APISIX 的底座）生成的默认错误页签名是 <hr><center>openresty</center>
• 普通 nginx 生成的是 <hr><center>nginx</center>

本次页面签名是 nginx → 说明 413 是一个普通 nginx 发出的，APISIX 只是转发并盖了自己的 Server 头。

线索三：nginx 错误日志的字段

1
2026/09/23 08:33:24 [error] 32#32: *9 client intended to send too large body: 1834823 bytes,
2
client: 10.244.0.1,
3
server: _,
4
request: "POST /client-gateway/client/common/upload HTTP/1.1",
5
host: "cm.wuxi.dev.ljyun.cn"

• client intended to send too large body: N bytes → 请求体超过本机 client_max_body_size 的直接证据
• client: → 上一跳的地址。如果是 10.244.x.x（集群 Pod 网段），说明这台 nginx 前面还有一跳，它不是最外层入口
• server: → 处理该请求的 server 标识。本次是 _，与该 nginx 配置里的 server_name _; 对应（兜底 server）
• host: → 请求头里的域名

线索四：容器里的实际配置

1
nginx -T                                   # 实际加载了哪些文件、值是多少
2
cat /proc/mounts | grep -i nginx           # 这些文件是不是挂载进来的
3
ls -l /etc/nginx/ /etc/nginx/conf.d/       # 文件时间戳、是否软链
4
hostname                                   # 当前 Pod 名

如果多个文件（如 nginx.conf、config.js、conf.d/）的时间戳完全一致，基本可以判定它们是 ConfigMap 挂载进来的。

Step 1：确认失败的是接口请求，不是后端业务报错#

F12 → Network → 找到失败请求：

• 状态码 413，响应体是 HTML（nginx 默认错误页），不是业务 JSON
• 结论：不是后端 Spring 的 multipart 报错，而是某个 nginx 拦的

Step 2：先找 Ingress，结果”配了也没用”#

在 Rancher 里找到入口 Ingress，注解里已经有：

1
metadata:
2
  annotations:
3
    nginx.ingress.kubernetes.io/proxy-body-size: 200M
4
    nginx.ingress.kubernetes.io/proxy-buffering: 'off'
5
    nginx.ingress.kubernetes.io/use-regex: 'true'
6
spec:
7
  ingressClassName: nginx
8
  rules:
9
    - host: maas-test-3.portal.ljyun.cn
10
      http:
11
        paths:
12
          - path: /
13
            pathType: Prefix
14
            backend:
15
              service:
16
                name: compute-maas-svc
17
                port:
18
                  number: 80

看起来”已经配了 200M”，但上传依旧 413。注意域名：实际访问的域名与这里的 host 不一致时，请求会落到入口的兜底 server，注解根本作用不到。

Step 3：抓 nginx 错误日志，锁定”是哪台 nginx”#

在 Rancher：Workloads → Pods →（命名空间）→ 某个 nginx Pod → ⋮ → View Logs，复现一次上传后搜 too large。

1
kubectl -n <ns> logs <nginx-pod> | grep -i "too large"

得到的日志（关键字段见 2.5）：

1
[error] 32#32: *9 client intended to send too large body: 1834823 bytes,
2
client: 10.244.0.1, server: _, request: "POST /client-gateway/client/common/upload HTTP/1.1",
3
host: "cm.wuxi.dev.ljyun.cn"

Step 4：进 Pod，看它真正加载了什么配置#

Rancher：Pod 详情 → ⋮ → Execute Shell（Kuboard 是 终端）。

1
# 我一开始把关键字写错了（client_max_size），所以什么都没查到——正确写法是 client_max_body_size
2
nginx -T 2>&1 | grep -n -E "client_max_body_size|server_name|include|# configuration file"
3

4
cat /etc/nginx/nginx.conf | head -60
5
ls -l /etc/nginx/ /etc/nginx/conf.d/

输出（节选）：

1
3:# configuration file /etc/nginx/nginx.conf:
2
47:    server_name _;
3

4
worker_processes 1;
5
user root;
6

7
events { worker_connections 1024; }
8

9
http {
10
  upstream website             { server compute-maas-website:3000; }
11
  upstream maas-client         { server maas-client-frontend:4173; }
12
  upstream compute-client      { server compute-maas-console-frontend:8000; }
13
  upstream maas-agent          { server maas-chat-backend:8000; }
14
  upstream compute-maas-admin  { server compute-maas-admin-frontend:8000; }
15
  upstream client-auth-gateway { server dispatch-client-gateway-svc:8002; }
16
  upstream server-auth-gateway { server dispatch-server-gateway-svc:8001; }
17
  upstream compute-maas-certificate { server compute-maas-certificate-frontend:8000; }
18

19
  server {
20
    listen 80;
21
    listen [::]:80;
22
    server_name _;
23
    server_tokens off;
24
    ...
25
  }
26
}
27

28
/etc/nginx/:
29
-rw-r--r--  nginx.conf     2242  Sep 23 03:18
30
-rw-r--r--  config.js       152  Sep 23 03:18
31
drwxr-xr-x  conf.d                  Sep 23 03:18

三个结论当场得出：

1. 这个 Pod 是 平台网关 nginx（一个 nginx 代理了 admin / console / website / certificate 等前端，以及两个后端网关），hostname 为 compute-maas-nginx-866dddd44d-d8lgw
2. 它的 nginx.conf 里没有 client_max_body_size → 走默认 1m → 1.8MB 必然 413
3. nginx -T 只列出了 /etc/nginx/nginx.conf，没有 conf.d → 项目仓库里那份配置是死配置，改它永远没用

同时，server_name _; + server_tokens off; 与日志中的 server: _、错误页里不带版本号的 nginx 完全对应——413 就是它发的。

Step 5：确定配置来源，并修改#

nginx.conf、config.js、conf.d/ 时间戳一致 → 判定为挂载（ConfigMap）。

确认来源：

• Rancher：工作负载 → compute-maas-nginx → Pod 模板里的 Volumes → 看挂了哪个 ConfigMap
• 或 Pod 内：cat /proc/mounts | grep -i nginx
• 认领 ConfigMap：在 配置 → ConfigMaps 里找内容包含 upstream compute-maas-admin 的那一份

修改（两种粒度，选其一）：

1
# 方案 A：只放开两个上传接口（影响面最小，推荐）
2
location /server-gateway/ {
3
    client_max_body_size 20m;   # 新增
4
    proxy_pass http://server-auth-gateway/;
5
}
6

7
location /client-gateway/ {
8
    client_max_body_size 20m;   # 新增
9
    proxy_pass http://client-auth-gateway/;
10
}

1
# 方案 B：整台网关放开（省事，但影响所有走它的站点）
2
http {
3
    client_max_body_size 20m;   # 新增
4
    ...
5
}

改完 必须重启（ConfigMap 改动不会自动 reload nginx）：

1
Rancher：工作负载 → compute-maas-nginx → ⋮ → Restart

8.1 现象#

换到第二个环境（cm.wuxi.dev.ljyun.cn）后，console 应用上传依旧 413：

1
2026/09/23 08:33:24 [error] 32#32: *9 client intended to send too large body: 1834823 bytes,
2
client: 10.244.0.1, server: _, request: "POST /client-gateway/client/common/upload HTTP/1.1",
3
host: "cm.wuxi.dev.ljyun.cn"

链路骨架与案例一相同（浏览器 → APISIX → 平台网关 nginx → 后端网关），区别是： 这次的网关是 wuxi-dev 环境那一套（所有 upstream 都带 .wuxi-dev 后缀），而且它的配置里已经有 client_max_body_size 20m; 了，却依然 413。

8.2 理论：nginx 如何选择 server 块#

一个 nginx 可以有多个 server 块（虚拟主机），请求进来时的匹配规则是：

1. 先按 listen 的端口/IP 分组
2. 再按请求头里的 Host 去匹配各 server 块的 server_name（精确匹配 > 通配符 > 正则）
3. 都不匹配时，交给该端口的 default server —— 即显式标了 default_server 的那个，没标的话就是第一个 server 块

两个推论：

• 各 server 块之间的配置互不继承。你在 A 块（server_name token.ljyun.cn）里写 client_max_body_size 20m;，对落在 B 块（server_name _）的请求完全无效。
• 指令只在其所在层级及其子层级继承：http 全局 > server 该虚拟主机 > location 该路径。

同时这也解释了案例一里日志的 server: _ 字段——错误日志中的 server: 反映的是该请求匹配到的 server，此处即配置里的 server_name _;。

8.3 根因：20m 加在了另一个 server 块#

该网关的 /etc/nginx/nginx.conf（4383 字节）里有两个 server 块：

1
http {
2
  upstream website             { server compute-maas-website.wuxi-dev:3000; }
3
  upstream compute-client      { server compute-maas-console-frontend.wuxi-dev:8000; }
4
  upstream compute-maas-admin  { server compute-maas-admin-frontend.wuxi-dev:8000; }
5
  upstream client-auth-gateway { server dispatch-client-gateway-svc.wuxi-dev:8002; }
6
  upstream server-auth-gateway { server dispatch-server-gateway-svc.wuxi-dev:8001; }
7
  ...
8

9
  # ===== 第 1 个 server：兜底，cm.wuxi.dev.ljyun.cn 走这里 =====
10
  server {
11
    listen 80;
12
    server_name _;
13
    server_tokens off;
14

15
    location /console/ { proxy_pass http://compute-client; }
16
    location /admin/   { proxy_pass http://compute-maas-admin; }
17

18
    location /client-gateway/ {
19
      proxy_pass http://client-auth-gateway/;      # ← 没有 client_max_body_size
20
    }
21

22
    location /server-gateway/ {
23
      proxy_pass http://server-auth-gateway/;      # ← 没有 client_max_body_size
24
    }
25
  }
26

27
  # ===== 第 2 个 server：只有 token.ljyun.cn 会命中 =====
28
  server {
29
    listen 80;
30
    server_name token.ljyun.cn;
31

32
    location /client-gateway/ {
33
      proxy_pass http://client-auth-gateway/;
34
      client_max_body_size 20m;                    # ← 第 167 行，加在这里
35
    }
36

37
    location /server-gateway/ {
38
      proxy_pass http://server-auth-gateway/;
39
      client_max_body_size 20m;                    # ← 第 173 行，加在这里
40
    }
41
  }
42
}

nginx -T | grep -n 的输出直接印证了这一点——两处 client_max_body_size 20m; 分别在 167 行和 173 行，都落在 server_name token.ljyun.cn 那个块（118 行起）里：

1
3:# configuration file /etc/nginx/nginx.conf:
2
51:    server_name _;
3
118:      server_name token.ljyun.cn;
4
167:          client_max_body_size 20m;
5
173:          client_max_body_size 20m;

而我们访问的是 cm.wuxi.dev.ljyun.cn → 落到 server_name _ 兜底块 → 那里的两个 location 没有这条指令 → 默认 1m → 1.8MB 被拒。

8.4 如何一眼判断”配置加对了位置没有”#

8.5 修复#

把 client_max_body_size 20m; 加到真正命中的那个块里——即在 server_name _; 的 server 块的两个 location 内补上：

1
  server {
2
    listen 80;
3
    listen [::]:80;
4
    server_name _;
5
    server_tokens off;
6

7
    location /client-gateway/ {
8
      proxy_pass http://client-auth-gateway/;
9
      client_max_body_size 20m;        # 新增
10
    }
11

12
    location /server-gateway/ {
13
      proxy_pass http://server-auth-gateway/;
14
      client_max_body_size 20m;        # 新增
15
    }
16
  }

更省事且更保险的写法是直接写在 http { 里一行（两个 server 块一并覆盖，但等于放开该网关上的所有站点）：

1
http {
2
  client_max_body_size 20m;            # 新增：http 级，所有 server 生效
3
  ...
4
}

改完必须重建 Pod（工作负载 → compute-maas-nginx → ⋮ → Restart），因为：

1. nginx 不会自动 reload 配置文件
2. 该配置文件是 subPath 挂载的 ConfigMap，subPath 挂载不会热更新，只有新 Pod 才会挂到新内容

8.6 本案例的三条教训#

1. 改共享网关前，先确认”你访问的 Host 会命中哪个 server 块”：把 server_name 列表和实际域名对一遍，不要看到配置里有 20m 就以为生效了
2. 存在多个 server 块时，改动要成对做：本次配置里两个块有几乎重复的 location，只改一个块等于没改
3. subPath 挂载的 ConfigMap 改完必须重建 Pod：只改 ConfigMap 不重启，容器里读到的还是老文件