接到这类「AI中转站密钥轮换」的队列任务需求,我一般会先确认两件事:一是当前密钥在什么条件下被认为失效,二是队列任务的重试策略和缓存设置有没有额外干扰。很多问题并不是出在轮换本身,而是判断条件写得太宽,把临时网络抖动也当成密钥失效。
先确认现象,再决定是否轮换
在队列任务中判断密钥是否该轮换,不能只依赖响应状态码。建议先检查返回的JSON体中是否包含特定的错误类型,例如令牌无效或额度耗尽。对于401和429这类状态码,可以定义成触发轮换的条件,但也要区分是网关返回的还是中转站返回的。如果只是偶发的网络抖动导致连接失败,直接轮换容易产生不必要的开销。因此,可以在任务里增加一个计数器,连续多次遇到同一密钥的错误才真正触发轮换。这样既避免误判,也减少了密钥管理的频繁变动。
判断连续多次的关键是“连续多次”的判定。我通常用Cache::increment来实现,每次错误给同一密钥加一,达到阈值再投递轮换任务;只要中间有一次正常响应,就清掉计数。这样能避开瞬时错误带来的误触发。
$count = Cache::increment('key_error:'.$keyId);
Cache::expire('key_error:'.$keyId, 300);
if ($count >= 3) {
Cache::forget('key_error:'.$keyId);
RotateKeyJob::dispatch($keyId)->onQueue('rotate');
}注意,计数器的过期时间要大于单次请求的耗时上限,我习惯设5到10分钟。如果队列任务本身会重试,要考虑计数器在多次重试中被重复累加,所以最好在任务里记录原始执行次数,或者直接用缓存锁保证同一时间只有一个轮换任务在跑。
把轮换动作隔离到独立队列
轮换操作往往涉及外部HTTP请求和数据库更新,如果和普通业务任务混在一起,容易互相阻塞。实现轮换时,可以在Laravel中创建一个RotateKeyJob,将其投递到独立的队列。在handle方法里,先从密钥表中取出当前密钥对应的记录,然后通过密钥管理服务申请一个新密钥。拿到新密钥后,不要立即覆盖旧记录,而是先保存为待验证状态。接着调用一次AI中转站的健康检查接口,确认新密钥有效后再更新记录中的密钥字段。如果验证失败,就删除暂存的新密钥并记录异常,保留旧密钥继续工作。整个操作可以放在DB::transaction中,防止出现半更新状态。
投递时我建议指定onQueue('rotate'),并在queue:work里单独起一个进程消费这个队列。这样即使轮换请求很慢,也不会拖慢发起AI请求的主链路任务。
class RotateKeyJob implements ShouldQueue
{
public function handle()
{
$record = KeyRecord::find($this->keyId);
if (! $record || $record->version !== $this->expectedVersion) {
// 已经被其他任务处理过,直接结束
return;
}
DB::beginTransaction();
try {
$newKey = KeyManager::requestNewKey();
$pending = KeyRecord::create([
'secret' => $newKey,
'status' => 'pending',
'version' => $record->version + 1,
'parent_id' => $record->id,
]);
if (! $this->checkNewKey($newKey)) {
$pending->delete();
Log::warning('新密钥验证失败', ['key_id' => $record->id]);
DB::commit();
return;
}
$record->status = 'retired';
$record->save();
$pending->status = 'active';
$pending->save();
Cache::forget('ai_key_current');
DB::commit();
} catch (\Throwable $e) {
DB::rollBack();
report($e);
}
}
}注意,DB::transaction 本身不提供互斥,这里还依赖后面的缓存锁。另外,checkNewKey 内部不能直接抛异常,要返回布尔值,否则事务会回滚,但暂存记录不会被删除,需要在catch里处理。
怎么验证新密钥确实可用
验证新密钥不能只看它能否创建,最好发送一个低成本的请求,比如列出模型或获取余额。在Laravel中可以用Http客户端发起GET请求,检查响应状态码和业务字段。有些中转站对新密钥有生效延迟,可能秒级或分钟级,所以验证任务里可以增加两到三次重试,每次间隔几秒。如果重试后仍然失败,就要考虑新密钥是否在生成时没有绑定正确的模型或权限。此时可以对比新旧密钥的权限元数据,确认差异后再决定是否回滚。
$response = Http::retry(3, 3000)->withToken($newKey)
->get($gatewayBaseUrl . '/v1/models');
if ($response->failed()) {
Log::info('新密钥健康检查失败,需要人工确认', [
'status' => $response->status(),
'body' => $response->json(),
]);
return false;
}
$data = $response->json();
return isset($data['data']) && is_array($data['data']);retry(3, 3000)这个参数是Laravel自带的HTTP重试,间隔3秒。如果中转站返回5xx,它也会自动重试。但要注意,如果返回401,重试没有意义,所以更稳妥的方式是根据响应状态码决定是否需要重试,比如只有429和5xx才重试。关键还是把临时失败和密钥本身失效分开。
并发轮换的锁和旧密钥平滑退出
轮换过程中的并发问题是很容易被忽略的隐患。如果多个任务同时检测到旧密钥失效并尝试轮换,就会产生多条新密钥,最后只保留一条,其余都浪费了。为避免这种情况,可以在轮换操作前使用Cache::lock或Redis锁,获取到锁的任务才能继续,没有获取到的就等待或放弃。另外,轮换时要考虑旧密钥的平滑退出,比如将新密钥写入配置后,让旧密钥在缓存中保留一小段时间,使得正在进行的请求不会突然中断。这样既保证连续性,也降低了切换时的失败率。
$lock = Cache::lock('rotate_key_lock:' . $keyId, 30);
if (! $lock->get()) {
return; // 另一个任务正在处理,主动退出
}
try {
// 这里执行完整的轮换流程
} finally {
$lock->release();
}锁的过期时间建议覆盖整个轮换流程的平均耗时,我一般设30秒,如果发现轮换任务经常超时,需要调大它。旧密钥平滑退出不需要写在任务里,可以在业务代码里设置一个双读逻辑:优先读取新密钥,读取失败时回退到旧密钥缓存,这个旧密钥缓存再保留10到30秒。
队列重试和缓存一致性的坑
队列任务默认失败后会自动重试,如果任务里包含了轮换逻辑,第二次执行时可能用旧密钥再去尝试轮换,而此时密钥已经换过了。解决办法是在任务开始时检查当前密钥的version或updated_at是否与任务传入的一致,如果不一致就直接返回。另外一个常见问题是密钥存储不一致,比如同时用了缓存和数据库,轮换时只更新了一处。建议以数据库为准,缓存只做读取优化,并在轮换后主动清理相关缓存键。
前面代码里我已经用了version字段检查,这个比较关键。它既能防止重复轮换,也能让你看到当前密钥是哪一轮生成的。轮换完成后,记得把旧密钥的status改为retired,但不要物理删除,方便回滚时找回。
回滚和后续维护
如果新密钥上线后不久发现异常,需要快速回滚。我通常不会直接改数据库,而是再创建一个轮换任务,把当前密钥标记为retired,同时把之前保留的旧密钥重新激活。前提是旧密钥没有被销毁,并且中转站仍然承认它。可以写一个简单的维护命令,允许指定版本号回退。
后续维护方面,建议每天扫一遍pending状态的密钥记录,这些是验证失败但没有清理的残留数据。还要检查队列日志里是否有重复轮换的记录,如果有,说明计数器或锁没有完全生效,需要补充监控。整个流程不用设计得太复杂,守住“验证成功才切换、锁保证只轮换一次、version防止重复执行”这三个边界,基本就够用了。