在给内网AI网关做反向代理时,上游模型API的Key失效往往来得比预期快,尤其是那些由第三方平台签发、带有有效期或配额上限的密钥。上游API网关的密钥失效是运维中常见故障,通常表现为上游返回401或403,而Nginx日志里只有access log中的状态码变化,没有明显的错误堆栈。若业务侧没有做重试或缓存熔断,用户会直接看到接口报错。此时若依赖人工登录上游控制台复制新Key,再修改Nginx配置文件并reload,整个过程少则几分钟,多则几小时,而且容易漏改环境变量或忘记同步到其他节点。因此,把密钥轮换纳入Nginx配置自动化流程,比等故障发生后再抢修更有实际意义。
在AI网关这种多上游的场景里,问题会更具体:一个网关可能同时转发多个模型供应商的请求,有的Key由业务方自己管理,有的Key来自统一安全平台,失效时间不统一。手动维护一份nginx.conf里的Authorization头,基本是在给自己留故障隐患。先做一件事:把Key从Nginx配置里拿出来。
先把密钥从配置里挪到独立文件
无论后面选哪种轮换方式,第一步都是避免在nginx.conf里写死Key。可以建一个目录,比如/etc/nginx/keys/,把每个上游的Key存成单独文件,并在Nginx配置里通过变量引用。这样做之后,轮换脚本只更新文件,不需要改Nginx主配置,也方便不同环境分发。
动态读取:让Nginx按需拿最新Key
如果密钥变化频繁,或者多个Nginx节点不方便同时reload,可以考虑动态读取。实现Nginx层密钥自动轮换,核心思路是让Nginx在每次发起上游请求时动态读取密钥,而不是在worker进程启动时固化到内存。做法是把API Key放在独立文件中,通过Nginx的js模块或lua模块在rewrite阶段读取该文件内容并设置请求头。配合外部定时任务,比如cron或systemd timer,定期拉取新密钥并原子替换文件,例如先写入临时文件再mv,避免Nginx读到半个文件。需要注意的是,Nginx worker进程对文件的缓存可能生效,频繁读取小文件时,建议在读取逻辑中加入mtime检查或使用短缓存时间,确保拿到的是最新值。
我这里用Lua模块做示例,适合已经有lua-nginx-module的环境。下面这个配置片段里,Nginx每隔5秒读一次密钥文件,存到共享字典,然后每个请求在rewrite阶段把Key放进Authorization头。
load_module modules/ndk_http_module.so;
load_module modules/ngx_http_lua_module.so;
lua_shared_dict auth_key 1m;
init_worker_by_lua_block {
local function load_key()
local f = io.open('/etc/nginx/keys/upstream_api_key', 'r')
if not f then return end
local key = f:read('*a'):gsub('%s+', '')
f:close()
ngx.shared.auth_key:set('key', key, 60)
end
load_key()
ngx.timer.every(5, load_key)
}
location /api/ {
rewrite_by_lua_block {
local key = ngx.shared.auth_key:get('key')
if not key then
ngx.log(ngx.ERR, 'api key missing')
ngx.exit(502)
end
ngx.req.set_header('Authorization', 'Bearer ' .. key)
}
proxy_pass http://upstream;
}
这里有几个要点:lua_shared_dict让多个worker进程共享同一份缓存;ngx.timer.every负责定时刷新;rewrite_by_lua_block在proxy_pass之前执行,确保上游收到的请求头是新的。如果Nginx没有Lua模块,也可以用NJS实现,思路一样。第一次配置完,先执行nginx -t,再看error log是否报模块加载错误。
轮换脚本:原子替换、备份和回滚
动态读取解决了“Nginx拿到新文件内容”的问题,但密钥文件本身得有人更新。通常用cron或systemd timer跑一个脚本。这个脚本必须做三件事:拉取新Key、原子替换、失败回滚。如果平台只允许手动导出,脚本也可以退化成“把导出的文件放到指定路径”。
#!/usr/bin/env bash
KEY_PATH=/etc/nginx/keys/upstream_api_key
TMP_PATH=${KEY_PATH}.tmp
BACKUP_PATH=${KEY_PATH}.$(date +%Y%m%d%H%M%S)
fetch_new_key > ${TMP_PATH}
chmod 600 ${TMP_PATH}
chown nginx:nginx ${TMP_PATH}
if [ ! -s ${TMP_PATH} ]; then
echo 'fetched key file is empty, abort' >&2
exit 1
fi
cp ${KEY_PATH} ${BACKUP_PATH}
mv ${TMP_PATH} ${KEY_PATH}
# 如果走静态 include 方案,执行下面两行;动态读取方案不需要。
nginx -t && nginx -s reload
脚本里的fetch_new_key是占位命令,实际环境可能是curl调用密钥管理接口,也可能从s3下载。关键是最后一步:替换文件后,动态读取方案不需要reload,保守的include方案则需要nginx -s reload。无论哪种,脚本执行后都要手动查一次文件内容、权限和属主,确认没有把换行符带进Key。记住,mv是同一文件系统内的原子操作,所以先写临时文件再mv,要比直接覆盖安全。
风险边界:双Key、重试和文件权限
自动轮换并非零风险,最常见的坑是密钥更新延迟导致部分请求使用旧Key。若上游在旧Key失效后立即拒绝,而Nginx本地缓存尚未过期,会出现间歇性401。解决办法是让密钥文件内容包含新旧两个Key,请求时先尝试新Key,收到401后再用旧Key重试一次,或者让Nginx在上游返回401时主动重新读取文件。另一种风险是文件权限过宽,密钥被其他系统用户读取,建议将密钥文件属主设为nginx运行用户,权限设为600,并定期审计文件内容是否意外包含换行或残留字符,这类问题往往导致请求头格式错误,排查起来比401更隐蔽。
在AI网关里,我建议把双Key方案放在评估列表里。大多数模型API的Key都是“新Key生效后旧Key会有几分钟到几小时的宽限期”,可以利用这个时间窗做平滑切换。如果上游不保留宽限期,那就要在Nginx侧处理401重试,或者接受短暂报错。重试逻辑不要无限制循环,最多试一次旧Key,同时把日志打到独立文件,方便事后确认是哪个Key造成的。
怎么确认轮换真的生效
验证不能只靠nginx -t通过。最直接的办法是在Nginx里临时加一个内部接口,返回当前共享字典里的Key值,用curl确认文件更新后,Nginx读到的是新值。
location = /debug_auth {
allow 127.0.0.1;
deny all;
content_by_lua_block {
ngx.say(ngx.shared.auth_key:get('key') or 'no key')
}
}
curl -s http://127.0.0.1/debug_auth
这个debug接口不要暴露到公网,用allow/deny限制本机访问。如果curl返回的Key和文件内容一致,说明读取和缓存逻辑正常;如果发现旧值,优先检查timer是否还在跑、共享字典过期时间、Nginx错误日志。更进一步,在测试环境用mock upstream打印接收到的Authorization头,确认请求头格式没有多余空格或换行,再切生产。