利用Lua脚本在OpenResty中实现AI中转站密钥的定时轮换

文章导读
先说明一个适用边界:下面这套做法适合密钥来源于统一配置源、并且上游允许短时间新旧密钥并存的中转场景。如果上游接口一旦发现旧密钥失效就立刻拒绝请求,没有缓冲余地,那单纯做定时轮换还不够,需要把“上游侧分发状态”和“本地切换状态”拆开观察,否则很容易出现切换成功了但业务侧依然报鉴权错误的情况。我建议先明确当前失败是本地密钥过期,还是上游还没把新密钥分发到所有节点,再决定要加锁、加缓冲还是直接缩短轮换周
📋 目录
  1. 一 轮换需求与总体方案
  2. 二 更新操作与缓冲窗口
  3. 三 并发更新与互斥控制
  4. 四 检查轮换是否生效
  5. 五 容易忽视的坑
A A

先说明一个适用边界:下面这套做法适合密钥来源于统一配置源、并且上游允许短时间新旧密钥并存的中转场景。如果上游接口一旦发现旧密钥失效就立刻拒绝请求,没有缓冲余地,那单纯做定时轮换还不够,需要把“上游侧分发状态”和“本地切换状态”拆开观察,否则很容易出现切换成功了但业务侧依然报鉴权错误的情况。我建议先明确当前失败是本地密钥过期,还是上游还没把新密钥分发到所有节点,再决定要加锁、加缓冲还是直接缩短轮换周期。

轮换需求与总体方案

在AI中转服务中,上游平台分配的API密钥往往带有有效期或存在被探测的风险,手动更换密钥不仅耗时,还容易漏掉某个实例。利用OpenResty的Lua环境,可以在服务启动阶段注册一个定时器,定期从配置中心或本地加密文件拉取密钥,并更新到共享内存中,使得所有工作进程在同一周期内完成切换。这种做法的好处是无需停服,也无需修改请求处理代码,只要在Lua脚本里维护好密钥的当前值与过期时间即可。

先说总体流程:一个init_worker阶段注册的定时器,每隔N秒读取一次密钥源,比较版本号,如果版本号发生变化,就更新共享内存和过期时间。请求进来时,通过access阶段读取共享内存中的密钥,拼接鉴权头后传给上游。这里的关键是,共享内存里至少要有两个字段:当前密钥和上一个密钥,否则过渡期间回退无从谈起。

-- nginx.conf中http段或conf.d中配置
lua_shared_dict ai_keys 10m;

-- init_worker.lua
local function rotate()
    local dict = ngx.shared.ai_keys
    -- 从配置文件或配置中心获取新密钥,此处仅示意
    local ok, new_key = fetch_latest_key()
    if not ok then
        ngx.log(ngx.WARN, "fetch key failed, keep old key")
        return
    end
    -- 把新密钥放到暂存字段,等待过渡期
    dict:set("pending_key", new_key)
    dict:set("pending_time", ngx.now())
end

local timer = ngx.timer.every
-- 通常设置30秒到5分钟,避免太频繁
local handle, err = timer(30, rotate)
if handle == nil then
    ngx.log(ngx.ERR, "failed to create timer: ", err)
end

这里有个容易被忽略的动作:fetch_latest_key必须返回两个东西,一个是密钥本身,另一个是密钥的版本号或过期时间。不能只比较内容是否变化,因为相同密钥内容可能对应不同的签名规则,版本号是判断“是否真的需要轮换”的唯一可靠依据。可以先让配置源生成一个简单的递增序号,本地记录上一次处理过的序号,只有序号变化才进入后续更新流程。

更新操作与缓冲窗口

轮换操作本身并不复杂,但要注意更新过程中的请求一致性。先定义一个共享字典存放密钥,然后在定时器回调中获取新密钥,将其写入另一个字段,并设置短暂的过渡时间。在这段时间内,请求优先使用新密钥,若失败则回退到旧密钥,从而避免因上游尚未完全接受新密钥而导致的临时故障。当过渡期结束后,再删除旧密钥,完成整个轮换过程。这样既保证了切换平滑,也给上游分发密钥留下一点缓冲余地。

实现时要注意过渡期并不是越长越好。跨机房部署时,上游节点可能按分钟粒度拉取密钥,太短的过渡期可能不够;但过渡期过长,旧密钥回收不及时,万一旧密钥泄露,风险窗口也会拉长。我的建议是先取30到60秒,观察日志中“回退到旧密钥”这条记录的出现频率,如果频繁出现,说明上游分发有滞后,适当加长到120秒;如果几乎不出现,可以稳定在30秒。

-- access.lua 中请求处理阶段的读取逻辑
local dict = ngx.shared.ai_keys
local current = dict:get("current_key")
local pending = dict:get("pending_key")
local pending_time = dict:get("pending_time") or 0
local transition_end = pending_time + 60  -- 过渡窗口60秒

local use_key
if pending and ngx.now() < transition_end then
    use_key = pending
else
    use_key = current
end

ngx.req.set_header("Authorization", "Bearer " .. use_key)

注意,这个缓冲逻辑依赖前端能够感知请求失败。通常做法是:先用新密钥发起上游请求,如果收到401或403,再在Lua层重新设置旧密钥并重放一次。但重放必须保证请求体可以重复读取,否则只能对幂等请求做重试。一个更保守的办法是干脆不重放,只在失败时记录一条日志,表明过渡期里新密钥尚未被上游接受,等下一个轮换周期再调整。直接重放GET请求问题不大,POST请求就要谨慎。

并发更新与互斥控制

OpenResty的每个worker进程都有一套独立的Lua环境,但共享内存是全局的。如果每个worker都启动自己的定时器,可能同时执行轮换,造成新密钥互相覆盖。需要在轮换函数开头加一个互斥锁,比如使用lua-resty-lock或shared字典的add操作,先尝试加锁,只有成功的进程才真正更新密钥,其他进程只读取结果。另外,考虑到配置源可能有多次变更,还要记录一个轮换序号,确保每次更新都是基于最新状态,而不是把停用密钥重新写入。

我倾向于用shared字典的add方法做简易锁,因为不需要额外引入resty.lock的依赖。锁的key可以叫rotate_lock,value存进程ID或时间戳,过期时间设为定时器间隔的两倍即可。抢锁失败时,当前worker直接跳过这次轮换,等待下一个周期,不要用循环重试,因为多个worker同时循环重试反而更容易把shared字典的写锁占满。

-- 简易互锁示例
local dict = ngx.shared.ai_keys
-- 只有第一个add成功的进程才继续执行轮换
local ok, err = dict:add("rotate_lock", ngx.worker.pid(), 60)
if not ok then
    -- 其他进程直接返回,等下一轮
    return
end

local seq = dict:get("rotate_seq") or 0
local new_seq = fetch_remote_seq()
if new_seq and new_seq > seq then
    local key = fetch_latest_key()
    -- 先写pending,再在下一个定时器逻辑里把pending提升为current
    dict:set("pending_key", key)
    dict:set("rotate_seq", new_seq)
end
-- 无需手动释放,锁到期自动消失

这段代码里没有显式释放锁,原因有两个:一是避免一个进程成功更新后马上释放,而另一个慢worker刚拿到锁又重复写一次;二是锁过期后自然让位给下一个周期,这样反而能把轮换频率稳定住。如果确实需要更快的锁释放,可以单独记录锁的所有者,只有同一个PID才能删除锁,但这样做属于优化项,初期不必加。

检查轮换是否生效

轮换是否生效,主要看两件事:一是共享字典里的密钥指纹是否按时变化,二是旧密钥是否在预期时间被回收。可以在定时器回调里记录日志,包含时间戳和密钥哈希,但绝不能输出明文密钥。如果需要更主动的监控,可以单独设置一个内网调试接口,返回当前密钥的指纹和最近一次轮换时间,供测试脚本或人工检查。当连续周期没有成功更新时,应触发告警,并保留上一次的有效密钥,而不是直接置空,避免服务中断。

这个内网调试接口不能暴露到公网,至少要限制在内网IP或绑到回环地址。返回内容不必包含完整密钥,展示哈希摘要即可。我常用的是先取密钥字符串,再计算SHA1或SHA256,然后取前16位作为指纹。

# nginx.conf中定义内网调试接口
location = /internal/key_status {
    allow 127.0.0.1;
    allow 10.0.0.0/8;
    deny all;
    content_by_lua_block {
        local dict = ngx.shared.ai_keys
        local current = dict:get("current_key") or ""
        local pending = dict:get("pending_key") or ""
        local rotate_time = dict:get("rotate_time") or 0
        local fingerprint = require("resty.sha1"):new()
        -- 实际计算需要配合resty.string,这里只做示意
        ngx.say("rotate_time: ", rotate_time)
        ngx.say("current_key_fp: ", fingerprint)
        ngx.say("pending_key_fp: ", pending ~= "" and fingerprint or "none")
        ngx.say("seq: ", dict:get("rotate_seq") or 0)
    }
}

验证时,先手动修改配置源里的密钥,等一个轮换周期后访问这个接口,观察指纹和轮换时间是否更新。如果指纹没有变化,优先检查锁是否一直被某个worker占用。如果指纹变化了但请求仍然报鉴权失败,再查过渡期是否太短,以及上游是否支持旧密钥短时间续用。这里的排查顺序很重要:先确认本地确实更新了,再查上游,不要一上来就改定时器间隔。

容易忽视的坑

定时器回调中不能使用依赖请求上下文的API,例如ngx.req、ngx.say、ngx.exit等,否则会报错,因为此时没有正在处理的请求。如果想记录日志,可以用ngx.log,但要注意日志级别。另一个坑是共享内存的大小默认值可能不够用,因为密钥密文可能很长,还要保存历史密钥和序号,如果空间不足,写入操作会静默失败,因此要在配置中预估并预留足够的内存。此外,定时器的最小间隔受OpenResty的timer_nr和运行频率限制,不要设置过小,以免无谓消耗CPU。

共享内存写入失败时,shared字典的set方法会返回nil和err信息,但很多人只做了简单判断,甚至完全不判断。如果写入失败,旧密钥还在,服务不一定报错,但轮换就失效了。建议在每次update后检查返回值,并且把shared内存使用量记录到日志里。另一种容易踩的坑是定时器回调里使用了全局变量来保存密钥状态,这在不同worker下不互通,必须用shared字典,不能只用Lua的模块级变量。

再补充一个和定时器并发相关的点:如果同一个OpenResty实例里还有其他业务定时器,尽量把轮换定时器的执行时间错开,避免所有worker在整点同时抢锁。虽然锁能解决覆盖问题,但大量worker同时抢锁会短暂阻塞shared字典的其他读写。可以先给每个worker分配一个随机偏移,比如让每个worker等random(0, 5)秒后再启动第一个定时器,后续周期再统一。

最后,轮换逻辑上线前,可以做一次手动模拟:把配置源的时间戳改到未来,触发一次轮换,观察日志里的指纹变化和请求成功率。回滚时只需要把配置源恢复成原来的密钥,等下一个轮换周期就会自动把旧密钥重新写回,不需要重启Nginx。但如果共享内存里的序号逻辑处理不当,也可能出现旧密钥被当成新配置重复写入,所以要记住:每次轮换都必须更新序号,并且比较序号之前先判断配置源是否真的返回了新内容。