遇到LLM网关重试问题,我最先确认的是上游超时和5xx出现时,Nginx到底把那一次原始请求重放成了什么样子。很多情况下重试没有效果,不是因为上游真的挂了,而是重试时请求体已经被改动,或者URI被rewrite规则带偏了。下面把排查顺序和处理方式写出来,供参考。
先确认现象:重试请求和原始请求是否完全一致
实现LLM网关重试时,最容易踩的坑是上游返回超时或5xx后,重试请求却带着被解析过的body结构,甚至丢了原始字段。由于大模型接口通常要求JSON格式的完整载荷,任何字段缺失都可能导致新的4xx错误。因此,在进入Nginx Lua的access_by_lua阶段,就应该先用ngx.req.read_body()把原始body以字符串形式读取并保存在共享内存或模块级变量中,后续重试时直接复用这份原始字符串,而不是从表结构中重新序列化。这样可以避免因字段顺序变化、数字精度丢失或额外空格导致的签名校验失败。
具体操作上,我会在access阶段先判断当前请求是否需要重试。如果重试条件满足,就把保存好的body原样交给新的请求。这里要注意,body读取必须在修改请求之前完成,否则拿到的可能是被改写后的内容。
-- access_by_lua阶段读取并保存原始body
ngx.req.read_body()
local body = ngx.req.get_body_data()
if not body then
local body_file = ngx.req.get_body_file()
if body_file then
local f = io.open(body_file, "rb")
body = f:read("*a")
f:close()
end
end
-- 保存到模块变量或共享字典,后续重试时使用
ngx.ctx.original_request_body = body这里的验证方式是记录一次正常请求和一次重试请求的md5值,如果两次一致,说明body没有被改动。失败时优先检查是否在读取body之前执行过ngx.req.set_body_data或proxy_pass,这会干扰原始数据的获取。
容易误判:URI重放时只关心路径,忽略查询参数
重试时URI重放不能只关注路径部分,查询参数同样需要原样保留。建议在日志阶段或变量捕获阶段,通过ngx.var.request_uri获取完整的原始请求URI,包括问号后的所有参数,然后拼接到上游请求中。如果上游是HTTP/1.1,还需要检查Host头是否被正确传递。一个常见的坑是Nginx的proxy_pass指令会让URI在重写时改变,所以在Lua里使用ngx.location.capture时,需要明确传入原始URI字符串,避免使用nil导致默认跳到当前location,从而产生404。
-- 保存原始URI,重试时直接使用
local original_uri = ngx.var.request_uri
ngx.ctx.original_uri = original_uri
-- 假设在某个逻辑分支里重试
local resp = ngx.location.capture(original_uri, {
method = ngx.HTTP_POST,
body = ngx.ctx.original_request_body,
ctx = ngx.ctx
})这里的关键是ngx.location.capture的第一个参数必须是完整的URI字符串,不能传nil。如果传nil,Nginx会认为是当前location,访问的路径可能变成内部跳转的默认路径,导致上游接收到错误的请求地址。验证方式是在上游日志里对比原始请求和重试请求的request_line,重点看query string是否一致。
建议的处理顺序:先明确重试边界,再用共享字典控制并发
重试不能无限做,也不能让多个worker同时重试同一个请求。Nginx是多worker进程模型,如果每个worker都在内存中独立保存重试状态,可能导致同一请求被多个worker同时重试,造成上游压力翻倍。建议使用lua_shared_dict分配一块共享字典,以请求唯一ID(可以由ngx.var.request_id生成)作为key,记录重试次数和时间戳。在准备重试前,先执行dict:add(key, 0, exptime=10)尝试加锁,如果返回nil说明已有其他worker在处理,则直接放弃重试并返回当前结果。注意加锁操作本身要设置过期时间,防止锁泄漏导致永久无法重试。释放锁时使用dict:delete,但要避免在release_phase无条件删除,否则可能误删其他worker的锁。
重试条件要控制在明确的响应码范围内,建议只对网络层错误(如超时、连接失败)和上游返回的5xx状态码进行重试,不要对4xx做重试,因为LLM网关的4xx通常是请求本身问题,重试也无效。同时需要设置最大重试次数,并加入抖动延迟。在Lua中可以通过ngx.sleep(0.05 * retry_count)实现逐步退避,但要注意sleep在content_by_lua阶段会阻塞worker,所以最好在access阶段使用ngx.thread.spawn配合ngx.socket.udp或tcpsock来实现非阻塞等待。更保守的做法是直接把重试次数上限设为2,并同时检查上游响应头中是否存在明确的限流标识,避免触发网关端的熔断。
-- 共享字典定义,可在nginx.conf http块中配置
lua_shared_dict retry_lock 10m;
-- access阶段实现加锁与重试计数
local dict = ngx.shared.retry_lock
local key = ngx.var.request_id
local ok = dict:add(key, 0, 10) -- 初始值0,10秒过期
if not ok then
-- 已有worker在处理,放弃重试
return ngx.exit(ngx.status)
end
dict:incr(key, 1) -- 重试次数+1
local retries = dict:get(key)这里需要注意,dict:add的过期时间要大于重试总耗时,否则锁提前释放后另一个worker又进来,造成重复重试。验证重试次数时,可以临时打印dict:get(key)的值,或者在上游访问日志里看到同一request_id出现多次。
验证方法:对比日志中的哈希和响应时间
记录重试日志时,除了常规的request_id、上游IP和响应码,还应该记录原始的body哈希值,以及重试前后的URI是否一致。可以在Lua中用ngx.md5(body)计算摘要,并配合log阶段输出。这样在复查问题时能快速区分是body被改动还是URI被改写。调试阶段,可以在lua环境中直接打印ngx.var.request_uri和body长度,但注意不能在生产环境输出完整body,以免泄露敏感信息。一种非侵入式的检查方法是对比第一次和第二次请求时的ngx.var.upstream_response_time,如果差异过大,则怀疑是上游缓存或负载均衡问题,而不是重试本身导致。
回滚和风险:保留原始请求体,必要时放弃重试
如果重试机制上线后出现异常,最直接的降级方式是把lua_shared_dict大小调小,或者直接注释掉重试逻辑,让Nginx恢复透传。风险点在于内存占用和上游压力。如果上游返回的body很大,重试前需要评估是否值得缓存。当LLM网关返回内容较大(如流式响应)时,重试机制需要更谨慎。如果上游已经部分返回了流式body,此时重试没有意义,因为客户端可能已经收到部分数据。因此,在进入重试流程前,先检查ngx.var.upstream_response_length是否大于0,或者通过ngx.var.upstream_response_status是否已空闲来判断是否已发起响应。若已发送响应体,则不再重试,直接返回错误。对于非流式场景,需要在Lua中临时保存响应body以便后续对比,但保存整个body可能消耗内存,所以建议只对小于可接受阈值(如2MB)的响应进行缓存,超过阈值则放弃重试,防止内存被单个大响应占满。
-- 在log或header_filter阶段判断是否已开始响应
if tonumber(ngx.var.upstream_response_length or 0) > 0 then
-- 已返回部分内容,不再重试
ngx.ctx.can_retry = false
end后续维护时,重点关注两个指标:重试成功率和重试原因分布。如果大量重试都集中在某几个上游IP,需要检查上游健康检查配置。如果重试后仍然5xx,不要继续调大重试次数,而是排查上游服务本身的状态。