chore: sync VERSION file with release v1.1.236 [skip ci]

feat: Claude账户定时测试功能

.env.example

@@ -61,6 +61,9 @@ PROXY_USE_IPV4=true
 # ⏱️ 请求超时配置
 REQUEST_TIMEOUT=600000  # 请求超时设置（毫秒），默认10分钟
 
+# 🔧 请求体大小配置
+REQUEST_MAX_SIZE_MB=60
+
 # 📈 使用限制
 DEFAULT_TOKEN_LIMIT=1000000
 
@@ -75,6 +78,8 @@ TOKEN_USAGE_RETENTION=2592000000
 HEALTH_CHECK_INTERVAL=60000
 TIMEZONE_OFFSET=8  # UTC偏移小时数，默认+8（中国时区）
 METRICS_WINDOW=5  # 实时指标统计窗口（分钟），可选1-60，默认5分钟
+# 启动时清理残留的并发排队计数器（默认true，多实例部署时建议设为false）
+CLEAR_CONCURRENCY_QUEUES_ON_STARTUP=true
 
 # 🎨 Web 界面配置
 WEB_TITLE=Claude Relay Service

.gitignore

@@ -26,6 +26,7 @@ redis_data/
 
 # Logs directory
 logs/
+logs1/
 *.log
 startup.log
 app.log

CLAUDE.md

@@ -22,6 +22,7 @@ Claude Relay Service 是一个多平台 AI API 中转服务，支持 **Claude (
 - **权限控制**: API Key支持权限配置（all/claude/gemini/openai等），控制可访问的服务类型
 - **客户端限制**: 基于User-Agent的客户端识别和限制，支持ClaudeCode、Gemini-CLI等预定义客户端
 - **模型黑名单**: 支持API Key级别的模型访问限制
+- **并发请求排队**: 当API Key并发数超限时，请求进入队列等待而非立即返回429，支持配置最大排队数、超时时间，适用于Claude Code Agent并行工具调用场景
 
 ### 主要服务组件
 
@@ -60,6 +61,7 @@ Claude Relay Service 是一个多平台 AI API 中转服务，支持 **Claude (
 
 - **apiKeyService.js**: API Key管理，验证、限流、使用统计、成本计算
 - **userService.js**: 用户管理系统，支持用户注册、登录、API Key管理
+- **userMessageQueueService.js**: 用户消息串行队列，防止同账户并发用户消息触发限流
 - **pricingService.js**: 定价服务，模型价格管理和成本计算
 - **costInitService.js**: 成本数据初始化服务
 - **webhookService.js**: Webhook通知服务
@@ -185,12 +187,17 @@ npm run service:stop          # 停止服务
 - `CLAUDE_OVERLOAD_HANDLING_MINUTES`: Claude 529错误处理持续时间（分钟，0表示禁用）
 - `STICKY_SESSION_TTL_HOURS`: 粘性会话TTL（小时，默认1）
 - `STICKY_SESSION_RENEWAL_THRESHOLD_MINUTES`: 粘性会话续期阈值（分钟，默认0）
+- `USER_MESSAGE_QUEUE_ENABLED`: 启用用户消息串行队列（默认false）
+- `USER_MESSAGE_QUEUE_DELAY_MS`: 用户消息请求间隔（毫秒，默认200）
+- `USER_MESSAGE_QUEUE_TIMEOUT_MS`: 队列等待超时（毫秒，默认5000，锁持有时间短无需长等待）
+- `USER_MESSAGE_QUEUE_LOCK_TTL_MS`: 锁TTL（毫秒，默认5000，请求发送后立即释放无需长TTL）
 - `METRICS_WINDOW`: 实时指标统计窗口（分钟，1-60，默认5）
 - `MAX_API_KEYS_PER_USER`: 每用户最大API Key数量（默认1）
 - `ALLOW_USER_DELETE_API_KEYS`: 允许用户删除自己的API Keys（默认false）
 - `DEBUG_HTTP_TRAFFIC`: 启用HTTP请求/响应调试日志（默认false，仅开发环境）
 - `PROXY_USE_IPV4`: 代理使用IPv4（默认true）
 - `REQUEST_TIMEOUT`: 请求超时时间（毫秒，默认600000即10分钟）
+- `CLEAR_CONCURRENCY_QUEUES_ON_STARTUP`: 启动时清理残留的并发排队计数器（默认true，多实例部署时建议设为false）
 
 #### AWS Bedrock配置（可选）
 - `CLAUDE_CODE_USE_BEDROCK`: 启用Bedrock（设置为1启用）
@@ -337,6 +344,35 @@ npm run setup  # 自动生成密钥并创建管理员账户
 11. **速率限制未清理**: rateLimitCleanupService每5分钟自动清理过期限流状态
 12. **成本统计不准确**: 运行 `npm run init:costs` 初始化成本数据，检查pricingService是否正确加载模型价格
 13. **缓存命中率低**: 查看缓存监控统计，调整LRU缓存大小配置
+14. **用户消息队列超时**: 优化后锁持有时间已从分钟级降到毫秒级（请求发送后立即释放），默认 `USER_MESSAGE_QUEUE_TIMEOUT_MS=5000` 已足够。如仍有超时，检查网络延迟或禁用此功能（`USER_MESSAGE_QUEUE_ENABLED=false`）
+15. **并发请求排队问题**:
+   - 排队超时：检查 `concurrentRequestQueueTimeoutMs` 配置是否合理（默认10秒）
+   - 排队数过多：调整 `concurrentRequestQueueMaxSize` 和 `concurrentRequestQueueMaxSizeMultiplier`
+   - 查看排队统计：访问 `/admin/concurrency-queue/stats` 接口查看 entered/success/timeout/cancelled/socket_changed/rejected_overload 统计
+   - 排队计数泄漏：系统重启时自动清理，或访问 `/admin/concurrency-queue` DELETE 接口手动清理
+   - Socket 身份验证失败：查看 `socket_changed` 统计，如果频繁发生，检查代理配置或客户端连接稳定性
+   - 健康检查拒绝：查看 `rejected_overload` 统计，表示队列过载时的快速失败次数
+
+### 代理配置要求（并发请求排队）
+
+使用并发请求排队功能时，需要正确配置代理（如 Nginx）的超时参数：
+
+- **推荐配置**: `proxy_read_timeout >= max(2 × concurrentRequestQueueTimeoutMs, 60s)`
+  - 当前默认排队超时 10 秒，Nginx 默认 `proxy_read_timeout = 60s` 已满足要求
+  - 如果调整排队超时到 60 秒，推荐代理超时 ≥ 120 秒
+- **Nginx 配置示例**:
+  ```nginx
+  location /api/ {
+      proxy_read_timeout 120s;  # 排队超时 60s 时推荐 120s
+      proxy_connect_timeout 10s;
+      # ...其他配置
+  }
+  ```
+- **企业防火墙环境**:
+  - 某些企业防火墙可能静默关闭长时间无数据的连接（20-40 秒）
+  - 如遇此问题，联系网络管理员调整空闲连接超时策略
+  - 或降低 `concurrentRequestQueueTimeoutMs` 配置
+- **后续升级说明**: 如有需要，后续版本可能提供可选的轻量级心跳机制
 
 ### 调试工具
 
@@ -449,6 +485,15 @@ npm run setup  # 自动生成密钥并创建管理员账户
 - **缓存优化**: 多层LRU缓存（解密缓存、账户缓存），全局缓存监控和统计
 - **成本追踪**: 实时token使用统计（input/output/cache_create/cache_read）和成本计算（基于pricingService）
 - **并发控制**: Redis Sorted Set实现的并发计数，支持自动过期清理
+- **并发请求排队**: 当API Key并发超限时，请求进入队列等待而非直接返回429
+  - **工作原理**: 采用「先占后检查」模式，每次轮询尝试占位，超限则释放继续等待
+  - **指数退避**: 初始200ms，指数增长至最大2秒，带±20%抖动防惊群效应
+  - **智能清理**: 排队计数有TTL保护（超时+30秒），进程崩溃也能自动清理
+  - **Socket身份验证**: 使用UUID token + socket对象引用双重验证，避免HTTP Keep-Alive连接复用导致的身份混淆
+  - **健康检查**: P90等待时间超过阈值时快速失败（返回429），避免新请求在过载时继续排队
+  - **配置参数**: `concurrentRequestQueueEnabled`（默认false）、`concurrentRequestQueueMaxSize`（默认3）、`concurrentRequestQueueMaxSizeMultiplier`（默认0）、`concurrentRequestQueueTimeoutMs`（默认10秒）、`concurrentRequestQueueMaxRedisFailCount`（默认5）、`concurrentRequestQueueHealthCheckEnabled`（默认true）、`concurrentRequestQueueHealthThreshold`（默认0.8）
+  - **最大排队数**: max(固定值, 并发限制×倍数)，例如并发限制=10、倍数=2时最大排队数=20
+  - **适用场景**: Claude Code Agent并行工具调用、批量请求处理
 - **客户端识别**: 基于User-Agent的客户端限制，支持预定义客户端（ClaudeCode、Gemini-CLI等）
 - **错误处理**: 529错误自动标记账户过载状态，配置时长内自动排除该账户
 
@@ -508,8 +553,16 @@ npm run setup  # 自动生成密钥并创建管理员账户
   - `overload:{accountId}` - 账户过载状态（529错误）
 - **并发控制**:
   - `concurrency:{accountId}` - Redis Sorted Set实现的并发计数
+- **并发请求排队**:
+  - `concurrency:queue:{apiKeyId}` - API Key级别的排队计数器（TTL由 `concurrentRequestQueueTimeoutMs` + 30秒缓冲决定）
+  - `concurrency:queue:stats:{apiKeyId}` - 排队统计（entered/success/timeout/cancelled）
+  - `concurrency:queue:wait_times:{apiKeyId}` - 按API Key的等待时间记录（用于P50/P90/P99计算）
+  - `concurrency:queue:wait_times:global` - 全局等待时间记录
 - **Webhook配置**:
   - `webhook_config:{id}` - Webhook配置
+- **用户消息队列**:
+  - `user_msg_queue_lock:{accountId}` - 用户消息队列锁（当前持有者requestId）
+  - `user_msg_queue_last:{accountId}` - 上次请求完成时间戳（用于延迟计算）
 - **系统信息**:
   - `system_info` - 系统状态缓存
   - `model_pricing` - 模型价格数据（pricingService）

Dockerfile

@@ -1,4 +1,17 @@
-# 🎯 前端构建阶段
+# 🎯 后端依赖阶段 (与前端构建并行)
+FROM node:18-alpine AS backend-deps
+
+# 📁 设置工作目录
+WORKDIR /app
+
+# 📦 复制 package 文件
+COPY package*.json ./
+
+# 🔽 安装依赖 (生产环境) - 使用 BuildKit 缓存加速
+RUN --mount=type=cache,target=/root/.npm \
+    npm ci --only=production
+
+# 🎯 前端构建阶段 (与后端依赖并行)
 FROM node:18-alpine AS frontend-builder
 
 # 📁 设置工作目录
@@ -7,8 +20,9 @@ WORKDIR /app/web/admin-spa
 # 📦 复制前端依赖文件
 COPY web/admin-spa/package*.json ./
 
-# 🔽 安装前端依赖
+# 🔽 安装前端依赖 - 使用 BuildKit 缓存加速
-RUN npm ci
+RUN --mount=type=cache,target=/root/.npm \
+    npm ci
 
 # 📋 复制前端源代码
 COPY web/admin-spa/ ./
@@ -34,17 +48,16 @@ RUN apk add --no-cache \
 # 📁 设置工作目录
 WORKDIR /app
 
-# 📦 复制 package 文件
+# 📦 复制 package 文件 (用于版本信息等)
 COPY package*.json ./
 
-# 🔽 安装依赖 (生产环境)
+# 📦 从后端依赖阶段复制 node_modules (已预装好)
-RUN npm ci --only=production && \
+COPY --from=backend-deps /app/node_modules ./node_modules
-    npm cache clean --force
 
 # 📋 复制应用代码
 COPY . .
 
-# 📦 从构建阶段复制前端产物
+# 📦 从前端构建阶段复制前端产物
 COPY --from=frontend-builder /app/web/admin-spa/dist /app/web/admin-spa/dist
 
 # 🔧 复制并设置启动脚本权限

VERSION

@@ -1 +1 @@
-1.1.221
+1.1.236

config/config.example.js

@@ -203,6 +203,15 @@ const config = {
   development: {
     debug: process.env.DEBUG === 'true',
     hotReload: process.env.HOT_RELOAD === 'true'
+  },
+
+  // 📬 用户消息队列配置
+  // 优化说明：锁在请求发送成功后立即释放（而非请求完成后），因为 Claude API 限流基于请求发送时刻计算
+  userMessageQueue: {
+    enabled: process.env.USER_MESSAGE_QUEUE_ENABLED === 'true', // 默认关闭
+    delayMs: parseInt(process.env.USER_MESSAGE_QUEUE_DELAY_MS) || 200, // 请求间隔（毫秒）
+    timeoutMs: parseInt(process.env.USER_MESSAGE_QUEUE_TIMEOUT_MS) || 5000, // 队列等待超时（毫秒），锁持有时间短，无需长等待
+    lockTtlMs: parseInt(process.env.USER_MESSAGE_QUEUE_LOCK_TTL_MS) || 5000 // 锁TTL（毫秒），5秒足以覆盖请求发送
   }
 }
 

docker-compose.yml

@@ -21,6 +21,9 @@ services:
       - PORT=3000
       - HOST=0.0.0.0
       
+      # 🔧 请求体大小配置
+      - REQUEST_MAX_SIZE_MB=60
+      
       # 🔐 安全配置（必填）
       - JWT_SECRET=${JWT_SECRET}  # 必填：至少32字符的随机字符串
       - ENCRYPTION_KEY=${ENCRYPTION_KEY}  # 必填：32字符的加密密钥

package-lock.json

@@ -26,6 +26,7 @@
         "ioredis": "^5.3.2",
         "ldapjs": "^3.0.7",
         "morgan": "^1.10.0",
+        "node-cron": "^4.2.1",
         "nodemailer": "^7.0.6",
         "ora": "^5.4.1",
         "rate-limiter-flexible": "^5.0.5",
@@ -44,6 +45,7 @@
         "jest": "^29.7.0",
         "nodemon": "^3.0.1",
         "prettier": "^3.6.2",
+        "prettier-plugin-tailwindcss": "^0.7.2",
         "supertest": "^6.3.3"
       },
       "engines": {
@@ -7027,6 +7029,15 @@
         "node": ">= 0.6"
       }
     },
+    "node_modules/node-cron": {
+      "version": "4.2.1",
+      "resolved": "https://registry.npmmirror.com/node-cron/-/node-cron-4.2.1.tgz",
+      "integrity": "sha512-lgimEHPE/QDgFlywTd8yTR61ptugX3Qer29efeyWw2rv259HtGBNn1vZVmp8lB9uo9wC0t/AT4iGqXxia+CJFg==",
+      "license": "ISC",
+      "engines": {
+        "node": ">=6.0.0"
+      }
+    },
     "node_modules/node-domexception": {
       "version": "1.0.0",
       "resolved": "https://registry.npmmirror.com/node-domexception/-/node-domexception-1.0.0.tgz",
@@ -7598,6 +7609,85 @@
         "node": ">=6.0.0"
       }
     },
+    "node_modules/prettier-plugin-tailwindcss": {
+      "version": "0.7.2",
+      "resolved": "https://registry.npmjs.org/prettier-plugin-tailwindcss/-/prettier-plugin-tailwindcss-0.7.2.tgz",
+      "integrity": "sha512-LkphyK3Fw+q2HdMOoiEHWf93fNtYJwfamoKPl7UwtjFQdei/iIBoX11G6j706FzN3ymX9mPVi97qIY8328vdnA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=20.19"
+      },
+      "peerDependencies": {
+        "@ianvs/prettier-plugin-sort-imports": "*",
+        "@prettier/plugin-hermes": "*",
+        "@prettier/plugin-oxc": "*",
+        "@prettier/plugin-pug": "*",
+        "@shopify/prettier-plugin-liquid": "*",
+        "@trivago/prettier-plugin-sort-imports": "*",
+        "@zackad/prettier-plugin-twig": "*",
+        "prettier": "^3.0",
+        "prettier-plugin-astro": "*",
+        "prettier-plugin-css-order": "*",
+        "prettier-plugin-jsdoc": "*",
+        "prettier-plugin-marko": "*",
+        "prettier-plugin-multiline-arrays": "*",
+        "prettier-plugin-organize-attributes": "*",
+        "prettier-plugin-organize-imports": "*",
+        "prettier-plugin-sort-imports": "*",
+        "prettier-plugin-svelte": "*"
+      },
+      "peerDependenciesMeta": {
+        "@ianvs/prettier-plugin-sort-imports": {
+          "optional": true
+        },
+        "@prettier/plugin-hermes": {
+          "optional": true
+        },
+        "@prettier/plugin-oxc": {
+          "optional": true
+        },
+        "@prettier/plugin-pug": {
+          "optional": true
+        },
+        "@shopify/prettier-plugin-liquid": {
+          "optional": true
+        },
+        "@trivago/prettier-plugin-sort-imports": {
+          "optional": true
+        },
+        "@zackad/prettier-plugin-twig": {
+          "optional": true
+        },
+        "prettier-plugin-astro": {
+          "optional": true
+        },
+        "prettier-plugin-css-order": {
+          "optional": true
+        },
+        "prettier-plugin-jsdoc": {
+          "optional": true
+        },
+        "prettier-plugin-marko": {
+          "optional": true
+        },
+        "prettier-plugin-multiline-arrays": {
+          "optional": true
+        },
+        "prettier-plugin-organize-attributes": {
+          "optional": true
+        },
+        "prettier-plugin-organize-imports": {
+          "optional": true
+        },
+        "prettier-plugin-sort-imports": {
+          "optional": true
+        },
+        "prettier-plugin-svelte": {
+          "optional": true
+        }
+      }
+    },
     "node_modules/pretty-format": {
       "version": "29.7.0",
       "resolved": "https://registry.npmmirror.com/pretty-format/-/pretty-format-29.7.0.tgz",

package.json

@@ -65,6 +65,7 @@
     "ioredis": "^5.3.2",
     "ldapjs": "^3.0.7",
     "morgan": "^1.10.0",
+    "node-cron": "^4.2.1",
     "nodemailer": "^7.0.6",
     "ora": "^5.4.1",
     "rate-limiter-flexible": "^5.0.5",
@@ -83,6 +84,7 @@
     "jest": "^29.7.0",
     "nodemon": "^3.0.1",
     "prettier": "^3.6.2",
+    "prettier-plugin-tailwindcss": "^0.7.2",
     "supertest": "^6.3.3"
   },
   "engines": {

pnpm-lock.yaml

@@ -59,6 +59,9 @@ importers:
       morgan:
         specifier: ^1.10.0
         version: 1.10.1
+      node-cron:
+        specifier: ^4.2.1
+        version: 4.2.1
       nodemailer:
         specifier: ^7.0.6
         version: 7.0.11
@@ -108,6 +111,9 @@ importers:
       prettier:
         specifier: ^3.6.2
         version: 3.7.4
+      prettier-plugin-tailwindcss:
+        specifier: ^0.7.2
+        version: 0.7.2(prettier@3.7.4)
       supertest:
         specifier: ^6.3.3
         version: 6.3.4
@@ -2144,6 +2150,10 @@ packages:
     resolution: {integrity: sha512-myRT3DiWPHqho5PrJaIRyaMv2kgYf0mUVgBNOYMuCH5Ki1yEiQaf/ZJuQ62nvpc44wL5WDbTX7yGJi1Neevw8w==}
     engines: {node: '>= 0.6'}
 
+  node-cron@4.2.1:
+    resolution: {integrity: sha512-lgimEHPE/QDgFlywTd8yTR61ptugX3Qer29efeyWw2rv259HtGBNn1vZVmp8lB9uo9wC0t/AT4iGqXxia+CJFg==}
+    engines: {node: '>=6.0.0'}
+
   node-domexception@1.0.0:
     resolution: {integrity: sha512-/jKZoMpw0F8GRwl4/eLROPA3cfcXtLApP0QzLmUT/HuPCZWyB7IY9ZrMeKw2O/nFIqPQB3PVM9aYm0F312AXDQ==}
     engines: {node: '>=10.5.0'}
@@ -2302,6 +2312,61 @@ packages:
     resolution: {integrity: sha512-GbK2cP9nraSSUF9N2XwUwqfzlAFlMNYYl+ShE/V+H8a9uNl/oUqB1w2EL54Jh0OlyRSd8RfWYJ3coVS4TROP2w==}
     engines: {node: '>=6.0.0'}
 
+  prettier-plugin-tailwindcss@0.7.2:
+    resolution: {integrity: sha512-LkphyK3Fw+q2HdMOoiEHWf93fNtYJwfamoKPl7UwtjFQdei/iIBoX11G6j706FzN3ymX9mPVi97qIY8328vdnA==}
+    engines: {node: '>=20.19'}
+    peerDependencies:
+      '@ianvs/prettier-plugin-sort-imports': '*'
+      '@prettier/plugin-hermes': '*'
+      '@prettier/plugin-oxc': '*'
+      '@prettier/plugin-pug': '*'
+      '@shopify/prettier-plugin-liquid': '*'
+      '@trivago/prettier-plugin-sort-imports': '*'
+      '@zackad/prettier-plugin-twig': '*'
+      prettier: ^3.0
+      prettier-plugin-astro: '*'
+      prettier-plugin-css-order: '*'
+      prettier-plugin-jsdoc: '*'
+      prettier-plugin-marko: '*'
+      prettier-plugin-multiline-arrays: '*'
+      prettier-plugin-organize-attributes: '*'
+      prettier-plugin-organize-imports: '*'
+      prettier-plugin-sort-imports: '*'
+      prettier-plugin-svelte: '*'
+    peerDependenciesMeta:
+      '@ianvs/prettier-plugin-sort-imports':
+        optional: true
+      '@prettier/plugin-hermes':
+        optional: true
+      '@prettier/plugin-oxc':
+        optional: true
+      '@prettier/plugin-pug':
+        optional: true
+      '@shopify/prettier-plugin-liquid':
+        optional: true
+      '@trivago/prettier-plugin-sort-imports':
+        optional: true
+      '@zackad/prettier-plugin-twig':
+        optional: true
+      prettier-plugin-astro:
+        optional: true
+      prettier-plugin-css-order:
+        optional: true
+      prettier-plugin-jsdoc:
+        optional: true
+      prettier-plugin-marko:
+        optional: true
+      prettier-plugin-multiline-arrays:
+        optional: true
+      prettier-plugin-organize-attributes:
+        optional: true
+      prettier-plugin-organize-imports:
+        optional: true
+      prettier-plugin-sort-imports:
+        optional: true
+      prettier-plugin-svelte:
+        optional: true
+
   prettier@3.7.4:
     resolution: {integrity: sha512-v6UNi1+3hSlVvv8fSaoUbggEM5VErKmmpGA7Pl3HF8V6uKY7rvClBOJlH6yNwQtfTueNkGVpOv/mtWL9L4bgRA==}
     engines: {node: '>=14'}
@@ -5692,6 +5757,8 @@ snapshots:
 
   negotiator@0.6.4: {}
 
+  node-cron@4.2.1: {}
+
   node-domexception@1.0.0: {}
 
   node-fetch@3.3.2:
@@ -5840,6 +5907,10 @@ snapshots:
     dependencies:
       fast-diff: 1.3.0
 
+  prettier-plugin-tailwindcss@0.7.2(prettier@3.7.4):
+    dependencies:
+      prettier: 3.7.4
+
   prettier@3.7.4: {}
 
   pretty-format@29.7.0:

scripts/test-official-models.js

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+/**
+ * 官方模型版本识别测试 - 最终版 v2
+ */
+
+const { isOpus45OrNewer } = require('../src/utils/modelHelper')
+
+// 官方模型
+const officialModels = [
+  { name: 'claude-3-opus-20240229', desc: 'Opus 3 (已弃用)', expectPro: false },
+  { name: 'claude-opus-4-20250514', desc: 'Opus 4.0', expectPro: false },
+  { name: 'claude-opus-4-1-20250805', desc: 'Opus 4.1', expectPro: false },
+  { name: 'claude-opus-4-5-20251101', desc: 'Opus 4.5', expectPro: true }
+]
+
+// 非 Opus 模型
+const nonOpusModels = [
+  { name: 'claude-sonnet-4-20250514', desc: 'Sonnet 4' },
+  { name: 'claude-sonnet-4-5-20250929', desc: 'Sonnet 4.5' },
+  { name: 'claude-haiku-4-5-20251001', desc: 'Haiku 4.5' },
+  { name: 'claude-3-5-haiku-20241022', desc: 'Haiku 3.5' },
+  { name: 'claude-3-haiku-20240307', desc: 'Haiku 3' },
+  { name: 'claude-3-7-sonnet-20250219', desc: 'Sonnet 3.7 (已弃用)' }
+]
+
+// 其他格式测试
+const otherFormats = [
+  { name: 'claude-opus-4.5', expected: true, desc: 'Opus 4.5 点分隔' },
+  { name: 'claude-opus-4-5', expected: true, desc: 'Opus 4.5 横线分隔' },
+  { name: 'opus-4.5', expected: true, desc: 'Opus 4.5 无前缀' },
+  { name: 'opus-4-5', expected: true, desc: 'Opus 4-5 无前缀' },
+  { name: 'opus-latest', expected: true, desc: 'Opus latest' },
+  { name: 'claude-opus-5', expected: true, desc: 'Opus 5 (未来)' },
+  { name: 'claude-opus-5-0', expected: true, desc: 'Opus 5.0 (未来)' },
+  { name: 'opus-4.0', expected: false, desc: 'Opus 4.0' },
+  { name: 'opus-4.1', expected: false, desc: 'Opus 4.1' },
+  { name: 'opus-4.4', expected: false, desc: 'Opus 4.4' },
+  { name: 'opus-4', expected: false, desc: 'Opus 4' },
+  { name: 'opus-4-0', expected: false, desc: 'Opus 4-0' },
+  { name: 'opus-4-1', expected: false, desc: 'Opus 4-1' },
+  { name: 'opus-4-4', expected: false, desc: 'Opus 4-4' },
+  { name: 'opus', expected: false, desc: '仅 opus' },
+  { name: null, expected: false, desc: 'null' },
+  { name: '', expected: false, desc: '空字符串' }
+]
+
+console.log('='.repeat(90))
+console.log('官方模型版本识别测试 - 最终版 v2')
+console.log('='.repeat(90))
+console.log()
+
+let passed = 0
+let failed = 0
+
+// 测试官方 Opus 模型
+console.log('📌 官方 Opus 模型:')
+for (const m of officialModels) {
+  const result = isOpus45OrNewer(m.name)
+  const status = result === m.expectPro ? '✅ PASS' : '❌ FAIL'
+  if (result === m.expectPro) {
+    passed++
+  } else {
+    failed++
+  }
+  const proSupport = result ? 'Pro 可用 ✅' : 'Pro 不可用 ❌'
+  console.log(`  ${status} | ${m.name.padEnd(32)} | ${m.desc.padEnd(18)} | ${proSupport}`)
+}
+
+console.log()
+console.log('📌 非 Opus 模型 (不受此函数影响):')
+for (const m of nonOpusModels) {
+  const result = isOpus45OrNewer(m.name)
+  console.log(
+    `  ➖      | ${m.name.padEnd(32)} | ${m.desc.padEnd(18)} | ${result ? '⚠️ 异常' : '正确跳过'}`
+  )
+  if (result) {
+    failed++ // 非 Opus 模型不应返回 true
+  }
+}
+
+console.log()
+console.log('📌 其他格式测试:')
+for (const m of otherFormats) {
+  const result = isOpus45OrNewer(m.name)
+  const status = result === m.expected ? '✅ PASS' : '❌ FAIL'
+  if (result === m.expected) {
+    passed++
+  } else {
+    failed++
+  }
+  const display = m.name === null ? 'null' : m.name === '' ? '""' : m.name
+  console.log(
+    `  ${status} | ${display.padEnd(25)} | ${m.desc.padEnd(18)} | ${result ? 'Pro 可用' : 'Pro 不可用'}`
+  )
+}
+
+console.log()
+console.log('='.repeat(90))
+console.log('测试结果:', passed, '通过,', failed, '失败')
+console.log('='.repeat(90))
+
+if (failed > 0) {
+  console.log('\n❌ 有测试失败，请检查函数逻辑')
+  process.exit(1)
+} else {
+  console.log('\n✅ 所有测试通过！函数可以安全使用')
+  process.exit(0)
+}

src/app.js

@@ -584,6 +584,20 @@ class Application {
 
         // 使用 Lua 脚本批量清理所有过期项
         for (const key of keys) {
+          // 跳过非 Sorted Set 类型的键（这些键有各自的清理逻辑）
+          // - concurrency:queue:stats:* 是 Hash 类型
+          // - concurrency:queue:wait_times:* 是 List 类型
+          // - concurrency:queue:* (不含stats/wait_times) 是 String 类型
+          if (
+            key.startsWith('concurrency:queue:stats:') ||
+            key.startsWith('concurrency:queue:wait_times:') ||
+            (key.startsWith('concurrency:queue:') &&
+              !key.includes(':stats:') &&
+              !key.includes(':wait_times:'))
+          ) {
+            continue
+          }
+
           try {
             const cleaned = await redis.client.eval(
               `
@@ -625,6 +639,41 @@ class Application {
     }, 60000) // 每分钟执行一次
 
     logger.info('🔢 Concurrency cleanup task started (running every 1 minute)')
+
+    // 📬 启动用户消息队列服务
+    const userMessageQueueService = require('./services/userMessageQueueService')
+    // 先清理服务重启后残留的锁，防止旧锁阻塞新请求
+    userMessageQueueService.cleanupStaleLocks().then(() => {
+      // 然后启动定时清理任务
+      userMessageQueueService.startCleanupTask()
+    })
+
+    // 🚦 清理服务重启后残留的并发排队计数器
+    // 多实例部署时建议关闭此开关，避免新实例启动时清空其他实例的队列计数
+    // 可通过 DELETE /admin/concurrency/queue 接口手动清理
+    const clearQueuesOnStartup = process.env.CLEAR_CONCURRENCY_QUEUES_ON_STARTUP !== 'false'
+    if (clearQueuesOnStartup) {
+      redis.clearAllConcurrencyQueues().catch((error) => {
+        logger.error('❌ Error clearing concurrency queues on startup:', error)
+      })
+    } else {
+      logger.info(
+        '🚦 Skipping concurrency queue cleanup on startup (CLEAR_CONCURRENCY_QUEUES_ON_STARTUP=false)'
+      )
+    }
+
+    // 🧪 启动账户定时测试调度器
+    // 根据配置定期测试账户连通性并保存测试历史
+    const accountTestSchedulerEnabled =
+      process.env.ACCOUNT_TEST_SCHEDULER_ENABLED !== 'false' &&
+      config.accountTestScheduler?.enabled !== false
+    if (accountTestSchedulerEnabled) {
+      const accountTestSchedulerService = require('./services/accountTestSchedulerService')
+      accountTestSchedulerService.start()
+      logger.info('🧪 Account test scheduler service started')
+    } else {
+      logger.info('🧪 Account test scheduler service disabled')
+    }
   }
 
   setupGracefulShutdown() {
@@ -661,6 +710,15 @@ class Application {
             logger.error('❌ Error stopping rate limit cleanup service:', error)
           }
 
+          // 停止用户消息队列清理服务
+          try {
+            const userMessageQueueService = require('./services/userMessageQueueService')
+            userMessageQueueService.stopCleanupTask()
+            logger.info('📬 User message queue service stopped')
+          } catch (error) {
+            logger.error('❌ Error stopping user message queue service:', error)
+          }
+
           // 停止费用排序索引服务
           try {
             const costRankService = require('./services/costRankService')
@@ -670,6 +728,15 @@ class Application {
             logger.error('❌ Error stopping cost rank service:', error)
           }
 
+          // 停止账户定时测试调度器
+          try {
+            const accountTestSchedulerService = require('./services/accountTestSchedulerService')
+            accountTestSchedulerService.stop()
+            logger.info('🧪 Account test scheduler service stopped')
+          } catch (error) {
+            logger.error('❌ Error stopping account test scheduler service:', error)
+          }
+
           // 🔢 清理所有并发计数（Phase 1 修复：防止重启泄漏）
           try {
             logger.info('🔢 Cleaning up all concurrency counters...')

src/middleware/auth.js

@@ -6,6 +6,104 @@ const logger = require('../utils/logger')
 const redis = require('../models/redis')
 // const { RateLimiterRedis } = require('rate-limiter-flexible') // 暂时未使用
 const ClientValidator = require('../validators/clientValidator')
+const ClaudeCodeValidator = require('../validators/clients/claudeCodeValidator')
+const claudeRelayConfigService = require('../services/claudeRelayConfigService')
+const { calculateWaitTimeStats } = require('../utils/statsHelper')
+
+// 工具函数
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+/**
+ * 检查排队是否过载，决定是否应该快速失败
+ * 详见 design.md Decision 7: 排队健康检查与快速失败
+ *
+ * @param {string} apiKeyId - API Key ID
+ * @param {number} timeoutMs - 排队超时时间（毫秒）
+ * @param {Object} queueConfig - 队列配置
+ * @param {number} maxQueueSize - 最大排队数
+ * @returns {Promise<Object>} { reject: boolean, reason?: string, estimatedWaitMs?: number, timeoutMs?: number }
+ */
+async function shouldRejectDueToOverload(apiKeyId, timeoutMs, queueConfig, maxQueueSize) {
+  try {
+    // 如果健康检查被禁用，直接返回不拒绝
+    if (!queueConfig.concurrentRequestQueueHealthCheckEnabled) {
+      return { reject: false, reason: 'health_check_disabled' }
+    }
+
+    // 🔑 先检查当前队列长度
+    const currentQueueCount = await redis.getConcurrencyQueueCount(apiKeyId).catch(() => 0)
+
+    // 队列为空，说明系统已恢复，跳过健康检查
+    if (currentQueueCount === 0) {
+      return { reject: false, reason: 'queue_empty', currentQueueCount: 0 }
+    }
+
+    // 🔑 关键改进：只有当队列接近满载时才进行健康检查
+    // 队列长度 <= maxQueueSize * 0.5 时，认为系统有足够余量，跳过健康检查
+    // 这避免了在队列较短时过于保守地拒绝请求
+    // 使用 ceil 确保小队列（如 maxQueueSize=3）时阈值为 2，即队列 <=1 时跳过
+    const queueLoadThreshold = Math.ceil(maxQueueSize * 0.5)
+    if (currentQueueCount <= queueLoadThreshold) {
+      return {
+        reject: false,
+        reason: 'queue_not_loaded',
+        currentQueueCount,
+        queueLoadThreshold,
+        maxQueueSize
+      }
+    }
+
+    // 获取该 API Key 的等待时间样本
+    const waitTimes = await redis.getQueueWaitTimes(apiKeyId)
+    const stats = calculateWaitTimeStats(waitTimes)
+
+    // 样本不足（< 10），跳过健康检查，避免冷启动误判
+    if (!stats || stats.sampleCount < 10) {
+      return { reject: false, reason: 'insufficient_samples', sampleCount: stats?.sampleCount || 0 }
+    }
+
+    // P90 不可靠时也跳过（虽然 sampleCount >= 10 时 p90Unreliable 应该是 false）
+    if (stats.p90Unreliable) {
+      return { reject: false, reason: 'p90_unreliable', sampleCount: stats.sampleCount }
+    }
+
+    // 计算健康阈值：P90 >= 超时时间 × 阈值 时拒绝
+    const threshold = queueConfig.concurrentRequestQueueHealthThreshold || 0.8
+    const maxAllowedP90 = timeoutMs * threshold
+
+    if (stats.p90 >= maxAllowedP90) {
+      return {
+        reject: true,
+        reason: 'queue_overloaded',
+        estimatedWaitMs: stats.p90,
+        timeoutMs,
+        threshold,
+        sampleCount: stats.sampleCount,
+        currentQueueCount,
+        maxQueueSize
+      }
+    }
+
+    return { reject: false, p90: stats.p90, sampleCount: stats.sampleCount, currentQueueCount }
+  } catch (error) {
+    // 健康检查出错时不阻塞请求，记录警告并继续
+    logger.warn(`Health check failed for ${apiKeyId}:`, error.message)
+    return { reject: false, reason: 'health_check_error', error: error.message }
+  }
+}
+
+// 排队轮询配置常量（可通过配置文件覆盖）
+// 性能权衡：初始间隔越短响应越快，但 Redis QPS 越高
+// 当前配置：100 个等待者时约 250-300 QPS（指数退避后）
+const QUEUE_POLLING_CONFIG = {
+  pollIntervalMs: 200, // 初始轮询间隔（毫秒）- 平衡响应速度和 Redis 压力
+  maxPollIntervalMs: 2000, // 最大轮询间隔（毫秒）- 长时间等待时降低 Redis 压力
+  backoffFactor: 1.5, // 指数退避系数
+  jitterRatio: 0.2, // 抖动比例（±20%）- 防止惊群效应
+  maxRedisFailCount: 5 // 连续 Redis 失败阈值（从 3 提高到 5，提高网络抖动容忍度）
+}
 
 const FALLBACK_CONCURRENCY_CONFIG = {
   leaseSeconds: 300,
@@ -126,9 +224,223 @@ function isTokenCountRequest(req) {
   return false
 }
 
+/**
+ * 等待并发槽位（排队机制核心）
+ *
+ * 采用「先占后检查」模式避免竞态条件：
+ * - 每次轮询时尝试 incrConcurrency 占位
+ * - 如果超限则 decrConcurrency 释放并继续等待
+ * - 成功获取槽位后返回，调用方无需再次 incrConcurrency
+ *
+ * ⚠️ 重要清理责任说明：
+ * - 排队计数：此函数的 finally 块负责调用 decrConcurrencyQueue 清理
+ * - 并发槽位：当返回 acquired=true 时，槽位已被占用（通过 incrConcurrency）
+ *   调用方必须在请求结束时调用 decrConcurrency 释放槽位
+ *   （已在 authenticateApiKey 的 finally 块中处理）
+ *
+ * @param {Object} req - Express 请求对象
+ * @param {Object} res - Express 响应对象
+ * @param {string} apiKeyId - API Key ID
+ * @param {Object} queueOptions - 配置参数
+ * @returns {Promise<Object>} { acquired: boolean, reason?: string, waitTimeMs: number }
+ */
+async function waitForConcurrencySlot(req, res, apiKeyId, queueOptions) {
+  const {
+    concurrencyLimit,
+    requestId,
+    leaseSeconds,
+    timeoutMs,
+    pollIntervalMs,
+    maxPollIntervalMs,
+    backoffFactor,
+    jitterRatio,
+    maxRedisFailCount: configMaxRedisFailCount
+  } = queueOptions
+
+  let clientDisconnected = false
+  // 追踪轮询过程中是否临时占用了槽位（用于异常时清理）
+  // 工作流程：
+  // 1. incrConcurrency 成功且 count <= limit 时，设置 internalSlotAcquired = true
+  // 2. 统计记录完成后，设置 internalSlotAcquired = false 并返回（所有权转移给调用方）
+  // 3. 如果在步骤 1-2 之间发生异常，finally 块会检测到 internalSlotAcquired = true 并释放槽位
+  let internalSlotAcquired = false
+
+  // 监听客户端断开事件
+  // ⚠️ 重要：必须监听 socket 的事件，而不是 req 的事件！
+  // 原因：对于 POST 请求，当 body-parser 读取完请求体后，req（IncomingMessage 可读流）
+  // 的 'close' 事件会立即触发，但这不代表客户端断开连接！客户端仍在等待响应。
+  // socket 的 'close' 事件才是真正的连接关闭信号。
+  const { socket } = req
+  const onSocketClose = () => {
+    clientDisconnected = true
+    logger.debug(
+      `🔌 [Queue] Socket closed during queue wait for API key ${apiKeyId}, requestId: ${requestId}`
+    )
+  }
+
+  if (socket) {
+    socket.once('close', onSocketClose)
+  }
+
+  // 检查 socket 是否在监听器注册前已被销毁（边界情况）
+  if (socket?.destroyed) {
+    clientDisconnected = true
+  }
+
+  const startTime = Date.now()
+  let pollInterval = pollIntervalMs
+  let redisFailCount = 0
+  // 优先使用配置中的值，否则使用默认值
+  const maxRedisFailCount = configMaxRedisFailCount || QUEUE_POLLING_CONFIG.maxRedisFailCount
+
+  try {
+    while (Date.now() - startTime < timeoutMs) {
+      // 检测客户端是否断开（双重检查：事件标记 + socket 状态）
+      // socket.destroyed 是同步检查，确保即使事件处理有延迟也能及时检测
+      if (clientDisconnected || socket?.destroyed) {
+        redis
+          .incrConcurrencyQueueStats(apiKeyId, 'cancelled')
+          .catch((e) => logger.warn('Failed to record cancelled stat:', e))
+        return {
+          acquired: false,
+          reason: 'client_disconnected',
+          waitTimeMs: Date.now() - startTime
+        }
+      }
+
+      // 尝试获取槽位（先占后检查）
+      try {
+        const count = await redis.incrConcurrency(apiKeyId, requestId, leaseSeconds)
+        redisFailCount = 0 // 重置失败计数
+
+        if (count <= concurrencyLimit) {
+          // 成功获取槽位！
+          const waitTimeMs = Date.now() - startTime
+
+          // 槽位所有权转移说明：
+          // 1. 此时槽位已通过 incrConcurrency 获取
+          // 2. 先标记 internalSlotAcquired = true，确保异常时 finally 块能清理
+          // 3. 统计操作完成后，清除标记并返回，所有权转移给调用方
+          // 4. 调用方（authenticateApiKey）负责在请求结束时释放槽位
+
+          // 标记槽位已获取（用于异常时 finally 块清理）
+          internalSlotAcquired = true
+
+          // 记录统计（非阻塞，fire-and-forget 模式）
+          // ⚠️ 设计说明：
+          // - 故意不 await 这些 Promise，因为统计记录不应阻塞请求处理
+          // - 每个 Promise 都有独立的 .catch()，确保单个失败不影响其他
+          // - 外层 .catch() 是防御性措施，处理 Promise.all 本身的异常
+          // - 即使统计记录在函数返回后才完成/失败，也是安全的（仅日志记录）
+          // - 统计数据丢失可接受，不影响核心业务逻辑
+          Promise.all([
+            redis
+              .recordQueueWaitTime(apiKeyId, waitTimeMs)
+              .catch((e) => logger.warn('Failed to record queue wait time:', e)),
+            redis
+              .recordGlobalQueueWaitTime(waitTimeMs)
+              .catch((e) => logger.warn('Failed to record global wait time:', e)),
+            redis
+              .incrConcurrencyQueueStats(apiKeyId, 'success')
+              .catch((e) => logger.warn('Failed to increment success stats:', e))
+          ]).catch((e) => logger.warn('Failed to record queue stats batch:', e))
+
+          // 成功返回前清除标记（所有权转移给调用方，由其负责释放）
+          internalSlotAcquired = false
+          return { acquired: true, waitTimeMs }
+        }
+
+        // 超限，释放槽位继续等待
+        try {
+          await redis.decrConcurrency(apiKeyId, requestId)
+        } catch (decrError) {
+          // 释放失败时记录警告但继续轮询
+          // 下次 incrConcurrency 会自然覆盖同一 requestId 的条目
+          logger.warn(
+            `Failed to release slot during polling for ${apiKeyId}, will retry:`,
+            decrError
+          )
+        }
+      } catch (redisError) {
+        redisFailCount++
+        logger.error(
+          `Redis error in queue polling (${redisFailCount}/${maxRedisFailCount}):`,
+          redisError
+        )
+
+        if (redisFailCount >= maxRedisFailCount) {
+          // 连续 Redis 失败，放弃排队
+          return {
+            acquired: false,
+            reason: 'redis_error',
+            waitTimeMs: Date.now() - startTime
+          }
+        }
+      }
+
+      // 指数退避等待
+      await sleep(pollInterval)
+
+      // 计算下一次轮询间隔（指数退避 + 抖动）
+      // 1. 先应用指数退避
+      let nextInterval = pollInterval * backoffFactor
+      // 2. 添加抖动防止惊群效应（±jitterRatio 范围内的随机偏移）
+      //    抖动范围：[-jitterRatio, +jitterRatio]，例如 jitterRatio=0.2 时为 ±20%
+      //    这是预期行为：负抖动可使间隔略微缩短，正抖动可使间隔略微延长
+      //    目的是分散多个等待者的轮询时间点，避免同时请求 Redis
+      const jitter = nextInterval * jitterRatio * (Math.random() * 2 - 1)
+      nextInterval = nextInterval + jitter
+      // 3. 确保在合理范围内：最小 1ms，最大 maxPollIntervalMs
+      //    Math.max(1, ...) 保证即使负抖动也不会产生 ≤0 的间隔
+      pollInterval = Math.max(1, Math.min(nextInterval, maxPollIntervalMs))
+    }
+
+    // 超时
+    redis
+      .incrConcurrencyQueueStats(apiKeyId, 'timeout')
+      .catch((e) => logger.warn('Failed to record timeout stat:', e))
+    return { acquired: false, reason: 'timeout', waitTimeMs: Date.now() - startTime }
+  } finally {
+    // 确保清理：
+    // 1. 减少排队计数（排队计数在调用方已增加，这里负责减少）
+    try {
+      await redis.decrConcurrencyQueue(apiKeyId)
+    } catch (cleanupError) {
+      // 清理失败记录错误（可能导致计数泄漏，但有 TTL 保护）
+      logger.error(
+        `Failed to decrement queue count in finally block for ${apiKeyId}:`,
+        cleanupError
+      )
+    }
+
+    // 2. 如果内部获取了槽位但未正常返回（异常路径），释放槽位
+    if (internalSlotAcquired) {
+      try {
+        await redis.decrConcurrency(apiKeyId, requestId)
+        logger.warn(
+          `⚠️ Released orphaned concurrency slot in finally block for ${apiKeyId}, requestId: ${requestId}`
+        )
+      } catch (slotCleanupError) {
+        logger.error(
+          `Failed to release orphaned concurrency slot for ${apiKeyId}:`,
+          slotCleanupError
+        )
+      }
+    }
+
+    // 清理 socket 事件监听器
+    if (socket) {
+      socket.removeListener('close', onSocketClose)
+    }
+  }
+}
+
 // 🔑 API Key验证中间件（优化版）
 const authenticateApiKey = async (req, res, next) => {
   const startTime = Date.now()
+  let authErrored = false
+  let concurrencyCleanup = null
+  let hasConcurrencySlot = false
 
   try {
     // 安全提取API Key，支持多种格式（包括Gemini CLI支持）
@@ -201,6 +513,53 @@ const authenticateApiKey = async (req, res, next) => {
       )
     }
 
+    // 🔒 检查全局 Claude Code 限制（与 API Key 级别是 OR 逻辑）
+    // 仅对 Claude 服务端点生效 (/api/v1/messages 和 /claude/v1/messages)
+    if (!skipKeyRestrictions) {
+      const normalizedPath = (req.originalUrl || req.path || '').toLowerCase()
+      const isClaudeMessagesEndpoint =
+        normalizedPath.includes('/v1/messages') &&
+        (normalizedPath.startsWith('/api') || normalizedPath.startsWith('/claude'))
+
+      if (isClaudeMessagesEndpoint) {
+        try {
+          const globalClaudeCodeOnly = await claudeRelayConfigService.isClaudeCodeOnlyEnabled()
+
+          // API Key 级别的 Claude Code 限制
+          const keyClaudeCodeOnly =
+            validation.keyData.enableClientRestriction &&
+            Array.isArray(validation.keyData.allowedClients) &&
+            validation.keyData.allowedClients.length === 1 &&
+            validation.keyData.allowedClients.includes('claude_code')
+
+          // OR 逻辑：全局开启 或 API Key 级别限制为仅 claude_code
+          if (globalClaudeCodeOnly || keyClaudeCodeOnly) {
+            const isClaudeCode = ClaudeCodeValidator.validate(req)
+
+            if (!isClaudeCode) {
+              const clientIP = req.ip || req.connection?.remoteAddress || 'unknown'
+              logger.api(
+                `❌ Claude Code client validation failed (global: ${globalClaudeCodeOnly}, key: ${keyClaudeCodeOnly}) from ${clientIP}`
+              )
+              return res.status(403).json({
+                error: {
+                  type: 'client_validation_error',
+                  message: 'This endpoint only accepts requests from Claude Code CLI'
+                }
+              })
+            }
+
+            logger.api(
+              `✅ Claude Code client validated (global: ${globalClaudeCodeOnly}, key: ${keyClaudeCodeOnly})`
+            )
+          }
+        } catch (error) {
+          logger.error('❌ Error checking Claude Code restriction:', error)
+          // 配置服务出错时不阻断请求
+        }
+      }
+    }
+
     // 检查并发限制
     const concurrencyLimit = validation.keyData.concurrencyLimit || 0
     if (!skipKeyRestrictions && concurrencyLimit > 0) {
@@ -216,23 +575,86 @@ const authenticateApiKey = async (req, res, next) => {
       }
       const requestId = uuidv4()
 
+      // ⚠️ 优化后的 Connection: close 设置策略
+      // 问题背景：HTTP Keep-Alive 使多个请求共用同一个 TCP 连接
+      // 当第一个请求正在处理，第二个请求进入排队时，它们共用同一个 socket
+      // 如果客户端超时关闭连接，两个请求都会受影响
+      // 优化方案：只有在请求实际进入排队时才设置 Connection: close
+      // 未排队的请求保持 Keep-Alive，避免不必要的 TCP 握手开销
+      // 详见 design.md Decision 2: Connection: close 设置时机
+      // 注意：Connection: close 将在下方代码实际进入排队时设置（第 637 行左右）
+
+      // ============================================================
+      // 🔒 并发槽位状态管理说明
+      // ============================================================
+      // 此函数中有两个关键状态变量：
+      // - hasConcurrencySlot: 当前是否持有并发槽位
+      // - concurrencyCleanup: 错误时调用的清理函数
+      //
+      // 状态转换流程：
+      // 1. incrConcurrency 成功 → hasConcurrencySlot=true, 设置临时清理函数
+      // 2. 若超限 → 释放槽位，hasConcurrencySlot=false, concurrencyCleanup=null
+      // 3. 若排队成功 → hasConcurrencySlot=true, 升级为完整清理函数（含 interval 清理）
+      // 4. 请求结束（res.close/req.close）→ 调用 decrementConcurrency 释放
+      // 5. 认证错误 → finally 块调用 concurrencyCleanup 释放
+      //
+      // 为什么需要两种清理函数？
+      // - 临时清理：在排队/认证过程中出错时使用，只释放槽位
+      // - 完整清理：请求正常开始后使用，还需清理 leaseRenewInterval
+      // ============================================================
+      const setTemporaryConcurrencyCleanup = () => {
+        concurrencyCleanup = async () => {
+          if (!hasConcurrencySlot) {
+            return
+          }
+          hasConcurrencySlot = false
+          try {
+            await redis.decrConcurrency(validation.keyData.id, requestId)
+          } catch (cleanupError) {
+            logger.error(
+              `Failed to decrement concurrency after auth error for key ${validation.keyData.id}:`,
+              cleanupError
+            )
+          }
+        }
+      }
+
       const currentConcurrency = await redis.incrConcurrency(
         validation.keyData.id,
         requestId,
         leaseSeconds
       )
+      hasConcurrencySlot = true
+      setTemporaryConcurrencyCleanup()
       logger.api(
         `📈 Incremented concurrency for key: ${validation.keyData.id} (${validation.keyData.name}), current: ${currentConcurrency}, limit: ${concurrencyLimit}`
       )
 
       if (currentConcurrency > concurrencyLimit) {
-        // 如果超过限制，立即减少计数
+        // 1. 先释放刚占用的槽位
+        try {
           await redis.decrConcurrency(validation.keyData.id, requestId)
+        } catch (error) {
+          logger.error(
+            `Failed to decrement concurrency after limit exceeded for key ${validation.keyData.id}:`,
+            error
+          )
+        }
+        hasConcurrencySlot = false
+        concurrencyCleanup = null
+
+        // 2. 获取排队配置
+        const queueConfig = await claudeRelayConfigService.getConfig()
+
+        // 3. 排队功能未启用，直接返回 429（保持现有行为）
+        if (!queueConfig.concurrentRequestQueueEnabled) {
           logger.security(
             `🚦 Concurrency limit exceeded for key: ${validation.keyData.id} (${
               validation.keyData.name
             }), current: ${currentConcurrency - 1}, limit: ${concurrencyLimit}`
           )
+          // 建议客户端在短暂延迟后重试（并发场景下通常很快会有槽位释放）
+          res.set('Retry-After', '1')
           return res.status(429).json({
             error: 'Concurrency limit exceeded',
             message: `Too many concurrent requests. Limit: ${concurrencyLimit} concurrent requests`,
@@ -241,6 +663,260 @@ const authenticateApiKey = async (req, res, next) => {
           })
         }
 
+        // 4. 计算最大排队数
+        const maxQueueSize = Math.max(
+          concurrencyLimit * queueConfig.concurrentRequestQueueMaxSizeMultiplier,
+          queueConfig.concurrentRequestQueueMaxSize
+        )
+
+        // 4.5 排队健康检查：过载时快速失败
+        // 详见 design.md Decision 7: 排队健康检查与快速失败
+        const overloadCheck = await shouldRejectDueToOverload(
+          validation.keyData.id,
+          queueConfig.concurrentRequestQueueTimeoutMs,
+          queueConfig,
+          maxQueueSize
+        )
+        if (overloadCheck.reject) {
+          // 使用健康检查返回的当前排队数，避免重复调用 Redis
+          const currentQueueCount = overloadCheck.currentQueueCount || 0
+          logger.api(
+            `🚨 Queue overloaded for key: ${validation.keyData.id} (${validation.keyData.name}), ` +
+              `P90=${overloadCheck.estimatedWaitMs}ms, timeout=${overloadCheck.timeoutMs}ms, ` +
+              `threshold=${overloadCheck.threshold}, samples=${overloadCheck.sampleCount}, ` +
+              `concurrency=${concurrencyLimit}, queue=${currentQueueCount}/${maxQueueSize}`
+          )
+          // 记录被拒绝的过载统计
+          redis
+            .incrConcurrencyQueueStats(validation.keyData.id, 'rejected_overload')
+            .catch((e) => logger.warn('Failed to record rejected_overload stat:', e))
+          // 返回 429 + Retry-After，让客户端稍后重试
+          const retryAfterSeconds = 30
+          res.set('Retry-After', String(retryAfterSeconds))
+          return res.status(429).json({
+            error: 'Queue overloaded',
+            message: `Queue is overloaded. Estimated wait time (${overloadCheck.estimatedWaitMs}ms) exceeds threshold. Limit: ${concurrencyLimit} concurrent requests, queue: ${currentQueueCount}/${maxQueueSize}. Please retry later.`,
+            currentConcurrency: concurrencyLimit,
+            concurrencyLimit,
+            queueCount: currentQueueCount,
+            maxQueueSize,
+            estimatedWaitMs: overloadCheck.estimatedWaitMs,
+            timeoutMs: overloadCheck.timeoutMs,
+            queueTimeoutMs: queueConfig.concurrentRequestQueueTimeoutMs,
+            retryAfterSeconds
+          })
+        }
+
+        // 5. 尝试进入排队（原子操作：先增加再检查，避免竞态条件）
+        let queueIncremented = false
+        try {
+          const newQueueCount = await redis.incrConcurrencyQueue(
+            validation.keyData.id,
+            queueConfig.concurrentRequestQueueTimeoutMs
+          )
+          queueIncremented = true
+
+          if (newQueueCount > maxQueueSize) {
+            // 超过最大排队数，立即释放并返回 429
+            await redis.decrConcurrencyQueue(validation.keyData.id)
+            queueIncremented = false
+            logger.api(
+              `🚦 Concurrency queue full for key: ${validation.keyData.id} (${validation.keyData.name}), ` +
+                `queue: ${newQueueCount - 1}, maxQueue: ${maxQueueSize}`
+            )
+            // 队列已满，建议客户端在排队超时时间后重试
+            const retryAfterSeconds = Math.ceil(queueConfig.concurrentRequestQueueTimeoutMs / 1000)
+            res.set('Retry-After', String(retryAfterSeconds))
+            return res.status(429).json({
+              error: 'Concurrency queue full',
+              message: `Too many requests waiting in queue. Limit: ${concurrencyLimit} concurrent requests, queue: ${newQueueCount - 1}/${maxQueueSize}, timeout: ${retryAfterSeconds}s`,
+              currentConcurrency: concurrencyLimit,
+              concurrencyLimit,
+              queueCount: newQueueCount - 1,
+              maxQueueSize,
+              queueTimeoutMs: queueConfig.concurrentRequestQueueTimeoutMs,
+              retryAfterSeconds
+            })
+          }
+
+          // 6. 已成功进入排队，记录统计并开始等待槽位
+          logger.api(
+            `⏳ Request entering queue for key: ${validation.keyData.id} (${validation.keyData.name}), ` +
+              `queue position: ${newQueueCount}`
+          )
+          redis
+            .incrConcurrencyQueueStats(validation.keyData.id, 'entered')
+            .catch((e) => logger.warn('Failed to record entered stat:', e))
+
+          // ⚠️ 仅在请求实际进入排队时设置 Connection: close
+          // 详见 design.md Decision 2: Connection: close 设置时机
+          // 未排队的请求保持 Keep-Alive，避免不必要的 TCP 握手开销
+          if (!res.headersSent) {
+            res.setHeader('Connection', 'close')
+            logger.api(
+              `🔌 [Queue] Set Connection: close for queued request, key: ${validation.keyData.id}`
+            )
+          }
+
+          // ⚠️ 记录排队开始时的 socket 标识，用于排队完成后验证
+          // 问题背景：HTTP Keep-Alive 连接复用时，长时间排队可能导致 socket 被其他请求使用
+          // 验证方法：使用 UUID token + socket 对象引用双重验证
+          // 详见 design.md Decision 1: Socket 身份验证机制
+          req._crService = req._crService || {}
+          req._crService.queueToken = uuidv4()
+          req._crService.originalSocket = req.socket
+          req._crService.startTime = Date.now()
+          const savedToken = req._crService.queueToken
+          const savedSocket = req._crService.originalSocket
+
+          // ⚠️ 重要：在调用前将 queueIncremented 设为 false
+          // 因为 waitForConcurrencySlot 的 finally 块会负责清理排队计数
+          // 如果在调用后设置，当 waitForConcurrencySlot 抛出异常时
+          // 外层 catch 块会重复减少计数（finally 已经减过一次）
+          queueIncremented = false
+
+          const slot = await waitForConcurrencySlot(req, res, validation.keyData.id, {
+            concurrencyLimit,
+            requestId,
+            leaseSeconds,
+            timeoutMs: queueConfig.concurrentRequestQueueTimeoutMs,
+            pollIntervalMs: QUEUE_POLLING_CONFIG.pollIntervalMs,
+            maxPollIntervalMs: QUEUE_POLLING_CONFIG.maxPollIntervalMs,
+            backoffFactor: QUEUE_POLLING_CONFIG.backoffFactor,
+            jitterRatio: QUEUE_POLLING_CONFIG.jitterRatio,
+            maxRedisFailCount: queueConfig.concurrentRequestQueueMaxRedisFailCount
+          })
+
+          // 7. 处理排队结果
+          if (!slot.acquired) {
+            if (slot.reason === 'client_disconnected') {
+              // 客户端已断开，不返回响应（连接已关闭）
+              logger.api(
+                `🔌 Client disconnected while queuing for key: ${validation.keyData.id} (${validation.keyData.name})`
+              )
+              return
+            }
+
+            if (slot.reason === 'redis_error') {
+              // Redis 连续失败，返回 503
+              logger.error(
+                `❌ Redis error during queue wait for key: ${validation.keyData.id} (${validation.keyData.name})`
+              )
+              return res.status(503).json({
+                error: 'Service temporarily unavailable',
+                message: 'Failed to acquire concurrency slot due to internal error'
+              })
+            }
+            // 排队超时（使用 api 级别，与其他排队日志保持一致）
+            logger.api(
+              `⏰ Queue timeout for key: ${validation.keyData.id} (${validation.keyData.name}), waited: ${slot.waitTimeMs}ms`
+            )
+            // 已等待超时，建议客户端稍后重试
+            // ⚠️ Retry-After 策略优化：
+            // - 请求已经等了完整的 timeout 时间，说明系统负载较高
+            // - 过早重试（如固定 5 秒）会加剧拥塞，导致更多超时
+            // - 合理策略：使用 timeout 时间的一半作为重试间隔
+            // - 最小值 5 秒，最大值 30 秒，避免极端情况
+            const timeoutSeconds = Math.ceil(queueConfig.concurrentRequestQueueTimeoutMs / 1000)
+            const retryAfterSeconds = Math.max(5, Math.min(30, Math.ceil(timeoutSeconds / 2)))
+            res.set('Retry-After', String(retryAfterSeconds))
+            return res.status(429).json({
+              error: 'Queue timeout',
+              message: `Request timed out waiting for concurrency slot. Limit: ${concurrencyLimit} concurrent requests, maxQueue: ${maxQueueSize}, Queue timeout: ${timeoutSeconds}s, waited: ${slot.waitTimeMs}ms`,
+              currentConcurrency: concurrencyLimit,
+              concurrencyLimit,
+              maxQueueSize,
+              queueTimeoutMs: queueConfig.concurrentRequestQueueTimeoutMs,
+              waitTimeMs: slot.waitTimeMs,
+              retryAfterSeconds
+            })
+          }
+
+          // 8. 排队成功，slot.acquired 表示已在 waitForConcurrencySlot 中获取到槽位
+          logger.api(
+            `✅ Queue wait completed for key: ${validation.keyData.id} (${validation.keyData.name}), ` +
+              `waited: ${slot.waitTimeMs}ms`
+          )
+          hasConcurrencySlot = true
+          setTemporaryConcurrencyCleanup()
+
+          // 9. ⚠️ 关键检查：排队等待结束后，验证客户端是否还在等待响应
+          // 长时间排队后，客户端可能在应用层已放弃（如 Claude Code 的超时机制），
+          // 但 TCP 连接仍然存活。此时继续处理请求是浪费资源。
+          // 注意：如果发送了心跳，headersSent 会是 true，但这是正常的
+          const postQueueSocket = req.socket
+          // 只检查连接是否真正断开（destroyed/writableEnded/socketDestroyed）
+          // headersSent 在心跳场景下是正常的，不应该作为放弃的依据
+          if (res.destroyed || res.writableEnded || postQueueSocket?.destroyed) {
+            logger.warn(
+              `⚠️ Client no longer waiting after queue for key: ${validation.keyData.id} (${validation.keyData.name}), ` +
+                `waited: ${slot.waitTimeMs}ms | destroyed: ${res.destroyed}, ` +
+                `writableEnded: ${res.writableEnded}, socketDestroyed: ${postQueueSocket?.destroyed}`
+            )
+            // 释放刚获取的槽位
+            hasConcurrencySlot = false
+            await redis
+              .decrConcurrency(validation.keyData.id, requestId)
+              .catch((e) => logger.error('Failed to release slot after client abandoned:', e))
+            // 不返回响应（客户端已不在等待）
+            return
+          }
+
+          // 10. ⚠️ 关键检查：验证 socket 身份是否改变
+          // HTTP Keep-Alive 连接复用可能导致排队期间 socket 被其他请求使用
+          // 验证方法：UUID token + socket 对象引用双重验证
+          // 详见 design.md Decision 1: Socket 身份验证机制
+          const queueData = req._crService
+          const socketIdentityChanged =
+            !queueData ||
+            queueData.queueToken !== savedToken ||
+            queueData.originalSocket !== savedSocket
+
+          if (socketIdentityChanged) {
+            logger.error(
+              `❌ [Queue] Socket identity changed during queue wait! ` +
+                `key: ${validation.keyData.id} (${validation.keyData.name}), ` +
+                `waited: ${slot.waitTimeMs}ms | ` +
+                `tokenMatch: ${queueData?.queueToken === savedToken}, ` +
+                `socketMatch: ${queueData?.originalSocket === savedSocket}`
+            )
+            // 释放刚获取的槽位
+            hasConcurrencySlot = false
+            await redis
+              .decrConcurrency(validation.keyData.id, requestId)
+              .catch((e) => logger.error('Failed to release slot after socket identity change:', e))
+            // 记录 socket_changed 统计
+            redis
+              .incrConcurrencyQueueStats(validation.keyData.id, 'socket_changed')
+              .catch((e) => logger.warn('Failed to record socket_changed stat:', e))
+            // 不返回响应（socket 已被其他请求使用）
+            return
+          }
+        } catch (queueError) {
+          // 异常时清理资源，防止泄漏
+          // 1. 清理排队计数（如果还没被 waitForConcurrencySlot 的 finally 清理）
+          if (queueIncremented) {
+            await redis
+              .decrConcurrencyQueue(validation.keyData.id)
+              .catch((e) => logger.error('Failed to cleanup queue count after error:', e))
+          }
+
+          // 2. 防御性清理：如果 waitForConcurrencySlot 内部获取了槽位但在返回前异常
+          //    虽然这种情况极少发生（统计记录的异常会被内部捕获），但为了安全起见
+          //    尝试释放可能已获取的槽位。decrConcurrency 使用 ZREM，即使成员不存在也安全
+          if (hasConcurrencySlot) {
+            hasConcurrencySlot = false
+            await redis
+              .decrConcurrency(validation.keyData.id, requestId)
+              .catch((e) =>
+                logger.error('Failed to cleanup concurrency slot after queue error:', e)
+              )
+          }
+
+          throw queueError
+        }
+      }
+
       const renewIntervalMs =
         renewIntervalSeconds > 0 ? Math.max(renewIntervalSeconds * 1000, 15000) : 0
 
@@ -249,7 +925,38 @@ const authenticateApiKey = async (req, res, next) => {
       let leaseRenewInterval = null
 
       if (renewIntervalMs > 0) {
+        // 🔴 关键修复：添加最大刷新次数限制，防止租约永不过期
+        // 默认最大生存时间为 10 分钟，可通过环境变量配置
+        const maxLifetimeMinutes = parseInt(process.env.CONCURRENCY_MAX_LIFETIME_MINUTES) || 10
+        const maxRefreshCount = Math.ceil((maxLifetimeMinutes * 60 * 1000) / renewIntervalMs)
+        let refreshCount = 0
+
         leaseRenewInterval = setInterval(() => {
+          refreshCount++
+
+          // 超过最大刷新次数，强制停止并清理
+          if (refreshCount > maxRefreshCount) {
+            logger.warn(
+              `⚠️ Lease refresh exceeded max count (${maxRefreshCount}) for key ${validation.keyData.id} (${validation.keyData.name}), forcing cleanup after ${maxLifetimeMinutes} minutes`
+            )
+            // 清理定时器
+            if (leaseRenewInterval) {
+              clearInterval(leaseRenewInterval)
+              leaseRenewInterval = null
+            }
+            // 强制减少并发计数（如果还没减少）
+            if (!concurrencyDecremented) {
+              concurrencyDecremented = true
+              redis.decrConcurrency(validation.keyData.id, requestId).catch((error) => {
+                logger.error(
+                  `Failed to decrement concurrency after max refresh for key ${validation.keyData.id}:`,
+                  error
+                )
+              })
+            }
+            return
+          }
+
           redis
             .refreshConcurrencyLease(validation.keyData.id, requestId, leaseSeconds)
             .catch((error) => {
@@ -268,6 +975,7 @@ const authenticateApiKey = async (req, res, next) => {
       const decrementConcurrency = async () => {
         if (!concurrencyDecremented) {
           concurrencyDecremented = true
+          hasConcurrencySlot = false
           if (leaseRenewInterval) {
             clearInterval(leaseRenewInterval)
             leaseRenewInterval = null
@@ -282,6 +990,11 @@ const authenticateApiKey = async (req, res, next) => {
           }
         }
       }
+      // 升级为完整清理函数（包含 leaseRenewInterval 清理逻辑）
+      // 此时请求已通过认证，后续由 res.close/req.close 事件触发清理
+      if (hasConcurrencySlot) {
+        concurrencyCleanup = decrementConcurrency
+      }
 
       // 监听最可靠的事件（避免重复监听）
       // res.on('close') 是最可靠的，会在连接关闭时触发
@@ -607,6 +1320,7 @@ const authenticateApiKey = async (req, res, next) => {
 
     return next()
   } catch (error) {
+    authErrored = true
     const authDuration = Date.now() - startTime
     logger.error(`❌ Authentication middleware error (${authDuration}ms):`, {
       error: error.message,
@@ -620,6 +1334,14 @@ const authenticateApiKey = async (req, res, next) => {
       error: 'Authentication error',
       message: 'Internal server error during authentication'
     })
+  } finally {
+    if (authErrored && typeof concurrencyCleanup === 'function') {
+      try {
+        await concurrencyCleanup()
+      } catch (cleanupError) {
+        logger.error('Failed to cleanup concurrency after auth error:', cleanupError)
+      }
+    }
   }
 }
 
@@ -1298,7 +2020,8 @@ const globalRateLimit = async (req, res, next) =>
 
 // 📊 请求大小限制中间件
 const requestSizeLimit = (req, res, next) => {
-  const maxSize = 60 * 1024 * 1024 // 60MB
+  const MAX_SIZE_MB = parseInt(process.env.REQUEST_MAX_SIZE_MB || '60', 10)
+  const maxSize = MAX_SIZE_MB * 1024 * 1024
   const contentLength = parseInt(req.headers['content-length'] || '0')
 
   if (contentLength > maxSize) {

src/routes/admin/apiKeys.js

@@ -103,6 +103,17 @@ router.get('/api-keys/:keyId/cost-debug', authenticateAdmin, async (req, res) =>
   }
 })
 
+// 获取所有被使用过的模型列表
+router.get('/api-keys/used-models', authenticateAdmin, async (req, res) => {
+  try {
+    const models = await redis.getAllUsedModels()
+    return res.json({ success: true, data: models })
+  } catch (error) {
+    logger.error('❌ Failed to get used models:', error)
+    return res.status(500).json({ error: 'Failed to get used models', message: error.message })
+  }
+})
+
 // 获取所有API Keys
 router.get('/api-keys', authenticateAdmin, async (req, res) => {
   try {
@@ -116,6 +127,7 @@ router.get('/api-keys', authenticateAdmin, async (req, res) => {
       // 筛选参数
       tag = '',
       isActive = '',
+      models = '', // 模型筛选（逗号分隔）
       // 排序参数
       sortBy = 'createdAt',
       sortOrder = 'desc',
@@ -127,6 +139,9 @@ router.get('/api-keys', authenticateAdmin, async (req, res) => {
       timeRange = 'all'
     } = req.query
 
+    // 解析模型筛选参数
+    const modelFilter = models ? models.split(',').filter((m) => m.trim()) : []
+
     // 验证分页参数
     const pageNum = Math.max(1, parseInt(page) || 1)
     const pageSizeNum = [10, 20, 50, 100].includes(parseInt(pageSize)) ? parseInt(pageSize) : 20
@@ -217,7 +232,8 @@ router.get('/api-keys', authenticateAdmin, async (req, res) => {
           search,
           searchMode,
           tag,
-          isActive
+          isActive,
+          modelFilter
         })
 
         costSortStatus = {
@@ -250,7 +266,8 @@ router.get('/api-keys', authenticateAdmin, async (req, res) => {
           search,
           searchMode,
           tag,
-          isActive
+          isActive,
+          modelFilter
         })
 
         costSortStatus.isRealTimeCalculation = false
@@ -265,7 +282,8 @@ router.get('/api-keys', authenticateAdmin, async (req, res) => {
         tag,
         isActive,
         sortBy: validSortBy,
-        sortOrder: validSortOrder
+        sortOrder: validSortOrder,
+        modelFilter
       })
     }
 
@@ -322,7 +340,17 @@ router.get('/api-keys', authenticateAdmin, async (req, res) => {
  * 使用预计算索引进行费用排序的分页查询
  */
 async function getApiKeysSortedByCostPrecomputed(options) {
-  const { page, pageSize, sortOrder, costTimeRange, search, searchMode, tag, isActive } = options
+  const {
+    page,
+    pageSize,
+    sortOrder,
+    costTimeRange,
+    search,
+    searchMode,
+    tag,
+    isActive,
+    modelFilter = []
+  } = options
   const costRankService = require('../../services/costRankService')
 
   // 1. 获取排序后的全量 keyId 列表
@@ -369,6 +397,15 @@ async function getApiKeysSortedByCostPrecomputed(options) {
     }
   }
 
+  // 模型筛选
+  if (modelFilter.length > 0) {
+    const keyIdsWithModels = await redis.getKeyIdsWithModels(
+      orderedKeys.map((k) => k.id),
+      modelFilter
+    )
+    orderedKeys = orderedKeys.filter((k) => keyIdsWithModels.has(k.id))
+  }
+
   // 5. 收集所有可用标签
   const allTags = new Set()
   for (const key of allKeys) {
@@ -411,8 +448,18 @@ async function getApiKeysSortedByCostPrecomputed(options) {
  * 使用实时计算进行 custom 时间范围的费用排序
  */
 async function getApiKeysSortedByCostCustom(options) {
-  const { page, pageSize, sortOrder, startDate, endDate, search, searchMode, tag, isActive } =
+  const {
-    options
+    page,
+    pageSize,
+    sortOrder,
+    startDate,
+    endDate,
+    search,
+    searchMode,
+    tag,
+    isActive,
+    modelFilter = []
+  } = options
   const costRankService = require('../../services/costRankService')
 
   // 1. 实时计算所有 Keys 的费用
@@ -427,9 +474,9 @@ async function getApiKeysSortedByCostCustom(options) {
   }
 
   // 2. 转换为数组并排序
-  const sortedEntries = [...costs.entries()].sort((a, b) => {
+  const sortedEntries = [...costs.entries()].sort((a, b) =>
-    return sortOrder === 'desc' ? b[1] - a[1] : a[1] - b[1]
+    sortOrder === 'desc' ? b[1] - a[1] : a[1] - b[1]
-  })
+  )
   const rankedKeyIds = sortedEntries.map(([keyId]) => keyId)
 
   // 3. 批量获取 API Key 基础数据
@@ -465,6 +512,15 @@ async function getApiKeysSortedByCostCustom(options) {
     }
   }
 
+  // 模型筛选
+  if (modelFilter.length > 0) {
+    const keyIdsWithModels = await redis.getKeyIdsWithModels(
+      orderedKeys.map((k) => k.id),
+      modelFilter
+    )
+    orderedKeys = orderedKeys.filter((k) => keyIdsWithModels.has(k.id))
+  }
+
   // 6. 收集所有可用标签
   const allTags = new Set()
   for (const key of allKeys) {
@@ -863,6 +919,86 @@ async function calculateKeyStats(keyId, timeRange, startDate, endDate) {
   // 去重（避免日数据和月数据重复计算）
   const uniqueKeys = [...new Set(allKeys)]
 
+  // 获取实时限制数据（窗口数据不受时间范围筛选影响，始终获取当前窗口状态）
+  let dailyCost = 0
+  let currentWindowCost = 0
+  let windowRemainingSeconds = null
+  let windowStartTime = null
+  let windowEndTime = null
+  let allTimeCost = 0
+
+  try {
+    // 先获取 API Key 配置，判断是否需要查询限制相关数据
+    const apiKey = await redis.getApiKey(keyId)
+    const rateLimitWindow = parseInt(apiKey?.rateLimitWindow) || 0
+    const dailyCostLimit = parseFloat(apiKey?.dailyCostLimit) || 0
+    const totalCostLimit = parseFloat(apiKey?.totalCostLimit) || 0
+
+    // 只在启用了每日费用限制时查询
+    if (dailyCostLimit > 0) {
+      dailyCost = await redis.getDailyCost(keyId)
+    }
+
+    // 只在启用了总费用限制时查询
+    if (totalCostLimit > 0) {
+      const totalCostKey = `usage:cost:total:${keyId}`
+      allTimeCost = parseFloat((await client.get(totalCostKey)) || '0')
+    }
+
+    // 🔧 FIX: 对于 "全部时间" 时间范围，直接使用 allTimeCost
+    // 因为 usage:*:model:daily:* 键有 30 天 TTL，旧数据已经过期
+    if (timeRange === 'all' && allTimeCost > 0) {
+      logger.debug(`📊 使用 allTimeCost 计算 timeRange='all': ${allTimeCost}`)
+
+      return {
+        requests: 0, // 旧数据详情不可用
+        tokens: 0,
+        inputTokens: 0,
+        outputTokens: 0,
+        cacheCreateTokens: 0,
+        cacheReadTokens: 0,
+        cost: allTimeCost,
+        formattedCost: CostCalculator.formatCost(allTimeCost),
+        // 实时限制数据（始终返回，不受时间范围影响）
+        dailyCost,
+        currentWindowCost,
+        windowRemainingSeconds,
+        windowStartTime,
+        windowEndTime,
+        allTimeCost
+      }
+    }
+
+    // 只在启用了窗口限制时查询窗口数据
+    if (rateLimitWindow > 0) {
+      const costCountKey = `rate_limit:cost:${keyId}`
+      const windowStartKey = `rate_limit:window_start:${keyId}`
+
+      currentWindowCost = parseFloat((await client.get(costCountKey)) || '0')
+
+      // 获取窗口开始时间和计算剩余时间
+      const windowStart = await client.get(windowStartKey)
+      if (windowStart) {
+        const now = Date.now()
+        windowStartTime = parseInt(windowStart)
+        const windowDuration = rateLimitWindow * 60 * 1000 // 转换为毫秒
+        windowEndTime = windowStartTime + windowDuration
+
+        // 如果窗口还有效
+        if (now < windowEndTime) {
+          windowRemainingSeconds = Math.max(0, Math.floor((windowEndTime - now) / 1000))
+        } else {
+          // 窗口已过期
+          windowRemainingSeconds = 0
+          currentWindowCost = 0
+        }
+      }
+    }
+  } catch (error) {
+    logger.warn(`⚠️ 获取实时限制数据失败 (key: ${keyId}):`, error.message)
+  }
+
+  // 如果没有使用数据，返回零值但包含窗口数据
   if (uniqueKeys.length === 0) {
     return {
       requests: 0,
@@ -872,7 +1008,14 @@ async function calculateKeyStats(keyId, timeRange, startDate, endDate) {
       cacheCreateTokens: 0,
       cacheReadTokens: 0,
       cost: 0,
-      formattedCost: '$0.00'
+      formattedCost: '$0.00',
+      // 实时限制数据（始终返回，不受时间范围影响）
+      dailyCost,
+      currentWindowCost,
+      windowRemainingSeconds,
+      windowStartTime,
+      windowEndTime,
+      allTimeCost
     }
   }
 
@@ -887,12 +1030,10 @@ async function calculateKeyStats(keyId, timeRange, startDate, endDate) {
   const modelStatsMap = new Map()
   let totalRequests = 0
 
-  // 用于去重：只统计日数据，避免与月数据重复
+  // 用于去重：先统计月数据，避免与日数据重复
   const dailyKeyPattern = /usage:.+:model:daily:(.+):\d{4}-\d{2}-\d{2}$/
   const monthlyKeyPattern = /usage:.+:model:monthly:(.+):\d{4}-\d{2}$/
-
+  const currentMonth = `${tzDate.getUTCFullYear()}-${String(tzDate.getUTCMonth() + 1).padStart(2, '0')}`
-  // 检查是否有日数据
-  const hasDailyData = uniqueKeys.some((key) => dailyKeyPattern.test(key))
 
   for (let i = 0; i < results.length; i++) {
     const [err, data] = results[i]
@@ -919,8 +1060,12 @@ async function calculateKeyStats(keyId, timeRange, startDate, endDate) {
       continue
     }
 
-    // 如果有日数据，则跳过月数据以避免重复
+    // 跳过当前月的月数据
-    if (hasDailyData && isMonthly) {
+    if (isMonthly && key.includes(`:${currentMonth}`)) {
+      continue
+    }
+    // 跳过非当前月的日数据
+    if (!isMonthly && !key.includes(`:${currentMonth}-`)) {
       continue
     }
 
@@ -973,52 +1118,6 @@ async function calculateKeyStats(keyId, timeRange, startDate, endDate) {
 
   const tokens = inputTokens + outputTokens + cacheCreateTokens + cacheReadTokens
 
-  // 获取实时限制数据
-  let dailyCost = 0
-  let currentWindowCost = 0
-  let windowRemainingSeconds = null
-  let windowStartTime = null
-  let windowEndTime = null
-  let allTimeCost = 0
-
-  try {
-    // 获取当日费用
-    dailyCost = await redis.getDailyCost(keyId)
-
-    // 获取历史总费用（用于总费用限制进度条，不受时间范围影响）
-    const totalCostKey = `usage:cost:total:${keyId}`
-    allTimeCost = parseFloat((await client.get(totalCostKey)) || '0')
-
-    // 获取 API Key 配置信息以判断是否需要窗口数据
-    const apiKey = await redis.getApiKey(keyId)
-    if (apiKey && apiKey.rateLimitWindow > 0) {
-      const costCountKey = `rate_limit:cost:${keyId}`
-      const windowStartKey = `rate_limit:window_start:${keyId}`
-
-      currentWindowCost = parseFloat((await client.get(costCountKey)) || '0')
-
-      // 获取窗口开始时间和计算剩余时间
-      const windowStart = await client.get(windowStartKey)
-      if (windowStart) {
-        const now = Date.now()
-        windowStartTime = parseInt(windowStart)
-        const windowDuration = apiKey.rateLimitWindow * 60 * 1000 // 转换为毫秒
-        windowEndTime = windowStartTime + windowDuration
-
-        // 如果窗口还有效
-        if (now < windowEndTime) {
-          windowRemainingSeconds = Math.max(0, Math.floor((windowEndTime - now) / 1000))
-        } else {
-          // 窗口已过期
-          windowRemainingSeconds = 0
-          currentWindowCost = 0
-        }
-      }
-    }
-  } catch (error) {
-    logger.debug(`获取实时限制数据失败 (key: ${keyId}):`, error.message)
-  }
-
   return {
     requests: totalRequests,
     tokens,

src/routes/admin/claudeAccounts.js

@@ -9,6 +9,7 @@ const router = express.Router()
 const claudeAccountService = require('../../services/claudeAccountService')
 const claudeRelayService = require('../../services/claudeRelayService')
 const accountGroupService = require('../../services/accountGroupService')
+const accountTestSchedulerService = require('../../services/accountTestSchedulerService')
 const apiKeyService = require('../../services/apiKeyService')
 const redis = require('../../models/redis')
 const { authenticateAdmin } = require('../../middleware/auth')
@@ -277,7 +278,7 @@ router.post('/claude-accounts/oauth-with-cookie', authenticateAdmin, async (req,
 
     logger.info('🍪 Starting Cookie-based OAuth authorization', {
       sessionKeyLength: trimmedSessionKey.length,
-      sessionKeyPrefix: trimmedSessionKey.substring(0, 10) + '...',
+      sessionKeyPrefix: `${trimmedSessionKey.substring(0, 10)}...`,
       hasProxy: !!proxy
     })
 
@@ -326,7 +327,7 @@ router.post('/claude-accounts/setup-token-with-cookie', authenticateAdmin, async
 
     logger.info('🍪 Starting Cookie-based Setup Token authorization', {
       sessionKeyLength: trimmedSessionKey.length,
-      sessionKeyPrefix: trimmedSessionKey.substring(0, 10) + '...',
+      sessionKeyPrefix: `${trimmedSessionKey.substring(0, 10)}...`,
       hasProxy: !!proxy
     })
 
@@ -903,4 +904,219 @@ router.post('/claude-accounts/:accountId/test', authenticateAdmin, async (req, r
   }
 })
 
+// ============================================================================
+// 账户定时测试相关端点
+// ============================================================================
+
+// 获取账户测试历史
+router.get('/claude-accounts/:accountId/test-history', authenticateAdmin, async (req, res) => {
+  const { accountId } = req.params
+
+  try {
+    const history = await redis.getAccountTestHistory(accountId, 'claude')
+    return res.json({
+      success: true,
+      data: {
+        accountId,
+        platform: 'claude',
+        history
+      }
+    })
+  } catch (error) {
+    logger.error(`❌ Failed to get test history for account ${accountId}:`, error)
+    return res.status(500).json({
+      error: 'Failed to get test history',
+      message: error.message
+    })
+  }
+})
+
+// 获取账户定时测试配置
+router.get('/claude-accounts/:accountId/test-config', authenticateAdmin, async (req, res) => {
+  const { accountId } = req.params
+
+  try {
+    const testConfig = await redis.getAccountTestConfig(accountId, 'claude')
+    return res.json({
+      success: true,
+      data: {
+        accountId,
+        platform: 'claude',
+        config: testConfig || {
+          enabled: false,
+          cronExpression: '0 8 * * *',
+          model: 'claude-sonnet-4-5-20250929'
+        }
+      }
+    })
+  } catch (error) {
+    logger.error(`❌ Failed to get test config for account ${accountId}:`, error)
+    return res.status(500).json({
+      error: 'Failed to get test config',
+      message: error.message
+    })
+  }
+})
+
+// 设置账户定时测试配置
+router.put('/claude-accounts/:accountId/test-config', authenticateAdmin, async (req, res) => {
+  const { accountId } = req.params
+  const { enabled, cronExpression, model } = req.body
+
+  try {
+    // 验证 enabled 参数
+    if (typeof enabled !== 'boolean') {
+      return res.status(400).json({
+        error: 'Invalid parameter',
+        message: 'enabled must be a boolean'
+      })
+    }
+
+    // 验证 cronExpression 参数
+    if (!cronExpression || typeof cronExpression !== 'string') {
+      return res.status(400).json({
+        error: 'Invalid parameter',
+        message: 'cronExpression is required and must be a string'
+      })
+    }
+
+    // 限制 cronExpression 长度防止 DoS
+    const MAX_CRON_LENGTH = 100
+    if (cronExpression.length > MAX_CRON_LENGTH) {
+      return res.status(400).json({
+        error: 'Invalid parameter',
+        message: `cronExpression too long (max ${MAX_CRON_LENGTH} characters)`
+      })
+    }
+
+    // 使用 service 的方法验证 cron 表达式
+    if (!accountTestSchedulerService.validateCronExpression(cronExpression)) {
+      return res.status(400).json({
+        error: 'Invalid parameter',
+        message: `Invalid cron expression: ${cronExpression}. Format: "minute hour day month weekday" (e.g., "0 8 * * *" for daily at 8:00)`
+      })
+    }
+
+    // 验证模型参数
+    const testModel = model || 'claude-sonnet-4-5-20250929'
+    if (typeof testModel !== 'string' || testModel.length > 256) {
+      return res.status(400).json({
+        error: 'Invalid parameter',
+        message: 'model must be a valid string (max 256 characters)'
+      })
+    }
+
+    // 检查账户是否存在
+    const account = await claudeAccountService.getAccount(accountId)
+    if (!account) {
+      return res.status(404).json({
+        error: 'Account not found',
+        message: `Claude account ${accountId} not found`
+      })
+    }
+
+    // 保存配置
+    await redis.saveAccountTestConfig(accountId, 'claude', {
+      enabled,
+      cronExpression,
+      model: testModel
+    })
+
+    logger.success(
+      `📝 Updated test config for Claude account ${accountId}: enabled=${enabled}, cronExpression=${cronExpression}, model=${testModel}`
+    )
+
+    return res.json({
+      success: true,
+      message: 'Test config updated successfully',
+      data: {
+        accountId,
+        platform: 'claude',
+        config: { enabled, cronExpression, model: testModel }
+      }
+    })
+  } catch (error) {
+    logger.error(`❌ Failed to update test config for account ${accountId}:`, error)
+    return res.status(500).json({
+      error: 'Failed to update test config',
+      message: error.message
+    })
+  }
+})
+
+// 手动触发账户测试（非流式，返回JSON结果）
+router.post('/claude-accounts/:accountId/test-sync', authenticateAdmin, async (req, res) => {
+  const { accountId } = req.params
+
+  try {
+    // 检查账户是否存在
+    const account = await claudeAccountService.getAccount(accountId)
+    if (!account) {
+      return res.status(404).json({
+        error: 'Account not found',
+        message: `Claude account ${accountId} not found`
+      })
+    }
+
+    logger.info(`🧪 Manual sync test triggered for Claude account: ${accountId}`)
+
+    // 执行测试
+    const testResult = await claudeRelayService.testAccountConnectionSync(accountId)
+
+    // 保存测试结果到历史
+    await redis.saveAccountTestResult(accountId, 'claude', testResult)
+    await redis.setAccountLastTestTime(accountId, 'claude')
+
+    return res.json({
+      success: true,
+      data: {
+        accountId,
+        platform: 'claude',
+        result: testResult
+      }
+    })
+  } catch (error) {
+    logger.error(`❌ Failed to run sync test for account ${accountId}:`, error)
+    return res.status(500).json({
+      error: 'Failed to run test',
+      message: error.message
+    })
+  }
+})
+
+// 批量获取多个账户的测试历史
+router.post('/claude-accounts/batch-test-history', authenticateAdmin, async (req, res) => {
+  const { accountIds } = req.body
+
+  try {
+    if (!Array.isArray(accountIds) || accountIds.length === 0) {
+      return res.status(400).json({
+        error: 'Invalid parameter',
+        message: 'accountIds must be a non-empty array'
+      })
+    }
+
+    // 限制批量查询数量
+    const limitedIds = accountIds.slice(0, 100)
+
+    const accounts = limitedIds.map((accountId) => ({
+      accountId,
+      platform: 'claude'
+    }))
+
+    const historyMap = await redis.getAccountsTestHistory(accounts)
+
+    return res.json({
+      success: true,
+      data: historyMap
+    })
+  } catch (error) {
+    logger.error('❌ Failed to get batch test history:', error)
+    return res.status(500).json({
+      error: 'Failed to get batch test history',
+      message: error.message
+    })
+  }
+})
+
 module.exports = router

src/routes/admin/claudeRelayConfig.js

@@ -0,0 +1,239 @@
+/**
+ * Claude 转发配置 API 路由
+ * 管理全局 Claude Code 限制和会话绑定配置
+ */
+
+const express = require('express')
+const { authenticateAdmin } = require('../../middleware/auth')
+const claudeRelayConfigService = require('../../services/claudeRelayConfigService')
+const logger = require('../../utils/logger')
+
+const router = express.Router()
+
+/**
+ * GET /admin/claude-relay-config
+ * 获取 Claude 转发配置
+ */
+router.get('/claude-relay-config', authenticateAdmin, async (req, res) => {
+  try {
+    const config = await claudeRelayConfigService.getConfig()
+    return res.json({
+      success: true,
+      config
+    })
+  } catch (error) {
+    logger.error('❌ Failed to get Claude relay config:', error)
+    return res.status(500).json({
+      error: 'Failed to get configuration',
+      message: error.message
+    })
+  }
+})
+
+/**
+ * PUT /admin/claude-relay-config
+ * 更新 Claude 转发配置
+ */
+router.put('/claude-relay-config', authenticateAdmin, async (req, res) => {
+  try {
+    const {
+      claudeCodeOnlyEnabled,
+      globalSessionBindingEnabled,
+      sessionBindingErrorMessage,
+      sessionBindingTtlDays,
+      userMessageQueueEnabled,
+      userMessageQueueDelayMs,
+      userMessageQueueTimeoutMs,
+      concurrentRequestQueueEnabled,
+      concurrentRequestQueueMaxSize,
+      concurrentRequestQueueMaxSizeMultiplier,
+      concurrentRequestQueueTimeoutMs
+    } = req.body
+
+    // 验证输入
+    if (claudeCodeOnlyEnabled !== undefined && typeof claudeCodeOnlyEnabled !== 'boolean') {
+      return res.status(400).json({ error: 'claudeCodeOnlyEnabled must be a boolean' })
+    }
+
+    if (
+      globalSessionBindingEnabled !== undefined &&
+      typeof globalSessionBindingEnabled !== 'boolean'
+    ) {
+      return res.status(400).json({ error: 'globalSessionBindingEnabled must be a boolean' })
+    }
+
+    if (sessionBindingErrorMessage !== undefined) {
+      if (typeof sessionBindingErrorMessage !== 'string') {
+        return res.status(400).json({ error: 'sessionBindingErrorMessage must be a string' })
+      }
+      if (sessionBindingErrorMessage.length > 500) {
+        return res
+          .status(400)
+          .json({ error: 'sessionBindingErrorMessage must be less than 500 characters' })
+      }
+    }
+
+    if (sessionBindingTtlDays !== undefined) {
+      if (
+        typeof sessionBindingTtlDays !== 'number' ||
+        sessionBindingTtlDays < 1 ||
+        sessionBindingTtlDays > 365
+      ) {
+        return res
+          .status(400)
+          .json({ error: 'sessionBindingTtlDays must be a number between 1 and 365' })
+      }
+    }
+
+    // 验证用户消息队列配置
+    if (userMessageQueueEnabled !== undefined && typeof userMessageQueueEnabled !== 'boolean') {
+      return res.status(400).json({ error: 'userMessageQueueEnabled must be a boolean' })
+    }
+
+    if (userMessageQueueDelayMs !== undefined) {
+      if (
+        typeof userMessageQueueDelayMs !== 'number' ||
+        userMessageQueueDelayMs < 0 ||
+        userMessageQueueDelayMs > 10000
+      ) {
+        return res
+          .status(400)
+          .json({ error: 'userMessageQueueDelayMs must be a number between 0 and 10000' })
+      }
+    }
+
+    if (userMessageQueueTimeoutMs !== undefined) {
+      if (
+        typeof userMessageQueueTimeoutMs !== 'number' ||
+        userMessageQueueTimeoutMs < 1000 ||
+        userMessageQueueTimeoutMs > 300000
+      ) {
+        return res
+          .status(400)
+          .json({ error: 'userMessageQueueTimeoutMs must be a number between 1000 and 300000' })
+      }
+    }
+
+    // 验证并发请求排队配置
+    if (
+      concurrentRequestQueueEnabled !== undefined &&
+      typeof concurrentRequestQueueEnabled !== 'boolean'
+    ) {
+      return res.status(400).json({ error: 'concurrentRequestQueueEnabled must be a boolean' })
+    }
+
+    if (concurrentRequestQueueMaxSize !== undefined) {
+      if (
+        typeof concurrentRequestQueueMaxSize !== 'number' ||
+        !Number.isInteger(concurrentRequestQueueMaxSize) ||
+        concurrentRequestQueueMaxSize < 1 ||
+        concurrentRequestQueueMaxSize > 100
+      ) {
+        return res
+          .status(400)
+          .json({ error: 'concurrentRequestQueueMaxSize must be an integer between 1 and 100' })
+      }
+    }
+
+    if (concurrentRequestQueueMaxSizeMultiplier !== undefined) {
+      // 使用 Number.isFinite() 同时排除 NaN、Infinity、-Infinity 和非数字类型
+      if (
+        !Number.isFinite(concurrentRequestQueueMaxSizeMultiplier) ||
+        concurrentRequestQueueMaxSizeMultiplier < 0 ||
+        concurrentRequestQueueMaxSizeMultiplier > 10
+      ) {
+        return res.status(400).json({
+          error: 'concurrentRequestQueueMaxSizeMultiplier must be a finite number between 0 and 10'
+        })
+      }
+    }
+
+    if (concurrentRequestQueueTimeoutMs !== undefined) {
+      if (
+        typeof concurrentRequestQueueTimeoutMs !== 'number' ||
+        !Number.isInteger(concurrentRequestQueueTimeoutMs) ||
+        concurrentRequestQueueTimeoutMs < 5000 ||
+        concurrentRequestQueueTimeoutMs > 300000
+      ) {
+        return res.status(400).json({
+          error:
+            'concurrentRequestQueueTimeoutMs must be an integer between 5000 and 300000 (5 seconds to 5 minutes)'
+        })
+      }
+    }
+
+    const updateData = {}
+    if (claudeCodeOnlyEnabled !== undefined) {
+      updateData.claudeCodeOnlyEnabled = claudeCodeOnlyEnabled
+    }
+    if (globalSessionBindingEnabled !== undefined) {
+      updateData.globalSessionBindingEnabled = globalSessionBindingEnabled
+    }
+    if (sessionBindingErrorMessage !== undefined) {
+      updateData.sessionBindingErrorMessage = sessionBindingErrorMessage
+    }
+    if (sessionBindingTtlDays !== undefined) {
+      updateData.sessionBindingTtlDays = sessionBindingTtlDays
+    }
+    if (userMessageQueueEnabled !== undefined) {
+      updateData.userMessageQueueEnabled = userMessageQueueEnabled
+    }
+    if (userMessageQueueDelayMs !== undefined) {
+      updateData.userMessageQueueDelayMs = userMessageQueueDelayMs
+    }
+    if (userMessageQueueTimeoutMs !== undefined) {
+      updateData.userMessageQueueTimeoutMs = userMessageQueueTimeoutMs
+    }
+    if (concurrentRequestQueueEnabled !== undefined) {
+      updateData.concurrentRequestQueueEnabled = concurrentRequestQueueEnabled
+    }
+    if (concurrentRequestQueueMaxSize !== undefined) {
+      updateData.concurrentRequestQueueMaxSize = concurrentRequestQueueMaxSize
+    }
+    if (concurrentRequestQueueMaxSizeMultiplier !== undefined) {
+      updateData.concurrentRequestQueueMaxSizeMultiplier = concurrentRequestQueueMaxSizeMultiplier
+    }
+    if (concurrentRequestQueueTimeoutMs !== undefined) {
+      updateData.concurrentRequestQueueTimeoutMs = concurrentRequestQueueTimeoutMs
+    }
+
+    const updatedConfig = await claudeRelayConfigService.updateConfig(
+      updateData,
+      req.admin?.username || 'unknown'
+    )
+
+    return res.json({
+      success: true,
+      message: 'Configuration updated successfully',
+      config: updatedConfig
+    })
+  } catch (error) {
+    logger.error('❌ Failed to update Claude relay config:', error)
+    return res.status(500).json({
+      error: 'Failed to update configuration',
+      message: error.message
+    })
+  }
+})
+
+/**
+ * GET /admin/claude-relay-config/session-bindings
+ * 获取会话绑定统计
+ */
+router.get('/claude-relay-config/session-bindings', authenticateAdmin, async (req, res) => {
+  try {
+    const stats = await claudeRelayConfigService.getSessionBindingStats()
+    return res.json({
+      success: true,
+      data: stats
+    })
+  } catch (error) {
+    logger.error('❌ Failed to get session binding stats:', error)
+    return res.status(500).json({
+      error: 'Failed to get session binding statistics',
+      message: error.message
+    })
+  }
+})
+
+module.exports = router

src/routes/admin/concurrency.js

@@ -0,0 +1,313 @@
+/**
+ * 并发管理 API 路由
+ * 提供并发状态查看和手动清理功能
+ */
+
+const express = require('express')
+const router = express.Router()
+const redis = require('../../models/redis')
+const logger = require('../../utils/logger')
+const { authenticateAdmin } = require('../../middleware/auth')
+const { calculateWaitTimeStats } = require('../../utils/statsHelper')
+
+/**
+ * GET /admin/concurrency
+ * 获取所有并发状态
+ */
+router.get('/concurrency', authenticateAdmin, async (req, res) => {
+  try {
+    const status = await redis.getAllConcurrencyStatus()
+
+    // 为每个 API Key 获取排队计数
+    const statusWithQueue = await Promise.all(
+      status.map(async (s) => {
+        const queueCount = await redis.getConcurrencyQueueCount(s.apiKeyId)
+        return {
+          ...s,
+          queueCount
+        }
+      })
+    )
+
+    // 计算汇总统计
+    const summary = {
+      totalKeys: statusWithQueue.length,
+      totalActiveRequests: statusWithQueue.reduce((sum, s) => sum + s.activeCount, 0),
+      totalExpiredRequests: statusWithQueue.reduce((sum, s) => sum + s.expiredCount, 0),
+      totalQueuedRequests: statusWithQueue.reduce((sum, s) => sum + s.queueCount, 0)
+    }
+
+    res.json({
+      success: true,
+      summary,
+      concurrencyStatus: statusWithQueue
+    })
+  } catch (error) {
+    logger.error('❌ Failed to get concurrency status:', error)
+    res.status(500).json({
+      success: false,
+      error: 'Failed to get concurrency status',
+      message: error.message
+    })
+  }
+})
+
+/**
+ * GET /admin/concurrency-queue/stats
+ * 获取排队统计信息
+ */
+router.get('/concurrency-queue/stats', authenticateAdmin, async (req, res) => {
+  try {
+    // 获取所有有统计数据的 API Key
+    const statsKeys = await redis.scanConcurrencyQueueStatsKeys()
+    const queueKeys = await redis.scanConcurrencyQueueKeys()
+
+    // 合并所有相关的 API Key
+    const allApiKeyIds = [...new Set([...statsKeys, ...queueKeys])]
+
+    // 获取各 API Key 的详细统计
+    const perKeyStats = await Promise.all(
+      allApiKeyIds.map(async (apiKeyId) => {
+        const [queueCount, stats, waitTimes] = await Promise.all([
+          redis.getConcurrencyQueueCount(apiKeyId),
+          redis.getConcurrencyQueueStats(apiKeyId),
+          redis.getQueueWaitTimes(apiKeyId)
+        ])
+
+        return {
+          apiKeyId,
+          currentQueueCount: queueCount,
+          stats,
+          waitTimeStats: calculateWaitTimeStats(waitTimes)
+        }
+      })
+    )
+
+    // 获取全局等待时间统计
+    const globalWaitTimes = await redis.getGlobalQueueWaitTimes()
+    const globalWaitTimeStats = calculateWaitTimeStats(globalWaitTimes)
+
+    // 计算全局汇总
+    const globalStats = {
+      totalEntered: perKeyStats.reduce((sum, s) => sum + s.stats.entered, 0),
+      totalSuccess: perKeyStats.reduce((sum, s) => sum + s.stats.success, 0),
+      totalTimeout: perKeyStats.reduce((sum, s) => sum + s.stats.timeout, 0),
+      totalCancelled: perKeyStats.reduce((sum, s) => sum + s.stats.cancelled, 0),
+      totalSocketChanged: perKeyStats.reduce((sum, s) => sum + (s.stats.socket_changed || 0), 0),
+      totalRejectedOverload: perKeyStats.reduce(
+        (sum, s) => sum + (s.stats.rejected_overload || 0),
+        0
+      ),
+      currentTotalQueued: perKeyStats.reduce((sum, s) => sum + s.currentQueueCount, 0),
+      // 队列资源利用率指标
+      peakQueueSize:
+        perKeyStats.length > 0 ? Math.max(...perKeyStats.map((s) => s.currentQueueCount)) : 0,
+      avgQueueSize:
+        perKeyStats.length > 0
+          ? Math.round(
+              perKeyStats.reduce((sum, s) => sum + s.currentQueueCount, 0) / perKeyStats.length
+            )
+          : 0,
+      activeApiKeys: perKeyStats.filter((s) => s.currentQueueCount > 0).length
+    }
+
+    // 计算成功率
+    if (globalStats.totalEntered > 0) {
+      globalStats.successRate = Math.round(
+        (globalStats.totalSuccess / globalStats.totalEntered) * 100
+      )
+      globalStats.timeoutRate = Math.round(
+        (globalStats.totalTimeout / globalStats.totalEntered) * 100
+      )
+      globalStats.cancelledRate = Math.round(
+        (globalStats.totalCancelled / globalStats.totalEntered) * 100
+      )
+    }
+
+    // 从全局等待时间统计中提取关键指标
+    if (globalWaitTimeStats) {
+      globalStats.avgWaitTimeMs = globalWaitTimeStats.avg
+      globalStats.p50WaitTimeMs = globalWaitTimeStats.p50
+      globalStats.p90WaitTimeMs = globalWaitTimeStats.p90
+      globalStats.p99WaitTimeMs = globalWaitTimeStats.p99
+      // 多实例采样策略标记（详见 design.md Decision 9）
+      // 全局 P90 仅用于可视化和监控，不用于系统决策
+      // 健康检查使用 API Key 级别的 P90（每 Key 独立采样）
+      globalWaitTimeStats.globalP90ForVisualizationOnly = true
+    }
+
+    res.json({
+      success: true,
+      globalStats,
+      globalWaitTimeStats,
+      perKeyStats
+    })
+  } catch (error) {
+    logger.error('❌ Failed to get queue stats:', error)
+    res.status(500).json({
+      success: false,
+      error: 'Failed to get queue stats',
+      message: error.message
+    })
+  }
+})
+
+/**
+ * DELETE /admin/concurrency-queue/:apiKeyId
+ * 清理特定 API Key 的排队计数
+ */
+router.delete('/concurrency-queue/:apiKeyId', authenticateAdmin, async (req, res) => {
+  try {
+    const { apiKeyId } = req.params
+    await redis.clearConcurrencyQueue(apiKeyId)
+
+    logger.warn(`🧹 Admin ${req.admin?.username || 'unknown'} cleared queue for key ${apiKeyId}`)
+
+    res.json({
+      success: true,
+      message: `Successfully cleared queue for API key ${apiKeyId}`
+    })
+  } catch (error) {
+    logger.error(`❌ Failed to clear queue for ${req.params.apiKeyId}:`, error)
+    res.status(500).json({
+      success: false,
+      error: 'Failed to clear queue',
+      message: error.message
+    })
+  }
+})
+
+/**
+ * DELETE /admin/concurrency-queue
+ * 清理所有排队计数
+ */
+router.delete('/concurrency-queue', authenticateAdmin, async (req, res) => {
+  try {
+    const cleared = await redis.clearAllConcurrencyQueues()
+
+    logger.warn(`🧹 Admin ${req.admin?.username || 'unknown'} cleared ALL queues`)
+
+    res.json({
+      success: true,
+      message: 'Successfully cleared all queues',
+      cleared
+    })
+  } catch (error) {
+    logger.error('❌ Failed to clear all queues:', error)
+    res.status(500).json({
+      success: false,
+      error: 'Failed to clear all queues',
+      message: error.message
+    })
+  }
+})
+
+/**
+ * GET /admin/concurrency/:apiKeyId
+ * 获取特定 API Key 的并发状态详情
+ */
+router.get('/concurrency/:apiKeyId', authenticateAdmin, async (req, res) => {
+  try {
+    const { apiKeyId } = req.params
+    const status = await redis.getConcurrencyStatus(apiKeyId)
+    const queueCount = await redis.getConcurrencyQueueCount(apiKeyId)
+
+    res.json({
+      success: true,
+      concurrencyStatus: {
+        ...status,
+        queueCount
+      }
+    })
+  } catch (error) {
+    logger.error(`❌ Failed to get concurrency status for ${req.params.apiKeyId}:`, error)
+    res.status(500).json({
+      success: false,
+      error: 'Failed to get concurrency status',
+      message: error.message
+    })
+  }
+})
+
+/**
+ * DELETE /admin/concurrency/:apiKeyId
+ * 强制清理特定 API Key 的并发计数
+ */
+router.delete('/concurrency/:apiKeyId', authenticateAdmin, async (req, res) => {
+  try {
+    const { apiKeyId } = req.params
+    const result = await redis.forceClearConcurrency(apiKeyId)
+
+    logger.warn(
+      `🧹 Admin ${req.admin?.username || 'unknown'} force cleared concurrency for key ${apiKeyId}`
+    )
+
+    res.json({
+      success: true,
+      message: `Successfully cleared concurrency for API key ${apiKeyId}`,
+      result
+    })
+  } catch (error) {
+    logger.error(`❌ Failed to clear concurrency for ${req.params.apiKeyId}:`, error)
+    res.status(500).json({
+      success: false,
+      error: 'Failed to clear concurrency',
+      message: error.message
+    })
+  }
+})
+
+/**
+ * DELETE /admin/concurrency
+ * 强制清理所有并发计数
+ */
+router.delete('/concurrency', authenticateAdmin, async (req, res) => {
+  try {
+    const result = await redis.forceClearAllConcurrency()
+
+    logger.warn(`🧹 Admin ${req.admin?.username || 'unknown'} force cleared ALL concurrency`)
+
+    res.json({
+      success: true,
+      message: 'Successfully cleared all concurrency',
+      result
+    })
+  } catch (error) {
+    logger.error('❌ Failed to clear all concurrency:', error)
+    res.status(500).json({
+      success: false,
+      error: 'Failed to clear all concurrency',
+      message: error.message
+    })
+  }
+})
+
+/**
+ * POST /admin/concurrency/cleanup
+ * 清理过期的并发条目（不影响活跃请求）
+ */
+router.post('/concurrency/cleanup', authenticateAdmin, async (req, res) => {
+  try {
+    const { apiKeyId } = req.body
+    const result = await redis.cleanupExpiredConcurrency(apiKeyId || null)
+
+    logger.info(`🧹 Admin ${req.admin?.username || 'unknown'} cleaned up expired concurrency`)
+
+    res.json({
+      success: true,
+      message: apiKeyId
+        ? `Successfully cleaned up expired concurrency for API key ${apiKeyId}`
+        : 'Successfully cleaned up all expired concurrency',
+      result
+    })
+  } catch (error) {
+    logger.error('❌ Failed to cleanup expired concurrency:', error)
+    res.status(500).json({
+      success: false,
+      error: 'Failed to cleanup expired concurrency',
+      message: error.message
+    })
+  }
+})
+
+module.exports = router

src/routes/admin/index.js

@@ -22,6 +22,8 @@ const droidAccountsRoutes = require('./droidAccounts')
 const dashboardRoutes = require('./dashboard')
 const usageStatsRoutes = require('./usageStats')
 const systemRoutes = require('./system')
+const concurrencyRoutes = require('./concurrency')
+const claudeRelayConfigRoutes = require('./claudeRelayConfig')
 
 // 挂载所有子路由
 // 使用完整路径的模块（直接挂载到根路径）
@@ -35,6 +37,8 @@ router.use('/', droidAccountsRoutes)
 router.use('/', dashboardRoutes)
 router.use('/', usageStatsRoutes)
 router.use('/', systemRoutes)
+router.use('/', concurrencyRoutes)
+router.use('/', claudeRelayConfigRoutes)
 
 // 使用相对路径的模块（需要指定基础路径前缀）
 router.use('/account-groups', accountGroupsRoutes)

src/routes/admin/usageStats.js

@@ -1,8 +1,10 @@
 const express = require('express')
 const apiKeyService = require('../../services/apiKeyService')
+const ccrAccountService = require('../../services/ccrAccountService')
 const claudeAccountService = require('../../services/claudeAccountService')
 const claudeConsoleAccountService = require('../../services/claudeConsoleAccountService')
 const geminiAccountService = require('../../services/geminiAccountService')
+const geminiApiAccountService = require('../../services/geminiApiAccountService')
 const openaiAccountService = require('../../services/openaiAccountService')
 const openaiResponsesAccountService = require('../../services/openaiResponsesAccountService')
 const droidAccountService = require('../../services/droidAccountService')
@@ -14,6 +16,65 @@ const pricingService = require('../../services/pricingService')
 
 const router = express.Router()
 
+const accountTypeNames = {
+  claude: 'Claude官方',
+  'claude-console': 'Claude Console',
+  ccr: 'Claude Console Relay',
+  openai: 'OpenAI',
+  'openai-responses': 'OpenAI Responses',
+  gemini: 'Gemini',
+  'gemini-api': 'Gemini API',
+  droid: 'Droid',
+  unknown: '未知渠道'
+}
+
+const resolveAccountByPlatform = async (accountId, platform) => {
+  const serviceMap = {
+    claude: claudeAccountService,
+    'claude-console': claudeConsoleAccountService,
+    gemini: geminiAccountService,
+    'gemini-api': geminiApiAccountService,
+    openai: openaiAccountService,
+    'openai-responses': openaiResponsesAccountService,
+    droid: droidAccountService,
+    ccr: ccrAccountService
+  }
+
+  if (platform && serviceMap[platform]) {
+    try {
+      const account = await serviceMap[platform].getAccount(accountId)
+      if (account) {
+        return { ...account, platform }
+      }
+    } catch (error) {
+      logger.debug(`⚠️ Failed to get account ${accountId} from ${platform}: ${error.message}`)
+    }
+  }
+
+  for (const [platformName, service] of Object.entries(serviceMap)) {
+    try {
+      const account = await service.getAccount(accountId)
+      if (account) {
+        return { ...account, platform: platformName }
+      }
+    } catch (error) {
+      logger.debug(`⚠️ Failed to get account ${accountId} from ${platformName}: ${error.message}`)
+    }
+  }
+
+  return null
+}
+
+const getApiKeyName = async (keyId) => {
+  try {
+    const keyData = await redis.getApiKey(keyId)
+    return keyData?.name || keyData?.label || keyId
+  } catch (error) {
+    logger.debug(`⚠️ Failed to get API key name for ${keyId}: ${error.message}`)
+    return keyId
+  }
+}
+
 // 📊 账户使用统计
 
 // 获取所有账户的使用统计
@@ -148,7 +209,6 @@ router.get('/accounts/:accountId/usage-history', authenticateAdmin, async (req,
           accountData = await geminiAccountService.getAccount(accountId)
           break
         case 'gemini-api': {
-          const geminiApiAccountService = require('../../services/geminiApiAccountService')
           accountData = await geminiApiAccountService.getAccount(accountId)
           break
         }
@@ -369,7 +429,9 @@ router.get('/usage-trend', authenticateAdmin, async (req, res) => {
         logger.info(`  endDate (raw): ${endDate}`)
         logger.info(`  startTime (parsed): ${startTime.toISOString()}`)
         logger.info(`  endTime (parsed): ${endTime.toISOString()}`)
-        logger.info(`  System timezone offset: ${require('../../../config/config').system.timezoneOffset || 8}`)
+        logger.info(
+          `  System timezone offset: ${require('../../../config/config').system.timezoneOffset || 8}`
+        )
       } else {
         // 默认最近24小时
         endTime = new Date()
@@ -890,7 +952,6 @@ router.get('/account-usage-trend', authenticateAdmin, async (req, res) => {
         })
       ]
     } else if (group === 'gemini') {
-      const geminiApiAccountService = require('../../services/geminiApiAccountService')
       const [geminiAccounts, geminiApiAccounts] = await Promise.all([
         geminiAccountService.getAllAccounts(),
         geminiApiAccountService.getAllAccounts(true)
@@ -1818,4 +1879,628 @@ router.get('/usage-costs', authenticateAdmin, async (req, res) => {
   }
 })
 
+// 获取 API Key 的请求记录时间线
+router.get('/api-keys/:keyId/usage-records', authenticateAdmin, async (req, res) => {
+  try {
+    const { keyId } = req.params
+    const {
+      page = 1,
+      pageSize = 50,
+      startDate,
+      endDate,
+      model,
+      accountId,
+      sortOrder = 'desc'
+    } = req.query
+
+    const pageNumber = Math.max(parseInt(page, 10) || 1, 1)
+    const pageSizeNumber = Math.min(Math.max(parseInt(pageSize, 10) || 50, 1), 200)
+    const normalizedSortOrder = sortOrder === 'asc' ? 'asc' : 'desc'
+
+    const startTime = startDate ? new Date(startDate) : null
+    const endTime = endDate ? new Date(endDate) : null
+
+    if (
+      (startDate && Number.isNaN(startTime?.getTime())) ||
+      (endDate && Number.isNaN(endTime?.getTime()))
+    ) {
+      return res.status(400).json({ success: false, error: 'Invalid date range' })
+    }
+
+    if (startTime && endTime && startTime > endTime) {
+      return res
+        .status(400)
+        .json({ success: false, error: 'Start date must be before or equal to end date' })
+    }
+
+    const apiKeyInfo = await redis.getApiKey(keyId)
+    if (!apiKeyInfo || Object.keys(apiKeyInfo).length === 0) {
+      return res.status(404).json({ success: false, error: 'API key not found' })
+    }
+
+    const rawRecords = await redis.getUsageRecords(keyId, 5000)
+
+    const accountServices = [
+      { type: 'claude', getter: (id) => claudeAccountService.getAccount(id) },
+      { type: 'claude-console', getter: (id) => claudeConsoleAccountService.getAccount(id) },
+      { type: 'ccr', getter: (id) => ccrAccountService.getAccount(id) },
+      { type: 'openai', getter: (id) => openaiAccountService.getAccount(id) },
+      { type: 'openai-responses', getter: (id) => openaiResponsesAccountService.getAccount(id) },
+      { type: 'gemini', getter: (id) => geminiAccountService.getAccount(id) },
+      { type: 'gemini-api', getter: (id) => geminiApiAccountService.getAccount(id) },
+      { type: 'droid', getter: (id) => droidAccountService.getAccount(id) }
+    ]
+
+    const accountCache = new Map()
+    const resolveAccountInfo = async (id, type) => {
+      if (!id) {
+        return null
+      }
+
+      const cacheKey = `${type || 'any'}:${id}`
+      if (accountCache.has(cacheKey)) {
+        return accountCache.get(cacheKey)
+      }
+
+      let servicesToTry = type
+        ? accountServices.filter((svc) => svc.type === type)
+        : accountServices
+
+      // 若渠道改名或传入未知类型，回退尝试全量服务，避免漏解析历史账号
+      if (!servicesToTry.length) {
+        servicesToTry = accountServices
+      }
+
+      for (const service of servicesToTry) {
+        try {
+          const account = await service.getter(id)
+          if (account) {
+            const info = {
+              id,
+              name: account.name || account.email || id,
+              type: service.type,
+              status: account.status || account.isActive
+            }
+            accountCache.set(cacheKey, info)
+            return info
+          }
+        } catch (error) {
+          logger.debug(`⚠️ Failed to resolve account ${id} via ${service.type}: ${error.message}`)
+        }
+      }
+
+      accountCache.set(cacheKey, null)
+      return null
+    }
+
+    const toUsageObject = (record) => ({
+      input_tokens: record.inputTokens || 0,
+      output_tokens: record.outputTokens || 0,
+      cache_creation_input_tokens: record.cacheCreateTokens || 0,
+      cache_read_input_tokens: record.cacheReadTokens || 0,
+      cache_creation: record.cacheCreation || record.cache_creation || null
+    })
+
+    const withinRange = (record) => {
+      if (!record.timestamp) {
+        return false
+      }
+      const ts = new Date(record.timestamp)
+      if (Number.isNaN(ts.getTime())) {
+        return false
+      }
+      if (startTime && ts < startTime) {
+        return false
+      }
+      if (endTime && ts > endTime) {
+        return false
+      }
+      return true
+    }
+
+    const filteredRecords = rawRecords.filter((record) => {
+      if (!withinRange(record)) {
+        return false
+      }
+      if (model && record.model !== model) {
+        return false
+      }
+      if (accountId && record.accountId !== accountId) {
+        return false
+      }
+      return true
+    })
+
+    filteredRecords.sort((a, b) => {
+      const aTime = new Date(a.timestamp).getTime()
+      const bTime = new Date(b.timestamp).getTime()
+      if (Number.isNaN(aTime) || Number.isNaN(bTime)) {
+        return 0
+      }
+      return normalizedSortOrder === 'asc' ? aTime - bTime : bTime - aTime
+    })
+
+    const summary = {
+      totalRequests: 0,
+      inputTokens: 0,
+      outputTokens: 0,
+      cacheCreateTokens: 0,
+      cacheReadTokens: 0,
+      totalTokens: 0,
+      totalCost: 0
+    }
+
+    const modelSet = new Set()
+    const accountOptionMap = new Map()
+    let earliestTimestamp = null
+    let latestTimestamp = null
+
+    for (const record of filteredRecords) {
+      const usage = toUsageObject(record)
+      const costData = CostCalculator.calculateCost(usage, record.model || 'unknown')
+      const computedCost =
+        typeof record.cost === 'number' ? record.cost : costData?.costs?.total || 0
+      const totalTokens =
+        record.totalTokens ||
+        usage.input_tokens +
+          usage.output_tokens +
+          usage.cache_creation_input_tokens +
+          usage.cache_read_input_tokens
+
+      summary.totalRequests += 1
+      summary.inputTokens += usage.input_tokens
+      summary.outputTokens += usage.output_tokens
+      summary.cacheCreateTokens += usage.cache_creation_input_tokens
+      summary.cacheReadTokens += usage.cache_read_input_tokens
+      summary.totalTokens += totalTokens
+      summary.totalCost += computedCost
+
+      if (record.model) {
+        modelSet.add(record.model)
+      }
+
+      if (record.accountId) {
+        const normalizedType = record.accountType || 'unknown'
+        if (!accountOptionMap.has(record.accountId)) {
+          accountOptionMap.set(record.accountId, {
+            id: record.accountId,
+            accountTypes: new Set([normalizedType])
+          })
+        } else {
+          accountOptionMap.get(record.accountId).accountTypes.add(normalizedType)
+        }
+      }
+
+      if (record.timestamp) {
+        const ts = new Date(record.timestamp)
+        if (!Number.isNaN(ts.getTime())) {
+          if (!earliestTimestamp || ts < earliestTimestamp) {
+            earliestTimestamp = ts
+          }
+          if (!latestTimestamp || ts > latestTimestamp) {
+            latestTimestamp = ts
+          }
+        }
+      }
+    }
+
+    const totalRecords = filteredRecords.length
+    const totalPages = totalRecords > 0 ? Math.ceil(totalRecords / pageSizeNumber) : 0
+    const safePage = totalPages > 0 ? Math.min(pageNumber, totalPages) : 1
+    const startIndex = (safePage - 1) * pageSizeNumber
+    const pageRecords =
+      totalRecords === 0 ? [] : filteredRecords.slice(startIndex, startIndex + pageSizeNumber)
+
+    const enrichedRecords = []
+    for (const record of pageRecords) {
+      const usage = toUsageObject(record)
+      const costData = CostCalculator.calculateCost(usage, record.model || 'unknown')
+      const computedCost =
+        typeof record.cost === 'number' ? record.cost : costData?.costs?.total || 0
+      const totalTokens =
+        record.totalTokens ||
+        usage.input_tokens +
+          usage.output_tokens +
+          usage.cache_creation_input_tokens +
+          usage.cache_read_input_tokens
+
+      const accountInfo = await resolveAccountInfo(record.accountId, record.accountType)
+      const resolvedAccountType = accountInfo?.type || record.accountType || 'unknown'
+
+      enrichedRecords.push({
+        timestamp: record.timestamp,
+        model: record.model || 'unknown',
+        accountId: record.accountId || null,
+        accountName: accountInfo?.name || null,
+        accountStatus: accountInfo?.status ?? null,
+        accountType: resolvedAccountType,
+        accountTypeName: accountTypeNames[resolvedAccountType] || '未知渠道',
+        inputTokens: usage.input_tokens,
+        outputTokens: usage.output_tokens,
+        cacheCreateTokens: usage.cache_creation_input_tokens,
+        cacheReadTokens: usage.cache_read_input_tokens,
+        ephemeral5mTokens: record.ephemeral5mTokens || 0,
+        ephemeral1hTokens: record.ephemeral1hTokens || 0,
+        totalTokens,
+        isLongContextRequest: record.isLongContext || record.isLongContextRequest || false,
+        cost: Number(computedCost.toFixed(6)),
+        costFormatted:
+          record.costFormatted ||
+          costData?.formatted?.total ||
+          CostCalculator.formatCost(computedCost),
+        costBreakdown: record.costBreakdown || {
+          input: costData?.costs?.input || 0,
+          output: costData?.costs?.output || 0,
+          cacheCreate: costData?.costs?.cacheWrite || 0,
+          cacheRead: costData?.costs?.cacheRead || 0,
+          total: costData?.costs?.total || computedCost
+        },
+        responseTime: record.responseTime || null
+      })
+    }
+
+    const accountOptions = []
+    for (const option of accountOptionMap.values()) {
+      const types = Array.from(option.accountTypes || [])
+
+      // 优先按历史出现的 accountType 解析，若失败则回退全量解析
+      let resolvedInfo = null
+      for (const type of types) {
+        resolvedInfo = await resolveAccountInfo(option.id, type)
+        if (resolvedInfo && resolvedInfo.name) {
+          break
+        }
+      }
+      if (!resolvedInfo) {
+        resolvedInfo = await resolveAccountInfo(option.id)
+      }
+
+      const chosenType = resolvedInfo?.type || types[0] || 'unknown'
+      const chosenTypeName = accountTypeNames[chosenType] || '未知渠道'
+
+      if (!resolvedInfo) {
+        logger.warn(`⚠️ 保留无法解析的账户筛选项: ${option.id}, types=${types.join(',') || 'none'}`)
+      }
+
+      accountOptions.push({
+        id: option.id,
+        name: resolvedInfo?.name || option.id,
+        accountType: chosenType,
+        accountTypeName: chosenTypeName,
+        rawTypes: types
+      })
+    }
+
+    return res.json({
+      success: true,
+      data: {
+        records: enrichedRecords,
+        pagination: {
+          currentPage: safePage,
+          pageSize: pageSizeNumber,
+          totalRecords,
+          totalPages,
+          hasNextPage: totalPages > 0 && safePage < totalPages,
+          hasPreviousPage: totalPages > 0 && safePage > 1
+        },
+        filters: {
+          startDate: startTime ? startTime.toISOString() : null,
+          endDate: endTime ? endTime.toISOString() : null,
+          model: model || null,
+          accountId: accountId || null,
+          sortOrder: normalizedSortOrder
+        },
+        apiKeyInfo: {
+          id: keyId,
+          name: apiKeyInfo.name || apiKeyInfo.label || keyId
+        },
+        summary: {
+          ...summary,
+          totalCost: Number(summary.totalCost.toFixed(6)),
+          avgCost:
+            summary.totalRequests > 0
+              ? Number((summary.totalCost / summary.totalRequests).toFixed(6))
+              : 0
+        },
+        availableFilters: {
+          models: Array.from(modelSet),
+          accounts: accountOptions,
+          dateRange: {
+            earliest: earliestTimestamp ? earliestTimestamp.toISOString() : null,
+            latest: latestTimestamp ? latestTimestamp.toISOString() : null
+          }
+        }
+      }
+    })
+  } catch (error) {
+    logger.error('❌ Failed to get API key usage records:', error)
+    return res
+      .status(500)
+      .json({ error: 'Failed to get API key usage records', message: error.message })
+  }
+})
+
+// 获取账户的请求记录时间线
+router.get('/accounts/:accountId/usage-records', authenticateAdmin, async (req, res) => {
+  try {
+    const { accountId } = req.params
+    const {
+      platform,
+      page = 1,
+      pageSize = 50,
+      startDate,
+      endDate,
+      model,
+      apiKeyId,
+      sortOrder = 'desc'
+    } = req.query
+
+    const pageNumber = Math.max(parseInt(page, 10) || 1, 1)
+    const pageSizeNumber = Math.min(Math.max(parseInt(pageSize, 10) || 50, 1), 200)
+    const normalizedSortOrder = sortOrder === 'asc' ? 'asc' : 'desc'
+
+    const startTime = startDate ? new Date(startDate) : null
+    const endTime = endDate ? new Date(endDate) : null
+
+    if (
+      (startDate && Number.isNaN(startTime?.getTime())) ||
+      (endDate && Number.isNaN(endTime?.getTime()))
+    ) {
+      return res.status(400).json({ success: false, error: 'Invalid date range' })
+    }
+
+    if (startTime && endTime && startTime > endTime) {
+      return res
+        .status(400)
+        .json({ success: false, error: 'Start date must be before or equal to end date' })
+    }
+
+    const accountInfo = await resolveAccountByPlatform(accountId, platform)
+    if (!accountInfo) {
+      return res.status(404).json({ success: false, error: 'Account not found' })
+    }
+
+    const allApiKeys = await apiKeyService.getAllApiKeys(true)
+    const apiKeyNameCache = new Map(
+      allApiKeys.map((key) => [key.id, key.name || key.label || key.id])
+    )
+
+    let keysToUse = apiKeyId ? allApiKeys.filter((key) => key.id === apiKeyId) : allApiKeys
+    if (apiKeyId && keysToUse.length === 0) {
+      keysToUse = [{ id: apiKeyId }]
+    }
+
+    const toUsageObject = (record) => ({
+      input_tokens: record.inputTokens || 0,
+      output_tokens: record.outputTokens || 0,
+      cache_creation_input_tokens: record.cacheCreateTokens || 0,
+      cache_read_input_tokens: record.cacheReadTokens || 0,
+      cache_creation: record.cacheCreation || record.cache_creation || null
+    })
+
+    const withinRange = (record) => {
+      if (!record.timestamp) {
+        return false
+      }
+      const ts = new Date(record.timestamp)
+      if (Number.isNaN(ts.getTime())) {
+        return false
+      }
+      if (startTime && ts < startTime) {
+        return false
+      }
+      if (endTime && ts > endTime) {
+        return false
+      }
+      return true
+    }
+
+    const filteredRecords = []
+    const modelSet = new Set()
+    const apiKeyOptionMap = new Map()
+    let earliestTimestamp = null
+    let latestTimestamp = null
+
+    const batchSize = 10
+    for (let i = 0; i < keysToUse.length; i += batchSize) {
+      const batch = keysToUse.slice(i, i + batchSize)
+      const batchResults = await Promise.all(
+        batch.map(async (key) => {
+          try {
+            const records = await redis.getUsageRecords(key.id, 5000)
+            return { keyId: key.id, records: records || [] }
+          } catch (error) {
+            logger.debug(`⚠️ Failed to get usage records for key ${key.id}: ${error.message}`)
+            return { keyId: key.id, records: [] }
+          }
+        })
+      )
+
+      for (const { keyId, records } of batchResults) {
+        const apiKeyName = apiKeyNameCache.get(keyId) || (await getApiKeyName(keyId))
+        for (const record of records) {
+          if (record.accountId !== accountId) {
+            continue
+          }
+          if (!withinRange(record)) {
+            continue
+          }
+          if (model && record.model !== model) {
+            continue
+          }
+
+          const accountType = record.accountType || accountInfo.platform || 'unknown'
+          const normalizedModel = record.model || 'unknown'
+
+          modelSet.add(normalizedModel)
+          apiKeyOptionMap.set(keyId, { id: keyId, name: apiKeyName })
+
+          if (record.timestamp) {
+            const ts = new Date(record.timestamp)
+            if (!Number.isNaN(ts.getTime())) {
+              if (!earliestTimestamp || ts < earliestTimestamp) {
+                earliestTimestamp = ts
+              }
+              if (!latestTimestamp || ts > latestTimestamp) {
+                latestTimestamp = ts
+              }
+            }
+          }
+
+          filteredRecords.push({
+            ...record,
+            model: normalizedModel,
+            accountType,
+            apiKeyId: keyId,
+            apiKeyName
+          })
+        }
+      }
+    }
+
+    filteredRecords.sort((a, b) => {
+      const aTime = new Date(a.timestamp).getTime()
+      const bTime = new Date(b.timestamp).getTime()
+      if (Number.isNaN(aTime) || Number.isNaN(bTime)) {
+        return 0
+      }
+      return normalizedSortOrder === 'asc' ? aTime - bTime : bTime - aTime
+    })
+
+    const summary = {
+      totalRequests: 0,
+      inputTokens: 0,
+      outputTokens: 0,
+      cacheCreateTokens: 0,
+      cacheReadTokens: 0,
+      totalTokens: 0,
+      totalCost: 0
+    }
+
+    for (const record of filteredRecords) {
+      const usage = toUsageObject(record)
+      const costData = CostCalculator.calculateCost(usage, record.model || 'unknown')
+      const computedCost =
+        typeof record.cost === 'number' ? record.cost : costData?.costs?.total || 0
+      const totalTokens =
+        record.totalTokens ||
+        usage.input_tokens +
+          usage.output_tokens +
+          usage.cache_creation_input_tokens +
+          usage.cache_read_input_tokens
+
+      summary.totalRequests += 1
+      summary.inputTokens += usage.input_tokens
+      summary.outputTokens += usage.output_tokens
+      summary.cacheCreateTokens += usage.cache_creation_input_tokens
+      summary.cacheReadTokens += usage.cache_read_input_tokens
+      summary.totalTokens += totalTokens
+      summary.totalCost += computedCost
+    }
+
+    const totalRecords = filteredRecords.length
+    const totalPages = totalRecords > 0 ? Math.ceil(totalRecords / pageSizeNumber) : 0
+    const safePage = totalPages > 0 ? Math.min(pageNumber, totalPages) : 1
+    const startIndex = (safePage - 1) * pageSizeNumber
+    const pageRecords =
+      totalRecords === 0 ? [] : filteredRecords.slice(startIndex, startIndex + pageSizeNumber)
+
+    const enrichedRecords = []
+    for (const record of pageRecords) {
+      const usage = toUsageObject(record)
+      const costData = CostCalculator.calculateCost(usage, record.model || 'unknown')
+      const computedCost =
+        typeof record.cost === 'number' ? record.cost : costData?.costs?.total || 0
+      const totalTokens =
+        record.totalTokens ||
+        usage.input_tokens +
+          usage.output_tokens +
+          usage.cache_creation_input_tokens +
+          usage.cache_read_input_tokens
+
+      enrichedRecords.push({
+        timestamp: record.timestamp,
+        model: record.model || 'unknown',
+        apiKeyId: record.apiKeyId,
+        apiKeyName: record.apiKeyName,
+        accountId,
+        accountName: accountInfo.name || accountInfo.email || accountId,
+        accountType: record.accountType,
+        accountTypeName: accountTypeNames[record.accountType] || '未知渠道',
+        inputTokens: usage.input_tokens,
+        outputTokens: usage.output_tokens,
+        cacheCreateTokens: usage.cache_creation_input_tokens,
+        cacheReadTokens: usage.cache_read_input_tokens,
+        ephemeral5mTokens: record.ephemeral5mTokens || 0,
+        ephemeral1hTokens: record.ephemeral1hTokens || 0,
+        totalTokens,
+        isLongContextRequest: record.isLongContext || record.isLongContextRequest || false,
+        cost: Number(computedCost.toFixed(6)),
+        costFormatted:
+          record.costFormatted ||
+          costData?.formatted?.total ||
+          CostCalculator.formatCost(computedCost),
+        costBreakdown: record.costBreakdown || {
+          input: costData?.costs?.input || 0,
+          output: costData?.costs?.output || 0,
+          cacheCreate: costData?.costs?.cacheWrite || 0,
+          cacheRead: costData?.costs?.cacheRead || 0,
+          total: costData?.costs?.total || computedCost
+        },
+        responseTime: record.responseTime || null
+      })
+    }
+
+    return res.json({
+      success: true,
+      data: {
+        records: enrichedRecords,
+        pagination: {
+          currentPage: safePage,
+          pageSize: pageSizeNumber,
+          totalRecords,
+          totalPages,
+          hasNextPage: totalPages > 0 && safePage < totalPages,
+          hasPreviousPage: totalPages > 0 && safePage > 1
+        },
+        filters: {
+          startDate: startTime ? startTime.toISOString() : null,
+          endDate: endTime ? endTime.toISOString() : null,
+          model: model || null,
+          apiKeyId: apiKeyId || null,
+          platform: accountInfo.platform,
+          sortOrder: normalizedSortOrder
+        },
+        accountInfo: {
+          id: accountId,
+          name: accountInfo.name || accountInfo.email || accountId,
+          platform: accountInfo.platform || platform || 'unknown',
+          status: accountInfo.status ?? accountInfo.isActive ?? null
+        },
+        summary: {
+          ...summary,
+          totalCost: Number(summary.totalCost.toFixed(6)),
+          avgCost:
+            summary.totalRequests > 0
+              ? Number((summary.totalCost / summary.totalRequests).toFixed(6))
+              : 0
+        },
+        availableFilters: {
+          models: Array.from(modelSet),
+          apiKeys: Array.from(apiKeyOptionMap.values()),
+          dateRange: {
+            earliest: earliestTimestamp ? earliestTimestamp.toISOString() : null,
+            latest: latestTimestamp ? latestTimestamp.toISOString() : null
+          }
+        }
+      }
+    })
+  } catch (error) {
+    logger.error('❌ Failed to get account usage records:', error)
+    return res
+      .status(500)
+      .json({ error: 'Failed to get account usage records', message: error.message })
+  }
+})
+
 module.exports = router

src/routes/admin/utils.js

@@ -33,7 +33,9 @@ function mapExpiryField(updates, accountType, accountId) {
   if ('expiresAt' in mappedUpdates) {
     mappedUpdates.subscriptionExpiresAt = mappedUpdates.expiresAt
     delete mappedUpdates.expiresAt
-    logger.info(`Mapping expiresAt to subscriptionExpiresAt for ${accountType} account ${accountId}`)
+    logger.info(
+      `Mapping expiresAt to subscriptionExpiresAt for ${accountType} account ${accountId}`
+    )
   }
   return mappedUpdates
 }

src/routes/api.js

@@ -11,6 +11,7 @@ const logger = require('../utils/logger')
 const { getEffectiveModel, parseVendorPrefixedModel } = require('../utils/modelHelper')
 const sessionHelper = require('../utils/sessionHelper')
 const { updateRateLimitCounters } = require('../utils/rateLimitHelper')
+const claudeRelayConfigService = require('../services/claudeRelayConfigService')
 const { sanitizeUpstreamError } = require('../utils/errorSanitizer')
 const router = express.Router()
 
@@ -37,6 +38,73 @@ function queueRateLimitUpdate(rateLimitInfo, usageSummary, model, context = '')
     })
 }
 
+/**
+ * 判断是否为旧会话（污染的会话）
+ * Claude Code 发送的请求特点：
+ * - messages 数组通常只有 1 个元素
+ * - 历史对话记录嵌套在单个 message 的 content 数组中
+ * - content 数组中包含 <system-reminder> 开头的系统注入内容
+ *
+ * 污染会话的特征：
+ * 1. messages.length > 1
+ * 2. messages.length === 1 但 content 中有多个用户输入
+ * 3. "warmup" 请求：单条简单消息 + 无 tools（真正新会话会带 tools）
+ *
+ * @param {Object} body - 请求体
+ * @returns {boolean} 是否为旧会话
+ */
+function isOldSession(body) {
+  const messages = body?.messages
+  const tools = body?.tools
+
+  if (!messages || messages.length === 0) {
+    return false
+  }
+
+  // 1. 多条消息 = 旧会话
+  if (messages.length > 1) {
+    return true
+  }
+
+  // 2. 单条消息，分析 content
+  const firstMessage = messages[0]
+  const content = firstMessage?.content
+
+  if (!content) {
+    return false
+  }
+
+  // 如果 content 是字符串，只有一条输入，需要检查 tools
+  if (typeof content === 'string') {
+    // 有 tools = 正常新会话，无 tools = 可疑
+    return !tools || tools.length === 0
+  }
+
+  // 如果 content 是数组，统计非 system-reminder 的元素
+  if (Array.isArray(content)) {
+    const userInputs = content.filter((item) => {
+      if (item.type !== 'text') {
+        return false
+      }
+      const text = item.text || ''
+      // 剔除以 <system-reminder> 开头的
+      return !text.trimStart().startsWith('<system-reminder>')
+    })
+
+    // 多个用户输入 = 旧会话
+    if (userInputs.length > 1) {
+      return true
+    }
+
+    // Warmup 检测：单个消息 + 无 tools = 旧会话
+    if (userInputs.length === 1 && (!tools || tools.length === 0)) {
+      return true
+    }
+  }
+
+  return false
+}
+
 // 🔧 共享的消息处理函数
 async function handleMessagesRequest(req, res) {
   try {
@@ -122,12 +190,42 @@ async function handleMessagesRequest(req, res) {
     )
 
     if (isStream) {
+      // 🔍 检查客户端连接是否仍然有效（可能在并发排队等待期间断开）
+      if (res.destroyed || res.socket?.destroyed || res.writableEnded) {
+        logger.warn(
+          `⚠️ Client disconnected before stream response could start for key: ${req.apiKey?.name || 'unknown'}`
+        )
+        return undefined
+      }
+
       // 流式响应 - 只使用官方真实usage数据
       res.setHeader('Content-Type', 'text/event-stream')
       res.setHeader('Cache-Control', 'no-cache')
       res.setHeader('Connection', 'keep-alive')
       res.setHeader('Access-Control-Allow-Origin', '*')
       res.setHeader('X-Accel-Buffering', 'no') // 禁用 Nginx 缓冲
+      // ⚠️ 检查 headers 是否已发送（可能在排队心跳时已设置）
+      if (!res.headersSent) {
+        res.setHeader('Content-Type', 'text/event-stream')
+        res.setHeader('Cache-Control', 'no-cache')
+        // ⚠️ 关键修复：尊重 auth.js 提前设置的 Connection: close
+        // 当并发队列功能启用时，auth.js 会设置 Connection: close 来禁用 Keep-Alive
+        // 这里只在没有设置过 Connection 头时才设置 keep-alive
+        const existingConnection = res.getHeader('Connection')
+        if (!existingConnection) {
+          res.setHeader('Connection', 'keep-alive')
+        } else {
+          logger.api(
+            `🔌 [STREAM] Preserving existing Connection header: ${existingConnection} for key: ${req.apiKey?.name || 'unknown'}`
+          )
+        }
+        res.setHeader('Access-Control-Allow-Origin', '*')
+        res.setHeader('X-Accel-Buffering', 'no') // 禁用 Nginx 缓冲
+      } else {
+        logger.debug(
+          `📤 [STREAM] Headers already sent, skipping setHeader for key: ${req.apiKey?.name || 'unknown'}`
+        )
+      }
 
       // 禁用 Nagle 算法，确保数据立即发送
       if (res.socket && typeof res.socket.setNoDelay === 'function') {
@@ -141,6 +239,56 @@ async function handleMessagesRequest(req, res) {
       // 生成会话哈希用于sticky会话
       const sessionHash = sessionHelper.generateSessionHash(req.body)
 
+      // 🔒 全局会话绑定验证
+      let forcedAccount = null
+      let needSessionBinding = false
+      let originalSessionIdForBinding = null
+
+      try {
+        const globalBindingEnabled = await claudeRelayConfigService.isGlobalSessionBindingEnabled()
+
+        if (globalBindingEnabled) {
+          const originalSessionId = claudeRelayConfigService.extractOriginalSessionId(req.body)
+
+          if (originalSessionId) {
+            const validation = await claudeRelayConfigService.validateNewSession(
+              req.body,
+              originalSessionId
+            )
+
+            if (!validation.valid) {
+              logger.api(
+                `❌ Session binding validation failed: ${validation.code} for session ${originalSessionId}`
+              )
+              return res.status(403).json({
+                error: {
+                  type: 'session_binding_error',
+                  message: validation.error
+                }
+              })
+            }
+
+            // 如果已有绑定，使用绑定的账户
+            if (validation.binding) {
+              forcedAccount = validation.binding
+              logger.api(
+                `🔗 Using bound account for session ${originalSessionId}: ${forcedAccount.accountId}`
+              )
+            }
+
+            // 标记需要在调度成功后建立绑定
+            if (validation.isNewSession) {
+              needSessionBinding = true
+              originalSessionIdForBinding = originalSessionId
+              logger.api(`📝 New session detected, will create binding: ${originalSessionId}`)
+            }
+          }
+        }
+      } catch (error) {
+        logger.error('❌ Error in global session binding check:', error)
+        // 配置服务出错时不阻断请求
+      }
+
       // 使用统一调度选择账号（传递请求的模型）
       const requestedModel = req.body.model
       let accountId
@@ -149,10 +297,21 @@ async function handleMessagesRequest(req, res) {
         const selection = await unifiedClaudeScheduler.selectAccountForApiKey(
           req.apiKey,
           sessionHash,
-          requestedModel
+          requestedModel,
+          forcedAccount
         )
         ;({ accountId, accountType } = selection)
       } catch (error) {
+        // 处理会话绑定账户不可用的错误
+        if (error.code === 'SESSION_BINDING_ACCOUNT_UNAVAILABLE') {
+          const errorMessage = await claudeRelayConfigService.getSessionBindingErrorMessage()
+          return res.status(403).json({
+            error: {
+              type: 'session_binding_error',
+              message: errorMessage
+            }
+          })
+        }
         if (error.code === 'CLAUDE_DEDICATED_RATE_LIMITED') {
           const limitMessage = claudeRelayService._buildStandardRateLimitMessage(
             error.rateLimitEndAt
@@ -170,6 +329,40 @@ async function handleMessagesRequest(req, res) {
         throw error
       }
 
+      // 🔗 在成功调度后建立会话绑定（仅 claude-official 类型）
+      // claude-official 只接受：1) 新会话 2) 已绑定的会话
+      if (
+        needSessionBinding &&
+        originalSessionIdForBinding &&
+        accountId &&
+        accountType === 'claude-official'
+      ) {
+        // 🚫 检测旧会话（污染的会话）
+        if (isOldSession(req.body)) {
+          const cfg = await claudeRelayConfigService.getConfig()
+          logger.warn(
+            `🚫 Old session rejected: sessionId=${originalSessionIdForBinding}, messages.length=${req.body?.messages?.length}, tools.length=${req.body?.tools?.length || 0}, isOldSession=true`
+          )
+          return res.status(400).json({
+            error: {
+              type: 'session_binding_error',
+              message: cfg.sessionBindingErrorMessage || '你的本地session已污染，请清理后使用。'
+            }
+          })
+        }
+
+        // 创建绑定
+        try {
+          await claudeRelayConfigService.setOriginalSessionBinding(
+            originalSessionIdForBinding,
+            accountId,
+            accountType
+          )
+        } catch (bindingError) {
+          logger.warn(`⚠️ Failed to create session binding:`, bindingError)
+        }
+      }
+
       // 根据账号类型选择对应的转发服务并调用
       if (accountType === 'claude-official') {
         // 官方Claude账号使用原有的转发服务（会自己选择账号）
@@ -494,15 +687,113 @@ async function handleMessagesRequest(req, res) {
         }
       }, 1000) // 1秒后检查
     } else {
+      // 🔍 检查客户端连接是否仍然有效（可能在并发排队等待期间断开）
+      if (res.destroyed || res.socket?.destroyed || res.writableEnded) {
+        logger.warn(
+          `⚠️ Client disconnected before non-stream request could start for key: ${req.apiKey?.name || 'unknown'}`
+        )
+        return undefined
+      }
+
       // 非流式响应 - 只使用官方真实usage数据
       logger.info('📄 Starting non-streaming request', {
         apiKeyId: req.apiKey.id,
         apiKeyName: req.apiKey.name
       })
 
+      // 📊 监听 socket 事件以追踪连接状态变化
+      const nonStreamSocket = res.socket
+      let _clientClosedConnection = false
+      let _socketCloseTime = null
+
+      if (nonStreamSocket) {
+        const onSocketEnd = () => {
+          _clientClosedConnection = true
+          _socketCloseTime = Date.now()
+          logger.warn(
+            `⚠️ [NON-STREAM] Socket 'end' event - client sent FIN | key: ${req.apiKey?.name}, ` +
+              `requestId: ${req.requestId}, elapsed: ${Date.now() - startTime}ms`
+          )
+        }
+        const onSocketClose = () => {
+          _clientClosedConnection = true
+          logger.warn(
+            `⚠️ [NON-STREAM] Socket 'close' event | key: ${req.apiKey?.name}, ` +
+              `requestId: ${req.requestId}, elapsed: ${Date.now() - startTime}ms, ` +
+              `hadError: ${nonStreamSocket.destroyed}`
+          )
+        }
+        const onSocketError = (err) => {
+          logger.error(
+            `❌ [NON-STREAM] Socket error | key: ${req.apiKey?.name}, ` +
+              `requestId: ${req.requestId}, error: ${err.message}`
+          )
+        }
+
+        nonStreamSocket.once('end', onSocketEnd)
+        nonStreamSocket.once('close', onSocketClose)
+        nonStreamSocket.once('error', onSocketError)
+
+        // 清理监听器（在响应结束后）
+        res.once('finish', () => {
+          nonStreamSocket.removeListener('end', onSocketEnd)
+          nonStreamSocket.removeListener('close', onSocketClose)
+          nonStreamSocket.removeListener('error', onSocketError)
+        })
+      }
+
       // 生成会话哈希用于sticky会话
       const sessionHash = sessionHelper.generateSessionHash(req.body)
 
+      // 🔒 全局会话绑定验证（非流式）
+      let forcedAccountNonStream = null
+      let needSessionBindingNonStream = false
+      let originalSessionIdForBindingNonStream = null
+
+      try {
+        const globalBindingEnabled = await claudeRelayConfigService.isGlobalSessionBindingEnabled()
+
+        if (globalBindingEnabled) {
+          const originalSessionId = claudeRelayConfigService.extractOriginalSessionId(req.body)
+
+          if (originalSessionId) {
+            const validation = await claudeRelayConfigService.validateNewSession(
+              req.body,
+              originalSessionId
+            )
+
+            if (!validation.valid) {
+              logger.api(
+                `❌ Session binding validation failed (non-stream): ${validation.code} for session ${originalSessionId}`
+              )
+              return res.status(403).json({
+                error: {
+                  type: 'session_binding_error',
+                  message: validation.error
+                }
+              })
+            }
+
+            if (validation.binding) {
+              forcedAccountNonStream = validation.binding
+              logger.api(
+                `🔗 Using bound account for session (non-stream) ${originalSessionId}: ${forcedAccountNonStream.accountId}`
+              )
+            }
+
+            if (validation.isNewSession) {
+              needSessionBindingNonStream = true
+              originalSessionIdForBindingNonStream = originalSessionId
+              logger.api(
+                `📝 New session detected (non-stream), will create binding: ${originalSessionId}`
+              )
+            }
+          }
+        }
+      } catch (error) {
+        logger.error('❌ Error in global session binding check (non-stream):', error)
+      }
+
       // 使用统一调度选择账号（传递请求的模型）
       const requestedModel = req.body.model
       let accountId
@@ -511,10 +802,20 @@ async function handleMessagesRequest(req, res) {
         const selection = await unifiedClaudeScheduler.selectAccountForApiKey(
           req.apiKey,
           sessionHash,
-          requestedModel
+          requestedModel,
+          forcedAccountNonStream
         )
         ;({ accountId, accountType } = selection)
       } catch (error) {
+        if (error.code === 'SESSION_BINDING_ACCOUNT_UNAVAILABLE') {
+          const errorMessage = await claudeRelayConfigService.getSessionBindingErrorMessage()
+          return res.status(403).json({
+            error: {
+              type: 'session_binding_error',
+              message: errorMessage
+            }
+          })
+        }
         if (error.code === 'CLAUDE_DEDICATED_RATE_LIMITED') {
           const limitMessage = claudeRelayService._buildStandardRateLimitMessage(
             error.rateLimitEndAt
@@ -527,6 +828,40 @@ async function handleMessagesRequest(req, res) {
         throw error
       }
 
+      // 🔗 在成功调度后建立会话绑定（非流式，仅 claude-official 类型）
+      // claude-official 只接受：1) 新会话 2) 已绑定的会话
+      if (
+        needSessionBindingNonStream &&
+        originalSessionIdForBindingNonStream &&
+        accountId &&
+        accountType === 'claude-official'
+      ) {
+        // 🚫 检测旧会话（污染的会话）
+        if (isOldSession(req.body)) {
+          const cfg = await claudeRelayConfigService.getConfig()
+          logger.warn(
+            `🚫 Old session rejected (non-stream): sessionId=${originalSessionIdForBindingNonStream}, messages.length=${req.body?.messages?.length}, tools.length=${req.body?.tools?.length || 0}, isOldSession=true`
+          )
+          return res.status(400).json({
+            error: {
+              type: 'session_binding_error',
+              message: cfg.sessionBindingErrorMessage || '你的本地session已污染，请清理后使用。'
+            }
+          })
+        }
+
+        // 创建绑定
+        try {
+          await claudeRelayConfigService.setOriginalSessionBinding(
+            originalSessionIdForBindingNonStream,
+            accountId,
+            accountType
+          )
+        } catch (bindingError) {
+          logger.warn(`⚠️ Failed to create session binding (non-stream):`, bindingError)
+        }
+      }
+
       // 根据账号类型选择对应的转发服务
       let response
       logger.debug(`[DEBUG] Request query params: ${JSON.stringify(req.query)}`)
@@ -611,6 +946,15 @@ async function handleMessagesRequest(req, res) {
         bodyLength: response.body ? response.body.length : 0
       })
 
+      // 🔍 检查客户端连接是否仍然有效
+      // 在长时间请求过程中，客户端可能已经断开连接（超时、用户取消等）
+      if (res.destroyed || res.socket?.destroyed || res.writableEnded) {
+        logger.warn(
+          `⚠️ Client disconnected before non-stream response could be sent for key: ${req.apiKey?.name || 'unknown'}`
+        )
+        return undefined
+      }
+
       res.status(response.statusCode)
 
       // 设置响应头，避免 Content-Length 和 Transfer-Encoding 冲突
@@ -676,10 +1020,12 @@ async function handleMessagesRequest(req, res) {
           logger.warn('⚠️ No usage data found in Claude API JSON response')
         }
 
+        // 使用 Express 内建的 res.json() 发送响应（简单可靠）
         res.json(jsonData)
       } catch (parseError) {
         logger.warn('⚠️ Failed to parse Claude API response as JSON:', parseError.message)
         logger.info('📄 Raw response body:', response.body)
+        // 使用 Express 内建的 res.send() 发送响应（简单可靠）
         res.send(response.body)
       }
 
@@ -824,7 +1170,8 @@ router.get('/v1/models', authenticateApiKey, async (req, res) => {
     // 可选：根据 API Key 的模型限制过滤
     let filteredModels = models
     if (req.apiKey.enableModelRestriction && req.apiKey.restrictedModels?.length > 0) {
-      filteredModels = models.filter((model) => req.apiKey.restrictedModels.includes(model.id))
+      // 将 restrictedModels 视为黑名单：过滤掉受限模型
+      filteredModels = models.filter((model) => !req.apiKey.restrictedModels.includes(model.id))
     }
 
     res.json({
@@ -965,6 +1312,41 @@ router.post('/v1/messages/count_tokens', authenticateApiKey, async (req, res) =>
     })
   }
 
+  // 🔗 会话绑定验证（与 messages 端点保持一致）
+  const originalSessionId = claudeRelayConfigService.extractOriginalSessionId(req.body)
+  const sessionValidation = await claudeRelayConfigService.validateNewSession(
+    req.body,
+    originalSessionId
+  )
+
+  if (!sessionValidation.valid) {
+    logger.warn(
+      `🚫 Session binding validation failed (count_tokens): ${sessionValidation.code} for session ${originalSessionId}`
+    )
+    return res.status(400).json({
+      error: {
+        type: 'session_binding_error',
+        message: sessionValidation.error
+      }
+    })
+  }
+
+  // 🔗 检测旧会话（污染的会话）- 仅对需要绑定的新会话检查
+  if (sessionValidation.isNewSession && originalSessionId) {
+    if (isOldSession(req.body)) {
+      const cfg = await claudeRelayConfigService.getConfig()
+      logger.warn(
+        `🚫 Old session rejected (count_tokens): sessionId=${originalSessionId}, messages.length=${req.body?.messages?.length}, tools.length=${req.body?.tools?.length || 0}, isOldSession=true`
+      )
+      return res.status(400).json({
+        error: {
+          type: 'session_binding_error',
+          message: cfg.sessionBindingErrorMessage || '你的本地session已污染，请清理后使用。'
+        }
+      })
+    }
+  }
+
   logger.info(`🔢 Processing token count request for key: ${req.apiKey.name}`)
 
   const sessionHash = sessionHelper.generateSessionHash(req.body)

src/routes/apiStats.js

@@ -206,14 +206,24 @@ router.post('/api/user-stats', async (req, res) => {
     // 获取验证结果中的完整keyData（包含isActive状态和cost信息）
     const fullKeyData = keyData
 
-    // 计算总费用 - 使用与模型统计相同的逻辑（按模型分别计算）
+    // 🔧 FIX: 使用 allTimeCost 而不是扫描月度键
+    // 计算总费用 - 优先使用持久化的总费用计数器
     let totalCost = 0
     let formattedCost = '$0.000000'
 
     try {
       const client = redis.getClientSafe()
 
-      // 获取所有月度模型统计（与model-stats接口相同的逻辑）
+      // 读取累积的总费用（没有 TTL 的持久键）
+      const totalCostKey = `usage:cost:total:${keyId}`
+      const allTimeCost = parseFloat((await client.get(totalCostKey)) || '0')
+
+      if (allTimeCost > 0) {
+        totalCost = allTimeCost
+        formattedCost = CostCalculator.formatCost(allTimeCost)
+        logger.debug(`📊 使用 allTimeCost 计算用户统计: ${allTimeCost}`)
+      } else {
+        // Fallback: 如果 allTimeCost 为空（旧键），尝试月度键
         const allModelKeys = await client.keys(`usage:${keyId}:model:monthly:*:*`)
         const modelUsageMap = new Map()
 
@@ -272,8 +282,9 @@ router.post('/api/user-stats', async (req, res) => {
         }
 
         formattedCost = CostCalculator.formatCost(totalCost)
+      }
     } catch (error) {
-      logger.warn(`Failed to calculate detailed cost for key ${keyId}:`, error)
+      logger.warn(`Failed to calculate cost for key ${keyId}:`, error)
       // 回退到简单计算
       if (fullKeyData.usage?.total?.allTokens > 0) {
         const usage = fullKeyData.usage.total

src/routes/openaiClaudeRoutes.js

@@ -15,6 +15,7 @@ const claudeCodeHeadersService = require('../services/claudeCodeHeadersService')
 const sessionHelper = require('../utils/sessionHelper')
 const { updateRateLimitCounters } = require('../utils/rateLimitHelper')
 const pricingService = require('../services/pricingService')
+const { getEffectiveModel } = require('../utils/modelHelper')
 
 // 🔧 辅助函数：检查 API Key 权限
 function checkPermissions(apiKeyData, requiredPermission = 'claude') {
@@ -75,9 +76,9 @@ router.get('/v1/models', authenticateApiKey, async (req, res) => {
       }
     ]
 
-    // 如果启用了模型限制，过滤模型列表
+    // 如果启用了模型限制，视为黑名单：过滤掉受限模型
     if (apiKeyData.enableModelRestriction && apiKeyData.restrictedModels?.length > 0) {
-      models = models.filter((model) => apiKeyData.restrictedModels.includes(model.id))
+      models = models.filter((model) => !apiKeyData.restrictedModels.includes(model.id))
     }
 
     res.json({
@@ -114,9 +115,9 @@ router.get('/v1/models/:model', authenticateApiKey, async (req, res) => {
       })
     }
 
-    // 检查模型限制
+    // 模型限制（黑名单）：命中则直接拒绝
     if (apiKeyData.enableModelRestriction && apiKeyData.restrictedModels?.length > 0) {
-      if (!apiKeyData.restrictedModels.includes(modelId)) {
+      if (apiKeyData.restrictedModels.includes(modelId)) {
         return res.status(404).json({
           error: {
             message: `Model '${modelId}' not found`,
@@ -199,9 +200,10 @@ async function handleChatCompletion(req, res, apiKeyData) {
     // 转换 OpenAI 请求为 Claude 格式
     const claudeRequest = openaiToClaude.convertRequest(req.body)
 
-    // 检查模型限制
+    // 模型限制（黑名单）：命中受限模型则拒绝
     if (apiKeyData.enableModelRestriction && apiKeyData.restrictedModels?.length > 0) {
-      if (!apiKeyData.restrictedModels.includes(claudeRequest.model)) {
+      const effectiveModel = getEffectiveModel(claudeRequest.model || '')
+      if (apiKeyData.restrictedModels.includes(effectiveModel)) {
         return res.status(403).json({
           error: {
             message: `Model ${req.body.model} is not allowed for this API key`,

src/routes/openaiRoutes.js

@@ -247,9 +247,11 @@ const handleResponses = async (req, res) => {
 
     // 从请求体中提取模型和流式标志
     let requestedModel = req.body?.model || null
+    const isCodexModel =
+      typeof requestedModel === 'string' && requestedModel.toLowerCase().includes('codex')
 
-    // 如果模型是 gpt-5 开头且后面还有内容（如 gpt-5-2025-08-07），则覆盖为 gpt-5
+    // 如果模型是 gpt-5 开头且后面还有内容（如 gpt-5-2025-08-07），并且不是 Codex 系列，则覆盖为 gpt-5
-    if (requestedModel && requestedModel.startsWith('gpt-5-') && requestedModel !== 'gpt-5-codex') {
+    if (requestedModel && requestedModel.startsWith('gpt-5-') && !isCodexModel) {
       logger.info(`📝 Model ${requestedModel} detected, normalizing to gpt-5 for Codex API`)
       requestedModel = 'gpt-5'
       req.body.model = 'gpt-5' // 同时更新请求体中的模型

src/services/accountTestSchedulerService.js

@@ -0,0 +1,420 @@
+/**
+ * 账户定时测试调度服务
+ * 使用 node-cron 支持 crontab 表达式，为每个账户创建独立的定时任务
+ */
+
+const cron = require('node-cron')
+const redis = require('../models/redis')
+const logger = require('../utils/logger')
+
+class AccountTestSchedulerService {
+  constructor() {
+    // 存储每个账户的 cron 任务: Map<string, { task: ScheduledTask, cronExpression: string }>
+    this.scheduledTasks = new Map()
+    // 定期刷新配置的间隔 (毫秒)
+    this.refreshIntervalMs = 60 * 1000
+    this.refreshInterval = null
+    // 当前正在测试的账户
+    this.testingAccounts = new Set()
+    // 是否已启动
+    this.isStarted = false
+  }
+
+  /**
+   * 验证 cron 表达式是否有效
+   * @param {string} cronExpression - cron 表达式
+   * @returns {boolean}
+   */
+  validateCronExpression(cronExpression) {
+    // 长度检查（防止 DoS）
+    if (!cronExpression || cronExpression.length > 100) {
+      return false
+    }
+    return cron.validate(cronExpression)
+  }
+
+  /**
+   * 启动调度器
+   */
+  async start() {
+    if (this.isStarted) {
+      logger.warn('⚠️ Account test scheduler is already running')
+      return
+    }
+
+    this.isStarted = true
+    logger.info('🚀 Starting account test scheduler service (node-cron mode)')
+
+    // 初始化所有已配置账户的定时任务
+    await this._refreshAllTasks()
+
+    // 定期刷新配置，以便动态添加/修改的配置能生效
+    this.refreshInterval = setInterval(() => {
+      this._refreshAllTasks()
+    }, this.refreshIntervalMs)
+
+    logger.info(
+      `📅 Account test scheduler started (refreshing configs every ${this.refreshIntervalMs / 1000}s)`
+    )
+  }
+
+  /**
+   * 停止调度器
+   */
+  stop() {
+    if (this.refreshInterval) {
+      clearInterval(this.refreshInterval)
+      this.refreshInterval = null
+    }
+
+    // 停止所有 cron 任务
+    for (const [accountKey, taskInfo] of this.scheduledTasks.entries()) {
+      taskInfo.task.stop()
+      logger.debug(`🛑 Stopped cron task for ${accountKey}`)
+    }
+    this.scheduledTasks.clear()
+
+    this.isStarted = false
+    logger.info('🛑 Account test scheduler stopped')
+  }
+
+  /**
+   * 刷新所有账户的定时任务
+   * @private
+   */
+  async _refreshAllTasks() {
+    try {
+      const platforms = ['claude', 'gemini', 'openai']
+      const activeAccountKeys = new Set()
+
+      // 并行加载所有平台的配置
+      const allEnabledAccounts = await Promise.all(
+        platforms.map((platform) =>
+          redis
+            .getEnabledTestAccounts(platform)
+            .then((accounts) => accounts.map((acc) => ({ ...acc, platform })))
+            .catch((error) => {
+              logger.warn(`⚠️ Failed to load test accounts for platform ${platform}:`, error)
+              return []
+            })
+        )
+      )
+
+      // 展平平台数据
+      const flatAccounts = allEnabledAccounts.flat()
+
+      for (const { accountId, cronExpression, model, platform } of flatAccounts) {
+        if (!cronExpression) {
+          logger.warn(
+            `⚠️ Account ${accountId} (${platform}) has no valid cron expression, skipping`
+          )
+          continue
+        }
+
+        const accountKey = `${platform}:${accountId}`
+        activeAccountKeys.add(accountKey)
+
+        // 检查是否需要更新任务
+        const existingTask = this.scheduledTasks.get(accountKey)
+        if (existingTask) {
+          // 如果 cron 表达式和模型都没变，不需要更新
+          if (existingTask.cronExpression === cronExpression && existingTask.model === model) {
+            continue
+          }
+          // 配置变了，停止旧任务
+          existingTask.task.stop()
+          logger.info(`🔄 Updating cron task for ${accountKey}: ${cronExpression}, model: ${model}`)
+        } else {
+          logger.info(`➕ Creating cron task for ${accountKey}: ${cronExpression}, model: ${model}`)
+        }
+
+        // 创建新的 cron 任务
+        this._createCronTask(accountId, platform, cronExpression, model)
+      }
+
+      // 清理已删除或禁用的账户任务
+      for (const [accountKey, taskInfo] of this.scheduledTasks.entries()) {
+        if (!activeAccountKeys.has(accountKey)) {
+          taskInfo.task.stop()
+          this.scheduledTasks.delete(accountKey)
+          logger.info(`➖ Removed cron task for ${accountKey} (disabled or deleted)`)
+        }
+      }
+    } catch (error) {
+      logger.error('❌ Error refreshing account test tasks:', error)
+    }
+  }
+
+  /**
+   * 为单个账户创建 cron 任务
+   * @param {string} accountId
+   * @param {string} platform
+   * @param {string} cronExpression
+   * @param {string} model - 测试使用的模型
+   * @private
+   */
+  _createCronTask(accountId, platform, cronExpression, model) {
+    const accountKey = `${platform}:${accountId}`
+
+    // 验证 cron 表达式
+    if (!this.validateCronExpression(cronExpression)) {
+      logger.error(`❌ Invalid cron expression for ${accountKey}: ${cronExpression}`)
+      return
+    }
+
+    const task = cron.schedule(
+      cronExpression,
+      async () => {
+        await this._runAccountTest(accountId, platform, model)
+      },
+      {
+        scheduled: true,
+        timezone: process.env.TZ || 'Asia/Shanghai'
+      }
+    )
+
+    this.scheduledTasks.set(accountKey, {
+      task,
+      cronExpression,
+      model,
+      accountId,
+      platform
+    })
+  }
+
+  /**
+   * 执行单个账户测试
+   * @param {string} accountId - 账户ID
+   * @param {string} platform - 平台类型
+   * @param {string} model - 测试使用的模型
+   * @private
+   */
+  async _runAccountTest(accountId, platform, model) {
+    const accountKey = `${platform}:${accountId}`
+
+    // 避免重复测试
+    if (this.testingAccounts.has(accountKey)) {
+      logger.debug(`⏳ Account ${accountKey} is already being tested, skipping`)
+      return
+    }
+
+    this.testingAccounts.add(accountKey)
+
+    try {
+      logger.info(
+        `🧪 Running scheduled test for ${platform} account: ${accountId} (model: ${model})`
+      )
+
+      let testResult
+
+      // 根据平台调用对应的测试方法
+      switch (platform) {
+        case 'claude':
+          testResult = await this._testClaudeAccount(accountId, model)
+          break
+        case 'gemini':
+          testResult = await this._testGeminiAccount(accountId, model)
+          break
+        case 'openai':
+          testResult = await this._testOpenAIAccount(accountId, model)
+          break
+        default:
+          testResult = {
+            success: false,
+            error: `Unsupported platform: ${platform}`,
+            timestamp: new Date().toISOString()
+          }
+      }
+
+      // 保存测试结果
+      await redis.saveAccountTestResult(accountId, platform, testResult)
+
+      // 更新最后测试时间
+      await redis.setAccountLastTestTime(accountId, platform)
+
+      // 记录日志
+      if (testResult.success) {
+        logger.info(
+          `✅ Scheduled test passed for ${platform} account ${accountId} (${testResult.latencyMs}ms)`
+        )
+      } else {
+        logger.warn(
+          `❌ Scheduled test failed for ${platform} account ${accountId}: ${testResult.error}`
+        )
+      }
+
+      return testResult
+    } catch (error) {
+      logger.error(`❌ Error testing ${platform} account ${accountId}:`, error)
+
+      const errorResult = {
+        success: false,
+        error: error.message,
+        timestamp: new Date().toISOString()
+      }
+
+      await redis.saveAccountTestResult(accountId, platform, errorResult)
+      await redis.setAccountLastTestTime(accountId, platform)
+
+      return errorResult
+    } finally {
+      this.testingAccounts.delete(accountKey)
+    }
+  }
+
+  /**
+   * 测试 Claude 账户
+   * @param {string} accountId
+   * @param {string} model - 测试使用的模型
+   * @private
+   */
+  async _testClaudeAccount(accountId, model) {
+    const claudeRelayService = require('./claudeRelayService')
+    return await claudeRelayService.testAccountConnectionSync(accountId, model)
+  }
+
+  /**
+   * 测试 Gemini 账户
+   * @param {string} _accountId
+   * @param {string} _model
+   * @private
+   */
+  async _testGeminiAccount(_accountId, _model) {
+    // Gemini 测试暂时返回未实现
+    return {
+      success: false,
+      error: 'Gemini scheduled test not implemented yet',
+      timestamp: new Date().toISOString()
+    }
+  }
+
+  /**
+   * 测试 OpenAI 账户
+   * @param {string} _accountId
+   * @param {string} _model
+   * @private
+   */
+  async _testOpenAIAccount(_accountId, _model) {
+    // OpenAI 测试暂时返回未实现
+    return {
+      success: false,
+      error: 'OpenAI scheduled test not implemented yet',
+      timestamp: new Date().toISOString()
+    }
+  }
+
+  /**
+   * 手动触发账户测试
+   * @param {string} accountId - 账户ID
+   * @param {string} platform - 平台类型
+   * @param {string} model - 测试使用的模型
+   * @returns {Promise<Object>} 测试结果
+   */
+  async triggerTest(accountId, platform, model = 'claude-sonnet-4-5-20250929') {
+    logger.info(`🎯 Manual test triggered for ${platform} account: ${accountId} (model: ${model})`)
+    return await this._runAccountTest(accountId, platform, model)
+  }
+
+  /**
+   * 获取账户测试历史
+   * @param {string} accountId - 账户ID
+   * @param {string} platform - 平台类型
+   * @returns {Promise<Array>} 测试历史
+   */
+  async getTestHistory(accountId, platform) {
+    return await redis.getAccountTestHistory(accountId, platform)
+  }
+
+  /**
+   * 获取账户测试配置
+   * @param {string} accountId - 账户ID
+   * @param {string} platform - 平台类型
+   * @returns {Promise<Object|null>}
+   */
+  async getTestConfig(accountId, platform) {
+    return await redis.getAccountTestConfig(accountId, platform)
+  }
+
+  /**
+   * 设置账户测试配置
+   * @param {string} accountId - 账户ID
+   * @param {string} platform - 平台类型
+   * @param {Object} testConfig - 测试配置 { enabled: boolean, cronExpression: string, model: string }
+   * @returns {Promise<void>}
+   */
+  async setTestConfig(accountId, platform, testConfig) {
+    // 验证 cron 表达式
+    if (testConfig.cronExpression && !this.validateCronExpression(testConfig.cronExpression)) {
+      throw new Error(`Invalid cron expression: ${testConfig.cronExpression}`)
+    }
+
+    await redis.saveAccountTestConfig(accountId, platform, testConfig)
+    logger.info(
+      `📝 Test config updated for ${platform} account ${accountId}: enabled=${testConfig.enabled}, cronExpression=${testConfig.cronExpression}, model=${testConfig.model}`
+    )
+
+    // 立即刷新任务，使配置立即生效
+    if (this.isStarted) {
+      await this._refreshAllTasks()
+    }
+  }
+
+  /**
+   * 更新单个账户的定时任务（配置变更时调用）
+   * @param {string} accountId
+   * @param {string} platform
+   */
+  async refreshAccountTask(accountId, platform) {
+    if (!this.isStarted) {
+      return
+    }
+
+    const accountKey = `${platform}:${accountId}`
+    const testConfig = await redis.getAccountTestConfig(accountId, platform)
+
+    // 停止现有任务
+    const existingTask = this.scheduledTasks.get(accountKey)
+    if (existingTask) {
+      existingTask.task.stop()
+      this.scheduledTasks.delete(accountKey)
+    }
+
+    // 如果启用且有有效的 cron 表达式，创建新任务
+    if (testConfig?.enabled && testConfig?.cronExpression) {
+      this._createCronTask(accountId, platform, testConfig.cronExpression, testConfig.model)
+      logger.info(
+        `🔄 Refreshed cron task for ${accountKey}: ${testConfig.cronExpression}, model: ${testConfig.model}`
+      )
+    }
+  }
+
+  /**
+   * 获取调度器状态
+   * @returns {Object}
+   */
+  getStatus() {
+    const tasks = []
+    for (const [accountKey, taskInfo] of this.scheduledTasks.entries()) {
+      tasks.push({
+        accountKey,
+        accountId: taskInfo.accountId,
+        platform: taskInfo.platform,
+        cronExpression: taskInfo.cronExpression,
+        model: taskInfo.model
+      })
+    }
+
+    return {
+      running: this.isStarted,
+      refreshIntervalMs: this.refreshIntervalMs,
+      scheduledTasksCount: this.scheduledTasks.size,
+      scheduledTasks: tasks,
+      currentlyTesting: Array.from(this.testingAccounts)
+    }
+  }
+}
+
+// 单例模式
+const accountTestSchedulerService = new AccountTestSchedulerService()
+
+module.exports = accountTestSchedulerService

src/services/bedrockRelayService.js

@@ -6,6 +6,7 @@ const {
 const { fromEnv } = require('@aws-sdk/credential-providers')
 const logger = require('../utils/logger')
 const config = require('../../config/config')
+const userMessageQueueService = require('./userMessageQueueService')
 
 class BedrockRelayService {
   constructor() {
@@ -69,7 +70,68 @@ class BedrockRelayService {
 
   // 处理非流式请求
   async handleNonStreamRequest(requestBody, bedrockAccount = null) {
+    const accountId = bedrockAccount?.id
+    let queueLockAcquired = false
+    let queueRequestId = null
+
     try {
+      // 📬 用户消息队列处理
+      if (userMessageQueueService.isUserMessageRequest(requestBody)) {
+        // 校验 accountId 非空，避免空值污染队列锁键
+        if (!accountId || accountId === '') {
+          logger.error('❌ accountId missing for queue lock in Bedrock handleNonStreamRequest')
+          throw new Error('accountId missing for queue lock')
+        }
+        const queueResult = await userMessageQueueService.acquireQueueLock(accountId)
+        if (!queueResult.acquired && !queueResult.skipped) {
+          // 区分 Redis 后端错误和队列超时
+          const isBackendError = queueResult.error === 'queue_backend_error'
+          const errorCode = isBackendError ? 'QUEUE_BACKEND_ERROR' : 'QUEUE_TIMEOUT'
+          const errorType = isBackendError ? 'queue_backend_error' : 'queue_timeout'
+          const errorMessage = isBackendError
+            ? 'Queue service temporarily unavailable, please retry later'
+            : 'User message queue wait timeout, please retry later'
+          const statusCode = isBackendError ? 500 : 503
+
+          // 结构化性能日志，用于后续统计
+          logger.performance('user_message_queue_error', {
+            errorType,
+            errorCode,
+            accountId,
+            statusCode,
+            backendError: isBackendError ? queueResult.errorMessage : undefined
+          })
+
+          logger.warn(
+            `📬 User message queue ${errorType} for Bedrock account ${accountId}`,
+            isBackendError ? { backendError: queueResult.errorMessage } : {}
+          )
+          return {
+            statusCode,
+            headers: {
+              'Content-Type': 'application/json',
+              'x-user-message-queue-error': errorType
+            },
+            body: JSON.stringify({
+              type: 'error',
+              error: {
+                type: errorType,
+                code: errorCode,
+                message: errorMessage
+              }
+            }),
+            success: false
+          }
+        }
+        if (queueResult.acquired && !queueResult.skipped) {
+          queueLockAcquired = true
+          queueRequestId = queueResult.requestId
+          logger.debug(
+            `📬 User message queue lock acquired for Bedrock account ${accountId}, requestId: ${queueRequestId}`
+          )
+        }
+      }
+
       const modelId = this._selectModel(requestBody, bedrockAccount)
       const region = this._selectRegion(modelId, bedrockAccount)
       const client = this._getBedrockClient(region, bedrockAccount)
@@ -90,6 +152,23 @@ class BedrockRelayService {
       const response = await client.send(command)
       const duration = Date.now() - startTime
 
+      // 📬 请求已发送成功，立即释放队列锁（无需等待响应处理完成）
+      // 因为限流基于请求发送时刻计算（RPM），不是请求完成时刻
+      if (queueLockAcquired && queueRequestId && accountId) {
+        try {
+          await userMessageQueueService.releaseQueueLock(accountId, queueRequestId)
+          queueLockAcquired = false // 标记已释放，防止 finally 重复释放
+          logger.debug(
+            `📬 User message queue lock released early for Bedrock account ${accountId}, requestId: ${queueRequestId}`
+          )
+        } catch (releaseError) {
+          logger.error(
+            `❌ Failed to release user message queue lock early for Bedrock account ${accountId}:`,
+            releaseError.message
+          )
+        }
+      }
+
       // 解析响应
       const responseBody = JSON.parse(new TextDecoder().decode(response.body))
       const claudeResponse = this._convertFromBedrockFormat(responseBody)
@@ -106,12 +185,94 @@ class BedrockRelayService {
     } catch (error) {
       logger.error('❌ Bedrock非流式请求失败:', error)
       throw this._handleBedrockError(error)
+    } finally {
+      // 📬 释放用户消息队列锁（兜底，正常情况下已在请求发送后提前释放）
+      if (queueLockAcquired && queueRequestId && accountId) {
+        try {
+          await userMessageQueueService.releaseQueueLock(accountId, queueRequestId)
+          logger.debug(
+            `📬 User message queue lock released in finally for Bedrock account ${accountId}, requestId: ${queueRequestId}`
+          )
+        } catch (releaseError) {
+          logger.error(
+            `❌ Failed to release user message queue lock for Bedrock account ${accountId}:`,
+            releaseError.message
+          )
+        }
+      }
     }
   }
 
   // 处理流式请求
   async handleStreamRequest(requestBody, bedrockAccount = null, res) {
+    const accountId = bedrockAccount?.id
+    let queueLockAcquired = false
+    let queueRequestId = null
+
     try {
+      // 📬 用户消息队列处理
+      if (userMessageQueueService.isUserMessageRequest(requestBody)) {
+        // 校验 accountId 非空，避免空值污染队列锁键
+        if (!accountId || accountId === '') {
+          logger.error('❌ accountId missing for queue lock in Bedrock handleStreamRequest')
+          throw new Error('accountId missing for queue lock')
+        }
+        const queueResult = await userMessageQueueService.acquireQueueLock(accountId)
+        if (!queueResult.acquired && !queueResult.skipped) {
+          // 区分 Redis 后端错误和队列超时
+          const isBackendError = queueResult.error === 'queue_backend_error'
+          const errorCode = isBackendError ? 'QUEUE_BACKEND_ERROR' : 'QUEUE_TIMEOUT'
+          const errorType = isBackendError ? 'queue_backend_error' : 'queue_timeout'
+          const errorMessage = isBackendError
+            ? 'Queue service temporarily unavailable, please retry later'
+            : 'User message queue wait timeout, please retry later'
+          const statusCode = isBackendError ? 500 : 503
+
+          // 结构化性能日志，用于后续统计
+          logger.performance('user_message_queue_error', {
+            errorType,
+            errorCode,
+            accountId,
+            statusCode,
+            stream: true,
+            backendError: isBackendError ? queueResult.errorMessage : undefined
+          })
+
+          logger.warn(
+            `📬 User message queue ${errorType} for Bedrock account ${accountId} (stream)`,
+            isBackendError ? { backendError: queueResult.errorMessage } : {}
+          )
+          if (!res.headersSent) {
+            const existingConnection = res.getHeader ? res.getHeader('Connection') : null
+            res.writeHead(statusCode, {
+              'Content-Type': 'text/event-stream',
+              'Cache-Control': 'no-cache',
+              Connection: existingConnection || 'keep-alive',
+              'x-user-message-queue-error': errorType
+            })
+          }
+          const errorEvent = `event: error\ndata: ${JSON.stringify({
+            type: 'error',
+            error: {
+              type: errorType,
+              code: errorCode,
+              message: errorMessage
+            }
+          })}\n\n`
+          res.write(errorEvent)
+          res.write('data: [DONE]\n\n')
+          res.end()
+          return { success: false, error: errorType }
+        }
+        if (queueResult.acquired && !queueResult.skipped) {
+          queueLockAcquired = true
+          queueRequestId = queueResult.requestId
+          logger.debug(
+            `📬 User message queue lock acquired for Bedrock account ${accountId} (stream), requestId: ${queueRequestId}`
+          )
+        }
+      }
+
       const modelId = this._selectModel(requestBody, bedrockAccount)
       const region = this._selectRegion(modelId, bedrockAccount)
       const client = this._getBedrockClient(region, bedrockAccount)
@@ -131,11 +292,35 @@ class BedrockRelayService {
       const startTime = Date.now()
       const response = await client.send(command)
 
+      // 📬 请求已发送成功，立即释放队列锁（无需等待响应处理完成）
+      // 因为限流基于请求发送时刻计算（RPM），不是请求完成时刻
+      if (queueLockAcquired && queueRequestId && accountId) {
+        try {
+          await userMessageQueueService.releaseQueueLock(accountId, queueRequestId)
+          queueLockAcquired = false // 标记已释放，防止 finally 重复释放
+          logger.debug(
+            `📬 User message queue lock released early for Bedrock stream account ${accountId}, requestId: ${queueRequestId}`
+          )
+        } catch (releaseError) {
+          logger.error(
+            `❌ Failed to release user message queue lock early for Bedrock stream account ${accountId}:`,
+            releaseError.message
+          )
+        }
+      }
+
       // 设置SSE响应头
+      // ⚠️ 关键修复：尊重 auth.js 提前设置的 Connection: close
+      const existingConnection = res.getHeader ? res.getHeader('Connection') : null
+      if (existingConnection) {
+        logger.debug(
+          `🔌 [Bedrock Stream] Preserving existing Connection header: ${existingConnection}`
+        )
+      }
       res.writeHead(200, {
         'Content-Type': 'text/event-stream',
         'Cache-Control': 'no-cache',
-        Connection: 'keep-alive',
+        Connection: existingConnection || 'keep-alive',
         'Access-Control-Allow-Origin': '*',
         'Access-Control-Allow-Headers': 'Content-Type, Authorization'
       })
@@ -191,6 +376,21 @@ class BedrockRelayService {
       res.end()
 
       throw this._handleBedrockError(error)
+    } finally {
+      // 📬 释放用户消息队列锁（兜底，正常情况下已在请求发送后提前释放）
+      if (queueLockAcquired && queueRequestId && accountId) {
+        try {
+          await userMessageQueueService.releaseQueueLock(accountId, queueRequestId)
+          logger.debug(
+            `📬 User message queue lock released in finally for Bedrock stream account ${accountId}, requestId: ${queueRequestId}`
+          )
+        } catch (releaseError) {
+          logger.error(
+            `❌ Failed to release user message queue lock for Bedrock stream account ${accountId}:`,
+            releaseError.message
+          )
+        }
+      }
     }
   }
 

src/services/ccrRelayService.js

@@ -3,6 +3,8 @@ const ccrAccountService = require('./ccrAccountService')
 const logger = require('../utils/logger')
 const config = require('../../config/config')
 const { parseVendorPrefixedModel } = require('../utils/modelHelper')
+const userMessageQueueService = require('./userMessageQueueService')
+const { isStreamWritable } = require('../utils/streamHelper')
 
 class CcrRelayService {
   constructor() {
@@ -21,8 +23,67 @@ class CcrRelayService {
   ) {
     let abortController = null
     let account = null
+    let queueLockAcquired = false
+    let queueRequestId = null
 
     try {
+      // 📬 用户消息队列处理
+      if (userMessageQueueService.isUserMessageRequest(requestBody)) {
+        // 校验 accountId 非空，避免空值污染队列锁键
+        if (!accountId || accountId === '') {
+          logger.error('❌ accountId missing for queue lock in CCR relayRequest')
+          throw new Error('accountId missing for queue lock')
+        }
+        const queueResult = await userMessageQueueService.acquireQueueLock(accountId)
+        if (!queueResult.acquired && !queueResult.skipped) {
+          // 区分 Redis 后端错误和队列超时
+          const isBackendError = queueResult.error === 'queue_backend_error'
+          const errorCode = isBackendError ? 'QUEUE_BACKEND_ERROR' : 'QUEUE_TIMEOUT'
+          const errorType = isBackendError ? 'queue_backend_error' : 'queue_timeout'
+          const errorMessage = isBackendError
+            ? 'Queue service temporarily unavailable, please retry later'
+            : 'User message queue wait timeout, please retry later'
+          const statusCode = isBackendError ? 500 : 503
+
+          // 结构化性能日志，用于后续统计
+          logger.performance('user_message_queue_error', {
+            errorType,
+            errorCode,
+            accountId,
+            statusCode,
+            backendError: isBackendError ? queueResult.errorMessage : undefined
+          })
+
+          logger.warn(
+            `📬 User message queue ${errorType} for CCR account ${accountId}`,
+            isBackendError ? { backendError: queueResult.errorMessage } : {}
+          )
+          return {
+            statusCode,
+            headers: {
+              'Content-Type': 'application/json',
+              'x-user-message-queue-error': errorType
+            },
+            body: JSON.stringify({
+              type: 'error',
+              error: {
+                type: errorType,
+                code: errorCode,
+                message: errorMessage
+              }
+            }),
+            accountId
+          }
+        }
+        if (queueResult.acquired && !queueResult.skipped) {
+          queueLockAcquired = true
+          queueRequestId = queueResult.requestId
+          logger.debug(
+            `📬 User message queue lock acquired for CCR account ${accountId}, requestId: ${queueRequestId}`
+          )
+        }
+      }
+
       // 获取账户信息
       account = await ccrAccountService.getAccount(accountId)
       if (!account) {
@@ -162,6 +223,23 @@ class CcrRelayService {
       )
       const response = await axios(requestConfig)
 
+      // 📬 请求已发送成功，立即释放队列锁（无需等待响应处理完成）
+      // 因为 Claude API 限流基于请求发送时刻计算（RPM），不是请求完成时刻
+      if (queueLockAcquired && queueRequestId && accountId) {
+        try {
+          await userMessageQueueService.releaseQueueLock(accountId, queueRequestId)
+          queueLockAcquired = false // 标记已释放，防止 finally 重复释放
+          logger.debug(
+            `📬 User message queue lock released early for CCR account ${accountId}, requestId: ${queueRequestId}`
+          )
+        } catch (releaseError) {
+          logger.error(
+            `❌ Failed to release user message queue lock early for CCR account ${accountId}:`,
+            releaseError.message
+          )
+        }
+      }
+
       // 移除监听器（请求成功完成）
       if (clientRequest) {
         clientRequest.removeListener('close', handleClientDisconnect)
@@ -233,6 +311,21 @@ class CcrRelayService {
       )
 
       throw error
+    } finally {
+      // 📬 释放用户消息队列锁（兜底，正常情况下已在请求发送后提前释放）
+      if (queueLockAcquired && queueRequestId && accountId) {
+        try {
+          await userMessageQueueService.releaseQueueLock(accountId, queueRequestId)
+          logger.debug(
+            `📬 User message queue lock released in finally for CCR account ${accountId}, requestId: ${queueRequestId}`
+          )
+        } catch (releaseError) {
+          logger.error(
+            `❌ Failed to release user message queue lock for CCR account ${accountId}:`,
+            releaseError.message
+          )
+        }
+      }
     }
   }
 
@@ -248,7 +341,77 @@ class CcrRelayService {
     options = {}
   ) {
     let account = null
+    let queueLockAcquired = false
+    let queueRequestId = null
+
     try {
+      // 📬 用户消息队列处理
+      if (userMessageQueueService.isUserMessageRequest(requestBody)) {
+        // 校验 accountId 非空，避免空值污染队列锁键
+        if (!accountId || accountId === '') {
+          logger.error(
+            '❌ accountId missing for queue lock in CCR relayStreamRequestWithUsageCapture'
+          )
+          throw new Error('accountId missing for queue lock')
+        }
+        const queueResult = await userMessageQueueService.acquireQueueLock(accountId)
+        if (!queueResult.acquired && !queueResult.skipped) {
+          // 区分 Redis 后端错误和队列超时
+          const isBackendError = queueResult.error === 'queue_backend_error'
+          const errorCode = isBackendError ? 'QUEUE_BACKEND_ERROR' : 'QUEUE_TIMEOUT'
+          const errorType = isBackendError ? 'queue_backend_error' : 'queue_timeout'
+          const errorMessage = isBackendError
+            ? 'Queue service temporarily unavailable, please retry later'
+            : 'User message queue wait timeout, please retry later'
+          const statusCode = isBackendError ? 500 : 503
+
+          // 结构化性能日志，用于后续<E5908E><E7BBAD>计
+          logger.performance('user_message_queue_error', {
+            errorType,
+            errorCode,
+            accountId,
+            statusCode,
+            stream: true,
+            backendError: isBackendError ? queueResult.errorMessage : undefined
+          })
+
+          logger.warn(
+            `📬 User message queue ${errorType} for CCR account ${accountId} (stream)`,
+            isBackendError ? { backendError: queueResult.errorMessage } : {}
+          )
+          if (!responseStream.headersSent) {
+            const existingConnection = responseStream.getHeader
+              ? responseStream.getHeader('Connection')
+              : null
+            responseStream.writeHead(statusCode, {
+              'Content-Type': 'text/event-stream',
+              'Cache-Control': 'no-cache',
+              Connection: existingConnection || 'keep-alive',
+              'x-user-message-queue-error': errorType
+            })
+          }
+          const errorEvent = `event: error\ndata: ${JSON.stringify({
+            type: 'error',
+            error: {
+              type: errorType,
+              code: errorCode,
+              message: errorMessage
+            }
+          })}\n\n`
+          responseStream.write(errorEvent)
+          responseStream.write('data: [DONE]\n\n')
+          responseStream.end()
+          return
+        }
+        if (queueResult.acquired && !queueResult.skipped) {
+          queueLockAcquired = true
+          queueRequestId = queueResult.requestId
+          logger.debug(
+            `📬 User message queue lock acquired for CCR account ${accountId} (stream), requestId: ${queueRequestId}`
+          )
+        }
+      }
+
       // 获取账户信息
       account = await ccrAccountService.getAccount(accountId)
       if (!account) {
@@ -296,14 +459,53 @@ class CcrRelayService {
         accountId,
         usageCallback,
         streamTransformer,
-        options
+        options,
+        // 📬 回调：在收到响应头时释放队列锁
+        async () => {
+          if (queueLockAcquired && queueRequestId && accountId) {
+            try {
+              await userMessageQueueService.releaseQueueLock(accountId, queueRequestId)
+              queueLockAcquired = false // 标记已释放，防止 finally 重复释放
+              logger.debug(
+                `📬 User message queue lock released early for CCR stream account ${accountId}, requestId: ${queueRequestId}`
+              )
+            } catch (releaseError) {
+              logger.error(
+                `❌ Failed to release user message queue lock early for CCR stream account ${accountId}:`,
+                releaseError.message
+              )
+            }
+          }
+        }
       )
 
       // 更新最后使用时间
       await this._updateLastUsedTime(accountId)
     } catch (error) {
+      // 客户端主动断开连接是正常情况，使用 INFO 级别
+      if (error.message === 'Client disconnected') {
+        logger.info(
+          `🔌 CCR stream relay ended: Client disconnected (Account: ${account?.name || accountId})`
+        )
+      } else {
         logger.error(`❌ CCR stream relay failed (Account: ${account?.name || accountId}):`, error)
+      }
       throw error
+    } finally {
+      // 📬 释放用户消息队列锁（兜底，正常情况下已在收到响应头后提前释放）
+      if (queueLockAcquired && queueRequestId && accountId) {
+        try {
+          await userMessageQueueService.releaseQueueLock(accountId, queueRequestId)
+          logger.debug(
+            `📬 User message queue lock released in finally for CCR stream account ${accountId}, requestId: ${queueRequestId}`
+          )
+        } catch (releaseError) {
+          logger.error(
+            `❌ Failed to release user message queue lock for CCR stream account ${accountId}:`,
+            releaseError.message
+          )
+        }
+      }
     }
   }
 
@@ -317,7 +519,8 @@ class CcrRelayService {
     accountId,
     usageCallback,
     streamTransformer = null,
-    requestOptions = {}
+    requestOptions = {},
+    onResponseHeaderReceived = null
   ) {
     return new Promise((resolve, reject) => {
       let aborted = false
@@ -380,8 +583,11 @@ class CcrRelayService {
       // 发送请求
       const request = axios(requestConfig)
 
+      // 注意：使用 .then(async ...) 模式处理响应
+      // - 内部的 releaseQueueLock 有独立的 try-catch，不会导致未捕获异常
+      // - queueLockAcquired = false 的赋值会在 finally 执行前完成（JS 单线程保证）
       request
-        .then((response) => {
+        .then(async (response) => {
           logger.debug(`🌊 CCR stream response status: ${response.status}`)
 
           // 错误响应处理
@@ -404,10 +610,13 @@ class CcrRelayService {
 
             // 设置错误响应的状态码和响应头
             if (!responseStream.headersSent) {
+              const existingConnection = responseStream.getHeader
+                ? responseStream.getHeader('Connection')
+                : null
               const errorHeaders = {
                 'Content-Type': response.headers['content-type'] || 'application/json',
                 'Cache-Control': 'no-cache',
-                Connection: 'keep-alive'
+                Connection: existingConnection || 'keep-alive'
               }
               // 避免 Transfer-Encoding 冲突，让 Express 自动处理
               delete errorHeaders['Transfer-Encoding']
@@ -417,13 +626,13 @@ class CcrRelayService {
 
             // 直接透传错误数据，不进行包装
             response.data.on('data', (chunk) => {
-              if (!responseStream.destroyed) {
+              if (isStreamWritable(responseStream)) {
                 responseStream.write(chunk)
               }
             })
 
             response.data.on('end', () => {
-              if (!responseStream.destroyed) {
+              if (isStreamWritable(responseStream)) {
                 responseStream.end()
               }
               resolve() // 不抛出异常，正常完成流处理
@@ -431,6 +640,19 @@ class CcrRelayService {
             return
           }
 
+          // 📬 收到成功响应头（HTTP 200），调用回调释放队列锁
+          // 此时请求已被 Claude API 接受并计入 RPM 配额，无需等待响应完成
+          if (onResponseHeaderReceived && typeof onResponseHeaderReceived === 'function') {
+            try {
+              await onResponseHeaderReceived()
+            } catch (callbackError) {
+              logger.error(
+                `❌ Failed to execute onResponseHeaderReceived callback for CCR stream account ${accountId}:`,
+                callbackError.message
+              )
+            }
+          }
+
           // 成功响应，检查并移除错误状态
           ccrAccountService.isAccountRateLimited(accountId).then((isRateLimited) => {
             if (isRateLimited) {
@@ -444,11 +666,20 @@ class CcrRelayService {
           })
 
           // 设置响应头
+          // ⚠️ 关键修复：尊重 auth.js 提前设置的 Connection: close
           if (!responseStream.headersSent) {
+            const existingConnection = responseStream.getHeader
+              ? responseStream.getHeader('Connection')
+              : null
+            if (existingConnection) {
+              logger.debug(
+                `🔌 [CCR Stream] Preserving existing Connection header: ${existingConnection}`
+              )
+            }
             const headers = {
               'Content-Type': 'text/event-stream',
               'Cache-Control': 'no-cache',
-              Connection: 'keep-alive',
+              Connection: existingConnection || 'keep-alive',
               'Access-Control-Allow-Origin': '*',
               'Access-Control-Allow-Headers': 'Cache-Control'
             }
@@ -487,12 +718,17 @@ class CcrRelayService {
                   }
 
                   // 写入到响应流
-                  if (outputLine && !responseStream.destroyed) {
+                  if (outputLine && isStreamWritable(responseStream)) {
                     responseStream.write(`${outputLine}\n`)
+                  } else if (outputLine) {
+                    // 客户端连接已断开，记录警告
+                    logger.warn(
+                      `⚠️ [CCR] Client disconnected during stream, skipping data for account: ${accountId}`
+                    )
                   }
                 } else {
                   // 空行也需要传递
-                  if (!responseStream.destroyed) {
+                  if (isStreamWritable(responseStream)) {
                     responseStream.write('\n')
                   }
                 }
@@ -503,10 +739,6 @@ class CcrRelayService {
           })
 
           response.data.on('end', () => {
-            if (!responseStream.destroyed) {
-              responseStream.end()
-            }
-
             // 如果收集到使用统计数据，调用回调
             if (usageCallback && Object.keys(collectedUsage).length > 0) {
               try {
@@ -518,12 +750,26 @@ class CcrRelayService {
               }
             }
 
+            if (isStreamWritable(responseStream)) {
+              // 等待数据完全 flush 到客户端后再 resolve
+              responseStream.end(() => {
+                logger.debug(
+                  `🌊 CCR stream response completed and flushed | bytesWritten: ${responseStream.bytesWritten || 'unknown'}`
+                )
                 resolve()
               })
+            } else {
+              // 连接已断开，记录警告
+              logger.warn(
+                `⚠️ [CCR] Client disconnected before stream end, data may not have been received | account: ${accountId}`
+              )
+              resolve()
+            }
+          })
 
           response.data.on('error', (err) => {
             logger.error('❌ Stream data error:', err)
-            if (!responseStream.destroyed) {
+            if (isStreamWritable(responseStream)) {
               responseStream.end()
             }
             reject(err)
@@ -555,7 +801,7 @@ class CcrRelayService {
             }
           }
 
-          if (!responseStream.destroyed) {
+          if (isStreamWritable(responseStream)) {
             responseStream.write(`data: ${JSON.stringify(errorResponse)}\n\n`)
             responseStream.end()
           }

src/services/claudeAccountService.js

@@ -16,6 +16,22 @@ const {
 const tokenRefreshService = require('./tokenRefreshService')
 const LRUCache = require('../utils/lruCache')
 const { formatDateWithTimezone, getISOStringWithTimezone } = require('../utils/dateHelper')
+const { isOpus45OrNewer } = require('../utils/modelHelper')
+
+/**
+ * Check if account is Pro (not Max)
+ * Compatible with both API real-time data (hasClaudePro) and local config (accountType)
+ * @param {Object} info - Subscription info object
+ * @returns {boolean}
+ */
+function isProAccount(info) {
+  // API real-time status takes priority
+  if (info.hasClaudePro === true && info.hasClaudeMax !== true) {
+    return true
+  }
+  // Local configured account type
+  return info.accountType === 'claude_pro'
+}
 
 class ClaudeAccountService {
   constructor() {
@@ -852,31 +868,39 @@ class ClaudeAccountService {
           !this.isSubscriptionExpired(account)
       )
 
-      // 如果请求的是 Opus 模型，过滤掉 Pro 和 Free 账号
+      // Filter Opus models based on account type and model version
       if (modelName && modelName.toLowerCase().includes('opus')) {
+        const isNewOpus = isOpus45OrNewer(modelName)
+
         activeAccounts = activeAccounts.filter((account) => {
-          // 检查账号的订阅信息
           if (account.subscriptionInfo) {
             try {
               const info = JSON.parse(account.subscriptionInfo)
-              // Pro 和 Free 账号不支持 Opus
+
-              if (info.hasClaudePro === true && info.hasClaudeMax !== true) {
+              // Free account: does not support any Opus model
-                return false // Claude Pro 不支持 Opus
+              if (info.accountType === 'free') {
+                return false
               }
-              if (info.accountType === 'claude_pro' || info.accountType === 'claude_free') {
+
-                return false // 明确标记为 Pro 或 Free 的账号不支持
+              // Pro account: only supports Opus 4.5+
+              if (isProAccount(info)) {
+                return isNewOpus
               }
+
+              // Max account: supports all Opus versions
+              return true
             } catch (e) {
-              // 解析失败，假设为旧数据，默认支持（兼容旧数据为 Max）
+              // Parse failed, assume legacy data (Max), default support
               return true
             }
           }
-          // 没有订阅信息的账号，默认当作支持（兼容旧数据）
+          // Account without subscription info, default to supported (legacy data compatibility)
           return true
         })
 
         if (activeAccounts.length === 0) {
-          throw new Error('No Claude accounts available that support Opus model')
+          const modelDesc = isNewOpus ? 'Opus 4.5+' : 'legacy Opus (requires Max subscription)'
+          throw new Error(`No Claude accounts available that support ${modelDesc} model`)
         }
       }
 
@@ -970,31 +994,39 @@ class ClaudeAccountService {
           !this.isSubscriptionExpired(account)
       )
 
-      // 如果请求的是 Opus 模型，过滤掉 Pro 和 Free 账号
+      // Filter Opus models based on account type and model version
       if (modelName && modelName.toLowerCase().includes('opus')) {
+        const isNewOpus = isOpus45OrNewer(modelName)
+
         sharedAccounts = sharedAccounts.filter((account) => {
-          // 检查账号的订阅信息
           if (account.subscriptionInfo) {
             try {
               const info = JSON.parse(account.subscriptionInfo)
-              // Pro 和 Free 账号不支持 Opus
+
-              if (info.hasClaudePro === true && info.hasClaudeMax !== true) {
+              // Free account: does not support any Opus model
-                return false // Claude Pro 不支持 Opus
+              if (info.accountType === 'free') {
+                return false
               }
-              if (info.accountType === 'claude_pro' || info.accountType === 'claude_free') {
+
-                return false // 明确标记为 Pro 或 Free 的账号不支持
+              // Pro account: only supports Opus 4.5+
+              if (isProAccount(info)) {
+                return isNewOpus
               }
+
+              // Max account: supports all Opus versions
+              return true
             } catch (e) {
-              // 解析失败，假设为旧数据，默认支持（兼容旧数据为 Max）
+              // Parse failed, assume legacy data (Max), default support
               return true
             }
           }
-          // 没有订阅信息的账号，默认当作支持（兼容旧数据）
+          // Account without subscription info, default to supported (legacy data compatibility)
           return true
         })
 
         if (sharedAccounts.length === 0) {
-          throw new Error('No shared Claude accounts available that support Opus model')
+          const modelDesc = isNewOpus ? 'Opus 4.5+' : 'legacy Opus (requires Max subscription)'
+          throw new Error(`No shared Claude accounts available that support ${modelDesc} model`)
         }
       }
 

src/services/claudeConsoleRelayService.js

@@ -9,6 +9,9 @@ const {
   sanitizeErrorMessage,
   isAccountDisabledError
 } = require('../utils/errorSanitizer')
+const userMessageQueueService = require('./userMessageQueueService')
+const { isStreamWritable } = require('../utils/streamHelper')
+const { filterForClaude } = require('../utils/headerFilter')
 
 class ClaudeConsoleRelayService {
   constructor() {
@@ -29,8 +32,68 @@ class ClaudeConsoleRelayService {
     let account = null
     const requestId = uuidv4() // 用于并发追踪
     let concurrencyAcquired = false
+    let queueLockAcquired = false
+    let queueRequestId = null
 
     try {
+      // 📬 用户消息队列处理：如果是用户消息请求，需要获取队列锁
+      if (userMessageQueueService.isUserMessageRequest(requestBody)) {
+        // 校验 accountId 非空，避免空值污染队列锁键
+        if (!accountId || accountId === '') {
+          logger.error('❌ accountId missing for queue lock in console relayRequest')
+          throw new Error('accountId missing for queue lock')
+        }
+        const queueResult = await userMessageQueueService.acquireQueueLock(accountId)
+        if (!queueResult.acquired && !queueResult.skipped) {
+          // 区分 Redis 后端错误和队列超时
+          const isBackendError = queueResult.error === 'queue_backend_error'
+          const errorCode = isBackendError ? 'QUEUE_BACKEND_ERROR' : 'QUEUE_TIMEOUT'
+          const errorType = isBackendError ? 'queue_backend_error' : 'queue_timeout'
+          const errorMessage = isBackendError
+            ? 'Queue service temporarily unavailable, please retry later'
+            : 'User message queue wait timeout, please retry later'
+          const statusCode = isBackendError ? 500 : 503
+
+          // 结构化性能日志，用于后续统计
+          logger.performance('user_message_queue_error', {
+            errorType,
+            errorCode,
+            accountId,
+            statusCode,
+            apiKeyName: apiKeyData.name,
+            backendError: isBackendError ? queueResult.errorMessage : undefined
+          })
+
+          logger.warn(
+            `📬 User message queue ${errorType} for console account ${accountId}, key: ${apiKeyData.name}`,
+            isBackendError ? { backendError: queueResult.errorMessage } : {}
+          )
+          return {
+            statusCode,
+            headers: {
+              'Content-Type': 'application/json',
+              'x-user-message-queue-error': errorType
+            },
+            body: JSON.stringify({
+              type: 'error',
+              error: {
+                type: errorType,
+                code: errorCode,
+                message: errorMessage
+              }
+            }),
+            accountId
+          }
+        }
+        if (queueResult.acquired && !queueResult.skipped) {
+          queueLockAcquired = true
+          queueRequestId = queueResult.requestId
+          logger.debug(
+            `📬 User message queue lock acquired for console account ${accountId}, requestId: ${queueRequestId}`
+          )
+        }
+      }
+
       // 获取账户信息
       account = await claudeConsoleAccountService.getAccount(accountId)
       if (!account) {
@@ -203,6 +266,23 @@ class ClaudeConsoleRelayService {
       )
       const response = await axios(requestConfig)
 
+      // 📬 请求已发送成功，立即释放队列锁（无需等待响应处理完成）
+      // 因为 Claude API 限流基于请求发送时刻计算（RPM），不是请求完成时刻
+      if (queueLockAcquired && queueRequestId && accountId) {
+        try {
+          await userMessageQueueService.releaseQueueLock(accountId, queueRequestId)
+          queueLockAcquired = false // 标记已释放，防止 finally 重复释放
+          logger.debug(
+            `📬 User message queue lock released early for console account ${accountId}, requestId: ${queueRequestId}`
+          )
+        } catch (releaseError) {
+          logger.error(
+            `❌ Failed to release user message queue lock early for console account ${accountId}:`,
+            releaseError.message
+          )
+        }
+      }
+
       // 移除监听器（请求成功完成）
       if (clientRequest) {
         clientRequest.removeListener('close', handleClientDisconnect)
@@ -366,6 +446,21 @@ class ClaudeConsoleRelayService {
           )
         }
       }
+
+      // 📬 释放用户消息队列锁（兜底，正常情况下已在请求发送后提前释放）
+      if (queueLockAcquired && queueRequestId && accountId) {
+        try {
+          await userMessageQueueService.releaseQueueLock(accountId, queueRequestId)
+          logger.debug(
+            `📬 User message queue lock released in finally for console account ${accountId}, requestId: ${queueRequestId}`
+          )
+        } catch (releaseError) {
+          logger.error(
+            `❌ Failed to release user message queue lock for account ${accountId}:`,
+            releaseError.message
+          )
+        }
+      }
     }
   }
 
@@ -384,8 +479,71 @@ class ClaudeConsoleRelayService {
     const requestId = uuidv4() // 用于并发追踪
     let concurrencyAcquired = false
     let leaseRefreshInterval = null // 租约刷新定时器
+    let queueLockAcquired = false
+    let queueRequestId = null
 
     try {
+      // 📬 用户消息队列处理：如果是用户消息请求，需要获取队列锁
+      if (userMessageQueueService.isUserMessageRequest(requestBody)) {
+        // 校验 accountId 非空，避免空值污染队列锁键
+        if (!accountId || accountId === '') {
+          logger.error(
+            '❌ accountId missing for queue lock in console relayStreamRequestWithUsageCapture'
+          )
+          throw new Error('accountId missing for queue lock')
+        }
+        const queueResult = await userMessageQueueService.acquireQueueLock(accountId)
+        if (!queueResult.acquired && !queueResult.skipped) {
+          // 区分 Redis 后端错误和队列超时
+          const isBackendError = queueResult.error === 'queue_backend_error'
+          const errorCode = isBackendError ? 'QUEUE_BACKEND_ERROR' : 'QUEUE_TIMEOUT'
+          const errorType = isBackendError ? 'queue_backend_error' : 'queue_timeout'
+          const errorMessage = isBackendError
+            ? 'Queue service temporarily unavailable, please retry later'
+            : 'User message queue wait timeout, please retry later'
+          const statusCode = isBackendError ? 500 : 503
+
+          // 结构化性能日志，用于后续统计
+          logger.performance('user_message_queue_error', {
+            errorType,
+            errorCode,
+            accountId,
+            statusCode,
+            stream: true,
+            apiKeyName: apiKeyData.name,
+            backendError: isBackendError ? queueResult.errorMessage : undefined
+          })
+
+          logger.warn(
+            `📬 User message queue ${errorType} for console account ${accountId} (stream), key: ${apiKeyData.name}`,
+            isBackendError ? { backendError: queueResult.errorMessage } : {}
+          )
+          if (!responseStream.headersSent) {
+            const existingConnection = responseStream.getHeader
+              ? responseStream.getHeader('Connection')
+              : null
+            responseStream.writeHead(statusCode, {
+              'Content-Type': 'text/event-stream',
+              'Cache-Control': 'no-cache',
+              Connection: existingConnection || 'keep-alive',
+              'x-user-message-queue-error': errorType
+            })
+          }
+          const errorEvent = `event: error\ndata: ${JSON.stringify({ type: 'error', error: { type: errorType, code: errorCode, message: errorMessage } })}\n\n`
+          responseStream.write(errorEvent)
+          responseStream.write('data: [DONE]\n\n')
+          responseStream.end()
+          return
+        }
+        if (queueResult.acquired && !queueResult.skipped) {
+          queueLockAcquired = true
+          queueRequestId = queueResult.requestId
+          logger.debug(
+            `📬 User message queue lock acquired for console account ${accountId} (stream), requestId: ${queueRequestId}`
+          )
+        }
+      }
+
       // 获取账户信息
       account = await claudeConsoleAccountService.getAccount(accountId)
       if (!account) {
@@ -483,16 +641,40 @@ class ClaudeConsoleRelayService {
         accountId,
         usageCallback,
         streamTransformer,
-        options
+        options,
+        // 📬 回调：在收到响应头时释放队列锁
+        async () => {
+          if (queueLockAcquired && queueRequestId && accountId) {
+            try {
+              await userMessageQueueService.releaseQueueLock(accountId, queueRequestId)
+              queueLockAcquired = false // 标记已释放，防止 finally 重复释放
+              logger.debug(
+                `📬 User message queue lock released early for console stream account ${accountId}, requestId: ${queueRequestId}`
+              )
+            } catch (releaseError) {
+              logger.error(
+                `❌ Failed to release user message queue lock early for console stream account ${accountId}:`,
+                releaseError.message
+              )
+            }
+          }
+        }
       )
 
       // 更新最后使用时间
       await this._updateLastUsedTime(accountId)
     } catch (error) {
+      // 客户端主动断开连接是正常情况，使用 INFO 级别
+      if (error.message === 'Client disconnected') {
+        logger.info(
+          `🔌 Claude Console stream relay ended: Client disconnected (Account: ${account?.name || accountId})`
+        )
+      } else {
         logger.error(
           `❌ Claude Console stream relay failed (Account: ${account?.name || accountId}):`,
           error
         )
+      }
       throw error
     } finally {
       // 🛑 清理租约刷新定时器
@@ -517,6 +699,21 @@ class ClaudeConsoleRelayService {
           )
         }
       }
+
+      // 📬 释放用户消息队列锁（兜底，正常情况下已在收到响应头后提前释放）
+      if (queueLockAcquired && queueRequestId && accountId) {
+        try {
+          await userMessageQueueService.releaseQueueLock(accountId, queueRequestId)
+          logger.debug(
+            `📬 User message queue lock released in finally for console stream account ${accountId}, requestId: ${queueRequestId}`
+          )
+        } catch (releaseError) {
+          logger.error(
+            `❌ Failed to release user message queue lock for stream account ${accountId}:`,
+            releaseError.message
+          )
+        }
+      }
     }
   }
 
@@ -530,7 +727,8 @@ class ClaudeConsoleRelayService {
     accountId,
     usageCallback,
     streamTransformer = null,
-    requestOptions = {}
+    requestOptions = {},
+    onResponseHeaderReceived = null
   ) {
     return new Promise((resolve, reject) => {
       let aborted = false
@@ -593,8 +791,11 @@ class ClaudeConsoleRelayService {
       // 发送请求
       const request = axios(requestConfig)
 
+      // 注意：使用 .then(async ...) 模式处理响应
+      // - 内部的 releaseQueueLock 有独立的 try-catch，不会导致未捕获异常
+      // - queueLockAcquired = false 的赋值会在 finally 执行前完成（JS 单线程保证）
       request
-        .then((response) => {
+        .then(async (response) => {
           logger.debug(`🌊 Claude Console Claude stream response status: ${response.status}`)
 
           // 错误响应处理
@@ -682,7 +883,7 @@ class ClaudeConsoleRelayService {
                   `🧹 [Stream] [SANITIZED] Error response to client: ${JSON.stringify(sanitizedError)}`
                 )
 
-                if (!responseStream.destroyed) {
+                if (isStreamWritable(responseStream)) {
                   responseStream.write(JSON.stringify(sanitizedError))
                   responseStream.end()
                 }
@@ -690,7 +891,7 @@ class ClaudeConsoleRelayService {
                 const sanitizedText = sanitizeErrorMessage(errorDataForCheck)
                 logger.error(`🧹 [Stream] [SANITIZED] Error response to client: ${sanitizedText}`)
 
-                if (!responseStream.destroyed) {
+                if (isStreamWritable(responseStream)) {
                   responseStream.write(sanitizedText)
                   responseStream.end()
                 }
@@ -701,6 +902,19 @@ class ClaudeConsoleRelayService {
             return
           }
 
+          // 📬 收到成功响应头（HTTP 200），调用回调释放队列锁
+          // 此时请求已被 Claude API 接受并计入 RPM 配额，无需等待响应完成
+          if (onResponseHeaderReceived && typeof onResponseHeaderReceived === 'function') {
+            try {
+              await onResponseHeaderReceived()
+            } catch (callbackError) {
+              logger.error(
+                `❌ Failed to execute onResponseHeaderReceived callback for console stream account ${accountId}:`,
+                callbackError.message
+              )
+            }
+          }
+
           // 成功响应，检查并移除错误状态
           claudeConsoleAccountService.isAccountRateLimited(accountId).then((isRateLimited) => {
             if (isRateLimited) {
@@ -714,11 +928,22 @@ class ClaudeConsoleRelayService {
           })
 
           // 设置响应头
+          // ⚠️ 关键修复：尊重 auth.js 提前设置的 Connection: close
+          // 当并发队列功能启用时，auth.js 会设置 Connection: close 来禁用 Keep-Alive
           if (!responseStream.headersSent) {
+            const existingConnection = responseStream.getHeader
+              ? responseStream.getHeader('Connection')
+              : null
+            const connectionHeader = existingConnection || 'keep-alive'
+            if (existingConnection) {
+              logger.debug(
+                `🔌 [Console Stream] Preserving existing Connection header: ${existingConnection}`
+              )
+            }
             responseStream.writeHead(200, {
               'Content-Type': 'text/event-stream',
               'Cache-Control': 'no-cache',
-              Connection: 'keep-alive',
+              Connection: connectionHeader,
               'X-Accel-Buffering': 'no'
             })
           }
@@ -744,20 +969,33 @@ class ClaudeConsoleRelayService {
               buffer = lines.pop() || ''
 
               // 转发数据并解析usage
-              if (lines.length > 0 && !responseStream.destroyed) {
+              if (lines.length > 0) {
+                // 检查流是否可写（客户端连接是否有效）
+                if (isStreamWritable(responseStream)) {
                   const linesToForward = lines.join('\n') + (lines.length > 0 ? '\n' : '')
 
                   // 应用流转换器如果有
+                  let dataToWrite = linesToForward
                   if (streamTransformer) {
                     const transformed = streamTransformer(linesToForward)
                     if (transformed) {
-                    responseStream.write(transformed)
+                      dataToWrite = transformed
-                  }
                     } else {
-                  responseStream.write(linesToForward)
+                      dataToWrite = null
+                    }
                   }
 
-                // 解析SSE数据寻找usage信息
+                  if (dataToWrite) {
+                    responseStream.write(dataToWrite)
+                  }
+                } else {
+                  // 客户端连接已断开，记录警告（但仍继续解析usage）
+                  logger.warn(
+                    `⚠️ [Console] Client disconnected during stream, skipping ${lines.length} lines for account: ${account?.name || accountId}`
+                  )
+                }
+
+                // 解析SSE数据寻找usage信息（无论连接状态如何）
                 for (const line of lines) {
                   if (line.startsWith('data:')) {
                     const jsonStr = line.slice(5).trimStart()
@@ -865,7 +1103,7 @@ class ClaudeConsoleRelayService {
                 `❌ Error processing Claude Console stream data (Account: ${account?.name || accountId}):`,
                 error
               )
-              if (!responseStream.destroyed) {
+              if (isStreamWritable(responseStream)) {
                 // 如果有 streamTransformer（如测试请求），使用前端期望的格式
                 if (streamTransformer) {
                   responseStream.write(
@@ -888,7 +1126,7 @@ class ClaudeConsoleRelayService {
           response.data.on('end', () => {
             try {
               // 处理缓冲区中剩余的数据
-              if (buffer.trim() && !responseStream.destroyed) {
+              if (buffer.trim() && isStreamWritable(responseStream)) {
                 if (streamTransformer) {
                   const transformed = streamTransformer(buffer)
                   if (transformed) {
@@ -937,12 +1175,33 @@ class ClaudeConsoleRelayService {
               }
 
               // 确保流正确结束
-              if (!responseStream.destroyed) {
+              if (isStreamWritable(responseStream)) {
-                responseStream.end()
+                // 📊 诊断日志：流结束前状态
+                logger.info(
+                  `📤 [STREAM] Ending response | destroyed: ${responseStream.destroyed}, ` +
+                    `socketDestroyed: ${responseStream.socket?.destroyed}, ` +
+                    `socketBytesWritten: ${responseStream.socket?.bytesWritten || 0}`
+                )
+
+                // 禁用 Nagle 算法确保数据立即发送
+                if (responseStream.socket && !responseStream.socket.destroyed) {
+                  responseStream.socket.setNoDelay(true)
                 }
 
-              logger.debug('🌊 Claude Console Claude stream response completed')
+                // 等待数据完全 flush 到客户端后再 resolve
+                responseStream.end(() => {
+                  logger.info(
+                    `✅ [STREAM] Response ended and flushed | socketBytesWritten: ${responseStream.socket?.bytesWritten || 'unknown'}`
+                  )
                   resolve()
+                })
+              } else {
+                // 连接已断开，记录警告
+                logger.warn(
+                  `⚠️ [Console] Client disconnected before stream end, data may not have been received | account: ${account?.name || accountId}`
+                )
+                resolve()
+              }
             } catch (error) {
               logger.error('❌ Error processing stream end:', error)
               reject(error)
@@ -954,7 +1213,7 @@ class ClaudeConsoleRelayService {
               `❌ Claude Console stream error (Account: ${account?.name || accountId}):`,
               error
             )
-            if (!responseStream.destroyed) {
+            if (isStreamWritable(responseStream)) {
               // 如果有 streamTransformer（如测试请求），使用前端期望的格式
               if (streamTransformer) {
                 responseStream.write(
@@ -1002,14 +1261,17 @@ class ClaudeConsoleRelayService {
 
           // 发送错误响应
           if (!responseStream.headersSent) {
+            const existingConnection = responseStream.getHeader
+              ? responseStream.getHeader('Connection')
+              : null
             responseStream.writeHead(error.response?.status || 500, {
               'Content-Type': 'text/event-stream',
               'Cache-Control': 'no-cache',
-              Connection: 'keep-alive'
+              Connection: existingConnection || 'keep-alive'
             })
           }
 
-          if (!responseStream.destroyed) {
+          if (isStreamWritable(responseStream)) {
             // 如果有 streamTransformer（如测试请求），使用前端期望的格式
             if (streamTransformer) {
               responseStream.write(
@@ -1041,30 +1303,9 @@ class ClaudeConsoleRelayService {
 
   // 🔧 过滤客户端请求头
   _filterClientHeaders(clientHeaders) {
-    const sensitiveHeaders = [
+    // 使用统一的 headerFilter 工具类（白名单模式）
-      'content-type',
+    // 与 claudeRelayService 保持一致，避免透传 CDN headers 触发上游 API 安全检查
-      'user-agent',
+    return filterForClaude(clientHeaders)
-      'authorization',
-      'x-api-key',
-      'host',
-      'content-length',
-      'connection',
-      'proxy-authorization',
-      'content-encoding',
-      'transfer-encoding',
-      'anthropic-version'
-    ]
-
-    const filteredHeaders = {}
-
-    Object.keys(clientHeaders || {}).forEach((key) => {
-      const lowerKey = key.toLowerCase()
-      if (!sensitiveHeaders.includes(lowerKey)) {
-        filteredHeaders[key] = clientHeaders[key]
-      }
-    })
-
-    return filteredHeaders
   }
 
   // 🕐 更新最后使用时间
@@ -1179,7 +1420,7 @@ class ClaudeConsoleRelayService {
           'Cache-Control': 'no-cache'
         })
       }
-      if (!responseStream.destroyed && !responseStream.writableEnded) {
+      if (isStreamWritable(responseStream)) {
         responseStream.write(
           `data: ${JSON.stringify({ type: 'test_complete', success: false, error: error.message })}\n\n`
         )

src/services/claudeRelayConfigService.js

@@ -0,0 +1,453 @@
+/**
+ * Claude 转发配置服务
+ * 管理全局 Claude Code 限制和会话绑定配置
+ */
+
+const redis = require('../models/redis')
+const logger = require('../utils/logger')
+
+const CONFIG_KEY = 'claude_relay_config'
+const SESSION_BINDING_PREFIX = 'original_session_binding:'
+
+// 默认配置
+const DEFAULT_CONFIG = {
+  claudeCodeOnlyEnabled: false,
+  globalSessionBindingEnabled: false,
+  sessionBindingErrorMessage: '你的本地session已污染，请清理后使用。',
+  sessionBindingTtlDays: 30, // 会话绑定 TTL（天），默认30天
+  // 用户消息队列配置
+  userMessageQueueEnabled: false, // 是否启用用户消息队列（默认关闭）
+  userMessageQueueDelayMs: 200, // 请求间隔（毫秒）
+  userMessageQueueTimeoutMs: 5000, // 队列等待超时（毫秒），优化后锁持有时间短无需长等待
+  userMessageQueueLockTtlMs: 5000, // 锁TTL（毫秒），请求发送后立即释放无需长TTL
+  // 并发请求排队配置
+  concurrentRequestQueueEnabled: false, // 是否启用并发请求排队（默认关闭）
+  concurrentRequestQueueMaxSize: 3, // 固定最小排队数（默认3）
+  concurrentRequestQueueMaxSizeMultiplier: 0, // 并发数的倍数（默认0，仅使用固定值）
+  concurrentRequestQueueTimeoutMs: 10000, // 排队超时（毫秒，默认10秒）
+  concurrentRequestQueueMaxRedisFailCount: 5, // 连续 Redis 失败阈值（默认5次）
+  // 排队健康检查配置
+  concurrentRequestQueueHealthCheckEnabled: true, // 是否启用排队健康检查（默认开启）
+  concurrentRequestQueueHealthThreshold: 0.8, // 健康检查阈值（P90 >= 超时 × 阈值时拒绝新请求）
+  updatedAt: null,
+  updatedBy: null
+}
+
+// 内存缓存（避免频繁 Redis 查询）
+let configCache = null
+let configCacheTime = 0
+const CONFIG_CACHE_TTL = 60000 // 1分钟缓存
+
+class ClaudeRelayConfigService {
+  /**
+   * 从 metadata.user_id 中提取原始 sessionId
+   * 格式: user_{64位十六进制}_account__session_{uuid}
+   * @param {Object} requestBody - 请求体
+   * @returns {string|null} 原始 sessionId 或 null
+   */
+  extractOriginalSessionId(requestBody) {
+    if (!requestBody?.metadata?.user_id) {
+      return null
+    }
+
+    const userId = requestBody.metadata.user_id
+    const match = userId.match(/session_([a-f0-9-]{36})$/i)
+    return match ? match[1] : null
+  }
+
+  /**
+   * 获取配置（带缓存）
+   * @returns {Promise<Object>} 配置对象
+   */
+  async getConfig() {
+    try {
+      // 检查缓存
+      if (configCache && Date.now() - configCacheTime < CONFIG_CACHE_TTL) {
+        return configCache
+      }
+
+      const client = redis.getClient()
+      if (!client) {
+        logger.warn('⚠️ Redis not connected, using default config')
+        return { ...DEFAULT_CONFIG }
+      }
+
+      const data = await client.get(CONFIG_KEY)
+
+      if (data) {
+        configCache = { ...DEFAULT_CONFIG, ...JSON.parse(data) }
+      } else {
+        configCache = { ...DEFAULT_CONFIG }
+      }
+
+      configCacheTime = Date.now()
+      return configCache
+    } catch (error) {
+      logger.error('❌ Failed to get Claude relay config:', error)
+      return { ...DEFAULT_CONFIG }
+    }
+  }
+
+  /**
+   * 更新配置
+   * @param {Object} newConfig - 新配置
+   * @param {string} updatedBy - 更新者
+   * @returns {Promise<Object>} 更新后的配置
+   */
+  async updateConfig(newConfig, updatedBy) {
+    try {
+      const client = redis.getClientSafe()
+      const currentConfig = await this.getConfig()
+
+      const updatedConfig = {
+        ...currentConfig,
+        ...newConfig,
+        updatedAt: new Date().toISOString(),
+        updatedBy
+      }
+
+      await client.set(CONFIG_KEY, JSON.stringify(updatedConfig))
+
+      // 更新缓存
+      configCache = updatedConfig
+      configCacheTime = Date.now()
+
+      logger.info(`✅ Claude relay config updated by ${updatedBy}:`, {
+        claudeCodeOnlyEnabled: updatedConfig.claudeCodeOnlyEnabled,
+        globalSessionBindingEnabled: updatedConfig.globalSessionBindingEnabled,
+        concurrentRequestQueueEnabled: updatedConfig.concurrentRequestQueueEnabled
+      })
+
+      return updatedConfig
+    } catch (error) {
+      logger.error('❌ Failed to update Claude relay config:', error)
+      throw error
+    }
+  }
+
+  /**
+   * 检查是否启用全局 Claude Code 限制
+   * @returns {Promise<boolean>}
+   */
+  async isClaudeCodeOnlyEnabled() {
+    const cfg = await this.getConfig()
+    return cfg.claudeCodeOnlyEnabled === true
+  }
+
+  /**
+   * 检查是否启用全局会话绑定
+   * @returns {Promise<boolean>}
+   */
+  async isGlobalSessionBindingEnabled() {
+    const cfg = await this.getConfig()
+    return cfg.globalSessionBindingEnabled === true
+  }
+
+  /**
+   * 获取会话绑定错误信息
+   * @returns {Promise<string>}
+   */
+  async getSessionBindingErrorMessage() {
+    const cfg = await this.getConfig()
+    return cfg.sessionBindingErrorMessage || DEFAULT_CONFIG.sessionBindingErrorMessage
+  }
+
+  /**
+   * 获取原始会话绑定
+   * @param {string} originalSessionId - 原始会话ID
+   * @returns {Promise<Object|null>} 绑定信息或 null
+   */
+  async getOriginalSessionBinding(originalSessionId) {
+    if (!originalSessionId) {
+      return null
+    }
+
+    try {
+      const client = redis.getClient()
+      if (!client) {
+        return null
+      }
+
+      const key = `${SESSION_BINDING_PREFIX}${originalSessionId}`
+      const data = await client.get(key)
+
+      if (data) {
+        return JSON.parse(data)
+      }
+      return null
+    } catch (error) {
+      logger.error(`❌ Failed to get session binding for ${originalSessionId}:`, error)
+      return null
+    }
+  }
+
+  /**
+   * 设置原始会话绑定
+   * @param {string} originalSessionId - 原始会话ID
+   * @param {string} accountId - 账户ID
+   * @param {string} accountType - 账户类型
+   * @returns {Promise<Object>} 绑定信息
+   */
+  async setOriginalSessionBinding(originalSessionId, accountId, accountType) {
+    if (!originalSessionId || !accountId || !accountType) {
+      throw new Error('Invalid parameters for session binding')
+    }
+
+    try {
+      const client = redis.getClientSafe()
+      const key = `${SESSION_BINDING_PREFIX}${originalSessionId}`
+
+      const binding = {
+        accountId,
+        accountType,
+        createdAt: new Date().toISOString(),
+        lastUsedAt: new Date().toISOString()
+      }
+
+      // 使用配置的 TTL（默认30天）
+      const cfg = await this.getConfig()
+      const ttlDays = cfg.sessionBindingTtlDays || DEFAULT_CONFIG.sessionBindingTtlDays
+      const ttlSeconds = Math.floor(ttlDays * 24 * 3600)
+
+      await client.set(key, JSON.stringify(binding), 'EX', ttlSeconds)
+
+      logger.info(
+        `🔗 Session binding created: ${originalSessionId} -> ${accountId} (${accountType})`
+      )
+
+      return binding
+    } catch (error) {
+      logger.error(`❌ Failed to set session binding for ${originalSessionId}:`, error)
+      throw error
+    }
+  }
+
+  /**
+   * 更新会话绑定的最后使用时间（续期）
+   * @param {string} originalSessionId - 原始会话ID
+   */
+  async touchOriginalSessionBinding(originalSessionId) {
+    if (!originalSessionId) {
+      return
+    }
+
+    try {
+      const binding = await this.getOriginalSessionBinding(originalSessionId)
+      if (!binding) {
+        return
+      }
+
+      binding.lastUsedAt = new Date().toISOString()
+
+      const client = redis.getClientSafe()
+      const key = `${SESSION_BINDING_PREFIX}${originalSessionId}`
+
+      // 使用配置的 TTL（默认30天）
+      const cfg = await this.getConfig()
+      const ttlDays = cfg.sessionBindingTtlDays || DEFAULT_CONFIG.sessionBindingTtlDays
+      const ttlSeconds = Math.floor(ttlDays * 24 * 3600)
+
+      await client.set(key, JSON.stringify(binding), 'EX', ttlSeconds)
+    } catch (error) {
+      logger.warn(`⚠️ Failed to touch session binding for ${originalSessionId}:`, error)
+    }
+  }
+
+  /**
+   * 检查原始会话是否已绑定
+   * @param {string} originalSessionId - 原始会话ID
+   * @returns {Promise<boolean>}
+   */
+  async isOriginalSessionBound(originalSessionId) {
+    const binding = await this.getOriginalSessionBinding(originalSessionId)
+    return binding !== null
+  }
+
+  /**
+   * 验证绑定的账户是否可用
+   * @param {Object} binding - 绑定信息
+   * @returns {Promise<boolean>}
+   */
+  async validateBoundAccount(binding) {
+    if (!binding || !binding.accountId || !binding.accountType) {
+      return false
+    }
+
+    try {
+      const { accountType } = binding
+      const { accountId } = binding
+
+      let accountService
+      switch (accountType) {
+        case 'claude-official':
+          accountService = require('./claudeAccountService')
+          break
+        case 'claude-console':
+          accountService = require('./claudeConsoleAccountService')
+          break
+        case 'bedrock':
+          accountService = require('./bedrockAccountService')
+          break
+        case 'ccr':
+          accountService = require('./ccrAccountService')
+          break
+        default:
+          logger.warn(`Unknown account type for validation: ${accountType}`)
+          return false
+      }
+
+      const account = await accountService.getAccount(accountId)
+
+      // getAccount() 直接返回账户数据对象或 null，不是 { success, data } 格式
+      if (!account) {
+        logger.warn(`Session binding account not found: ${accountId} (${accountType})`)
+        return false
+      }
+
+      const accountData = account
+
+      // 检查账户是否激活
+      if (accountData.isActive === false || accountData.isActive === 'false') {
+        logger.warn(
+          `Session binding account not active: ${accountId} (${accountType}), isActive: ${accountData.isActive}`
+        )
+        return false
+      }
+
+      // 检查账户状态（如果存在）
+      if (accountData.status && accountData.status === 'error') {
+        logger.warn(
+          `Session binding account has error status: ${accountId} (${accountType}), status: ${accountData.status}`
+        )
+        return false
+      }
+
+      return true
+    } catch (error) {
+      logger.error(`❌ Failed to validate bound account ${binding.accountId}:`, error)
+      return false
+    }
+  }
+
+  /**
+   * 验证新会话请求
+   * @param {Object} _requestBody - 请求体（预留参数，当前未使用）
+   * @param {string} originalSessionId - 原始会话ID
+   * @returns {Promise<Object>} { valid: boolean, error?: string, binding?: object, isNewSession?: boolean }
+   */
+  async validateNewSession(_requestBody, originalSessionId) {
+    const cfg = await this.getConfig()
+
+    if (!cfg.globalSessionBindingEnabled) {
+      return { valid: true }
+    }
+
+    // 如果没有 sessionId，跳过验证（可能是非 Claude Code 客户端）
+    if (!originalSessionId) {
+      return { valid: true }
+    }
+
+    const existingBinding = await this.getOriginalSessionBinding(originalSessionId)
+
+    // 如果会话已存在绑定
+    if (existingBinding) {
+      // ⚠️ 只有 claude-official 类型账户受全局会话绑定限制
+      // 其他类型（bedrock, ccr, claude-console等）忽略绑定，走正常调度
+      if (existingBinding.accountType !== 'claude-official') {
+        logger.info(
+          `🔗 Session binding ignored for non-official account type: ${existingBinding.accountType}`
+        )
+        return { valid: true }
+      }
+
+      const accountValid = await this.validateBoundAccount(existingBinding)
+
+      if (!accountValid) {
+        return {
+          valid: false,
+          error: cfg.sessionBindingErrorMessage,
+          code: 'SESSION_BINDING_INVALID'
+        }
+      }
+
+      // 续期
+      await this.touchOriginalSessionBinding(originalSessionId)
+
+      // 已有绑定，允许继续（这是正常的会话延续）
+      return { valid: true, binding: existingBinding }
+    }
+
+    // 没有绑定，是新会话
+    // 注意：messages.length 检查在此处无法执行，因为我们不知道最终会调度到哪种账户类型
+    // 绑定会在调度后创建，仅针对 claude-official 账户
+    return { valid: true, isNewSession: true }
+  }
+
+  /**
+   * 删除原始会话绑定
+   * @param {string} originalSessionId - 原始会话ID
+   */
+  async deleteOriginalSessionBinding(originalSessionId) {
+    if (!originalSessionId) {
+      return
+    }
+
+    try {
+      const client = redis.getClient()
+      if (!client) {
+        return
+      }
+
+      const key = `${SESSION_BINDING_PREFIX}${originalSessionId}`
+      await client.del(key)
+      logger.info(`🗑️ Session binding deleted: ${originalSessionId}`)
+    } catch (error) {
+      logger.error(`❌ Failed to delete session binding for ${originalSessionId}:`, error)
+    }
+  }
+
+  /**
+   * 获取会话绑定统计
+   * @returns {Promise<Object>}
+   */
+  async getSessionBindingStats() {
+    try {
+      const client = redis.getClient()
+      if (!client) {
+        return { totalBindings: 0 }
+      }
+
+      let cursor = '0'
+      let count = 0
+
+      do {
+        const [newCursor, keys] = await client.scan(
+          cursor,
+          'MATCH',
+          `${SESSION_BINDING_PREFIX}*`,
+          'COUNT',
+          100
+        )
+        cursor = newCursor
+        count += keys.length
+      } while (cursor !== '0')
+
+      return {
+        totalBindings: count
+      }
+    } catch (error) {
+      logger.error('❌ Failed to get session binding stats:', error)
+      return { totalBindings: 0 }
+    }
+  }
+
+  /**
+   * 清除配置缓存（用于测试或强制刷新）
+   */
+  clearCache() {
+    configCache = null
+    configCacheTime = 0
+  }
+}
+
+module.exports = new ClaudeRelayConfigService()

src/services/claudeRelayService.js

@@ -15,10 +15,12 @@ const ClaudeCodeValidator = require('../validators/clients/claudeCodeValidator')
 const { formatDateWithTimezone } = require('../utils/dateHelper')
 const requestIdentityService = require('./requestIdentityService')
 const { createClaudeTestPayload } = require('../utils/testPayloadHelper')
+const userMessageQueueService = require('./userMessageQueueService')
+const { isStreamWritable } = require('../utils/streamHelper')
 
 class ClaudeRelayService {
   constructor() {
-    this.claudeApiUrl = config.claude.apiUrl
+    this.claudeApiUrl = 'https://api.anthropic.com/v1/messages?beta=true'
     this.apiVersion = config.claude.apiVersion
     this.betaHeader = config.claude.betaHeader
     this.systemPrompt = config.claude.systemPrompt
@@ -148,6 +150,9 @@ class ClaudeRelayService {
     options = {}
   ) {
     let upstreamRequest = null
+    let queueLockAcquired = false
+    let queueRequestId = null
+    let selectedAccountId = null
 
     try {
       // 调试日志：查看API Key数据
@@ -192,11 +197,70 @@ class ClaudeRelayService {
       }
       const { accountId } = accountSelection
       const { accountType } = accountSelection
+      selectedAccountId = accountId
 
       logger.info(
         `📤 Processing API request for key: ${apiKeyData.name || apiKeyData.id}, account: ${accountId} (${accountType})${sessionHash ? `, session: ${sessionHash}` : ''}`
       )
 
+      // 📬 用户消息队列处理：如果是用户消息请求，需要获取队列锁
+      if (userMessageQueueService.isUserMessageRequest(requestBody)) {
+        // 校验 accountId 非空，避免空值污染队列锁键
+        if (!accountId || accountId === '') {
+          logger.error('❌ accountId missing for queue lock in relayRequest')
+          throw new Error('accountId missing for queue lock')
+        }
+        const queueResult = await userMessageQueueService.acquireQueueLock(accountId)
+        if (!queueResult.acquired && !queueResult.skipped) {
+          // 区分 Redis 后端错误和队列超时
+          const isBackendError = queueResult.error === 'queue_backend_error'
+          const errorCode = isBackendError ? 'QUEUE_BACKEND_ERROR' : 'QUEUE_TIMEOUT'
+          const errorType = isBackendError ? 'queue_backend_error' : 'queue_timeout'
+          const errorMessage = isBackendError
+            ? 'Queue service temporarily unavailable, please retry later'
+            : 'User message queue wait timeout, please retry later'
+          const statusCode = isBackendError ? 500 : 503
+
+          // 结构化性能日志，用于后续统计
+          logger.performance('user_message_queue_error', {
+            errorType,
+            errorCode,
+            accountId,
+            statusCode,
+            apiKeyName: apiKeyData.name,
+            backendError: isBackendError ? queueResult.errorMessage : undefined
+          })
+
+          logger.warn(
+            `📬 User message queue ${errorType} for account ${accountId}, key: ${apiKeyData.name}`,
+            isBackendError ? { backendError: queueResult.errorMessage } : {}
+          )
+          return {
+            statusCode,
+            headers: {
+              'Content-Type': 'application/json',
+              'x-user-message-queue-error': errorType
+            },
+            body: JSON.stringify({
+              type: 'error',
+              error: {
+                type: errorType,
+                code: errorCode,
+                message: errorMessage
+              }
+            }),
+            accountId
+          }
+        }
+        if (queueResult.acquired && !queueResult.skipped) {
+          queueLockAcquired = true
+          queueRequestId = queueResult.requestId
+          logger.debug(
+            `📬 User message queue lock acquired for account ${accountId}, requestId: ${queueRequestId}`
+          )
+        }
+      }
+
       // 获取账户信息
       let account = await claudeAccountService.getAccount(accountId)
 
@@ -271,6 +335,23 @@ class ClaudeRelayService {
         options
       )
 
+      // 📬 请求已发送成功，立即释放队列锁（无需等待响应处理完成）
+      // 因为 Claude API 限流基于请求发送时刻计算（RPM），不是请求完成时刻
+      if (queueLockAcquired && queueRequestId && selectedAccountId) {
+        try {
+          await userMessageQueueService.releaseQueueLock(selectedAccountId, queueRequestId)
+          queueLockAcquired = false // 标记已释放，防止 finally 重复释放
+          logger.debug(
+            `📬 User message queue lock released early for account ${selectedAccountId}, requestId: ${queueRequestId}`
+          )
+        } catch (releaseError) {
+          logger.error(
+            `❌ Failed to release user message queue lock early for account ${selectedAccountId}:`,
+            releaseError.message
+          )
+        }
+      }
+
       response.accountId = accountId
       response.accountType = accountType
 
@@ -539,6 +620,21 @@ class ClaudeRelayService {
         error.message
       )
       throw error
+    } finally {
+      // 📬 释放用户消息队列锁（兜底，正常情况下已在请求发送后提前释放）
+      if (queueLockAcquired && queueRequestId && selectedAccountId) {
+        try {
+          await userMessageQueueService.releaseQueueLock(selectedAccountId, queueRequestId)
+          logger.debug(
+            `📬 User message queue lock released in finally for account ${selectedAccountId}, requestId: ${queueRequestId}`
+          )
+        } catch (releaseError) {
+          logger.error(
+            `❌ Failed to release user message queue lock for account ${selectedAccountId}:`,
+            releaseError.message
+          )
+        }
+      }
     }
   }
 
@@ -878,11 +974,104 @@ class ClaudeRelayService {
 
   // 🔧 过滤客户端请求头
   _filterClientHeaders(clientHeaders) {
-    // 使用统一的 headerFilter 工具类 - 移除 CDN、浏览器和代理相关 headers
+    // 使用统一的 headerFilter 工具类
     // 同时伪装成正常的直接客户端请求，避免触发上游 API 的安全检查
     return filterForClaude(clientHeaders)
   }
 
+  // 🔧 准备请求头和 payload（抽离公共逻辑）
+  async _prepareRequestHeadersAndPayload(
+    body,
+    clientHeaders,
+    accountId,
+    accessToken,
+    options = {}
+  ) {
+    const { account, accountType, sessionHash, requestOptions = {}, isStream = false } = options
+
+    // 获取统一的 User-Agent
+    const unifiedUA = await this.captureAndGetUnifiedUserAgent(clientHeaders, account)
+
+    // 获取过滤后的客户端 headers
+    const filteredHeaders = this._filterClientHeaders(clientHeaders)
+
+    // 判断是否是真实的 Claude Code 请求
+    const isRealClaudeCode = this.isRealClaudeCodeRequest(body)
+
+    // 如果不是真实的 Claude Code 请求，需要使用从账户获取的 Claude Code headers
+    let finalHeaders = { ...filteredHeaders }
+    let requestPayload = body
+
+    if (!isRealClaudeCode) {
+      // 获取该账号存储的 Claude Code headers
+      const claudeCodeHeaders = await claudeCodeHeadersService.getAccountHeaders(accountId)
+
+      // 只添加客户端没有提供的 headers
+      Object.keys(claudeCodeHeaders).forEach((key) => {
+        const lowerKey = key.toLowerCase()
+        if (!finalHeaders[key] && !finalHeaders[lowerKey]) {
+          finalHeaders[key] = claudeCodeHeaders[key]
+        }
+      })
+    }
+
+    // 应用请求身份转换
+    const extensionResult = this._applyRequestIdentityTransform(requestPayload, finalHeaders, {
+      account,
+      accountId,
+      accountType,
+      sessionHash,
+      clientHeaders,
+      requestOptions,
+      isStream
+    })
+
+    if (extensionResult.abortResponse) {
+      return { abortResponse: extensionResult.abortResponse }
+    }
+
+    requestPayload = extensionResult.body
+    finalHeaders = extensionResult.headers
+
+    // 序列化请求体，计算 content-length
+    const bodyString = JSON.stringify(requestPayload)
+    const contentLength = Buffer.byteLength(bodyString, 'utf8')
+
+    // 构建最终请求头（包含认证、版本、User-Agent、Beta 等）
+    const headers = {
+      host: 'api.anthropic.com',
+      connection: 'keep-alive',
+      'content-type': 'application/json',
+      'content-length': String(contentLength),
+      authorization: `Bearer ${accessToken}`,
+      'anthropic-version': this.apiVersion,
+      ...finalHeaders
+    }
+
+    // 使用统一 User-Agent 或客户端提供的，最后使用默认值
+    const userAgent = unifiedUA || headers['user-agent'] || 'claude-cli/1.0.119 (external, cli)'
+    const acceptHeader = headers['accept'] || 'application/json'
+    delete headers['user-agent']
+    delete headers['accept']
+    headers['User-Agent'] = userAgent
+    headers['Accept'] = acceptHeader
+
+    logger.info(`🔗 指纹是这个: ${headers['User-Agent']}`)
+
+    logger.info(`🔗 指纹是这个: ${headers['User-Agent']}`)
+
+    // 根据模型和客户端传递的 anthropic-beta 动态设置 header
+    const modelId = requestPayload?.model || body?.model
+    const clientBetaHeader = clientHeaders?.['anthropic-beta']
+    headers['anthropic-beta'] = this._getBetaHeader(modelId, clientBetaHeader)
+    return {
+      requestPayload,
+      bodyString,
+      headers,
+      isRealClaudeCode
+    }
+  }
+
   _applyRequestIdentityTransform(body, headers, context = {}) {
     const normalizedHeaders = headers && typeof headers === 'object' ? { ...headers } : {}
 
@@ -928,46 +1117,24 @@ class ClaudeRelayService {
     // 获取账户信息用于统一 User-Agent
     const account = await claudeAccountService.getAccount(accountId)
 
-    // 获取统一的 User-Agent
+    // 使用公共方法准备请求头和 payload
-    const unifiedUA = await this.captureAndGetUnifiedUserAgent(clientHeaders, account)
+    const prepared = await this._prepareRequestHeadersAndPayload(
-
+      body,
-    // 获取过滤后的客户端 headers
-    const filteredHeaders = this._filterClientHeaders(clientHeaders)
-
-    // 判断是否是真实的 Claude Code 请求
-    const isRealClaudeCode = this.isRealClaudeCodeRequest(body)
-
-    // 如果不是真实的 Claude Code 请求，需要使用从账户获取的 Claude Code headers
-    let finalHeaders = { ...filteredHeaders }
-    let requestPayload = body
-
-    if (!isRealClaudeCode) {
-      // 获取该账号存储的 Claude Code headers
-      const claudeCodeHeaders = await claudeCodeHeadersService.getAccountHeaders(accountId)
-
-      // 只添加客户端没有提供的 headers
-      Object.keys(claudeCodeHeaders).forEach((key) => {
-        const lowerKey = key.toLowerCase()
-        if (!finalHeaders[key] && !finalHeaders[lowerKey]) {
-          finalHeaders[key] = claudeCodeHeaders[key]
-        }
-      })
-    }
-
-    const extensionResult = this._applyRequestIdentityTransform(requestPayload, finalHeaders, {
-      account,
-      accountId,
       clientHeaders,
+      accountId,
+      accessToken,
+      {
+        account,
         requestOptions,
         isStream: false
-    })
+      }
+    )
 
-    if (extensionResult.abortResponse) {
+    if (prepared.abortResponse) {
-      return extensionResult.abortResponse
+      return prepared.abortResponse
     }
 
-    requestPayload = extensionResult.body
+    const { bodyString, headers } = prepared
-    finalHeaders = extensionResult.headers
 
     return new Promise((resolve, reject) => {
       // 支持自定义路径（如 count_tokens）
@@ -981,31 +1148,13 @@ class ClaudeRelayService {
       const options = {
         hostname: url.hostname,
         port: url.port || 443,
-        path: requestPath,
+        path: requestPath + (url.search || ''),
         method: 'POST',
-        headers: {
+        headers,
-          'Content-Type': 'application/json',
-          Authorization: `Bearer ${accessToken}`,
-          'anthropic-version': this.apiVersion,
-          ...finalHeaders
-        },
         agent: proxyAgent,
         timeout: config.requestTimeout || 600000
       }
 
-      // 使用统一 User-Agent 或客户端提供的，最后使用默认值
-      if (!options.headers['user-agent'] || unifiedUA !== null) {
-        const userAgent = unifiedUA || 'claude-cli/1.0.119 (external, cli)'
-        options.headers['user-agent'] = userAgent
-      }
-
-      logger.info(`🔗 指纹是这个: ${options.headers['user-agent']}`)
-
-      // 根据模型和客户端传递的 anthropic-beta 动态设置 header
-      const modelId = requestPayload?.model || body?.model
-      const clientBetaHeader = clientHeaders?.['anthropic-beta']
-      options.headers['anthropic-beta'] = this._getBetaHeader(modelId, clientBetaHeader)
-
       const req = https.request(options, (res) => {
         let responseData = Buffer.alloc(0)
 
@@ -1015,32 +1164,32 @@ class ClaudeRelayService {
 
         res.on('end', () => {
           try {
-            let bodyString = ''
+            let responseBody = ''
 
             // 根据Content-Encoding处理响应数据
             const contentEncoding = res.headers['content-encoding']
             if (contentEncoding === 'gzip') {
               try {
-                bodyString = zlib.gunzipSync(responseData).toString('utf8')
+                responseBody = zlib.gunzipSync(responseData).toString('utf8')
               } catch (unzipError) {
                 logger.error('❌ Failed to decompress gzip response:', unzipError)
-                bodyString = responseData.toString('utf8')
+                responseBody = responseData.toString('utf8')
               }
             } else if (contentEncoding === 'deflate') {
               try {
-                bodyString = zlib.inflateSync(responseData).toString('utf8')
+                responseBody = zlib.inflateSync(responseData).toString('utf8')
               } catch (unzipError) {
                 logger.error('❌ Failed to decompress deflate response:', unzipError)
-                bodyString = responseData.toString('utf8')
+                responseBody = responseData.toString('utf8')
               }
             } else {
-              bodyString = responseData.toString('utf8')
+              responseBody = responseData.toString('utf8')
             }
 
             const response = {
               statusCode: res.statusCode,
               headers: res.headers,
-              body: bodyString
+              body: responseBody
             }
 
             logger.debug(`🔗 Claude API response: ${res.statusCode}`)
@@ -1059,7 +1208,6 @@ class ClaudeRelayService {
       }
 
       req.on('error', async (error) => {
-        console.error(': ❌ ', error)
         logger.error(`❌ Claude API request error (Account: ${accountId}):`, error.message, {
           code: error.code,
           errno: error.errno,
@@ -1095,7 +1243,7 @@ class ClaudeRelayService {
       })
 
       // 写入请求体
-      req.write(JSON.stringify(requestPayload))
+      req.write(bodyString)
       req.end()
     })
   }
@@ -1110,6 +1258,10 @@ class ClaudeRelayService {
     streamTransformer = null,
     options = {}
   ) {
+    let queueLockAcquired = false
+    let queueRequestId = null
+    let selectedAccountId = null
+
     try {
       // 调试日志：查看API Key数据（流式请求）
       logger.info('🔍 [Stream] API Key data received:', {
@@ -1153,6 +1305,73 @@ class ClaudeRelayService {
       }
       const { accountId } = accountSelection
       const { accountType } = accountSelection
+      selectedAccountId = accountId
+
+      // 📬 用户消息队列处理：如果是用户消息请求，需要获取队列锁
+      if (userMessageQueueService.isUserMessageRequest(requestBody)) {
+        // 校验 accountId 非空，避免空值污染队列锁键
+        if (!accountId || accountId === '') {
+          logger.error('❌ accountId missing for queue lock in relayStreamRequestWithUsageCapture')
+          throw new Error('accountId missing for queue lock')
+        }
+        const queueResult = await userMessageQueueService.acquireQueueLock(accountId)
+        if (!queueResult.acquired && !queueResult.skipped) {
+          // 区分 Redis 后端错误和队列超时
+          const isBackendError = queueResult.error === 'queue_backend_error'
+          const errorCode = isBackendError ? 'QUEUE_BACKEND_ERROR' : 'QUEUE_TIMEOUT'
+          const errorType = isBackendError ? 'queue_backend_error' : 'queue_timeout'
+          const errorMessage = isBackendError
+            ? 'Queue service temporarily unavailable, please retry later'
+            : 'User message queue wait timeout, please retry later'
+          const statusCode = isBackendError ? 500 : 503
+
+          // 结构化性能日志，用于后续统计
+          logger.performance('user_message_queue_error', {
+            errorType,
+            errorCode,
+            accountId,
+            statusCode,
+            stream: true,
+            apiKeyName: apiKeyData.name,
+            backendError: isBackendError ? queueResult.errorMessage : undefined
+          })
+
+          logger.warn(
+            `📬 User message queue ${errorType} for account ${accountId} (stream), key: ${apiKeyData.name}`,
+            isBackendError ? { backendError: queueResult.errorMessage } : {}
+          )
+          if (!responseStream.headersSent) {
+            const existingConnection = responseStream.getHeader
+              ? responseStream.getHeader('Connection')
+              : null
+            responseStream.writeHead(statusCode, {
+              'Content-Type': 'text/event-stream',
+              'Cache-Control': 'no-cache',
+              Connection: existingConnection || 'keep-alive',
+              'x-user-message-queue-error': errorType
+            })
+          }
+          const errorEvent = `event: error\ndata: ${JSON.stringify({
+            type: 'error',
+            error: {
+              type: errorType,
+              code: errorCode,
+              message: errorMessage
+            }
+          })}\n\n`
+          responseStream.write(errorEvent)
+          responseStream.write('data: [DONE]\n\n')
+          responseStream.end()
+          return
+        }
+        if (queueResult.acquired && !queueResult.skipped) {
+          queueLockAcquired = true
+          queueRequestId = queueResult.requestId
+          logger.debug(
+            `📬 User message queue lock acquired for account ${accountId} (stream), requestId: ${queueRequestId}`
+          )
+        }
+      }
 
       logger.info(
         `📡 Processing streaming API request with usage capture for key: ${apiKeyData.name || apiKeyData.id}, account: ${accountId} (${accountType})${sessionHash ? `, session: ${sessionHash}` : ''}`
@@ -1219,11 +1438,48 @@ class ClaudeRelayService {
         sessionHash,
         streamTransformer,
         options,
-        isDedicatedOfficialAccount
+        isDedicatedOfficialAccount,
+        // 📬 新增回调：在收到响应头时释放队列锁
+        async () => {
+          if (queueLockAcquired && queueRequestId && selectedAccountId) {
+            try {
+              await userMessageQueueService.releaseQueueLock(selectedAccountId, queueRequestId)
+              queueLockAcquired = false // 标记已释放，防止 finally 重复释放
+              logger.debug(
+                `📬 User message queue lock released early for stream account ${selectedAccountId}, requestId: ${queueRequestId}`
+              )
+            } catch (releaseError) {
+              logger.error(
+                `❌ Failed to release user message queue lock early for stream account ${selectedAccountId}:`,
+                releaseError.message
+              )
+            }
+          }
+        }
       )
     } catch (error) {
+      // 客户端主动断开连接是正常情况，使用 INFO 级别
+      if (error.message === 'Client disconnected') {
+        logger.info(`🔌 Claude stream relay ended: Client disconnected`)
+      } else {
         logger.error(`❌ Claude stream relay with usage capture failed:`, error)
+      }
       throw error
+    } finally {
+      // 📬 释放用户消息队列锁（兜底，正常情况下已在收到响应头后提前释放）
+      if (queueLockAcquired && queueRequestId && selectedAccountId) {
+        try {
+          await userMessageQueueService.releaseQueueLock(selectedAccountId, queueRequestId)
+          logger.debug(
+            `📬 User message queue lock released in finally for stream account ${selectedAccountId}, requestId: ${queueRequestId}`
+          )
+        } catch (releaseError) {
+          logger.error(
+            `❌ Failed to release user message queue lock for stream account ${selectedAccountId}:`,
+            releaseError.message
+          )
+        }
+      }
     }
   }
 
@@ -1240,7 +1496,8 @@ class ClaudeRelayService {
     sessionHash,
     streamTransformer = null,
     requestOptions = {},
-    isDedicatedOfficialAccount = false
+    isDedicatedOfficialAccount = false,
+    onResponseStart = null // 📬 新增：收到响应头时的回调，用于提前释放队列锁
   ) {
     // 获取账户信息用于统一 User-Agent
     const account = await claudeAccountService.getAccount(accountId)
@@ -1248,79 +1505,39 @@ class ClaudeRelayService {
     const isOpusModelRequest =
       typeof body?.model === 'string' && body.model.toLowerCase().includes('opus')
 
-    // 获取统一的 User-Agent
+    // 使用公共方法准备请求头和 payload
-    const unifiedUA = await this.captureAndGetUnifiedUserAgent(clientHeaders, account)
+    const prepared = await this._prepareRequestHeadersAndPayload(
-
+      body,
-    // 获取过滤后的客户端 headers
+      clientHeaders,
-    const filteredHeaders = this._filterClientHeaders(clientHeaders)
-
-    // 判断是否是真实的 Claude Code 请求
-    const isRealClaudeCode = this.isRealClaudeCodeRequest(body)
-
-    // 如果不是真实的 Claude Code 请求，需要使用从账户获取的 Claude Code headers
-    let finalHeaders = { ...filteredHeaders }
-    let requestPayload = body
-
-    if (!isRealClaudeCode) {
-      // 获取该账号存储的 Claude Code headers
-      const claudeCodeHeaders = await claudeCodeHeadersService.getAccountHeaders(accountId)
-
-      // 只添加客户端没有提供的 headers
-      Object.keys(claudeCodeHeaders).forEach((key) => {
-        const lowerKey = key.toLowerCase()
-        if (!finalHeaders[key] && !finalHeaders[lowerKey]) {
-          finalHeaders[key] = claudeCodeHeaders[key]
-        }
-      })
-    }
-
-    const extensionResult = this._applyRequestIdentityTransform(requestPayload, finalHeaders, {
-      account,
       accountId,
+      accessToken,
+      {
+        account,
         accountType,
         sessionHash,
-      clientHeaders,
         requestOptions,
         isStream: true
-    })
+      }
+    )
 
-    if (extensionResult.abortResponse) {
+    if (prepared.abortResponse) {
-      return extensionResult.abortResponse
+      return prepared.abortResponse
     }
 
-    requestPayload = extensionResult.body
+    const { bodyString, headers } = prepared
-    finalHeaders = extensionResult.headers
 
     return new Promise((resolve, reject) => {
       const url = new URL(this.claudeApiUrl)
-
       const options = {
         hostname: url.hostname,
         port: url.port || 443,
-        path: url.pathname,
+        path: url.pathname + (url.search || ''),
         method: 'POST',
-        headers: {
+        headers,
-          'Content-Type': 'application/json',
-          Authorization: `Bearer ${accessToken}`,
-          'anthropic-version': this.apiVersion,
-          ...finalHeaders
-        },
         agent: proxyAgent,
         timeout: config.requestTimeout || 600000
       }
 
-      // 使用统一 User-Agent 或客户端提供的，最后使用默认值
-      if (!options.headers['user-agent'] || unifiedUA !== null) {
-        const userAgent = unifiedUA || 'claude-cli/1.0.119 (external, cli)'
-        options.headers['user-agent'] = userAgent
-      }
-
-      logger.info(`🔗 指纹是这个: ${options.headers['user-agent']}`)
-      // 根据模型和客户端传递的 anthropic-beta 动态设置 header
-      const modelId = body?.model
-      const clientBetaHeader = clientHeaders?.['anthropic-beta']
-      options.headers['anthropic-beta'] = this._getBetaHeader(modelId, clientBetaHeader)
-
       const req = https.request(options, async (res) => {
         logger.debug(`🌊 Claude stream response status: ${res.statusCode}`)
 
@@ -1465,7 +1682,6 @@ class ClaudeRelayService {
           })
 
           res.on('end', () => {
-            console.error(': ❌ ', errorData)
             logger.error(
               `❌ Claude API error response (Account: ${account?.name || accountId}):`,
               errorData
@@ -1489,7 +1705,7 @@ class ClaudeRelayService {
                 }
               })()
             }
-            if (!responseStream.destroyed) {
+            if (isStreamWritable(responseStream)) {
               // 解析 Claude API 返回的错误详情
               let errorMessage = `Claude API error: ${res.statusCode}`
               try {
@@ -1527,6 +1743,16 @@ class ClaudeRelayService {
           return
         }
 
+        // 📬 收到成功响应头（HTTP 200），立即调用回调释放队列锁
+        // 此时请求已被 Claude API 接受并计入 RPM 配额，无需等待响应完成
+        if (onResponseStart && typeof onResponseStart === 'function') {
+          try {
+            await onResponseStart()
+          } catch (callbackError) {
+            logger.error('❌ Error in onResponseStart callback:', callbackError.message)
+          }
+        }
+
         let buffer = ''
         const allUsageData = [] // 收集所有的usage事件
         let currentUsageData = {} // 当前正在收集的usage数据
@@ -1544,7 +1770,8 @@ class ClaudeRelayService {
             buffer = lines.pop() || '' // 保留最后的不完整行
 
             // 转发已处理的完整行到客户端
-            if (lines.length > 0 && !responseStream.destroyed) {
+            if (lines.length > 0) {
+              if (isStreamWritable(responseStream)) {
                 const linesToForward = lines.join('\n') + (lines.length > 0 ? '\n' : '')
                 // 如果有流转换器，应用转换
                 if (streamTransformer) {
@@ -1555,6 +1782,12 @@ class ClaudeRelayService {
                 } else {
                   responseStream.write(linesToForward)
                 }
+              } else {
+                // 客户端连接已断开，记录警告（但仍继续解析usage）
+                logger.warn(
+                  `⚠️ [Official] Client disconnected during stream, skipping ${lines.length} lines for account: ${accountId}`
+                )
+              }
             }
 
             for (const line of lines) {
@@ -1658,7 +1891,7 @@ class ClaudeRelayService {
           } catch (error) {
             logger.error('❌ Error processing stream data:', error)
             // 发送错误但不破坏流，让它自然结束
-            if (!responseStream.destroyed) {
+            if (isStreamWritable(responseStream)) {
               responseStream.write('event: error\n')
               responseStream.write(
                 `data: ${JSON.stringify({
@@ -1674,7 +1907,7 @@ class ClaudeRelayService {
         res.on('end', async () => {
           try {
             // 处理缓冲区中剩余的数据
-            if (buffer.trim() && !responseStream.destroyed) {
+            if (buffer.trim() && isStreamWritable(responseStream)) {
               if (streamTransformer) {
                 const transformed = streamTransformer(buffer)
                 if (transformed) {
@@ -1686,8 +1919,16 @@ class ClaudeRelayService {
             }
 
             // 确保流正确结束
-            if (!responseStream.destroyed) {
+            if (isStreamWritable(responseStream)) {
               responseStream.end()
+              logger.debug(
+                `🌊 Stream end called | bytesWritten: ${responseStream.bytesWritten || 'unknown'}`
+              )
+            } else {
+              // 连接已断开，记录警告
+              logger.warn(
+                `⚠️ [Official] Client disconnected before stream end, data may not have been received | account: ${account?.name || accountId}`
+              )
             }
           } catch (error) {
             logger.error('❌ Error processing stream end:', error)
@@ -1766,15 +2007,15 @@ class ClaudeRelayService {
 
           // 提取5小时会话窗口状态
           // 使用大小写不敏感的方式获取响应头
-          const get5hStatus = (headers) => {
+          const get5hStatus = (resHeaders) => {
-            if (!headers) {
+            if (!resHeaders) {
               return null
             }
             // HTTP头部名称不区分大小写，需要处理不同情况
             return (
-              headers['anthropic-ratelimit-unified-5h-status'] ||
+              resHeaders['anthropic-ratelimit-unified-5h-status'] ||
-              headers['Anthropic-Ratelimit-Unified-5h-Status'] ||
+              resHeaders['Anthropic-Ratelimit-Unified-5h-Status'] ||
-              headers['ANTHROPIC-RATELIMIT-UNIFIED-5H-STATUS']
+              resHeaders['ANTHROPIC-RATELIMIT-UNIFIED-5H-STATUS']
             )
           }
 
@@ -1885,14 +2126,17 @@ class ClaudeRelayService {
         }
 
         if (!responseStream.headersSent) {
+          const existingConnection = responseStream.getHeader
+            ? responseStream.getHeader('Connection')
+            : null
           responseStream.writeHead(statusCode, {
             'Content-Type': 'text/event-stream',
             'Cache-Control': 'no-cache',
-            Connection: 'keep-alive'
+            Connection: existingConnection || 'keep-alive'
           })
         }
 
-        if (!responseStream.destroyed) {
+        if (isStreamWritable(responseStream)) {
           // 发送 SSE 错误事件
           responseStream.write('event: error\n')
           responseStream.write(
@@ -1912,13 +2156,16 @@ class ClaudeRelayService {
         logger.error(`❌ Claude stream request timeout | Account: ${account?.name || accountId}`)
 
         if (!responseStream.headersSent) {
+          const existingConnection = responseStream.getHeader
+            ? responseStream.getHeader('Connection')
+            : null
           responseStream.writeHead(504, {
             'Content-Type': 'text/event-stream',
             'Cache-Control': 'no-cache',
-            Connection: 'keep-alive'
+            Connection: existingConnection || 'keep-alive'
           })
         }
-        if (!responseStream.destroyed) {
+        if (isStreamWritable(responseStream)) {
           // 发送 SSE 错误事件
           responseStream.write('event: error\n')
           responseStream.write(
@@ -1937,18 +2184,24 @@ class ClaudeRelayService {
       responseStream.on('close', () => {
         logger.debug('🔌 Client disconnected, cleaning up stream')
         if (!req.destroyed) {
-          req.destroy()
+          req.destroy(new Error('Client disconnected'))
         }
       })
 
       // 写入请求体
-      req.write(JSON.stringify(requestPayload))
+      req.write(bodyString)
       req.end()
     })
   }
 
   // 🛠️ 统一的错误处理方法
-  async _handleServerError(accountId, statusCode, _sessionHash = null, context = '') {
+  async _handleServerError(
+    accountId,
+    statusCode,
+    sessionHash = null,
+    context = '',
+    accountType = 'claude-official'
+  ) {
     try {
       await claudeAccountService.recordServerError(accountId, statusCode)
       const errorCount = await claudeAccountService.getServerErrorCount(accountId)
@@ -1962,6 +2215,18 @@ class ClaudeRelayService {
         `⏱️ ${prefix}${isTimeout ? 'Timeout' : 'Server'} error for account ${accountId}, error count: ${errorCount}/${threshold}`
       )
 
+      // 标记账户为临时不可用（5分钟）
+      try {
+        await unifiedClaudeScheduler.markAccountTemporarilyUnavailable(
+          accountId,
+          accountType,
+          sessionHash,
+          300
+        )
+      } catch (markError) {
+        logger.error(`❌ Failed to mark account temporarily unavailable: ${accountId}`, markError)
+      }
+
       if (errorCount > threshold) {
         const errorTypeLabel = isTimeout ? 'timeout' : '5xx'
         // ⚠️ 只记录5xx/504告警，不再自动停止调度，避免上游抖动导致误停
@@ -2191,19 +2456,14 @@ class ClaudeRelayService {
     }
   }
 
-  // 🧪 测试账号连接（供Admin API使用，直接复用 _makeClaudeStreamRequestWithUsageCapture）
+  // 🔧 准备测试请求的公共逻辑（供 testAccountConnection 和 testAccountConnectionSync 共用）
-  async testAccountConnection(accountId, responseStream) {
+  async _prepareAccountForTest(accountId) {
-    const testRequestBody = createClaudeTestPayload('claude-sonnet-4-5-20250929', { stream: true })
-
-    try {
     // 获取账户信息
     const account = await claudeAccountService.getAccount(accountId)
     if (!account) {
       throw new Error('Account not found')
     }
 
-      logger.info(`🧪 Testing Claude account connection: ${account.name} (${accountId})`)
-
     // 获取有效的访问token
     const accessToken = await claudeAccountService.getValidAccessToken(accountId)
     if (!accessToken) {
@@ -2213,12 +2473,27 @@ class ClaudeRelayService {
     // 获取代理配置
     const proxyAgent = await this._getProxyAgent(accountId)
 
+    return { account, accessToken, proxyAgent }
+  }
+
+  // 🧪 测试账号连接（供Admin API使用，直接复用 _makeClaudeStreamRequestWithUsageCapture）
+  async testAccountConnection(accountId, responseStream, model = 'claude-sonnet-4-5-20250929') {
+    const testRequestBody = createClaudeTestPayload(model, { stream: true })
+
+    try {
+      const { account, accessToken, proxyAgent } = await this._prepareAccountForTest(accountId)
+
+      logger.info(`🧪 Testing Claude account connection: ${account.name} (${accountId})`)
+
       // 设置响应头
       if (!responseStream.headersSent) {
+        const existingConnection = responseStream.getHeader
+          ? responseStream.getHeader('Connection')
+          : null
         responseStream.writeHead(200, {
           'Content-Type': 'text/event-stream',
           'Cache-Control': 'no-cache',
-          Connection: 'keep-alive',
+          Connection: existingConnection || 'keep-alive',
           'X-Accel-Buffering': 'no'
         })
       }
@@ -2246,7 +2521,7 @@ class ClaudeRelayService {
     } catch (error) {
       logger.error(`❌ Test account connection failed:`, error)
       // 发送错误事件给前端
-      if (!responseStream.destroyed && !responseStream.writableEnded) {
+      if (isStreamWritable(responseStream)) {
         try {
           const errorMsg = error.message || '测试失败'
           responseStream.write(`data: ${JSON.stringify({ type: 'error', error: errorMsg })}\n\n`)
@@ -2258,6 +2533,125 @@ class ClaudeRelayService {
     }
   }
 
+  // 🧪 非流式测试账号连接（供定时任务使用）
+  // 复用流式请求方法，收集结果后返回
+  async testAccountConnectionSync(accountId, model = 'claude-sonnet-4-5-20250929') {
+    const testRequestBody = createClaudeTestPayload(model, { stream: true })
+    const startTime = Date.now()
+
+    try {
+      // 使用公共方法准备测试所需的账户信息、token 和代理
+      const { account, accessToken, proxyAgent } = await this._prepareAccountForTest(accountId)
+
+      logger.info(`🧪 Testing Claude account connection (sync): ${account.name} (${accountId})`)
+
+      // 创建一个收集器来捕获流式响应
+      let responseText = ''
+      let capturedUsage = null
+      let capturedModel = model
+      let hasError = false
+      let errorMessage = ''
+
+      // 创建模拟的响应流对象
+      const mockResponseStream = {
+        headersSent: true, // 跳过设置响应头
+        write: (data) => {
+          // 解析 SSE 数据
+          if (typeof data === 'string' && data.startsWith('data: ')) {
+            try {
+              const jsonStr = data.replace('data: ', '').trim()
+              if (jsonStr && jsonStr !== '[DONE]') {
+                const parsed = JSON.parse(jsonStr)
+                // 提取文本内容
+                if (parsed.type === 'content_block_delta' && parsed.delta?.text) {
+                  responseText += parsed.delta.text
+                }
+                // 提取 usage 信息
+                if (parsed.type === 'message_delta' && parsed.usage) {
+                  capturedUsage = parsed.usage
+                }
+                // 提取模型信息
+                if (parsed.type === 'message_start' && parsed.message?.model) {
+                  capturedModel = parsed.message.model
+                }
+                // 检测错误
+                if (parsed.type === 'error') {
+                  hasError = true
+                  errorMessage = parsed.error?.message || 'Unknown error'
+                }
+              }
+            } catch {
+              // 忽略解析错误
+            }
+          }
+          return true
+        },
+        end: () => {},
+        on: () => {},
+        once: () => {},
+        emit: () => {},
+        writable: true
+      }
+
+      // 复用流式请求方法
+      await this._makeClaudeStreamRequestWithUsageCapture(
+        testRequestBody,
+        accessToken,
+        proxyAgent,
+        {}, // clientHeaders - 测试不需要客户端headers
+        mockResponseStream,
+        null, // usageCallback - 测试不需要统计
+        accountId,
+        'claude-official', // accountType
+        null, // sessionHash - 测试不需要会话
+        null, // streamTransformer - 不需要转换，直接解析原始格式
+        {}, // requestOptions
+        false // isDedicatedOfficialAccount
+      )
+
+      const latencyMs = Date.now() - startTime
+
+      if (hasError) {
+        logger.warn(`⚠️ Test completed with error for account: ${account.name} - ${errorMessage}`)
+        return {
+          success: false,
+          error: errorMessage,
+          latencyMs,
+          timestamp: new Date().toISOString()
+        }
+      }
+
+      logger.info(`✅ Test completed for account: ${account.name} (${latencyMs}ms)`)
+
+      return {
+        success: true,
+        message: responseText.substring(0, 200), // 截取前200字符
+        latencyMs,
+        model: capturedModel,
+        usage: capturedUsage,
+        timestamp: new Date().toISOString()
+      }
+    } catch (error) {
+      const latencyMs = Date.now() - startTime
+      logger.error(`❌ Test account connection (sync) failed:`, error.message)
+
+      // 提取错误详情
+      let errorMessage = error.message
+      if (error.response) {
+        errorMessage =
+          error.response.data?.error?.message || error.response.statusText || error.message
+      }
+
+      return {
+        success: false,
+        error: errorMessage,
+        statusCode: error.response?.status,
+        latencyMs,
+        timestamp: new Date().toISOString()
+      }
+    }
+  }
+
   // 🎯 健康检查
   async healthCheck() {
     try {

src/services/droidAccountService.js

@@ -556,7 +556,8 @@ class DroidAccountService {
       tokenType = 'Bearer',
       authenticationMethod = '',
       expiresIn = null,
-      apiKeys = []
+      apiKeys = [],
+      userAgent = '' // 自定义 User-Agent
     } = options
 
     const accountId = uuidv4()
@@ -832,7 +833,8 @@ class DroidAccountService {
           : '',
       apiKeys: hasApiKeys ? JSON.stringify(apiKeyEntries) : '',
       apiKeyCount: hasApiKeys ? String(apiKeyEntries.length) : '0',
-      apiKeyStrategy: hasApiKeys ? 'random_sticky' : ''
+      apiKeyStrategy: hasApiKeys ? 'random_sticky' : '',
+      userAgent: userAgent || '' // 自定义 User-Agent
     }
 
     await redis.setDroidAccount(accountId, accountData)
@@ -931,6 +933,11 @@ class DroidAccountService {
       sanitizedUpdates.endpointType = this._sanitizeEndpointType(sanitizedUpdates.endpointType)
     }
 
+    // 处理 userAgent 字段
+    if (typeof sanitizedUpdates.userAgent === 'string') {
+      sanitizedUpdates.userAgent = sanitizedUpdates.userAgent.trim()
+    }
+
     const parseProxyConfig = (value) => {
       if (!value) {
         return null

src/services/droidRelayService.js

@@ -26,7 +26,7 @@ class DroidRelayService {
       comm: '/o/v1/chat/completions'
     }
 
-    this.userAgent = 'factory-cli/0.19.12'
+    this.userAgent = 'factory-cli/0.32.1'
     this.systemPrompt = SYSTEM_PROMPT
     this.API_KEY_STICKY_PREFIX = 'droid_api_key'
   }
@@ -241,7 +241,8 @@ class DroidRelayService {
         accessToken,
         normalizedRequestBody,
         normalizedEndpoint,
-        clientHeaders
+        clientHeaders,
+        account
       )
 
       if (selectedApiKey) {
@@ -335,7 +336,12 @@ class DroidRelayService {
         )
       }
     } catch (error) {
+      // 客户端主动断开连接是正常情况，使用 INFO 级别
+      if (error.message === 'Client disconnected') {
+        logger.info(`🔌 Droid relay ended: Client disconnected`)
+      } else {
         logger.error(`❌ Droid relay error: ${error.message}`, error)
+      }
 
       const status = error?.response?.status
       if (status >= 400 && status < 500) {
@@ -633,7 +639,7 @@ class DroidRelayService {
       // 客户端断开连接时清理
       clientResponse.on('close', () => {
         if (req && !req.destroyed) {
-          req.destroy()
+          req.destroy(new Error('Client disconnected'))
         }
       })
 
@@ -737,6 +743,14 @@ class DroidRelayService {
                 currentUsageData.output_tokens = 0
               }
 
+              // Capture cache tokens from OpenAI format
+              currentUsageData.cache_read_input_tokens =
+                data.usage.input_tokens_details?.cached_tokens || 0
+              currentUsageData.cache_creation_input_tokens =
+                data.usage.input_tokens_details?.cache_creation_input_tokens ||
+                data.usage.cache_creation_input_tokens ||
+                0
+
               logger.debug('📊 Droid OpenAI usage:', currentUsageData)
             }
 
@@ -758,6 +772,14 @@ class DroidRelayService {
                 currentUsageData.output_tokens = 0
               }
 
+              // Capture cache tokens from OpenAI Response API format
+              currentUsageData.cache_read_input_tokens =
+                usage.input_tokens_details?.cached_tokens || 0
+              currentUsageData.cache_creation_input_tokens =
+                usage.input_tokens_details?.cache_creation_input_tokens ||
+                usage.cache_creation_input_tokens ||
+                0
+
               logger.debug('📊 Droid OpenAI response usage:', currentUsageData)
             }
           } catch (parseError) {
@@ -966,11 +988,13 @@ class DroidRelayService {
   /**
    * 构建请求头
    */
-  _buildHeaders(accessToken, requestBody, endpointType, clientHeaders = {}) {
+  _buildHeaders(accessToken, requestBody, endpointType, clientHeaders = {}, account = null) {
+    // 使用账户配置的 userAgent 或默认值
+    const userAgent = account?.userAgent || this.userAgent
     const headers = {
       'content-type': 'application/json',
       authorization: `Bearer ${accessToken}`,
-      'user-agent': this.userAgent,
+      'user-agent': userAgent,
       'x-factory-client': 'cli',
       connection: 'keep-alive'
     }
@@ -987,10 +1011,16 @@ class DroidRelayService {
       }
     }
 
-    // OpenAI 特定头
+    // OpenAI 特定头 - 根据模型动态选择 provider
     if (endpointType === 'openai') {
+      const model = (requestBody?.model || '').toLowerCase()
+      // -max 模型使用 openai provider，其他使用 azure_openai
+      if (model.includes('-max')) {
+        headers['x-api-provider'] = 'openai'
+      } else {
         headers['x-api-provider'] = 'azure_openai'
       }
+    }
 
     // Comm 端点根据模型动态设置 provider
     if (endpointType === 'comm') {

src/services/openaiResponsesRelayService.js

@@ -426,9 +426,9 @@ class OpenAIResponsesRelayService {
       const lines = data.split('\n')
 
       for (const line of lines) {
-        if (line.startsWith('data: ')) {
+        if (line.startsWith('data:')) {
           try {
-            const jsonStr = line.slice(6)
+            const jsonStr = line.slice(5).trim()
             if (jsonStr === '[DONE]') {
               continue
             }

src/services/requestIdentityService.js

@@ -22,6 +22,18 @@ const STAINLESS_HEADER_KEYS = [
   'x-stainless-runtime',
   'x-stainless-runtime-version'
 ]
+
+// 小写 key 到正确大小写格式的映射（用于返回给上游时）
+const STAINLESS_HEADER_CASE_MAP = {
+  'x-stainless-retry-count': 'X-Stainless-Retry-Count',
+  'x-stainless-timeout': 'X-Stainless-Timeout',
+  'x-stainless-lang': 'X-Stainless-Lang',
+  'x-stainless-package-version': 'X-Stainless-Package-Version',
+  'x-stainless-os': 'X-Stainless-OS',
+  'x-stainless-arch': 'X-Stainless-Arch',
+  'x-stainless-runtime': 'X-Stainless-Runtime',
+  'x-stainless-runtime-version': 'X-Stainless-Runtime-Version'
+}
 const MIN_FINGERPRINT_FIELDS = 4
 const REDIS_KEY_PREFIX = 'fmt_claude_req:stainless_headers:'
 
@@ -135,7 +147,9 @@ function applyFingerprintToHeaders(headers, fingerprint) {
       return
     }
     removeHeaderCaseInsensitive(nextHeaders, key)
-    nextHeaders[key] = fingerprint[key]
+    // 使用正确的大小写格式返回给上游
+    const properCaseKey = STAINLESS_HEADER_CASE_MAP[key] || key
+    nextHeaders[properCaseKey] = fingerprint[key]
   })
 
   return nextHeaders

src/services/unifiedClaudeScheduler.js

@@ -5,7 +5,33 @@ const ccrAccountService = require('./ccrAccountService')
 const accountGroupService = require('./accountGroupService')
 const redis = require('../models/redis')
 const logger = require('../utils/logger')
-const { parseVendorPrefixedModel } = require('../utils/modelHelper')
+const { parseVendorPrefixedModel, isOpus45OrNewer } = require('../utils/modelHelper')
+
+/**
+ * Check if account is Pro (not Max)
+ *
+ * ACCOUNT TYPE LOGIC (as of 2025-12-05):
+ * Pro accounts can be identified by either:
+ *   1. API real-time data: hasClaudePro=true && hasClaudeMax=false
+ *   2. Local config data: accountType='claude_pro'
+ *
+ * Account type restrictions for Opus models:
+ *   - Free account: No Opus access at all
+ *   - Pro account: Only Opus 4.5+ (new versions)
+ *   - Max account: All Opus versions (legacy 3.x, 4.0, 4.1 and new 4.5+)
+ *
+ * Compatible with both API real-time data (hasClaudePro) and local config (accountType)
+ * @param {Object} info - Subscription info object
+ * @returns {boolean} - true if Pro account (not Free, not Max)
+ */
+function isProAccount(info) {
+  // API real-time status takes priority
+  if (info.hasClaudePro === true && info.hasClaudeMax !== true) {
+    return true
+  }
+  // Local configured account type
+  return info.accountType === 'claude_pro'
+}
 
 class UnifiedClaudeScheduler {
   constructor() {
@@ -46,8 +72,14 @@ class UnifiedClaudeScheduler {
         return false
       }
 
-      // 2. Opus 模型的订阅级别检查
+      // 2. Opus model subscription level check
+      // VERSION RESTRICTION LOGIC:
+      // - Free: No Opus models
+      // - Pro: Only Opus 4.5+ (isOpus45OrNewer = true)
+      // - Max: All Opus versions
       if (requestedModel.toLowerCase().includes('opus')) {
+        const isNewOpus = isOpus45OrNewer(requestedModel)
+
         if (account.subscriptionInfo) {
           try {
             const info =
@@ -55,27 +87,36 @@ class UnifiedClaudeScheduler {
                 ? JSON.parse(account.subscriptionInfo)
                 : account.subscriptionInfo
 
-            // Pro 和 Free 账号不支持 Opus
+            // Free account: does not support any Opus model
-            if (info.hasClaudePro === true && info.hasClaudeMax !== true) {
+            if (info.accountType === 'free') {
               logger.info(
-                `🚫 Claude account ${account.name} (Pro) does not support Opus model${context ? ` ${context}` : ''}`
+                `🚫 Claude account ${account.name} (Free) does not support Opus model${context ? ` ${context}` : ''}`
               )
               return false
             }
-            if (info.accountType === 'claude_pro' || info.accountType === 'claude_free') {
+
+            // Pro account: only supports Opus 4.5+
+            // Reject legacy Opus (3.x, 4.0-4.4) but allow new Opus (4.5+)
+            if (isProAccount(info)) {
+              if (!isNewOpus) {
                 logger.info(
-                `🚫 Claude account ${account.name} (${info.accountType}) does not support Opus model${context ? ` ${context}` : ''}`
+                  `🚫 Claude account ${account.name} (Pro) does not support legacy Opus model${context ? ` ${context}` : ''}`
                 )
                 return false
               }
+              // Opus 4.5+ supported
+              return true
+            }
+
+            // Max account: supports all Opus versions (no restriction)
           } catch (e) {
-            // 解析失败，假设为旧数据，默认支持（兼容旧数据为 Max）
+            // Parse failed, assume legacy data (Max), default support
             logger.debug(
               `Account ${account.name} has invalid subscriptionInfo${context ? ` ${context}` : ''}, assuming Max`
             )
           }
         }
-        // 没有订阅信息的账号，默认当作支持（兼容旧数据）
+        // Account without subscription info, default to supported (legacy data compatibility)
       }
     }
 
@@ -139,8 +180,56 @@ class UnifiedClaudeScheduler {
   }
 
   // 🎯 统一调度Claude账号（官方和Console）
-  async selectAccountForApiKey(apiKeyData, sessionHash = null, requestedModel = null) {
+  async selectAccountForApiKey(
+    apiKeyData,
+    sessionHash = null,
+    requestedModel = null,
+    forcedAccount = null
+  ) {
     try {
+      // 🔒 如果有强制绑定的账户（全局会话绑定），仅 claude-official 类型受影响
+      if (forcedAccount && forcedAccount.accountId && forcedAccount.accountType) {
+        // ⚠️ 只有 claude-official 类型账户受全局会话绑定限制
+        // 其他类型（bedrock, ccr, claude-console等）忽略绑定，走正常调度
+        if (forcedAccount.accountType !== 'claude-official') {
+          logger.info(
+            `🔗 Session binding ignored for non-official account type: ${forcedAccount.accountType}, proceeding with normal scheduling`
+          )
+          // 不使用 forcedAccount，继续走下面的正常调度逻辑
+        } else {
+          // claude-official 类型需要检查可用性并强制使用
+          logger.info(
+            `🔗 Forced session binding detected: ${forcedAccount.accountId} (${forcedAccount.accountType})`
+          )
+
+          const isAvailable = await this._isAccountAvailableForSessionBinding(
+            forcedAccount.accountId,
+            forcedAccount.accountType,
+            requestedModel
+          )
+
+          if (isAvailable) {
+            logger.info(
+              `✅ Using forced session binding account: ${forcedAccount.accountId} (${forcedAccount.accountType})`
+            )
+            return {
+              accountId: forcedAccount.accountId,
+              accountType: forcedAccount.accountType
+            }
+          } else {
+            // 绑定账户不可用，抛出特定错误（不 fallback）
+            logger.warn(
+              `❌ Forced session binding account unavailable: ${forcedAccount.accountId} (${forcedAccount.accountType})`
+            )
+            const error = new Error('Session binding account unavailable')
+            error.code = 'SESSION_BINDING_ACCOUNT_UNAVAILABLE'
+            error.accountId = forcedAccount.accountId
+            error.accountType = forcedAccount.accountType
+            throw error
+          }
+        }
+      }
+
       // 解析供应商前缀
       const { vendor, baseModel } = parseVendorPrefixedModel(requestedModel)
       const effectiveModel = vendor === 'ccr' ? baseModel : requestedModel
@@ -177,6 +266,16 @@ class UnifiedClaudeScheduler {
         // 普通专属账户
         const boundAccount = await redis.getClaudeAccount(apiKeyData.claudeAccountId)
         if (boundAccount && boundAccount.isActive === 'true' && boundAccount.status !== 'error') {
+          // 检查是否临时不可用
+          const isTempUnavailable = await this.isAccountTemporarilyUnavailable(
+            boundAccount.id,
+            'claude-official'
+          )
+          if (isTempUnavailable) {
+            logger.warn(
+              `⏱️ Bound Claude OAuth account ${boundAccount.id} is temporarily unavailable, falling back to pool`
+            )
+          } else {
             const isRateLimited = await claudeAccountService.isAccountRateLimited(boundAccount.id)
             if (isRateLimited) {
               const rateInfo = await claudeAccountService.getAccountRateLimitInfo(boundAccount.id)
@@ -203,6 +302,7 @@ class UnifiedClaudeScheduler {
                 accountType: 'claude-official'
               }
             }
+          }
         } else {
           logger.warn(
             `⚠️ Bound Claude OAuth account ${apiKeyData.claudeAccountId} is not available (isActive: ${boundAccount?.isActive}, status: ${boundAccount?.status}), falling back to pool`
@@ -221,6 +321,16 @@ class UnifiedClaudeScheduler {
           boundConsoleAccount.status === 'active' &&
           this._isSchedulable(boundConsoleAccount.schedulable)
         ) {
+          // 检查是否临时不可用
+          const isTempUnavailable = await this.isAccountTemporarilyUnavailable(
+            boundConsoleAccount.id,
+            'claude-console'
+          )
+          if (isTempUnavailable) {
+            logger.warn(
+              `⏱️ Bound Claude Console account ${boundConsoleAccount.id} is temporarily unavailable, falling back to pool`
+            )
+          } else {
             logger.info(
               `🎯 Using bound dedicated Claude Console account: ${boundConsoleAccount.name} (${apiKeyData.claudeConsoleAccountId}) for API key ${apiKeyData.name}`
             )
@@ -228,6 +338,7 @@ class UnifiedClaudeScheduler {
               accountId: apiKeyData.claudeConsoleAccountId,
               accountType: 'claude-console'
             }
+          }
         } else {
           logger.warn(
             `⚠️ Bound Claude Console account ${apiKeyData.claudeConsoleAccountId} is not available (isActive: ${boundConsoleAccount?.isActive}, status: ${boundConsoleAccount?.status}, schedulable: ${boundConsoleAccount?.schedulable}), falling back to pool`
@@ -245,6 +356,16 @@ class UnifiedClaudeScheduler {
           boundBedrockAccountResult.data.isActive === true &&
           this._isSchedulable(boundBedrockAccountResult.data.schedulable)
         ) {
+          // 检查是否临时不可用
+          const isTempUnavailable = await this.isAccountTemporarilyUnavailable(
+            apiKeyData.bedrockAccountId,
+            'bedrock'
+          )
+          if (isTempUnavailable) {
+            logger.warn(
+              `⏱️ Bound Bedrock account ${apiKeyData.bedrockAccountId} is temporarily unavailable, falling back to pool`
+            )
+          } else {
             logger.info(
               `🎯 Using bound dedicated Bedrock account: ${boundBedrockAccountResult.data.name} (${apiKeyData.bedrockAccountId}) for API key ${apiKeyData.name}`
             )
@@ -252,6 +373,7 @@ class UnifiedClaudeScheduler {
               accountId: apiKeyData.bedrockAccountId,
               accountType: 'bedrock'
             }
+          }
         } else {
           logger.warn(
             `⚠️ Bound Bedrock account ${apiKeyData.bedrockAccountId} is not available (isActive: ${boundBedrockAccountResult?.data?.isActive}, schedulable: ${boundBedrockAccountResult?.data?.schedulable}), falling back to pool`
@@ -496,6 +618,18 @@ class UnifiedClaudeScheduler {
           continue
         }
 
+        // 检查是否临时不可用
+        const isTempUnavailable = await this.isAccountTemporarilyUnavailable(
+          account.id,
+          'claude-official'
+        )
+        if (isTempUnavailable) {
+          logger.debug(
+            `⏭️ Skipping Claude Official account ${account.name} - temporarily unavailable`
+          )
+          continue
+        }
+
         // 检查是否被限流
         const isRateLimited = await claudeAccountService.isAccountRateLimited(account.id)
         if (isRateLimited) {
@@ -584,6 +718,18 @@ class UnifiedClaudeScheduler {
           // 继续处理该账号
         }
 
+        // 检查是否临时不可用
+        const isTempUnavailable = await this.isAccountTemporarilyUnavailable(
+          currentAccount.id,
+          'claude-console'
+        )
+        if (isTempUnavailable) {
+          logger.debug(
+            `⏭️ Skipping Claude Console account ${currentAccount.name} - temporarily unavailable`
+          )
+          continue
+        }
+
         // 检查是否被限流
         const isRateLimited = await claudeConsoleAccountService.isAccountRateLimited(
           currentAccount.id
@@ -682,7 +828,15 @@ class UnifiedClaudeScheduler {
           account.accountType === 'shared' &&
           this._isSchedulable(account.schedulable)
         ) {
-          // 检查是否可调度
+          // 检查是否临时不可用
+          const isTempUnavailable = await this.isAccountTemporarilyUnavailable(
+            account.id,
+            'bedrock'
+          )
+          if (isTempUnavailable) {
+            logger.debug(`⏭️ Skipping Bedrock account ${account.name} - temporarily unavailable`)
+            continue
+          }
 
           availableAccounts.push({
             ...account,
@@ -731,6 +885,13 @@ class UnifiedClaudeScheduler {
             continue
           }
 
+          // 检查是否临时不可用
+          const isTempUnavailable = await this.isAccountTemporarilyUnavailable(account.id, 'ccr')
+          if (isTempUnavailable) {
+            logger.debug(`⏭️ Skipping CCR account ${account.name} - temporarily unavailable`)
+            continue
+          }
+
           // 检查是否被限流
           const isRateLimited = await ccrAccountService.isAccountRateLimited(account.id)
           const isQuotaExceeded = await ccrAccountService.isAccountQuotaExceeded(account.id)
@@ -1099,6 +1260,42 @@ class UnifiedClaudeScheduler {
     }
   }
 
+  // ⏱️ 标记账户为临时不可用状态（用于5xx等临时故障，默认5分钟后自动恢复）
+  async markAccountTemporarilyUnavailable(
+    accountId,
+    accountType,
+    sessionHash = null,
+    ttlSeconds = 300
+  ) {
+    try {
+      const client = redis.getClientSafe()
+      const key = `temp_unavailable:${accountType}:${accountId}`
+      await client.setex(key, ttlSeconds, '1')
+      if (sessionHash) {
+        await this._deleteSessionMapping(sessionHash)
+      }
+      logger.warn(
+        `⏱️ Account ${accountId} (${accountType}) marked temporarily unavailable for ${ttlSeconds}s`
+      )
+      return { success: true }
+    } catch (error) {
+      logger.error(`❌ Failed to mark account temporarily unavailable: ${accountId}`, error)
+      return { success: false }
+    }
+  }
+
+  // 🔍 检查账户是否临时不可用
+  async isAccountTemporarilyUnavailable(accountId, accountType) {
+    try {
+      const client = redis.getClientSafe()
+      const key = `temp_unavailable:${accountType}:${accountId}`
+      return (await client.exists(key)) === 1
+    } catch (error) {
+      logger.error(`❌ Failed to check temp unavailable status: ${accountId}`, error)
+      return false
+    }
+  }
+
   // 🚫 标记账户为限流状态
   async markAccountRateLimited(
     accountId,
@@ -1562,6 +1759,67 @@ class UnifiedClaudeScheduler {
       return []
     }
   }
+
+  /**
+   * 🔒 检查 claude-official 账户是否可用于会话绑定
+   * 注意：此方法仅用于 claude-official 类型账户，其他类型不受会话绑定限制
+   * @param {string} accountId - 账户ID
+   * @param {string} accountType - 账户类型（应为 'claude-official'）
+   * @param {string} _requestedModel - 请求的模型（保留参数，当前未使用）
+   * @returns {Promise<boolean>}
+   */
+  async _isAccountAvailableForSessionBinding(accountId, accountType, _requestedModel = null) {
+    try {
+      // 此方法仅处理 claude-official 类型
+      if (accountType !== 'claude-official') {
+        logger.warn(
+          `Session binding: _isAccountAvailableForSessionBinding called for non-official type: ${accountType}`
+        )
+        return true // 非 claude-official 类型不受限制
+      }
+
+      const account = await redis.getClaudeAccount(accountId)
+      if (!account) {
+        logger.warn(`Session binding: Claude OAuth account ${accountId} not found`)
+        return false
+      }
+
+      const isActive = account.isActive === 'true' || account.isActive === true
+      const { status } = account
+
+      if (!isActive) {
+        logger.warn(`Session binding: Claude OAuth account ${accountId} is not active`)
+        return false
+      }
+
+      if (status === 'error' || status === 'temp_error') {
+        logger.warn(
+          `Session binding: Claude OAuth account ${accountId} has error status: ${status}`
+        )
+        return false
+      }
+
+      // 检查是否被限流
+      if (await claudeAccountService.isAccountRateLimited(accountId)) {
+        logger.warn(`Session binding: Claude OAuth account ${accountId} is rate limited`)
+        return false
+      }
+
+      // 检查临时不可用
+      if (await this.isAccountTemporarilyUnavailable(accountId, accountType)) {
+        logger.warn(`Session binding: Claude OAuth account ${accountId} is temporarily unavailable`)
+        return false
+      }
+
+      return true
+    } catch (error) {
+      logger.error(
+        `❌ Error checking account availability for session binding: ${accountId} (${accountType})`,
+        error
+      )
+      return false
+    }
+  }
 }
 
 module.exports = new UnifiedClaudeScheduler()

src/services/unifiedOpenAIScheduler.js

@@ -9,6 +9,26 @@ class UnifiedOpenAIScheduler {
     this.SESSION_MAPPING_PREFIX = 'unified_openai_session_mapping:'
   }
 
+  // 🔢 按优先级和最后使用时间排序账户（与 Claude/Gemini 调度保持一致）
+  _sortAccountsByPriority(accounts) {
+    return accounts.sort((a, b) => {
+      const aPriority = Number.parseInt(a.priority, 10)
+      const bPriority = Number.parseInt(b.priority, 10)
+      const normalizedAPriority = Number.isFinite(aPriority) ? aPriority : 50
+      const normalizedBPriority = Number.isFinite(bPriority) ? bPriority : 50
+
+      // 首先按优先级排序（数字越小优先级越高）
+      if (normalizedAPriority !== normalizedBPriority) {
+        return normalizedAPriority - normalizedBPriority
+      }
+
+      // 优先级相同时，按最后使用时间排序（最久未使用的优先）
+      const aLastUsed = new Date(a.lastUsedAt || 0).getTime()
+      const bLastUsed = new Date(b.lastUsedAt || 0).getTime()
+      return aLastUsed - bLastUsed
+    })
+  }
+
   // 🔧 辅助方法：检查账户是否可调度（兼容字符串和布尔值）
   _isSchedulable(schedulable) {
     // 如果是 undefined 或 null，默认为可调度
@@ -244,13 +264,7 @@ class UnifiedOpenAIScheduler {
             `🎯 Using bound dedicated ${accountType} account: ${boundAccount.name} (${boundAccount.id}) for API key ${apiKeyData.name}`
           )
           // 更新账户的最后使用时间
-          if (accountType === 'openai') {
+          await this.updateAccountLastUsed(boundAccount.id, accountType)
-            await openaiAccountService.recordUsage(boundAccount.id, 0)
-          } else {
-            await openaiResponsesAccountService.updateAccount(boundAccount.id, {
-              lastUsedAt: new Date().toISOString()
-            })
-          }
           return {
             accountId: boundAccount.id,
             accountType
@@ -292,7 +306,7 @@ class UnifiedOpenAIScheduler {
               `🎯 Using sticky session account: ${mappedAccount.accountId} (${mappedAccount.accountType}) for session ${sessionHash}`
             )
             // 更新账户的最后使用时间
-            await openaiAccountService.recordUsage(mappedAccount.accountId, 0)
+            await this.updateAccountLastUsed(mappedAccount.accountId, mappedAccount.accountType)
             return mappedAccount
           } else {
             logger.warn(
@@ -321,12 +335,8 @@ class UnifiedOpenAIScheduler {
         }
       }
 
-      // 按最后使用时间排序（最久未使用的优先，与 Claude 保持一致）
+      // 按优先级和最后使用时间排序（与 Claude/Gemini 调度保持一致）
-      const sortedAccounts = availableAccounts.sort((a, b) => {
+      const sortedAccounts = this._sortAccountsByPriority(availableAccounts)
-        const aLastUsed = new Date(a.lastUsedAt || 0).getTime()
-        const bLastUsed = new Date(b.lastUsedAt || 0).getTime()
-        return aLastUsed - bLastUsed // 最久未使用的优先
-      })
 
       // 选择第一个账户
       const selectedAccount = sortedAccounts[0]
@@ -344,11 +354,11 @@ class UnifiedOpenAIScheduler {
       }
 
       logger.info(
-        `🎯 Selected account: ${selectedAccount.name} (${selectedAccount.accountId}, ${selectedAccount.accountType}) for API key ${apiKeyData.name}`
+        `🎯 Selected account: ${selectedAccount.name} (${selectedAccount.accountId}, ${selectedAccount.accountType}, priority: ${selectedAccount.priority || 50}) for API key ${apiKeyData.name}`
       )
 
       // 更新账户的最后使用时间
-      await openaiAccountService.recordUsage(selectedAccount.accountId, 0)
+      await this.updateAccountLastUsed(selectedAccount.accountId, selectedAccount.accountType)
 
       return {
         accountId: selectedAccount.accountId,
@@ -494,21 +504,6 @@ class UnifiedOpenAIScheduler {
     return availableAccounts
   }
 
-  // 🔢 按优先级和最后使用时间排序账户（已废弃，改为与 Claude 保持一致，只按最后使用时间排序）
-  // _sortAccountsByPriority(accounts) {
-  //   return accounts.sort((a, b) => {
-  //     // 首先按优先级排序（数字越小优先级越高）
-  //     if (a.priority !== b.priority) {
-  //       return a.priority - b.priority
-  //     }
-
-  //     // 优先级相同时，按最后使用时间排序（最久未使用的优先）
-  //     const aLastUsed = new Date(a.lastUsedAt || 0).getTime()
-  //     const bLastUsed = new Date(b.lastUsedAt || 0).getTime()
-  //     return aLastUsed - bLastUsed
-  //   })
-  // }
-
   // 🔍 检查账户是否可用
   async _isAccountAvailable(accountId, accountType) {
     try {
@@ -817,7 +812,7 @@ class UnifiedOpenAIScheduler {
                 `🎯 Using sticky session account from group: ${mappedAccount.accountId} (${mappedAccount.accountType})`
               )
               // 更新账户的最后使用时间
-              await openaiAccountService.recordUsage(mappedAccount.accountId, 0)
+              await this.updateAccountLastUsed(mappedAccount.accountId, mappedAccount.accountType)
               return mappedAccount
             }
           }
@@ -909,12 +904,8 @@ class UnifiedOpenAIScheduler {
         throw error
       }
 
-      // 按最后使用时间排序（最久未使用的优先，与 Claude 保持一致）
+      // 按优先级和最后使用时间排序（与 Claude/Gemini 调度保持一致）
-      const sortedAccounts = availableAccounts.sort((a, b) => {
+      const sortedAccounts = this._sortAccountsByPriority(availableAccounts)
-        const aLastUsed = new Date(a.lastUsedAt || 0).getTime()
-        const bLastUsed = new Date(b.lastUsedAt || 0).getTime()
-        return aLastUsed - bLastUsed // 最久未使用的优先
-      })
 
       // 选择第一个账户
       const selectedAccount = sortedAccounts[0]
@@ -932,11 +923,11 @@ class UnifiedOpenAIScheduler {
       }
 
       logger.info(
-        `🎯 Selected account from group: ${selectedAccount.name} (${selectedAccount.accountId})`
+        `🎯 Selected account from group: ${selectedAccount.name} (${selectedAccount.accountId}, ${selectedAccount.accountType}, priority: ${selectedAccount.priority || 50})`
       )
 
       // 更新账户的最后使用时间
-      await openaiAccountService.recordUsage(selectedAccount.accountId, 0)
+      await this.updateAccountLastUsed(selectedAccount.accountId, selectedAccount.accountType)
 
       return {
         accountId: selectedAccount.accountId,
@@ -958,9 +949,12 @@ class UnifiedOpenAIScheduler {
   async updateAccountLastUsed(accountId, accountType) {
     try {
       if (accountType === 'openai') {
-        await openaiAccountService.updateAccount(accountId, {
+        await openaiAccountService.recordUsage(accountId, 0)
-          lastUsedAt: new Date().toISOString()
+        return
-        })
+      }
+
+      if (accountType === 'openai-responses') {
+        await openaiResponsesAccountService.recordUsage(accountId, 0)
       }
     } catch (error) {
       logger.warn(`⚠️ Failed to update last used time for account ${accountId}:`, error)

src/services/userMessageQueueService.js

@@ -0,0 +1,348 @@
+/**
+ * 用户消息队列服务
+ * 为 Claude 账户实现基于消息类型的串行排队机制
+ *
+ * 当请求的最后一条消息是用户输入（role: user）时，
+ * 同一账户的此类请求需要串行等待，并在请求之间添加延迟
+ */
+
+const { v4: uuidv4 } = require('uuid')
+const redis = require('../models/redis')
+const config = require('../../config/config')
+const logger = require('../utils/logger')
+
+// 清理任务间隔
+const CLEANUP_INTERVAL_MS = 60000 // 1分钟
+
+// 轮询等待配置
+const POLL_INTERVAL_BASE_MS = 50 // 基础轮询间隔
+const POLL_INTERVAL_MAX_MS = 500 // 最大轮询间隔
+const POLL_BACKOFF_FACTOR = 1.5 // 退避因子
+
+class UserMessageQueueService {
+  constructor() {
+    this.cleanupTimer = null
+  }
+
+  /**
+   * 检测请求是否为真正的用户消息请求
+   * 区分真正的用户输入和 tool_result 消息
+   *
+   * Claude API 消息格式：
+   * - 用户文本消息: { role: 'user', content: 'text' } 或 { role: 'user', content: [{ type: 'text', text: '...' }] }
+   * - 工具结果消息: { role: 'user', content: [{ type: 'tool_result', tool_use_id: '...', content: '...' }] }
+   *
+   * @param {Object} requestBody - 请求体
+   * @returns {boolean} - 是否为真正的用户消息（排除 tool_result）
+   */
+  isUserMessageRequest(requestBody) {
+    const messages = requestBody?.messages
+    if (!Array.isArray(messages) || messages.length === 0) {
+      return false
+    }
+    const lastMessage = messages[messages.length - 1]
+
+    // 检查 role 是否为 user
+    if (lastMessage?.role !== 'user') {
+      return false
+    }
+
+    // 检查 content 是否包含 tool_result 类型
+    const { content } = lastMessage
+    if (Array.isArray(content)) {
+      // 如果 content 数组中任何元素是 tool_result，则不是真正的用户消息
+      const hasToolResult = content.some(
+        (block) => block?.type === 'tool_result' || block?.type === 'tool_use_result'
+      )
+      if (hasToolResult) {
+        return false
+      }
+    }
+
+    // role 是 user 且不包含 tool_result，是真正的用户消息
+    return true
+  }
+
+  /**
+   * 获取当前配置（支持 Web 界面配置优先）
+   * @returns {Promise<Object>} 配置对象
+   */
+  async getConfig() {
+    // 默认配置（防止 config.userMessageQueue 未定义）
+    // 注意：优化后的默认值 - 锁持有时间从分钟级降到毫秒级，无需长等待
+    const queueConfig = config.userMessageQueue || {}
+    const defaults = {
+      enabled: queueConfig.enabled ?? false,
+      delayMs: queueConfig.delayMs ?? 200,
+      timeoutMs: queueConfig.timeoutMs ?? 5000, // 从 60000 降到 5000，因为锁持有时间短
+      lockTtlMs: queueConfig.lockTtlMs ?? 5000 // 从 120000 降到 5000，5秒足以覆盖请求发送
+    }
+
+    // 尝试从 claudeRelayConfigService 获取 Web 界面配置
+    try {
+      const claudeRelayConfigService = require('./claudeRelayConfigService')
+      const webConfig = await claudeRelayConfigService.getConfig()
+
+      return {
+        enabled:
+          webConfig.userMessageQueueEnabled !== undefined
+            ? webConfig.userMessageQueueEnabled
+            : defaults.enabled,
+        delayMs:
+          webConfig.userMessageQueueDelayMs !== undefined
+            ? webConfig.userMessageQueueDelayMs
+            : defaults.delayMs,
+        timeoutMs:
+          webConfig.userMessageQueueTimeoutMs !== undefined
+            ? webConfig.userMessageQueueTimeoutMs
+            : defaults.timeoutMs,
+        lockTtlMs:
+          webConfig.userMessageQueueLockTtlMs !== undefined
+            ? webConfig.userMessageQueueLockTtlMs
+            : defaults.lockTtlMs
+      }
+    } catch {
+      // 回退到环境变量配置
+      return defaults
+    }
+  }
+
+  /**
+   * 检查功能是否启用
+   * @returns {Promise<boolean>}
+   */
+  async isEnabled() {
+    const cfg = await this.getConfig()
+    return cfg.enabled === true
+  }
+
+  /**
+   * 获取账户队列锁（阻塞等待）
+   * @param {string} accountId - 账户ID
+   * @param {string} requestId - 请求ID（可选，会自动生成）
+   * @param {number} timeoutMs - 超时时间（可选，使用配置默认值）
+   * @returns {Promise<{acquired: boolean, requestId: string, error?: string}>}
+   */
+  async acquireQueueLock(accountId, requestId = null, timeoutMs = null) {
+    const cfg = await this.getConfig()
+
+    if (!cfg.enabled) {
+      return { acquired: true, requestId: requestId || uuidv4(), skipped: true }
+    }
+
+    const reqId = requestId || uuidv4()
+    const timeout = timeoutMs || cfg.timeoutMs
+    const startTime = Date.now()
+    let retryCount = 0
+
+    logger.debug(`📬 User message queue: attempting to acquire lock for account ${accountId}`, {
+      requestId: reqId,
+      timeoutMs: timeout
+    })
+
+    while (Date.now() - startTime < timeout) {
+      const result = await redis.acquireUserMessageLock(
+        accountId,
+        reqId,
+        cfg.lockTtlMs,
+        cfg.delayMs
+      )
+
+      // 检测 Redis 错误，立即返回系统错误而非继续轮询
+      if (result.redisError) {
+        logger.error(`📬 User message queue: Redis error while acquiring lock`, {
+          accountId,
+          requestId: reqId,
+          errorMessage: result.errorMessage
+        })
+        return {
+          acquired: false,
+          requestId: reqId,
+          error: 'queue_backend_error',
+          errorMessage: result.errorMessage
+        }
+      }
+
+      if (result.acquired) {
+        logger.debug(`📬 User message queue: lock acquired for account ${accountId}`, {
+          requestId: reqId,
+          waitedMs: Date.now() - startTime,
+          retries: retryCount
+        })
+        return { acquired: true, requestId: reqId }
+      }
+
+      // 需要等待
+      if (result.waitMs > 0) {
+        // 需要延迟（上一个请求刚完成）
+        await this._sleep(Math.min(result.waitMs, timeout - (Date.now() - startTime)))
+      } else {
+        // 锁被占用，使用指数退避轮询等待
+        const basePollInterval = Math.min(
+          POLL_INTERVAL_BASE_MS * Math.pow(POLL_BACKOFF_FACTOR, retryCount),
+          POLL_INTERVAL_MAX_MS
+        )
+        // 添加 ±15% 随机抖动，避免高并发下的周期性碰撞
+        const jitter = basePollInterval * (0.85 + Math.random() * 0.3)
+        const pollInterval = Math.min(jitter, POLL_INTERVAL_MAX_MS)
+        await this._sleep(pollInterval)
+        retryCount++
+      }
+    }
+
+    // 超时
+    logger.warn(`📬 User message queue: timeout waiting for lock`, {
+      accountId,
+      requestId: reqId,
+      timeoutMs: timeout
+    })
+
+    return {
+      acquired: false,
+      requestId: reqId,
+      error: 'queue_timeout'
+    }
+  }
+
+  /**
+   * 释放账户队列锁
+   * @param {string} accountId - 账户ID
+   * @param {string} requestId - 请求ID
+   * @returns {Promise<boolean>}
+   */
+  async releaseQueueLock(accountId, requestId) {
+    if (!accountId || !requestId) {
+      return false
+    }
+
+    const released = await redis.releaseUserMessageLock(accountId, requestId)
+
+    if (released) {
+      logger.debug(`📬 User message queue: lock released for account ${accountId}`, {
+        requestId
+      })
+    } else {
+      logger.warn(`📬 User message queue: failed to release lock (not owner?)`, {
+        accountId,
+        requestId
+      })
+    }
+
+    return released
+  }
+
+  /**
+   * 获取队列统计信息
+   * @param {string} accountId - 账户ID
+   * @returns {Promise<Object>}
+   */
+  async getQueueStats(accountId) {
+    return await redis.getUserMessageQueueStats(accountId)
+  }
+
+  /**
+   * 服务启动时清理所有残留的队列锁
+   * 防止服务重启后旧锁阻塞新请求
+   * @returns {Promise<number>} 清理的锁数量
+   */
+  async cleanupStaleLocks() {
+    try {
+      const accountIds = await redis.scanUserMessageQueueLocks()
+      let cleanedCount = 0
+
+      for (const accountId of accountIds) {
+        try {
+          await redis.forceReleaseUserMessageLock(accountId)
+          cleanedCount++
+          logger.debug(`📬 User message queue: cleaned stale lock for account ${accountId}`)
+        } catch (error) {
+          logger.error(
+            `📬 User message queue: failed to clean lock for account ${accountId}:`,
+            error
+          )
+        }
+      }
+
+      if (cleanedCount > 0) {
+        logger.info(`📬 User message queue: cleaned ${cleanedCount} stale lock(s) on startup`)
+      }
+
+      return cleanedCount
+    } catch (error) {
+      logger.error('📬 User message queue: failed to cleanup stale locks on startup:', error)
+      return 0
+    }
+  }
+
+  /**
+   * 启动定时清理任务
+   * 始终启动，每次执行时检查配置以支持运行时动态启用/禁用
+   */
+  startCleanupTask() {
+    if (this.cleanupTimer) {
+      return
+    }
+
+    this.cleanupTimer = setInterval(async () => {
+      // 每次运行时检查配置，以便在运行时动态启用/禁用
+      const currentConfig = await this.getConfig()
+      if (!currentConfig.enabled) {
+        logger.debug('📬 User message queue: cleanup skipped (feature disabled)')
+        return
+      }
+      await this._cleanupOrphanLocks()
+    }, CLEANUP_INTERVAL_MS)
+
+    logger.info('📬 User message queue: cleanup task started')
+  }
+
+  /**
+   * 停止定时清理任务
+   */
+  stopCleanupTask() {
+    if (this.cleanupTimer) {
+      clearInterval(this.cleanupTimer)
+      this.cleanupTimer = null
+      logger.info('📬 User message queue: cleanup task stopped')
+    }
+  }
+
+  /**
+   * 清理孤儿锁
+   * 检测异常情况：锁存在但没有设置过期时间（lockTtlRaw === -1）
+   * 正常情况下所有锁都应该有 TTL，Redis 会自动过期
+   * @private
+   */
+  async _cleanupOrphanLocks() {
+    try {
+      const accountIds = await redis.scanUserMessageQueueLocks()
+
+      for (const accountId of accountIds) {
+        const stats = await redis.getUserMessageQueueStats(accountId)
+
+        // 检测异常情况：锁存在（isLocked=true）但没有过期时间（lockTtlRaw=-1）
+        // 正常创建的锁都带有 PX 过期时间，如果没有说明是异常状态
+        if (stats.isLocked && stats.lockTtlRaw === -1) {
+          logger.warn(
+            `📬 User message queue: cleaning up orphan lock without TTL for account ${accountId}`,
+            { lockHolder: stats.lockHolder }
+          )
+          await redis.forceReleaseUserMessageLock(accountId)
+        }
+      }
+    } catch (error) {
+      logger.error('📬 User message queue: cleanup task error:', error)
+    }
+  }
+
+  /**
+   * 睡眠辅助函数
+   * @param {number} ms - 毫秒
+   * @private
+   */
+  _sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms))
+  }
+}
+
+module.exports = new UserMessageQueueService()

src/utils/contents.js

@@ -84,6 +84,11 @@ const PROMPT_DEFINITIONS = {
     title: 'Claude Code Compact System Prompt',
     text: 'You are a helpful AI assistant tasked with summarizing conversations.'
   },
+  exploreAgentSystemPrompt: {
+    category: 'system',
+    title: 'Claude Code Explore Agent System Prompt',
+    text: "You are a file search specialist for Claude Code, Anthropic's official CLI for Claude."
+  },
   outputStyleInsightsPrompt: {
     category: 'output_style',
     title: 'Output Style Insights Addendum',

src/utils/headerFilter.js

@@ -52,50 +52,38 @@ function filterForOpenAI(headers) {
 
 /**
  * 为 Claude/Anthropic API 过滤 headers
- * 在原有逻辑基础上添加 CDN headers 到敏感列表
+ * 使用白名单模式，只允许指定的 headers 通过
  */
 function filterForClaude(headers) {
-  const sensitiveHeaders = [
+  // 白名单模式：只允许以下 headers
-    'content-type',
+  const allowedHeaders = [
-    'user-agent',
-    'x-api-key',
-    'authorization',
-    'x-authorization',
-    'host',
-    'content-length',
-    'connection',
-    'proxy-authorization',
-    'content-encoding',
-    'transfer-encoding',
-    ...cdnHeaders // 添加 CDN headers
-  ]
-
-  const browserHeaders = [
-    'origin',
-    'referer',
-    'sec-fetch-mode',
-    'sec-fetch-site',
-    'sec-fetch-dest',
-    'sec-ch-ua',
-    'sec-ch-ua-mobile',
-    'sec-ch-ua-platform',
-    'accept-language',
-    'accept-encoding',
     'accept',
-    'cache-control',
+    'x-stainless-retry-count',
-    'pragma',
+    'x-stainless-timeout',
-    'anthropic-dangerous-direct-browser-access'
+    'x-stainless-lang',
+    'x-stainless-package-version',
+    'x-stainless-os',
+    'x-stainless-arch',
+    'x-stainless-runtime',
+    'x-stainless-runtime-version',
+    'x-stainless-helper-method',
+    'anthropic-dangerous-direct-browser-access',
+    'anthropic-version',
+    'x-app',
+    'anthropic-beta',
+    'accept-language',
+    'sec-fetch-mode',
+    'accept-encoding',
+    'user-agent',
+    'content-type',
+    'connection'
   ]
 
-  const allowedHeaders = ['x-request-id', 'anthropic-version', 'anthropic-beta']
-
   const filtered = {}
   Object.keys(headers || {}).forEach((key) => {
     const lowerKey = key.toLowerCase()
     if (allowedHeaders.includes(lowerKey)) {
       filtered[key] = headers[key]
-    } else if (!sensitiveHeaders.includes(lowerKey) && !browserHeaders.includes(lowerKey)) {
-      filtered[key] = headers[key]
     }
   })
 

src/utils/logger.js

@@ -137,6 +137,7 @@ const createLogFormat = (colorize = false) => {
 
 const logFormat = createLogFormat(false)
 const consoleFormat = createLogFormat(true)
+const isTestEnv = process.env.NODE_ENV === 'test' || process.env.JEST_WORKER_ID
 
 // 📁 确保日志目录存在并设置权限
 if (!fs.existsSync(config.logging.dirname)) {
@@ -159,7 +160,8 @@ const createRotateTransport = (filename, level = null) => {
     transport.level = level
   }
 
-  // 监听轮转事件
+  // 监听轮转事件（测试环境关闭以避免 Jest 退出后输出）
+  if (!isTestEnv) {
     transport.on('rotate', (oldFilename, newFilename) => {
       console.log(`📦 Log rotated: ${oldFilename} -> ${newFilename}`)
     })
@@ -171,6 +173,7 @@ const createRotateTransport = (filename, level = null) => {
     transport.on('archive', (zipFilename) => {
       console.log(`🗜️ Log archived: ${zipFilename}`)
     })
+  }
 
   return transport
 }

src/utils/modelHelper.js

@@ -70,9 +70,119 @@ function getVendorType(modelStr) {
   return vendor
 }
 
+/**
+ * Check if the model is Opus 4.5 or newer.
+ *
+ * VERSION LOGIC (as of 2025-12-05):
+ * - Opus 4.5+ (including 5.0, 6.0, etc.) → returns true (Pro account eligible)
+ * - Opus 4.4 and below (including 3.x, 4.0, 4.1) → returns false (Max account only)
+ *
+ * Supported naming formats:
+ *   - New format: claude-opus-{major}[-{minor}][-date], e.g., claude-opus-4-5-20251101
+ *   - New format: claude-opus-{major}.{minor}, e.g., claude-opus-4.5
+ *   - Old format: claude-{version}-opus[-date], e.g., claude-3-opus-20240229
+ *   - Special: opus-latest, claude-opus-latest → always returns true
+ *
+ * @param {string} modelName - Model name
+ * @returns {boolean} - Whether the model is Opus 4.5 or newer
+ */
+function isOpus45OrNewer(modelName) {
+  if (!modelName) {
+    return false
+  }
+
+  const lowerModel = modelName.toLowerCase()
+  if (!lowerModel.includes('opus')) {
+    return false
+  }
+
+  // Handle 'latest' special case
+  if (lowerModel.includes('opus-latest') || lowerModel.includes('opus_latest')) {
+    return true
+  }
+
+  // Old format: claude-{version}-opus (version before opus)
+  // e.g., claude-3-opus-20240229, claude-3.5-opus
+  const oldFormatMatch = lowerModel.match(/claude[- ](\d+)(?:[.-](\d+))?[- ]opus/)
+  if (oldFormatMatch) {
+    const majorVersion = parseInt(oldFormatMatch[1], 10)
+    const minorVersion = oldFormatMatch[2] ? parseInt(oldFormatMatch[2], 10) : 0
+
+    // Old format version refers to Claude major version
+    // majorVersion > 4: 5.x, 6.x, ... → true
+    // majorVersion === 4 && minorVersion >= 5: 4.5, 4.6, ... → true
+    // Others (3.x, 4.0-4.4): → false
+    if (majorVersion > 4) {
+      return true
+    }
+    if (majorVersion === 4 && minorVersion >= 5) {
+      return true
+    }
+    return false
+  }
+
+  // New format 1: opus-{major}.{minor} (dot-separated)
+  // e.g., claude-opus-4.5, opus-4.5
+  const dotFormatMatch = lowerModel.match(/opus[- ]?(\d+)\.(\d+)/)
+  if (dotFormatMatch) {
+    const majorVersion = parseInt(dotFormatMatch[1], 10)
+    const minorVersion = parseInt(dotFormatMatch[2], 10)
+
+    // Same version logic as old format
+    // opus-5.0, opus-6.0 → true
+    // opus-4.5, opus-4.6 → true
+    // opus-4.0, opus-4.4 → false
+    if (majorVersion > 4) {
+      return true
+    }
+    if (majorVersion === 4 && minorVersion >= 5) {
+      return true
+    }
+    return false
+  }
+
+  // New format 2: opus-{major}[-{minor}][-date] (hyphen-separated)
+  // e.g., claude-opus-4-5-20251101, claude-opus-4-20250514, claude-opus-4-1-20250805
+  // If opus-{major} is followed by 8-digit date, there's no minor version
+
+  // Extract content after 'opus'
+  const opusIndex = lowerModel.indexOf('opus')
+  const afterOpus = lowerModel.substring(opusIndex + 4)
+
+  // Match: -{major}-{minor}-{date} or -{major}-{date} or -{major}
+  // IMPORTANT: Minor version regex is (\d{1,2}) not (\d+)
+  // This prevents matching 8-digit dates as minor version
+  // Example: opus-4-20250514 → major=4, minor=undefined (not 20250514)
+  // Example: opus-4-5-20251101 → major=4, minor=5
+  // Future-proof: Supports up to 2-digit minor versions (0-99)
+  const versionMatch = afterOpus.match(/^[- ](\d+)(?:[- ](\d{1,2})(?=[- ]\d{8}|$))?/)
+
+  if (versionMatch) {
+    const majorVersion = parseInt(versionMatch[1], 10)
+    const minorVersion = versionMatch[2] ? parseInt(versionMatch[2], 10) : 0
+
+    // Same version logic: >= 4.5 returns true
+    // opus-5-0-date, opus-6-date → true
+    // opus-4-5-date, opus-4-10-date → true (supports 2-digit minor)
+    // opus-4-date (no minor, treated as 4.0) → false
+    // opus-4-1-date, opus-4-4-date → false
+    if (majorVersion > 4) {
+      return true
+    }
+    if (majorVersion === 4 && minorVersion >= 5) {
+      return true
+    }
+    return false
+  }
+
+  // Other cases containing 'opus' but cannot parse version, assume legacy
+  return false
+}
+
 module.exports = {
   parseVendorPrefixedModel,
   hasVendorPrefix,
   getEffectiveModel,
-  getVendorType
+  getVendorType,
+  isOpus45OrNewer
 }

src/utils/statsHelper.js

@@ -0,0 +1,105 @@
+/**
+ * 统计计算工具函数
+ * 提供百分位数计算、等待时间统计等通用统计功能
+ */
+
+/**
+ * 计算百分位数（使用 nearest-rank 方法）
+ * @param {number[]} sortedArray - 已排序的数组（升序）
+ * @param {number} percentile - 百分位数 (0-100)
+ * @returns {number} 百分位值
+ *
+ * 边界情况说明：
+ * - percentile=0: 返回最小值 (index=0)
+ * - percentile=100: 返回最大值 (index=len-1)
+ * - percentile=50 且 len=2: 返回第一个元素（nearest-rank 向下取）
+ *
+ * 算法说明（nearest-rank 方法）：
+ * - index = ceil(percentile / 100 * len) - 1
+ * - 示例：len=100, P50 → ceil(50) - 1 = 49（第50个元素，0-indexed）
+ * - 示例：len=100, P99 → ceil(99) - 1 = 98（第99个元素）
+ */
+function getPercentile(sortedArray, percentile) {
+  const len = sortedArray.length
+  if (len === 0) {
+    return 0
+  }
+  if (len === 1) {
+    return sortedArray[0]
+  }
+
+  // 边界处理：percentile <= 0 返回最小值
+  if (percentile <= 0) {
+    return sortedArray[0]
+  }
+  // 边界处理：percentile >= 100 返回最大值
+  if (percentile >= 100) {
+    return sortedArray[len - 1]
+  }
+
+  const index = Math.ceil((percentile / 100) * len) - 1
+  return sortedArray[index]
+}
+
+/**
+ * 计算等待时间分布统计
+ * @param {number[]} waitTimes - 等待时间数组（无需预先排序）
+ * @returns {Object|null} 统计对象，空数组返回 null
+ *
+ * 返回对象包含：
+ * - sampleCount: 样本数量（始终包含，便于调用方判断可靠性）
+ * - count: 样本数量（向后兼容）
+ * - min: 最小值
+ * - max: 最大值
+ * - avg: 平均值（四舍五入）
+ * - p50: 50百分位数（中位数）
+ * - p90: 90百分位数
+ * - p99: 99百分位数
+ * - sampleSizeWarning: 样本量不足时的警告信息（样本 < 10）
+ * - p90Unreliable: P90 统计不可靠标记（样本 < 10）
+ * - p99Unreliable: P99 统计不可靠标记（样本 < 100）
+ *
+ * 可靠性标记说明（详见 design.md Decision 6）：
+ * - 样本 < 10: P90 和 P99 都不可靠
+ * - 样本 < 100: P99 不可靠（P90 需要 10 个样本，P99 需要 100 个样本）
+ * - 即使标记为不可靠，仍返回计算值供参考
+ */
+function calculateWaitTimeStats(waitTimes) {
+  if (!waitTimes || waitTimes.length === 0) {
+    return null
+  }
+
+  const sorted = [...waitTimes].sort((a, b) => a - b)
+  const sum = sorted.reduce((a, b) => a + b, 0)
+  const len = sorted.length
+
+  const stats = {
+    sampleCount: len, // 新增：始终包含样本数
+    count: len, // 向后兼容
+    min: sorted[0],
+    max: sorted[len - 1],
+    avg: Math.round(sum / len),
+    p50: getPercentile(sorted, 50),
+    p90: getPercentile(sorted, 90),
+    p99: getPercentile(sorted, 99)
+  }
+
+  // 渐进式可靠性标记（详见 design.md Decision 6）
+  // 样本 < 10: P90 不可靠（P90 至少需要 ceil(100/10) = 10 个样本）
+  if (len < 10) {
+    stats.sampleSizeWarning = 'Results may be inaccurate due to small sample size'
+    stats.p90Unreliable = true
+  }
+
+  // 样本 < 100: P99 不可靠（P99 至少需要 ceil(100/1) = 100 个样本）
+  if (len < 100) {
+    stats.p99Unreliable = true
+  }
+
+  return stats
+}
+
+module.exports = {
+  getPercentile,
+  calculateWaitTimeStats
+}

src/utils/streamHelper.js

@@ -0,0 +1,36 @@
+/**
+ * Stream Helper Utilities
+ * 流处理辅助工具函数
+ */
+
+/**
+ * 检查响应流是否仍然可写（客户端连接是否有效）
+ * @param {import('http').ServerResponse} stream - HTTP响应流
+ * @returns {boolean} 如果流可写返回true，否则返回false
+ */
+function isStreamWritable(stream) {
+  if (!stream) {
+    return false
+  }
+
+  // 检查流是否已销毁
+  if (stream.destroyed) {
+    return false
+  }
+
+  // 检查底层socket是否已销毁
+  if (stream.socket?.destroyed) {
+    return false
+  }
+
+  // 检查流是否已结束写入
+  if (stream.writableEnded) {
+    return false
+  }
+
+  return true
+}
+
+module.exports = {
+  isStreamWritable
+}

src/utils/unstableUpstreamHelper.js

@@ -0,0 +1,81 @@
+const logger = require('./logger')
+
+function parseList(envValue) {
+  if (!envValue) {
+    return []
+  }
+  return envValue
+    .split(',')
+    .map((s) => s.trim().toLowerCase())
+    .filter(Boolean)
+}
+
+const unstableTypes = new Set(parseList(process.env.UNSTABLE_ERROR_TYPES))
+const unstableKeywords = parseList(process.env.UNSTABLE_ERROR_KEYWORDS)
+const unstableStatusCodes = new Set([408, 499, 502, 503, 504, 522])
+
+function normalizeErrorPayload(payload) {
+  if (!payload) {
+    return {}
+  }
+
+  if (typeof payload === 'string') {
+    try {
+      return normalizeErrorPayload(JSON.parse(payload))
+    } catch (e) {
+      return { message: payload }
+    }
+  }
+
+  if (payload.error && typeof payload.error === 'object') {
+    return {
+      type: payload.error.type || payload.error.error || payload.error.code,
+      code: payload.error.code || payload.error.error || payload.error.type,
+      message: payload.error.message || payload.error.msg || payload.message || payload.error.error
+    }
+  }
+
+  return {
+    type: payload.type || payload.code,
+    code: payload.code || payload.type,
+    message: payload.message || ''
+  }
+}
+
+function isUnstableUpstreamError(statusCode, payload) {
+  const normalizedStatus = Number(statusCode)
+  if (Number.isFinite(normalizedStatus) && normalizedStatus >= 500) {
+    return true
+  }
+  if (Number.isFinite(normalizedStatus) && unstableStatusCodes.has(normalizedStatus)) {
+    return true
+  }
+
+  const { type, code, message } = normalizeErrorPayload(payload)
+  const lowerType = (type || '').toString().toLowerCase()
+  const lowerCode = (code || '').toString().toLowerCase()
+  const lowerMessage = (message || '').toString().toLowerCase()
+
+  if (lowerType === 'server_error' || lowerCode === 'server_error') {
+    return true
+  }
+  if (unstableTypes.has(lowerType) || unstableTypes.has(lowerCode)) {
+    return true
+  }
+  if (unstableKeywords.length > 0) {
+    return unstableKeywords.some((kw) => lowerMessage.includes(kw))
+  }
+
+  return false
+}
+
+function logUnstable(accountLabel, statusCode) {
+  logger.warn(
+    `Detected unstable upstream error (${statusCode}) for account ${accountLabel}, marking temporarily unavailable`
+  )
+}
+
+module.exports = {
+  isUnstableUpstreamError,
+  logUnstable
+}

src/validators/clients/claudeCodeValidator.js

@@ -65,8 +65,9 @@ class ClaudeCodeValidator {
       const { bestScore } = bestSimilarityByTemplates(rawText)
       if (bestScore < threshold) {
         logger.error(
-          `Claude system prompt similarity below threshold: score=${bestScore.toFixed(4)}, threshold=${threshold}, prompt=${rawText}`
+          `Claude system prompt similarity below threshold: score=${bestScore.toFixed(4)}, threshold=${threshold}`
         )
+        logger.warn(`Claude system prompt detail: ${rawText}`)
         return false
       }
     }

tests/concurrencyQueue.integration.test.js

@@ -0,0 +1,860 @@
+/**
+ * 并发请求排队功能集成测试
+ *
+ * 测试分为三个层次：
+ * 1. Mock 测试 - 测试核心逻辑，不需要真实 Redis
+ * 2. Redis 方法测试 - 测试 Redis 操作的原子性和正确性
+ * 3. 端到端场景测试 - 测试完整的排队流程
+ *
+ * 运行方式：
+ * - npm test -- concurrencyQueue.integration  # 运行所有测试（Mock 部分）
+ * - REDIS_TEST=1 npm test -- concurrencyQueue.integration  # 包含真实 Redis 测试
+ */
+
+// Mock logger to avoid console output during tests
+jest.mock('../src/utils/logger', () => ({
+  api: jest.fn(),
+  warn: jest.fn(),
+  error: jest.fn(),
+  info: jest.fn(),
+  database: jest.fn(),
+  security: jest.fn()
+}))
+
+const redis = require('../src/models/redis')
+const claudeRelayConfigService = require('../src/services/claudeRelayConfigService')
+
+// Helper: sleep function
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+
+// Helper: 创建模拟的 req/res 对象
+function createMockReqRes() {
+  const listeners = {}
+  const req = {
+    destroyed: false,
+    once: jest.fn((event, handler) => {
+      listeners[`req:${event}`] = handler
+    }),
+    removeListener: jest.fn((event) => {
+      delete listeners[`req:${event}`]
+    }),
+    // 触发事件的辅助方法
+    emit: (event) => {
+      const handler = listeners[`req:${event}`]
+      if (handler) {
+        handler()
+      }
+    }
+  }
+
+  const res = {
+    once: jest.fn((event, handler) => {
+      listeners[`res:${event}`] = handler
+    }),
+    removeListener: jest.fn((event) => {
+      delete listeners[`res:${event}`]
+    }),
+    emit: (event) => {
+      const handler = listeners[`res:${event}`]
+      if (handler) {
+        handler()
+      }
+    }
+  }
+
+  return { req, res, listeners }
+}
+
+// ============================================
+// 第一部分：Mock 测试 - waitForConcurrencySlot 核心逻辑
+// ============================================
+describe('ConcurrencyQueue Integration Tests', () => {
+  describe('Part 1: waitForConcurrencySlot Logic (Mocked)', () => {
+    // 导入 auth 模块中的 waitForConcurrencySlot
+    // 由于它是内部函数，我们需要通过测试其行为来验证
+    // 这里我们模拟整个流程
+
+    let mockRedis
+
+    beforeEach(() => {
+      jest.clearAllMocks()
+
+      // 创建 Redis mock
+      mockRedis = {
+        concurrencyCount: {},
+        queueCount: {},
+        stats: {},
+        waitTimes: {},
+        globalWaitTimes: []
+      }
+
+      // Mock Redis 并发方法
+      jest.spyOn(redis, 'incrConcurrency').mockImplementation(async (keyId, requestId, _lease) => {
+        if (!mockRedis.concurrencyCount[keyId]) {
+          mockRedis.concurrencyCount[keyId] = new Set()
+        }
+        mockRedis.concurrencyCount[keyId].add(requestId)
+        return mockRedis.concurrencyCount[keyId].size
+      })
+
+      jest.spyOn(redis, 'decrConcurrency').mockImplementation(async (keyId, requestId) => {
+        if (mockRedis.concurrencyCount[keyId]) {
+          mockRedis.concurrencyCount[keyId].delete(requestId)
+          return mockRedis.concurrencyCount[keyId].size
+        }
+        return 0
+      })
+
+      // Mock 排队计数方法
+      jest.spyOn(redis, 'incrConcurrencyQueue').mockImplementation(async (keyId) => {
+        mockRedis.queueCount[keyId] = (mockRedis.queueCount[keyId] || 0) + 1
+        return mockRedis.queueCount[keyId]
+      })
+
+      jest.spyOn(redis, 'decrConcurrencyQueue').mockImplementation(async (keyId) => {
+        mockRedis.queueCount[keyId] = Math.max(0, (mockRedis.queueCount[keyId] || 0) - 1)
+        return mockRedis.queueCount[keyId]
+      })
+
+      jest
+        .spyOn(redis, 'getConcurrencyQueueCount')
+        .mockImplementation(async (keyId) => mockRedis.queueCount[keyId] || 0)
+
+      // Mock 统计方法
+      jest.spyOn(redis, 'incrConcurrencyQueueStats').mockImplementation(async (keyId, field) => {
+        if (!mockRedis.stats[keyId]) {
+          mockRedis.stats[keyId] = {}
+        }
+        mockRedis.stats[keyId][field] = (mockRedis.stats[keyId][field] || 0) + 1
+        return mockRedis.stats[keyId][field]
+      })
+
+      jest.spyOn(redis, 'recordQueueWaitTime').mockResolvedValue(undefined)
+      jest.spyOn(redis, 'recordGlobalQueueWaitTime').mockResolvedValue(undefined)
+    })
+
+    afterEach(() => {
+      jest.restoreAllMocks()
+    })
+
+    describe('Slot Acquisition Flow', () => {
+      it('should acquire slot immediately when under concurrency limit', async () => {
+        // 模拟 waitForConcurrencySlot 的行为
+        const keyId = 'test-key-1'
+        const requestId = 'req-1'
+        const concurrencyLimit = 5
+
+        // 直接测试 incrConcurrency 的行为
+        const count = await redis.incrConcurrency(keyId, requestId, 300)
+
+        expect(count).toBe(1)
+        expect(count).toBeLessThanOrEqual(concurrencyLimit)
+      })
+
+      it('should track multiple concurrent requests correctly', async () => {
+        const keyId = 'test-key-2'
+        const concurrencyLimit = 3
+
+        // 模拟多个并发请求
+        const results = []
+        for (let i = 1; i <= 5; i++) {
+          const count = await redis.incrConcurrency(keyId, `req-${i}`, 300)
+          results.push({ requestId: `req-${i}`, count, exceeds: count > concurrencyLimit })
+        }
+
+        // 前3个应该在限制内
+        expect(results[0].exceeds).toBe(false)
+        expect(results[1].exceeds).toBe(false)
+        expect(results[2].exceeds).toBe(false)
+        // 后2个超过限制
+        expect(results[3].exceeds).toBe(true)
+        expect(results[4].exceeds).toBe(true)
+      })
+
+      it('should release slot and allow next request', async () => {
+        const keyId = 'test-key-3'
+        const concurrencyLimit = 1
+
+        // 第一个请求获取槽位
+        const count1 = await redis.incrConcurrency(keyId, 'req-1', 300)
+        expect(count1).toBe(1)
+
+        // 第二个请求超限
+        const count2 = await redis.incrConcurrency(keyId, 'req-2', 300)
+        expect(count2).toBe(2)
+        expect(count2).toBeGreaterThan(concurrencyLimit)
+
+        // 释放第二个请求（因为超限）
+        await redis.decrConcurrency(keyId, 'req-2')
+
+        // 释放第一个请求
+        await redis.decrConcurrency(keyId, 'req-1')
+
+        // 现在第三个请求应该能获取
+        const count3 = await redis.incrConcurrency(keyId, 'req-3', 300)
+        expect(count3).toBe(1)
+      })
+    })
+
+    describe('Queue Count Management', () => {
+      it('should increment and decrement queue count atomically', async () => {
+        const keyId = 'test-key-4'
+
+        // 增加排队计数
+        const count1 = await redis.incrConcurrencyQueue(keyId, 60000)
+        expect(count1).toBe(1)
+
+        const count2 = await redis.incrConcurrencyQueue(keyId, 60000)
+        expect(count2).toBe(2)
+
+        // 减少排队计数
+        const count3 = await redis.decrConcurrencyQueue(keyId)
+        expect(count3).toBe(1)
+
+        const count4 = await redis.decrConcurrencyQueue(keyId)
+        expect(count4).toBe(0)
+      })
+
+      it('should not go below zero on decrement', async () => {
+        const keyId = 'test-key-5'
+
+        // 直接减少（没有先增加）
+        const count = await redis.decrConcurrencyQueue(keyId)
+        expect(count).toBe(0)
+      })
+
+      it('should handle concurrent queue operations', async () => {
+        const keyId = 'test-key-6'
+
+        // 并发增加
+        const increments = await Promise.all([
+          redis.incrConcurrencyQueue(keyId, 60000),
+          redis.incrConcurrencyQueue(keyId, 60000),
+          redis.incrConcurrencyQueue(keyId, 60000)
+        ])
+
+        // 所有增量应该是连续的
+        const sortedIncrements = [...increments].sort((a, b) => a - b)
+        expect(sortedIncrements).toEqual([1, 2, 3])
+      })
+    })
+
+    describe('Statistics Tracking', () => {
+      it('should track entered/success/timeout/cancelled stats', async () => {
+        const keyId = 'test-key-7'
+
+        await redis.incrConcurrencyQueueStats(keyId, 'entered')
+        await redis.incrConcurrencyQueueStats(keyId, 'entered')
+        await redis.incrConcurrencyQueueStats(keyId, 'success')
+        await redis.incrConcurrencyQueueStats(keyId, 'timeout')
+        await redis.incrConcurrencyQueueStats(keyId, 'cancelled')
+
+        expect(mockRedis.stats[keyId]).toEqual({
+          entered: 2,
+          success: 1,
+          timeout: 1,
+          cancelled: 1
+        })
+      })
+    })
+
+    describe('Client Disconnection Handling', () => {
+      it('should detect client disconnection via close event', async () => {
+        const { req } = createMockReqRes()
+
+        let clientDisconnected = false
+
+        // 设置监听器
+        req.once('close', () => {
+          clientDisconnected = true
+        })
+
+        // 模拟客户端断开
+        req.emit('close')
+
+        expect(clientDisconnected).toBe(true)
+      })
+
+      it('should detect pre-destroyed request', () => {
+        const { req } = createMockReqRes()
+        req.destroyed = true
+
+        expect(req.destroyed).toBe(true)
+      })
+    })
+
+    describe('Exponential Backoff Simulation', () => {
+      it('should increase poll interval with backoff', () => {
+        const config = {
+          pollIntervalMs: 200,
+          maxPollIntervalMs: 2000,
+          backoffFactor: 1.5,
+          jitterRatio: 0 // 禁用抖动以便测试
+        }
+
+        let interval = config.pollIntervalMs
+        const intervals = [interval]
+
+        for (let i = 0; i < 5; i++) {
+          interval = Math.min(interval * config.backoffFactor, config.maxPollIntervalMs)
+          intervals.push(interval)
+        }
+
+        // 验证指数增长
+        expect(intervals[1]).toBe(300) // 200 * 1.5
+        expect(intervals[2]).toBe(450) // 300 * 1.5
+        expect(intervals[3]).toBe(675) // 450 * 1.5
+        expect(intervals[4]).toBe(1012.5) // 675 * 1.5
+        expect(intervals[5]).toBe(1518.75) // 1012.5 * 1.5
+      })
+
+      it('should cap interval at maximum', () => {
+        const config = {
+          pollIntervalMs: 1000,
+          maxPollIntervalMs: 2000,
+          backoffFactor: 1.5
+        }
+
+        let interval = config.pollIntervalMs
+
+        for (let i = 0; i < 10; i++) {
+          interval = Math.min(interval * config.backoffFactor, config.maxPollIntervalMs)
+        }
+
+        expect(interval).toBe(2000)
+      })
+
+      it('should apply jitter within expected range', () => {
+        const baseInterval = 1000
+        const jitterRatio = 0.2 // ±20%
+        const results = []
+
+        for (let i = 0; i < 100; i++) {
+          const randomValue = Math.random()
+          const jitter = baseInterval * jitterRatio * (randomValue * 2 - 1)
+          const finalInterval = baseInterval + jitter
+          results.push(finalInterval)
+        }
+
+        const min = Math.min(...results)
+        const max = Math.max(...results)
+
+        // 所有结果应该在 [800, 1200] 范围内
+        expect(min).toBeGreaterThanOrEqual(800)
+        expect(max).toBeLessThanOrEqual(1200)
+      })
+    })
+  })
+
+  // ============================================
+  // 第二部分：并发竞争场景测试
+  // ============================================
+  describe('Part 2: Concurrent Race Condition Tests', () => {
+    beforeEach(() => {
+      jest.clearAllMocks()
+    })
+
+    afterEach(() => {
+      jest.restoreAllMocks()
+    })
+
+    describe('Race Condition: Multiple Requests Competing for Same Slot', () => {
+      it('should handle race condition when multiple requests try to acquire last slot', async () => {
+        const keyId = 'race-test-1'
+        const concurrencyLimit = 1
+        const concurrencyState = { count: 0, holders: new Set() }
+
+        // 模拟原子的 incrConcurrency
+        jest.spyOn(redis, 'incrConcurrency').mockImplementation(async (key, reqId) => {
+          // 模拟原子操作
+          concurrencyState.count++
+          concurrencyState.holders.add(reqId)
+          return concurrencyState.count
+        })
+
+        jest.spyOn(redis, 'decrConcurrency').mockImplementation(async (key, reqId) => {
+          if (concurrencyState.holders.has(reqId)) {
+            concurrencyState.count--
+            concurrencyState.holders.delete(reqId)
+          }
+          return concurrencyState.count
+        })
+
+        // 5个请求同时竞争1个槽位
+        const requests = Array.from({ length: 5 }, (_, i) => `req-${i + 1}`)
+
+        const acquireResults = await Promise.all(
+          requests.map(async (reqId) => {
+            const count = await redis.incrConcurrency(keyId, reqId, 300)
+            const acquired = count <= concurrencyLimit
+
+            if (!acquired) {
+              // 超限，释放
+              await redis.decrConcurrency(keyId, reqId)
+            }
+
+            return { reqId, count, acquired }
+          })
+        )
+
+        // 只有一个请求应该成功获取槽位
+        const successfulAcquires = acquireResults.filter((r) => r.acquired)
+        expect(successfulAcquires.length).toBe(1)
+
+        // 最终并发计数应该是1
+        expect(concurrencyState.count).toBe(1)
+      })
+
+      it('should maintain consistency under high contention', async () => {
+        const keyId = 'race-test-2'
+        const concurrencyLimit = 3
+        const requestCount = 20
+        const concurrencyState = { count: 0, maxSeen: 0 }
+
+        jest.spyOn(redis, 'incrConcurrency').mockImplementation(async () => {
+          concurrencyState.count++
+          concurrencyState.maxSeen = Math.max(concurrencyState.maxSeen, concurrencyState.count)
+          return concurrencyState.count
+        })
+
+        jest.spyOn(redis, 'decrConcurrency').mockImplementation(async () => {
+          concurrencyState.count = Math.max(0, concurrencyState.count - 1)
+          return concurrencyState.count
+        })
+
+        // 模拟多轮请求
+        const activeRequests = []
+
+        for (let i = 0; i < requestCount; i++) {
+          const count = await redis.incrConcurrency(keyId, `req-${i}`, 300)
+
+          if (count <= concurrencyLimit) {
+            activeRequests.push(`req-${i}`)
+
+            // 模拟处理时间后释放
+            setTimeout(async () => {
+              await redis.decrConcurrency(keyId, `req-${i}`)
+            }, Math.random() * 50)
+          } else {
+            await redis.decrConcurrency(keyId, `req-${i}`)
+          }
+
+          // 随机延迟
+          await sleep(Math.random() * 10)
+        }
+
+        // 等待所有请求完成
+        await sleep(100)
+
+        // 最大并发不应超过限制
+        expect(concurrencyState.maxSeen).toBeLessThanOrEqual(concurrencyLimit + requestCount) // 允许短暂超限
+      })
+    })
+
+    describe('Queue Overflow Protection', () => {
+      it('should reject requests when queue is full', async () => {
+        const keyId = 'overflow-test-1'
+        const maxQueueSize = 5
+        const queueState = { count: 0 }
+
+        jest.spyOn(redis, 'incrConcurrencyQueue').mockImplementation(async () => {
+          queueState.count++
+          return queueState.count
+        })
+
+        jest.spyOn(redis, 'decrConcurrencyQueue').mockImplementation(async () => {
+          queueState.count = Math.max(0, queueState.count - 1)
+          return queueState.count
+        })
+
+        const results = []
+
+        // 尝试10个请求进入队列
+        for (let i = 0; i < 10; i++) {
+          const queueCount = await redis.incrConcurrencyQueue(keyId, 60000)
+
+          if (queueCount > maxQueueSize) {
+            // 队列满，释放并拒绝
+            await redis.decrConcurrencyQueue(keyId)
+            results.push({ index: i, accepted: false })
+          } else {
+            results.push({ index: i, accepted: true, position: queueCount })
+          }
+        }
+
+        const accepted = results.filter((r) => r.accepted)
+        const rejected = results.filter((r) => !r.accepted)
+
+        expect(accepted.length).toBe(5)
+        expect(rejected.length).toBe(5)
+      })
+    })
+  })
+
+  // ============================================
+  // 第三部分：真实 Redis 集成测试（可选）
+  // ============================================
+  describe('Part 3: Real Redis Integration Tests', () => {
+    const skipRealRedis = !process.env.REDIS_TEST
+
+    // 辅助函数：检查 Redis 连接
+    async function checkRedisConnection() {
+      try {
+        const client = redis.getClient()
+        if (!client) {
+          return false
+        }
+        await client.ping()
+        return true
+      } catch {
+        return false
+      }
+    }
+
+    beforeAll(async () => {
+      if (skipRealRedis) {
+        console.log('⏭️  Skipping real Redis tests (set REDIS_TEST=1 to enable)')
+        return
+      }
+
+      const connected = await checkRedisConnection()
+      if (!connected) {
+        console.log('⚠️  Redis not connected, skipping real Redis tests')
+      }
+    })
+
+    // 清理测试数据
+    afterEach(async () => {
+      if (skipRealRedis) {
+        return
+      }
+
+      try {
+        const client = redis.getClient()
+        if (!client) {
+          return
+        }
+
+        // 清理测试键
+        const testKeys = await client.keys('concurrency:queue:test-*')
+        if (testKeys.length > 0) {
+          await client.del(...testKeys)
+        }
+      } catch {
+        // 忽略清理错误
+      }
+    })
+
+    describe('Redis Queue Operations', () => {
+      const testOrSkip = skipRealRedis ? it.skip : it
+
+      testOrSkip('should atomically increment queue count with TTL', async () => {
+        const keyId = 'test-redis-queue-1'
+        const timeoutMs = 5000
+
+        const count1 = await redis.incrConcurrencyQueue(keyId, timeoutMs)
+        expect(count1).toBe(1)
+
+        const count2 = await redis.incrConcurrencyQueue(keyId, timeoutMs)
+        expect(count2).toBe(2)
+
+        // 验证 TTL 被设置
+        const client = redis.getClient()
+        const ttl = await client.ttl(`concurrency:queue:${keyId}`)
+        expect(ttl).toBeGreaterThan(0)
+        expect(ttl).toBeLessThanOrEqual(Math.ceil(timeoutMs / 1000) + 30)
+      })
+
+      testOrSkip('should atomically decrement and delete when zero', async () => {
+        const keyId = 'test-redis-queue-2'
+
+        await redis.incrConcurrencyQueue(keyId, 60000)
+        const count = await redis.decrConcurrencyQueue(keyId)
+
+        expect(count).toBe(0)
+
+        // 验证键已删除
+        const client = redis.getClient()
+        const exists = await client.exists(`concurrency:queue:${keyId}`)
+        expect(exists).toBe(0)
+      })
+
+      testOrSkip('should handle concurrent increments correctly', async () => {
+        const keyId = 'test-redis-queue-3'
+        const numRequests = 10
+
+        // 并发增加
+        const results = await Promise.all(
+          Array.from({ length: numRequests }, () => redis.incrConcurrencyQueue(keyId, 60000))
+        )
+
+        // 所有结果应该是 1 到 numRequests
+        const sorted = [...results].sort((a, b) => a - b)
+        expect(sorted).toEqual(Array.from({ length: numRequests }, (_, i) => i + 1))
+      })
+    })
+
+    describe('Redis Stats Operations', () => {
+      const testOrSkip = skipRealRedis ? it.skip : it
+
+      testOrSkip('should track queue statistics correctly', async () => {
+        const keyId = 'test-redis-stats-1'
+
+        await redis.incrConcurrencyQueueStats(keyId, 'entered')
+        await redis.incrConcurrencyQueueStats(keyId, 'entered')
+        await redis.incrConcurrencyQueueStats(keyId, 'success')
+        await redis.incrConcurrencyQueueStats(keyId, 'timeout')
+
+        const stats = await redis.getConcurrencyQueueStats(keyId)
+
+        expect(stats.entered).toBe(2)
+        expect(stats.success).toBe(1)
+        expect(stats.timeout).toBe(1)
+        expect(stats.cancelled).toBe(0)
+      })
+
+      testOrSkip('should record and retrieve wait times', async () => {
+        const keyId = 'test-redis-wait-1'
+        const waitTimes = [100, 200, 150, 300, 250]
+
+        for (const wt of waitTimes) {
+          await redis.recordQueueWaitTime(keyId, wt)
+        }
+
+        const recorded = await redis.getQueueWaitTimes(keyId)
+
+        // 应该按 LIFO 顺序存储
+        expect(recorded.length).toBe(5)
+        expect(recorded[0]).toBe(250) // 最后插入的在前面
+      })
+
+      testOrSkip('should record global wait times', async () => {
+        const waitTimes = [500, 600, 700]
+
+        for (const wt of waitTimes) {
+          await redis.recordGlobalQueueWaitTime(wt)
+        }
+
+        const recorded = await redis.getGlobalQueueWaitTimes()
+
+        expect(recorded.length).toBeGreaterThanOrEqual(3)
+      })
+    })
+
+    describe('Redis Cleanup Operations', () => {
+      const testOrSkip = skipRealRedis ? it.skip : it
+
+      testOrSkip('should clear specific queue', async () => {
+        const keyId = 'test-redis-clear-1'
+
+        await redis.incrConcurrencyQueue(keyId, 60000)
+        await redis.incrConcurrencyQueue(keyId, 60000)
+
+        const cleared = await redis.clearConcurrencyQueue(keyId)
+        expect(cleared).toBe(true)
+
+        const count = await redis.getConcurrencyQueueCount(keyId)
+        expect(count).toBe(0)
+      })
+
+      testOrSkip('should clear all queues but preserve stats', async () => {
+        const keyId1 = 'test-redis-clearall-1'
+        const keyId2 = 'test-redis-clearall-2'
+
+        // 创建队列和统计
+        await redis.incrConcurrencyQueue(keyId1, 60000)
+        await redis.incrConcurrencyQueue(keyId2, 60000)
+        await redis.incrConcurrencyQueueStats(keyId1, 'entered')
+
+        // 清理所有队列
+        const cleared = await redis.clearAllConcurrencyQueues()
+        expect(cleared).toBeGreaterThanOrEqual(2)
+
+        // 验证队列已清理
+        const count1 = await redis.getConcurrencyQueueCount(keyId1)
+        const count2 = await redis.getConcurrencyQueueCount(keyId2)
+        expect(count1).toBe(0)
+        expect(count2).toBe(0)
+
+        // 统计应该保留
+        const stats = await redis.getConcurrencyQueueStats(keyId1)
+        expect(stats.entered).toBe(1)
+      })
+    })
+  })
+
+  // ============================================
+  // 第四部分：配置服务集成测试
+  // ============================================
+  describe('Part 4: Configuration Service Integration', () => {
+    beforeEach(() => {
+      // 清除配置缓存
+      claudeRelayConfigService.clearCache()
+    })
+
+    afterEach(() => {
+      jest.restoreAllMocks()
+    })
+
+    describe('Queue Configuration', () => {
+      it('should return default queue configuration', async () => {
+        jest.spyOn(redis, 'getClient').mockReturnValue(null)
+
+        const config = await claudeRelayConfigService.getConfig()
+
+        expect(config.concurrentRequestQueueEnabled).toBe(false)
+        expect(config.concurrentRequestQueueMaxSize).toBe(3)
+        expect(config.concurrentRequestQueueMaxSizeMultiplier).toBe(0)
+        expect(config.concurrentRequestQueueTimeoutMs).toBe(10000)
+      })
+
+      it('should calculate max queue size correctly', async () => {
+        const testCases = [
+          { concurrencyLimit: 5, multiplier: 2, fixedMin: 3, expected: 10 }, // 5*2=10 > 3
+          { concurrencyLimit: 1, multiplier: 1, fixedMin: 5, expected: 5 }, // 1*1=1 < 5
+          { concurrencyLimit: 10, multiplier: 0.5, fixedMin: 3, expected: 5 }, // 10*0.5=5 > 3
+          { concurrencyLimit: 2, multiplier: 1, fixedMin: 10, expected: 10 } // 2*1=2 < 10
+        ]
+
+        for (const tc of testCases) {
+          const maxQueueSize = Math.max(tc.concurrencyLimit * tc.multiplier, tc.fixedMin)
+          expect(maxQueueSize).toBe(tc.expected)
+        }
+      })
+    })
+  })
+
+  // ============================================
+  // 第五部分：端到端场景测试
+  // ============================================
+  describe('Part 5: End-to-End Scenario Tests', () => {
+    describe('Scenario: Claude Code Agent Parallel Tool Calls', () => {
+      it('should handle burst of parallel tool results', async () => {
+        // 模拟 Claude Code Agent 发送多个并行工具结果的场景
+        const concurrencyLimit = 2
+        const maxQueueSize = 5
+
+        const state = {
+          concurrency: 0,
+          queue: 0,
+          completed: 0,
+          rejected: 0
+        }
+
+        // 模拟 8 个并行工具结果请求
+        const requests = Array.from({ length: 8 }, (_, i) => ({
+          id: `tool-result-${i + 1}`,
+          startTime: Date.now()
+        }))
+
+        // 模拟处理逻辑
+        async function processRequest(req) {
+          // 尝试获取并发槽位
+          state.concurrency++
+
+          if (state.concurrency > concurrencyLimit) {
+            // 超限，进入队列
+            state.concurrency--
+            state.queue++
+
+            if (state.queue > maxQueueSize) {
+              // 队列满，拒绝
+              state.queue--
+              state.rejected++
+              return { ...req, status: 'rejected', reason: 'queue_full' }
+            }
+
+            // 等待槽位（模拟）
+            await sleep(Math.random() * 100)
+            state.queue--
+            state.concurrency++
+          }
+
+          // 处理请求
+          await sleep(50) // 模拟处理时间
+          state.concurrency--
+          state.completed++
+
+          return { ...req, status: 'completed', duration: Date.now() - req.startTime }
+        }
+
+        const results = await Promise.all(requests.map(processRequest))
+
+        const completed = results.filter((r) => r.status === 'completed')
+        const rejected = results.filter((r) => r.status === 'rejected')
+
+        // 大部分请求应该完成
+        expect(completed.length).toBeGreaterThan(0)
+        // 可能有一些被拒绝
+        expect(state.rejected).toBe(rejected.length)
+
+        console.log(
+          `  ✓ Completed: ${completed.length}, Rejected: ${rejected.length}, Max concurrent: ${concurrencyLimit}`
+        )
+      })
+    })
+
+    describe('Scenario: Graceful Degradation', () => {
+      it('should fallback when Redis fails', async () => {
+        jest
+          .spyOn(redis, 'incrConcurrencyQueue')
+          .mockRejectedValue(new Error('Redis connection lost'))
+
+        // 模拟降级行为：Redis 失败时直接拒绝而不是崩溃
+        let result
+        try {
+          await redis.incrConcurrencyQueue('fallback-test', 60000)
+          result = { success: true }
+        } catch (error) {
+          // 优雅降级：返回 429 而不是 500
+          result = { success: false, fallback: true, error: error.message }
+        }
+
+        expect(result.fallback).toBe(true)
+        expect(result.error).toContain('Redis')
+      })
+    })
+
+    describe('Scenario: Timeout Behavior', () => {
+      it('should respect queue timeout', async () => {
+        const timeoutMs = 100
+        const startTime = Date.now()
+
+        // 模拟等待超时
+        await new Promise((resolve) => setTimeout(resolve, timeoutMs))
+
+        const elapsed = Date.now() - startTime
+        expect(elapsed).toBeGreaterThanOrEqual(timeoutMs - 10) // 允许 10ms 误差
+      })
+
+      it('should track timeout statistics', async () => {
+        const stats = { entered: 0, success: 0, timeout: 0, cancelled: 0 }
+
+        // 模拟多个请求，部分超时
+        const requests = [
+          { id: 'req-1', willTimeout: false },
+          { id: 'req-2', willTimeout: true },
+          { id: 'req-3', willTimeout: false },
+          { id: 'req-4', willTimeout: true }
+        ]
+
+        for (const req of requests) {
+          stats.entered++
+          if (req.willTimeout) {
+            stats.timeout++
+          } else {
+            stats.success++
+          }
+        }
+
+        expect(stats.entered).toBe(4)
+        expect(stats.success).toBe(2)
+        expect(stats.timeout).toBe(2)
+
+        // 成功率应该是 50%
+        const successRate = (stats.success / stats.entered) * 100
+        expect(successRate).toBe(50)
+      })
+    })
+  })
+})

tests/concurrencyQueue.test.js

@@ -0,0 +1,278 @@
+/**
+ * 并发请求排队功能测试
+ * 测试排队逻辑中的核心算法：百分位数计算、等待时间统计、指数退避等
+ *
+ * 注意：Redis 方法的测试需要集成测试环境，这里主要测试纯算法逻辑
+ */
+
+// Mock logger to avoid console output during tests
+jest.mock('../src/utils/logger', () => ({
+  api: jest.fn(),
+  warn: jest.fn(),
+  error: jest.fn(),
+  info: jest.fn(),
+  database: jest.fn(),
+  security: jest.fn()
+}))
+
+// 使用共享的统计工具函数（与生产代码一致）
+const { getPercentile, calculateWaitTimeStats } = require('../src/utils/statsHelper')
+
+describe('ConcurrencyQueue', () => {
+  describe('Percentile Calculation (nearest-rank method)', () => {
+    // 直接测试共享工具函数，确保与生产代码行为一致
+    it('should return 0 for empty array', () => {
+      expect(getPercentile([], 50)).toBe(0)
+    })
+
+    it('should return single element for single-element array', () => {
+      expect(getPercentile([100], 50)).toBe(100)
+      expect(getPercentile([100], 99)).toBe(100)
+    })
+
+    it('should return min for percentile 0', () => {
+      expect(getPercentile([10, 20, 30, 40, 50], 0)).toBe(10)
+    })
+
+    it('should return max for percentile 100', () => {
+      expect(getPercentile([10, 20, 30, 40, 50], 100)).toBe(50)
+    })
+
+    it('should calculate P50 correctly for len=10', () => {
+      // For [10, 20, 30, 40, 50, 60, 70, 80, 90, 100] (len=10)
+      // P50: ceil(50/100 * 10) - 1 = ceil(5) - 1 = 4 → value at index 4 = 50
+      const arr = [10, 20, 30, 40, 50, 60, 70, 80, 90, 100]
+      expect(getPercentile(arr, 50)).toBe(50)
+    })
+
+    it('should calculate P90 correctly for len=10', () => {
+      // For len=10, P90: ceil(90/100 * 10) - 1 = ceil(9) - 1 = 8 → value at index 8 = 90
+      const arr = [10, 20, 30, 40, 50, 60, 70, 80, 90, 100]
+      expect(getPercentile(arr, 90)).toBe(90)
+    })
+
+    it('should calculate P99 correctly for len=100', () => {
+      // For len=100, P99: ceil(99/100 * 100) - 1 = ceil(99) - 1 = 98
+      const arr = Array.from({ length: 100 }, (_, i) => i + 1)
+      expect(getPercentile(arr, 99)).toBe(99)
+    })
+
+    it('should handle two-element array correctly', () => {
+      // For [10, 20] (len=2)
+      // P50: ceil(50/100 * 2) - 1 = ceil(1) - 1 = 0 → value = 10
+      expect(getPercentile([10, 20], 50)).toBe(10)
+    })
+
+    it('should handle negative percentile as 0', () => {
+      expect(getPercentile([10, 20, 30], -10)).toBe(10)
+    })
+
+    it('should handle percentile > 100 as 100', () => {
+      expect(getPercentile([10, 20, 30], 150)).toBe(30)
+    })
+  })
+
+  describe('Wait Time Stats Calculation', () => {
+    // 直接测试共享工具函数
+    it('should return null for empty array', () => {
+      expect(calculateWaitTimeStats([])).toBeNull()
+    })
+
+    it('should return null for null input', () => {
+      expect(calculateWaitTimeStats(null)).toBeNull()
+    })
+
+    it('should return null for undefined input', () => {
+      expect(calculateWaitTimeStats(undefined)).toBeNull()
+    })
+
+    it('should calculate stats correctly for typical data', () => {
+      const waitTimes = [100, 200, 150, 300, 250, 180, 220, 280, 190, 210]
+      const stats = calculateWaitTimeStats(waitTimes)
+
+      expect(stats.count).toBe(10)
+      expect(stats.min).toBe(100)
+      expect(stats.max).toBe(300)
+      // Sum: 100+150+180+190+200+210+220+250+280+300 = 2080
+      expect(stats.avg).toBe(208)
+      expect(stats.sampleSizeWarning).toBeUndefined()
+    })
+
+    it('should add warning for small sample size (< 10)', () => {
+      const waitTimes = [100, 200, 300]
+      const stats = calculateWaitTimeStats(waitTimes)
+
+      expect(stats.count).toBe(3)
+      expect(stats.sampleSizeWarning).toBe('Results may be inaccurate due to small sample size')
+    })
+
+    it('should handle single value', () => {
+      const stats = calculateWaitTimeStats([500])
+
+      expect(stats.count).toBe(1)
+      expect(stats.min).toBe(500)
+      expect(stats.max).toBe(500)
+      expect(stats.avg).toBe(500)
+      expect(stats.p50).toBe(500)
+      expect(stats.p90).toBe(500)
+      expect(stats.p99).toBe(500)
+    })
+
+    it('should sort input array before calculating', () => {
+      const waitTimes = [500, 100, 300, 200, 400]
+      const stats = calculateWaitTimeStats(waitTimes)
+
+      expect(stats.min).toBe(100)
+      expect(stats.max).toBe(500)
+    })
+
+    it('should not modify original array', () => {
+      const waitTimes = [500, 100, 300]
+      calculateWaitTimeStats(waitTimes)
+
+      expect(waitTimes).toEqual([500, 100, 300])
+    })
+  })
+
+  describe('Exponential Backoff with Jitter', () => {
+    /**
+     * 指数退避计算函数（与 auth.js 中的实现一致）
+     * @param {number} currentInterval - 当前轮询间隔
+     * @param {number} backoffFactor - 退避系数
+     * @param {number} jitterRatio - 抖动比例
+     * @param {number} maxInterval - 最大间隔
+     * @param {number} randomValue - 随机值 [0, 1)，用于确定性测试
+     */
+    function calculateNextInterval(
+      currentInterval,
+      backoffFactor,
+      jitterRatio,
+      maxInterval,
+      randomValue
+    ) {
+      let nextInterval = currentInterval * backoffFactor
+      // 抖动范围：[-jitterRatio, +jitterRatio]
+      const jitter = nextInterval * jitterRatio * (randomValue * 2 - 1)
+      nextInterval = nextInterval + jitter
+      return Math.max(1, Math.min(nextInterval, maxInterval))
+    }
+
+    it('should apply exponential backoff without jitter (randomValue=0.5)', () => {
+      // randomValue = 0.5 gives jitter = 0
+      const next = calculateNextInterval(100, 1.5, 0.2, 1000, 0.5)
+      expect(next).toBe(150) // 100 * 1.5 = 150
+    })
+
+    it('should apply maximum positive jitter (randomValue=1.0)', () => {
+      // randomValue = 1.0 gives maximum positive jitter (+20%)
+      const next = calculateNextInterval(100, 1.5, 0.2, 1000, 1.0)
+      // 100 * 1.5 = 150, jitter = 150 * 0.2 * 1 = 30
+      expect(next).toBe(180) // 150 + 30
+    })
+
+    it('should apply maximum negative jitter (randomValue=0.0)', () => {
+      // randomValue = 0.0 gives maximum negative jitter (-20%)
+      const next = calculateNextInterval(100, 1.5, 0.2, 1000, 0.0)
+      // 100 * 1.5 = 150, jitter = 150 * 0.2 * -1 = -30
+      expect(next).toBe(120) // 150 - 30
+    })
+
+    it('should respect maximum interval', () => {
+      const next = calculateNextInterval(800, 1.5, 0.2, 1000, 1.0)
+      // 800 * 1.5 = 1200, with +20% jitter = 1440, capped at 1000
+      expect(next).toBe(1000)
+    })
+
+    it('should never go below 1ms even with extreme negative jitter', () => {
+      const next = calculateNextInterval(1, 1.0, 0.9, 1000, 0.0)
+      // 1 * 1.0 = 1, jitter = 1 * 0.9 * -1 = -0.9
+      // 1 - 0.9 = 0.1, but Math.max(1, ...) ensures minimum is 1
+      expect(next).toBe(1)
+    })
+
+    it('should handle zero jitter ratio', () => {
+      const next = calculateNextInterval(100, 2.0, 0, 1000, 0.0)
+      expect(next).toBe(200) // Pure exponential, no jitter
+    })
+
+    it('should handle large backoff factor', () => {
+      const next = calculateNextInterval(100, 3.0, 0.1, 1000, 0.5)
+      expect(next).toBe(300) // 100 * 3.0 = 300
+    })
+
+    describe('jitter distribution', () => {
+      it('should produce values in expected range', () => {
+        const results = []
+        // Test with various random values
+        for (let r = 0; r <= 1; r += 0.1) {
+          results.push(calculateNextInterval(100, 1.5, 0.2, 1000, r))
+        }
+        // All values should be between 120 (150 - 30) and 180 (150 + 30)
+        expect(Math.min(...results)).toBeGreaterThanOrEqual(120)
+        expect(Math.max(...results)).toBeLessThanOrEqual(180)
+      })
+    })
+  })
+
+  describe('Queue Size Calculation', () => {
+    /**
+     * 最大排队数计算（与 auth.js 中的实现一致）
+     */
+    function calculateMaxQueueSize(concurrencyLimit, multiplier, fixedMin) {
+      return Math.max(concurrencyLimit * multiplier, fixedMin)
+    }
+
+    it('should use multiplier when result is larger', () => {
+      // concurrencyLimit=10, multiplier=2, fixedMin=5
+      // max(10*2, 5) = max(20, 5) = 20
+      expect(calculateMaxQueueSize(10, 2, 5)).toBe(20)
+    })
+
+    it('should use fixed minimum when multiplier result is smaller', () => {
+      // concurrencyLimit=2, multiplier=1, fixedMin=5
+      // max(2*1, 5) = max(2, 5) = 5
+      expect(calculateMaxQueueSize(2, 1, 5)).toBe(5)
+    })
+
+    it('should handle zero multiplier', () => {
+      // concurrencyLimit=10, multiplier=0, fixedMin=3
+      // max(10*0, 3) = max(0, 3) = 3
+      expect(calculateMaxQueueSize(10, 0, 3)).toBe(3)
+    })
+
+    it('should handle fractional multiplier', () => {
+      // concurrencyLimit=10, multiplier=1.5, fixedMin=5
+      // max(10*1.5, 5) = max(15, 5) = 15
+      expect(calculateMaxQueueSize(10, 1.5, 5)).toBe(15)
+    })
+  })
+
+  describe('TTL Calculation', () => {
+    /**
+     * 排队计数器 TTL 计算（与 redis.js 中的实现一致）
+     */
+    function calculateQueueTtl(timeoutMs, bufferSeconds = 30) {
+      return Math.ceil(timeoutMs / 1000) + bufferSeconds
+    }
+
+    it('should calculate TTL with default buffer', () => {
+      // 60000ms = 60s + 30s buffer = 90s
+      expect(calculateQueueTtl(60000)).toBe(90)
+    })
+
+    it('should round up milliseconds to seconds', () => {
+      // 61500ms = ceil(61.5) = 62s + 30s = 92s
+      expect(calculateQueueTtl(61500)).toBe(92)
+    })
+
+    it('should handle custom buffer', () => {
+      // 30000ms = 30s + 60s buffer = 90s
+      expect(calculateQueueTtl(30000, 60)).toBe(90)
+    })
+
+    it('should handle very short timeout', () => {
+      // 1000ms = 1s + 30s = 31s
+      expect(calculateQueueTtl(1000)).toBe(31)
+    })
+  })
+})

tests/userMessageQueue.test.js

@@ -0,0 +1,434 @@
+/**
+ * 用户消息队列服务测试
+ * 测试消息类型检测、队列串行行为、延迟间隔、超时处理和功能开关
+ */
+
+const redis = require('../src/models/redis')
+const userMessageQueueService = require('../src/services/userMessageQueueService')
+
+describe('UserMessageQueueService', () => {
+  describe('isUserMessageRequest', () => {
+    it('should return true when last message role is user', () => {
+      const requestBody = {
+        messages: [
+          { role: 'user', content: 'Hello' },
+          { role: 'assistant', content: 'Hi there' },
+          { role: 'user', content: 'How are you?' }
+        ]
+      }
+      expect(userMessageQueueService.isUserMessageRequest(requestBody)).toBe(true)
+    })
+
+    it('should return false when last message role is assistant', () => {
+      const requestBody = {
+        messages: [
+          { role: 'user', content: 'Hello' },
+          { role: 'assistant', content: 'Hi there' }
+        ]
+      }
+      expect(userMessageQueueService.isUserMessageRequest(requestBody)).toBe(false)
+    })
+
+    it('should return false when last message contains tool_result', () => {
+      const requestBody = {
+        messages: [
+          { role: 'user', content: 'Hello' },
+          { role: 'assistant', content: 'Let me check that' },
+          {
+            role: 'user',
+            content: [
+              {
+                type: 'tool_result',
+                tool_use_id: 'test-id',
+                content: 'Tool result'
+              }
+            ]
+          }
+        ]
+      }
+      // tool_result 消息虽然 role 是 user，但不是真正的用户消息
+      // 应该返回 false，不进入用户消息队列
+      expect(userMessageQueueService.isUserMessageRequest(requestBody)).toBe(false)
+    })
+
+    it('should return false when last message contains multiple tool_results', () => {
+      const requestBody = {
+        messages: [
+          { role: 'user', content: 'Run multiple tools' },
+          {
+            role: 'user',
+            content: [
+              {
+                type: 'tool_result',
+                tool_use_id: 'tool-1',
+                content: 'Result 1'
+              },
+              {
+                type: 'tool_result',
+                tool_use_id: 'tool-2',
+                content: 'Result 2'
+              }
+            ]
+          }
+        ]
+      }
+      expect(userMessageQueueService.isUserMessageRequest(requestBody)).toBe(false)
+    })
+
+    it('should return true when user message has array content with text type', () => {
+      const requestBody = {
+        messages: [
+          {
+            role: 'user',
+            content: [
+              {
+                type: 'text',
+                text: 'Hello, this is a user message'
+              }
+            ]
+          }
+        ]
+      }
+      expect(userMessageQueueService.isUserMessageRequest(requestBody)).toBe(true)
+    })
+
+    it('should return true when user message has mixed text and image content', () => {
+      const requestBody = {
+        messages: [
+          {
+            role: 'user',
+            content: [
+              {
+                type: 'text',
+                text: 'What is in this image?'
+              },
+              {
+                type: 'image',
+                source: { type: 'base64', media_type: 'image/png', data: '...' }
+              }
+            ]
+          }
+        ]
+      }
+      expect(userMessageQueueService.isUserMessageRequest(requestBody)).toBe(true)
+    })
+
+    it('should return false when messages is empty', () => {
+      const requestBody = { messages: [] }
+      expect(userMessageQueueService.isUserMessageRequest(requestBody)).toBe(false)
+    })
+
+    it('should return false when messages is not an array', () => {
+      const requestBody = { messages: 'not an array' }
+      expect(userMessageQueueService.isUserMessageRequest(requestBody)).toBe(false)
+    })
+
+    it('should return false when messages is undefined', () => {
+      const requestBody = {}
+      expect(userMessageQueueService.isUserMessageRequest(requestBody)).toBe(false)
+    })
+
+    it('should return false when requestBody is null', () => {
+      expect(userMessageQueueService.isUserMessageRequest(null)).toBe(false)
+    })
+
+    it('should return false when requestBody is undefined', () => {
+      expect(userMessageQueueService.isUserMessageRequest(undefined)).toBe(false)
+    })
+
+    it('should return false when last message has no role', () => {
+      const requestBody = {
+        messages: [{ content: 'Hello' }]
+      }
+      expect(userMessageQueueService.isUserMessageRequest(requestBody)).toBe(false)
+    })
+
+    it('should handle single user message', () => {
+      const requestBody = {
+        messages: [{ role: 'user', content: 'Hello' }]
+      }
+      expect(userMessageQueueService.isUserMessageRequest(requestBody)).toBe(true)
+    })
+
+    it('should handle single assistant message', () => {
+      const requestBody = {
+        messages: [{ role: 'assistant', content: 'Hello' }]
+      }
+      expect(userMessageQueueService.isUserMessageRequest(requestBody)).toBe(false)
+    })
+  })
+
+  describe('getConfig', () => {
+    it('should return config with expected properties', async () => {
+      const config = await userMessageQueueService.getConfig()
+      expect(config).toHaveProperty('enabled')
+      expect(config).toHaveProperty('delayMs')
+      expect(config).toHaveProperty('timeoutMs')
+      expect(config).toHaveProperty('lockTtlMs')
+      expect(typeof config.enabled).toBe('boolean')
+      expect(typeof config.delayMs).toBe('number')
+      expect(typeof config.timeoutMs).toBe('number')
+      expect(typeof config.lockTtlMs).toBe('number')
+    })
+  })
+
+  describe('isEnabled', () => {
+    it('should return boolean', async () => {
+      const enabled = await userMessageQueueService.isEnabled()
+      expect(typeof enabled).toBe('boolean')
+    })
+  })
+
+  describe('acquireQueueLock', () => {
+    afterEach(() => {
+      jest.restoreAllMocks()
+    })
+
+    it('should acquire lock immediately when no lock exists', async () => {
+      jest.spyOn(userMessageQueueService, 'getConfig').mockResolvedValue({
+        enabled: true,
+        delayMs: 200,
+        timeoutMs: 30000,
+        lockTtlMs: 120000
+      })
+      jest.spyOn(redis, 'acquireUserMessageLock').mockResolvedValue({
+        acquired: true,
+        waitMs: 0
+      })
+
+      const result = await userMessageQueueService.acquireQueueLock('acct-1', 'req-1')
+
+      expect(result.acquired).toBe(true)
+      expect(result.requestId).toBe('req-1')
+      expect(result.error).toBeUndefined()
+    })
+
+    it('should skip lock acquisition when queue disabled', async () => {
+      jest.spyOn(userMessageQueueService, 'getConfig').mockResolvedValue({
+        enabled: false,
+        delayMs: 200,
+        timeoutMs: 30000,
+        lockTtlMs: 120000
+      })
+      const acquireSpy = jest.spyOn(redis, 'acquireUserMessageLock')
+
+      const result = await userMessageQueueService.acquireQueueLock('acct-1')
+
+      expect(result.acquired).toBe(true)
+      expect(result.skipped).toBe(true)
+      expect(acquireSpy).not.toHaveBeenCalled()
+    })
+
+    it('should generate requestId when not provided', async () => {
+      jest.spyOn(userMessageQueueService, 'getConfig').mockResolvedValue({
+        enabled: true,
+        delayMs: 200,
+        timeoutMs: 30000,
+        lockTtlMs: 120000
+      })
+      jest.spyOn(redis, 'acquireUserMessageLock').mockResolvedValue({
+        acquired: true,
+        waitMs: 0
+      })
+
+      const result = await userMessageQueueService.acquireQueueLock('acct-1')
+
+      expect(result.acquired).toBe(true)
+      expect(result.requestId).toBeDefined()
+      expect(result.requestId.length).toBeGreaterThan(0)
+    })
+
+    it('should wait and retry when lock is held by another request', async () => {
+      jest.spyOn(userMessageQueueService, 'getConfig').mockResolvedValue({
+        enabled: true,
+        delayMs: 200,
+        timeoutMs: 1000,
+        lockTtlMs: 120000
+      })
+
+      let callCount = 0
+      jest.spyOn(redis, 'acquireUserMessageLock').mockImplementation(async () => {
+        callCount++
+        if (callCount < 3) {
+          return { acquired: false, waitMs: -1 } // lock held
+        }
+        return { acquired: true, waitMs: 0 }
+      })
+
+      // Mock sleep to speed up test
+      jest.spyOn(userMessageQueueService, '_sleep').mockResolvedValue(undefined)
+
+      const result = await userMessageQueueService.acquireQueueLock('acct-1', 'req-1')
+
+      expect(result.acquired).toBe(true)
+      expect(callCount).toBe(3)
+    })
+
+    it('should respect delay when previous request just completed', async () => {
+      jest.spyOn(userMessageQueueService, 'getConfig').mockResolvedValue({
+        enabled: true,
+        delayMs: 200,
+        timeoutMs: 1000,
+        lockTtlMs: 120000
+      })
+
+      let callCount = 0
+      jest.spyOn(redis, 'acquireUserMessageLock').mockImplementation(async () => {
+        callCount++
+        if (callCount === 1) {
+          return { acquired: false, waitMs: 150 } // need to wait 150ms for delay
+        }
+        return { acquired: true, waitMs: 0 }
+      })
+
+      const sleepSpy = jest.spyOn(userMessageQueueService, '_sleep').mockResolvedValue(undefined)
+
+      const result = await userMessageQueueService.acquireQueueLock('acct-1', 'req-1')
+
+      expect(result.acquired).toBe(true)
+      expect(sleepSpy).toHaveBeenCalledWith(150) // Should wait for delay
+    })
+
+    it('should timeout and return error when wait exceeds timeout', async () => {
+      jest.spyOn(userMessageQueueService, 'getConfig').mockResolvedValue({
+        enabled: true,
+        delayMs: 200,
+        timeoutMs: 100, // very short timeout
+        lockTtlMs: 120000
+      })
+
+      jest.spyOn(redis, 'acquireUserMessageLock').mockResolvedValue({
+        acquired: false,
+        waitMs: -1 // always held
+      })
+
+      // Use real timers for timeout test but mock sleep to be instant
+      jest.spyOn(userMessageQueueService, '_sleep').mockImplementation(async () => {
+        // Simulate time passing
+        await new Promise((resolve) => setTimeout(resolve, 60))
+      })
+
+      const result = await userMessageQueueService.acquireQueueLock('acct-1', 'req-1', 100)
+
+      expect(result.acquired).toBe(false)
+      expect(result.error).toBe('queue_timeout')
+    })
+  })
+
+  describe('releaseQueueLock', () => {
+    afterEach(() => {
+      jest.restoreAllMocks()
+    })
+
+    it('should release lock successfully when holding the lock', async () => {
+      jest.spyOn(redis, 'releaseUserMessageLock').mockResolvedValue(true)
+
+      const result = await userMessageQueueService.releaseQueueLock('acct-1', 'req-1')
+
+      expect(result).toBe(true)
+      expect(redis.releaseUserMessageLock).toHaveBeenCalledWith('acct-1', 'req-1')
+    })
+
+    it('should return false when not holding the lock', async () => {
+      jest.spyOn(redis, 'releaseUserMessageLock').mockResolvedValue(false)
+
+      const result = await userMessageQueueService.releaseQueueLock('acct-1', 'req-1')
+
+      expect(result).toBe(false)
+    })
+
+    it('should return false when accountId is missing', async () => {
+      const releaseSpy = jest.spyOn(redis, 'releaseUserMessageLock')
+
+      const result = await userMessageQueueService.releaseQueueLock(null, 'req-1')
+
+      expect(result).toBe(false)
+      expect(releaseSpy).not.toHaveBeenCalled()
+    })
+
+    it('should return false when requestId is missing', async () => {
+      const releaseSpy = jest.spyOn(redis, 'releaseUserMessageLock')
+
+      const result = await userMessageQueueService.releaseQueueLock('acct-1', null)
+
+      expect(result).toBe(false)
+      expect(releaseSpy).not.toHaveBeenCalled()
+    })
+  })
+
+  describe('queue serialization behavior', () => {
+    afterEach(() => {
+      jest.restoreAllMocks()
+    })
+
+    it('should allow different accounts to acquire locks simultaneously', async () => {
+      jest.spyOn(userMessageQueueService, 'getConfig').mockResolvedValue({
+        enabled: true,
+        delayMs: 200,
+        timeoutMs: 30000,
+        lockTtlMs: 120000
+      })
+      jest.spyOn(redis, 'acquireUserMessageLock').mockResolvedValue({
+        acquired: true,
+        waitMs: 0
+      })
+
+      const [result1, result2] = await Promise.all([
+        userMessageQueueService.acquireQueueLock('acct-1', 'req-1'),
+        userMessageQueueService.acquireQueueLock('acct-2', 'req-2')
+      ])
+
+      expect(result1.acquired).toBe(true)
+      expect(result2.acquired).toBe(true)
+    })
+
+    it('should serialize requests for same account', async () => {
+      jest.spyOn(userMessageQueueService, 'getConfig').mockResolvedValue({
+        enabled: true,
+        delayMs: 50,
+        timeoutMs: 5000,
+        lockTtlMs: 120000
+      })
+
+      const lockState = { held: false, holderId: null }
+
+      jest
+        .spyOn(redis, 'acquireUserMessageLock')
+        .mockImplementation(async (accountId, requestId) => {
+          if (!lockState.held) {
+            lockState.held = true
+            lockState.holderId = requestId
+            return { acquired: true, waitMs: 0 }
+          }
+          return { acquired: false, waitMs: -1 }
+        })
+
+      jest
+        .spyOn(redis, 'releaseUserMessageLock')
+        .mockImplementation(async (accountId, requestId) => {
+          if (lockState.holderId === requestId) {
+            lockState.held = false
+            lockState.holderId = null
+            return true
+          }
+          return false
+        })
+
+      jest.spyOn(userMessageQueueService, '_sleep').mockResolvedValue(undefined)
+
+      // First request acquires lock
+      const result1 = await userMessageQueueService.acquireQueueLock('acct-1', 'req-1')
+      expect(result1.acquired).toBe(true)
+
+      // Second request should fail to acquire (lock held)
+      const acquirePromise = userMessageQueueService.acquireQueueLock('acct-1', 'req-2', 200)
+
+      // Release first lock
+      await userMessageQueueService.releaseQueueLock('acct-1', 'req-1')
+
+      // Now second request should acquire
+      const result2 = await acquirePromise
+      expect(result2.acquired).toBe(true)
+    })
+  })
+})

web/admin-spa/package-lock.json

@@ -1157,7 +1157,6 @@
       "resolved": "https://registry.npmmirror.com/@types/lodash-es/-/lodash-es-4.17.12.tgz",
       "integrity": "sha512-0NgftHUcV4v34VhXm8QBSftKVXtbkBG3ViCjs6+eJ5a6y6Mi/jiFGPc1sC7QK+9BFhWrURE3EOggmWaSxL9OzQ==",
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@types/lodash": "*"
       }
@@ -1352,7 +1351,6 @@
       "integrity": "sha512-NZyJarBfL7nWwIq+FDL6Zp/yHEhePMNnnJ0y3qfieCrmNvYct8uvtiV41UvlSe6apAfk0fY1FbWx+NwfmpvtTg==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "bin": {
         "acorn": "bin/acorn"
       },
@@ -1589,7 +1587,6 @@
         }
       ],
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "caniuse-lite": "^1.0.30001726",
         "electron-to-chromium": "^1.5.173",
@@ -3063,15 +3060,13 @@
       "version": "4.17.21",
       "resolved": "https://registry.npmmirror.com/lodash/-/lodash-4.17.21.tgz",
       "integrity": "sha512-v2kDEe57lecTulaDIuNTPy3Ry4gLGJ6Z1O3vE1krgXZNrsQ+LFTGHVxVjcXPs17LhbZVGedAJv8XZ1tvj5FvSg==",
-      "license": "MIT",
+      "license": "MIT"
-      "peer": true
     },
     "node_modules/lodash-es": {
       "version": "4.17.21",
       "resolved": "https://registry.npmmirror.com/lodash-es/-/lodash-es-4.17.21.tgz",
       "integrity": "sha512-mKnC+QJ9pWVzv+C4/U3rRsHapFfHvQFoFB92e52xeyGMcX6/OlIl78je1u8vePzYZSkkogMPJ2yjxxsb89cxyw==",
-      "license": "MIT",
+      "license": "MIT"
-      "peer": true
     },
     "node_modules/lodash-unified": {
       "version": "1.0.3",
@@ -3623,7 +3618,6 @@
         }
       ],
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "nanoid": "^3.3.11",
         "picocolors": "^1.1.1",
@@ -3770,7 +3764,6 @@
       "integrity": "sha512-I7AIg5boAr5R0FFtJ6rCfD+LFsWHp81dolrFD8S79U9tb8Az2nGrJncnMSnys+bpQJfRUzqs9hnA81OAA3hCuQ==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "bin": {
         "prettier": "bin/prettier.cjs"
       },
@@ -4035,7 +4028,6 @@
       "integrity": "sha512-33xGNBsDJAkzt0PvninskHlWnTIPgDtTwhg0U38CUoNP/7H6wI2Cz6dUeoNPbjdTdsYTGuiFFASuUOWovH0SyQ==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@types/estree": "1.0.8"
       },
@@ -4533,7 +4525,6 @@
       "integrity": "sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "engines": {
         "node": ">=12"
       },
@@ -4924,7 +4915,6 @@
       "integrity": "sha512-qO3aKv3HoQC8QKiNSTuUM1l9o/XX3+c+VTgLHbJWHZGeTPVAg2XwazI9UWzoxjIJCGCV2zU60uqMzjeLZuULqA==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "esbuild": "^0.21.3",
         "postcss": "^8.4.43",
@@ -5125,7 +5115,6 @@
       "resolved": "https://registry.npmmirror.com/vue/-/vue-3.5.18.tgz",
       "integrity": "sha512-7W4Y4ZbMiQ3SEo+m9lnoNpV9xG7QVMLa+/0RFwwiAVkeYoyGXqWE85jabU4pllJNUzqfLShJ5YLptewhCWUgNA==",
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@vue/compiler-dom": "3.5.18",
         "@vue/compiler-sfc": "3.5.18",

web/admin-spa/src/components/accounts/AccountForm.vue

@@ -1320,10 +1320,10 @@
                       class="rounded-lg bg-blue-100 px-3 py-1 text-xs text-blue-700 transition-colors hover:bg-blue-200 dark:bg-blue-900/30 dark:text-blue-400 dark:hover:bg-blue-900/50"
                       type="button"
                       @click="
-                        addPresetMapping('claude-sonnet-4-20250514', 'claude-sonnet-4-20250514')
+                        addPresetMapping('claude-opus-4-5-20251101', 'claude-opus-4-5-20251101')
                       "
                     >
-                      + Sonnet 4
+                      + Opus 4.5
                     </button>
                     <button
                       class="rounded-lg bg-indigo-100 px-3 py-1 text-xs text-indigo-700 transition-colors hover:bg-indigo-200 dark:bg-indigo-900/30 dark:text-indigo-400 dark:hover:bg-indigo-900/50"
@@ -1334,24 +1334,6 @@
                     >
                       + Sonnet 4.5
                     </button>
-                    <button
-                      class="rounded-lg bg-purple-100 px-3 py-1 text-xs text-purple-700 transition-colors hover:bg-purple-200 dark:bg-purple-900/30 dark:text-purple-400 dark:hover:bg-purple-900/50"
-                      type="button"
-                      @click="
-                        addPresetMapping('claude-opus-4-1-20250805', 'claude-opus-4-1-20250805')
-                      "
-                    >
-                      + Opus 4.1
-                    </button>
-                    <button
-                      class="rounded-lg bg-green-100 px-3 py-1 text-xs text-green-700 transition-colors hover:bg-green-200 dark:bg-green-900/30 dark:text-green-400 dark:hover:bg-green-900/50"
-                      type="button"
-                      @click="
-                        addPresetMapping('claude-3-5-haiku-20241022', 'claude-3-5-haiku-20241022')
-                      "
-                    >
-                      + Haiku 3.5
-                    </button>
                     <button
                       class="rounded-lg bg-emerald-100 px-3 py-1 text-xs text-emerald-700 transition-colors hover:bg-emerald-200 dark:bg-emerald-900/30 dark:text-emerald-400 dark:hover:bg-emerald-900/50"
                       type="button"
@@ -1843,7 +1825,7 @@
                     >
                       请从已登录 Gemini CLI 的机器上获取
                       <code class="rounded bg-blue-100 px-1 py-0.5 font-mono dark:bg-blue-900/50"
-                        >~/.config/gemini/credentials.json</code
+                        >~/.config/.gemini/oauth_creds.json</code
                       >
                       文件中的凭证。
                     </p>
@@ -1944,6 +1926,22 @@
                   rows="4"
                 />
               </div>
+
+              <!-- Droid User-Agent 配置 (OAuth/Manual 模式) -->
+              <div v-if="form.platform === 'droid'">
+                <label class="mb-3 block text-sm font-semibold text-gray-700 dark:text-gray-300"
+                  >自定义 User-Agent (可选)</label
+                >
+                <input
+                  v-model="form.userAgent"
+                  class="form-input w-full border-gray-300 dark:border-gray-600 dark:bg-gray-700 dark:text-gray-200 dark:placeholder-gray-400"
+                  placeholder="factory-cli/0.32.1"
+                  type="text"
+                />
+                <p class="mt-1 text-xs text-gray-500 dark:text-gray-400">
+                  留空使用默认值 factory-cli/0.32.1，可根据需要自定义
+                </p>
+              </div>
             </div>
 
             <!-- API Key 模式输入 -->
@@ -1989,6 +1987,22 @@
                 </p>
               </div>
 
+              <!-- Droid User-Agent 配置 -->
+              <div>
+                <label class="mb-3 block text-sm font-semibold text-gray-700 dark:text-gray-300"
+                  >自定义 User-Agent (可选)</label
+                >
+                <input
+                  v-model="form.userAgent"
+                  class="form-input w-full border-gray-300 dark:border-gray-600 dark:bg-gray-700 dark:text-gray-200 dark:placeholder-gray-400"
+                  placeholder="factory-cli/0.32.1"
+                  type="text"
+                />
+                <p class="mt-1 text-xs text-gray-500 dark:text-gray-400">
+                  留空使用默认值 factory-cli/0.32.1，可根据需要自定义
+                </p>
+              </div>
+
               <div
                 class="rounded-lg border border-purple-200 bg-white/70 p-3 text-xs text-purple-800 dark:border-purple-700 dark:bg-purple-800/20 dark:text-purple-100"
               >
@@ -3639,6 +3653,22 @@
             </div>
           </div>
 
+          <!-- Droid User-Agent 配置 (编辑模式) -->
+          <div v-if="form.platform === 'droid'">
+            <label class="mb-3 block text-sm font-semibold text-gray-700 dark:text-gray-300"
+              >自定义 User-Agent (可选)</label
+            >
+            <input
+              v-model="form.userAgent"
+              class="form-input w-full border-gray-300 dark:border-gray-600 dark:bg-gray-700 dark:text-gray-200 dark:placeholder-gray-400"
+              placeholder="factory-cli/0.32.1"
+              type="text"
+            />
+            <p class="mt-1 text-xs text-gray-500 dark:text-gray-400">
+              留空使用默认值 factory-cli/0.32.1，可根据需要自定义
+            </p>
+          </div>
+
           <!-- 代理设置 -->
           <ProxyConfig v-model="form.proxy" />
 

web/admin-spa/src/components/accounts/AccountScheduledTestModal.vue

@@ -0,0 +1,402 @@
+<template>
+  <Teleport to="body">
+    <div
+      v-if="show"
+      class="fixed inset-0 z-[1050] flex items-center justify-center bg-gray-900/40 backdrop-blur-sm"
+    >
+      <div class="absolute inset-0" @click="handleClose" />
+      <div
+        class="relative z-10 mx-3 flex w-full max-w-lg flex-col overflow-hidden rounded-2xl border border-gray-200/70 bg-white/95 shadow-2xl ring-1 ring-black/5 transition-all dark:border-gray-700/60 dark:bg-gray-900/95 dark:ring-white/10 sm:mx-4"
+      >
+        <!-- 顶部栏 -->
+        <div
+          class="flex items-center justify-between border-b border-gray-100 bg-white/80 px-5 py-4 backdrop-blur dark:border-gray-800 dark:bg-gray-900/80"
+        >
+          <div class="flex items-center gap-3">
+            <div
+              class="flex h-10 w-10 flex-shrink-0 items-center justify-center rounded-xl bg-gradient-to-br from-amber-500 to-orange-500 text-white shadow-lg"
+            >
+              <i class="fas fa-clock" />
+            </div>
+            <div>
+              <h3 class="text-lg font-semibold text-gray-900 dark:text-gray-100">定时测试配置</h3>
+              <p class="text-xs text-gray-500 dark:text-gray-400">
+                {{ account?.name || '未知账户' }}
+              </p>
+            </div>
+          </div>
+          <button
+            class="flex h-9 w-9 items-center justify-center rounded-full bg-gray-100 text-gray-500 transition hover:bg-gray-200 hover:text-gray-700 dark:bg-gray-800 dark:text-gray-400 dark:hover:bg-gray-700 dark:hover:text-gray-200"
+            :disabled="saving"
+            @click="handleClose"
+          >
+            <i class="fas fa-times text-sm" />
+          </button>
+        </div>
+
+        <!-- 内容区域 -->
+        <div class="px-5 py-4">
+          <!-- 加载状态 -->
+          <div v-if="loading" class="flex items-center justify-center py-8">
+            <i class="fas fa-spinner fa-spin mr-2 text-blue-500" />
+            <span class="text-gray-500 dark:text-gray-400">加载配置中...</span>
+          </div>
+
+          <template v-else>
+            <!-- 启用开关 -->
+            <div class="mb-5 flex items-center justify-between">
+              <div>
+                <p class="font-medium text-gray-700 dark:text-gray-300">启用定时测试</p>
+                <p class="text-xs text-gray-500 dark:text-gray-400">按计划自动测试账户连通性</p>
+              </div>
+              <button
+                :class="[
+                  'relative h-6 w-11 rounded-full transition-colors duration-200',
+                  config.enabled ? 'bg-green-500' : 'bg-gray-300 dark:bg-gray-600'
+                ]"
+                @click="config.enabled = !config.enabled"
+              >
+                <span
+                  :class="[
+                    'absolute top-0.5 h-5 w-5 rounded-full bg-white shadow-md transition-transform duration-200',
+                    config.enabled ? 'left-5' : 'left-0.5'
+                  ]"
+                />
+              </button>
+            </div>
+
+            <!-- Cron 表达式配置 -->
+            <div class="mb-5">
+              <label class="mb-2 block text-sm font-medium text-gray-700 dark:text-gray-300">
+                Cron 表达式
+              </label>
+              <input
+                v-model="config.cronExpression"
+                class="w-full rounded-lg border border-gray-200 bg-white px-3 py-2 text-sm text-gray-700 placeholder-gray-400 transition focus:border-blue-500 focus:outline-none focus:ring-2 focus:ring-blue-500/20 dark:border-gray-700 dark:bg-gray-800 dark:text-gray-300 dark:placeholder-gray-500"
+                :disabled="!config.enabled"
+                placeholder="0 8 * * *"
+                type="text"
+              />
+              <p class="mt-1.5 text-xs text-gray-500 dark:text-gray-400">
+                格式: 分 时 日 月 周 (例: "0 8 * * *" = 每天8:00)
+              </p>
+            </div>
+
+            <!-- 快捷选项 -->
+            <div class="mb-5">
+              <label class="mb-2 block text-sm font-medium text-gray-700 dark:text-gray-300">
+                快捷设置
+              </label>
+              <div class="flex flex-wrap gap-2">
+                <button
+                  v-for="preset in cronPresets"
+                  :key="preset.value"
+                  :class="[
+                    'rounded-lg border px-3 py-1.5 text-xs font-medium transition',
+                    config.cronExpression === preset.value
+                      ? 'border-blue-500 bg-blue-50 text-blue-700 dark:border-blue-400 dark:bg-blue-900/30 dark:text-blue-300'
+                      : 'border-gray-200 bg-gray-50 text-gray-600 hover:bg-gray-100 dark:border-gray-700 dark:bg-gray-800 dark:text-gray-400 dark:hover:bg-gray-700',
+                    !config.enabled && 'cursor-not-allowed opacity-50'
+                  ]"
+                  :disabled="!config.enabled"
+                  @click="config.cronExpression = preset.value"
+                >
+                  {{ preset.label }}
+                </button>
+              </div>
+            </div>
+
+            <!-- 测试模型选择 -->
+            <div class="mb-5">
+              <label class="mb-2 block text-sm font-medium text-gray-700 dark:text-gray-300">
+                测试模型
+              </label>
+              <input
+                v-model="config.model"
+                class="w-full rounded-lg border border-gray-200 bg-white px-3 py-2 text-sm text-gray-700 placeholder-gray-400 transition focus:border-blue-500 focus:outline-none focus:ring-2 focus:ring-blue-500/20 dark:border-gray-700 dark:bg-gray-800 dark:text-gray-300 dark:placeholder-gray-500"
+                :disabled="!config.enabled"
+                placeholder="claude-sonnet-4-5-20250929"
+                type="text"
+              />
+              <div class="mt-2 flex flex-wrap gap-2">
+                <button
+                  v-for="modelOption in modelOptions"
+                  :key="modelOption.value"
+                  :class="[
+                    'rounded-lg border px-3 py-1.5 text-xs font-medium transition',
+                    config.model === modelOption.value
+                      ? 'border-blue-500 bg-blue-50 text-blue-700 dark:border-blue-400 dark:bg-blue-900/30 dark:text-blue-300'
+                      : 'border-gray-200 bg-gray-50 text-gray-600 hover:bg-gray-100 dark:border-gray-700 dark:bg-gray-800 dark:text-gray-400 dark:hover:bg-gray-700',
+                    !config.enabled && 'cursor-not-allowed opacity-50'
+                  ]"
+                  :disabled="!config.enabled"
+                  @click="config.model = modelOption.value"
+                >
+                  {{ modelOption.label }}
+                </button>
+              </div>
+            </div>
+
+            <!-- 测试历史 -->
+            <div v-if="testHistory.length > 0" class="mb-4">
+              <label class="mb-2 block text-sm font-medium text-gray-700 dark:text-gray-300">
+                最近测试记录
+              </label>
+              <div
+                class="max-h-40 space-y-2 overflow-y-auto rounded-lg border border-gray-200 bg-gray-50 p-3 dark:border-gray-700 dark:bg-gray-800/50"
+              >
+                <div
+                  v-for="(record, index) in testHistory"
+                  :key="index"
+                  class="flex items-center justify-between text-xs"
+                >
+                  <div class="flex items-center gap-2">
+                    <i
+                      :class="[
+                        'fas',
+                        record.success
+                          ? 'fa-check-circle text-green-500'
+                          : 'fa-times-circle text-red-500'
+                      ]"
+                    />
+                    <span class="text-gray-600 dark:text-gray-400">
+                      {{ formatTimestamp(record.timestamp) }}
+                    </span>
+                  </div>
+                  <span v-if="record.latencyMs" class="text-gray-500 dark:text-gray-500">
+                    {{ record.latencyMs }}ms
+                  </span>
+                  <span
+                    v-else-if="record.error"
+                    class="max-w-[150px] truncate text-red-500"
+                    :title="record.error"
+                  >
+                    {{ record.error }}
+                  </span>
+                </div>
+              </div>
+            </div>
+
+            <!-- 无历史记录 -->
+            <div
+              v-else
+              class="mb-4 rounded-lg border border-gray-200 bg-gray-50 p-4 text-center text-sm text-gray-500 dark:border-gray-700 dark:bg-gray-800/50 dark:text-gray-400"
+            >
+              <i class="fas fa-history mb-2 text-2xl text-gray-300 dark:text-gray-600" />
+              <p>暂无测试记录</p>
+            </div>
+          </template>
+        </div>
+
+        <!-- 底部操作栏 -->
+        <div
+          class="flex items-center justify-end gap-3 border-t border-gray-100 bg-gray-50/80 px-5 py-3 dark:border-gray-800 dark:bg-gray-900/50"
+        >
+          <button
+            class="rounded-lg border border-gray-200 bg-white px-4 py-2 text-sm font-medium text-gray-700 shadow-sm transition hover:bg-gray-50 hover:shadow dark:border-gray-700 dark:bg-gray-800 dark:text-gray-300 dark:hover:bg-gray-700"
+            :disabled="saving"
+            @click="handleClose"
+          >
+            取消
+          </button>
+          <button
+            :class="[
+              'flex items-center gap-2 rounded-lg px-4 py-2 text-sm font-medium shadow-sm transition',
+              saving
+                ? 'cursor-not-allowed bg-gray-200 text-gray-400 dark:bg-gray-700 dark:text-gray-500'
+                : 'bg-gradient-to-r from-blue-500 to-indigo-500 text-white hover:from-blue-600 hover:to-indigo-600 hover:shadow-md'
+            ]"
+            :disabled="saving || loading"
+            @click="saveConfig"
+          >
+            <i :class="['fas', saving ? 'fa-spinner fa-spin' : 'fa-save']" />
+            {{ saving ? '保存中...' : '保存配置' }}
+          </button>
+        </div>
+      </div>
+    </div>
+  </Teleport>
+</template>
+
+<script setup>
+import { ref, watch } from 'vue'
+import { API_PREFIX } from '@/config/api'
+import { showToast } from '@/utils/toast'
+
+const props = defineProps({
+  show: {
+    type: Boolean,
+    default: false
+  },
+  account: {
+    type: Object,
+    default: null
+  }
+})
+
+const emit = defineEmits(['close', 'saved'])
+
+// 状态
+const loading = ref(false)
+const saving = ref(false)
+const config = ref({
+  enabled: false,
+  cronExpression: '0 8 * * *',
+  model: 'claude-sonnet-4-5-20250929'
+})
+const testHistory = ref([])
+
+// Cron 预设选项
+const cronPresets = [
+  { label: '每天 8:00', value: '0 8 * * *' },
+  { label: '每天 12:00', value: '0 12 * * *' },
+  { label: '每天 18:00', value: '0 18 * * *' },
+  { label: '每6小时', value: '0 */6 * * *' },
+  { label: '每12小时', value: '0 */12 * * *' },
+  { label: '工作日 9:00', value: '0 9 * * 1-5' }
+]
+
+// 模型选项
+const modelOptions = [
+  { label: 'Claude Sonnet 4.5', value: 'claude-sonnet-4-5-20250929' },
+  { label: 'Claude Haiku 4.5', value: 'claude-haiku-4-5-20251001' },
+  { label: 'Claude Opus 4.5', value: 'claude-opus-4-5-20251101' }
+]
+
+// 格式化时间戳
+function formatTimestamp(timestamp) {
+  if (!timestamp) return '未知'
+  const date = new Date(timestamp)
+  return date.toLocaleString('zh-CN', {
+    month: '2-digit',
+    day: '2-digit',
+    hour: '2-digit',
+    minute: '2-digit'
+  })
+}
+
+// 加载配置
+async function loadConfig() {
+  if (!props.account) return
+
+  loading.value = true
+  try {
+    const authToken = localStorage.getItem('authToken')
+    const platform = props.account.platform
+
+    // 根据平台获取配置端点
+    let endpoint = ''
+    if (platform === 'claude') {
+      endpoint = `${API_PREFIX}/admin/claude-accounts/${props.account.id}/test-config`
+    } else {
+      // 其他平台暂不支持
+      loading.value = false
+      return
+    }
+
+    // 获取配置
+    const configRes = await fetch(endpoint, {
+      headers: {
+        Authorization: authToken ? `Bearer ${authToken}` : ''
+      }
+    })
+
+    if (configRes.ok) {
+      const data = await configRes.json()
+      if (data.success && data.data?.config) {
+        config.value = {
+          enabled: data.data.config.enabled || false,
+          cronExpression: data.data.config.cronExpression || '0 8 * * *',
+          model: data.data.config.model || 'claude-sonnet-4-5-20250929'
+        }
+      }
+    }
+
+    // 获取测试历史
+    const historyEndpoint = endpoint.replace('/test-config', '/test-history')
+    const historyRes = await fetch(historyEndpoint, {
+      headers: {
+        Authorization: authToken ? `Bearer ${authToken}` : ''
+      }
+    })
+
+    if (historyRes.ok) {
+      const historyData = await historyRes.json()
+      if (historyData.success && historyData.data?.history) {
+        testHistory.value = historyData.data.history
+      }
+    }
+  } catch (err) {
+    showToast('加载配置失败: ' + err.message, 'error')
+  } finally {
+    loading.value = false
+  }
+}
+
+// 保存配置
+async function saveConfig() {
+  if (!props.account) return
+
+  saving.value = true
+  try {
+    const authToken = localStorage.getItem('authToken')
+    const platform = props.account.platform
+
+    let endpoint = ''
+    if (platform === 'claude') {
+      endpoint = `${API_PREFIX}/admin/claude-accounts/${props.account.id}/test-config`
+    } else {
+      saving.value = false
+      return
+    }
+
+    const res = await fetch(endpoint, {
+      method: 'PUT',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: authToken ? `Bearer ${authToken}` : ''
+      },
+      body: JSON.stringify({
+        enabled: config.value.enabled,
+        cronExpression: config.value.cronExpression,
+        model: config.value.model
+      })
+    })
+
+    if (res.ok) {
+      showToast('配置已保存', 'success')
+      emit('saved')
+      handleClose()
+    } else {
+      const errorData = await res.json().catch(() => ({}))
+      showToast(errorData.message || '保存失败', 'error')
+    }
+  } catch (err) {
+    showToast('保存失败: ' + err.message, 'error')
+  } finally {
+    saving.value = false
+  }
+}
+
+// 关闭模态框
+function handleClose() {
+  if (saving.value) return
+  emit('close')
+}
+
+// 监听 show 变化，加载配置
+watch(
+  () => props.show,
+  (newVal) => {
+    if (newVal) {
+      config.value = {
+        enabled: false,
+        cronExpression: '0 8 * * *',
+        model: 'claude-sonnet-4-5-20250929'
+      }
+      testHistory.value = []
+      loadConfig()
+    }
+  }
+)
+</script>

web/admin-spa/src/components/accounts/AccountUsageDetailModal.vue

@@ -44,6 +44,13 @@
               </p>
             </div>
           </div>
+          <div class="flex items-center gap-2">
+            <button
+              class="flex items-center gap-2 rounded-full bg-purple-100 px-3 py-2 text-xs font-semibold text-purple-700 transition hover:bg-purple-200 dark:bg-purple-500/10 dark:text-purple-200 dark:hover:bg-purple-500/20"
+              @click="goTimeline"
+            >
+              <i class="fas fa-clock" /> 请求时间线
+            </button>
             <button
               class="flex h-10 w-10 items-center justify-center rounded-full bg-gray-100 text-gray-500 transition hover:bg-gray-200 hover:text-gray-700 dark:bg-gray-800 dark:text-gray-400 dark:hover:bg-gray-700 dark:hover:text-gray-200"
               @click="handleClose"
@@ -51,6 +58,7 @@
               <i class="fas fa-times" />
             </button>
           </div>
+        </div>
 
         <!-- 内容区域 -->
         <div class="flex-1 overflow-y-auto px-5 py-4 sm:px-6">
@@ -325,6 +333,7 @@
 
 <script setup>
 import { computed, nextTick, onUnmounted, ref, watch } from 'vue'
+import { useRouter } from 'vue-router'
 import { storeToRefs } from 'pinia'
 import Chart from 'chart.js/auto'
 import { useThemeStore } from '@/stores/theme'
@@ -343,6 +352,7 @@ const emit = defineEmits(['close'])
 
 const themeStore = useThemeStore()
 const { isDarkMode } = storeToRefs(themeStore)
+const router = useRouter()
 
 const chartCanvas = ref(null)
 let chartInstance = null
@@ -579,6 +589,14 @@ const handleClose = () => {
   emit('close')
 }
 
+const goTimeline = () => {
+  if (!props.account?.id) return
+  router.push({
+    path: `/accounts/${props.account.id}/usage-records`,
+    query: { platform: props.account.platform || props.account.accountType }
+  })
+}
+
 watch(
   () => props.show,
   (visible) => {

web/admin-spa/src/components/apikeys/RecordDetailModal.vue

@@ -0,0 +1,211 @@
+<template>
+  <el-dialog
+    :append-to-body="true"
+    class="record-detail-modal"
+    :close-on-click-modal="false"
+    :destroy-on-close="true"
+    :model-value="show"
+    :show-close="false"
+    top="10vh"
+    width="720px"
+    @close="emitClose"
+  >
+    <template #header>
+      <div class="flex items-center justify-between">
+        <div>
+          <p class="text-xs font-medium uppercase tracking-wide text-gray-500 dark:text-gray-400">
+            请求详情
+          </p>
+          <p class="text-lg font-bold text-gray-900 dark:text-gray-100">
+            {{ record?.model || '未知模型' }}
+          </p>
+        </div>
+        <button
+          aria-label="关闭"
+          class="rounded-full p-2 text-gray-500 transition hover:bg-gray-100 hover:text-gray-700 dark:text-gray-300 dark:hover:bg-gray-800 dark:hover:text-gray-100"
+          @click="emitClose"
+        >
+          <i class="fas fa-times" />
+        </button>
+      </div>
+    </template>
+
+    <div class="space-y-4">
+      <div class="grid gap-3 md:grid-cols-2">
+        <div
+          class="rounded-lg border border-gray-200 bg-gray-50 p-4 dark:border-gray-800 dark:bg-gray-900"
+        >
+          <h4 class="mb-3 text-sm font-semibold text-gray-800 dark:text-gray-200">基本信息</h4>
+          <ul class="space-y-2 text-sm text-gray-700 dark:text-gray-300">
+            <li class="flex items-center justify-between">
+              <span class="text-gray-500 dark:text-gray-400">时间</span>
+              <span class="font-medium">{{ formattedTime }}</span>
+            </li>
+            <li class="flex items-center justify-between">
+              <span class="text-gray-500 dark:text-gray-400">模型</span>
+              <span class="font-medium">{{ record?.model || '未知模型' }}</span>
+            </li>
+            <li class="flex items-center justify-between">
+              <span class="text-gray-500 dark:text-gray-400">账户</span>
+              <span class="font-medium">{{ record?.accountName || '未知账户' }}</span>
+            </li>
+            <li class="flex items-center justify-between">
+              <span class="text-gray-500 dark:text-gray-400">渠道</span>
+              <span class="font-medium">{{ record?.accountTypeName || '未知渠道' }}</span>
+            </li>
+          </ul>
+        </div>
+
+        <div
+          class="rounded-lg border border-gray-200 bg-gray-50 p-4 dark:border-gray-800 dark:bg-gray-900"
+        >
+          <h4 class="mb-3 text-sm font-semibold text-gray-800 dark:text-gray-200">Token 使用</h4>
+          <ul class="space-y-2 text-sm text-gray-700 dark:text-gray-300">
+            <li class="flex items-center justify-between">
+              <span class="text-gray-500 dark:text-gray-400">输入 Token</span>
+              <span class="font-semibold text-blue-600 dark:text-blue-400">
+                {{ formatNumber(record?.inputTokens) }}
+              </span>
+            </li>
+            <li class="flex items-center justify-between">
+              <span class="text-gray-500 dark:text-gray-400">输出 Token</span>
+              <span class="font-semibold text-green-600 dark:text-green-400">
+                {{ formatNumber(record?.outputTokens) }}
+              </span>
+            </li>
+            <li class="flex items-center justify-between">
+              <span class="text-gray-500 dark:text-gray-400">缓存创建</span>
+              <span class="font-semibold text-purple-600 dark:text-purple-400">
+                {{ formatNumber(record?.cacheCreateTokens) }}
+              </span>
+            </li>
+            <li class="flex items-center justify-between">
+              <span class="text-gray-500 dark:text-gray-400">缓存读取</span>
+              <span class="font-semibold text-orange-600 dark:text-orange-400">
+                {{ formatNumber(record?.cacheReadTokens) }}
+              </span>
+            </li>
+            <li class="flex items-center justify-between">
+              <span class="text-gray-500 dark:text-gray-400">总计</span>
+              <span class="font-semibold text-gray-900 dark:text-gray-100">
+                {{ formatNumber(record?.totalTokens) }}
+              </span>
+            </li>
+          </ul>
+        </div>
+      </div>
+
+      <div
+        class="rounded-lg border border-gray-200 bg-white p-4 dark:border-gray-800 dark:bg-gray-900"
+      >
+        <h4 class="mb-3 text-sm font-semibold text-gray-800 dark:text-gray-200">费用详情</h4>
+        <div class="grid gap-3 sm:grid-cols-2">
+          <div
+            class="flex items-center justify-between rounded-md bg-gray-50 px-3 py-2 dark:bg-gray-800"
+          >
+            <span class="text-sm text-gray-500 dark:text-gray-400">输入费用</span>
+            <span class="text-sm font-semibold text-gray-900 dark:text-gray-100">
+              {{ formattedCosts.input }}
+            </span>
+          </div>
+          <div
+            class="flex items-center justify-between rounded-md bg-gray-50 px-3 py-2 dark:bg-gray-800"
+          >
+            <span class="text-sm text-gray-500 dark:text-gray-400">输出费用</span>
+            <span class="text-sm font-semibold text-gray-900 dark:text-gray-100">
+              {{ formattedCosts.output }}
+            </span>
+          </div>
+          <div
+            class="flex items-center justify-between rounded-md bg-gray-50 px-3 py-2 dark:bg-gray-800"
+          >
+            <span class="text-sm text-gray-500 dark:text-gray-400">缓存创建</span>
+            <span class="text-sm font-semibold text-gray-900 dark:text-gray-100">
+              {{ formattedCosts.cacheCreate }}
+            </span>
+          </div>
+          <div
+            class="flex items-center justify-between rounded-md bg-gray-50 px-3 py-2 dark:bg-gray-800"
+          >
+            <span class="text-sm text-gray-500 dark:text-gray-400">缓存读取</span>
+            <span class="text-sm font-semibold text-gray-900 dark:text-gray-100">
+              {{ formattedCosts.cacheRead }}
+            </span>
+          </div>
+        </div>
+        <div
+          class="mt-4 flex items-center justify-between rounded-md border border-gray-200 bg-gray-50 px-4 py-3 dark:border-gray-800 dark:bg-gray-800"
+        >
+          <span class="text-sm font-semibold text-gray-700 dark:text-gray-200">总费用</span>
+          <div class="text-base font-bold text-yellow-600 dark:text-yellow-400">
+            {{ record?.costFormatted || formattedCosts.total }}
+          </div>
+        </div>
+      </div>
+    </div>
+
+    <template #footer>
+      <div class="flex justify-end">
+        <el-button type="primary" @click="emitClose">关闭</el-button>
+      </div>
+    </template>
+  </el-dialog>
+</template>
+
+<script setup>
+import { computed } from 'vue'
+import dayjs from 'dayjs'
+import { formatNumber } from '@/utils/format'
+
+const props = defineProps({
+  show: {
+    type: Boolean,
+    default: false
+  },
+  record: {
+    type: Object,
+    default: () => ({})
+  }
+})
+
+const emit = defineEmits(['close'])
+const emitClose = () => emit('close')
+
+const formattedTime = computed(() => {
+  if (!props.record?.timestamp) return '未知时间'
+  return dayjs(props.record.timestamp).format('YYYY-MM-DD HH:mm:ss')
+})
+
+const formattedCosts = computed(() => {
+  const breakdown = props.record?.costBreakdown || {}
+  const formatValue = (value) => {
+    const num = typeof value === 'number' ? value : 0
+    if (num >= 1) return `$${num.toFixed(2)}`
+    if (num >= 0.001) return `$${num.toFixed(4)}`
+    return `$${num.toFixed(6)}`
+  }
+
+  return {
+    input: formatValue(breakdown.input),
+    output: formatValue(breakdown.output),
+    cacheCreate: formatValue(breakdown.cacheCreate),
+    cacheRead: formatValue(breakdown.cacheRead),
+    total: formatValue(breakdown.total)
+  }
+})
+</script>
+
+<style scoped>
+.record-detail-modal :deep(.el-dialog__header) {
+  margin: 0;
+  padding: 16px 16px 0;
+}
+
+.record-detail-modal :deep(.el-dialog__body) {
+  padding: 12px 16px 4px;
+}
+
+.record-detail-modal :deep(.el-dialog__footer) {
+  padding: 8px 16px 16px;
+}
+</style>

web/admin-spa/src/components/apikeys/UsageDetailModal.vue

@@ -231,6 +231,9 @@
 
         <!-- 底部按钮 -->
         <div class="mt-4 flex justify-end gap-2 sm:mt-6 sm:gap-3">
+          <button class="btn btn-primary px-4 py-2 text-sm" type="button" @click="openTimeline">
+            查看请求时间线
+          </button>
           <button class="btn btn-secondary px-4 py-2 text-sm" type="button" @click="close">
             关闭
           </button>
@@ -256,7 +259,7 @@ const props = defineProps({
   }
 })
 
-const emit = defineEmits(['close'])
+const emit = defineEmits(['close', 'open-timeline'])
 
 // 计算属性
 const totalRequests = computed(() => props.apiKey.usage?.total?.requests || 0)
@@ -320,6 +323,10 @@ const formatTokenCount = (count) => {
 const close = () => {
   emit('close')
 }
+
+const openTimeline = () => {
+  emit('open-timeline', props.apiKey?.id)
+}
 </script>
 
 <style scoped>

web/admin-spa/src/components/apistats/LimitConfig.vue

@@ -284,7 +284,7 @@
     </div>
 
     <!-- 详细限制信息 -->
-    <div v-if="hasModelRestrictions" class="card p-4 md:p-6">
+    <div v-if="hasModelRestrictions" class="card !overflow-visible p-4 md:p-6">
       <h3
         class="mb-3 flex items-center text-lg font-bold text-gray-900 dark:text-gray-100 md:mb-4 md:text-xl"
       >
@@ -301,7 +301,7 @@
           <i class="fas fa-robot mr-1 text-xs md:mr-2 md:text-sm" />
           受限模型列表
         </h4>
-        <div class="space-y-1 md:space-y-2">
+        <div class="max-h-64 space-y-1 overflow-y-auto pr-1 md:max-h-80 md:space-y-2">
           <div
             v-for="model in statsData.restrictions.restrictedModels"
             :key="model"

web/admin-spa/src/components/common/ActionDropdown.vue

@@ -77,7 +77,21 @@ const getActionClass = (action) => {
   return colorMap[action.color] || colorMap.gray
 }
 
+const instanceId = Symbol('action-dropdown')
+const handleGlobalOpen = (event) => {
+  if (event?.detail?.id !== instanceId) {
+    closeDropdown()
+  }
+}
+
 const toggleDropdown = async () => {
+  if (!isOpen.value) {
+    window.dispatchEvent(
+      new CustomEvent('action-dropdown-open', {
+        detail: { id: instanceId }
+      })
+    )
+  }
   isOpen.value = !isOpen.value
   if (isOpen.value) {
     await nextTick()
@@ -102,7 +116,8 @@ const updateDropdownPosition = () => {
 
   const trigger = triggerRef.value.getBoundingClientRect()
   const dropdownHeight = 200 // 预估高度
-  const dropdownWidth = 160 // 预估宽度
+  const dropdownWidth = 180 // 预估宽度，略大以减少遮挡
+  const gap = 8
   const spaceBelow = window.innerHeight - trigger.bottom
   const spaceAbove = trigger.top
   const spaceRight = window.innerWidth - trigger.right
@@ -112,16 +127,16 @@ const updateDropdownPosition = () => {
 
   // 计算垂直位置
   if (spaceBelow >= dropdownHeight || spaceBelow >= spaceAbove) {
-    top = trigger.bottom + 4
+    top = trigger.bottom + gap
   } else {
-    top = trigger.top - dropdownHeight - 4
+    top = trigger.top - dropdownHeight - gap
   }
 
-  // 计算水平位置 - 优先显示在左侧（因为按钮在右侧固定列）
+  // 计算水平位置 - 优先向右展开，避免遮挡左侧内容
-  if (spaceLeft >= dropdownWidth) {
+  if (spaceRight >= dropdownWidth + gap) {
-    left = trigger.left - dropdownWidth + trigger.width
+    left = trigger.right + gap
-  } else if (spaceRight >= dropdownWidth) {
+  } else if (spaceLeft >= dropdownWidth + gap) {
-    left = trigger.left
+    left = trigger.left - dropdownWidth - gap + trigger.width
   } else {
     left = window.innerWidth - dropdownWidth - 10
   }
@@ -164,11 +179,13 @@ onMounted(() => {
   window.addEventListener('scroll', handleScroll, true)
   window.addEventListener('resize', handleResize)
   document.addEventListener('click', handleClickOutside)
+  window.addEventListener('action-dropdown-open', handleGlobalOpen)
 })
 
 onBeforeUnmount(() => {
   window.removeEventListener('scroll', handleScroll, true)
   window.removeEventListener('resize', handleResize)
   document.removeEventListener('click', handleClickOutside)
+  window.removeEventListener('action-dropdown-open', handleGlobalOpen)
 })
 </script>

web/admin-spa/src/components/common/CustomDropdown.vue

@@ -41,19 +41,25 @@
             <div
               v-for="option in options"
               :key="option.value"
-              class="flex cursor-pointer items-center gap-2 whitespace-nowrap px-3 py-2 text-sm transition-colors duration-150"
+              class="flex cursor-pointer items-center gap-2 whitespace-nowrap py-2 text-sm transition-colors duration-150"
               :class="[
-                option.value === modelValue
+                isSelected(option.value)
                   ? 'bg-blue-50 font-medium text-blue-700 dark:bg-blue-900/30 dark:text-blue-400'
+                  : option.isGroup
+                    ? 'bg-gray-50 font-semibold text-gray-800 dark:bg-gray-700/50 dark:text-gray-200'
                     : 'text-gray-700 hover:bg-gray-50 dark:text-gray-300 dark:hover:bg-gray-700'
               ]"
+              :style="{
+                paddingLeft: option.indent ? `${12 + option.indent * 16}px` : '12px',
+                paddingRight: '12px'
+              }"
               @click="selectOption(option)"
             >
               <i v-if="option.icon" :class="['fas', option.icon, 'text-xs']"></i>
               <span>{{ option.label }}</span>
               <i
-                v-if="option.value === modelValue"
+                v-if="isSelected(option.value)"
-                class="fas fa-check ml-auto pl-3 text-xs text-blue-600"
+                class="fas fa-check ml-auto pl-3 text-xs text-blue-600 dark:text-blue-400"
               ></i>
             </div>
           </div>
@@ -68,7 +74,7 @@ import { ref, computed, onMounted, onBeforeUnmount, nextTick } from 'vue'
 
 const props = defineProps({
   modelValue: {
-    type: [String, Number],
+    type: [String, Number, Array],
     default: ''
   },
   options: {
@@ -86,6 +92,10 @@ const props = defineProps({
   iconColor: {
     type: String,
     default: 'text-gray-500'
+  },
+  multiple: {
+    type: Boolean,
+    default: false
   }
 })
 
@@ -96,7 +106,18 @@ const triggerRef = ref(null)
 const dropdownRef = ref(null)
 const dropdownStyle = ref({})
 
+const isSelected = (value) => {
+  if (props.multiple) {
+    return Array.isArray(props.modelValue) && props.modelValue.includes(value)
+  }
+  return props.modelValue === value
+}
+
 const selectedLabel = computed(() => {
+  if (props.multiple) {
+    const count = Array.isArray(props.modelValue) ? props.modelValue.length : 0
+    return count > 0 ? `已选 ${count} 个` : ''
+  }
   const selected = props.options.find((opt) => opt.value === props.modelValue)
   return selected ? selected.label : ''
 })
@@ -114,9 +135,21 @@ const closeDropdown = () => {
 }
 
 const selectOption = (option) => {
+  if (props.multiple) {
+    const current = Array.isArray(props.modelValue) ? [...props.modelValue] : []
+    const idx = current.indexOf(option.value)
+    if (idx >= 0) {
+      current.splice(idx, 1)
+    } else {
+      current.push(option.value)
+    }
+    emit('update:modelValue', current)
+    emit('change', current)
+  } else {
     emit('update:modelValue', option.value)
     emit('change', option.value)
     closeDropdown()
+  }
 }
 
 const updateDropdownPosition = () => {

web/admin-spa/src/router/index.js

@@ -11,7 +11,9 @@ const UserManagementView = () => import('@/views/UserManagementView.vue')
 const MainLayout = () => import('@/components/layout/MainLayout.vue')
 const DashboardView = () => import('@/views/DashboardView.vue')
 const ApiKeysView = () => import('@/views/ApiKeysView.vue')
+const ApiKeyUsageRecordsView = () => import('@/views/ApiKeyUsageRecordsView.vue')
 const AccountsView = () => import('@/views/AccountsView.vue')
+const AccountUsageRecordsView = () => import('@/views/AccountUsageRecordsView.vue')
 const TutorialView = () => import('@/views/TutorialView.vue')
 const SettingsView = () => import('@/views/SettingsView.vue')
 const ApiStatsView = () => import('@/views/ApiStatsView.vue')
@@ -85,6 +87,18 @@ const routes = [
       }
     ]
   },
+  {
+    path: '/api-keys/:keyId/usage-records',
+    component: MainLayout,
+    meta: { requiresAuth: true },
+    children: [
+      {
+        path: '',
+        name: 'ApiKeyUsageRecords',
+        component: ApiKeyUsageRecordsView
+      }
+    ]
+  },
   {
     path: '/accounts',
     component: MainLayout,
@@ -97,6 +111,18 @@ const routes = [
       }
     ]
   },
+  {
+    path: '/accounts/:accountId/usage-records',
+    component: MainLayout,
+    meta: { requiresAuth: true },
+    children: [
+      {
+        path: '',
+        name: 'AccountUsageRecords',
+        component: AccountUsageRecordsView
+      }
+    ]
+  },
   {
     path: '/tutorial',
     component: MainLayout,

web/admin-spa/src/stores/dashboard.js

@@ -67,22 +67,72 @@ export const useDashboardStore = defineStore('dashboard', () => {
     groupLabel: 'Claude账户'
   })
 
-  // 日期筛选
+  // 本地偏好
-  const dateFilter = ref({
+  const STORAGE_KEYS = {
-    type: 'preset', // preset 或 custom
+    preset: 'dashboard:date:preset',
-    preset: '7days', // today, 7days, 30days
+    granularity: 'dashboard:trend:granularity'
-    customStart: '',
+  }
-    customEnd: '',
+  const defaultPreset = 'today'
-    customRange: null,
+  const defaultGranularity = 'day'
-    presetOptions: [
+
+  const getPresetOptions = (granularity) =>
+    granularity === 'hour'
+      ? [
+          { value: 'last24h', label: '近24小时', hours: 24 },
+          { value: 'yesterday', label: '昨天', hours: 24 },
+          { value: 'dayBefore', label: '前天', hours: 24 }
+        ]
+      : [
           { value: 'today', label: '今日', days: 1 },
           { value: '7days', label: '7天', days: 7 },
           { value: '30days', label: '30天', days: 30 }
         ]
+
+  const readFromStorage = (key, fallback) => {
+    try {
+      const value = localStorage.getItem(key)
+      return value || fallback
+    } catch (error) {
+      return fallback
+    }
+  }
+
+  const saveToStorage = (key, value) => {
+    try {
+      localStorage.setItem(key, value)
+    } catch (error) {
+      // 忽略存储错误，避免影响渲染
+    }
+  }
+
+  const normalizePresetForGranularity = (preset, granularity) => {
+    const options = getPresetOptions(granularity)
+    const hasPreset = options.some((opt) => opt.value === preset)
+    if (hasPreset) return preset
+    return granularity === 'hour' ? 'last24h' : defaultPreset
+  }
+
+  const storedGranularity = readFromStorage(STORAGE_KEYS.granularity, defaultGranularity)
+  const initialGranularity = ['day', 'hour'].includes(storedGranularity)
+    ? storedGranularity
+    : defaultGranularity
+  const initialPreset = normalizePresetForGranularity(
+    readFromStorage(STORAGE_KEYS.preset, defaultPreset),
+    initialGranularity
+  )
+
+  // 日期筛选
+  const dateFilter = ref({
+    type: 'preset', // preset 或 custom
+    preset: initialPreset, // today, 7days, 30days
+    customStart: '',
+    customEnd: '',
+    customRange: null,
+    presetOptions: getPresetOptions(initialGranularity)
   })
 
   // 趋势图粒度
-  const trendGranularity = ref('day') // 'day' 或 'hour'
+  const trendGranularity = ref(initialGranularity) // 'day' 或 'hour'
   const apiKeysTrendMetric = ref('requests') // 'requests' 或 'tokens'
   const accountUsageGroup = ref('claude') // claude | openai | gemini
 
@@ -138,6 +188,21 @@ export const useDashboardStore = defineStore('dashboard', () => {
     }
   }
 
+  const persistDatePreferences = (
+    preset = dateFilter.value.preset,
+    granularity = trendGranularity.value
+  ) => {
+    saveToStorage(STORAGE_KEYS.preset, preset)
+    saveToStorage(STORAGE_KEYS.granularity, granularity)
+  }
+
+  const getEffectiveGranularity = () =>
+    dateFilter.value.type === 'preset' &&
+    dateFilter.value.preset === 'today' &&
+    trendGranularity.value === 'day'
+      ? 'hour'
+      : trendGranularity.value
+
   // 方法
   async function loadDashboardData(timeRange = null) {
     loading.value = true
@@ -232,7 +297,7 @@ export const useDashboardStore = defineStore('dashboard', () => {
     }
   }
 
-  async function loadUsageTrend(days = 7, granularity = 'day') {
+  async function loadUsageTrend(days = 7, granularity = getEffectiveGranularity()) {
     try {
       let url = '/admin/usage-trend?'
 
@@ -241,26 +306,9 @@ export const useDashboardStore = defineStore('dashboard', () => {
         url += `granularity=hour`
 
         if (dateFilter.value.customRange && dateFilter.value.customRange.length === 2) {
-          // 使用自定义时间范围 - 需要将系统时区时间转换为UTC
+          // 使用自定义时间范围 - 直接按系统时区字符串传递，避免额外时区偏移导致窗口错位
-          const convertToUTC = (systemTzTimeStr) => {
+          url += `&startDate=${encodeURIComponent(dateFilter.value.customRange[0])}`
-            // 固定使用UTC+8，因为后端系统时区是UTC+8
+          url += `&endDate=${encodeURIComponent(dateFilter.value.customRange[1])}`
-            const systemTz = 8
-            // 解析系统时区时间字符串
-            const [datePart, timePart] = systemTzTimeStr.split(' ')
-            const [year, month, day] = datePart.split('-').map(Number)
-            const [hours, minutes, seconds] = timePart.split(':').map(Number)
-
-            // 创建UTC时间，使其在系统时区显示为用户选择的时间
-            // 例如：用户选择 UTC+8 的 2025-07-25 00:00:00
-            // 对应的UTC时间是 2025-07-24 16:00:00
-            const utcDate = new Date(
-              Date.UTC(year, month - 1, day, hours - systemTz, minutes, seconds)
-            )
-            return utcDate.toISOString()
-          }
-
-          url += `&startDate=${encodeURIComponent(convertToUTC(dateFilter.value.customRange[0]))}`
-          url += `&endDate=${encodeURIComponent(convertToUTC(dateFilter.value.customRange[1]))}`
         } else {
           // 使用预设计算时间范围，与loadApiKeysTrend保持一致
           const now = new Date()
@@ -268,6 +316,12 @@ export const useDashboardStore = defineStore('dashboard', () => {
 
           if (dateFilter.value.type === 'preset') {
             switch (dateFilter.value.preset) {
+              case 'today': {
+                // 今日：使用系统时区的当日0点-23:59
+                startTime = getSystemTimezoneDay(now, true)
+                endTime = getSystemTimezoneDay(now, false)
+                break
+              }
               case 'last24h': {
                 // 近24小时：从当前时间往前推24小时
                 endTime = new Date(now)
@@ -318,34 +372,28 @@ export const useDashboardStore = defineStore('dashboard', () => {
     }
   }
 
-  async function loadModelStats(period = 'daily') {
+  async function loadModelStats(period = 'daily', granularity = null) {
+    const currentGranularity = granularity || getEffectiveGranularity()
     try {
       let url = `/admin/model-stats?period=${period}`
 
       // 如果是自定义时间范围或小时粒度，传递具体的时间参数
-      if (dateFilter.value.type === 'custom' || trendGranularity.value === 'hour') {
+      if (dateFilter.value.type === 'custom' || currentGranularity === 'hour') {
         if (dateFilter.value.customRange && dateFilter.value.customRange.length === 2) {
-          // 将系统时区时间转换为UTC
+          // 按系统时区字符串直传，避免额外时区转换
-          const convertToUTC = (systemTzTimeStr) => {
+          url += `&startDate=${encodeURIComponent(dateFilter.value.customRange[0])}`
-            const systemTz = 8
+          url += `&endDate=${encodeURIComponent(dateFilter.value.customRange[1])}`
-            const [datePart, timePart] = systemTzTimeStr.split(' ')
+        } else if (currentGranularity === 'hour' && dateFilter.value.type === 'preset') {
-            const [year, month, day] = datePart.split('-').map(Number)
-            const [hours, minutes, seconds] = timePart.split(':').map(Number)
-
-            const utcDate = new Date(
-              Date.UTC(year, month - 1, day, hours - systemTz, minutes, seconds)
-            )
-            return utcDate.toISOString()
-          }
-
-          url += `&startDate=${encodeURIComponent(convertToUTC(dateFilter.value.customRange[0]))}`
-          url += `&endDate=${encodeURIComponent(convertToUTC(dateFilter.value.customRange[1]))}`
-        } else if (trendGranularity.value === 'hour' && dateFilter.value.type === 'preset') {
           // 小时粒度的预设时间范围
           const now = new Date()
           let startTime, endTime
 
           switch (dateFilter.value.preset) {
+            case 'today': {
+              startTime = getSystemTimezoneDay(now, true)
+              endTime = getSystemTimezoneDay(now, false)
+              break
+            }
             case 'last24h': {
               endTime = new Date(now)
               startTime = new Date(now.getTime() - 24 * 60 * 60 * 1000)
@@ -374,7 +422,7 @@ export const useDashboardStore = defineStore('dashboard', () => {
           url += `&startDate=${encodeURIComponent(startTime.toISOString())}`
           url += `&endDate=${encodeURIComponent(endTime.toISOString())}`
         }
-      } else if (dateFilter.value.type === 'preset' && trendGranularity.value === 'day') {
+      } else if (dateFilter.value.type === 'preset' && currentGranularity === 'day') {
         // 天粒度的预设时间范围，需要传递startDate和endDate参数
         const now = new Date()
         let startDate, endDate
@@ -409,36 +457,20 @@ export const useDashboardStore = defineStore('dashboard', () => {
     }
   }
 
-  async function loadApiKeysTrend(metric = 'requests') {
+  async function loadApiKeysTrend(metric = 'requests', granularity = null) {
+    const currentGranularity = granularity || getEffectiveGranularity()
     try {
       let url = '/admin/api-keys-usage-trend?'
       let days = 7
 
-      if (trendGranularity.value === 'hour') {
+      if (currentGranularity === 'hour') {
         // 小时粒度，计算时间范围
         url += `granularity=hour`
 
         if (dateFilter.value.customRange && dateFilter.value.customRange.length === 2) {
-          // 使用自定义时间范围 - 需要将系统时区时间转换为UTC
+          // 使用自定义时间范围 - 按系统时区字符串直传
-          const convertToUTC = (systemTzTimeStr) => {
+          url += `&startDate=${encodeURIComponent(dateFilter.value.customRange[0])}`
-            // 固定使用UTC+8，因为后端系统时区是UTC+8
+          url += `&endDate=${encodeURIComponent(dateFilter.value.customRange[1])}`
-            const systemTz = 8
-            // 解析系统时区时间字符串
-            const [datePart, timePart] = systemTzTimeStr.split(' ')
-            const [year, month, day] = datePart.split('-').map(Number)
-            const [hours, minutes, seconds] = timePart.split(':').map(Number)
-
-            // 创建UTC时间，使其在系统时区显示为用户选择的时间
-            // 例如：用户选择 UTC+8 的 2025-07-25 00:00:00
-            // 对应的UTC时间是 2025-07-24 16:00:00
-            const utcDate = new Date(
-              Date.UTC(year, month - 1, day, hours - systemTz, minutes, seconds)
-            )
-            return utcDate.toISOString()
-          }
-
-          url += `&startDate=${encodeURIComponent(convertToUTC(dateFilter.value.customRange[0]))}`
-          url += `&endDate=${encodeURIComponent(convertToUTC(dateFilter.value.customRange[1]))}`
         } else {
           // 使用预设计算时间范围，与setDateFilterPreset保持一致
           const now = new Date()
@@ -446,6 +478,11 @@ export const useDashboardStore = defineStore('dashboard', () => {
 
           if (dateFilter.value.type === 'preset') {
             switch (dateFilter.value.preset) {
+              case 'today': {
+                startTime = getSystemTimezoneDay(now, true)
+                endTime = getSystemTimezoneDay(now, false)
+                break
+              }
               case 'last24h': {
                 // 近24小时：从当前时间往前推24小时
                 endTime = new Date(now)
@@ -511,29 +548,18 @@ export const useDashboardStore = defineStore('dashboard', () => {
     }
   }
 
-  async function loadAccountUsageTrend(group = accountUsageGroup.value) {
+  async function loadAccountUsageTrend(group = accountUsageGroup.value, granularity = null) {
+    const currentGranularity = granularity || getEffectiveGranularity()
     try {
       let url = '/admin/account-usage-trend?'
       let days = 7
 
-      if (trendGranularity.value === 'hour') {
+      if (currentGranularity === 'hour') {
         url += `granularity=hour`
 
         if (dateFilter.value.customRange && dateFilter.value.customRange.length === 2) {
-          const convertToUTC = (systemTzTimeStr) => {
+          url += `&startDate=${encodeURIComponent(dateFilter.value.customRange[0])}`
-            const systemTz = 8
+          url += `&endDate=${encodeURIComponent(dateFilter.value.customRange[1])}`
-            const [datePart, timePart] = systemTzTimeStr.split(' ')
-            const [year, month, day] = datePart.split('-').map(Number)
-            const [hours, minutes, seconds] = timePart.split(':').map(Number)
-
-            const utcDate = new Date(
-              Date.UTC(year, month - 1, day, hours - systemTz, minutes, seconds)
-            )
-            return utcDate.toISOString()
-          }
-
-          url += `&startDate=${encodeURIComponent(convertToUTC(dateFilter.value.customRange[0]))}`
-          url += `&endDate=${encodeURIComponent(convertToUTC(dateFilter.value.customRange[1]))}`
         } else {
           const now = new Date()
           let startTime
@@ -541,6 +567,11 @@ export const useDashboardStore = defineStore('dashboard', () => {
 
           if (dateFilter.value.type === 'preset') {
             switch (dateFilter.value.preset) {
+              case 'today': {
+                startTime = getSystemTimezoneDay(now, true)
+                endTime = getSystemTimezoneDay(now, false)
+                break
+              }
               case 'last24h': {
                 endTime = new Date(now)
                 startTime = new Date(now.getTime() - 24 * 60 * 60 * 1000)
@@ -603,111 +634,88 @@ export const useDashboardStore = defineStore('dashboard', () => {
   }
 
   // 日期筛选相关方法
-  function setDateFilterPreset(preset) {
+  function setDateFilterPreset(preset, options = {}) {
-    dateFilter.value.type = 'preset'
+    const { silent = false, skipSave = false } = options
-    dateFilter.value.preset = preset
+    const normalizedPreset = normalizePresetForGranularity(preset, trendGranularity.value)
 
-    // 根据预设计算并设置具体的日期范围
+    dateFilter.value.type = 'preset'
-    const option = dateFilter.value.presetOptions.find((opt) => opt.value === preset)
+    dateFilter.value.preset = normalizedPreset
-    if (option) {
+
+    const option = dateFilter.value.presetOptions.find((opt) => opt.value === normalizedPreset)
     const now = new Date()
-      let startDate, endDate
+    let startDate
+    let endDate
 
     if (trendGranularity.value === 'hour') {
-        // 小时粒度的预设
+      switch (normalizedPreset) {
-        switch (preset) {
+        case 'today': {
+          startDate = getSystemTimezoneDay(now, true)
+          endDate = getSystemTimezoneDay(now, false)
+          break
+        }
         case 'last24h': {
-            // 近24小时：从当前时间往前推24小时
           endDate = new Date(now)
           startDate = new Date(now.getTime() - 24 * 60 * 60 * 1000)
           break
         }
         case 'yesterday': {
-            // 昨天：获取本地时间的昨天
           const yesterday = new Date()
           yesterday.setDate(yesterday.getDate() - 1)
-            // 转换为系统时区的昨天0点和23:59
           startDate = getSystemTimezoneDay(yesterday, true)
           endDate = getSystemTimezoneDay(yesterday, false)
           break
         }
         case 'dayBefore': {
-            // 前天：获取本地时间的前天
           const dayBefore = new Date()
           dayBefore.setDate(dayBefore.getDate() - 2)
-            // 转换为系统时区的前天0点和23:59
           startDate = getSystemTimezoneDay(dayBefore, true)
           endDate = getSystemTimezoneDay(dayBefore, false)
           break
         }
+        default: {
+          endDate = new Date(now)
+          startDate = new Date(now.getTime() - 24 * 60 * 60 * 1000)
+        }
       }
     } else {
-        // 天粒度的预设
       startDate = new Date(now)
       endDate = new Date(now)
 
-        if (preset === 'today') {
+      if (normalizedPreset === 'today') {
-          // 今日：从凌晨开始
         startDate.setHours(0, 0, 0, 0)
         endDate.setHours(23, 59, 59, 999)
-        } else {
+      } else if (option?.days) {
-          // 其他预设：按天数计算
         startDate.setDate(now.getDate() - (option.days - 1))
         startDate.setHours(0, 0, 0, 0)
         endDate.setHours(23, 59, 59, 999)
       }
     }
 
-      dateFilter.value.customStart = startDate.toISOString().split('T')[0]
-      dateFilter.value.customEnd = endDate.toISOString().split('T')[0]
-
-      // 设置 customRange 为 Element Plus 需要的格式
-      // 对于小时粒度的昨天/前天，需要特殊处理显示
-      if (trendGranularity.value === 'hour' && (preset === 'yesterday' || preset === 'dayBefore')) {
-        // 获取本地日期
-        const targetDate = new Date()
-        if (preset === 'yesterday') {
-          targetDate.setDate(targetDate.getDate() - 1)
-        } else {
-          targetDate.setDate(targetDate.getDate() - 2)
-        }
-
-        // 显示系统时区的完整一天
-        const year = targetDate.getFullYear()
-        const month = String(targetDate.getMonth() + 1).padStart(2, '0')
-        const day = String(targetDate.getDate()).padStart(2, '0')
-
-        dateFilter.value.customRange = [
-          `${year}-${month}-${day} 00:00:00`,
-          `${year}-${month}-${day} 23:59:59`
-        ]
-      } else {
-        // 其他情况：近24小时或天粒度
     const formatDateForDisplay = (date) => {
-          // 固定使用UTC+8来显示时间
+      // 使用本地时间直接格式化，避免多余的时区偏移导致日期错位
-          const systemTz = 8
+      const localTime = new Date(date)
-          const tzOffset = systemTz * 60 * 60 * 1000
+      const year = localTime.getFullYear()
-          const localTime = new Date(date.getTime() + tzOffset)
+      const month = String(localTime.getMonth() + 1).padStart(2, '0')
-
+      const day = String(localTime.getDate()).padStart(2, '0')
-          const year = localTime.getUTCFullYear()
+      const hours = String(localTime.getHours()).padStart(2, '0')
-          const month = String(localTime.getUTCMonth() + 1).padStart(2, '0')
+      const minutes = String(localTime.getMinutes()).padStart(2, '0')
-          const day = String(localTime.getUTCDate()).padStart(2, '0')
+      const seconds = String(localTime.getSeconds()).padStart(2, '0')
-          const hours = String(localTime.getUTCHours()).padStart(2, '0')
-          const minutes = String(localTime.getUTCMinutes()).padStart(2, '0')
-          const seconds = String(localTime.getUTCSeconds()).padStart(2, '0')
       return `${year}-${month}-${day} ${hours}:${minutes}:${seconds}`
     }
 
-        dateFilter.value.customRange = [
+    dateFilter.value.customStart = startDate ? startDate.toISOString().split('T')[0] : ''
-          formatDateForDisplay(startDate),
+    dateFilter.value.customEnd = endDate ? endDate.toISOString().split('T')[0] : ''
-          formatDateForDisplay(endDate)
+    dateFilter.value.customRange =
-        ]
+      startDate && endDate ? [formatDateForDisplay(startDate), formatDateForDisplay(endDate)] : null
-      }
+
+    if (!skipSave) {
+      persistDatePreferences(dateFilter.value.preset, trendGranularity.value)
     }
 
-    // 触发数据刷新
+    if (!silent) {
       refreshChartsData()
     }
+  }
 
   function onCustomDateRangeChange(value) {
     if (value && value.length === 2) {
@@ -751,20 +759,17 @@ export const useDashboardStore = defineStore('dashboard', () => {
       refreshChartsData()
     } else if (value === null) {
       // 清空时恢复默认
-      setDateFilterPreset(trendGranularity.value === 'hour' ? 'last24h' : '7days')
+      setDateFilterPreset(trendGranularity.value === 'hour' ? 'last24h' : defaultPreset)
     }
   }
 
-  function setTrendGranularity(granularity) {
+  function setTrendGranularity(granularity, options = {}) {
+    const { silent = false, skipSave = false, presetOverride } = options
     trendGranularity.value = granularity
 
     // 根据粒度更新预设选项
     if (granularity === 'hour') {
-      dateFilter.value.presetOptions = [
+      dateFilter.value.presetOptions = getPresetOptions('hour')
-        { value: 'last24h', label: '近24小时', hours: 24 },
-        { value: 'yesterday', label: '昨天', hours: 24 },
-        { value: 'dayBefore', label: '前天', hours: 24 }
-      ]
 
       // 检查当前自定义日期范围是否超过24小时
       if (
@@ -777,46 +782,53 @@ export const useDashboardStore = defineStore('dashboard', () => {
         const hoursDiff = (end - start) / (1000 * 60 * 60)
         if (hoursDiff > 24) {
           showToast('小时粒度下日期范围不能超过24小时，已切换到近24小时', 'warning')
-          setDateFilterPreset('last24h')
+          setDateFilterPreset('last24h', { silent, skipSave })
           return
         }
       }
-
-      // 如果当前是天粒度的预设，切换到小时粒度的默认预设
-      if (['today', '7days', '30days'].includes(dateFilter.value.preset)) {
-        setDateFilterPreset('last24h')
-        return
-      }
     } else {
       // 天粒度
-      dateFilter.value.presetOptions = [
+      dateFilter.value.presetOptions = getPresetOptions('day')
-        { value: 'today', label: '今日', days: 1 },
+    }
-        { value: '7days', label: '7天', days: 7 },
-        { value: '30days', label: '30天', days: 30 }
-      ]
 
-      // 如果当前是小时粒度的预设，切换到天粒度的默认预设
+    if (dateFilter.value.type === 'custom') {
-      if (['last24h', 'yesterday', 'dayBefore'].includes(dateFilter.value.preset)) {
+      if (!skipSave) {
-        setDateFilterPreset('7days')
+        persistDatePreferences(dateFilter.value.preset || defaultPreset, trendGranularity.value)
+      }
+
+      if (!silent) {
+        refreshChartsData()
+      }
       return
     }
+
+    const nextPreset =
+      presetOverride ||
+      normalizePresetForGranularity(dateFilter.value.preset, trendGranularity.value)
+
+    setDateFilterPreset(nextPreset, { silent: true, skipSave: true })
+
+    if (!skipSave) {
+      persistDatePreferences(dateFilter.value.preset, trendGranularity.value)
     }
 
-    // 触发数据刷新
+    if (!silent) {
       refreshChartsData()
     }
+  }
 
   async function refreshChartsData() {
     // 根据当前筛选条件刷新数据
     let days
     let modelPeriod = 'monthly'
+    const effectiveGranularity = getEffectiveGranularity()
 
     if (dateFilter.value.type === 'preset') {
       const option = dateFilter.value.presetOptions.find(
         (opt) => opt.value === dateFilter.value.preset
       )
 
-      if (trendGranularity.value === 'hour') {
+      if (effectiveGranularity === 'hour') {
         // 小时粒度
         days = 1 // 小时粒度默认查看1天的数据
         modelPeriod = 'daily' // 小时粒度使用日统计
@@ -832,7 +844,7 @@ export const useDashboardStore = defineStore('dashboard', () => {
       }
     } else {
       // 自定义日期范围
-      if (trendGranularity.value === 'hour') {
+      if (effectiveGranularity === 'hour') {
         // 小时粒度下的自定义范围，计算小时数
         const start = new Date(dateFilter.value.customRange[0])
         const end = new Date(dateFilter.value.customRange[1])
@@ -845,16 +857,16 @@ export const useDashboardStore = defineStore('dashboard', () => {
     }
 
     await Promise.all([
-      loadUsageTrend(days, trendGranularity.value),
+      loadUsageTrend(days, effectiveGranularity),
-      loadModelStats(modelPeriod),
+      loadModelStats(modelPeriod, effectiveGranularity),
-      loadApiKeysTrend(apiKeysTrendMetric.value),
+      loadApiKeysTrend(apiKeysTrendMetric.value, effectiveGranularity),
-      loadAccountUsageTrend(accountUsageGroup.value)
+      loadAccountUsageTrend(accountUsageGroup.value, effectiveGranularity)
     ])
   }
 
   function setAccountUsageGroup(group) {
     accountUsageGroup.value = group
-    return loadAccountUsageTrend(group)
+    return loadAccountUsageTrend(group, getEffectiveGranularity())
   }
 
   function calculateDaysBetween(start, end) {
@@ -870,6 +882,10 @@ export const useDashboardStore = defineStore('dashboard', () => {
     return date > new Date()
   }
 
+  // 初始化日期筛选：同步本地偏好并填充范围
+  setDateFilterPreset(dateFilter.value.preset, { silent: true, skipSave: true })
+  persistDatePreferences(dateFilter.value.preset, trendGranularity.value)
+
   return {
     // 状态
     loading,

web/admin-spa/src/views/AccountUsageRecordsView.vue

@@ -0,0 +1,574 @@
+<template>
+  <div class="space-y-4 p-4 lg:p-6">
+    <div class="flex flex-wrap items-center justify-between gap-3">
+      <div class="flex items-center gap-3">
+        <button
+          class="rounded-full border border-gray-200 px-3 py-2 text-sm text-gray-700 transition hover:bg-gray-100 dark:border-gray-700 dark:text-gray-200 dark:hover:bg-gray-800"
+          @click="goBack"
+        >
+          ← 返回
+        </button>
+        <div>
+          <p class="text-xs font-semibold uppercase tracking-wide text-blue-600 dark:text-blue-400">
+            账户请求详情时间线
+          </p>
+          <h2 class="text-xl font-bold text-gray-900 dark:text-gray-100">
+            {{ accountDisplayName }}
+          </h2>
+          <p class="text-xs text-gray-500 dark:text-gray-400">ID: {{ accountId }}</p>
+          <p class="text-xs text-gray-500 dark:text-gray-400">渠道：{{ platformDisplayName }}</p>
+        </div>
+      </div>
+      <div class="flex items-center gap-2 text-sm text-gray-500 dark:text-gray-400">
+        <i class="fas fa-clock text-blue-500" />
+        <span v-if="dateRangeHint">{{ dateRangeHint }}</span>
+        <span v-else>显示近 5000 条记录</span>
+      </div>
+    </div>
+
+    <div class="grid gap-3 md:grid-cols-2 xl:grid-cols-4">
+      <div
+        class="rounded-xl border border-gray-200 bg-white p-4 shadow-sm dark:border-gray-800 dark:bg-gray-900"
+      >
+        <p class="text-xs uppercase text-gray-500 dark:text-gray-400">总请求</p>
+        <p class="mt-1 text-2xl font-bold text-gray-900 dark:text-gray-100">
+          {{ formatNumber(summary.totalRequests) }}
+        </p>
+      </div>
+      <div
+        class="rounded-xl border border-gray-200 bg-white p-4 shadow-sm dark:border-gray-800 dark:bg-gray-900"
+      >
+        <p class="text-xs uppercase text-gray-500 dark:text-gray-400">总 Token</p>
+        <p class="mt-1 text-2xl font-bold text-gray-900 dark:text-gray-100">
+          {{ formatNumber(summary.totalTokens) }}
+        </p>
+      </div>
+      <div
+        class="rounded-xl border border-gray-200 bg-white p-4 shadow-sm dark:border-gray-800 dark:bg-gray-900"
+      >
+        <p class="text-xs uppercase text-gray-500 dark:text-gray-400">总费用</p>
+        <p class="mt-1 text-2xl font-bold text-yellow-600 dark:text-yellow-400">
+          {{ formatCost(summary.totalCost) }}
+        </p>
+      </div>
+      <div
+        class="rounded-xl border border-gray-200 bg-white p-4 shadow-sm dark:border-gray-800 dark:bg-gray-900"
+      >
+        <p class="text-xs uppercase text-gray-500 dark:text-gray-400">平均费用/次</p>
+        <p class="mt-1 text-2xl font-bold text-gray-900 dark:text-gray-100">
+          {{ formatCost(summary.avgCost) }}
+        </p>
+      </div>
+    </div>
+
+    <div
+      class="rounded-xl border border-gray-200 bg-white p-4 shadow-sm dark:border-gray-800 dark:bg-gray-900"
+    >
+      <div class="flex flex-wrap items-center gap-3">
+        <el-date-picker
+          v-model="filters.dateRange"
+          class="max-w-[320px]"
+          clearable
+          end-placeholder="结束时间"
+          format="YYYY-MM-DD HH:mm:ss"
+          start-placeholder="开始时间"
+          type="datetimerange"
+          unlink-panels
+          value-format="YYYY-MM-DDTHH:mm:ss[Z]"
+        />
+
+        <el-select
+          v-model="filters.model"
+          class="w-[180px]"
+          clearable
+          filterable
+          placeholder="所有模型"
+        >
+          <el-option
+            v-for="modelOption in availableModels"
+            :key="modelOption"
+            :label="modelOption"
+            :value="modelOption"
+          />
+        </el-select>
+
+        <el-select
+          v-model="filters.apiKeyId"
+          class="w-[220px]"
+          clearable
+          filterable
+          placeholder="所有 API Key"
+        >
+          <el-option
+            v-for="apiKey in availableApiKeys"
+            :key="apiKey.id"
+            :label="apiKey.name || apiKey.id"
+            :value="apiKey.id"
+          />
+        </el-select>
+
+        <el-select v-model="filters.sortOrder" class="w-[140px]" placeholder="排序">
+          <el-option label="时间降序" value="desc" />
+          <el-option label="时间升序" value="asc" />
+        </el-select>
+
+        <el-button @click="resetFilters"> <i class="fas fa-undo mr-2" /> 重置 </el-button>
+        <el-button :loading="exporting" type="primary" @click="exportCsv">
+          <i class="fas fa-file-export mr-2" /> 导出 CSV
+        </el-button>
+      </div>
+    </div>
+
+    <div
+      class="rounded-xl border border-gray-200 bg-white shadow-sm dark:border-gray-800 dark:bg-gray-900"
+    >
+      <div
+        v-if="loading"
+        class="flex items-center justify-center p-10 text-gray-500 dark:text-gray-400"
+      >
+        <i class="fas fa-spinner fa-spin mr-2" /> 加载中...
+      </div>
+      <div v-else>
+        <div
+          v-if="records.length === 0"
+          class="flex flex-col items-center gap-2 p-10 text-gray-500 dark:text-gray-400"
+        >
+          <i class="fas fa-inbox text-2xl" />
+          <p>暂无记录</p>
+        </div>
+        <div v-else class="space-y-4">
+          <div class="hidden overflow-x-auto md:block">
+            <table class="min-w-full divide-y divide-gray-200 dark:divide-gray-800">
+              <thead class="bg-gray-50 dark:bg-gray-800">
+                <tr>
+                  <th
+                    class="px-4 py-3 text-left text-xs font-medium uppercase tracking-wider text-gray-500 dark:text-gray-300"
+                  >
+                    时间
+                  </th>
+                  <th
+                    class="px-4 py-3 text-left text-xs font-medium uppercase tracking-wider text-gray-500 dark:text-gray-300"
+                  >
+                    API Key
+                  </th>
+                  <th
+                    class="px-4 py-3 text-left text-xs font-medium uppercase tracking-wider text-gray-500 dark:text-gray-300"
+                  >
+                    模型
+                  </th>
+                  <th
+                    class="px-4 py-3 text-left text-xs font-medium uppercase tracking-wider text-gray-500 dark:text-gray-300"
+                  >
+                    输入
+                  </th>
+                  <th
+                    class="px-4 py-3 text-left text-xs font-medium uppercase tracking-wider text-gray-500 dark:text-gray-300"
+                  >
+                    输出
+                  </th>
+                  <th
+                    class="px-4 py-3 text-left text-xs font-medium uppercase tracking-wider text-gray-500 dark:text-gray-300"
+                  >
+                    缓存(创/读)
+                  </th>
+                  <th
+                    class="px-4 py-3 text-left text-xs font-medium uppercase tracking-wider text-gray-500 dark:text-gray-300"
+                  >
+                    总 Token
+                  </th>
+                  <th
+                    class="px-4 py-3 text-left text-xs font-medium uppercase tracking-wider text-gray-500 dark:text-gray-300"
+                  >
+                    费用
+                  </th>
+                  <th
+                    class="px-4 py-3 text-right text-xs font-medium uppercase tracking-wider text-gray-500 dark:text-gray-300"
+                  >
+                    操作
+                  </th>
+                </tr>
+              </thead>
+              <tbody
+                class="divide-y divide-gray-200 bg-white dark:divide-gray-800 dark:bg-gray-900"
+              >
+                <tr v-for="record in records" :key="record.timestamp + record.model">
+                  <td class="whitespace-nowrap px-4 py-3 text-sm text-gray-800 dark:text-gray-100">
+                    {{ formatDate(record.timestamp) }}
+                  </td>
+                  <td class="px-4 py-3 text-sm text-gray-800 dark:text-gray-100">
+                    <div class="flex flex-col">
+                      <span class="font-semibold">
+                        {{ record.apiKeyName || record.apiKeyId || '未知 Key' }}
+                      </span>
+                      <span class="text-xs text-gray-500 dark:text-gray-400">
+                        ID: {{ record.apiKeyId }}
+                      </span>
+                    </div>
+                  </td>
+                  <td class="whitespace-nowrap px-4 py-3 text-sm text-gray-800 dark:text-gray-100">
+                    {{ record.model }}
+                  </td>
+                  <td class="whitespace-nowrap px-4 py-3 text-sm text-blue-600 dark:text-blue-400">
+                    {{ formatNumber(record.inputTokens) }}
+                  </td>
+                  <td
+                    class="whitespace-nowrap px-4 py-3 text-sm text-green-600 dark:text-green-400"
+                  >
+                    {{ formatNumber(record.outputTokens) }}
+                  </td>
+                  <td
+                    class="whitespace-nowrap px-4 py-3 text-sm text-purple-600 dark:text-purple-400"
+                  >
+                    {{ formatNumber(record.cacheCreateTokens) }} /
+                    {{ formatNumber(record.cacheReadTokens) }}
+                  </td>
+                  <td class="whitespace-nowrap px-4 py-3 text-sm text-gray-800 dark:text-gray-100">
+                    {{ formatNumber(record.totalTokens) }}
+                  </td>
+                  <td
+                    class="whitespace-nowrap px-4 py-3 text-sm text-yellow-600 dark:text-yellow-400"
+                  >
+                    {{ record.costFormatted || formatCost(record.cost) }}
+                  </td>
+                  <td class="whitespace-nowrap px-4 py-3 text-right text-sm">
+                    <el-button size="small" @click="openDetail(record)">详情</el-button>
+                  </td>
+                </tr>
+              </tbody>
+            </table>
+          </div>
+
+          <div class="space-y-3 md:hidden">
+            <div
+              v-for="record in records"
+              :key="record.timestamp + record.model"
+              class="rounded-lg border border-gray-200 bg-white p-4 shadow-sm dark:border-gray-800 dark:bg-gray-900"
+            >
+              <div class="flex items-center justify-between">
+                <div>
+                  <p class="text-sm font-semibold text-gray-900 dark:text-gray-100">
+                    {{ record.apiKeyName || record.apiKeyId || '未知 Key' }}
+                  </p>
+                  <p class="text-xs text-gray-500 dark:text-gray-400">
+                    ID: {{ record.apiKeyId }} · {{ formatDate(record.timestamp) }}
+                  </p>
+                  <p class="text-xs text-gray-500 dark:text-gray-400">
+                    渠道：{{ platformDisplayName }}
+                  </p>
+                </div>
+                <el-button size="small" @click="openDetail(record)">详情</el-button>
+              </div>
+              <div class="mt-3 grid grid-cols-2 gap-2 text-sm text-gray-700 dark:text-gray-300">
+                <div>模型：{{ record.model }}</div>
+                <div>总 Token：{{ formatNumber(record.totalTokens) }}</div>
+                <div>输入：{{ formatNumber(record.inputTokens) }}</div>
+                <div>输出：{{ formatNumber(record.outputTokens) }}</div>
+                <div>
+                  缓存创/读：{{ formatNumber(record.cacheCreateTokens) }} /
+                  {{ formatNumber(record.cacheReadTokens) }}
+                </div>
+                <div class="text-yellow-600 dark:text-yellow-400">
+                  费用：{{ record.costFormatted || formatCost(record.cost) }}
+                </div>
+              </div>
+            </div>
+          </div>
+
+          <div class="flex items-center justify-between px-4 pb-4">
+            <div class="text-sm text-gray-500 dark:text-gray-400">
+              共 {{ pagination.totalRecords }} 条记录
+            </div>
+            <el-pagination
+              background
+              :current-page="pagination.currentPage"
+              layout="prev, pager, next, sizes"
+              :page-size="pagination.pageSize"
+              :page-sizes="[20, 50, 100, 200]"
+              :total="pagination.totalRecords"
+              @current-change="handlePageChange"
+              @size-change="handleSizeChange"
+            />
+          </div>
+        </div>
+      </div>
+    </div>
+
+    <RecordDetailModal :record="activeRecord" :show="detailVisible" @close="closeDetail" />
+  </div>
+</template>
+
+<script setup>
+import { computed, onMounted, reactive, ref, watch } from 'vue'
+import dayjs from 'dayjs'
+import { useRoute, useRouter } from 'vue-router'
+import { apiClient } from '@/config/api'
+import { showToast } from '@/utils/toast'
+import { formatNumber } from '@/utils/format'
+import RecordDetailModal from '@/components/apikeys/RecordDetailModal.vue'
+
+const route = useRoute()
+const router = useRouter()
+
+const accountId = computed(() => route.params.accountId)
+const platform = computed(() => route.query.platform)
+const loading = ref(false)
+const exporting = ref(false)
+const records = ref([])
+const availableModels = ref([])
+const availableApiKeys = ref([])
+
+const pagination = reactive({
+  currentPage: 1,
+  pageSize: 50,
+  totalRecords: 0
+})
+
+const filters = reactive({
+  dateRange: null,
+  model: '',
+  apiKeyId: '',
+  sortOrder: 'desc'
+})
+
+const summary = reactive({
+  totalRequests: 0,
+  totalTokens: 0,
+  totalCost: 0,
+  avgCost: 0
+})
+
+const accountInfo = reactive({
+  id: accountId.value,
+  name: '',
+  platform: platform.value || ''
+})
+
+const detailVisible = ref(false)
+const activeRecord = ref(null)
+
+const accountDisplayName = computed(() => accountInfo.name || accountInfo.id || accountId.value)
+const platformDisplayName = computed(() => {
+  const map = {
+    claude: 'Claude官方',
+    'claude-console': 'Claude Console',
+    ccr: 'Claude Console Relay',
+    openai: 'OpenAI',
+    'openai-responses': 'OpenAI Responses',
+    gemini: 'Gemini',
+    'gemini-api': 'Gemini API',
+    droid: 'Droid',
+    unknown: '未知渠道'
+  }
+  const key = accountInfo.platform || platform.value || 'unknown'
+  return map[key] || '未知渠道'
+})
+
+const dateRangeHint = computed(() => {
+  if (!filters.dateRange || filters.dateRange.length !== 2) return ''
+  return `${formatDate(filters.dateRange[0])} ~ ${formatDate(filters.dateRange[1])}`
+})
+
+const formatDate = (value) => {
+  if (!value) return '--'
+  return dayjs(value).format('YYYY-MM-DD HH:mm:ss')
+}
+
+const formatCost = (value) => {
+  const num = typeof value === 'number' ? value : 0
+  if (num >= 1) return `$${num.toFixed(2)}`
+  if (num >= 0.001) return `$${num.toFixed(4)}`
+  return `$${num.toFixed(6)}`
+}
+
+const buildParams = (page) => {
+  const params = {
+    page,
+    pageSize: pagination.pageSize,
+    sortOrder: filters.sortOrder
+  }
+
+  if (filters.model) params.model = filters.model
+  if (filters.apiKeyId) params.apiKeyId = filters.apiKeyId
+  if (filters.dateRange && filters.dateRange.length === 2) {
+    params.startDate = dayjs(filters.dateRange[0]).toISOString()
+    params.endDate = dayjs(filters.dateRange[1]).toISOString()
+  }
+  if (platform.value) {
+    params.platform = platform.value
+  }
+
+  return params
+}
+
+const syncResponseState = (data) => {
+  records.value = data.records || []
+
+  const pageInfo = data.pagination || {}
+  pagination.currentPage = pageInfo.currentPage || 1
+  pagination.pageSize = pageInfo.pageSize || pagination.pageSize
+  pagination.totalRecords = pageInfo.totalRecords || 0
+
+  const filterEcho = data.filters || {}
+  if (filterEcho.model !== undefined) filters.model = filterEcho.model || ''
+  if (filterEcho.apiKeyId !== undefined) filters.apiKeyId = filterEcho.apiKeyId || ''
+  if (filterEcho.sortOrder) filters.sortOrder = filterEcho.sortOrder
+  if (filterEcho.startDate && filterEcho.endDate) {
+    const nextRange = [filterEcho.startDate, filterEcho.endDate]
+    const currentRange = filters.dateRange || []
+    if (currentRange[0] !== nextRange[0] || currentRange[1] !== nextRange[1]) {
+      filters.dateRange = nextRange
+    }
+  }
+
+  const summaryData = data.summary || {}
+  summary.totalRequests = summaryData.totalRequests || 0
+  summary.totalTokens = summaryData.totalTokens || 0
+  summary.totalCost = summaryData.totalCost || 0
+  summary.avgCost = summaryData.avgCost || 0
+
+  accountInfo.id = data.accountInfo?.id || accountId.value
+  accountInfo.name = data.accountInfo?.name || ''
+  accountInfo.platform = data.accountInfo?.platform || platform.value || ''
+
+  availableModels.value = data.availableFilters?.models || []
+  availableApiKeys.value = data.availableFilters?.apiKeys || []
+}
+
+const fetchRecords = async (page = pagination.currentPage) => {
+  loading.value = true
+  try {
+    const response = await apiClient.get(`/admin/accounts/${accountId.value}/usage-records`, {
+      params: buildParams(page)
+    })
+    syncResponseState(response.data || {})
+  } catch (error) {
+    showToast(`加载请求记录失败：${error.message || '未知错误'}`, 'error')
+  } finally {
+    loading.value = false
+  }
+}
+
+const handlePageChange = (page) => {
+  pagination.currentPage = page
+  fetchRecords(page)
+}
+
+const handleSizeChange = (size) => {
+  pagination.pageSize = size
+  pagination.currentPage = 1
+  fetchRecords(1)
+}
+
+const resetFilters = () => {
+  filters.model = ''
+  filters.apiKeyId = ''
+  filters.dateRange = null
+  filters.sortOrder = 'desc'
+  pagination.currentPage = 1
+  fetchRecords(1)
+}
+
+const openDetail = (record) => {
+  activeRecord.value = record
+  detailVisible.value = true
+}
+
+const closeDetail = () => {
+  detailVisible.value = false
+  activeRecord.value = null
+}
+
+const goBack = () => {
+  router.push('/accounts')
+}
+
+const exportCsv = async () => {
+  if (exporting.value) return
+  exporting.value = true
+  try {
+    const aggregated = []
+    let page = 1
+    let totalPages = 1
+    const maxPages = 50 // 50 * 200 = 10000，超过后端 5000 上限已足够
+
+    while (page <= totalPages && page <= maxPages) {
+      const response = await apiClient.get(`/admin/accounts/${accountId.value}/usage-records`, {
+        params: { ...buildParams(page), pageSize: 200 }
+      })
+      const payload = response.data || {}
+      aggregated.push(...(payload.records || []))
+      totalPages = payload.pagination?.totalPages || 1
+      page += 1
+    }
+
+    if (aggregated.length === 0) {
+      showToast('没有可导出的记录', 'info')
+      return
+    }
+
+    const headers = [
+      '时间',
+      'API Key',
+      '模型',
+      '输入Token',
+      '输出Token',
+      '缓存创建Token',
+      '缓存读取Token',
+      '总Token',
+      '费用'
+    ]
+
+    const csvRows = [headers.join(',')]
+    aggregated.forEach((record) => {
+      const row = [
+        formatDate(record.timestamp),
+        record.apiKeyName || record.apiKeyId || '',
+        record.model || '',
+        record.inputTokens || 0,
+        record.outputTokens || 0,
+        record.cacheCreateTokens || 0,
+        record.cacheReadTokens || 0,
+        record.totalTokens || 0,
+        record.costFormatted || formatCost(record.cost)
+      ]
+      csvRows.push(row.map((cell) => `"${String(cell).replace(/"/g, '""')}"`).join(','))
+    })
+
+    const blob = new Blob([csvRows.join('\n')], {
+      type: 'text/csv;charset=utf-8;'
+    })
+    const url = URL.createObjectURL(blob)
+    const link = document.createElement('a')
+    link.href = url
+    link.download = `account-${accountId.value}-usage-records.csv`
+    link.click()
+    URL.revokeObjectURL(url)
+    showToast('导出 CSV 成功', 'success')
+  } catch (error) {
+    showToast(`导出失败：${error.message || '未知错误'}`, 'error')
+  } finally {
+    exporting.value = false
+  }
+}
+
+watch(
+  () => [filters.model, filters.apiKeyId, filters.sortOrder],
+  () => {
+    pagination.currentPage = 1
+    fetchRecords(1)
+  }
+)
+
+watch(
+  () => filters.dateRange,
+  () => {
+    pagination.currentPage = 1
+    fetchRecords(1)
+  },
+  { deep: true }
+)
+
+onMounted(() => {
+  fetchRecords()
+})
+</script>

web/admin-spa/src/views/ApiKeyUsageRecordsView.vue

@@ -0,0 +1,549 @@
+<template>
+  <div class="space-y-4 p-4 lg:p-6">
+    <div class="flex flex-wrap items-center justify-between gap-3">
+      <div class="flex items-center gap-3">
+        <button
+          class="rounded-full border border-gray-200 px-3 py-2 text-sm text-gray-700 transition hover:bg-gray-100 dark:border-gray-700 dark:text-gray-200 dark:hover:bg-gray-800"
+          @click="goBack"
+        >
+          ← 返回
+        </button>
+        <div>
+          <p class="text-xs font-semibold uppercase tracking-wide text-blue-600 dark:text-blue-400">
+            API Key 请求详情时间线
+          </p>
+          <h2 class="text-xl font-bold text-gray-900 dark:text-gray-100">
+            {{ apiKeyDisplayName }}
+          </h2>
+          <p class="text-xs text-gray-500 dark:text-gray-400">ID: {{ keyId }}</p>
+        </div>
+      </div>
+      <div class="flex items-center gap-2 text-sm text-gray-500 dark:text-gray-400">
+        <i class="fas fa-clock text-blue-500" />
+        <span v-if="dateRangeHint">{{ dateRangeHint }}</span>
+        <span v-else>显示近 5000 条记录</span>
+      </div>
+    </div>
+
+    <div class="grid gap-3 md:grid-cols-2 xl:grid-cols-4">
+      <div
+        class="rounded-xl border border-gray-200 bg-white p-4 shadow-sm dark:border-gray-800 dark:bg-gray-900"
+      >
+        <p class="text-xs uppercase text-gray-500 dark:text-gray-400">总请求</p>
+        <p class="mt-1 text-2xl font-bold text-gray-900 dark:text-gray-100">
+          {{ formatNumber(summary.totalRequests) }}
+        </p>
+      </div>
+      <div
+        class="rounded-xl border border-gray-200 bg-white p-4 shadow-sm dark:border-gray-800 dark:bg-gray-900"
+      >
+        <p class="text-xs uppercase text-gray-500 dark:text-gray-400">总 Token</p>
+        <p class="mt-1 text-2xl font-bold text-gray-900 dark:text-gray-100">
+          {{ formatNumber(summary.totalTokens) }}
+        </p>
+      </div>
+      <div
+        class="rounded-xl border border-gray-200 bg-white p-4 shadow-sm dark:border-gray-800 dark:bg-gray-900"
+      >
+        <p class="text-xs uppercase text-gray-500 dark:text-gray-400">总费用</p>
+        <p class="mt-1 text-2xl font-bold text-yellow-600 dark:text-yellow-400">
+          {{ formatCost(summary.totalCost) }}
+        </p>
+      </div>
+      <div
+        class="rounded-xl border border-gray-200 bg-white p-4 shadow-sm dark:border-gray-800 dark:bg-gray-900"
+      >
+        <p class="text-xs uppercase text-gray-500 dark:text-gray-400">平均费用/次</p>
+        <p class="mt-1 text-2xl font-bold text-gray-900 dark:text-gray-100">
+          {{ formatCost(summary.avgCost) }}
+        </p>
+      </div>
+    </div>
+
+    <div
+      class="rounded-xl border border-gray-200 bg-white p-4 shadow-sm dark:border-gray-800 dark:bg-gray-900"
+    >
+      <div class="flex flex-wrap items-center gap-3">
+        <el-date-picker
+          v-model="filters.dateRange"
+          class="max-w-[320px]"
+          clearable
+          end-placeholder="结束时间"
+          format="YYYY-MM-DD HH:mm:ss"
+          start-placeholder="开始时间"
+          type="datetimerange"
+          unlink-panels
+          value-format="YYYY-MM-DDTHH:mm:ss[Z]"
+        />
+
+        <el-select
+          v-model="filters.model"
+          class="w-[180px]"
+          clearable
+          filterable
+          placeholder="所有模型"
+        >
+          <el-option
+            v-for="modelOption in availableModels"
+            :key="modelOption"
+            :label="modelOption"
+            :value="modelOption"
+          />
+        </el-select>
+
+        <el-select
+          v-model="filters.accountId"
+          class="w-[220px]"
+          clearable
+          filterable
+          placeholder="所有账户"
+        >
+          <el-option
+            v-for="account in availableAccounts"
+            :key="account.id"
+            :label="`${account.name}（${account.accountTypeName}）`"
+            :value="account.id"
+          />
+        </el-select>
+
+        <el-select v-model="filters.sortOrder" class="w-[140px]" placeholder="排序">
+          <el-option label="时间降序" value="desc" />
+          <el-option label="时间升序" value="asc" />
+        </el-select>
+
+        <el-button @click="resetFilters"> <i class="fas fa-undo mr-2" /> 重置 </el-button>
+        <el-button :loading="exporting" type="primary" @click="exportCsv">
+          <i class="fas fa-file-export mr-2" /> 导出 CSV
+        </el-button>
+      </div>
+    </div>
+
+    <div
+      class="rounded-xl border border-gray-200 bg-white shadow-sm dark:border-gray-800 dark:bg-gray-900"
+    >
+      <div
+        v-if="loading"
+        class="flex items-center justify-center p-10 text-gray-500 dark:text-gray-400"
+      >
+        <i class="fas fa-spinner fa-spin mr-2" /> 加载中...
+      </div>
+      <div v-else>
+        <div
+          v-if="records.length === 0"
+          class="flex flex-col items-center gap-2 p-10 text-gray-500 dark:text-gray-400"
+        >
+          <i class="fas fa-inbox text-2xl" />
+          <p>暂无记录</p>
+        </div>
+        <div v-else class="space-y-4">
+          <div class="hidden overflow-x-auto md:block">
+            <table class="min-w-full divide-y divide-gray-200 dark:divide-gray-800">
+              <thead class="bg-gray-50 dark:bg-gray-800">
+                <tr>
+                  <th
+                    class="px-4 py-3 text-left text-xs font-medium uppercase tracking-wider text-gray-500 dark:text-gray-300"
+                  >
+                    时间
+                  </th>
+                  <th
+                    class="px-4 py-3 text-left text-xs font-medium uppercase tracking-wider text-gray-500 dark:text-gray-300"
+                  >
+                    账户
+                  </th>
+                  <th
+                    class="px-4 py-3 text-left text-xs font-medium uppercase tracking-wider text-gray-500 dark:text-gray-300"
+                  >
+                    模型
+                  </th>
+                  <th
+                    class="px-4 py-3 text-left text-xs font-medium uppercase tracking-wider text-gray-500 dark:text-gray-300"
+                  >
+                    输入
+                  </th>
+                  <th
+                    class="px-4 py-3 text-left text-xs font-medium uppercase tracking-wider text-gray-500 dark:text-gray-300"
+                  >
+                    输出
+                  </th>
+                  <th
+                    class="px-4 py-3 text-left text-xs font-medium uppercase tracking-wider text-gray-500 dark:text-gray-300"
+                  >
+                    缓存(创/读)
+                  </th>
+                  <th
+                    class="px-4 py-3 text-left text-xs font-medium uppercase tracking-wider text-gray-500 dark:text-gray-300"
+                  >
+                    总 Token
+                  </th>
+                  <th
+                    class="px-4 py-3 text-left text-xs font-medium uppercase tracking-wider text-gray-500 dark:text-gray-300"
+                  >
+                    费用
+                  </th>
+                  <th
+                    class="px-4 py-3 text-right text-xs font-medium uppercase tracking-wider text-gray-500 dark:text-gray-300"
+                  >
+                    操作
+                  </th>
+                </tr>
+              </thead>
+              <tbody
+                class="divide-y divide-gray-200 bg-white dark:divide-gray-800 dark:bg-gray-900"
+              >
+                <tr v-for="record in records" :key="record.timestamp + record.model">
+                  <td class="whitespace-nowrap px-4 py-3 text-sm text-gray-800 dark:text-gray-100">
+                    {{ formatDate(record.timestamp) }}
+                  </td>
+                  <td class="px-4 py-3 text-sm text-gray-800 dark:text-gray-100">
+                    <div class="flex flex-col">
+                      <span class="font-semibold">{{ record.accountName || '未知账户' }}</span>
+                      <span class="text-xs text-gray-500 dark:text-gray-400">
+                        {{ record.accountTypeName || '未知渠道' }}
+                      </span>
+                    </div>
+                  </td>
+                  <td class="whitespace-nowrap px-4 py-3 text-sm text-gray-800 dark:text-gray-100">
+                    {{ record.model }}
+                  </td>
+                  <td class="whitespace-nowrap px-4 py-3 text-sm text-blue-600 dark:text-blue-400">
+                    {{ formatNumber(record.inputTokens) }}
+                  </td>
+                  <td
+                    class="whitespace-nowrap px-4 py-3 text-sm text-green-600 dark:text-green-400"
+                  >
+                    {{ formatNumber(record.outputTokens) }}
+                  </td>
+                  <td
+                    class="whitespace-nowrap px-4 py-3 text-sm text-purple-600 dark:text-purple-400"
+                  >
+                    {{ formatNumber(record.cacheCreateTokens) }} /
+                    {{ formatNumber(record.cacheReadTokens) }}
+                  </td>
+                  <td class="whitespace-nowrap px-4 py-3 text-sm text-gray-800 dark:text-gray-100">
+                    {{ formatNumber(record.totalTokens) }}
+                  </td>
+                  <td
+                    class="whitespace-nowrap px-4 py-3 text-sm text-yellow-600 dark:text-yellow-400"
+                  >
+                    {{ record.costFormatted || formatCost(record.cost) }}
+                  </td>
+                  <td class="whitespace-nowrap px-4 py-3 text-right text-sm">
+                    <el-button size="small" @click="openDetail(record)">详情</el-button>
+                  </td>
+                </tr>
+              </tbody>
+            </table>
+          </div>
+
+          <div class="space-y-3 md:hidden">
+            <div
+              v-for="record in records"
+              :key="record.timestamp + record.model"
+              class="rounded-lg border border-gray-200 bg-white p-4 shadow-sm dark:border-gray-800 dark:bg-gray-900"
+            >
+              <div class="flex items-center justify-between">
+                <div>
+                  <p class="text-sm font-semibold text-gray-900 dark:text-gray-100">
+                    {{ record.accountName || '未知账户' }}
+                  </p>
+                  <p class="text-xs text-gray-500 dark:text-gray-400">
+                    {{ formatDate(record.timestamp) }}
+                  </p>
+                </div>
+                <el-button size="small" @click="openDetail(record)">详情</el-button>
+              </div>
+              <div class="mt-3 grid grid-cols-2 gap-2 text-sm text-gray-700 dark:text-gray-300">
+                <div>模型：{{ record.model }}</div>
+                <div>总 Token：{{ formatNumber(record.totalTokens) }}</div>
+                <div>输入：{{ formatNumber(record.inputTokens) }}</div>
+                <div>输出：{{ formatNumber(record.outputTokens) }}</div>
+                <div>
+                  缓存创/读：{{ formatNumber(record.cacheCreateTokens) }} /
+                  {{ formatNumber(record.cacheReadTokens) }}
+                </div>
+                <div class="text-yellow-600 dark:text-yellow-400">
+                  费用：{{ record.costFormatted || formatCost(record.cost) }}
+                </div>
+              </div>
+            </div>
+          </div>
+
+          <div class="flex items-center justify-between px-4 pb-4">
+            <div class="text-sm text-gray-500 dark:text-gray-400">
+              共 {{ pagination.totalRecords }} 条记录
+            </div>
+            <el-pagination
+              background
+              :current-page="pagination.currentPage"
+              layout="prev, pager, next, sizes"
+              :page-size="pagination.pageSize"
+              :page-sizes="[20, 50, 100, 200]"
+              :total="pagination.totalRecords"
+              @current-change="handlePageChange"
+              @size-change="handleSizeChange"
+            />
+          </div>
+        </div>
+      </div>
+    </div>
+
+    <RecordDetailModal :record="activeRecord" :show="detailVisible" @close="closeDetail" />
+  </div>
+</template>
+
+<script setup>
+import { computed, onMounted, reactive, ref, watch } from 'vue'
+import dayjs from 'dayjs'
+import { useRoute, useRouter } from 'vue-router'
+import { apiClient } from '@/config/api'
+import { showToast } from '@/utils/toast'
+import { formatNumber } from '@/utils/format'
+import RecordDetailModal from '@/components/apikeys/RecordDetailModal.vue'
+
+const route = useRoute()
+const router = useRouter()
+
+const keyId = computed(() => route.params.keyId)
+const loading = ref(false)
+const exporting = ref(false)
+const records = ref([])
+const availableModels = ref([])
+const availableAccounts = ref([])
+
+const pagination = reactive({
+  currentPage: 1,
+  pageSize: 50,
+  totalRecords: 0
+})
+
+const filters = reactive({
+  dateRange: null,
+  model: '',
+  accountId: '',
+  sortOrder: 'desc'
+})
+
+const summary = reactive({
+  totalRequests: 0,
+  totalTokens: 0,
+  totalCost: 0,
+  avgCost: 0
+})
+
+const apiKeyInfo = reactive({
+  id: keyId.value,
+  name: ''
+})
+
+const detailVisible = ref(false)
+const activeRecord = ref(null)
+
+const apiKeyDisplayName = computed(() => apiKeyInfo.name || apiKeyInfo.id || keyId.value)
+
+const dateRangeHint = computed(() => {
+  if (!filters.dateRange || filters.dateRange.length !== 2) return ''
+  return `${formatDate(filters.dateRange[0])} ~ ${formatDate(filters.dateRange[1])}`
+})
+
+const formatDate = (value) => {
+  if (!value) return '--'
+  return dayjs(value).format('YYYY-MM-DD HH:mm:ss')
+}
+
+const formatCost = (value) => {
+  const num = typeof value === 'number' ? value : 0
+  if (num >= 1) return `$${num.toFixed(2)}`
+  if (num >= 0.001) return `$${num.toFixed(4)}`
+  return `$${num.toFixed(6)}`
+}
+
+const buildParams = (page) => {
+  const params = {
+    page,
+    pageSize: pagination.pageSize,
+    sortOrder: filters.sortOrder
+  }
+
+  if (filters.model) params.model = filters.model
+  if (filters.accountId) params.accountId = filters.accountId
+  if (filters.dateRange && filters.dateRange.length === 2) {
+    params.startDate = dayjs(filters.dateRange[0]).toISOString()
+    params.endDate = dayjs(filters.dateRange[1]).toISOString()
+  }
+
+  return params
+}
+
+const syncResponseState = (data) => {
+  records.value = data.records || []
+
+  const pageInfo = data.pagination || {}
+  pagination.currentPage = pageInfo.currentPage || 1
+  pagination.pageSize = pageInfo.pageSize || pagination.pageSize
+  pagination.totalRecords = pageInfo.totalRecords || 0
+
+  const filterEcho = data.filters || {}
+  if (filterEcho.model !== undefined) filters.model = filterEcho.model || ''
+  if (filterEcho.accountId !== undefined) filters.accountId = filterEcho.accountId || ''
+  if (filterEcho.sortOrder) filters.sortOrder = filterEcho.sortOrder
+  if (filterEcho.startDate && filterEcho.endDate) {
+    const nextRange = [filterEcho.startDate, filterEcho.endDate]
+    const currentRange = filters.dateRange || []
+    if (currentRange[0] !== nextRange[0] || currentRange[1] !== nextRange[1]) {
+      filters.dateRange = nextRange
+    }
+  }
+
+  const summaryData = data.summary || {}
+  summary.totalRequests = summaryData.totalRequests || 0
+  summary.totalTokens = summaryData.totalTokens || 0
+  summary.totalCost = summaryData.totalCost || 0
+  summary.avgCost = summaryData.avgCost || 0
+
+  apiKeyInfo.id = data.apiKeyInfo?.id || keyId.value
+  apiKeyInfo.name = data.apiKeyInfo?.name || ''
+
+  availableModels.value = data.availableFilters?.models || []
+  availableAccounts.value = data.availableFilters?.accounts || []
+}
+
+const fetchRecords = async (page = pagination.currentPage) => {
+  loading.value = true
+  try {
+    const response = await apiClient.get(`/admin/api-keys/${keyId.value}/usage-records`, {
+      params: buildParams(page)
+    })
+    syncResponseState(response.data || {})
+  } catch (error) {
+    showToast(`加载请求记录失败：${error.message || '未知错误'}`, 'error')
+  } finally {
+    loading.value = false
+  }
+}
+
+const handlePageChange = (page) => {
+  pagination.currentPage = page
+  fetchRecords(page)
+}
+
+const handleSizeChange = (size) => {
+  pagination.pageSize = size
+  pagination.currentPage = 1
+  fetchRecords(1)
+}
+
+const resetFilters = () => {
+  filters.model = ''
+  filters.accountId = ''
+  filters.dateRange = null
+  filters.sortOrder = 'desc'
+  pagination.currentPage = 1
+  fetchRecords(1)
+}
+
+const openDetail = (record) => {
+  activeRecord.value = record
+  detailVisible.value = true
+}
+
+const closeDetail = () => {
+  detailVisible.value = false
+  activeRecord.value = null
+}
+
+const goBack = () => {
+  router.push('/api-keys')
+}
+
+const exportCsv = async () => {
+  if (exporting.value) return
+  exporting.value = true
+  try {
+    const aggregated = []
+    let page = 1
+    let totalPages = 1
+    const maxPages = 50 // 50 * 200 = 10000，超过后端 5000 上限已足够
+
+    while (page <= totalPages && page <= maxPages) {
+      const response = await apiClient.get(`/admin/api-keys/${keyId.value}/usage-records`, {
+        params: { ...buildParams(page), pageSize: 200 }
+      })
+      const payload = response.data || {}
+      aggregated.push(...(payload.records || []))
+      totalPages = payload.pagination?.totalPages || 1
+      page += 1
+    }
+
+    if (aggregated.length === 0) {
+      showToast('没有可导出的记录', 'info')
+      return
+    }
+
+    const headers = [
+      '时间',
+      '账户',
+      '渠道',
+      '模型',
+      '输入Token',
+      '输出Token',
+      '缓存创建Token',
+      '缓存读取Token',
+      '总Token',
+      '费用'
+    ]
+
+    const csvRows = [headers.join(',')]
+    aggregated.forEach((record) => {
+      const row = [
+        formatDate(record.timestamp),
+        record.accountName || '',
+        record.accountTypeName || '',
+        record.model || '',
+        record.inputTokens || 0,
+        record.outputTokens || 0,
+        record.cacheCreateTokens || 0,
+        record.cacheReadTokens || 0,
+        record.totalTokens || 0,
+        record.costFormatted || formatCost(record.cost)
+      ]
+      csvRows.push(row.map((cell) => `"${String(cell).replace(/"/g, '""')}"`).join(','))
+    })
+
+    const blob = new Blob([csvRows.join('\n')], {
+      type: 'text/csv;charset=utf-8;'
+    })
+    const url = URL.createObjectURL(blob)
+    const link = document.createElement('a')
+    link.href = url
+    link.download = `api-key-${keyId.value}-usage-records.csv`
+    link.click()
+    URL.revokeObjectURL(url)
+    showToast('导出 CSV 成功', 'success')
+  } catch (error) {
+    showToast(`导出失败：${error.message || '未知错误'}`, 'error')
+  } finally {
+    exporting.value = false
+  }
+}
+
+watch(
+  () => [filters.model, filters.accountId, filters.sortOrder],
+  () => {
+    pagination.currentPage = 1
+    fetchRecords(1)
+  }
+)
+
+watch(
+  () => filters.dateRange,
+  () => {
+    pagination.currentPage = 1
+    fetchRecords(1)
+  },
+  { deep: true }
+)
+
+onMounted(() => {
+  fetchRecords()
+})
+</script>

web/admin-spa/src/views/ApiKeysView.vue

@@ -116,6 +116,29 @@
                 </div>
               </div>
 
+              <!-- 模型筛选器 -->
+              <div class="group relative min-w-[140px]">
+                <div
+                  class="absolute -inset-0.5 rounded-lg bg-gradient-to-r from-orange-500 to-amber-500 opacity-0 blur transition duration-300 group-hover:opacity-20"
+                ></div>
+                <div class="relative">
+                  <CustomDropdown
+                    v-model="selectedModels"
+                    icon="fa-cube"
+                    icon-color="text-orange-500"
+                    :multiple="true"
+                    :options="modelOptions"
+                    placeholder="所有模型"
+                  />
+                  <span
+                    v-if="selectedModels.length > 0"
+                    class="absolute -right-2 -top-2 z-10 flex h-5 w-5 items-center justify-center rounded-full bg-orange-500 text-xs text-white shadow-sm"
+                  >
+                    {{ selectedModels.length }}
+                  </span>
+                </div>
+              </div>
+
               <!-- 搜索模式与搜索框 -->
               <div class="flex min-w-[240px] flex-col gap-2 sm:flex-row sm:items-center">
                 <div class="sm:w-44">
@@ -2085,17 +2108,18 @@
       @save="handleSaveExpiry"
     />
 
-    <!-- 使用详情弹窗 -->
     <UsageDetailModal
       :api-key="selectedApiKeyForDetail || {}"
       :show="showUsageDetailModal"
       @close="showUsageDetailModal = false"
+      @open-timeline="openTimeline"
     />
   </div>
 </template>
 
 <script setup>
 import { ref, reactive, computed, onMounted, onUnmounted, watch } from 'vue'
+import { useRouter } from 'vue-router'
 import { showToast } from '@/utils/toast'
 import { apiClient } from '@/config/api'
 import { useClientsStore } from '@/stores/clients'
@@ -2114,6 +2138,7 @@ import CustomDropdown from '@/components/common/CustomDropdown.vue'
 import ActionDropdown from '@/components/common/ActionDropdown.vue'
 
 // 响应式数据
+const router = useRouter()
 const clientsStore = useClientsStore()
 const authStore = useAuthStore()
 const apiKeys = ref([])
@@ -2218,6 +2243,10 @@ const selectedApiKeyForDetail = ref(null)
 const selectedTagFilter = ref('')
 const availableTags = ref([])
 
+// 模型筛选相关
+const selectedModels = ref([])
+const availableModels = ref([])
+
 // 搜索相关
 const searchKeyword = ref('')
 const searchMode = ref('apiKey')
@@ -2234,6 +2263,14 @@ const tagOptions = computed(() => {
   return options
 })
 
+const modelOptions = computed(() => {
+  return availableModels.value.map((model) => ({
+    value: model,
+    label: model,
+    icon: 'fa-cube'
+  }))
+})
+
 const selectedTagCount = computed(() => {
   if (!selectedTagFilter.value) return 0
   return apiKeys.value.filter((key) => key.tags && key.tags.includes(selectedTagFilter.value))
@@ -2472,6 +2509,18 @@ const loadAccounts = async (forceRefresh = false) => {
   }
 }
 
+// 加载已使用的模型列表
+const loadUsedModels = async () => {
+  try {
+    const data = await apiClient.get('/admin/api-keys/used-models')
+    if (data.success) {
+      availableModels.value = data.data || []
+    }
+  } catch (error) {
+    console.error('Failed to load used models:', error)
+  }
+}
+
 // 加载API Keys（使用后端分页）
 const loadApiKeys = async (clearStatsCache = true) => {
   apiKeysLoading.value = true
@@ -2500,6 +2549,11 @@ const loadApiKeys = async (clearStatsCache = true) => {
       params.set('tag', selectedTagFilter.value)
     }
 
+    // 模型筛选参数
+    if (selectedModels.value.length > 0) {
+      params.set('models', selectedModels.value.join(','))
+    }
+
     // 排序参数（支持费用排序）
     const validSortFields = [
       'name',
@@ -4193,19 +4247,15 @@ const formatWindowTime = (seconds) => {
 
 // 显示使用详情
 const showUsageDetails = (apiKey) => {
-  // 获取异步加载的统计数据
   const cachedStats = getCachedStats(apiKey.id)
 
-  // 合并异步统计数据到 apiKey 对象
   const enrichedApiKey = {
     ...apiKey,
-    // 合并实时限制数据
     dailyCost: cachedStats?.dailyCost ?? apiKey.dailyCost ?? 0,
     currentWindowCost: cachedStats?.currentWindowCost ?? apiKey.currentWindowCost ?? 0,
     windowRemainingSeconds: cachedStats?.windowRemainingSeconds ?? apiKey.windowRemainingSeconds,
     windowStartTime: cachedStats?.windowStartTime ?? apiKey.windowStartTime ?? null,
     windowEndTime: cachedStats?.windowEndTime ?? apiKey.windowEndTime ?? null,
-    // 合并 usage 数据（用于详情弹窗中的统计卡片）
     usage: {
       ...apiKey.usage,
       total: {
@@ -4226,6 +4276,13 @@ const showUsageDetails = (apiKey) => {
   showUsageDetailModal.value = true
 }
 
+const openTimeline = (keyId) => {
+  const id = keyId || selectedApiKeyForDetail.value?.id
+  if (!id) return
+  showUsageDetailModal.value = false
+  router.push(`/api-keys/${id}/usage-records`)
+}
+
 // 格式化时间（秒转换为可读格式） - 已移到 WindowLimitBar 组件中
 // const formatTime = (seconds) => {
 //   if (seconds === null || seconds === undefined) return '--:--'
@@ -4706,6 +4763,12 @@ watch(selectedTagFilter, () => {
   loadApiKeys(false)
 })
 
+// 监听模型筛选变化
+watch(selectedModels, () => {
+  currentPage.value = 1
+  loadApiKeys(false)
+})
+
 // 监听排序变化，重新加载数据
 watch([apiKeysSortBy, apiKeysSortOrder], () => {
   loadApiKeys(false)
@@ -4740,7 +4803,7 @@ onMounted(async () => {
   fetchCostSortStatus()
 
   // 先加载 API Keys（优先显示列表）
-  await Promise.all([clientsStore.loadSupportedClients(), loadApiKeys()])
+  await Promise.all([clientsStore.loadSupportedClients(), loadApiKeys(), loadUsedModels()])
 
   // 初始化全选状态
   updateSelectAllState()

web/admin-spa/src/views/DashboardView.vue

@@ -1036,6 +1036,7 @@ function createUsageTrendChart() {
           type: 'linear',
           display: true,
           position: 'left',
+          min: 0,
           title: {
             display: true,
             text: 'Token数量',
@@ -1055,6 +1056,7 @@ function createUsageTrendChart() {
           type: 'linear',
           display: true,
           position: 'right',
+          min: 0,
           title: {
             display: true,
             text: '请求数',
@@ -1073,7 +1075,8 @@ function createUsageTrendChart() {
         y2: {
           type: 'linear',
           display: false, // 隐藏费用轴，在tooltip中显示
-          position: 'right'
+          position: 'right',
+          min: 0
         }
       }
     }
@@ -1253,6 +1256,7 @@ function createApiKeysUsageTrendChart() {
         },
         y: {
           beginAtZero: true,
+          min: 0,
           title: {
             display: true,
             text: apiKeysTrendMetric.value === 'tokens' ? 'Token 数量' : '请求次数',
@@ -1428,6 +1432,7 @@ function createAccountUsageTrendChart() {
         },
         y: {
           beginAtZero: true,
+          min: 0,
           title: {
             display: true,
             text: '消耗金额 (USD)',

web/admin-spa/src/views/SettingsView.vue

@@ -36,6 +36,18 @@
             <i class="fas fa-bell mr-2"></i>
             通知设置
           </button>
+          <button
+            :class="[
+              'border-b-2 pb-2 text-sm font-medium transition-colors',
+              activeSection === 'claude'
+                ? 'border-blue-500 text-blue-600 dark:border-blue-400 dark:text-blue-400'
+                : 'border-transparent text-gray-500 hover:border-gray-300 hover:text-gray-700 dark:text-gray-400 dark:hover:text-gray-300'
+            ]"
+            @click="activeSection = 'claude'"
+          >
+            <i class="fas fa-robot mr-2"></i>
+            Claude 转发
+          </button>
         </nav>
       </div>
 
@@ -629,6 +641,390 @@
             </button>
           </div>
         </div>
+
+        <!-- Claude 转发配置部分 -->
+        <div v-show="activeSection === 'claude'">
+          <!-- 加载状态 -->
+          <div v-if="claudeConfigLoading" class="py-12 text-center">
+            <div class="loading-spinner mx-auto mb-4"></div>
+            <p class="text-gray-500 dark:text-gray-400">正在加载配置...</p>
+          </div>
+
+          <div v-else>
+            <!-- Claude Code 客户端限制 -->
+            <div
+              class="mb-6 rounded-lg bg-white/80 p-6 shadow-lg backdrop-blur-sm dark:bg-gray-800/80"
+            >
+              <div class="flex items-center justify-between">
+                <div>
+                  <div class="flex items-center">
+                    <div
+                      class="mr-3 flex h-10 w-10 items-center justify-center rounded-full bg-gradient-to-br from-orange-500 to-amber-600 text-white shadow-lg"
+                    >
+                      <i class="fas fa-terminal"></i>
+                    </div>
+                    <div>
+                      <h2 class="text-lg font-semibold text-gray-800 dark:text-gray-200">
+                        仅允许 Claude Code 客户端
+                      </h2>
+                      <p class="mt-1 text-sm text-gray-600 dark:text-gray-400">
+                        启用后，所有
+                        <code class="rounded bg-gray-100 px-1 dark:bg-gray-700"
+                          >/api/v1/messages</code
+                        >
+                        和
+                        <code class="rounded bg-gray-100 px-1 dark:bg-gray-700"
+                          >/claude/v1/messages</code
+                        >
+                        端点将强制验证 Claude Code CLI 客户端
+                      </p>
+                    </div>
+                  </div>
+                </div>
+                <label class="relative inline-flex cursor-pointer items-center">
+                  <input
+                    v-model="claudeConfig.claudeCodeOnlyEnabled"
+                    class="peer sr-only"
+                    type="checkbox"
+                    @change="saveClaudeConfig"
+                  />
+                  <div
+                    class="peer h-6 w-11 rounded-full bg-gray-200 after:absolute after:left-[2px] after:top-[2px] after:h-5 after:w-5 after:rounded-full after:border after:border-gray-300 after:bg-white after:transition-all after:content-[''] peer-checked:bg-orange-500 peer-checked:after:translate-x-full peer-checked:after:border-white peer-focus:outline-none peer-focus:ring-4 peer-focus:ring-orange-300 dark:border-gray-600 dark:bg-gray-700 dark:peer-focus:ring-orange-800"
+                  ></div>
+                </label>
+              </div>
+              <div class="mt-4 rounded-lg bg-amber-50 p-4 dark:bg-amber-900/20">
+                <div class="flex">
+                  <i class="fas fa-info-circle mt-0.5 text-amber-500"></i>
+                  <div class="ml-3">
+                    <p class="text-sm text-amber-700 dark:text-amber-300">
+                      此设置与 API Key 级别的客户端限制是 <strong>OR 逻辑</strong>：全局启用或 API
+                      Key 设置中启用，都会执行 Claude Code 验证。
+                    </p>
+                  </div>
+                </div>
+              </div>
+            </div>
+
+            <!-- 全局会话绑定 -->
+            <div
+              class="mb-6 rounded-lg bg-white/80 p-6 shadow-lg backdrop-blur-sm dark:bg-gray-800/80"
+            >
+              <div class="flex items-center justify-between">
+                <div>
+                  <div class="flex items-center">
+                    <div
+                      class="mr-3 flex h-10 w-10 items-center justify-center rounded-full bg-gradient-to-br from-purple-500 to-indigo-600 text-white shadow-lg"
+                    >
+                      <i class="fas fa-link"></i>
+                    </div>
+                    <div>
+                      <h2 class="text-lg font-semibold text-gray-800 dark:text-gray-200">
+                        强制会话绑定
+                      </h2>
+                      <p class="mt-1 text-sm text-gray-600 dark:text-gray-400">
+                        启用后，系统会将原始会话 ID 绑定到首次使用的账户，确保上下文的一致性
+                      </p>
+                    </div>
+                  </div>
+                </div>
+                <label class="relative inline-flex cursor-pointer items-center">
+                  <input
+                    v-model="claudeConfig.globalSessionBindingEnabled"
+                    class="peer sr-only"
+                    type="checkbox"
+                    @change="saveClaudeConfig"
+                  />
+                  <div
+                    class="peer h-6 w-11 rounded-full bg-gray-200 after:absolute after:left-[2px] after:top-[2px] after:h-5 after:w-5 after:rounded-full after:border after:border-gray-300 after:bg-white after:transition-all after:content-[''] peer-checked:bg-purple-500 peer-checked:after:translate-x-full peer-checked:after:border-white peer-focus:outline-none peer-focus:ring-4 peer-focus:ring-purple-300 dark:border-gray-600 dark:bg-gray-700 dark:peer-focus:ring-purple-800"
+                  ></div>
+                </label>
+              </div>
+
+              <!-- 绑定配置详情（仅在启用时显示） -->
+              <div v-if="claudeConfig.globalSessionBindingEnabled" class="mt-6 space-y-4">
+                <!-- 绑定有效期 -->
+                <div>
+                  <label class="block text-sm font-medium text-gray-700 dark:text-gray-300">
+                    <i class="fas fa-clock mr-2 text-gray-400"></i>
+                    绑定有效期（天）
+                  </label>
+                  <input
+                    v-model.number="claudeConfig.sessionBindingTtlDays"
+                    class="mt-1 block w-full max-w-xs rounded-lg border border-gray-300 bg-white px-3 py-2 shadow-sm focus:border-purple-500 focus:outline-none focus:ring-2 focus:ring-purple-500/20 dark:border-gray-500 dark:bg-gray-700 dark:text-white sm:text-sm"
+                    max="365"
+                    min="1"
+                    placeholder="30"
+                    type="number"
+                    @change="saveClaudeConfig"
+                  />
+                  <p class="mt-1 text-xs text-gray-500 dark:text-gray-400">
+                    会话绑定到账户后的有效时间，过期后会自动解除绑定
+                  </p>
+                </div>
+
+                <!-- 错误提示消息 -->
+                <div>
+                  <label class="block text-sm font-medium text-gray-700 dark:text-gray-300">
+                    <i class="fas fa-exclamation-triangle mr-2 text-gray-400"></i>
+                    旧会话污染提示
+                  </label>
+                  <textarea
+                    v-model="claudeConfig.sessionBindingErrorMessage"
+                    class="mt-1 block w-full rounded-lg border border-gray-300 bg-white px-3 py-2 shadow-sm focus:border-purple-500 focus:outline-none focus:ring-2 focus:ring-purple-500/20 dark:border-gray-500 dark:bg-gray-700 dark:text-white sm:text-sm"
+                    placeholder="你的本地session已污染，请清理后使用。"
+                    rows="2"
+                    @change="saveClaudeConfig"
+                  ></textarea>
+                  <p class="mt-1 text-xs text-gray-500 dark:text-gray-400">
+                    当检测到为旧的sessionId且未在系统中有调度记录时提示，返回给客户端的错误消息
+                  </p>
+                </div>
+              </div>
+
+              <div class="mt-4 rounded-lg bg-purple-50 p-4 dark:bg-purple-900/20">
+                <div class="flex">
+                  <i class="fas fa-lightbulb mt-0.5 text-purple-500"></i>
+                  <div class="ml-3">
+                    <p class="text-sm text-purple-700 dark:text-purple-300">
+                      <strong>工作原理：</strong>系统会提取请求中的原始 session ID （来自
+                      <code class="rounded bg-purple-100 px-1 dark:bg-purple-800"
+                        >metadata.user_id</code
+                      >）， 并将其与首次调度的账户绑定。后续使用相同 session ID
+                      的请求将自动路由到同一账户。
+                    </p>
+                    <p class="mt-2 text-sm text-purple-700 dark:text-purple-300">
+                      <strong>新会话识别：</strong>如果绑定会话历史中没有该sessionId但请求中
+                      <code class="rounded bg-purple-100 px-1 dark:bg-purple-800"
+                        >messages.length > 1</code
+                      >， 系统会认为这是一个污染的会话并拒绝请求。
+                    </p>
+                  </div>
+                </div>
+              </div>
+            </div>
+
+            <!-- 用户消息串行队列 -->
+            <div
+              class="mb-6 rounded-lg bg-white/80 p-6 shadow-lg backdrop-blur-sm dark:bg-gray-800/80"
+            >
+              <div class="flex items-center justify-between">
+                <div>
+                  <div class="flex items-center">
+                    <div
+                      class="mr-3 flex h-10 w-10 items-center justify-center rounded-full bg-gradient-to-br from-cyan-500 to-teal-600 text-white shadow-lg"
+                    >
+                      <i class="fas fa-list-ol"></i>
+                    </div>
+                    <div>
+                      <h2 class="text-lg font-semibold text-gray-800 dark:text-gray-200">
+                        用户消息串行队列
+                      </h2>
+                      <p class="mt-1 text-sm text-gray-600 dark:text-gray-400">
+                        启用后，同一账户的用户消息请求将串行执行，并在请求之间添加延迟，防止触发上游限流
+                      </p>
+                    </div>
+                  </div>
+                </div>
+                <label class="relative inline-flex cursor-pointer items-center">
+                  <input
+                    v-model="claudeConfig.userMessageQueueEnabled"
+                    class="peer sr-only"
+                    type="checkbox"
+                    @change="saveClaudeConfig"
+                  />
+                  <div
+                    class="peer h-6 w-11 rounded-full bg-gray-200 after:absolute after:left-[2px] after:top-[2px] after:h-5 after:w-5 after:rounded-full after:border after:border-gray-300 after:bg-white after:transition-all after:content-[''] peer-checked:bg-teal-500 peer-checked:after:translate-x-full peer-checked:after:border-white peer-focus:outline-none peer-focus:ring-4 peer-focus:ring-teal-300 dark:border-gray-600 dark:bg-gray-700 dark:peer-focus:ring-teal-800"
+                  ></div>
+                </label>
+              </div>
+
+              <!-- 队列配置详情（仅在启用时显示） -->
+              <div v-if="claudeConfig.userMessageQueueEnabled" class="mt-6 space-y-4">
+                <!-- 请求间隔 -->
+                <div>
+                  <label class="block text-sm font-medium text-gray-700 dark:text-gray-300">
+                    <i class="fas fa-hourglass-half mr-2 text-gray-400"></i>
+                    请求间隔（毫秒）
+                  </label>
+                  <input
+                    v-model.number="claudeConfig.userMessageQueueDelayMs"
+                    class="mt-1 block w-full max-w-xs rounded-lg border border-gray-300 bg-white px-3 py-2 shadow-sm focus:border-teal-500 focus:outline-none focus:ring-2 focus:ring-teal-500/20 dark:border-gray-500 dark:bg-gray-700 dark:text-white sm:text-sm"
+                    max="10000"
+                    min="0"
+                    placeholder="200"
+                    type="number"
+                    @change="saveClaudeConfig"
+                  />
+                  <p class="mt-1 text-xs text-gray-500 dark:text-gray-400">
+                    同一账户的用户消息请求之间的最小间隔时间（0-10000毫秒）
+                  </p>
+                </div>
+
+                <!-- 队列超时 -->
+                <div>
+                  <label class="block text-sm font-medium text-gray-700 dark:text-gray-300">
+                    <i class="fas fa-stopwatch mr-2 text-gray-400"></i>
+                    队列超时（毫秒）
+                  </label>
+                  <input
+                    v-model.number="claudeConfig.userMessageQueueTimeoutMs"
+                    class="mt-1 block w-full max-w-xs rounded-lg border border-gray-300 bg-white px-3 py-2 shadow-sm focus:border-teal-500 focus:outline-none focus:ring-2 focus:ring-teal-500/20 dark:border-gray-500 dark:bg-gray-700 dark:text-white sm:text-sm"
+                    max="300000"
+                    min="1000"
+                    placeholder="30000"
+                    type="number"
+                    @change="saveClaudeConfig"
+                  />
+                  <p class="mt-1 text-xs text-gray-500 dark:text-gray-400">
+                    请求在队列中等待的最大时间，超时将返回 503 错误（1000-300000毫秒）
+                  </p>
+                </div>
+              </div>
+
+              <div class="mt-4 rounded-lg bg-teal-50 p-4 dark:bg-teal-900/20">
+                <div class="flex">
+                  <i class="fas fa-info-circle mt-0.5 text-teal-500"></i>
+                  <div class="ml-3">
+                    <p class="text-sm text-teal-700 dark:text-teal-300">
+                      <strong>工作原理：</strong>系统检测请求中最后一条消息的
+                      <code class="rounded bg-teal-100 px-1 dark:bg-teal-800">role</code>
+                      是否为
+                      <code class="rounded bg-teal-100 px-1 dark:bg-teal-800">user</code
+                      >。用户消息请求需要排队串行执行，而工具调用结果、助手消息续传等不受此限制。
+                    </p>
+                  </div>
+                </div>
+              </div>
+            </div>
+
+            <!-- 并发请求排队 -->
+            <div
+              class="mb-6 rounded-lg bg-white/80 p-6 shadow-lg backdrop-blur-sm dark:bg-gray-800/80"
+            >
+              <div class="flex items-center justify-between">
+                <div class="flex items-center">
+                  <div
+                    class="flex h-12 w-12 items-center justify-center rounded-lg bg-gradient-to-r from-blue-500 to-cyan-500 text-white shadow-lg"
+                  >
+                    <i class="fas fa-layer-group text-xl"></i>
+                  </div>
+                  <div class="ml-4">
+                    <h4 class="text-lg font-semibold text-gray-900 dark:text-white">
+                      并发请求排队
+                    </h4>
+                    <p class="text-sm text-gray-500 dark:text-gray-400">
+                      当 API Key 并发请求超限时进入队列等待，而非直接拒绝
+                    </p>
+                  </div>
+                </div>
+                <label class="relative inline-flex cursor-pointer items-center">
+                  <input
+                    v-model="claudeConfig.concurrentRequestQueueEnabled"
+                    class="peer sr-only"
+                    type="checkbox"
+                    @change="saveClaudeConfig"
+                  />
+                  <div
+                    class="peer h-6 w-11 rounded-full bg-gray-200 after:absolute after:left-[2px] after:top-[2px] after:h-5 after:w-5 after:rounded-full after:border after:border-gray-300 after:bg-white after:transition-all after:content-[''] peer-checked:bg-blue-500 peer-checked:after:translate-x-full peer-checked:after:border-white peer-focus:outline-none peer-focus:ring-4 peer-focus:ring-blue-300 dark:border-gray-600 dark:bg-gray-700 dark:peer-focus:ring-blue-800"
+                  ></div>
+                </label>
+              </div>
+
+              <!-- 排队配置详情（仅在启用时显示） -->
+              <div v-if="claudeConfig.concurrentRequestQueueEnabled" class="mt-6 space-y-4">
+                <!-- 固定最小排队数 -->
+                <div>
+                  <label class="block text-sm font-medium text-gray-700 dark:text-gray-300">
+                    <i class="fas fa-list-ol mr-2 text-gray-400"></i>
+                    固定最小排队数
+                  </label>
+                  <input
+                    v-model.number="claudeConfig.concurrentRequestQueueMaxSize"
+                    class="mt-1 block w-full max-w-xs rounded-lg border border-gray-300 bg-white px-3 py-2 shadow-sm focus:border-blue-500 focus:outline-none focus:ring-2 focus:ring-blue-500/20 dark:border-gray-500 dark:bg-gray-700 dark:text-white sm:text-sm"
+                    max="100"
+                    min="1"
+                    placeholder="3"
+                    type="number"
+                    @change="saveClaudeConfig"
+                  />
+                  <p class="mt-1 text-xs text-gray-500 dark:text-gray-400">
+                    最大排队数的固定最小值（1-100）
+                  </p>
+                </div>
+
+                <!-- 排队数倍数 -->
+                <div>
+                  <label class="block text-sm font-medium text-gray-700 dark:text-gray-300">
+                    <i class="fas fa-times mr-2 text-gray-400"></i>
+                    排队数倍数
+                  </label>
+                  <input
+                    v-model.number="claudeConfig.concurrentRequestQueueMaxSizeMultiplier"
+                    class="mt-1 block w-full max-w-xs rounded-lg border border-gray-300 bg-white px-3 py-2 shadow-sm focus:border-blue-500 focus:outline-none focus:ring-2 focus:ring-blue-500/20 dark:border-gray-500 dark:bg-gray-700 dark:text-white sm:text-sm"
+                    max="10"
+                    min="0"
+                    placeholder="1"
+                    step="0.5"
+                    type="number"
+                    @change="saveClaudeConfig"
+                  />
+                  <p class="mt-1 text-xs text-gray-500 dark:text-gray-400">
+                    最大排队数 = MAX(倍数 × 并发限制, 固定值)，设为 0 则仅使用固定值
+                  </p>
+                </div>
+
+                <!-- 排队超时时间 -->
+                <div>
+                  <label class="block text-sm font-medium text-gray-700 dark:text-gray-300">
+                    <i class="fas fa-stopwatch mr-2 text-gray-400"></i>
+                    排队超时时间（毫秒）
+                  </label>
+                  <input
+                    v-model.number="claudeConfig.concurrentRequestQueueTimeoutMs"
+                    class="mt-1 block w-full max-w-xs rounded-lg border border-gray-300 bg-white px-3 py-2 shadow-sm focus:border-blue-500 focus:outline-none focus:ring-2 focus:ring-blue-500/20 dark:border-gray-500 dark:bg-gray-700 dark:text-white sm:text-sm"
+                    max="300000"
+                    min="5000"
+                    placeholder="10000"
+                    type="number"
+                    @change="saveClaudeConfig"
+                  />
+                  <p class="mt-1 text-xs text-gray-500 dark:text-gray-400">
+                    请求在排队中等待的最大时间，超时将返回 429 错误（5秒-5分钟，默认10秒）
+                  </p>
+                </div>
+              </div>
+
+              <div class="mt-4 rounded-lg bg-blue-50 p-4 dark:bg-blue-900/20">
+                <div class="flex">
+                  <i class="fas fa-info-circle mt-0.5 text-blue-500"></i>
+                  <div class="ml-3">
+                    <p class="text-sm text-blue-700 dark:text-blue-300">
+                      <strong>工作原理：</strong>当 API Key 的并发请求超过
+                      <code class="rounded bg-blue-100 px-1 dark:bg-blue-800"
+                        >concurrencyLimit</code
+                      >
+                      时，超限请求会进入队列等待而非直接返回 429。适合 Claude Code Agent
+                      并行工具调用场景。
+                    </p>
+                  </div>
+                </div>
+              </div>
+            </div>
+
+            <!-- 配置更新信息 -->
+            <div
+              v-if="claudeConfig.updatedAt"
+              class="rounded-lg bg-gray-50 p-4 text-sm text-gray-500 dark:bg-gray-700/50 dark:text-gray-400"
+            >
+              <i class="fas fa-history mr-2"></i>
+              最后更新：{{ formatDateTime(claudeConfig.updatedAt) }}
+              <span v-if="claudeConfig.updatedBy" class="ml-2">
+                由 <strong>{{ claudeConfig.updatedBy }}</strong> 修改
+              </span>
+            </div>
+          </div>
+        </div>
       </div>
     </div>
   </div>
@@ -1274,6 +1670,24 @@ const webhookConfig = ref({
   }
 })
 
+// Claude 转发配置
+const claudeConfigLoading = ref(false)
+const claudeConfig = ref({
+  claudeCodeOnlyEnabled: false,
+  globalSessionBindingEnabled: false,
+  sessionBindingErrorMessage: '你的本地session已污染，请清理后使用。',
+  sessionBindingTtlDays: 30,
+  userMessageQueueEnabled: false, // 与后端默认值保持一致
+  userMessageQueueDelayMs: 200,
+  userMessageQueueTimeoutMs: 5000, // 与后端默认值保持一致（优化后锁持有时间短无需长等待）
+  concurrentRequestQueueEnabled: false,
+  concurrentRequestQueueMaxSize: 3,
+  concurrentRequestQueueMaxSizeMultiplier: 0,
+  concurrentRequestQueueTimeoutMs: 10000,
+  updatedAt: null,
+  updatedBy: null
+})
+
 // 平台表单相关
 const showAddPlatformModal = ref(false)
 const editingPlatform = ref(null)
@@ -1311,6 +1725,8 @@ const sectionWatcher = watch(activeSection, async (newSection) => {
   if (!isMounted.value) return
   if (newSection === 'webhook') {
     await loadWebhookConfig()
+  } else if (newSection === 'claude') {
+    await loadClaudeConfig()
   }
 })
 
@@ -1522,6 +1938,83 @@ const saveWebhookConfig = async () => {
   }
 }
 
+// 加载 Claude 转发配置
+const loadClaudeConfig = async () => {
+  if (!isMounted.value) return
+  claudeConfigLoading.value = true
+  try {
+    const response = await apiClient.get('/admin/claude-relay-config', {
+      signal: abortController.value.signal
+    })
+    if (response.success && isMounted.value) {
+      claudeConfig.value = {
+        claudeCodeOnlyEnabled: response.config?.claudeCodeOnlyEnabled ?? false,
+        globalSessionBindingEnabled: response.config?.globalSessionBindingEnabled ?? false,
+        sessionBindingErrorMessage:
+          response.config?.sessionBindingErrorMessage || '你的本地session已污染，请清理后使用。',
+        sessionBindingTtlDays: response.config?.sessionBindingTtlDays ?? 30,
+        userMessageQueueEnabled: response.config?.userMessageQueueEnabled ?? false, // 与后端默认值保持一致
+        userMessageQueueDelayMs: response.config?.userMessageQueueDelayMs ?? 200,
+        userMessageQueueTimeoutMs: response.config?.userMessageQueueTimeoutMs ?? 5000, // 与后端默认值保持一致
+        concurrentRequestQueueEnabled: response.config?.concurrentRequestQueueEnabled ?? false,
+        concurrentRequestQueueMaxSize: response.config?.concurrentRequestQueueMaxSize ?? 3,
+        concurrentRequestQueueMaxSizeMultiplier:
+          response.config?.concurrentRequestQueueMaxSizeMultiplier ?? 0,
+        concurrentRequestQueueTimeoutMs: response.config?.concurrentRequestQueueTimeoutMs ?? 10000,
+        updatedAt: response.config?.updatedAt || null,
+        updatedBy: response.config?.updatedBy || null
+      }
+    }
+  } catch (error) {
+    if (error.name === 'AbortError') return
+    if (!isMounted.value) return
+    showToast('获取 Claude 转发配置失败', 'error')
+    console.error(error)
+  } finally {
+    if (isMounted.value) {
+      claudeConfigLoading.value = false
+    }
+  }
+}
+
+// 保存 Claude 转发配置
+const saveClaudeConfig = async () => {
+  if (!isMounted.value) return
+  try {
+    const payload = {
+      claudeCodeOnlyEnabled: claudeConfig.value.claudeCodeOnlyEnabled,
+      globalSessionBindingEnabled: claudeConfig.value.globalSessionBindingEnabled,
+      sessionBindingErrorMessage: claudeConfig.value.sessionBindingErrorMessage,
+      sessionBindingTtlDays: claudeConfig.value.sessionBindingTtlDays,
+      userMessageQueueEnabled: claudeConfig.value.userMessageQueueEnabled,
+      userMessageQueueDelayMs: claudeConfig.value.userMessageQueueDelayMs,
+      userMessageQueueTimeoutMs: claudeConfig.value.userMessageQueueTimeoutMs,
+      concurrentRequestQueueEnabled: claudeConfig.value.concurrentRequestQueueEnabled,
+      concurrentRequestQueueMaxSize: claudeConfig.value.concurrentRequestQueueMaxSize,
+      concurrentRequestQueueMaxSizeMultiplier:
+        claudeConfig.value.concurrentRequestQueueMaxSizeMultiplier,
+      concurrentRequestQueueTimeoutMs: claudeConfig.value.concurrentRequestQueueTimeoutMs
+    }
+
+    const response = await apiClient.put('/admin/claude-relay-config', payload, {
+      signal: abortController.value.signal
+    })
+    if (response.success && isMounted.value) {
+      claudeConfig.value = {
+        ...claudeConfig.value,
+        updatedAt: response.config?.updatedAt || new Date().toISOString(),
+        updatedBy: response.config?.updatedBy || null
+      }
+      showToast('Claude 转发配置已保存', 'success')
+    }
+  } catch (error) {
+    if (error.name === 'AbortError') return
+    if (!isMounted.value) return
+    showToast('保存 Claude 转发配置失败', 'error')
+    console.error(error)
+  }
+}
+
 // 验证 URL
 const validateUrl = () => {
   // Bark和SMTP平台不需要验证URL