改善 OpenAI 的故障转移机制

[gsh123china]

OpenAI 故障转移机制

概述

OpenAI接口现已实现完整的故障转移机制，参照Claude接口的设计模式，支持自动错误计数、临时禁用和自动恢复功能。

核心功能

1. 请求成功判定

• 成功状态码: 2xx、304、307
• 失败状态码: 除上述外的所有状态码（含4xx、5xx及非白名单3xx）

2. 错误计数机制

• 在指定时间窗口内统计失败请求次数
• 达到阈值后自动触发临时禁用
• 成功请求立即清零错误计数

3. 临时禁用

• 使用Redis TTL自动管理禁用时长
• 防止并发触发（分布式锁保护）
• 禁用期间账户不参与调度

4. 自动恢复

• 基于Redis过期机制自动恢复
• 定期清理服务确保及时恢复
• 恢复后自动发送Webhook通知

配置参数

环境变量配置（.env文件）：

# OpenAI 故障转移配置
OPENAI_ERROR_THRESHOLD=10          # 触发禁用的失败次数阈值（默认10）
OPENAI_ERROR_WINDOW_MINUTES=5      # 错误计数时间窗口（分钟，默认5）
OPENAI_TEMP_DISABLE_MINUTES=5      # 临时禁用持续时长（分钟，默认5）

架构设计

请求流程:

1. 请求到达 → 判断状态码
2. 成功(2xx/304/307) → 清除错误计数
3. 失败(其他) → 记录错误 → 检查阈值
4. 达到阈值 → 标记temp_error → 设置Redis TTL
5. TTL过期 → 清理服务检测 → 自动恢复账户

单体测试

./scripts/quick-test-failover.sh

这个脚本会：

• 自动检查前置条件（Redis、配置文件）
• 创建测试账户（如果需要）
• 运行完整测试并清理数据

测试内容包括：

• 错误计数累加
• 阈值触发禁用
• 并发控制验证
• Redis TTL检查
• 手动恢复测试

支持的账户类型

本故障转移机制覆盖以下类型：

• openai（通用 OpenAI 账户，后端直连 ChatGPT Codex 接口）
• openai-responses（第三方 OpenAI Responses 兼容账户）

两者共享同一组配置（OPENAI_ERROR_THRESHOLD、OPENAI_ERROR_WINDOW_MINUTES、OPENAI_TEMP_DISABLE_MINUTES），但使用独立的 Redis 命名空间，互不影响。

Redis Key 命名

• OpenAI: openai_account:request_errors:{id}、openai_account:temp_error:{id}、openai_account:temp_error:lock:{id}
• OpenAI-Responses: openai_responses_account:request_errors:{id}、openai_responses_account:temp_error:{id}、openai_responses_account:temp_error:lock:{id}

相关文件

• /src/routes/openaiRoutes.js - 路由层错误处理
• /src/services/openaiAccountService.js - 故障转移核心逻辑
• /src/services/openaiCleanupService.js - 定期清理服务（并行处理 openai 与 openai-responses）
• /src/services/rateLimitCleanupService.js - 限流清理服务
• /scripts/quick-test-failover.sh - 快速测试脚本(调用手动测试脚本)
• /scripts/test-openai-failover.js - 手动测试脚本 for openai
• /scripts/test-openai-responses-failover.js - 手动测试脚本 for openai-responses