431 和 494 错误与请求头静默截断:分步诊断与限制配置指南
简介
本指南专注于一类范围虽窄但极其棘手的问题:请求无法通过或只通过了一部分,原因在于它的请求头或 Cookie 变得太大了。表面上看,它可能表现为 431 Request Header Fields Too Large 错误,也可能表现为 nginx 特有的 494 Request Header Too Large 代码,或者是含糊不清的 400 Request Header Or Cookie Too Large;而最糟糕的情况是它根本不表现为任何错误:某个中间节点默默丢弃了部分请求头,应用收到的用户没有会话、没有授权令牌,或者缺少必要的 Cookie。
首先需要把它和相邻的主题区分清楚。在另一篇文章中我们分析了 407、502 和 504,这些是代理层在建立隧道时自己返回的:代理认证未通过、上游未启动、超时。那里的问题出在连接和代理本身。而在这里,连接正常建立,隧道也存在,但你试图发送的数据放不进链路中某个节点的缓冲区里。原因始终在于请求头的体积和构成,需要用完全不同的工具来解决。
读完你能获得什么
- 能够在几分钟内精确测量某个请求的请求头和 Cookie 大小。
- 理解到底是链路中的哪个节点(浏览器或客户端、代理、负载均衡器、Web 服务器、应用)在拒绝或截断数据。
- 一个现成的回显端点,用于识别没有任何错误码的静默截断。
- 适用于 nginx、Apache、Node.js、HAProxy、Tomcat 和 Gunicorn 的可用限制配置,并逐一解释每个参数。
- 一套减小 Cookie 的策略,防止问题在一个月后卷土重来。
- 一套监控,能在接近限制前提前预警。
本指南适合谁
适合 Web 开发者、系统管理员、爬虫与自动化工程师,以及那些通过代理操作大量账号、经常遇到莫名其妙拒绝的人。难度中等:你不需要是 HTTP 协议专家,但需要基本的终端操作能力和理解什么是配置文件。
你需要提前知道什么
- 如何打开终端并执行命令。
- 如何在浏览器中打开开发者面板(F12 键)。
- 如果你负责运维,你的 Web 服务器配置文件放在哪里。
- 对请求从客户端经过中间节点到达服务器有一个大致概念。
需要多少时间
步骤 1-4 的诊断需要 30 到 60 分钟。在服务器端修复(步骤 5-7)还需 1-2 小时,包括重启和验证。如果你只是检查别人的服务、没有其配置的访问权限,那么前四步加上 Cookie 缩减那一节就足够了。
前期准备
不需要什么特别的东西,但请提前准备好工具,以免中途分心。
必需工具
- curl 7.70 或更高版本。macOS、所有 Linux 发行版以及 Windows 10 和 11 都自带。用命令
curl --version检查。 - 带开发者面板的浏览器:Chrome、Edge、Firefox 或 Yandex 浏览器。需要用到 Network(网络)标签页和 Application 或 Storage 标签页来查看 Cookie。
- 带语法高亮的文本编辑器:VS Code、Notepad++ 或服务器上的 nano。
- 如果要修改限制,需要SSH 访问服务器。必须拥有读取日志和重启服务的权限。
- Python 3 或 Node.js 用于运行回显端点。任何当前版本都够用。
- 可选:mitmproxy 或反检测浏览器内置的分析器,如果你想查看客户端与代理之间的流量。
系统要求
任何一台工作机器都行。回显服务器 100 MB 内存就够。唯一真正的要求是:能通过网络访问待检查的服务,必要时也能访问所用代理。
需要下载和配置什么
- 确认 curl 可用:执行
curl -sI https://example.com。你应该看到以HTTP/2 200或类似内容开头的响应头行。 - 如果通过代理工作,准备好它的地址、端口、用户名和密码。用命令
curl -x http://用户名:密码@host:port -sI https://example.com测试基本连接。如果这里报 407 或连接根本建立不起来,请回到代理层错误码那篇文章:我们的主题只在隧道成功之后才开始。 - 在服务器上找到主配置:nginx 通常是
/etc/nginx/nginx.conf和/etc/nginx/conf.d/目录,Apache 是/etc/apache2/apache2.conf或/etc/httpd/conf/httpd.conf。 - 找到日志:
/var/log/nginx/error.log、/var/log/nginx/access.log、/var/log/apache2/error.log。确认你能用tail -n 50读取它们。
备份
任何配置修改之前都要先复制一份。这只需几秒钟,却能省下几个小时。
- 执行
sudo cp /etc/nginx/nginx.conf /etc/nginx/nginx.conf.bak-2026。 - 对于站点目录:
sudo cp -r /etc/nginx/conf.d /etc/nginx/conf.d.bak-2026。 - Apache 同理:
sudo cp /etc/apache2/apache2.conf /etc/apache2/apache2.conf.bak-2026。 - 把当前限制值记到一个单独的笔记文件里,以便知道自己从哪儿出发。
注意:在未预先检查语法之前,绝不要修改生产配置。nginx 用 sudo nginx -t,Apache 用 sudo apachectl configtest。一行出错,重启时就会让服务躺下。
基础概念
在捕捉问题之前,先统一术语。这里没什么难的,但词语混乱往往会把诊断带偏。
什么是请求头
任何 HTTP 请求都由起始行(方法、路径、协议版本)、请求头块和可选的主体组成。请求头是形如 名称: 值 的键值对。浏览器会自动添加它们:Host、User-Agent、Accept、Accept-Language、Referer、Authorization,当然还有 Cookie。应用会添加自己的:令牌、追踪标识、实验标记。
为何 Cookie 是最常见的罪魁
Cookie 请求头由所有匹配请求域名和路径的 Cookie 汇集而成。每个分析系统、每个聊天挂件、每个广告网络都会加几个。一个 Cookie 的值最多可达 4 KB,而一个域名上这样的 Cookie 有几十个。而且浏览器会随所有请求发送它们,包括图片和字体请求。结果 Cookie 请求头轻松超过 8-16 KB,而大多数服务器默认就设置在这样的阈值上。
431 代码
431 Request Header Fields Too Large 是 HTTP 规范中定义的标准代码。服务器在说:请求头太大,可能是其中某一个,也可能是全部合起来。Node.js、Go、Envoy、某些 CDN 和现代框架会返回这个代码。431 响应符合协议规范的,在日志中清晰可见,因此是诊断最方便的变体。
494 代码
494 Request Header Too Large 是 nginx 内部非标准代码。当请求头放不进 large_client_header_buffers 指令设置的缓冲区时,nginx 会在自己的代码里使用它。默认情况下客户端收到的是 400,正文为 Request Header Or Cookie Too Large。要看到 494 这个数字只有两种情况:管理员显式配置了 error_page 494,或者你在读取 nginx 的内部变量和日志。所以如果用户抱怨看到写着 400、提到 cookie 的白页,要知道:这就是同一个 494。
静默截断
最讨厌的场景。中间节点不拒绝请求,而是按自己缓冲区的大小截断请求头,或者干脆丢掉一部分请求头。应用收到不完整的数据。症状五花八门:用户突然被登出、购物车丢失、令牌读不出来、带地区标识的请求头消失。没有错误码,Web 服务器日志里全绿。这种行为见于基于固定缓冲区的自研代理、老旧的企业网关、某些软处理模式的 WAF、会拆分或截断长值的客户端库,以及浏览器本身——它会静默忽略超过 4096 字节的 Set-Cookie。
限制到底在哪些地方
想象这样一条链路:浏览器或脚本,然后是你的出口代理(例如移动代理),然后是 CDN 或 WAF,然后是负载均衡器,然后是 Web 服务器,然后是应用服务器。每一环都有自己的限制和超限行为。诊断任务就是找到最窄的瓶颈。正因如此,单纯调大 nginx 的限制往往不够:它后面还有自己的 16 KB 阈值的 Node.js。
与 502 upstream sent too big header 的边界
两个主题交界处的一个特殊情形。如果 nginx 在 error.log 里写 upstream sent too big header while reading response header from upstream 并返回 502,那问题不在隧道也不在上游宕机,而在于应用的响应头放不进 proxy_buffer_size。形式上这是 502,但要用我们这里讲的缓冲区参数来治。记住这个标记:它能帮你不在代理层里瞎找。
步骤 1:复现问题并记录症状
本阶段目标:获得一个能稳定触发错误的场景,并记录精确特征:状态码、响应正文、Server 请求头和时间。
- 在浏览器中打开有问题的页面。按 F12,切换到 Network(网络)标签页。
- 勾选 Preserve log(保留日志),以免跳转时记录消失。
- 按 F5 重新加载页面。找到标红的请求,或状态为 400、431、494 的请求。点击它。
- 在 Headers 标签页记录:状态码、响应中
Server请求头的值(nginx、cloudflare、AkamaiGHost、gunicorn)、Via的值(如果有),以及任何以X-或CF-开头的请求头。 - 切换到 Response 标签页,复制响应正文。Request Header Or Cookie Too Large 这句话指向 nginx。不带 Cookie 一词的 Request Header Fields Too Large 通常来自 Node.js。Bad Request - Request Too Long 则是 IIS 的特征。
- 向下滚动到 Request Headers 块。估一下
Cookie行的长度:如果它占了好几屏,这本身就是提示。 - 打开无痕模式窗口重发请求。如果全新配置里没有错误,那就是某个用户积累的 Cookie 有问题。
如果问题在脚本里而不是浏览器里复现,从库的响应里记录同样的数据:状态、正文、请求头。在 Python requests 里是 response.status_code、response.text 和 response.headers。
建议:在请求列表上右键,选择 Save all as HAR with content,把所有请求导出为 HAR 文件。这个文件以后可以打开或发给同事,它会保留请求头的精确大小。
检查:你应该有一份包含四点的笔记:状态码、响应正文文本、Server 请求头的值,以及无痕模式测试的结果。如果无痕模式结果不同,你已经知道 70% 的原因了。
可能遇到的问题
- 错误不是每次都出现。说明 Cookie 大小在阈值附近浮动:例如访问某个分区后会再多一个 Cookie。记录错误在哪些操作之后出现。
- 没有红色请求,但页面工作不正常。这是静默截断的迹象。测量完立即进入步骤 4。
步骤 2:测量请求头和 Cookie 的真实大小
本阶段目标:拿到精确的字节数字:请求头块的总大小、Cookie 请求头的大小、每个单独 Cookie 的大小。
在浏览器中测量
- 在开发者面板打开 Console(控制台)标签页。
- 输入
document.cookie.length回车。你会看到一个数字:这是脚本可访问的所有 Cookie 的字符长度,不含 HttpOnly 标志。真实请求头会更大,因为 HttpOnly Cookie 不在其中。 - 输入
document.cookie.split('; ').map(c => [c.split('=')[0], c.length]).sort((a, b) => b[1] - a[1])。控制台会显示按长度降序排列的名称-长度数组。最重的 Cookie 会排在最上面。 - 切换到 Application 标签页(Firefox 中是 Storage),展开 Cookies,选择域名。这里能看到所有 Cookie,包括 HttpOnly,并带有 Size 列。点击列标题可按大小排序。
- 把大小加起来,或直接看步骤 1 请求里的 Cookie 行:Chrome 中悬停在请求头上会显示其长度。
用 curl 测量
curl 可以发送任意大小的请求头,并精确判断服务器在多大体积时开始拒绝。我们来生成一个长度可控的 Cookie。
- 创建一个 8000 字符的字符串。在 Linux 和 macOS 中:
BIG=$(head -c 8000 /dev/zero | tr '\0' 'a')。如果 shell 报转义错误,用这个变体BIG=$(python3 -c "print('a'*8000)")。 - 发送请求:
curl -s -o /dev/null -w '%{http_code}' -H "Cookie: test=$BIG" https://你的网站.ru/。屏幕上只会出现响应码。 - 改变大小:4000、8000、12000、16000、32000、64000。记录在哪个值上状态码从 200 变成 400 或 431。
- 如果通过代理工作,加上
-x http://用户名:密码@host:port再跑一遍。带代理和不带代理的阈值之差会显示代理本身是否有自己的限制。
用一条命令做二分查找阈值的 bash 示例:
for n in 4000 8000 12000 16000 24000 32000 64000; do BIG=$(python3 -c "print('a'*$n)"); echo -n "$n: "; curl -s -o /dev/null -w '%{http_code}' -H "Cookie: t=$BIG" https://你的网站.ru/; echo; doneWindows PowerShell 中的等价写法:$big = 'a' * 16000; curl.exe -s -o NUL -w '%{http_code}' -H "Cookie: t=$big" https://你的网站.ru/。
数字解读
- 阈值约 8 KB:Apache 默认设置、Tomcat、Gunicorn 的典型值,也是 nginx 在请求头放不进四个 8 KB 缓冲区之一时的表现。
- 阈值约 16 KB:Node.js 13 版本起、使用基础 tune.bufsize 的 HAProxy、IIS。
- 阈值约 32 KB:某些 CDN 的总限制。那里单个请求头通常限制在 16 KB。
- 阈值约 60-64 KB:Envoy 和部分云负载均衡器。
- 阈值约 1 MB:标准 Go 服务器。
建议:不要只测 Cookie。用 Authorization: Bearer $BIG 和几个较小的请求头重复测试。有些服务器会单独限制单个字段的大小、单独限制字段数量、单独限制总容量。例如 nginx 默认即整体不大,也不会放行单个超过 8 KB 的请求头,因为每一行都必须放进单独的缓冲区。
检查:笔记里应该出现一个数字——服务器开始拒绝时的大小,以及三到五个最重 Cookie 及其大小的列表。如果到 64 KB 都没找到阈值,而浏览器里却有错误,那么拒绝的不是服务器,而是你特定环境中浏览器和服务器之间的某个东西。请进入下一步。
步骤 3:确定是哪一层在拒绝
本阶段目标:准确说出链路中返回错误或裁剪数据的节点,以便在正确的地方修改设置。
阅读响应签名
- 执行
curl -sv -H "Cookie: t=$BIG" https://你的网站.ru/ 2>&1 | grep -i -E 'server|via|cf-|x-served|x-cache|HTTP/',其中 BIG 明显超过阈值。 - 阅读
Server请求头。值为 nginx 且正文为 Request Header Or Cookie Too Large,说明拒绝的是 nginx。值为 cloudflare 说明请求根本没到你的服务器。Server 为空且正文为 JSON 格式,通常指向应用。 - 注意第一行中的协议版本。如果正常请求时服务器用 HTTP/2 响应,而错误却通过 HTTP/1.1 返回,这是响应由中间节点而非最终节点生成的迹象。
- 对比错误正文:nginx 页面简洁,底部有它的名字;Cloudflare 页面包含 Ray ID;Node.js 常返回空正文加 431 状态。
绕过各层
- 如果你有 CDN 后面服务器的直连 IP,用
--resolve 你的网站.ru:443:1.2.3.4重发请求。这会强制 curl 直连,同时保留正确的 Host 和 SNI。如果直连通过而走 CDN 不通过,限制就在 CDN 上。 - 如果你有服务器访问权限,在本地执行请求:
curl -s -o /dev/null -w '%{http_code}' -H "Cookie: t=$BIG" -H 'Host: 你的网站.ru' http://127.0.0.1:80/。这样就排除了所有外部节点。 - 然后直接打应用,绕过 nginx:Node.js 用
curl ... http://127.0.0.1:3000/或 Gunicorn 监听的端口。如果 nginx 放行而应用返回 431,限制就在应用里。 - 检查你的出口代理的影响:一组请求带
-x,一组不带。对于通过代理的 HTTPS 请求使用 CONNECT 方法,代理看不到加密隧道内的请求头,因此无法影响其大小。但对于普通 HTTP 请求,代理自己解析请求头,这时就可能有自己的限制甚至截断。
在服务器上读日志
- 执行
sudo tail -f /var/log/nginx/error.log并重发问题请求。 - client sent too long header line 这行确认单个请求头行超过了 nginx 的缓冲区。client sent too large request 则表示总容量溢出。
- Apache 的 error.log 里找 Request header exceeds LimitRequestFieldSize 或 Size of a request header field exceeds server limit。
- Node.js 的应用日志里:错误 HPE_HEADER_OVERFLOW,这是解析器的内部代码,对外会变成 431。
- 在 nginx 的 access.log 里查看请求大小的字段。如果你用的是标准格式,在 log_format 里加上变量
$request_length:它会显示请求连同请求头的总大小,对监控很有用。
注意:如果在 nginx 的 error.log 里看到 upstream sent too big header,拒绝的不是入站请求,而是你应用的响应,它的请求头放不进 nginx 的缓冲区。这种情况看起来像 502,但属于我们的主题。原因通常是巨大的 Set-Cookie 或框架发出的几十个请求头。解决方案在步骤 6。
检查:你应该能胸有成竹地说出其中之一:拒绝的是 CDN;拒绝的是 nginx;拒绝的是 Apache;拒绝的是应用;拒绝的是我这边的代理。如果情况不明确,说明多个节点同时超限,需要逐个修改,每次都重复步骤 2 的测试。
步骤 4:用回显端点识别静默截断
本阶段目标:确认请求头以发送时的原样到达应用,并抓住那个默默修改它们的节点。
思路很简单。我们启动一个小服务器,在响应中返回收到的所有请求头及其大小。发送一个已知长度、带校验和的请求头,对比收到了什么。
启动 Python 回显服务器
- 创建文件
echo.py,内容如下:
import hashlib, json
from http.server import BaseHTTPRequestHandler, HTTPServer
class H(BaseHTTPRequestHandler):
def do_GET(self):
out = {}
total = 0
for k, v in self.headers.items():
total += len(k) + len(v) + 4
out[k] = {"len": len(v), "sha": hashlib.sha256(v.encode()).hexdigest()[:12]}
out["_total"] = total
out["_count"] = len(self.headers)
body = json.dumps(out, indent=1).encode()
self.send_response(200)
self.send_header("Content-Type", "application/json")
self.send_header("Content-Length", str(len(body)))
self.end_headers()
self.wfile.write(body)
HTTPServer(("0.0.0.0", 8089), H).serve_forever()- 运行:
python3 echo.py。服务器监听 8089 端口。 - 把它放在你真实应用所在的位置,或临时在 nginx 中把一个 location 指向它:
location /__echo { proxy_pass http://127.0.0.1:8089; }。这样请求就会经过完整真实链路。
注意 Python 标准 HTTPServer 对请求头长度没有硬性限制,但会把请求头数量限制在几十个。测试够用。
发送控制请求
- 生成一个 12000 字符的值,注意不要同质化,要带位置标记,以便看出从哪儿被截断:
V=$(python3 -c "print(''.join(str(i%10) for i in range(12000)))")。 - 计算基准哈希:
python3 -c "import hashlib,sys; print(hashlib.sha256(sys.argv[1].encode()).hexdigest()[:12])" "$V"。 - 通过整条链路发送:
curl -s -H "Cookie: probe=$V" -H "X-Probe-Len: 12000" https://你的网站.ru/__echo。 - 在响应中对比 Cookie 的 len 字段与数字 12006(名称 probe 加等号加 12000 字符)以及哈希与基准值。
- 用多个请求头重复:添加 30 个
X-Test-1……X-Test-30,检查 _count 字段。
如何解读结果
- 长度一致,哈希一致:这条路径上没有截断。
- 长度变小,请求头被切断:有人截掉了尾部。看收到值的最后一个字符:它能提示切点位置,通常是 4096 或 8192 字节的整齐边界。
- 请求头完全缺失:节点丢弃了放不进缓冲区的字段。某些 WAF 和老旧网关就是这么干的。
- _count 小于发送值:达到了请求头数量上限。Apache 和 Gunicorn 默认接受 100 个字段,HAProxy 是 101,部分实现会默默丢掉多余的。
- 长度一致,哈希不一致:节点修改了内容。空格归一化或重新编码时会出现这种情况;检查值里是否有代理视为非法的字符。
建议:如果你通过移动或其他外部代理工作,在公网可访问的主机上架起回显服务器,用普通 HTTP 而非 TLS 跑请求。正是在这种模式下代理自己解析请求头,能展示自己的限制。在 HTTPS 通过 CONNECT 的模式下,内容对代理是不透明的,这一层物理上不可能截断。
检查:你有一张表:节点、发送字节、收到字节、哈希是否一致。如果所有行都一致,就没有静默截断,你的症状用步骤 1-3 的显式拒绝就能解释。如果有出入,你就知道问题在哪。
单独检查浏览器的 Set-Cookie 行为
浏览器也会静默裁剪,但不是请求,而是响应。如果服务器发送的 Set-Cookie 超过约 4096 字节,Chrome 和 Firefox 会直接忽略它,不给任何警告。检查方法:在 Network 标签页找到带 Set-Cookie 的响应,看该行的长度,然后打开 Application 标签页确认 Cookie 是否保存。如果没保存,就把值拆成几部分,或者把数据挪到服务器端。
步骤 5:减小 Cookie 和请求头的体积
本阶段目标:根除问题根源,让请求能放进标准限制里,不再依赖中间节点的恩赐。
调大限制很诱人,但那是治标。每个多余的千字节 Cookie 都会随每个用户的每个请求发送,包括图片请求。先从缩减开始。
Cookie 审计
- 取步骤 2 得到的按大小排序的列表。
- 对每个 Cookie 回答三个问题:谁设置它,服务器是否需要它,站点每个路径是否都需要它。
- 分析系统和广告像素的 Cookie 服务器几乎从不需要。不需要删除它们,但不要把它们发到 API 域名。
- 带序列化状态的 Cookie(JSON 购物车、界面设置、浏览历史)是挪到 localStorage 或服务端存储加短标识的候选对象。
缩减技巧
- 把 API 拆到单独子域名。在没有显式 Domain 的情况下设置在 www.网站.ru 上的 Cookie 不会发往 api.网站.ru。沉重的营销 Cookie 留在门面上,API 只拿到会话。
- 设置 Path 属性。带
Path=/admin的 Cookie 不会发往/static的请求。检查你的框架是否没必要地把所有 Cookie 都设在根路径。 - Cookie 里存标识而不是数据。不要放 3 KB 的 JSON,放一个 32 字符的键,数据放在 Redis 或数据库里。顺便还能解决内容被伪造的问题。
- 精简 JWT。Cookie 或 Authorization 里的令牌会因 payload 中的多余字段而膨胀:角色列表、地址、头像。只留标识和有效期,其余通过单独调用获取。典型 JWT 应控制在 500-800 字节。
- 显式删除过期 Cookie。如果你重命名了 Cookie,旧的会留在用户那里直到过期。用旧名字发一个 Max-Age=0 的 Set-Cookie。
- 为静态资源使用不带 Cookie 的独立域名。经典做法:static.网站.ru 或 CDN 域名,完全不在上面设置 Cookie。
- 检查重复。同一个 Cookie 常常存在两个版本:给 网站.ru 的和给 .网站.ru(带点)的。浏览器会把两个都发出去。
面向脚本和自动化
如果你通过代理和反检测浏览器管理大量账号,要留意配置文件。存活半年的配置文件会积累几十个第三方域名的 Cookie,对目标站点的请求正因为膨胀的请求头而开始被拒。设置定期清理第三方域名的 Cookie,但不要动目标站点的授权 Cookie。在 requests 或 httpx 这类库里,按账号把 Cookie 存在单独的 CookieJar 里,每天删除一次已过期的记录。
建议:在客户端加一个简单检查:如果 document.cookie.length 超过 6000 字符,就向你的分析系统发一个指标。这样你会从首批用户那里得知问题,而不是从大规模投诉中。
检查:在干净配置上重复步骤 2 的测量,走一遍典型用户场景(登录、目录、购物车、结算),确认请求头总大小在 API 上不超过 4 KB、在门面上不超过 8 KB。相对于任何标准限制这都是舒适的余量。
步骤 6:在 Web 服务器、负载均衡器和应用中配置限制
本阶段目标:在你管理的所有节点上设置一致的限制,使其中任何一个都不会意外地比邻居更窄。
黄金法则:外层节点的限制应该不大于内层节点的限制。否则 nginx 放行 32 KB,而它后面的 Node.js 用 431 拒绝,你会在栈深处拿到更难诊断的错误。2026 年的合理参考值:整个请求头块 16 KB,单个字段 8-16 KB。这几乎够所有人用,同时还能防滥用。
nginx
- 打开
/etc/nginx/nginx.conf。找到http { ... }块。 - 添加或修改三条指令:
http {
client_header_buffer_size 4k;
large_client_header_buffers 4 16k;
proxy_buffer_size 16k;
proxy_buffers 8 16k;
}client_header_buffer_size是处理典型请求的第一个小缓冲区。默认值 1k 会让 nginx 几乎总是切换到更大的缓冲区,这不算坏事,但 4k 能减少多余的分配。large_client_header_buffers 4 16k表示:最多四个 16 KB 的缓冲区。每一行请求头都必须完整放进一个缓冲区,整个块则要放进所有缓冲区之和。也就是说,单个 Cookie 或 Authorization 不能超过 16 KB,所有请求头合计 64 KB。proxy_buffer_size负责上游响应的第一部分,包括它的响应头。正是调大它才能消除带 upstream sent too big header 字样的 502。proxy_buffers的值不应小于 proxy_buffer_size。- 如果你希望客户端看到有意义的响应而不是标准的 400 页面,在 server 里加上:
error_page 494 =431 /431.html;,并放置带有清晰文案和建议清理 Cookie 的 431.html 文件。这样你就把非标准的 494 变成了标准的 431。 - 检查语法:
sudo nginx -t。应显示 syntax is ok 和 test is successful。 - 不断开连接地应用:
sudo nginx -s reload。
记住 large_client_header_buffers 也可以在 server 上下文里设置,但对 HTTP/2 生效的是 http 上下文里的值,所以要改就改那里。对 HTTP/2 过去还有 http2_max_header_size 指令;在当前的构建中它已被移除,large_client_header_buffers 就够了。
Apache
- 打开主配置,在服务器或 VirtualHost 级别添加:
LimitRequestFieldSize 16384
LimitRequestFields 150
LimitRequestLine 16384LimitRequestFieldSize限制单个字段,默认 8190 字节。LimitRequestFields限制字段数量,默认 100。LimitRequestLine限制起始行,这对带参数的冗长 URL 很重要。- 如果 Apache 通过 mod_proxy_http 作为反向代理,为带大请求头的响应添加
ProxyIOBufferSize 32768。 - 检查:
sudo apachectl configtest,然后sudo systemctl reload apache2。
Node.js
- 限制通过进程启动参数
--max-http-header-size设置。值以字节为单位:node --max-http-header-size=32768 server.js。 - 如果你用 PM2 或 systemd,把参数写进 node_args 字段或环境变量
NODE_OPTIONS=--max-http-header-size=32768。 - 代码里的替代方案:
http.createServer({ maxHeaderSize: 32768 }, app)。当前版本的 Node 支持这个参数,可以在不改启动参数的情况下设置限制。 - 重启后直接用 curl 打 Node 端口验证:阈值应该发生移动。
Tomcat 和 Spring Boot
- 在
server.xml的 Connector 元素上添加属性maxHttpHeaderSize="16384"。默认是 8192。 - Spring Boot 里在 application.properties 加一行即可:
server.max-http-request-header-size=16KB。旧属性名 server.max-http-header-size 在部分版本也能用,但已标记为废弃。 - 重启应用并验证阈值。
Gunicorn 和 Uvicorn
- Gunicorn 在配置或命令行里添加:
--limit-request-field_size 16380 --limit-request-fields 150 --limit-request-line 8190。注意 field_size 是下划线写法:这是历史遗留,用连字符参数不会生效。 - limit-request-field_size 值为 0 会完全取消限制,但不要在公网服务器上这么做。
- Uvicorn 通过 h11 解析器限制请求头大小,默认允许相当大的值;瓶颈通常不在它,而在它前面的 nginx。
HAProxy
- 在 global 段:
tune.bufsize 32768和tune.http.maxhdr 150。 - 整个请求连同所有请求头必须放进一个大小为 tune.bufsize 减去 tune.maxrewrite 预留的缓冲区。默认 16384 时实际可用约 15 KB。
- 用
haproxy -c -f /etc/haproxy/haproxy.cfg检查并重启。注意增大 bufsize 会提高每个连接的内存占用。
IIS
- 限制在注册表 HTTP.sys 分支:参数 MaxFieldLength 和 MaxRequestBytes 位于 HKLM SYSTEM CurrentControlSet Services HTTP Parameters 键。默认两者都是 16384 字节,最大 65534。
- 修改后需要重启 HTTP 服务或服务器。
- 如果问题涉及冗长 URL,另外检查 requestFiltering 里的
maxAllowedContentLength和maxQueryString。
CDN 和 WAF
大多数云 CDN 在基础套餐里限制是固定的,只在企业套餐里才能调整。如果步骤 3 的阈值卡在 CDN 上,唯一通用的办法就是步骤 5 的缩减 Cookie。另外检查 WAF 是否配置成了不拦截大请求头而是裁掉它们的模式:这种模式正是静默截断的根源,最好切换成带错误码的显式拒绝。
注意:不要为了安心把限制设成兆字节级别。每个千字节的缓冲区都会乘以并发连接数,而攻击者可以故意发送巨型请求头来耗尽内存。保持在真实最大值两到三倍的合理余量即可,不要更多。
检查:对每个节点分别重复步骤 2 的 curl 系列(直连应用、经 nginx、外部经 CDN)。阈值应当要么相同,要么从内向外递减。确认超限时每个节点都返回清晰的代码,而不是切断连接。
步骤 7:让拒绝变得显式并配置监控
本阶段目标:杜绝未来的静默截断,并在请求头触限之前就得知它们增长的情况。
用显式响应替代沉默
- 确认你的每个节点超限时都返回 431 或至少带文本的 400。nginx 里已在步骤 6 通过 error_page 494 做到。
- 如果你有基于固定缓冲区的自研代理或网关,加一个检查:如果请求头放不进,就返回 431 并关闭连接。绝不把截断后的值继续传下去。
- 在应用里对关键请求头加校验。例如,如果 JWT 解析不了,或者会话 Cookie 短于预期长度,就单独记录一个带 possible truncation 标记的事件。这是在任何外部节点上检测问题的廉价探测器。
记录大小
- 在 nginx 中扩展日志格式。在 http 块里:
log_format withsize '$remote_addr - $status "$request" req_len=$request_length cookie_len=$cookie_len';
map $http_cookie $cookie_len { default 0; ~^(?<c>.*)$ $c; }- 不用 map 的简单可靠方案:只记录
$request_length。这个变量足以看出增长。 - 每天用
awk跑一遍 access.log,找出 req_len 的最大值和 99 百分位。如果 99 百分位超过限制的一半,就该清理 Cookie 了。 - Apache 在 LogFormat 里使用 mod_logio 的
%I变量:它显示包含请求头在内的入站字节数。
告警
- 为带 Cookie 相关正文的 431 和 400 响应数设一个指标。在 Prometheus 配 nginx-exporter 时用 access.log 中的状态;云监控面板通常也有按代码的拆分。
- 设置阈值:5 分钟内超过 10 个此类响应就是信号。大规模 431 几乎总是意味着有人上线了新的沉重 Cookie。
- 加一个合成检查:每小时一次脚本发送一个大小为限制 90% 的请求头,确认它能通过;再发送限制 110% 的请求头,确认返回的正是 431。这样既能抓住意外的限制收紧,也能抓住意外的限制放开。
建议:把步骤 4 的回显端点长期保留,用 IP 或简单认证保护起来。每次基础设施变动时它都有用:加了 WAF、换了负载均衡器、接了新的代理池,一分钟就能确认请求头完整到达。
检查:发送一个明显过大的请求,确认它以正确大小进了日志、431 计数器增加了、在拨动阈值时告警触发了。之后把阈值调回工作值。
结果验证
过一遍检查清单。每一项都应满足,否则回到对应步骤。
检查清单
- 步骤 1 的问题页面在浏览器主配置中打开无错误。
- 典型请求的请求头总大小不超过 8 KB,在 API 域名上不超过 4 KB。
- 没有任何 Cookie 超过 2 KB,最重的第三方 Cookie 不会发往 API。
- 每个节点的拒绝阈值已知并记录在案;限制从应用到外围要么递减要么相同。
- 超限时客户端收到 431 或带文本的 400,而不是连接中断或静默裁剪过的请求。
- 回显端点显示通过整条链路(包括你的代理)发送时长度和哈希一致。
- access.log 中存在请求大小,已配置 431 增长的告警。
- 配置备份就在旁边,你知道回滚命令。
如何完整测试
- 清掉测试域名的 Cookie,走一遍从登录到关键操作的用户场景。不应有错误。
- 从外部运行步骤 2 的 curl 循环。记录阈值;它应与你新的设置相符。
- 通过每条使用的路径向回显端点发送控制请求:直连、经 CDN、经代理池。
- 故意发送两倍于限制的请求头,确认收到带清晰正文的 431。
- 确认带大 Set-Cookie 的应用响应不会引发 nginx 的 502。
成功指标
常规流量中带请求头相关文本的 431 和 400 响应占比趋近于零。请求大小的 99 百分位低于最窄限制的一半。无端登出和丢失会话不再出现在用户反馈中。
常见错误与解决办法
调大了 nginx 限制,431 依旧
原因:nginx 后面是自带 8-16 KB 限制的 Node.js 或 Tomcat,现在拒绝的是它。解决办法:从步骤 3 直接打应用端口检查阈值,用 --max-http-header-size 或 maxHttpHeaderSize 调大。然后确认 nginx 的限制不大于应用的。
在 server 块设置了 large_client_header_buffers,但没变化
原因:对 HTTP/2,nginx 使用 http 上下文中的值;而且同一地址有多个 server 时,该指令的继承并不像预期那样。解决办法:把指令挪到 http 块并重载配置。
错误只在一部分用户身上出现
原因:Cookie 大小取决于具体用户的历史:访问过的分区、开启的实验、上个站点版本遗留的旧 Cookie。解决办法:用 $request_length 收集大小统计,找出哪些 Cookie 在增长,并通过带 Max-Age=0 的 Set-Cookie 显式删除过期的。
清完 Cookie 就好了,但一周后又坏了
原因:增长源头没消除:例如分析脚本每次访问都往同一个 Cookie 里追加数据。解决办法:在不同日期按大小排序,找出正在增长的 Cookie,把内容挪到 localStorage,或在脚本供应商那一侧加以限制。
Nginx 返回 502,尽管应用还活着
原因:error.log 里有 upstream sent too big header:应用的响应头放不进 proxy_buffer_size。通常是巨大的 Set-Cookie 或大量调试请求头惹的祸。解决办法:把 proxy_buffer_size 调到 16k、proxy_buffers 调到 8 16k,同时在应用里精简响应头。
经代理的 HTTP 请求丢了一部分请求头,而 HTTPS 正常
原因:对 HTTP,代理自己解析请求头并撞上自己的缓冲区;对 HTTPS 经 CONNECT,内容不透明,能原样通过。解决办法:为目标资源改用 HTTPS,或缩减请求头。如果代理是你自己的,调大它的限制,并配置显式拒绝而不是截断。
服务器响应后浏览器不保存 Cookie
原因:Set-Cookie 行超过 4096 字节,或该域名上的 Cookie 总数超过浏览器上限(Chrome 约 180 个),于是它默默丢弃新的或挤掉旧的。解决办法:Cookie 里只存标识,数据放服务器端;不要创建几十个小 Cookie,把它们合并。
Gunicorn 忽略限制参数
原因:参数写成了带连字符的 limit-request-field-size,而正确的名字带下划线:limit-request-field_size。解决办法:改正拼写并重启 worker。
进阶技巧
为不同路径设置不同限制
不必为整个站点调大限制。如果只有某个路径需要沉重请求头,例如上传带长元数据的文件,在 nginx 里可以把该路径拆到独立名称或端口上的独立 server,配更大的 large_client_header_buffers,主站保持严格。这样在更需要防滥用的地方保住了防护。
HTTP/2 和 HTTP/3 中的请求头压缩
HTTP/2 和 HTTP/3 用 HPACK 和 QPACK 算法压缩请求头。在线路上重复的 Cookie 会以紧凑形式传输,但在服务器上会解压回完整大小,限制正是按解压后的数据来执行的。所以启用 HTTP/2 能省流量,却不能免于 431。服务器向客户端声明的 SETTINGS_MAX_HEADER_LIST_SIZE 参数设定了解压后列表的上限;nginx 里它由 large_client_header_buffers 自动算出。
分块 Cookie
一些授权库能把长值拆成带 .0、.1、.2 后缀的几个 Cookie,在服务器端再拼起来。这解决了浏览器单个 Cookie 4 KB 的限制,但不减小 Cookie 请求头的总大小。此技巧只应在迁移到服务端会话存储期间作为临时措施使用。
用服务端会话替代 Cookie 容器
最可靠的架构方案:Cookie 里只留 32-64 字符的随机标识,所有状态放带 TTL 的 Redis。这样 Cookie 请求头很少超过 200 字节,整个限制话题就不再相关。迁移对小应用只要一天,对大应用要几周,但能通过降低流量和简化安全来收回成本。
CI 中的自动检查
在流水线里加一个测试:启动应用,发送大小为声明限制 90% 的请求头,确认状态 200;再发送 120%,确认状态 431。测试只需几秒,却能防止框架升级时默认值变化导致限制被意外收窄。
与代理池配合
如果你使用多个代理服务器或带轮换的移动代理池,通过每个出口用 HTTP 和 HTTPS 各跑一次回显端点的控制请求。把结果存进表格。这样能发现行为非标准的出口,你可以排除它们,或只让它们走 HTTPS 流量——那里不可能发生截断。
常见问题
431 和 494 本质都是大请求头,有什么区别?
431 是 HTTP 规范中的标准代码,所有客户端和监控工具都能理解。494 是 nginx 的内部代码,默认对外会变成带 Request Header Or Cookie Too Large 文本的 400。对用户来说没差别,但对诊断而言,日志里或 error_page 里的 494 明确指向 nginx 是源头。
能不能干脆设个超大限制然后不管了?
技术上可以,但这样会增加每个连接的内存占用,并方便巨型请求头攻击。此外 CDN 和浏览器的限制不受你控制,问题只会挪到那里。正确顺序:先缩减 Cookie,再设置带余量的适度限制。
为什么无痕模式正常,普通模式报错?
无痕模式没有积累的 Cookie。这几乎是百分之百的迹象,说明原因在具体用户的 Cookie 请求头大小上。清掉该域名的 Cookie 能一次性解决,而步骤 5 能永久解决。
没有服务器访问权限时怎么测量请求头大小?
用开发者面板:Application 标签页显示每个 Cookie 的大小,控制台的 document.cookie.length 命令给出脚本可访问 Cookie 的总长度。要测精确的拒绝阈值,用 curl 发送人为加大的请求头,观察响应码。
我的代理在 HTTPS 请求里会截断请求头吗?
不会。HTTPS 通过代理时使用 CONNECT 方法,代理转发的是加密字节流,看不到内容。它物理上无法截断或修改其中的请求头。但对于普通 HTTP 请求,代理自己解析请求头,这里就可能有各种限制和截断。
没有错误时怎么判断请求头被截断了?
架起步骤 4 的回显端点,发送一个带位置标记的已知长度请求头,对比收到值的长度和哈希与发送值。差异既能显示截断事实,也能显示切点位置。
Nginx 放行,而 Node.js 应用返回 431,怎么办?
用 --max-http-header-size 参数或 createServer 的 maxHeaderSize 参数调大 Node.js 的限制,然后把 nginx 的限制调到相同或更小的值,让拒绝发生在外层并带清晰页面。
限制单个请求头大小还是总大小更重要?
两者都重要。总大小保护内存,单字段限制保护解析器。在 nginx 里两个限制都由 large_client_header_buffers 推出:缓冲区大小是单行限制,缓冲区数乘以大小是总限制。
是否应该在客户端拦截 431 并自动清理 Cookie?
对自家网站这是个好办法:收到 431 或带特定文本的 400 时,前端删掉明显非必要的 Cookie 并重发请求。不要在未经用户同意的情况下删除授权 Cookie,并且一定要记录这类事件,以便根除问题。
如何确认新版框架没有改变默认限制?
保留步骤 7 的合成检查和进阶技巧里的 CI 测试。两者都在限制边界发送请求,一旦阈值向任何方向移动就能立刻发现。
结语
来总结一下你做了的事。你学会了复现错误,并通过响应签名区分 431、494 及其 400 的公开化身。你测量了请求头和 Cookie 的真实大小,用 curl 二分查找找到了拒绝阈值。你确定了链路中哪个节点负责拒绝,并把这个问题与 407、502、504 等代理层代码区分开,同时留下了 upstream sent too big header 这个有用的标记。借助回显端点,你抓住了或排除了不留日志痕迹的静默截断。接着你缩减了 Cookie,把 API 挪到干净域名,统一了 nginx、Apache、Node.js、Tomcat、Gunicorn 和 HAProxy 上的限制,让拒绝变得显式,并接上了监控。
下一步做什么。接下来一周观察请求大小指标和 431 计数器:它们会显示 Cookie 增长源头是否还在。给团队立个规矩:任何新 Cookie 都要经过评审,回答大小、域名和路径的问题。如果项目在 Cookie 里用序列化状态做会话,安排迁移到带短标识的服务端存储。
往哪儿发展。下一个层次是深入理解 HTTP/2 和 HTTP/3 的请求头压缩、按负载精细调优缓冲区,以及构建可观测性层,让每个请求的大小在追踪中可见。另外值得研究通过不同类型代理和负载均衡器时限制的行为,并为你所用的基础设施建立自己的阈值表。本指南中收集的工具,包括回显端点和 curl 循环,会一直陪着你,在下次遇到奇怪拒绝时省下数小时。你已经成功了,这类问题不再是谜。