feat: add provider compatibility error detection for intelligent failover

- Introduce ProviderCompatibilityException for unsupported parameter/feature errors
- Add COMPATIBILITY_ERROR_PATTERNS to detect provider-specific limitations
- Implement _is_compatibility_error() method in ErrorClassifier
- Prioritize compatibility error checking before client error validation
- Remove 'max_tokens' from CLIENT_ERROR_PATTERNS as it can indicate compatibility issues
- Enable automatic failover when provider doesn't support requested features
- Improve error classification accuracy with pattern matching for common compatibility issues

.github/workflows/docker-publish.yml

@@ -15,6 +15,8 @@ env:
   REGISTRY: ghcr.io
   BASE_IMAGE_NAME: fawney19/aether-base
   APP_IMAGE_NAME: fawney19/aether
+  # Files that affect base image - used for hash calculation
+  BASE_FILES: "Dockerfile.base pyproject.toml frontend/package.json frontend/package-lock.json"
 
 jobs:
   check-base-changes:
@@ -23,8 +25,13 @@ jobs:
       base_changed: ${{ steps.check.outputs.base_changed }}
     steps:
       - uses: actions/checkout@v4
+
+      - name: Log in to Container Registry
+        uses: docker/login-action@v3
         with:
-          fetch-depth: 2
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Check if base image needs rebuild
         id: check
@@ -34,10 +41,26 @@ jobs:
             exit 0
           fi
 
-          # Check if base-related files changed
-          if git diff --name-only HEAD~1 HEAD | grep -qE '^(Dockerfile\.base|pyproject\.toml|frontend/package.*\.json)$'; then
+          # Calculate current hash of base-related files
+          CURRENT_HASH=$(cat ${{ env.BASE_FILES }} 2>/dev/null | sha256sum | cut -d' ' -f1)
+          echo "Current base files hash: $CURRENT_HASH"
+
+          # Try to get hash label from remote image config
+          # Pull the image config and extract labels
+          REMOTE_HASH=""
+          if docker pull ${{ env.REGISTRY }}/${{ env.BASE_IMAGE_NAME }}:latest 2>/dev/null; then
+            REMOTE_HASH=$(docker inspect ${{ env.REGISTRY }}/${{ env.BASE_IMAGE_NAME }}:latest --format '{{ index .Config.Labels "org.opencontainers.image.base.hash" }}' 2>/dev/null) || true
+          fi
+
+          if [ -z "$REMOTE_HASH" ] || [ "$REMOTE_HASH" == "<no value>" ]; then
+            # No remote image or no hash label, need to rebuild
+            echo "No remote base image or hash label found, need rebuild"
+            echo "base_changed=true" >> $GITHUB_OUTPUT
+          elif [ "$CURRENT_HASH" != "$REMOTE_HASH" ]; then
+            echo "Hash mismatch: remote=$REMOTE_HASH, current=$CURRENT_HASH"
             echo "base_changed=true" >> $GITHUB_OUTPUT
           else
+            echo "Hash matches, no rebuild needed"
             echo "base_changed=false" >> $GITHUB_OUTPUT
           fi
 
@@ -61,6 +84,12 @@ jobs:
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
+      - name: Calculate base files hash
+        id: hash
+        run: |
+          HASH=$(cat ${{ env.BASE_FILES }} 2>/dev/null | sha256sum | cut -d' ' -f1)
+          echo "hash=$HASH" >> $GITHUB_OUTPUT
+
       - name: Extract metadata for base image
         id: meta
         uses: docker/metadata-action@v5
@@ -69,6 +98,8 @@ jobs:
           tags: |
             type=raw,value=latest
             type=sha,prefix=
+          labels: |
+            org.opencontainers.image.base.hash=${{ steps.hash.outputs.hash }}
 
       - name: Build and push base image
         uses: docker/build-push-action@v5

Dockerfile.base

@@ -19,7 +19,7 @@ RUN apt-get update && apt-get install -y \
 # Python 依赖（安装到系统，不用 -e 模式）
 COPY pyproject.toml README.md ./
 RUN mkdir -p src && touch src/__init__.py && \
-    pip install --no-cache-dir .
+    SETUPTOOLS_SCM_PRETEND_VERSION=0.1.0 pip install --no-cache-dir .
 
 # 前端依赖
 COPY frontend/package*.json /tmp/frontend/
@@ -70,6 +70,8 @@ RUN printf '%s\n' \
 '        proxy_cache off;' \
 '        proxy_request_buffering off;' \
 '        chunked_transfer_encoding on;' \
+'        gzip off;' \
+'        add_header X-Accel-Buffering no;' \
 '        proxy_connect_timeout 600s;' \
 '        proxy_send_timeout 600s;' \
 '        proxy_read_timeout 600s;' \

Dockerfile.base.local

@@ -74,6 +74,8 @@ RUN printf '%s\n' \
 '        proxy_cache off;' \
 '        proxy_request_buffering off;' \
 '        chunked_transfer_encoding on;' \
+'        gzip off;' \
+'        add_header X-Accel-Buffering no;' \
 '        proxy_connect_timeout 600s;' \
 '        proxy_send_timeout 600s;' \
 '        proxy_read_timeout 600s;' \

alembic/versions/20251218_0631_f30f9936f6a2_add_proxy_field_to_provider_endpoints.py

@@ -0,0 +1,57 @@
+"""add proxy field to provider_endpoints
+
+Revision ID: f30f9936f6a2
+Revises: 1cc6942cf06f
+Create Date: 2025-12-18 06:31:58.451112+00:00
+
+"""
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects.postgresql import JSONB
+from sqlalchemy import inspect
+
+# revision identifiers, used by Alembic.
+revision = 'f30f9936f6a2'
+down_revision = '1cc6942cf06f'
+branch_labels = None
+depends_on = None
+
+
+def column_exists(table_name: str, column_name: str) -> bool:
+    """检查列是否存在"""
+    bind = op.get_bind()
+    inspector = inspect(bind)
+    columns = [col['name'] for col in inspector.get_columns(table_name)]
+    return column_name in columns
+
+
+def get_column_type(table_name: str, column_name: str) -> str:
+    """获取列的类型"""
+    bind = op.get_bind()
+    inspector = inspect(bind)
+    for col in inspector.get_columns(table_name):
+        if col['name'] == column_name:
+            return str(col['type']).upper()
+    return ''
+
+
+def upgrade() -> None:
+    """添加 proxy 字段到 provider_endpoints 表"""
+    if not column_exists('provider_endpoints', 'proxy'):
+        # 字段不存在，直接添加 JSONB 类型
+        op.add_column('provider_endpoints', sa.Column('proxy', JSONB(), nullable=True))
+    else:
+        # 字段已存在，检查是否需要转换类型
+        col_type = get_column_type('provider_endpoints', 'proxy')
+        if 'JSONB' not in col_type:
+            # 如果是 JSON 类型，转换为 JSONB
+            op.execute(
+                'ALTER TABLE provider_endpoints '
+                'ALTER COLUMN proxy TYPE JSONB USING proxy::jsonb'
+            )
+
+
+def downgrade() -> None:
+    """移除 proxy 字段"""
+    if column_exists('provider_endpoints', 'proxy'):
+        op.drop_column('provider_endpoints', 'proxy')

deploy.sh

@@ -21,9 +21,9 @@ HASH_FILE=".deps-hash"
 CODE_HASH_FILE=".code-hash"
 MIGRATION_HASH_FILE=".migration-hash"
 
-# 计算依赖文件的哈希值
+# 计算依赖文件的哈希值（包含 Dockerfile.base.local）
 calc_deps_hash() {
-    cat pyproject.toml frontend/package.json frontend/package-lock.json 2>/dev/null | md5sum | cut -d' ' -f1
+    cat pyproject.toml frontend/package.json frontend/package-lock.json Dockerfile.base.local 2>/dev/null | md5sum | cut -d' ' -f1
 }
 
 # 计算代码文件的哈希值
@@ -162,25 +162,32 @@ git pull
 
 # 标记是否需要重启
 NEED_RESTART=false
+BASE_REBUILT=false
 
 # 检查基础镜像是否存在，或依赖是否变化
 if ! docker image inspect aether-base:latest >/dev/null 2>&1; then
     echo ">>> Base image not found, building..."
     build_base
+    BASE_REBUILT=true
     NEED_RESTART=true
 elif check_deps_changed; then
     echo ">>> Dependencies changed, rebuilding base image..."
     build_base
+    BASE_REBUILT=true
     NEED_RESTART=true
 else
     echo ">>> Dependencies unchanged."
 fi
 
-# 检查代码是否变化
+# 检查代码是否变化，或者 base 重建了（app 依赖 base）
 if ! docker image inspect aether-app:latest >/dev/null 2>&1; then
     echo ">>> App image not found, building..."
     build_app
     NEED_RESTART=true
+elif [ "$BASE_REBUILT" = true ]; then
+    echo ">>> Base image rebuilt, rebuilding app image..."
+    build_app
+    NEED_RESTART=true
 elif check_code_changed; then
     echo ">>> Code changed, rebuilding app image..."
     build_app

frontend/src/api/cache.ts

@@ -66,6 +66,7 @@ export interface UserAffinity {
   key_name: string | null
   key_prefix: string | null  // Provider Key 脱敏显示（前4...后4）
   rate_multiplier: number
+  global_model_id: string | null  // 原始的 global_model_id（用于删除）
   model_name: string | null  // 模型名称（如 claude-haiku-4-5-20250514）
   model_display_name: string | null  // 模型显示名称（如 Claude Haiku 4.5）
   api_format: string | null  // API 格式 (claude/openai)
@@ -119,6 +120,18 @@ export const cacheApi = {
     await api.delete(`/api/admin/monitoring/cache/users/${userIdentifier}`)
   },
 
+  /**
+   * 清除单条缓存亲和性
+   *
+   * @param affinityKey API Key ID
+   * @param endpointId Endpoint ID
+   * @param modelId GlobalModel ID
+   * @param apiFormat API 格式 (claude/openai)
+   */
+  async clearSingleAffinity(affinityKey: string, endpointId: string, modelId: string, apiFormat: string): Promise<void> {
+    await api.delete(`/api/admin/monitoring/cache/affinity/${affinityKey}/${endpointId}/${modelId}/${apiFormat}`)
+  },
+
   /**
    * 清除所有缓存
    */

frontend/src/api/endpoints/endpoints.ts

@@ -1,5 +1,5 @@
 import client from '../client'
-import type { ProviderEndpoint } from './types'
+import type { ProviderEndpoint, ProxyConfig } from './types'
 
 /**
  * 获取指定 Provider 的所有 Endpoints
@@ -38,6 +38,7 @@ export async function createEndpoint(
     rate_limit?: number
     is_active?: boolean
     config?: Record<string, any>
+    proxy?: ProxyConfig | null
   }
 ): Promise<ProviderEndpoint> {
   const response = await client.post(`/api/admin/endpoints/providers/${providerId}/endpoints`, data)
@@ -63,6 +64,7 @@ export async function updateEndpoint(
     rate_limit: number
     is_active: boolean
     config: Record<string, any>
+    proxy: ProxyConfig | null
   }>
 ): Promise<ProviderEndpoint> {
   const response = await client.put(`/api/admin/endpoints/${endpointId}`, data)

frontend/src/api/endpoints/types.ts

@@ -20,6 +20,16 @@ export const API_FORMAT_LABELS: Record<string, string> = {
   [API_FORMATS.GEMINI_CLI]: 'Gemini CLI',
 }
 
+/**
+ * 代理配置类型
+ */
+export interface ProxyConfig {
+  url: string
+  username?: string
+  password?: string
+  enabled?: boolean  // 是否启用代理（false 时保留配置但不使用）
+}
+
 export interface ProviderEndpoint {
   id: string
   provider_id: string
@@ -41,6 +51,7 @@ export interface ProviderEndpoint {
   last_failure_at?: string
   is_active: boolean
   config?: Record<string, any>
+  proxy?: ProxyConfig | null
   total_keys: number
   active_keys: number
   created_at: string

frontend/src/components/ui/dialog/Dialog.vue

@@ -22,7 +22,7 @@
         />
       </Transition>
 
-      <div class="relative flex min-h-full items-end justify-center p-4 text-center sm:items-center sm:p-0">
+      <div class="relative flex min-h-full items-end justify-center p-4 text-center sm:items-center sm:p-0 pointer-events-none">
         <!-- 对话框内容 -->
         <Transition
           enter-active-class="duration-300 ease-out"

frontend/src/features/api-keys/components/StandaloneKeyFormDialog.vue

@@ -132,7 +132,7 @@
               type="number"
               min="1"
               max="10000"
-              placeholder="100"
+              placeholder="留空不限制"
               class="h-10"
               @update:model-value="(v) => form.rate_limit = parseNumberInput(v, { min: 1, max: 10000 })"
             />
@@ -376,7 +376,7 @@ const form = ref<StandaloneKeyFormData>({
   initial_balance_usd: 10,
   expire_days: undefined,
   never_expire: true,
-  rate_limit: 100,
+  rate_limit: undefined,
   auto_delete_on_expiry: false,
   allowed_providers: [],
   allowed_api_formats: [],
@@ -389,7 +389,7 @@ function resetForm() {
     initial_balance_usd: 10,
     expire_days: undefined,
     never_expire: true,
-    rate_limit: 100,
+    rate_limit: undefined,
     auto_delete_on_expiry: false,
     allowed_providers: [],
     allowed_api_formats: [],
@@ -408,7 +408,7 @@ function loadKeyData() {
     initial_balance_usd: props.apiKey.initial_balance_usd,
     expire_days: props.apiKey.expire_days,
     never_expire: props.apiKey.never_expire,
-    rate_limit: props.apiKey.rate_limit || 100,
+    rate_limit: props.apiKey.rate_limit,
     auto_delete_on_expiry: props.apiKey.auto_delete_on_expiry,
     allowed_providers: props.apiKey.allowed_providers || [],
     allowed_api_formats: props.apiKey.allowed_api_formats || [],

frontend/src/features/providers/components/EndpointFormDialog.vue

@@ -9,7 +9,7 @@
   >
     <form
       class="space-y-6"
-      @submit.prevent="handleSubmit"
+      @submit.prevent="handleSubmit()"
     >
       <!-- API 配置 -->
       <div class="space-y-4">
@@ -132,6 +132,79 @@
           </div>
         </div>
       </div>
+
+      <!-- 代理配置 -->
+      <div class="space-y-4">
+        <div class="flex items-center justify-between">
+          <h3 class="text-sm font-medium">
+            代理配置
+          </h3>
+          <div class="flex items-center gap-2">
+            <Switch v-model="proxyEnabled" />
+            <span class="text-sm text-muted-foreground">启用代理</span>
+          </div>
+        </div>
+
+        <div
+          v-if="proxyEnabled"
+          class="space-y-4 rounded-lg border p-4"
+        >
+          <div class="space-y-2">
+            <Label for="proxy_url">代理 URL *</Label>
+            <Input
+              id="proxy_url"
+              v-model="form.proxy_url"
+              placeholder="http://host:port 或 socks5://host:port"
+              required
+              :class="proxyUrlError ? 'border-red-500' : ''"
+            />
+            <p
+              v-if="proxyUrlError"
+              class="text-xs text-red-500"
+            >
+              {{ proxyUrlError }}
+            </p>
+            <p
+              v-else
+              class="text-xs text-muted-foreground"
+            >
+              支持 HTTP、HTTPS、SOCKS5 代理
+            </p>
+          </div>
+
+          <div class="grid grid-cols-2 gap-4">
+            <div class="space-y-2">
+              <Label for="proxy_user">用户名（可选）</Label>
+              <Input
+                :id="`proxy_user_${formId}`"
+                :name="`proxy_user_${formId}`"
+                v-model="form.proxy_username"
+                placeholder="代理认证用户名"
+                autocomplete="off"
+                data-form-type="other"
+                data-lpignore="true"
+                data-1p-ignore="true"
+              />
+            </div>
+
+            <div class="space-y-2">
+              <Label :for="`proxy_pass_${formId}`">密码（可选）</Label>
+              <Input
+                :id="`proxy_pass_${formId}`"
+                :name="`proxy_pass_${formId}`"
+                v-model="form.proxy_password"
+                type="text"
+                :placeholder="passwordPlaceholder"
+                autocomplete="off"
+                data-form-type="other"
+                data-lpignore="true"
+                data-1p-ignore="true"
+                :style="{ '-webkit-text-security': 'disc', 'text-security': 'disc' }"
+              />
+            </div>
+          </div>
+        </div>
+      </div>
     </form>
 
     <template #footer>
@@ -145,12 +218,24 @@
       </Button>
       <Button
         :disabled="loading || !form.base_url || (!isEditMode && !form.api_format)"
-        @click="handleSubmit"
+        @click="handleSubmit()"
       >
         {{ loading ? (isEditMode ? '保存中...' : '创建中...') : (isEditMode ? '保存修改' : '创建') }}
       </Button>
     </template>
   </Dialog>
+
+  <!-- 确认清空凭据对话框 -->
+  <AlertDialog
+    v-model="showClearCredentialsDialog"
+    title="清空代理凭据"
+    description="代理 URL 为空，但用户名和密码仍有值。是否清空这些凭据并继续保存？"
+    type="warning"
+    confirm-text="清空并保存"
+    cancel-text="返回编辑"
+    @confirm="confirmClearCredentials"
+    @cancel="showClearCredentialsDialog = false"
+  />
 </template>
 
 <script setup lang="ts">
@@ -165,7 +250,9 @@ import {
   SelectValue,
   SelectContent,
   SelectItem,
+  Switch,
 } from '@/components/ui'
+import AlertDialog from '@/components/common/AlertDialog.vue'
 import { Link, SquarePen } from 'lucide-vue-next'
 import { useToast } from '@/composables/useToast'
 import { useFormDialog } from '@/composables/useFormDialog'
@@ -194,6 +281,11 @@ const emit = defineEmits<{
 const { success, error: showError } = useToast()
 const loading = ref(false)
 const selectOpen = ref(false)
+const proxyEnabled = ref(false)
+const showClearCredentialsDialog = ref(false)  // 确认清空凭据对话框
+
+// 生成随机 ID 防止浏览器自动填充
+const formId = Math.random().toString(36).substring(2, 10)
 
 // 内部状态
 const internalOpen = computed(() => props.modelValue)
@@ -207,7 +299,11 @@ const form = ref({
   max_retries: 3,
   max_concurrent: undefined as number | undefined,
   rate_limit: undefined as number | undefined,
-  is_active: true
+  is_active: true,
+  // 代理配置
+  proxy_url: '',
+  proxy_username: '',
+  proxy_password: '',
 })
 
 // API 格式列表
@@ -237,6 +333,53 @@ const defaultPathPlaceholder = computed(() => {
   return `留空使用默认路径：${defaultPath.value}`
 })
 
+// 检查是否有已保存的密码（后端返回 *** 表示有密码）
+const hasExistingPassword = computed(() => {
+  if (!props.endpoint?.proxy) return false
+  const proxy = props.endpoint.proxy as { password?: string }
+  return proxy?.password === MASKED_PASSWORD
+})
+
+// 密码输入框的 placeholder
+const passwordPlaceholder = computed(() => {
+  if (hasExistingPassword.value) {
+    return '已保存密码，留空保持不变'
+  }
+  return '代理认证密码'
+})
+
+// 代理 URL 验证
+const proxyUrlError = computed(() => {
+  // 只有启用代理且填写了 URL 时才验证
+  if (!proxyEnabled.value || !form.value.proxy_url) {
+    return ''
+  }
+  const url = form.value.proxy_url.trim()
+
+  // 检查禁止的特殊字符
+  if (/[\n\r]/.test(url)) {
+    return '代理 URL 包含非法字符'
+  }
+
+  // 验证协议（不支持 SOCKS4）
+  if (!/^(http|https|socks5):\/\//i.test(url)) {
+    return '代理 URL 必须以 http://, https:// 或 socks5:// 开头'
+  }
+  try {
+    const parsed = new URL(url)
+    if (!parsed.host) {
+      return '代理 URL 必须包含有效的 host'
+    }
+    // 禁止 URL 中内嵌认证信息
+    if (parsed.username || parsed.password) {
+      return '请勿在 URL 中包含用户名和密码，请使用独立的认证字段'
+    }
+  } catch {
+    return '代理 URL 格式无效'
+  }
+  return ''
+})
+
 // 组件挂载时加载API格式
 onMounted(() => {
   loadApiFormats()
@@ -252,14 +395,23 @@ function resetForm() {
     max_retries: 3,
     max_concurrent: undefined,
     rate_limit: undefined,
-    is_active: true
+    is_active: true,
+    proxy_url: '',
+    proxy_username: '',
+    proxy_password: '',
   }
+  proxyEnabled.value = false
 }
 
+// 原始密码占位符（后端返回的脱敏标记）
+const MASKED_PASSWORD = '***'
+
 // 加载端点数据（编辑模式）
 function loadEndpointData() {
   if (!props.endpoint) return
 
+  const proxy = props.endpoint.proxy as { url?: string; username?: string; password?: string; enabled?: boolean } | null
+
   form.value = {
     api_format: props.endpoint.api_format,
     base_url: props.endpoint.base_url,
@@ -268,8 +420,15 @@ function loadEndpointData() {
     max_retries: props.endpoint.max_retries,
     max_concurrent: props.endpoint.max_concurrent || undefined,
     rate_limit: props.endpoint.rate_limit || undefined,
-    is_active: props.endpoint.is_active
+    is_active: props.endpoint.is_active,
+    proxy_url: proxy?.url || '',
+    proxy_username: proxy?.username || '',
+    // 如果密码是脱敏标记，显示为空（让用户知道有密码但看不到）
+    proxy_password: proxy?.password === MASKED_PASSWORD ? '' : (proxy?.password || ''),
   }
+
+  // 根据 enabled 字段或 url 存在判断是否启用代理
+  proxyEnabled.value = proxy?.enabled ?? !!proxy?.url
 }
 
 // 使用 useFormDialog 统一处理对话框逻辑
@@ -282,12 +441,47 @@ const { isEditMode, handleDialogUpdate, handleCancel } = useFormDialog({
   resetForm,
 })
 
+// 构建代理配置
+// - 有 URL 时始终保存配置，通过 enabled 字段控制是否启用
+// - 无 URL 时返回 null
+function buildProxyConfig(): { url: string; username?: string; password?: string; enabled: boolean } | null {
+  if (!form.value.proxy_url) {
+    // 没填 URL，无代理配置
+    return null
+  }
+  return {
+    url: form.value.proxy_url,
+    username: form.value.proxy_username || undefined,
+    password: form.value.proxy_password || undefined,
+    enabled: proxyEnabled.value,  // 开关状态决定是否启用
+  }
+}
+
 // 提交表单
-const handleSubmit = async () => {
+const handleSubmit = async (skipCredentialCheck = false) => {
   if (!props.provider && !props.endpoint) return
 
+  // 只在开关开启且填写了 URL 时验证
+  if (proxyEnabled.value && form.value.proxy_url && proxyUrlError.value) {
+    showError(proxyUrlError.value, '代理配置错误')
+    return
+  }
+
+  // 检查：开关开启但没有 URL，却有用户名或密码
+  const hasOrphanedCredentials = proxyEnabled.value
+    && !form.value.proxy_url
+    && (form.value.proxy_username || form.value.proxy_password)
+
+  if (hasOrphanedCredentials && !skipCredentialCheck) {
+    // 弹出确认对话框
+    showClearCredentialsDialog.value = true
+    return
+  }
+
   loading.value = true
   try {
+    const proxyConfig = buildProxyConfig()
+
     if (isEditMode.value && props.endpoint) {
       // 更新端点
       await updateEndpoint(props.endpoint.id, {
@@ -297,7 +491,8 @@ const handleSubmit = async () => {
         max_retries: form.value.max_retries,
         max_concurrent: form.value.max_concurrent,
         rate_limit: form.value.rate_limit,
-        is_active: form.value.is_active
+        is_active: form.value.is_active,
+        proxy: proxyConfig,
       })
 
       success('端点已更新', '保存成功')
@@ -313,7 +508,8 @@ const handleSubmit = async () => {
         max_retries: form.value.max_retries,
         max_concurrent: form.value.max_concurrent,
         rate_limit: form.value.rate_limit,
-        is_active: form.value.is_active
+        is_active: form.value.is_active,
+        proxy: proxyConfig,
       })
 
       success('端点创建成功', '成功')
@@ -329,4 +525,12 @@ const handleSubmit = async () => {
     loading.value = false
   }
 }
+
+// 确认清空凭据并继续保存
+const confirmClearCredentials = () => {
+  form.value.proxy_username = ''
+  form.value.proxy_password = ''
+  showClearCredentialsDialog.value = false
+  handleSubmit(true)  // 跳过凭据检查，直接提交
+}
 </script>

frontend/src/features/usage/components/RequestDetailDrawer.vue

@@ -25,7 +25,7 @@
                 </h3>
                 <div class="flex items-center gap-1 text-sm font-mono text-muted-foreground bg-muted px-2 py-0.5 rounded">
                   <span>{{ detail?.model || '-' }}</span>
-                  <template v-if="detail?.target_model">
+                  <template v-if="detail?.target_model && detail.target_model !== detail.model">
                     <svg
                       xmlns="http://www.w3.org/2000/svg"
                       viewBox="0 0 20 20"

frontend/src/views/admin/CacheMonitoring.vue

@@ -142,32 +142,37 @@ async function resetAffinitySearch() {
   await fetchAffinityList()
 }
 
-async function clearUserCache(identifier: string, displayName?: string) {
-  const target = identifier?.trim()
-  if (!target) {
-    showError('无法识别标识符')
+async function clearSingleAffinity(item: UserAffinity) {
+  const affinityKey = item.affinity_key?.trim()
+  const endpointId = item.endpoint_id?.trim()
+  const modelId = item.global_model_id?.trim()
+  const apiFormat = item.api_format?.trim()
+
+  if (!affinityKey || !endpointId || !modelId || !apiFormat) {
+    showError('缓存记录信息不完整，无法删除')
     return
   }
 
-  const label = displayName || target
+  const label = item.user_api_key_name || affinityKey
+  const modelLabel = item.model_display_name || item.model_name || modelId
   const confirmed = await showConfirm({
     title: '确认清除',
-    message: `确定要清除 ${label} 的缓存吗？`,
+    message: `确定要清除 ${label} 在模型 ${modelLabel} 上的缓存亲和性吗？`,
     confirmText: '确认清除',
     variant: 'destructive'
   })
 
   if (!confirmed) return
 
-  clearingRowAffinityKey.value = target
+  clearingRowAffinityKey.value = affinityKey
   try {
-    await cacheApi.clearUserCache(target)
+    await cacheApi.clearSingleAffinity(affinityKey, endpointId, modelId, apiFormat)
     showSuccess('清除成功')
     await fetchCacheStats()
     await fetchAffinityList(tableKeyword.value.trim() || undefined)
   } catch (error) {
     showError('清除失败')
-    log.error('清除用户缓存失败', error)
+    log.error('清除单条缓存失败', error)
   } finally {
     clearingRowAffinityKey.value = null
   }
@@ -618,7 +623,7 @@ onBeforeUnmount(() => {
                 class="h-7 w-7 text-muted-foreground/70 hover:text-destructive"
                 :disabled="clearingRowAffinityKey === item.affinity_key"
                 title="清除缓存"
-                @click="clearUserCache(item.affinity_key, item.user_api_key_name || item.affinity_key)"
+                @click="clearSingleAffinity(item)"
               >
                 <Trash2 class="h-3.5 w-3.5" />
               </Button>
@@ -668,7 +673,7 @@ onBeforeUnmount(() => {
               variant="ghost"
               class="h-7 w-7 text-muted-foreground/70 hover:text-destructive shrink-0"
               :disabled="clearingRowAffinityKey === item.affinity_key"
-              @click="clearUserCache(item.affinity_key, item.user_api_key_name || item.affinity_key)"
+              @click="clearSingleAffinity(item)"
             >
               <Trash2 class="h-3.5 w-3.5" />
             </Button>

frontend/src/views/admin/SystemSettings.vue

@@ -185,32 +185,13 @@
         </div>
       </CardSection>
 
-      <!-- API Key 管理配置 -->
+      <!-- 独立余额 Key 过期管理 -->
       <CardSection
-        title="API Key 管理"
-        description="API Key 相关配置"
+        title="独立余额 Key 过期管理"
+        description="独立余额 Key 的过期处理策略（普通用户 Key 不会过期）"
       >
         <div class="grid grid-cols-1 md:grid-cols-2 gap-6">
-          <div>
-            <Label
-              for="api-key-expire"
-              class="block text-sm font-medium"
-            >
-              API密钥过期天数
-            </Label>
-            <Input
-              id="api-key-expire"
-              v-model.number="systemConfig.api_key_expire_days"
-              type="number"
-              placeholder="0"
-              class="mt-1"
-            />
-            <p class="mt-1 text-xs text-muted-foreground">
-              0 表示永不过期
-            </p>
-          </div>
-
-          <div class="flex items-center h-full pt-6">
+          <div class="flex items-center h-full">
             <div class="flex items-center space-x-2">
               <Checkbox
                 id="auto-delete-expired-keys"
@@ -224,7 +205,7 @@
                   自动删除过期 Key
                 </Label>
                 <p class="text-xs text-muted-foreground">
-                  关闭时仅禁用过期 Key
+                  关闭时仅禁用过期 Key，不会物理删除
                 </p>
               </div>
             </div>
@@ -448,6 +429,25 @@
               避免单次操作过大影响性能
             </p>
           </div>
+
+          <div>
+            <Label
+              for="audit-log-retention-days"
+              class="block text-sm font-medium"
+            >
+              审计日志保留天数
+            </Label>
+            <Input
+              id="audit-log-retention-days"
+              v-model.number="systemConfig.audit_log_retention_days"
+              type="number"
+              placeholder="30"
+              class="mt-1"
+            />
+            <p class="mt-1 text-xs text-muted-foreground">
+              超过后删除审计日志记录
+            </p>
+          </div>
         </div>
 
         <!-- 清理策略说明 -->
@@ -460,9 +460,11 @@
             <p>2. <strong>压缩日志阶段</strong>: body 字段被压缩存储，节省空间</p>
             <p>3. <strong>统计阶段</strong>: 仅保留 tokens、成本等统计信息</p>
             <p>4. <strong>归档删除</strong>: 超过保留期限后完全删除记录</p>
+            <p>5. <strong>审计日志</strong>: 独立清理，记录用户登录、操作等安全事件</p>
           </div>
         </div>
       </CardSection>
+
     </div>
 
     <!-- 导入配置对话框 -->
@@ -796,8 +798,7 @@ interface SystemConfig {
   // 用户注册
   enable_registration: boolean
   require_email_verification: boolean
-  // API Key 管理
-  api_key_expire_days: number
+  // 独立余额 Key 过期管理
   auto_delete_expired_keys: boolean
   // 日志记录
   request_log_level: string
@@ -811,6 +812,7 @@ interface SystemConfig {
   header_retention_days: number
   log_retention_days: number
   cleanup_batch_size: number
+  audit_log_retention_days: number
 }
 
 const loading = ref(false)
@@ -845,8 +847,7 @@ const systemConfig = ref<SystemConfig>({
   // 用户注册
   enable_registration: false,
   require_email_verification: false,
-  // API Key 管理
-  api_key_expire_days: 0,
+  // 独立余额 Key 过期管理
   auto_delete_expired_keys: false,
   // 日志记录
   request_log_level: 'basic',
@@ -860,6 +861,7 @@ const systemConfig = ref<SystemConfig>({
   header_retention_days: 90,
   log_retention_days: 365,
   cleanup_batch_size: 1000,
+  audit_log_retention_days: 30,
 })
 
 // 计算属性：KB 和 字节 之间的转换
@@ -901,8 +903,7 @@ async function loadSystemConfig() {
       // 用户注册
       'enable_registration',
       'require_email_verification',
-      // API Key 管理
-      'api_key_expire_days',
+      // 独立余额 Key 过期管理
       'auto_delete_expired_keys',
       // 日志记录
       'request_log_level',
@@ -916,6 +917,7 @@ async function loadSystemConfig() {
       'header_retention_days',
       'log_retention_days',
       'cleanup_batch_size',
+      'audit_log_retention_days',
     ]
 
     for (const key of configs) {
@@ -960,12 +962,7 @@ async function saveSystemConfig() {
         value: systemConfig.value.require_email_verification,
         description: '是否需要邮箱验证'
       },
-      // API Key 管理
-      {
-        key: 'api_key_expire_days',
-        value: systemConfig.value.api_key_expire_days,
-        description: 'API密钥过期天数'
-      },
+      // 独立余额 Key 过期管理
       {
         key: 'auto_delete_expired_keys',
         value: systemConfig.value.auto_delete_expired_keys,
@@ -1023,6 +1020,11 @@ async function saveSystemConfig() {
         value: systemConfig.value.cleanup_batch_size,
         description: '每批次清理的记录数'
       },
+      {
+        key: 'audit_log_retention_days',
+        value: systemConfig.value.audit_log_retention_days,
+        description: '审计日志保留天数'
+      },
     ]
 
     const promises = configItems.map(item =>

src/__init__.py

@@ -3,10 +3,8 @@
 A proxy server that enables AI models to work with multiple API providers.
 """
 
-from dotenv import load_dotenv
-
-# Load environment variables from .env file
-load_dotenv()
+# 注意: dotenv 加载已统一移至 src/config/settings.py
+# 不要在此处重复加载
 
 try:
     from src._version import __version__

src/api/admin/api_keys/routes.py

@@ -223,7 +223,7 @@ class AdminCreateStandaloneKeyAdapter(AdminApiAdapter):
             allowed_providers=self.key_data.allowed_providers,
             allowed_api_formats=self.key_data.allowed_api_formats,
             allowed_models=self.key_data.allowed_models,
-            rate_limit=self.key_data.rate_limit or 100,
+            rate_limit=self.key_data.rate_limit,  # None 表示不限制
             expire_days=self.key_data.expire_days,
             initial_balance_usd=self.key_data.initial_balance_usd,
             is_standalone=True,  # 标记为独立Key

src/api/admin/endpoints/routes.py

@@ -5,7 +5,7 @@ ProviderEndpoint CRUD 管理 API
 import uuid
 from dataclasses import dataclass
 from datetime import datetime, timezone
-from typing import List
+from typing import List, Optional
 
 from fastapi import APIRouter, Depends, Query, Request
 from sqlalchemy import and_, func
@@ -27,6 +27,16 @@ router = APIRouter(tags=["Endpoint Management"])
 pipeline = ApiRequestPipeline()
 
 
+def mask_proxy_password(proxy_config: Optional[dict]) -> Optional[dict]:
+    """对代理配置中的密码进行脱敏处理"""
+    if not proxy_config:
+        return None
+    masked = dict(proxy_config)
+    if masked.get("password"):
+        masked["password"] = "***"
+    return masked
+
+
 @router.get("/providers/{provider_id}/endpoints", response_model=List[ProviderEndpointResponse])
 async def list_provider_endpoints(
     provider_id: str,
@@ -153,6 +163,7 @@ class AdminListProviderEndpointsAdapter(AdminApiAdapter):
                 "api_format": endpoint.api_format,
                 "total_keys": total_keys_map.get(endpoint.id, 0),
                 "active_keys": active_keys_map.get(endpoint.id, 0),
+                "proxy": mask_proxy_password(endpoint.proxy),
             }
             endpoint_dict.pop("_sa_instance_state", None)
             result.append(ProviderEndpointResponse(**endpoint_dict))
@@ -202,6 +213,7 @@ class AdminCreateProviderEndpointAdapter(AdminApiAdapter):
             rate_limit=self.endpoint_data.rate_limit,
             is_active=True,
             config=self.endpoint_data.config,
+            proxy=self.endpoint_data.proxy.model_dump() if self.endpoint_data.proxy else None,
             created_at=now,
             updated_at=now,
         )
@@ -215,12 +227,13 @@ class AdminCreateProviderEndpointAdapter(AdminApiAdapter):
         endpoint_dict = {
             k: v
             for k, v in new_endpoint.__dict__.items()
-            if k not in {"api_format", "_sa_instance_state"}
+            if k not in {"api_format", "_sa_instance_state", "proxy"}
         }
         return ProviderEndpointResponse(
             **endpoint_dict,
             provider_name=provider.name,
             api_format=new_endpoint.api_format,
+            proxy=mask_proxy_password(new_endpoint.proxy),
             total_keys=0,
             active_keys=0,
         )
@@ -259,12 +272,13 @@ class AdminGetProviderEndpointAdapter(AdminApiAdapter):
         endpoint_dict = {
             k: v
             for k, v in endpoint_obj.__dict__.items()
-            if k not in {"api_format", "_sa_instance_state"}
+            if k not in {"api_format", "_sa_instance_state", "proxy"}
         }
         return ProviderEndpointResponse(
             **endpoint_dict,
             provider_name=provider.name,
             api_format=endpoint_obj.api_format,
+            proxy=mask_proxy_password(endpoint_obj.proxy),
             total_keys=total_keys,
             active_keys=active_keys,
         )
@@ -284,6 +298,17 @@ class AdminUpdateProviderEndpointAdapter(AdminApiAdapter):
             raise NotFoundException(f"Endpoint {self.endpoint_id} 不存在")
 
         update_data = self.endpoint_data.model_dump(exclude_unset=True)
+        # 把 proxy 转换为 dict 存储，支持显式设置为 None 清除代理
+        if "proxy" in update_data:
+            if update_data["proxy"] is not None:
+                new_proxy = dict(update_data["proxy"])
+                # 只有当密码字段未提供时才保留原密码（空字符串视为显式清除）
+                if "password" not in new_proxy and endpoint.proxy:
+                    old_password = endpoint.proxy.get("password")
+                    if old_password:
+                        new_proxy["password"] = old_password
+                update_data["proxy"] = new_proxy
+            # proxy 为 None 时保留，用于清除代理配置
         for field, value in update_data.items():
             setattr(endpoint, field, value)
         endpoint.updated_at = datetime.now(timezone.utc)
@@ -311,12 +336,13 @@ class AdminUpdateProviderEndpointAdapter(AdminApiAdapter):
         endpoint_dict = {
             k: v
             for k, v in endpoint.__dict__.items()
-            if k not in {"api_format", "_sa_instance_state"}
+            if k not in {"api_format", "_sa_instance_state", "proxy"}
         }
         return ProviderEndpointResponse(
             **endpoint_dict,
             provider_name=provider.name if provider else "Unknown",
             api_format=endpoint.api_format,
+            proxy=mask_proxy_password(endpoint.proxy),
             total_keys=total_keys,
             active_keys=active_keys,
         )

src/api/admin/monitoring/cache.py

@@ -186,6 +186,30 @@ async def clear_user_cache(
     return await pipeline.run(adapter=adapter, http_request=request, db=db, mode=adapter.mode)
 
 
+@router.delete("/affinity/{affinity_key}/{endpoint_id}/{model_id}/{api_format}")
+async def clear_single_affinity(
+    affinity_key: str,
+    endpoint_id: str,
+    model_id: str,
+    api_format: str,
+    request: Request,
+    db: Session = Depends(get_db),
+) -> Any:
+    """
+    Clear a single cache affinity entry
+
+    Parameters:
+    - affinity_key: API Key ID
+    - endpoint_id: Endpoint ID
+    - model_id: Model ID (GlobalModel ID)
+    - api_format: API format (claude/openai)
+    """
+    adapter = AdminClearSingleAffinityAdapter(
+        affinity_key=affinity_key, endpoint_id=endpoint_id, model_id=model_id, api_format=api_format
+    )
+    return await pipeline.run(adapter=adapter, http_request=request, db=db, mode=adapter.mode)
+
+
 @router.delete("")
 async def clear_all_cache(
     request: Request,
@@ -655,6 +679,7 @@ class AdminListAffinitiesAdapter(AdminApiAdapter):
                 "key_name": key.name if key else None,
                 "key_prefix": provider_key_masked,
                 "rate_multiplier": key.rate_multiplier if key else 1.0,
+                "global_model_id": affinity.get("model_name"),  # 原始的 global_model_id
                 "model_name": (
                     global_model_map.get(affinity.get("model_name")).name
                     if affinity.get("model_name") and global_model_map.get(affinity.get("model_name"))
@@ -817,6 +842,65 @@ class AdminClearUserCacheAdapter(AdminApiAdapter):
             raise HTTPException(status_code=500, detail=f"清除失败: {exc}")
 
 
+@dataclass
+class AdminClearSingleAffinityAdapter(AdminApiAdapter):
+    affinity_key: str
+    endpoint_id: str
+    model_id: str
+    api_format: str
+
+    async def handle(self, context: ApiRequestContext) -> Dict[str, Any]:  # type: ignore[override]
+        db = context.db
+        try:
+            redis_client = get_redis_client_sync()
+            affinity_mgr = await get_affinity_manager(redis_client)
+
+            # 直接获取指定的亲和性记录（无需遍历全部）
+            existing_affinity = await affinity_mgr.get_affinity(
+                self.affinity_key, self.api_format, self.model_id
+            )
+
+            if not existing_affinity:
+                raise HTTPException(status_code=404, detail="未找到指定的缓存亲和性记录")
+
+            # 验证 endpoint_id 是否匹配
+            if existing_affinity.endpoint_id != self.endpoint_id:
+                raise HTTPException(status_code=404, detail="未找到指定的缓存亲和性记录")
+
+            # 失效单条记录
+            await affinity_mgr.invalidate_affinity(
+                self.affinity_key, self.api_format, self.model_id, endpoint_id=self.endpoint_id
+            )
+
+            # 获取用于日志的信息
+            api_key = db.query(ApiKey).filter(ApiKey.id == self.affinity_key).first()
+            api_key_name = api_key.name if api_key else None
+
+            logger.info(
+                f"已清除单条缓存亲和性: affinity_key={self.affinity_key[:8]}..., "
+                f"endpoint_id={self.endpoint_id[:8]}..., model_id={self.model_id[:8]}..."
+            )
+
+            context.add_audit_metadata(
+                action="cache_clear_single",
+                affinity_key=self.affinity_key,
+                endpoint_id=self.endpoint_id,
+                model_id=self.model_id,
+            )
+            return {
+                "status": "ok",
+                "message": f"已清除缓存亲和性: {api_key_name or self.affinity_key[:8]}",
+                "affinity_key": self.affinity_key,
+                "endpoint_id": self.endpoint_id,
+                "model_id": self.model_id,
+            }
+        except HTTPException:
+            raise
+        except Exception as exc:
+            logger.exception(f"清除单条缓存亲和性失败: {exc}")
+            raise HTTPException(status_code=500, detail=f"清除失败: {exc}")
+
+
 class AdminClearAllCacheAdapter(AdminApiAdapter):
     async def handle(self, context: ApiRequestContext) -> Dict[str, Any]:  # type: ignore[override]
         try:

src/api/admin/monitoring/trace.py

@@ -7,7 +7,7 @@ from datetime import datetime
 from typing import List, Optional
 
 from fastapi import APIRouter, Depends, HTTPException, Query, Request
-from pydantic import BaseModel
+from pydantic import BaseModel, ConfigDict
 from sqlalchemy.orm import Session
 
 from src.api.base.admin_adapter import AdminApiAdapter
@@ -52,8 +52,7 @@ class CandidateResponse(BaseModel):
     started_at: Optional[datetime] = None
     finished_at: Optional[datetime] = None
 
-    class Config:
-        from_attributes = True
+    model_config = ConfigDict(from_attributes=True)
 
 
 class RequestTraceResponse(BaseModel):

src/api/admin/providers/models.py

@@ -9,6 +9,7 @@ from fastapi import APIRouter, Depends, Request
 from sqlalchemy.orm import Session, joinedload
 
 from src.api.base.admin_adapter import AdminApiAdapter
+from src.api.base.models_service import invalidate_models_list_cache
 from src.api.base.pipeline import ApiRequestPipeline
 from src.core.exceptions import InvalidRequestException, NotFoundException
 from src.core.logger import logger
@@ -419,4 +420,8 @@ class AdminBatchAssignModelsToProviderAdapter(AdminApiAdapter):
             f"Batch assigned {len(success)} GlobalModels to provider {provider.name} by {context.user.username}"
         )
 
+        # 清除 /v1/models 列表缓存
+        if success:
+            await invalidate_models_list_cache()
+
         return BatchAssignModelsToProviderResponse(success=success, errors=errors)

src/api/announcements/routes.py

@@ -140,9 +140,9 @@ class AnnouncementOptionalAuthAdapter(ApiAdapter):
         if not authorization or not authorization.lower().startswith("bearer "):
             return None
 
-        token = authorization.replace("Bearer ", "").strip()
+        token = authorization[7:].strip()
         try:
-            payload = await AuthService.verify_token(token)
+            payload = await AuthService.verify_token(token, token_type="access")
             user_id = payload.get("user_id")
             if not user_id:
                 return None

src/api/auth/routes.py

@@ -211,7 +211,7 @@ class AuthRefreshAdapter(AuthPublicAdapter):
 
 class AuthRegisterAdapter(AuthPublicAdapter):
     async def handle(self, context):  # type: ignore[override]
-        from ..models.database import SystemConfig
+        from src.models.database import SystemConfig
 
         db = context.db
         payload = context.ensure_json_body()

src/api/base/models_service.py

@@ -55,6 +55,23 @@ async def _set_cached_models(api_formats: list[str], models: list["ModelInfo"])
         logger.warning(f"[ModelsService] 缓存写入失败: {e}")
 
 
+async def invalidate_models_list_cache() -> None:
+    """
+    清除所有 /v1/models 列表缓存
+
+    在模型创建、更新、删除时调用，确保模型列表实时更新
+    """
+    # 清除所有格式的缓存
+    all_formats = ["CLAUDE", "OPENAI", "GEMINI"]
+    for fmt in all_formats:
+        cache_key = f"{_CACHE_KEY_PREFIX}:{fmt}"
+        try:
+            await CacheService.delete(cache_key)
+            logger.debug(f"[ModelsService] 已清除缓存: {cache_key}")
+        except Exception as e:
+            logger.warning(f"[ModelsService] 清除缓存失败 {cache_key}: {e}")
+
+
 @dataclass
 class ModelInfo:
     """统一的模型信息结构"""

src/api/base/pipeline.py

@@ -5,13 +5,12 @@ from enum import Enum
 from typing import Any, Optional, Tuple
 
 from fastapi import HTTPException, Request
-from sqlalchemy.orm import Session, sessionmaker
+from sqlalchemy.orm import Session
 
 from src.core.exceptions import QuotaExceededException
 from src.core.logger import logger
 from src.models.database import ApiKey, AuditEventType, User, UserRole
 from src.services.auth.service import AuthService
-from src.services.cache.user_cache import UserCacheService
 from src.services.system.audit import AuditService
 from src.services.usage.service import UsageService
 
@@ -178,9 +177,9 @@ class ApiRequestPipeline:
         if not authorization or not authorization.lower().startswith("bearer "):
             raise HTTPException(status_code=401, detail="缺少管理员凭证")
 
-        token = authorization.replace("Bearer ", "").strip()
+        token = authorization[7:].strip()
         try:
-            payload = await self.auth_service.verify_token(token)
+            payload = await self.auth_service.verify_token(token, token_type="access")
         except HTTPException:
             raise
         except Exception as exc:
@@ -191,8 +190,8 @@ class ApiRequestPipeline:
         if not user_id:
             raise HTTPException(status_code=401, detail="无效的管理员令牌")
 
-        # 使用缓存查询用户
-        user = await UserCacheService.get_user_by_id(db, user_id)
+        # 直接查询数据库，确保返回的是当前 Session 绑定的对象
+        user = db.query(User).filter(User.id == user_id).first()
         if not user or not user.is_active:
             raise HTTPException(status_code=403, detail="用户不存在或已禁用")
 
@@ -205,9 +204,9 @@ class ApiRequestPipeline:
         if not authorization or not authorization.lower().startswith("bearer "):
             raise HTTPException(status_code=401, detail="缺少用户凭证")
 
-        token = authorization.replace("Bearer ", "").strip()
+        token = authorization[7:].strip()
         try:
-            payload = await self.auth_service.verify_token(token)
+            payload = await self.auth_service.verify_token(token, token_type="access")
         except HTTPException:
             raise
         except Exception as exc:
@@ -218,8 +217,8 @@ class ApiRequestPipeline:
         if not user_id:
             raise HTTPException(status_code=401, detail="无效的用户令牌")
 
-        # 使用缓存查询用户
-        user = await UserCacheService.get_user_by_id(db, user_id)
+        # 直接查询数据库，确保返回的是当前 Session 绑定的对象
+        user = db.query(User).filter(User.id == user_id).first()
         if not user or not user.is_active:
             raise HTTPException(status_code=403, detail="用户不存在或已禁用")
 
@@ -242,11 +241,15 @@ class ApiRequestPipeline:
         status_code: Optional[int] = None,
         error: Optional[str] = None,
     ) -> None:
+        """记录审计事件
+
+        事务策略：复用请求级 Session，不单独提交。
+        审计记录随主事务一起提交，由中间件统一管理。
+        """
         if not getattr(adapter, "audit_log_enabled", True):
             return
 
-        bind = context.db.get_bind()
-        if bind is None:
+        if context.db is None:
             return
 
         event_type = adapter.audit_success_event if success else adapter.audit_failure_event
@@ -266,11 +269,11 @@ class ApiRequestPipeline:
             error=error,
         )
 
-        SessionMaker = sessionmaker(bind=bind)
-        audit_session = SessionMaker()
         try:
+            # 复用请求级 Session，不创建新的连接
+            # 审计记录随主事务一起提交，由中间件统一管理
             self.audit_service.log_event(
-                db=audit_session,
+                db=context.db,
                 event_type=event_type,
                 description=f"{context.request.method} {context.request.url.path} via {adapter.name}",
                 user_id=context.user.id if context.user else None,
@@ -282,12 +285,9 @@ class ApiRequestPipeline:
                 error_message=error,
                 metadata=metadata,
             )
-            audit_session.commit()
         except Exception as exc:
-            audit_session.rollback()
+            # 审计失败不应影响主请求，仅记录警告
             logger.warning(f"[Audit] Failed to record event for adapter={adapter.name}: {exc}")
-        finally:
-            audit_session.close()
 
     def _build_audit_metadata(
         self,

src/api/handlers/base/base_handler.py

@@ -28,7 +28,7 @@
 from __future__ import annotations
 
 import time
-from typing import Any, Callable, Dict, Optional, Protocol, runtime_checkable
+from typing import TYPE_CHECKING, Any, Callable, Dict, Optional, Protocol, runtime_checkable
 
 from fastapi import Request
 from fastapi.responses import JSONResponse, StreamingResponse
@@ -43,6 +43,9 @@ from src.services.provider.format import normalize_api_format
 from src.services.system.audit import audit_service
 from src.services.usage.service import UsageService
 
+if TYPE_CHECKING:
+    from src.api.handlers.base.stream_context import StreamContext
+
 
 
 class MessageTelemetry:
@@ -399,6 +402,41 @@ class BaseMessageHandler:
         # 创建后台任务，不阻塞当前流
         asyncio.create_task(_do_update())
 
+    def _update_usage_to_streaming_with_ctx(self, ctx: "StreamContext") -> None:
+        """更新 Usage 状态为 streaming，同时更新 provider 和 target_model
+
+        使用 asyncio 后台任务执行数据库更新，避免阻塞流式传输
+
+        Args:
+            ctx: 流式上下文，包含 provider_name 和 mapped_model
+        """
+        import asyncio
+        from src.database.database import get_db
+
+        target_request_id = self.request_id
+        provider = ctx.provider_name
+        target_model = ctx.mapped_model
+
+        async def _do_update() -> None:
+            try:
+                db_gen = get_db()
+                db = next(db_gen)
+                try:
+                    UsageService.update_usage_status(
+                        db=db,
+                        request_id=target_request_id,
+                        status="streaming",
+                        provider=provider,
+                        target_model=target_model,
+                    )
+                finally:
+                    db.close()
+            except Exception as e:
+                logger.warning(f"[{target_request_id}] 更新 Usage 状态为 streaming 失败: {e}")
+
+        # 创建后台任务，不阻塞当前流
+        asyncio.create_task(_do_update())
+
     def _log_request_error(self, message: str, error: Exception) -> None:
         """记录请求错误日志，对业务异常不打印堆栈
 
@@ -411,9 +449,10 @@ class BaseMessageHandler:
             QuotaExceededException,
             RateLimitException,
             ModelNotSupportedException,
+            UpstreamClientException,
         )
 
-        if isinstance(error, (ProviderException, QuotaExceededException, RateLimitException, ModelNotSupportedException)):
+        if isinstance(error, (ProviderException, QuotaExceededException, RateLimitException, ModelNotSupportedException, UpstreamClientException)):
             # 业务异常：简洁日志，不打印堆栈
             logger.error(f"{message}: [{type(error).__name__}] {error}")
         else:

src/api/handlers/base/chat_adapter_base.py

@@ -64,18 +64,6 @@ class ChatAdapterBase(ApiAdapter):
 
     def __init__(self, allowed_api_formats: Optional[list[str]] = None):
         self.allowed_api_formats = allowed_api_formats or [self.FORMAT_ID]
-        self.response_normalizer = None
-        # 可选启用响应规范化
-        self._init_response_normalizer()
-
-    def _init_response_normalizer(self):
-        """初始化响应规范化器 - 子类可覆盖"""
-        try:
-            from src.services.provider.response_normalizer import ResponseNormalizer
-
-            self.response_normalizer = ResponseNormalizer()
-        except ImportError:
-            pass
 
     async def handle(self, context: ApiRequestContext):
         """处理 Chat API 请求"""
@@ -228,8 +216,6 @@ class ChatAdapterBase(ApiAdapter):
             user_agent=user_agent,
             start_time=start_time,
             allowed_api_formats=self.allowed_api_formats,
-            response_normalizer=self.response_normalizer,
-            enable_response_normalization=self.response_normalizer is not None,
             adapter_detector=self.detect_capability_requirements,
         )
 

src/api/handlers/base/chat_handler_base.py

@@ -88,8 +88,6 @@ class ChatHandlerBase(BaseMessageHandler, ABC):
         user_agent: str,
         start_time: float,
         allowed_api_formats: Optional[list] = None,
-        response_normalizer: Optional[Any] = None,
-        enable_response_normalization: bool = False,
         adapter_detector: Optional[Callable[[Dict[str, str], Optional[Dict[str, Any]]], Dict[str, bool]]] = None,
     ):
         allowed = allowed_api_formats or [self.FORMAT_ID]
@@ -106,8 +104,6 @@ class ChatHandlerBase(BaseMessageHandler, ABC):
         )
         self._parser: Optional[ResponseParser] = None
         self._request_builder = PassthroughRequestBuilder()
-        self.response_normalizer = response_normalizer
-        self.enable_response_normalization = enable_response_normalization
 
     @property
     def parser(self) -> ResponseParser:
@@ -297,11 +293,15 @@ class ChatHandlerBase(BaseMessageHandler, ABC):
         # 创建类型安全的流式上下文
         ctx = StreamContext(model=model, api_format=api_format)
 
+        # 创建更新状态的回调闭包（可以访问 ctx）
+        def update_streaming_status() -> None:
+            self._update_usage_to_streaming_with_ctx(ctx)
+
         # 创建流处理器
         stream_processor = StreamProcessor(
             request_id=self.request_id,
             default_parser=self.parser,
-            on_streaming_start=self._update_usage_to_streaming,
+            on_streaming_start=update_streaming_status,
         )
 
         # 定义请求函数
@@ -466,7 +466,13 @@ class ChatHandlerBase(BaseMessageHandler, ABC):
             pool=config.http_pool_timeout,
         )
 
-        http_client = httpx.AsyncClient(timeout=timeout_config, follow_redirects=True)
+        # 创建 HTTP 客户端（支持代理配置）
+        from src.clients.http_client import HTTPClientPool
+
+        http_client = HTTPClientPool.create_client_with_proxy(
+            proxy_config=endpoint.proxy,
+            timeout=timeout_config,
+        )
         try:
             response_ctx = http_client.stream(
                 "POST", url, json=provider_payload, headers=provider_headers
@@ -634,10 +640,14 @@ class ChatHandlerBase(BaseMessageHandler, ABC):
             logger.info(f"  [{self.request_id}] 发送非流式请求: Provider={provider.name}, "
                 f"模型={model} -> {mapped_model or '无映射'}")
 
-            async with httpx.AsyncClient(
-                timeout=float(endpoint.timeout),
-                follow_redirects=True,
-            ) as http_client:
+            # 创建 HTTP 客户端（支持代理配置）
+            from src.clients.http_client import HTTPClientPool
+
+            http_client = HTTPClientPool.create_client_with_proxy(
+                proxy_config=endpoint.proxy,
+                timeout=httpx.Timeout(float(endpoint.timeout)),
+            )
+            async with http_client:
                 resp = await http_client.post(url, json=provider_payload, headers=provider_hdrs)
 
                 status_code = resp.status_code

src/api/handlers/base/cli_handler_base.py

@@ -454,7 +454,13 @@ class CliMessageHandlerBase(BaseMessageHandler):
             f"Key=***{key.api_key[-4:]}, "
             f"原始模型={ctx.model}, 映射后={mapped_model or '无映射'}, URL模型={url_model}")
 
-        http_client = httpx.AsyncClient(timeout=timeout_config, follow_redirects=True)
+        # 创建 HTTP 客户端（支持代理配置）
+        from src.clients.http_client import HTTPClientPool
+
+        http_client = HTTPClientPool.create_client_with_proxy(
+            proxy_config=endpoint.proxy,
+            timeout=timeout_config,
+        )
         try:
             response_ctx = http_client.stream(
                 "POST", url, json=provider_payload, headers=provider_headers
@@ -526,7 +532,7 @@ class CliMessageHandlerBase(BaseMessageHandler):
             async for chunk in stream_response.aiter_raw():
                 # 在第一次输出数据前更新状态为 streaming
                 if not streaming_status_updated:
-                    self._update_usage_to_streaming(ctx.request_id)
+                    self._update_usage_to_streaming_with_ctx(ctx)
                     streaming_status_updated = True
 
                 buffer += chunk
@@ -810,7 +816,7 @@ class CliMessageHandlerBase(BaseMessageHandler):
 
             # 在第一次输出数据前更新状态为 streaming
             if prefetched_chunks:
-                self._update_usage_to_streaming(ctx.request_id)
+                self._update_usage_to_streaming_with_ctx(ctx)
 
             # 先处理预读的字节块
             for chunk in prefetched_chunks:
@@ -1108,8 +1114,10 @@ class CliMessageHandlerBase(BaseMessageHandler):
             async for chunk in stream_generator:
                 yield chunk
         except asyncio.CancelledError:
-            ctx.status_code = 499
-            ctx.error_message = "Client disconnected"
+            # 如果响应已完成，不标记为失败
+            if not ctx.has_completion:
+                ctx.status_code = 499
+                ctx.error_message = "Client disconnected"
             raise
         except httpx.TimeoutException as e:
             ctx.status_code = 504
@@ -1419,10 +1427,14 @@ class CliMessageHandlerBase(BaseMessageHandler):
                 f"Key=***{key.api_key[-4:]}, "
                 f"原始模型={model}, 映射后={mapped_model or '无映射'}, URL模型={url_model}")
 
-            async with httpx.AsyncClient(
-                timeout=float(endpoint.timeout),
-                follow_redirects=True,
-            ) as http_client:
+            # 创建 HTTP 客户端（支持代理配置）
+            from src.clients.http_client import HTTPClientPool
+
+            http_client = HTTPClientPool.create_client_with_proxy(
+                proxy_config=endpoint.proxy,
+                timeout=httpx.Timeout(float(endpoint.timeout)),
+            )
+            async with http_client:
                 resp = await http_client.post(url, json=provider_payload, headers=provider_headers)
 
                 status_code = resp.status_code

src/api/handlers/base/content_extractors.py

@@ -0,0 +1,274 @@
+"""
+流式内容提取器 - 策略模式实现
+
+为不同 API 格式（OpenAI、Claude、Gemini）提供内容提取和 chunk 构造的抽象。
+StreamSmoother 使用这些提取器来处理不同格式的 SSE 事件。
+"""
+
+import copy
+import json
+from abc import ABC, abstractmethod
+from typing import Optional
+
+
+class ContentExtractor(ABC):
+    """
+    流式内容提取器抽象基类
+
+    定义从 SSE 事件中提取文本内容和构造新 chunk 的接口。
+    每种 API 格式（OpenAI、Claude、Gemini）需要实现自己的提取器。
+    """
+
+    @abstractmethod
+    def extract_content(self, data: dict) -> Optional[str]:
+        """
+        从 SSE 数据中提取可拆分的文本内容
+
+        Args:
+            data: 解析后的 JSON 数据
+
+        Returns:
+            提取的文本内容，如果无法提取则返回 None
+        """
+        pass
+
+    @abstractmethod
+    def create_chunk(
+        self,
+        original_data: dict,
+        new_content: str,
+        event_type: str = "",
+        is_first: bool = False,
+    ) -> bytes:
+        """
+        使用新内容构造 SSE chunk
+
+        Args:
+            original_data: 原始 JSON 数据
+            new_content: 新的文本内容
+            event_type: SSE 事件类型（某些格式需要）
+            is_first: 是否是第一个 chunk（用于保留 role 等字段）
+
+        Returns:
+            编码后的 SSE 字节数据
+        """
+        pass
+
+
+class OpenAIContentExtractor(ContentExtractor):
+    """
+    OpenAI 格式内容提取器
+
+    处理 OpenAI Chat Completions API 的流式响应格式：
+    - 数据结构: choices[0].delta.content
+    - 只在 delta 仅包含 role/content 时允许拆分，避免破坏 tool_calls 等结构
+    """
+
+    def extract_content(self, data: dict) -> Optional[str]:
+        if not isinstance(data, dict):
+            return None
+
+        choices = data.get("choices")
+        if not isinstance(choices, list) or len(choices) != 1:
+            return None
+
+        first_choice = choices[0]
+        if not isinstance(first_choice, dict):
+            return None
+
+        delta = first_choice.get("delta")
+        if not isinstance(delta, dict):
+            return None
+
+        content = delta.get("content")
+        if not isinstance(content, str):
+            return None
+
+        # 只有 delta 仅包含 role/content 时才允许拆分
+        # 避免破坏 tool_calls、function_call 等复杂结构
+        allowed_keys = {"role", "content"}
+        if not all(key in allowed_keys for key in delta.keys()):
+            return None
+
+        return content
+
+    def create_chunk(
+        self,
+        original_data: dict,
+        new_content: str,
+        event_type: str = "",
+        is_first: bool = False,
+    ) -> bytes:
+        new_data = original_data.copy()
+
+        if "choices" in new_data and new_data["choices"]:
+            new_choices = []
+            for choice in new_data["choices"]:
+                new_choice = choice.copy()
+                if "delta" in new_choice:
+                    new_delta = {}
+                    # 只有第一个 chunk 保留 role
+                    if is_first and "role" in new_choice["delta"]:
+                        new_delta["role"] = new_choice["delta"]["role"]
+                    new_delta["content"] = new_content
+                    new_choice["delta"] = new_delta
+                new_choices.append(new_choice)
+            new_data["choices"] = new_choices
+
+        return f"data: {json.dumps(new_data, ensure_ascii=False)}\n\n".encode("utf-8")
+
+
+class ClaudeContentExtractor(ContentExtractor):
+    """
+    Claude 格式内容提取器
+
+    处理 Claude Messages API 的流式响应格式：
+    - 事件类型: content_block_delta
+    - 数据结构: delta.type=text_delta, delta.text
+    """
+
+    def extract_content(self, data: dict) -> Optional[str]:
+        if not isinstance(data, dict):
+            return None
+
+        # 检查事件类型
+        if data.get("type") != "content_block_delta":
+            return None
+
+        delta = data.get("delta", {})
+        if not isinstance(delta, dict):
+            return None
+
+        # 检查 delta 类型
+        if delta.get("type") != "text_delta":
+            return None
+
+        text = delta.get("text")
+        if not isinstance(text, str):
+            return None
+
+        return text
+
+    def create_chunk(
+        self,
+        original_data: dict,
+        new_content: str,
+        event_type: str = "",
+        is_first: bool = False,
+    ) -> bytes:
+        new_data = original_data.copy()
+
+        if "delta" in new_data:
+            new_delta = new_data["delta"].copy()
+            new_delta["text"] = new_content
+            new_data["delta"] = new_delta
+
+        # Claude 格式需要 event: 前缀
+        event_name = event_type or "content_block_delta"
+        return f"event: {event_name}\ndata: {json.dumps(new_data, ensure_ascii=False)}\n\n".encode(
+            "utf-8"
+        )
+
+
+class GeminiContentExtractor(ContentExtractor):
+    """
+    Gemini 格式内容提取器
+
+    处理 Gemini API 的流式响应格式：
+    - 数据结构: candidates[0].content.parts[0].text
+    - 只有纯文本块才拆分
+    """
+
+    def extract_content(self, data: dict) -> Optional[str]:
+        if not isinstance(data, dict):
+            return None
+
+        candidates = data.get("candidates")
+        if not isinstance(candidates, list) or len(candidates) != 1:
+            return None
+
+        first_candidate = candidates[0]
+        if not isinstance(first_candidate, dict):
+            return None
+
+        content = first_candidate.get("content", {})
+        if not isinstance(content, dict):
+            return None
+
+        parts = content.get("parts", [])
+        if not isinstance(parts, list) or len(parts) != 1:
+            return None
+
+        first_part = parts[0]
+        if not isinstance(first_part, dict):
+            return None
+
+        text = first_part.get("text")
+        # 只有纯文本块（只有 text 字段）才拆分
+        if not isinstance(text, str) or len(first_part) != 1:
+            return None
+
+        return text
+
+    def create_chunk(
+        self,
+        original_data: dict,
+        new_content: str,
+        event_type: str = "",
+        is_first: bool = False,
+    ) -> bytes:
+        new_data = copy.deepcopy(original_data)
+
+        if "candidates" in new_data and new_data["candidates"]:
+            first_candidate = new_data["candidates"][0]
+            if "content" in first_candidate:
+                content = first_candidate["content"]
+                if "parts" in content and content["parts"]:
+                    content["parts"][0]["text"] = new_content
+
+        return f"data: {json.dumps(new_data, ensure_ascii=False)}\n\n".encode("utf-8")
+
+
+# 提取器注册表
+_EXTRACTORS: dict[str, type[ContentExtractor]] = {
+    "openai": OpenAIContentExtractor,
+    "claude": ClaudeContentExtractor,
+    "gemini": GeminiContentExtractor,
+}
+
+
+def get_extractor(format_name: str) -> Optional[ContentExtractor]:
+    """
+    根据格式名获取对应的内容提取器实例
+
+    Args:
+        format_name: 格式名称（openai, claude, gemini）
+
+    Returns:
+        对应的提取器实例，如果格式不支持则返回 None
+    """
+    extractor_class = _EXTRACTORS.get(format_name.lower())
+    if extractor_class:
+        return extractor_class()
+    return None
+
+
+def register_extractor(format_name: str, extractor_class: type[ContentExtractor]) -> None:
+    """
+    注册新的内容提取器
+
+    Args:
+        format_name: 格式名称
+        extractor_class: 提取器类
+    """
+    _EXTRACTORS[format_name.lower()] = extractor_class
+
+
+def get_extractor_formats() -> list[str]:
+    """
+    获取所有已注册的格式名称列表
+
+    Returns:
+        格式名称列表
+    """
+    return list(_EXTRACTORS.keys())

src/api/handlers/base/stream_processor.py

@@ -6,16 +6,22 @@
 2. 响应流生成
 3. 预读和嵌套错误检测
 4. 客户端断开检测
+5. 流式平滑输出
 """
 
 import asyncio
 import codecs
 import json
-import time
+from dataclasses import dataclass
 from typing import Any, AsyncGenerator, Callable, Optional
 
 import httpx
 
+from src.api.handlers.base.content_extractors import (
+    ContentExtractor,
+    get_extractor,
+    get_extractor_formats,
+)
 from src.api.handlers.base.parsers import get_parser_for_format
 from src.api.handlers.base.response_parser import ResponseParser
 from src.api.handlers.base.stream_context import StreamContext
@@ -25,11 +31,20 @@ from src.models.database import Provider, ProviderEndpoint
 from src.utils.sse_parser import SSEEventParser
 
 
+@dataclass
+class StreamSmoothingConfig:
+    """流式平滑输出配置"""
+
+    enabled: bool = False
+    chunk_size: int = 20
+    delay_ms: int = 8
+
+
 class StreamProcessor:
     """
     流式响应处理器
 
-    负责处理 SSE 流的解析、错误检测和响应生成。
+    负责处理 SSE 流的解析、错误检测、响应生成和平滑输出。
     从 ChatHandlerBase 中提取，使其职责更加单一。
     """
 
@@ -40,6 +55,7 @@ class StreamProcessor:
         on_streaming_start: Optional[Callable[[], None]] = None,
         *,
         collect_text: bool = False,
+        smoothing_config: Optional[StreamSmoothingConfig] = None,
     ):
         """
         初始化流处理器
@@ -48,11 +64,17 @@ class StreamProcessor:
             request_id: 请求 ID（用于日志）
             default_parser: 默认响应解析器
             on_streaming_start: 流开始时的回调（用于更新状态）
+            collect_text: 是否收集文本内容
+            smoothing_config: 流式平滑输出配置
         """
         self.request_id = request_id
         self.default_parser = default_parser
         self.on_streaming_start = on_streaming_start
         self.collect_text = collect_text
+        self.smoothing_config = smoothing_config or StreamSmoothingConfig()
+
+        # 内容提取器缓存
+        self._extractors: dict[str, ContentExtractor] = {}
 
     def get_parser_for_provider(self, ctx: StreamContext) -> ResponseParser:
         """
@@ -127,6 +149,13 @@ class StreamProcessor:
         if event_type in ("response.completed", "message_stop"):
             ctx.has_completion = True
 
+        # 检查 OpenAI 格式的 finish_reason
+        choices = data.get("choices", [])
+        if choices and isinstance(choices, list) and len(choices) > 0:
+            finish_reason = choices[0].get("finish_reason")
+            if finish_reason is not None:
+                ctx.has_completion = True
+
     async def prefetch_and_check_error(
         self,
         byte_iterator: Any,
@@ -369,7 +398,7 @@ class StreamProcessor:
             sse_parser: SSE 解析器
             line: 原始行数据
         """
-        # SSEEventParser 以“去掉换行符”的单行文本作为输入；这里统一剔除 CR/LF，
+        # SSEEventParser 以"去掉换行符"的单行文本作为输入；这里统一剔除 CR/LF，
         # 避免把空行误判成 "\n" 并导致事件边界解析错误。
         normalized_line = line.rstrip("\r\n")
         events = sse_parser.feed_line(normalized_line)
@@ -400,32 +429,201 @@ class StreamProcessor:
             响应数据块
         """
         try:
-            # 断连检查频率：每次 await 都会引入调度开销，过于频繁会让流式"发一段停一段"
-            # 这里按时间间隔节流，兼顾及时停止上游读取与吞吐平滑性。
-            next_disconnect_check_at = 0.0
-            disconnect_check_interval_s = 0.25
+            # 使用后台任务检查断连，完全不阻塞流式传输
+            disconnected = False
 
-            async for chunk in stream_generator:
-                now = time.monotonic()
-                if now >= next_disconnect_check_at:
-                    next_disconnect_check_at = now + disconnect_check_interval_s
+            async def check_disconnect_background() -> None:
+                nonlocal disconnected
+                while not disconnected and not ctx.has_completion:
+                    await asyncio.sleep(0.5)
                     if await is_disconnected():
-                        logger.warning(f"ID:{self.request_id} | Client disconnected")
-                        ctx.status_code = 499  # Client Closed Request
-                        ctx.error_message = "client_disconnected"
-
+                        disconnected = True
                         break
-                yield chunk
-        except asyncio.CancelledError:
-            ctx.status_code = 499
-            ctx.error_message = "client_disconnected"
 
+            # 启动后台检查任务
+            check_task = asyncio.create_task(check_disconnect_background())
+
+            try:
+                async for chunk in stream_generator:
+                    if disconnected:
+                        # 如果响应已完成，客户端断开不算失败
+                        if ctx.has_completion:
+                            logger.info(
+                                f"ID:{self.request_id} | Client disconnected after completion"
+                            )
+                        else:
+                            logger.warning(f"ID:{self.request_id} | Client disconnected")
+                            ctx.status_code = 499
+                            ctx.error_message = "client_disconnected"
+                        break
+                    yield chunk
+            finally:
+                check_task.cancel()
+                try:
+                    await check_task
+                except asyncio.CancelledError:
+                    pass
+        except asyncio.CancelledError:
+            # 如果响应已完成，不标记为失败
+            if not ctx.has_completion:
+                ctx.status_code = 499
+                ctx.error_message = "client_disconnected"
             raise
         except Exception as e:
             ctx.status_code = 500
             ctx.error_message = str(e)
             raise
 
+    async def create_smoothed_stream(
+        self,
+        stream_generator: AsyncGenerator[bytes, None],
+    ) -> AsyncGenerator[bytes, None]:
+        """
+        创建平滑输出的流生成器
+
+        如果启用了平滑输出，将大 chunk 拆分成小块并添加微小延迟。
+        否则直接透传原始流。
+
+        Args:
+            stream_generator: 原始流生成器
+
+        Yields:
+            平滑处理后的响应数据块
+        """
+        if not self.smoothing_config.enabled:
+            # 未启用平滑输出，直接透传
+            async for chunk in stream_generator:
+                yield chunk
+            return
+
+        # 启用平滑输出
+        buffer = b""
+        is_first_content = True
+
+        async for chunk in stream_generator:
+            buffer += chunk
+
+            # 按双换行分割 SSE 事件（标准 SSE 格式）
+            while b"\n\n" in buffer:
+                event_block, buffer = buffer.split(b"\n\n", 1)
+                event_str = event_block.decode("utf-8", errors="replace")
+
+                # 解析事件块
+                lines = event_str.strip().split("\n")
+                data_str = None
+                event_type = ""
+
+                for line in lines:
+                    line = line.rstrip("\r")
+                    if line.startswith("event: "):
+                        event_type = line[7:].strip()
+                    elif line.startswith("data: "):
+                        data_str = line[6:]
+
+                # 没有 data 行，直接透传
+                if data_str is None:
+                    yield event_block + b"\n\n"
+                    continue
+
+                # [DONE] 直接透传
+                if data_str.strip() == "[DONE]":
+                    yield event_block + b"\n\n"
+                    continue
+
+                # 尝试解析 JSON
+                try:
+                    data = json.loads(data_str)
+                except json.JSONDecodeError:
+                    yield event_block + b"\n\n"
+                    continue
+
+                # 检测格式并提取内容
+                content, extractor = self._detect_format_and_extract(data)
+
+                # 只有内容长度大于 1 才需要平滑处理
+                if content and len(content) > 1 and extractor:
+                    # 获取配置的延迟
+                    delay_seconds = self._calculate_delay()
+
+                    # 拆分内容
+                    content_chunks = self._split_content(content)
+
+                    for i, sub_content in enumerate(content_chunks):
+                        is_first = is_first_content and i == 0
+
+                        # 使用提取器创建新 chunk
+                        sse_chunk = extractor.create_chunk(
+                            data,
+                            sub_content,
+                            event_type=event_type,
+                            is_first=is_first,
+                        )
+
+                        yield sse_chunk
+
+                        # 除了最后一个块，其他块之间加延迟
+                        if i < len(content_chunks) - 1:
+                            await asyncio.sleep(delay_seconds)
+
+                    is_first_content = False
+                else:
+                    # 不需要拆分，直接透传
+                    yield event_block + b"\n\n"
+                    if content:
+                        is_first_content = False
+
+        # 处理剩余数据
+        if buffer:
+            yield buffer
+
+    def _get_extractor(self, format_name: str) -> Optional[ContentExtractor]:
+        """获取或创建格式对应的提取器（带缓存）"""
+        if format_name not in self._extractors:
+            extractor = get_extractor(format_name)
+            if extractor:
+                self._extractors[format_name] = extractor
+        return self._extractors.get(format_name)
+
+    def _detect_format_and_extract(
+        self, data: dict
+    ) -> tuple[Optional[str], Optional[ContentExtractor]]:
+        """
+        检测数据格式并提取内容
+
+        依次尝试各格式的提取器，返回第一个成功提取内容的结果。
+
+        Returns:
+            (content, extractor): 提取的内容和对应的提取器
+        """
+        for format_name in get_extractor_formats():
+            extractor = self._get_extractor(format_name)
+            if extractor:
+                content = extractor.extract_content(data)
+                if content is not None:
+                    return content, extractor
+
+        return None, None
+
+    def _calculate_delay(self) -> float:
+        """获取配置的延迟（秒）"""
+        return self.smoothing_config.delay_ms / 1000.0
+
+    def _split_content(self, content: str) -> list[str]:
+        """
+        按块拆分文本
+        """
+        chunk_size = self.smoothing_config.chunk_size
+        text_length = len(content)
+
+        if text_length <= chunk_size:
+            return [content]
+
+        # 按块拆分
+        chunks = []
+        for i in range(0, text_length, chunk_size):
+            chunks.append(content[i : i + chunk_size])
+        return chunks
+
     async def _cleanup(
         self,
         response_ctx: Any,
@@ -440,3 +638,128 @@ class StreamProcessor:
             await http_client.aclose()
         except Exception:
             pass
+
+
+async def create_smoothed_stream(
+    stream_generator: AsyncGenerator[bytes, None],
+    chunk_size: int = 20,
+    delay_ms: int = 8,
+) -> AsyncGenerator[bytes, None]:
+    """
+    独立的平滑流生成函数
+
+    供 CLI handler 等场景使用，无需创建完整的 StreamProcessor 实例。
+
+    Args:
+        stream_generator: 原始流生成器
+        chunk_size: 每块字符数
+        delay_ms: 每块之间的延迟毫秒数
+
+    Yields:
+        平滑处理后的响应数据块
+    """
+    processor = _LightweightSmoother(chunk_size=chunk_size, delay_ms=delay_ms)
+    async for chunk in processor.smooth(stream_generator):
+        yield chunk
+
+
+class _LightweightSmoother:
+    """
+    轻量级平滑处理器
+
+    只包含平滑输出所需的最小逻辑，不依赖 StreamProcessor 的其他功能。
+    """
+
+    def __init__(self, chunk_size: int = 20, delay_ms: int = 8) -> None:
+        self.chunk_size = chunk_size
+        self.delay_ms = delay_ms
+        self._extractors: dict[str, ContentExtractor] = {}
+
+    def _get_extractor(self, format_name: str) -> Optional[ContentExtractor]:
+        if format_name not in self._extractors:
+            extractor = get_extractor(format_name)
+            if extractor:
+                self._extractors[format_name] = extractor
+        return self._extractors.get(format_name)
+
+    def _detect_format_and_extract(
+        self, data: dict
+    ) -> tuple[Optional[str], Optional[ContentExtractor]]:
+        for format_name in get_extractor_formats():
+            extractor = self._get_extractor(format_name)
+            if extractor:
+                content = extractor.extract_content(data)
+                if content is not None:
+                    return content, extractor
+        return None, None
+
+    def _calculate_delay(self) -> float:
+        return self.delay_ms / 1000.0
+
+    def _split_content(self, content: str) -> list[str]:
+        text_length = len(content)
+        if text_length <= self.chunk_size:
+            return [content]
+        return [content[i : i + self.chunk_size] for i in range(0, text_length, self.chunk_size)]
+
+    async def smooth(
+        self, stream_generator: AsyncGenerator[bytes, None]
+    ) -> AsyncGenerator[bytes, None]:
+        buffer = b""
+        is_first_content = True
+
+        async for chunk in stream_generator:
+            buffer += chunk
+
+            while b"\n\n" in buffer:
+                event_block, buffer = buffer.split(b"\n\n", 1)
+                event_str = event_block.decode("utf-8", errors="replace")
+
+                lines = event_str.strip().split("\n")
+                data_str = None
+                event_type = ""
+
+                for line in lines:
+                    line = line.rstrip("\r")
+                    if line.startswith("event: "):
+                        event_type = line[7:].strip()
+                    elif line.startswith("data: "):
+                        data_str = line[6:]
+
+                if data_str is None:
+                    yield event_block + b"\n\n"
+                    continue
+
+                if data_str.strip() == "[DONE]":
+                    yield event_block + b"\n\n"
+                    continue
+
+                try:
+                    data = json.loads(data_str)
+                except json.JSONDecodeError:
+                    yield event_block + b"\n\n"
+                    continue
+
+                content, extractor = self._detect_format_and_extract(data)
+
+                if content and len(content) > 1 and extractor:
+                    delay_seconds = self._calculate_delay()
+                    content_chunks = self._split_content(content)
+
+                    for i, sub_content in enumerate(content_chunks):
+                        is_first = is_first_content and i == 0
+                        sse_chunk = extractor.create_chunk(
+                            data, sub_content, event_type=event_type, is_first=is_first
+                        )
+                        yield sse_chunk
+                        if i < len(content_chunks) - 1:
+                            await asyncio.sleep(delay_seconds)
+
+                    is_first_content = False
+                else:
+                    yield event_block + b"\n\n"
+                    if content:
+                        is_first_content = False
+
+        if buffer:
+            yield buffer

src/api/handlers/claude/handler.py

@@ -131,10 +131,5 @@ class ClaudeChatHandler(ChatHandlerBase):
         Returns:
             规范化后的响应
         """
-        if self.response_normalizer and self.response_normalizer.should_normalize(response):
-            result: Dict[str, Any] = self.response_normalizer.normalize_claude_response(
-                response_data=response,
-                request_id=self.request_id,
-            )
-            return result
+        # 作为中转站，直接透传响应，不做标准化处理
         return response

src/api/handlers/gemini/handler.py

@@ -148,17 +148,6 @@ class GeminiChatHandler(ChatHandlerBase):
 
         Returns:
             规范化后的响应
-
-        TODO: 如果需要，实现响应规范化逻辑
         """
-        # 可选：使用 response_normalizer 进行规范化
-        # if (
-        #     self.response_normalizer
-        #     and self.response_normalizer.should_normalize(response)
-        # ):
-        #     return self.response_normalizer.normalize_gemini_response(
-        #         response_data=response,
-        #         request_id=self.request_id,
-        #         strict=False,
-        #     )
+        # 作为中转站，直接透传响应，不做标准化处理
         return response

src/api/handlers/openai/handler.py

@@ -128,10 +128,5 @@ class OpenAIChatHandler(ChatHandlerBase):
         Returns:
             规范化后的响应
         """
-        if self.response_normalizer and self.response_normalizer.should_normalize(response):
-            return self.response_normalizer.normalize_openai_response(
-                response_data=response,
-                request_id=self.request_id,
-                strict=False,
-            )
+        # 作为中转站，直接透传响应，不做标准化处理
         return response

src/clients/http_client.py

@@ -5,12 +5,55 @@
 
 from contextlib import asynccontextmanager
 from typing import Any, Dict, Optional
+from urllib.parse import quote, urlparse
 
 import httpx
 
 from src.core.logger import logger
 
 
+def build_proxy_url(proxy_config: Dict[str, Any]) -> Optional[str]:
+    """
+    根据代理配置构建完整的代理 URL
+
+    Args:
+        proxy_config: 代理配置字典，包含 url, username, password, enabled
+
+    Returns:
+        完整的代理 URL，如 socks5://user:pass@host:port
+        如果 enabled=False 或无配置，返回 None
+    """
+    if not proxy_config:
+        return None
+
+    # 检查 enabled 字段，默认为 True（兼容旧数据）
+    if not proxy_config.get("enabled", True):
+        return None
+
+    proxy_url = proxy_config.get("url")
+    if not proxy_url:
+        return None
+
+    username = proxy_config.get("username")
+    password = proxy_config.get("password")
+
+    # 只要有用户名就添加认证信息（密码可以为空）
+    if username:
+        parsed = urlparse(proxy_url)
+        # URL 编码用户名和密码，处理特殊字符（如 @, :, /）
+        encoded_username = quote(username, safe="")
+        encoded_password = quote(password, safe="") if password else ""
+        # 重新构建带认证的代理 URL
+        if encoded_password:
+            auth_proxy = f"{parsed.scheme}://{encoded_username}:{encoded_password}@{parsed.netloc}"
+        else:
+            auth_proxy = f"{parsed.scheme}://{encoded_username}@{parsed.netloc}"
+        if parsed.path:
+            auth_proxy += parsed.path
+        return auth_proxy
+
+    return proxy_url
+
 
 class HTTPClientPool:
     """
@@ -121,6 +164,44 @@ class HTTPClientPool:
         finally:
             await client.aclose()
 
+    @classmethod
+    def create_client_with_proxy(
+        cls,
+        proxy_config: Optional[Dict[str, Any]] = None,
+        timeout: Optional[httpx.Timeout] = None,
+        **kwargs: Any,
+    ) -> httpx.AsyncClient:
+        """
+        创建带代理配置的HTTP客户端
+
+        Args:
+            proxy_config: 代理配置字典，包含 url, username, password
+            timeout: 超时配置
+            **kwargs: 其他 httpx.AsyncClient 配置参数
+
+        Returns:
+            配置好的 httpx.AsyncClient 实例
+        """
+        config: Dict[str, Any] = {
+            "http2": False,
+            "verify": True,
+            "follow_redirects": True,
+        }
+
+        if timeout:
+            config["timeout"] = timeout
+        else:
+            config["timeout"] = httpx.Timeout(10.0, read=300.0)
+
+        # 添加代理配置
+        proxy_url = build_proxy_url(proxy_config) if proxy_config else None
+        if proxy_url:
+            config["proxy"] = proxy_url
+            logger.debug(f"创建带代理的HTTP客户端: {proxy_config.get('url', 'unknown')}")
+
+        config.update(kwargs)
+        return httpx.AsyncClient(**config)
+
 
 # 便捷访问函数
 def get_http_client() -> httpx.AsyncClient:

src/clients/redis_client.py

@@ -120,7 +120,7 @@ class RedisClientManager:
         if self._circuit_open_until and time.time() < self._circuit_open_until:
             remaining = self._circuit_open_until - time.time()
             logger.warning(
-                "Redis 客户端处于熔断状态，跳过初始化，剩余 %.1f 秒 (last_error: %s)",
+                "Redis 客户端处于熔断状态，跳过初始化，剩余 {:.1f} 秒 (last_error: {})",
                 remaining,
                 self._last_error,
             )
@@ -200,7 +200,7 @@ class RedisClientManager:
             if self._consecutive_failures >= self._circuit_threshold:
                 self._circuit_open_until = time.time() + self._circuit_reset_seconds
                 logger.warning(
-                    "Redis 初始化连续失败 %s 次，开启熔断 %s 秒。"
+                    "Redis 初始化连续失败 {} 次，开启熔断 {} 秒。"
                     "熔断期间以下功能将降级: 缓存亲和性、分布式并发控制、RPM限流。"
                     "可通过管理 API /api/admin/system/redis/reset-circuit 手动重置。",
                     self._consecutive_failures,
@@ -267,6 +267,9 @@ async def get_redis_client(require_redis: bool = False) -> Optional[aioredis.Red
 
     if _redis_manager is None:
         _redis_manager = RedisClientManager()
+    # 如果尚未连接（例如启动时降级、或 close() 后），尝试重新初始化。
+    # initialize() 内部包含熔断器逻辑，避免频繁重试导致抖动。
+    if _redis_manager.get_client() is None:
         await _redis_manager.initialize(require_redis=require_redis)
 
     return _redis_manager.get_client()

src/config/constants.py

@@ -41,8 +41,8 @@ class CacheSize:
 class ConcurrencyDefaults:
     """并发控制默认值"""
 
-    # 自适应并发初始限制（保守值）
-    INITIAL_LIMIT = 3
+    # 自适应并发初始限制（宽松起步，遇到 429 再降低）
+    INITIAL_LIMIT = 50
 
     # 429错误后的冷却时间（分钟）- 在此期间不会增加并发限制
     COOLDOWN_AFTER_429_MINUTES = 5
@@ -67,13 +67,14 @@ class ConcurrencyDefaults:
     MIN_SAMPLES_FOR_DECISION = 5
 
     # 扩容步长 - 每次扩容增加的并发数
-    INCREASE_STEP = 1
+    INCREASE_STEP = 2
 
-    # 缩容乘数 - 遇到 429 时的缩容比例
-    DECREASE_MULTIPLIER = 0.7
+    # 缩容乘数 - 遇到 429 时基于当前并发数的缩容比例
+    # 0.85 表示降到触发 429 时并发数的 85%
+    DECREASE_MULTIPLIER = 0.85
 
     # 最大并发限制上限
-    MAX_CONCURRENT_LIMIT = 100
+    MAX_CONCURRENT_LIMIT = 200
 
     # 最小并发限制下限
     MIN_CONCURRENT_LIMIT = 1
@@ -85,6 +86,11 @@ class ConcurrencyDefaults:
     # 探测性扩容最小请求数 - 在探测间隔内至少需要这么多请求
     PROBE_INCREASE_MIN_REQUESTS = 10
 
+    # === 缓存用户预留比例 ===
+    # 缓存用户槽位预留比例（新用户可用 1 - 此值）
+    # 0.1 表示缓存用户预留 10%，新用户可用 90%
+    CACHE_RESERVATION_RATIO = 0.1
+
 
 class CircuitBreakerDefaults:
     """熔断器配置默认值（滑动窗口 + 半开状态模式）

src/config/settings.py

@@ -105,6 +105,13 @@ class Config:
         self.llm_api_rate_limit = int(os.getenv("LLM_API_RATE_LIMIT", "100"))
         self.public_api_rate_limit = int(os.getenv("PUBLIC_API_RATE_LIMIT", "60"))
 
+        # 可信代理配置
+        # TRUSTED_PROXY_COUNT: 信任的代理层数（默认 1，即信任最近一层代理）
+        # 设置为 0 表示不信任任何代理头，直接使用连接 IP
+        # 当服务部署在 Nginx/CloudFlare 等反向代理后面时，设置为对应的代理层数
+        # 如果服务直接暴露公网，应设置为 0 以防止 IP 伪造
+        self.trusted_proxy_count = int(os.getenv("TRUSTED_PROXY_COUNT", "1"))
+
         # 异常处理配置
         # 设置为 True 时，ProxyException 会传播到路由层以便记录 provider_request_headers
         # 设置为 False 时，使用全局异常处理器统一处理
@@ -122,9 +129,9 @@ class Config:
 
         # 并发控制配置
         # CONCURRENCY_SLOT_TTL: 并发槽位 TTL（秒），防止死锁
-        # CACHE_RESERVATION_RATIO: 缓存用户预留比例（默认 30%）
+        # CACHE_RESERVATION_RATIO: 缓存用户预留比例（默认 10%，新用户可用 90%）
         self.concurrency_slot_ttl = int(os.getenv("CONCURRENCY_SLOT_TTL", "600"))
-        self.cache_reservation_ratio = float(os.getenv("CACHE_RESERVATION_RATIO", "0.3"))
+        self.cache_reservation_ratio = float(os.getenv("CACHE_RESERVATION_RATIO", "0.1"))
 
         # HTTP 请求超时配置（秒）
         self.http_connect_timeout = float(os.getenv("HTTP_CONNECT_TIMEOUT", "10.0"))

src/core/batch_committer.py

@@ -46,6 +46,11 @@ class BatchCommitter:
 
     def mark_dirty(self, session: Session):
         """标记 Session 有待提交的更改"""
+        # 请求级事务由中间件统一 commit/rollback；避免后台任务在请求中途误提交。
+        if session is None:
+            return
+        if session.info.get("managed_by_middleware"):
+            return
         self._pending_sessions.add(session)
 
     async def _batch_commit_loop(self):

src/core/context.py

@@ -1,168 +0,0 @@
-"""
-统一的请求上下文
-
-RequestContext 贯穿整个请求生命周期，包含所有请求相关信息。
-这确保了数据在各层之间传递时不会丢失。
-
-使用方式：
-1. Pipeline 层创建 RequestContext
-2. 各层通过 context 访问和更新信息
-3. Adapter 层使用 context 记录 Usage
-"""
-
-import time
-import uuid
-from dataclasses import dataclass, field
-from typing import Any, Dict, Optional
-
-
-@dataclass
-class RequestContext:
-    """
-    请求上下文 - 贯穿整个请求生命周期
-
-    设计原则：
-    1. 在请求开始时创建，包含所有已知信息
-    2. 在请求执行过程中逐步填充 Provider 信息
-    3. 在请求结束时用于记录 Usage
-    """
-
-    # ==================== 请求标识 ====================
-    request_id: str
-
-    # ==================== 认证信息 ====================
-    user: Any  # User model
-    api_key: Any  # ApiKey model
-    db: Any  # Database session
-
-    # ==================== 请求信息 ====================
-    api_format: str  # CLAUDE, OPENAI, GEMINI, etc.
-    model: str  # 用户请求的模型名
-    is_stream: bool = False
-
-    # ==================== 原始请求 ====================
-    original_headers: Dict[str, str] = field(default_factory=dict)
-    original_body: Dict[str, Any] = field(default_factory=dict)
-
-    # ==================== 客户端信息 ====================
-    client_ip: str = "unknown"
-    user_agent: str = ""
-
-    # ==================== 计时 ====================
-    start_time: float = field(default_factory=time.time)
-
-    # ==================== Provider 信息（请求执行后填充）====================
-    provider_name: Optional[str] = None
-    provider_id: Optional[str] = None
-    endpoint_id: Optional[str] = None
-    provider_api_key_id: Optional[str] = None
-
-    # ==================== 模型映射信息 ====================
-    resolved_model: Optional[str] = None  # 映射后的模型名
-    original_model: Optional[str] = None  # 原始模型名（用于价格计算）
-
-    # ==================== 请求/响应头 ====================
-    provider_request_headers: Dict[str, str] = field(default_factory=dict)
-    provider_response_headers: Dict[str, str] = field(default_factory=dict)
-
-    # ==================== 追踪信息 ====================
-    attempt_id: Optional[str] = None
-
-    # ==================== 能力需求 ====================
-    capability_requirements: Dict[str, bool] = field(default_factory=dict)
-    # 运行时计算的能力需求，来源于:
-    # 1. 用户 model_capability_settings
-    # 2. 用户 ApiKey.force_capabilities
-    # 3. 请求头 X-Require-Capability
-    # 4. 失败重试时动态添加
-
-    @classmethod
-    def create(
-        cls,
-        *,
-        db: Any,
-        user: Any,
-        api_key: Any,
-        api_format: str,
-        model: str,
-        is_stream: bool = False,
-        original_headers: Optional[Dict[str, str]] = None,
-        original_body: Optional[Dict[str, Any]] = None,
-        client_ip: str = "unknown",
-        user_agent: str = "",
-        request_id: Optional[str] = None,
-    ) -> "RequestContext":
-        """创建请求上下文"""
-        return cls(
-            request_id=request_id or str(uuid.uuid4()),
-            db=db,
-            user=user,
-            api_key=api_key,
-            api_format=api_format,
-            model=model,
-            is_stream=is_stream,
-            original_headers=original_headers or {},
-            original_body=original_body or {},
-            client_ip=client_ip,
-            user_agent=user_agent,
-            original_model=model,  # 初始时原始模型等于请求模型
-        )
-
-    def update_provider_info(
-        self,
-        *,
-        provider_name: str,
-        provider_id: str,
-        endpoint_id: str,
-        provider_api_key_id: str,
-        resolved_model: Optional[str] = None,
-    ) -> None:
-        """更新 Provider 信息（请求执行后调用）"""
-        self.provider_name = provider_name
-        self.provider_id = provider_id
-        self.endpoint_id = endpoint_id
-        self.provider_api_key_id = provider_api_key_id
-        if resolved_model:
-            self.resolved_model = resolved_model
-
-    def update_headers(
-        self,
-        *,
-        request_headers: Optional[Dict[str, str]] = None,
-        response_headers: Optional[Dict[str, str]] = None,
-    ) -> None:
-        """更新请求/响应头"""
-        if request_headers:
-            self.provider_request_headers = request_headers
-        if response_headers:
-            self.provider_response_headers = response_headers
-
-    @property
-    def elapsed_ms(self) -> int:
-        """计算已经过的时间（毫秒）"""
-        return int((time.time() - self.start_time) * 1000)
-
-    @property
-    def effective_model(self) -> str:
-        """获取有效的模型名（映射后优先）"""
-        return self.resolved_model or self.model
-
-    @property
-    def billing_model(self) -> str:
-        """获取计费模型名（原始模型优先）"""
-        return self.original_model or self.model
-
-    def to_metadata_dict(self) -> Dict[str, Any]:
-        """转换为元数据字典（用于 Usage 记录）"""
-        return {
-            "api_format": self.api_format,
-            "provider": self.provider_name or "unknown",
-            "model": self.effective_model,
-            "original_model": self.billing_model,
-            "provider_id": self.provider_id,
-            "provider_endpoint_id": self.endpoint_id,
-            "provider_api_key_id": self.provider_api_key_id,
-            "provider_request_headers": self.provider_request_headers,
-            "provider_response_headers": self.provider_response_headers,
-            "attempt_id": self.attempt_id,
-        }

src/core/enums.py

@@ -10,8 +10,8 @@ class APIFormat(Enum):
     """API格式枚举 - 决定请求/响应的处理方式"""
 
     CLAUDE = "CLAUDE"  # Claude API 格式
-    OPENAI = "OPENAI"  # OpenAI API 格式
     CLAUDE_CLI = "CLAUDE_CLI"  # Claude CLI API 格式（使用 authorization: Bearer）
+    OPENAI = "OPENAI"  # OpenAI API 格式
     OPENAI_CLI = "OPENAI_CLI"  # OpenAI CLI/Responses API 格式（用于 Claude Code 等客户端）
     GEMINI = "GEMINI"  # Google Gemini API 格式
     GEMINI_CLI = "GEMINI_CLI"  # Gemini CLI API 格式

src/core/exceptions.py

@@ -442,6 +442,36 @@ class EmbeddedErrorException(ProviderException):
         self.error_status = error_status
 
 
+class ProviderCompatibilityException(ProviderException):
+    """Provider 兼容性错误异常 - 应该触发故障转移
+
+    用于处理因 Provider 不支持某些参数或功能导致的错误。
+    这类错误不是用户请求本身的问题，换一个 Provider 可能就能成功，应该触发故障转移。
+
+    常见场景：
+    - Unsupported parameter（不支持的参数）
+    - Unsupported model（不支持的模型）
+    - Unsupported feature（不支持的功能）
+    """
+
+    def __init__(
+        self,
+        message: str,
+        provider_name: Optional[str] = None,
+        status_code: int = 400,
+        upstream_error: Optional[str] = None,
+        request_metadata: Optional[Any] = None,
+    ):
+        self.upstream_error = upstream_error
+        super().__init__(
+            message=message,
+            provider_name=provider_name,
+            request_metadata=request_metadata,
+        )
+        # 覆盖状态码为 400（保持与上游一致）
+        self.status_code = status_code
+
+
 class UpstreamClientException(ProxyException):
     """上游返回的客户端错误异常 - HTTP 4xx 错误，不应该重试
 

src/core/logger.py

@@ -9,7 +9,7 @@
 
 输出策略:
 - 控制台: 开发环境=DEBUG, 生产环境=INFO (通过 LOG_LEVEL 控制)
-- 文件: 始终保存 DEBUG 级别，保留30天，每日轮转
+- 文件: 始终保存 DEBUG 级别，保留30天，按大小轮转 (100MB)
 
 使用方式:
     from src.core.logger import logger
@@ -72,12 +72,15 @@ def _log_filter(record: dict) -> bool:  # type: ignore[type-arg]
 
 
 if IS_DOCKER:
+    # 生产环境：禁用 backtrace 和 diagnose，减少日志噪音
     logger.add(
         sys.stdout,
         format=CONSOLE_FORMAT_PROD,
         level=LOG_LEVEL,
         filter=_log_filter,  # type: ignore[arg-type]
         colorize=False,
+        backtrace=False,
+        diagnose=False,
     )
 else:
     logger.add(
@@ -92,30 +95,37 @@ if not DISABLE_FILE_LOG:
     log_dir = PROJECT_ROOT / "logs"
     log_dir.mkdir(exist_ok=True)
 
+    # 文件日志通用配置
+    file_log_config = {
+        "format": FILE_FORMAT,
+        "filter": _log_filter,
+        "rotation": "100 MB",
+        "retention": "30 days",
+        "compression": "gz",
+        "enqueue": True,
+        "encoding": "utf-8",
+        "catch": True,
+    }
+
+    # 生产环境禁用详细堆栈
+    if IS_DOCKER:
+        file_log_config["backtrace"] = False
+        file_log_config["diagnose"] = False
+
     # 主日志文件 - 所有级别
     logger.add(
         log_dir / "app.log",
-        format=FILE_FORMAT,
         level="DEBUG",
-        filter=_log_filter,  # type: ignore[arg-type]
-        rotation="00:00",
-        retention="30 days",
-        compression="gz",
-        enqueue=True,
-        encoding="utf-8",
+        **file_log_config,  # type: ignore[arg-type]
     )
 
     # 错误日志文件 - 仅 ERROR 及以上
+    error_log_config = file_log_config.copy()
+    error_log_config["rotation"] = "50 MB"
     logger.add(
         log_dir / "error.log",
-        format=FILE_FORMAT,
         level="ERROR",
-        filter=_log_filter,  # type: ignore[arg-type]
-        rotation="00:00",
-        retention="30 days",
-        compression="gz",
-        enqueue=True,
-        encoding="utf-8",
+        **error_log_config,  # type: ignore[arg-type]
     )
 
 # ============================================================================

src/database/database.py

@@ -5,6 +5,7 @@
 import time
 from typing import AsyncGenerator, Generator, Optional
 
+from starlette.requests import Request
 from sqlalchemy import create_engine, event
 from sqlalchemy.engine import Engine
 from sqlalchemy.ext.asyncio import (
@@ -150,9 +151,22 @@ def _log_pool_capacity():
     theoretical = config.db_pool_size + config.db_max_overflow
     workers = max(1, config.worker_processes)
     total_estimated = theoretical * workers
-    logger.info("数据库连接池配置")
-    if total_estimated > config.db_pool_warn_threshold:
-        logger.warning("数据库连接需求可能超过阈值，请调小池大小或减少 worker 数")
+    safe_limit = config.pg_max_connections - config.pg_reserved_connections
+    logger.info(
+        "数据库连接池配置: pool_size={}, max_overflow={}, workers={}, total_estimated={}, safe_limit={}",
+        config.db_pool_size,
+        config.db_max_overflow,
+        workers,
+        total_estimated,
+        safe_limit,
+    )
+    if total_estimated > safe_limit:
+        logger.warning(
+            "数据库连接池总需求可能超过 PostgreSQL 限制: {} > {} (pg_max_connections - reserved)，"
+            "建议调整 DB_POOL_SIZE/DB_MAX_OVERFLOW 或减少 worker 数",
+            total_estimated,
+            safe_limit,
+        )
 
 
 def _ensure_async_engine() -> AsyncEngine:
@@ -185,7 +199,7 @@ def _ensure_async_engine() -> AsyncEngine:
     # 创建异步引擎
     _async_engine = create_async_engine(
         ASYNC_DATABASE_URL,
-        poolclass=QueuePool,  # 使用队列连接池
+        # AsyncEngine 不能使用 QueuePool；默认使用 AsyncAdaptedQueuePool
         pool_size=config.db_pool_size,
         max_overflow=config.db_max_overflow,
         pool_timeout=config.db_pool_timeout,
@@ -209,7 +223,18 @@ def _ensure_async_engine() -> AsyncEngine:
 
 
 async def get_async_db() -> AsyncGenerator[AsyncSession, None]:
-    """获取异步数据库会话"""
+    """获取异步数据库会话
+
+    .. deprecated::
+        此方法已废弃，项目统一使用同步 Session。
+        未来版本可能移除此方法。请使用 get_db() 代替。
+    """
+    import warnings
+    warnings.warn(
+        "get_async_db() 已废弃，项目统一使用同步 Session。请使用 get_db() 代替。",
+        DeprecationWarning,
+        stacklevel=2,
+    )
     # 确保异步引擎已初始化
     _ensure_async_engine()
 
@@ -220,16 +245,73 @@ async def get_async_db() -> AsyncGenerator[AsyncSession, None]:
             await session.close()
 
 
-def get_db() -> Generator[Session, None, None]:
+def get_db(request: Request = None) -> Generator[Session, None, None]:  # type: ignore[assignment]
     """获取数据库会话
 
-    注意：事务管理由业务逻辑层显式控制（手动调用 commit/rollback）
-    这里只负责会话的创建和关闭，不自动提交
+    事务策略说明
+    ============
+    本项目采用**混合事务管理**策略：
+
+    1. **LLM 请求路径**：
+       - 由 PluginMiddleware 统一管理事务
+       - Service 层使用 db.flush() 使更改可见，但不提交
+       - 请求结束时由中间件统一 commit 或 rollback
+       - 例外：UsageService.record_usage() 会显式 commit，因为使用记录需要立即持久化
+
+    2. **管理后台 API**：
+       - 路由层显式调用 db.commit()
+       - 提交后设置 request.state.tx_committed_by_route = True
+       - 中间件看到此标志后跳过 commit，只负责 close
+
+    3. **后台任务/调度器**：
+       - 使用独立 Session（通过 create_session() 或 next(get_db())）
+       - 自行管理事务生命周期
+
+    使用方式
+    ========
+    - FastAPI 请求：通过 Depends(get_db) 注入，支持中间件管理的 session 复用
+    - 非请求上下文：直接调用 get_db()，退化为独立 session 模式
+
+    路由层提交事务示例
+    ==================
+    ```python
+    @router.post("/example")
+    async def example(request: Request, db: Session = Depends(get_db)):
+        # ... 业务逻辑 ...
+        db.commit()
+        request.state.tx_committed_by_route = True  # 告知中间件已提交
+        return {"message": "success"}
+    ```
+
+    注意事项
+    ========
+    - 本函数不自动提交事务
+    - 异常时会自动回滚
+    - 中间件管理模式下，session 关闭由中间件负责
     """
+    # FastAPI 请求上下文：优先复用中间件绑定的 request.state.db
+    if request is not None:
+        existing_db = getattr(getattr(request, "state", None), "db", None)
+        if isinstance(existing_db, Session):
+            yield existing_db
+            return
+
     # 确保引擎已初始化
     _ensure_engine()
 
     db = _SessionLocal()
+
+    # 如果中间件声明会统一管理会话生命周期，则把 session 绑定到 request.state，
+    # 并由中间件负责 commit/rollback/close（这里不关闭，避免流式响应提前释放会话）。
+    managed_by_middleware = bool(
+        request is not None
+        and hasattr(request, "state")
+        and getattr(request.state, "db_managed_by_middleware", False)
+    )
+    if managed_by_middleware:
+        request.state.db = db
+        db.info["managed_by_middleware"] = True
+
     try:
         yield db
         # 不再自动 commit，由业务代码显式管理事务
@@ -241,12 +323,13 @@ def get_db() -> Generator[Session, None, None]:
             logger.debug(f"回滚事务时出错（可忽略）: {rollback_error}")
         raise
     finally:
-        try:
-            db.close()  # 确保连接返回池
-        except Exception as close_error:
-            # 记录关闭错误（如 IllegalStateChangeError）
-            # 连接池会处理连接的回收
-            logger.debug(f"关闭数据库连接时出错（可忽略）: {close_error}")
+        if not managed_by_middleware:
+            try:
+                db.close()  # 确保连接返回池
+            except Exception as close_error:
+                # 记录关闭错误（如 IllegalStateChangeError）
+                # 连接池会处理连接的回收
+                logger.debug(f"关闭数据库连接时出错（可忽略）: {close_error}")
 
 
 def create_session() -> Session:
@@ -336,7 +419,7 @@ def init_admin_user(db: Session):
         admin.set_password(config.admin_password)
 
         db.add(admin)
-        db.commit()  # 刷新以获取ID，但不提交
+        db.flush()  # 分配ID，但不提交事务（由外层 init_db 统一 commit）
 
         logger.info(f"创建管理员账户成功: {admin.email} ({admin.username})")
     except Exception as e:

src/main.py

@@ -3,7 +3,6 @@
 采用模块化架构设计
 """
 
-import asyncio
 from contextlib import asynccontextmanager
 from pathlib import Path
 
@@ -39,20 +38,18 @@ async def initialize_providers():
     """从数据库初始化提供商（仅用于日志记录）"""
     from sqlalchemy.orm import Session
 
-    from src.core.enums import APIFormat
-    from src.database import get_db
+    from src.database.database import create_session
     from src.models.database import Provider
 
     try:
         # 创建数据库会话
-        db_gen = get_db()
-        db: Session = next(db_gen)
+        db: Session = create_session()
 
         try:
             # 从数据库加载所有活跃的提供商
             providers = (
                 db.query(Provider)
-                .filter(Provider.is_active == True)
+                .filter(Provider.is_active.is_(True))
                 .order_by(Provider.provider_priority.asc())
                 .all()
             )
@@ -75,7 +72,7 @@ async def initialize_providers():
         finally:
             db.close()
 
-    except Exception as e:
+    except Exception:
         logger.exception("从数据库初始化提供商失败")
 
 
@@ -125,6 +122,7 @@ async def lifespan(app: FastAPI):
     logger.info("初始化全局Redis客户端...")
     from src.clients.redis_client import get_redis_client
 
+    redis_client = None
     try:
         redis_client = await get_redis_client(require_redis=config.require_redis)
         if redis_client:
@@ -136,6 +134,7 @@ async def lifespan(app: FastAPI):
             logger.exception("[ERROR] Redis连接失败，应用启动中止")
             raise
         logger.warning(f"Redis连接失败，但配置允许降级，将继续使用内存模式: {e}")
+        redis_client = None
 
     # 初始化并发管理器（内部会使用Redis）
     logger.info("初始化并发管理器...")
@@ -315,7 +314,7 @@ if frontend_dist.exists():
         仅对非API路径生效
         """
         # 如果是API路径，不处理
-        if full_path.startswith("api/") or full_path.startswith("v1/"):
+        if full_path in {"api", "v1"} or full_path.startswith(("api/", "v1/")):
             raise HTTPException(status_code=404, detail="Not Found")
 
         # 返回index.html，让前端路由处理

src/middleware/plugin_middleware.py

@@ -1,38 +1,43 @@
 """
-统一的插件中间件
+统一的插件中间件（纯 ASGI 实现）
 负责协调所有插件的调用
+
+注意：使用纯 ASGI middleware 而非 BaseHTTPMiddleware，
+以避免 Starlette 已知的流式响应兼容性问题。
 """
 
+import hashlib
 import time
-from typing import Any, Awaitable, Callable, Optional
+from typing import Optional
 
-from fastapi import HTTPException, Request
-from fastapi.responses import JSONResponse
-from sqlalchemy.orm import Session
-from starlette.middleware.base import BaseHTTPMiddleware
-from starlette.responses import Response as StarletteResponse
+from starlette.requests import Request
+from starlette.types import ASGIApp, Message, Receive, Scope, Send
 
 from src.config import config
 from src.core.logger import logger
-from src.database import get_db
 from src.plugins.manager import get_plugin_manager
 from src.plugins.rate_limit.base import RateLimitResult
 
 
-
-class PluginMiddleware(BaseHTTPMiddleware):
+class PluginMiddleware:
     """
-    统一的插件调用中间件
+    统一的插件调用中间件（纯 ASGI 实现）
 
     职责:
     - 性能监控
     - 限流控制 (可选)
+    - 数据库会话生命周期管理
 
     注意: 认证由各路由通过 Depends() 显式声明，不在中间件层处理
+
+    为什么使用纯 ASGI 而非 BaseHTTPMiddleware:
+    - BaseHTTPMiddleware 会缓冲整个响应体，对流式响应不友好
+    - BaseHTTPMiddleware 与 StreamingResponse 存在已知兼容性问题
+    - 纯 ASGI 可以直接透传流式响应，无额外开销
     """
 
-    def __init__(self, app: Any) -> None:
-        super().__init__(app)
+    def __init__(self, app: ASGIApp) -> None:
+        self.app = app
         self.plugin_manager = get_plugin_manager()
 
         # 从配置读取速率限制值
@@ -62,175 +67,159 @@ class PluginMiddleware(BaseHTTPMiddleware):
             "/v1/completions",
         ]
 
-    async def dispatch(
-        self, request: Request, call_next: Callable[[Request], Awaitable[StarletteResponse]]
-    ) -> StarletteResponse:
-        """处理请求并调用相应插件"""
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        """ASGI 入口点"""
+        if scope["type"] != "http":
+            # 非 HTTP 请求（如 WebSocket）直接透传
+            await self.app(scope, receive, send)
+            return
+
+        # 构建 Request 对象以便复用现有逻辑
+        request = Request(scope, receive, send)
 
         # 记录请求开始时间
         start_time = time.time()
+
+        # 设置 request.state 属性
+        # 注意：Starlette 的 Request 对象总是有 state 属性（State 实例）
         request.state.request_id = request.headers.get("x-request-id", "")
         request.state.start_time = start_time
+        # 标记：若请求过程中通过 Depends(get_db) 创建了会话，则由本中间件统一管理其生命周期
+        request.state.db_managed_by_middleware = True
 
-        # 从 request.app 获取 FastAPI 应用实例（而不是从 __init__ 的 app 参数）
-        # 这样才能访问到真正的 FastAPI 实例和其 dependency_overrides
-        db_func = get_db
-        if hasattr(request, "app") and hasattr(request.app, "dependency_overrides"):
-            if get_db in request.app.dependency_overrides:
-                db_func = request.app.dependency_overrides[get_db]
-                logger.debug("Using overridden get_db from app.dependency_overrides")
+        # 1. 限流检查（在调用下游之前）
+        rate_limit_result = await self._call_rate_limit_plugins(request)
+        if rate_limit_result and not rate_limit_result.allowed:
+            # 限流触发，返回429
+            await self._send_rate_limit_response(send, rate_limit_result)
+            return
 
-        # 创建数据库会话供需要的插件或后续处理使用
-        db_gen = db_func()
-        db = None
-        response = None
-        exception_to_raise = None
+        # 2. 预处理插件调用
+        await self._call_pre_request_plugins(request)
 
+        # 用于捕获响应状态码
+        response_status_code: int = 0
+
+        async def send_wrapper(message: Message) -> None:
+            nonlocal response_status_code
+
+            if message["type"] == "http.response.start":
+                response_status_code = message.get("status", 0)
+
+            await send(message)
+
+        # 3. 调用下游应用
+        exception_occurred: Optional[Exception] = None
         try:
-            # 获取数据库会话
-            db = next(db_gen)
-            request.state.db = db
-
-            # 1. 限流插件调用（可选功能）
-            rate_limit_result = await self._call_rate_limit_plugins(request)
-            if rate_limit_result and not rate_limit_result.allowed:
-                # 限流触发，返回429
-                headers = rate_limit_result.headers or {}
-                raise HTTPException(
-                    status_code=429,
-                    detail=rate_limit_result.message or "Rate limit exceeded",
-                    headers=headers,
-                )
-
-            # 2. 预处理插件调用
-            await self._call_pre_request_plugins(request)
-
-            # 处理请求
-            response = await call_next(request)
-
-            # 3. 提交关键数据库事务（在返回响应前）
-            # 这确保了 Usage 记录、配额扣减等关键数据在响应返回前持久化
-            try:
-                db.commit()
-            except Exception as commit_error:
-                logger.error(f"关键事务提交失败: {commit_error}")
-                db.rollback()
-                # 返回 500 错误，因为数据可能不一致
-                response = JSONResponse(
-                    status_code=500,
-                    content={
-                        "type": "error",
-                        "error": {
-                            "type": "database_error",
-                            "message": "数据保存失败，请重试",
-                        },
-                    },
-                )
-                # 跳过后处理插件，直接返回错误响应
-                return response
-
-            # 4. 后处理插件调用（监控等，非关键操作）
-            # 这些操作失败不应影响用户响应
-            await self._call_post_request_plugins(request, response, start_time)
-
-            # 注意：不在此处添加限流响应头，因为在BaseHTTPMiddleware中
-            # 响应返回后修改headers会导致Content-Length不匹配错误
-            # 限流响应头已在返回429错误时正确包含（见上面的HTTPException）
-
-        except RuntimeError as e:
-            if str(e) == "No response returned.":
-                if db:
-                    db.rollback()
-
-                logger.error("Downstream handler completed without returning a response")
-
-                await self._call_error_plugins(request, e, start_time)
-
-                if db:
-                    try:
-                        db.commit()
-                    except Exception:
-                        pass
-
-                response = JSONResponse(
-                    status_code=500,
-                    content={
-                        "type": "error",
-                        "error": {
-                            "type": "internal_error",
-                            "message": "Internal server error: downstream handler returned no response.",
-                        },
-                    },
-                )
-            else:
-                exception_to_raise = e
-
+            await self.app(scope, receive, send_wrapper)
         except Exception as e:
-            # 回滚数据库事务
-            if db:
-                db.rollback()
-
+            exception_occurred = e
             # 错误处理插件调用
             await self._call_error_plugins(request, e, start_time)
+            raise
+        finally:
+            # 4. 数据库会话清理（无论成功与否）
+            await self._cleanup_db_session(request, exception_occurred)
 
-            # 尝试提交错误日志
-            if db:
+        # 5. 后处理插件调用（仅在成功时）
+        if not exception_occurred and response_status_code > 0:
+            await self._call_post_request_plugins(request, response_status_code, start_time)
+
+    async def _send_rate_limit_response(
+        self, send: Send, result: RateLimitResult
+    ) -> None:
+        """发送 429 限流响应"""
+        import json
+
+        body = json.dumps({
+            "type": "error",
+            "error": {
+                "type": "rate_limit_error",
+                "message": result.message or "Rate limit exceeded",
+            },
+        }).encode("utf-8")
+
+        headers = [(b"content-type", b"application/json")]
+        if result.headers:
+            for key, value in result.headers.items():
+                headers.append((key.lower().encode(), str(value).encode()))
+
+        await send({
+            "type": "http.response.start",
+            "status": 429,
+            "headers": headers,
+        })
+        await send({
+            "type": "http.response.body",
+            "body": body,
+        })
+
+    async def _cleanup_db_session(
+        self, request: Request, exception: Optional[Exception]
+    ) -> None:
+        """清理数据库会话
+
+        事务策略：
+        - 如果 request.state.tx_committed_by_route 为 True，说明路由已自行提交，中间件只负责 close
+        - 否则由中间件统一 commit/rollback
+
+        这避免了双重提交的问题，同时保持向后兼容。
+        """
+        from sqlalchemy.orm import Session
+
+        db = getattr(request.state, "db", None)
+        if not isinstance(db, Session):
+            return
+
+        # 检查是否由路由层已经提交
+        tx_committed_by_route = getattr(request.state, "tx_committed_by_route", False)
+
+        try:
+            if exception is not None:
+                # 发生异常，回滚事务（无论谁负责提交）
+                try:
+                    db.rollback()
+                except Exception as rollback_error:
+                    logger.debug(f"回滚事务时出错（可忽略）: {rollback_error}")
+            elif not tx_committed_by_route:
+                # 正常完成且路由未自行提交，由中间件提交事务
                 try:
                     db.commit()
-                except:
-                    pass
-
-            exception_to_raise = e
-
-        finally:
-            # 确保数据库会话被正确关闭
-            # 注意：需要安全地处理各种状态，避免 IllegalStateChangeError
-            if db is not None:
-                try:
-                    # 检查会话是否可以安全地进行回滚
-                    # 只有当没有进行中的事务操作时才尝试回滚
-                    if db.is_active and not db.get_transaction().is_active:
-                        # 事务不在活跃状态，可以安全回滚
+                except Exception as commit_error:
+                    logger.error(f"关键事务提交失败: {commit_error}")
+                    try:
+                        db.rollback()
+                    except Exception:
                         pass
-                    elif db.is_active:
-                        # 事务在活跃状态，尝试回滚
-                        try:
-                            db.rollback()
-                        except Exception as rollback_error:
-                            # 回滚失败（可能是 commit 正在进行中），忽略错误
-                            logger.debug(f"Rollback skipped: {rollback_error}")
-                except Exception:
-                    # 检查状态时出错，忽略
-                    pass
-
-            # 通过触发生成器的 finally 块来关闭会话（标准模式）
-            # 这会调用 get_db() 的 finally 块，执行 db.close()
+            # 如果 tx_committed_by_route 为 True，跳过 commit（路由已提交）
+        finally:
+            # 关闭会话，归还连接到连接池
             try:
-                next(db_gen, None)
-            except StopIteration:
-                # 正常情况：生成器已耗尽
-                pass
-            except Exception as cleanup_error:
-                # 忽略 IllegalStateChangeError 等清理错误
-                # 这些错误通常是由于事务状态不一致导致的，不影响业务逻辑
-                if "IllegalStateChangeError" not in str(type(cleanup_error).__name__):
-                    logger.warning(f"Database cleanup warning: {cleanup_error}")
-
-        # 在 finally 块之后处理异常和响应
-        if exception_to_raise:
-            raise exception_to_raise
-
-        return response
+                db.close()
+            except Exception as close_error:
+                logger.debug(f"关闭数据库连接时出错（可忽略）: {close_error}")
 
     def _get_client_ip(self, request: Request) -> str:
         """
         获取客户端 IP 地址，支持代理头
+
+        注意：此方法信任 X-Forwarded-For 和 X-Real-IP 头，
+        仅当服务部署在可信代理（如 Nginx、CloudFlare）后面时才安全。
+        如果服务直接暴露公网，攻击者可伪造这些头绕过限流。
         """
+        # 从配置获取可信代理层数（默认为 1，即信任最近一层代理）
+        trusted_proxy_count = getattr(config, "trusted_proxy_count", 1)
+
         # 优先从代理头获取真实 IP
         forwarded_for = request.headers.get("x-forwarded-for")
         if forwarded_for:
-            # X-Forwarded-For 可能包含多个 IP，取第一个
-            return forwarded_for.split(",")[0].strip()
+            # X-Forwarded-For 格式: "client, proxy1, proxy2"
+            # 从右往左数 trusted_proxy_count 个，取其左边的第一个
+            ips = [ip.strip() for ip in forwarded_for.split(",")]
+            if len(ips) > trusted_proxy_count:
+                return ips[-(trusted_proxy_count + 1)]
+            elif ips:
+                return ips[0]
 
         real_ip = request.headers.get("x-real-ip")
         if real_ip:
@@ -250,7 +239,7 @@ class PluginMiddleware(BaseHTTPMiddleware):
         return False
 
     async def _get_rate_limit_key_and_config(
-        self, request: Request, db: Session
+        self, request: Request
     ) -> tuple[Optional[str], Optional[int]]:
         """
         获取速率限制的key和配置
@@ -272,13 +261,11 @@ class PluginMiddleware(BaseHTTPMiddleware):
             auth_header = request.headers.get("authorization", "")
             api_key = request.headers.get("x-api-key", "")
 
-            if auth_header.startswith("Bearer "):
+            if auth_header.lower().startswith("bearer "):
                 api_key = auth_header[7:]
 
             if api_key:
                 # 使用 API Key 的哈希作为限制 key（避免日志泄露完整 key）
-                import hashlib
-
                 key_hash = hashlib.sha256(api_key.encode()).hexdigest()[:16]
                 key = f"llm_api_key:{key_hash}"
                 request.state.rate_limit_key_type = "api_key"
@@ -318,14 +305,8 @@ class PluginMiddleware(BaseHTTPMiddleware):
             # 如果没有限流插件，允许通过
             return None
 
-        # 获取数据库会话
-        db = getattr(request.state, "db", None)
-        if not db:
-            logger.warning("速率限制检查：无法获取数据库会话")
-            return None
-
-        # 获取速率限制的key和配置（从数据库）
-        key, rate_limit_value = await self._get_rate_limit_key_and_config(request, db)
+        # 获取速率限制的 key 和配置
+        key, rate_limit_value = await self._get_rate_limit_key_and_config(request)
         if not key:
             # 不需要限流的端点（如未分类路径），静默跳过
             return None
@@ -336,7 +317,7 @@ class PluginMiddleware(BaseHTTPMiddleware):
                 key=key,
                 endpoint=request.url.path,
                 method=request.method,
-                rate_limit=rate_limit_value,  # 传入数据库配置的限制值
+                rate_limit=rate_limit_value,  # 传入配置的限制值
             )
             # 类型检查：确保返回的是RateLimitResult类型
             if isinstance(result, RateLimitResult):
@@ -349,7 +330,10 @@ class PluginMiddleware(BaseHTTPMiddleware):
                     )
                 else:
                     # 限流触发，记录日志
-                    logger.warning(f"速率限制触发: {getattr(request.state, 'rate_limit_key_type', 'unknown')}")
+                    logger.warning(
+                        "速率限制触发: {}",
+                        getattr(request.state, "rate_limit_key_type", "unknown"),
+                    )
                 return result
             return None
         except Exception as e:
@@ -362,7 +346,7 @@ class PluginMiddleware(BaseHTTPMiddleware):
         pass
 
     async def _call_post_request_plugins(
-        self, request: Request, response: StarletteResponse, start_time: float
+        self, request: Request, status_code: int, start_time: float
     ) -> None:
         """调用请求后的插件"""
 
@@ -375,8 +359,8 @@ class PluginMiddleware(BaseHTTPMiddleware):
                 monitor_labels = {
                     "method": request.method,
                     "endpoint": request.url.path,
-                    "status": str(response.status_code),
-                    "status_class": f"{response.status_code // 100}xx",
+                    "status": str(status_code),
+                    "status_class": f"{status_code // 100}xx",
                 }
 
                 # 记录请求计数
@@ -398,6 +382,7 @@ class PluginMiddleware(BaseHTTPMiddleware):
         self, request: Request, error: Exception, start_time: float
     ) -> None:
         """调用错误处理插件"""
+        from fastapi import HTTPException
 
         duration = time.time() - start_time
 
@@ -410,7 +395,7 @@ class PluginMiddleware(BaseHTTPMiddleware):
                         error=error,
                         context={
                             "endpoint": f"{request.method} {request.url.path}",
-                            "request_id": request.state.request_id,
+                            "request_id": getattr(request.state, "request_id", ""),
                             "duration": duration,
                         },
                     )

src/models/admin_requests.py

@@ -13,6 +13,42 @@ from pydantic import BaseModel, Field, field_validator, model_validator
 from src.core.enums import APIFormat, ProviderBillingType
 
 
+class ProxyConfig(BaseModel):
+    """代理配置"""
+
+    url: str = Field(..., description="代理 URL (http://, https://, socks5://)")
+    username: Optional[str] = Field(None, max_length=255, description="代理用户名")
+    password: Optional[str] = Field(None, max_length=500, description="代理密码")
+    enabled: bool = Field(True, description="是否启用代理（false 时保留配置但不使用）")
+
+    @field_validator("url")
+    @classmethod
+    def validate_proxy_url(cls, v: str) -> str:
+        """验证代理 URL 格式"""
+        from urllib.parse import urlparse
+
+        v = v.strip()
+
+        # 检查禁止的字符（防止注入）
+        if "\n" in v or "\r" in v:
+            raise ValueError("代理 URL 包含非法字符")
+
+        # 验证协议（不支持 SOCKS4）
+        if not re.match(r"^(http|https|socks5)://", v, re.IGNORECASE):
+            raise ValueError("代理 URL 必须以 http://, https:// 或 socks5:// 开头")
+
+        # 验证 URL 结构
+        parsed = urlparse(v)
+        if not parsed.netloc:
+            raise ValueError("代理 URL 必须包含有效的 host")
+
+        # 禁止 URL 中内嵌认证信息，强制使用独立字段
+        if parsed.username or parsed.password:
+            raise ValueError("请勿在 URL 中包含用户名和密码，请使用独立的认证字段")
+
+        return v
+
+
 class CreateProviderRequest(BaseModel):
     """创建 Provider 请求"""
 
@@ -107,20 +143,6 @@ class CreateProviderRequest(BaseModel):
         if not re.match(r"^https?://", v, re.IGNORECASE):
             v = f"https://{v}"
 
-        # 防止 SSRF 攻击：禁止内网地址
-        forbidden_patterns = [
-            r"localhost",
-            r"127\.0\.0\.1",
-            r"0\.0\.0\.0",
-            r"192\.168\.",
-            r"10\.",
-            r"172\.(1[6-9]|2[0-9]|3[0-1])\.",
-            r"169\.254\.",
-        ]
-        for pattern in forbidden_patterns:
-            if re.search(pattern, v, re.IGNORECASE):
-                raise ValueError("不允许使用内网地址")
-
         return v
 
     @field_validator("billing_type")
@@ -179,6 +201,7 @@ class CreateEndpointRequest(BaseModel):
     rpm_limit: Optional[int] = Field(None, ge=0, description="RPM 限制")
     concurrent_limit: Optional[int] = Field(None, ge=0, description="并发限制")
     config: Optional[Dict[str, Any]] = Field(None, description="其他配置")
+    proxy: Optional[ProxyConfig] = Field(None, description="代理配置")
 
     @field_validator("name")
     @classmethod
@@ -195,19 +218,6 @@ class CreateEndpointRequest(BaseModel):
         if not re.match(r"^https?://", v, re.IGNORECASE):
             raise ValueError("URL 必须以 http:// 或 https:// 开头")
 
-        # 防止 SSRF
-        forbidden_patterns = [
-            r"localhost",
-            r"127\.0\.0\.1",
-            r"0\.0\.0\.0",
-            r"192\.168\.",
-            r"10\.",
-            r"172\.(1[6-9]|2[0-9]|3[0-1])\.",
-        ]
-        for pattern in forbidden_patterns:
-            if re.search(pattern, v, re.IGNORECASE):
-                raise ValueError("不允许使用内网地址")
-
         return v.rstrip("/")  # 移除末尾斜杠
 
     @field_validator("api_format")
@@ -247,6 +257,7 @@ class UpdateEndpointRequest(BaseModel):
     rpm_limit: Optional[int] = Field(None, ge=0)
     concurrent_limit: Optional[int] = Field(None, ge=0)
     config: Optional[Dict[str, Any]] = None
+    proxy: Optional[ProxyConfig] = Field(None, description="代理配置")
 
     # 复用验证器
     _validate_name = field_validator("name")(CreateEndpointRequest.validate_name.__func__)

src/models/api.py

@@ -6,7 +6,7 @@ import re
 from datetime import datetime
 from typing import Any, Dict, List, Optional
 
-from pydantic import BaseModel, Field, field_validator
+from pydantic import BaseModel, ConfigDict, Field, field_validator
 
 from ..core.enums import UserRole
 
@@ -336,8 +336,7 @@ class ProviderResponse(BaseModel):
     active_models_count: int = 0
     api_keys_count: int = 0
 
-    class Config:
-        from_attributes = True
+    model_config = ConfigDict(from_attributes=True)
 
 
 # ========== 模型管理 ==========
@@ -442,8 +441,7 @@ class ModelResponse(BaseModel):
     global_model_name: Optional[str] = None
     global_model_display_name: Optional[str] = None
 
-    class Config:
-        from_attributes = True
+    model_config = ConfigDict(from_attributes=True)
 
 
 class ModelDetailResponse(BaseModel):
@@ -469,8 +467,7 @@ class ModelDetailResponse(BaseModel):
     created_at: datetime
     updated_at: datetime
 
-    class Config:
-        from_attributes = True
+    model_config = ConfigDict(from_attributes=True)
 
 
 # ========== 系统设置 ==========

src/models/api_key.py

@@ -5,7 +5,7 @@ Provider API Key相关的API模型
 from datetime import datetime
 from typing import Optional
 
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, ConfigDict, Field
 
 
 class ProviderAPIKeyBase(BaseModel):
@@ -53,8 +53,7 @@ class ProviderAPIKeyResponse(ProviderAPIKeyBase):
     created_at: datetime
     updated_at: datetime
 
-    class Config:
-        from_attributes = True
+    model_config = ConfigDict(from_attributes=True)
 
 
 class ProviderAPIKeyStats(BaseModel):

src/models/database.py

@@ -27,8 +27,7 @@ from sqlalchemy import (
     UniqueConstraint,
 )
 from sqlalchemy.dialects.postgresql import JSONB
-from sqlalchemy.ext.declarative import declarative_base
-from sqlalchemy.orm import relationship
+from sqlalchemy.orm import declarative_base, relationship
 
 from ..config import config
 from ..core.enums import ProviderBillingType, UserRole
@@ -539,6 +538,9 @@ class ProviderEndpoint(Base):
     # 额外配置
     config = Column(JSON, nullable=True)  # 端点特定配置（不推荐使用，优先使用专用字段）
 
+    # 代理配置
+    proxy = Column(JSONB, nullable=True)  # 代理配置: {url, username, password}
+
     # 时间戳
     created_at = Column(
         DateTime(timezone=True), default=lambda: datetime.now(timezone.utc), nullable=False

src/models/endpoint_models.py

@@ -6,7 +6,9 @@ import re
 from datetime import datetime
 from typing import Any, Dict, List, Optional
 
-from pydantic import BaseModel, Field, field_validator
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from src.models.admin_requests import ProxyConfig
 
 # ========== ProviderEndpoint CRUD ==========
 
@@ -30,6 +32,9 @@ class ProviderEndpointCreate(BaseModel):
     # 额外配置
     config: Optional[Dict[str, Any]] = Field(default=None, description="额外配置（JSON）")
 
+    # 代理配置
+    proxy: Optional[ProxyConfig] = Field(default=None, description="代理配置")
+
     @field_validator("api_format")
     @classmethod
     def validate_api_format(cls, v: str) -> str:
@@ -45,24 +50,9 @@ class ProviderEndpointCreate(BaseModel):
     @field_validator("base_url")
     @classmethod
     def validate_base_url(cls, v: str) -> str:
-        """验证 API URL（SSRF 防护）"""
         if not re.match(r"^https?://", v, re.IGNORECASE):
             raise ValueError("URL 必须以 http:// 或 https:// 开头")
 
-        # 防止 SSRF 攻击：禁止内网地址
-        forbidden_patterns = [
-            r"localhost",
-            r"127\.0\.0\.1",
-            r"0\.0\.0\.0",
-            r"192\.168\.",
-            r"10\.",
-            r"172\.(1[6-9]|2[0-9]|3[0-1])\.",
-            r"169\.254\.",
-        ]
-        for pattern in forbidden_patterns:
-            if re.search(pattern, v, re.IGNORECASE):
-                raise ValueError("不允许使用内网地址")
-
         return v.rstrip("/")  # 移除末尾斜杠
 
 
@@ -79,31 +69,18 @@ class ProviderEndpointUpdate(BaseModel):
     rate_limit: Optional[int] = Field(default=None, ge=1, description="速率限制")
     is_active: Optional[bool] = Field(default=None, description="是否启用")
     config: Optional[Dict[str, Any]] = Field(default=None, description="额外配置")
+    proxy: Optional[ProxyConfig] = Field(default=None, description="代理配置")
 
     @field_validator("base_url")
     @classmethod
     def validate_base_url(cls, v: Optional[str]) -> Optional[str]:
-        """验证 API URL（SSRF 防护）"""
+        """验证 API URL"""
         if v is None:
             return v
 
         if not re.match(r"^https?://", v, re.IGNORECASE):
             raise ValueError("URL 必须以 http:// 或 https:// 开头")
 
-        # 防止 SSRF 攻击：禁止内网地址
-        forbidden_patterns = [
-            r"localhost",
-            r"127\.0\.0\.1",
-            r"0\.0\.0\.0",
-            r"192\.168\.",
-            r"10\.",
-            r"172\.(1[6-9]|2[0-9]|3[0-1])\.",
-            r"169\.254\.",
-        ]
-        for pattern in forbidden_patterns:
-            if re.search(pattern, v, re.IGNORECASE):
-                raise ValueError("不允许使用内网地址")
-
         return v.rstrip("/")  # 移除末尾斜杠
 
 
@@ -133,6 +110,9 @@ class ProviderEndpointResponse(BaseModel):
     # 额外配置
     config: Optional[Dict[str, Any]] = None
 
+    # 代理配置（响应中密码已脱敏）
+    proxy: Optional[Dict[str, Any]] = Field(default=None, description="代理配置（密码已脱敏）")
+
     # 统计（从 Keys 聚合）
     total_keys: int = Field(default=0, description="总 Key 数量")
     active_keys: int = Field(default=0, description="活跃 Key 数量")
@@ -141,8 +121,7 @@ class ProviderEndpointResponse(BaseModel):
     created_at: datetime
     updated_at: datetime
 
-    class Config:
-        from_attributes = True
+    model_config = ConfigDict(from_attributes=True)
 
 
 # ========== ProviderAPIKey 相关（新架构） ==========
@@ -384,8 +363,7 @@ class EndpointAPIKeyResponse(BaseModel):
     created_at: datetime
     updated_at: datetime
 
-    class Config:
-        from_attributes = True
+    model_config = ConfigDict(from_attributes=True)
 
 
 # ========== 健康监控相关 ==========
@@ -535,8 +513,7 @@ class ProviderWithEndpointsSummary(BaseModel):
     created_at: datetime
     updated_at: datetime
 
-    class Config:
-        from_attributes = True
+    model_config = ConfigDict(from_attributes=True)
 
 
 # ========== 健康监控可视化模型 ==========

src/models/pydantic_models.py

@@ -5,7 +5,7 @@ Pydantic 数据模型（阶段一统一模型管理）
 from datetime import datetime
 from typing import Any, Dict, List, Optional
 
-from pydantic import BaseModel, Field, model_validator
+from pydantic import BaseModel, ConfigDict, Field, model_validator
 
 
 # ========== 阶梯计费相关模型 ==========
@@ -256,8 +256,7 @@ class GlobalModelResponse(BaseModel):
     created_at: datetime
     updated_at: Optional[datetime]
 
-    class Config:
-        from_attributes = True
+    model_config = ConfigDict(from_attributes=True)
 
 
 class GlobalModelWithStats(GlobalModelResponse):

src/plugins/auth/jwt.py

@@ -3,6 +3,7 @@ JWT认证插件
 支持JWT Bearer token认证
 """
 
+import hashlib
 from typing import Optional
 
 from fastapi import Request
@@ -46,12 +47,12 @@ class JwtAuthPlugin(AuthPlugin):
             logger.debug("未找到JWT token")
             return None
 
-        # 记录认证尝试的详细信息
-        logger.info(f"JWT认证尝试 - 路径: {request.url.path}, Token前20位: {token[:20]}...")
+        token_fingerprint = hashlib.sha256(token.encode()).hexdigest()[:12]
+        logger.info(f"JWT认证尝试 - 路径: {request.url.path}, token_fp={token_fingerprint}")
 
         try:
             # 验证JWT token
-            payload = AuthService.verify_token(token)
+            payload = await AuthService.verify_token(token, token_type="access")
             logger.debug(f"JWT token验证成功, payload: {payload}")
 
             # 从payload中提取用户信息

src/services/auth/jwt_blacklist.py

@@ -63,14 +63,16 @@ class JWTBlacklistService:
 
             if ttl_seconds <= 0:
                 # Token 已经过期，不需要加入黑名单
-                logger.debug(f"Token 已过期，无需加入黑名单: {token[:10]}...")
+                token_fp = JWTBlacklistService._get_token_hash(token)[:12]
+                logger.debug("Token 已过期，无需加入黑名单: token_fp={}", token_fp)
                 return True
 
             # 存储到 Redis，设置 TTL 为 Token 过期时间
             # 值存储为原因字符串
             await redis_client.setex(redis_key, ttl_seconds, reason)
 
-            logger.info(f"Token 已加入黑名单: {token[:10]}... (原因: {reason}, TTL: {ttl_seconds}s)")
+            token_fp = JWTBlacklistService._get_token_hash(token)[:12]
+            logger.info("Token 已加入黑名单: token_fp={} (原因: {}, TTL: {}s)", token_fp, reason, ttl_seconds)
             return True
 
         except Exception as e:
@@ -109,7 +111,8 @@ class JWTBlacklistService:
             if exists:
                 # 获取黑名单原因（可选）
                 reason = await redis_client.get(redis_key)
-                logger.warning(f"检测到黑名单 Token: {token[:10]}... (原因: {reason})")
+                token_fp = JWTBlacklistService._get_token_hash(token)[:12]
+                logger.warning("检测到黑名单 Token: token_fp={} (原因: {})", token_fp, reason)
                 return True
 
             return False
@@ -148,9 +151,11 @@ class JWTBlacklistService:
             deleted = await redis_client.delete(redis_key)
 
             if deleted:
-                logger.info(f"Token 已从黑名单移除: {token[:10]}...")
+                token_fp = JWTBlacklistService._get_token_hash(token)[:12]
+                logger.info("Token 已从黑名单移除: token_fp={}", token_fp)
             else:
-                logger.debug(f"Token 不在黑名单中: {token[:10]}...")
+                token_fp = JWTBlacklistService._get_token_hash(token)[:12]
+                logger.debug("Token 不在黑名单中: token_fp={}", token_fp)
 
             return bool(deleted)
 

src/services/auth/service.py

@@ -3,6 +3,7 @@
 """
 
 import os
+import hashlib
 import secrets
 from datetime import datetime, timedelta, timezone
 from typing import Any, Dict, Optional
@@ -93,8 +94,8 @@ class AuthService:
     @staticmethod
     async def authenticate_user(db: Session, email: str, password: str) -> Optional[User]:
         """用户登录认证"""
-        # 使用缓存查询用户
-        user = await UserCacheService.get_user_by_email(db, email)
+        # 登录校验必须读取密码哈希，不能使用不包含 password_hash 的缓存对象
+        user = db.query(User).filter(User.email == email).first()
 
         if not user:
             logger.warning(f"登录失败 - 用户不存在: {email}")
@@ -109,13 +110,10 @@ class AuthService:
             return None
 
         # 更新最后登录时间
-        # 需要重新从数据库获取以便更新（缓存的对象是分离的）
-        db_user = db.query(User).filter(User.id == user.id).first()
-        if db_user:
-            db_user.last_login_at = datetime.now(timezone.utc)
-            db.commit()  # 立即提交事务,释放数据库锁
-            # 清除缓存，因为用户信息已更新
-            await UserCacheService.invalidate_user_cache(user.id, user.email)
+        user.last_login_at = datetime.now(timezone.utc)
+        db.commit()  # 立即提交事务,释放数据库锁
+        # 清除缓存，因为用户信息已更新
+        await UserCacheService.invalidate_user_cache(user.id, user.email)
 
         logger.info(f"用户登录成功: {email} (ID: {user.id})")
         return user
@@ -172,7 +170,8 @@ class AuthService:
         key_record.last_used_at = datetime.now(timezone.utc)
         db.commit()  # 立即提交事务,释放数据库锁,避免阻塞后续请求
 
-        logger.debug(f"API认证成功: 用户 {user.email} (Key: {api_key[:10]}...)")
+        api_key_fp = hashlib.sha256(api_key.encode()).hexdigest()[:12]
+        logger.debug("API认证成功: 用户 {} (api_key_fp={})", user.email, api_key_fp)
         return user, key_record
 
     @staticmethod
@@ -198,7 +197,10 @@ class AuthService:
         if user.role == UserRole.ADMIN:
             return True
 
-        if user.role.value >= required_role.value:
+        # 避免使用字符串比较导致权限判断错误（例如 'user' >= 'admin'）
+        role_rank = {UserRole.USER: 0, UserRole.ADMIN: 1}
+        # 未知用户角色默认 -1（拒绝），未知要求角色默认 999（拒绝）
+        if role_rank.get(user.role, -1) >= role_rank.get(required_role, 999):
             return True
 
         logger.warning(f"权限不足: 用户 {user.email} 角色 {user.role.value} < 需要 {required_role.value}")
@@ -230,7 +232,7 @@ class AuthService:
             )
 
             if success:
-                user_id = payload.get("sub")
+                user_id = payload.get("user_id")
                 logger.info(f"用户登出成功: user_id={user_id}")
 
             return success

src/services/cache/aware_scheduler.py

@@ -59,7 +59,6 @@ from src.services.health.monitor import health_monitor
 from src.services.provider.format import normalize_api_format
 from src.services.rate_limit.adaptive_reservation import (
     AdaptiveReservationManager,
-    ReservationResult,
     get_adaptive_reservation_manager,
 )
 from src.services.rate_limit.concurrency_manager import get_concurrency_manager
@@ -112,8 +111,6 @@ class CacheAwareScheduler:
     - 健康度监控
     """
 
-    # 静态常量作为默认值（实际由 AdaptiveReservationManager 动态计算）
-    CACHE_RESERVATION_RATIO = 0.3
     # 优先级模式常量
     PRIORITY_MODE_PROVIDER = "provider"  # 提供商优先模式
     PRIORITY_MODE_GLOBAL_KEY = "global_key"  # 全局 Key 优先模式
@@ -1320,7 +1317,6 @@ class CacheAwareScheduler:
 
         return {
             "scheduler": "cache_aware",
-            "cache_reservation_ratio": self.CACHE_RESERVATION_RATIO,
             "dynamic_reservation": {
                 "enabled": True,
                 "config": reservation_stats["config"],

src/services/cache/model_cache.py

@@ -1,5 +1,21 @@
 """
 Model 映射缓存服务 - 减少模型查询
+
+架构说明
+========
+本服务采用混合 async/sync 模式：
+- 缓存操作（CacheService）：真正的 async，使用 aioredis
+- 数据库查询（db.query）：同步的 SQLAlchemy Session
+
+设计决策
+--------
+1. 保持 async 方法签名：因为缓存命中时完全异步，性能最优
+2. 缓存未命中时的同步查询：FastAPI 会在线程池中执行，不会阻塞事件循环
+3. 调用方必须在 async 上下文中使用 await
+
+使用示例
+--------
+    global_model = await ModelCacheService.resolve_global_model_by_name_or_alias(db, "gpt-4")
 """
 
 import time
@@ -19,7 +35,11 @@ from src.models.database import GlobalModel, Model
 
 
 class ModelCacheService:
-    """Model 映射缓存服务"""
+    """Model 映射缓存服务
+
+    提供 GlobalModel 和 Model 的缓存查询功能，减少数据库访问。
+    所有公开方法均为 async，需要在 async 上下文中调用。
+    """
 
     # 缓存 TTL（秒）- 使用统一常量
     CACHE_TTL = CacheTTL.MODEL

src/services/cache/provider_cache.py

@@ -1,254 +0,0 @@
-"""
-Provider 配置缓存服务 - 减少 Provider/Endpoint/APIKey 查询
-"""
-
-from typing import Any, Dict, List, Optional
-
-from sqlalchemy.orm import Session
-
-from src.config.constants import CacheTTL
-from src.core.cache_service import CacheKeys, CacheService
-from src.core.logger import logger
-from src.models.database import Provider, ProviderAPIKey, ProviderEndpoint
-
-
-
-class ProviderCacheService:
-    """Provider 配置缓存服务"""
-
-    # 缓存 TTL（秒）- 使用统一常量
-    CACHE_TTL = CacheTTL.PROVIDER
-
-    @staticmethod
-    async def get_provider_by_id(db: Session, provider_id: str) -> Optional[Provider]:
-        """
-        获取 Provider（带缓存）
-
-        Args:
-            db: 数据库会话
-            provider_id: Provider ID
-
-        Returns:
-            Provider 对象或 None
-        """
-        cache_key = CacheKeys.provider_by_id(provider_id)
-
-        # 1. 尝试从缓存获取
-        cached_data = await CacheService.get(cache_key)
-        if cached_data:
-            logger.debug(f"Provider 缓存命中: {provider_id}")
-            return ProviderCacheService._dict_to_provider(cached_data)
-
-        # 2. 缓存未命中，查询数据库
-        provider = db.query(Provider).filter(Provider.id == provider_id).first()
-
-        # 3. 写入缓存
-        if provider:
-            provider_dict = ProviderCacheService._provider_to_dict(provider)
-            await CacheService.set(
-                cache_key, provider_dict, ttl_seconds=ProviderCacheService.CACHE_TTL
-            )
-            logger.debug(f"Provider 已缓存: {provider_id}")
-
-        return provider
-
-    @staticmethod
-    async def get_endpoint_by_id(db: Session, endpoint_id: str) -> Optional[ProviderEndpoint]:
-        """
-        获取 Endpoint（带缓存）
-
-        Args:
-            db: 数据库会话
-            endpoint_id: Endpoint ID
-
-        Returns:
-            ProviderEndpoint 对象或 None
-        """
-        cache_key = CacheKeys.endpoint_by_id(endpoint_id)
-
-        # 1. 尝试从缓存获取
-        cached_data = await CacheService.get(cache_key)
-        if cached_data:
-            logger.debug(f"Endpoint 缓存命中: {endpoint_id}")
-            return ProviderCacheService._dict_to_endpoint(cached_data)
-
-        # 2. 缓存未命中，查询数据库
-        endpoint = db.query(ProviderEndpoint).filter(ProviderEndpoint.id == endpoint_id).first()
-
-        # 3. 写入缓存
-        if endpoint:
-            endpoint_dict = ProviderCacheService._endpoint_to_dict(endpoint)
-            await CacheService.set(
-                cache_key, endpoint_dict, ttl_seconds=ProviderCacheService.CACHE_TTL
-            )
-            logger.debug(f"Endpoint 已缓存: {endpoint_id}")
-
-        return endpoint
-
-    @staticmethod
-    async def get_api_key_by_id(db: Session, api_key_id: str) -> Optional[ProviderAPIKey]:
-        """
-        获取 API Key（带缓存）
-
-        Args:
-            db: 数据库会话
-            api_key_id: API Key ID
-
-        Returns:
-            ProviderAPIKey 对象或 None
-        """
-        cache_key = CacheKeys.api_key_by_id(api_key_id)
-
-        # 1. 尝试从缓存获取
-        cached_data = await CacheService.get(cache_key)
-        if cached_data:
-            logger.debug(f"API Key 缓存命中: {api_key_id}")
-            return ProviderCacheService._dict_to_api_key(cached_data)
-
-        # 2. 缓存未命中，查询数据库
-        api_key = db.query(ProviderAPIKey).filter(ProviderAPIKey.id == api_key_id).first()
-
-        # 3. 写入缓存
-        if api_key:
-            api_key_dict = ProviderCacheService._api_key_to_dict(api_key)
-            await CacheService.set(
-                cache_key, api_key_dict, ttl_seconds=ProviderCacheService.CACHE_TTL
-            )
-            logger.debug(f"API Key 已缓存: {api_key_id}")
-
-        return api_key
-
-    @staticmethod
-    async def invalidate_provider_cache(provider_id: str):
-        """
-        清除 Provider 缓存
-
-        Args:
-            provider_id: Provider ID
-        """
-        await CacheService.delete(CacheKeys.provider_by_id(provider_id))
-        logger.debug(f"Provider 缓存已清除: {provider_id}")
-
-    @staticmethod
-    async def invalidate_endpoint_cache(endpoint_id: str):
-        """
-        清除 Endpoint 缓存
-
-        Args:
-            endpoint_id: Endpoint ID
-        """
-        await CacheService.delete(CacheKeys.endpoint_by_id(endpoint_id))
-        logger.debug(f"Endpoint 缓存已清除: {endpoint_id}")
-
-    @staticmethod
-    async def invalidate_api_key_cache(api_key_id: str):
-        """
-        清除 API Key 缓存
-
-        Args:
-            api_key_id: API Key ID
-        """
-        await CacheService.delete(CacheKeys.api_key_by_id(api_key_id))
-        logger.debug(f"API Key 缓存已清除: {api_key_id}")
-
-    @staticmethod
-    def _provider_to_dict(provider: Provider) -> dict:
-        """将 Provider 对象转换为字典（用于缓存）"""
-        return {
-            "id": provider.id,
-            "name": provider.name,
-            "api_format": provider.api_format,
-            "base_url": provider.base_url,
-            "is_active": provider.is_active,
-            "priority": provider.priority,
-            "rpm_limit": provider.rpm_limit,
-            "rpm_used": provider.rpm_used,
-            "rpm_reset_at": provider.rpm_reset_at.isoformat() if provider.rpm_reset_at else None,
-            "config": provider.config,
-            "description": provider.description,
-        }
-
-    @staticmethod
-    def _dict_to_provider(provider_dict: dict) -> Provider:
-        """从字典重建 Provider 对象（分离的对象，不在 Session 中）"""
-        from datetime import datetime
-
-        provider = Provider(
-            id=provider_dict["id"],
-            name=provider_dict["name"],
-            api_format=provider_dict["api_format"],
-            base_url=provider_dict.get("base_url"),
-            is_active=provider_dict["is_active"],
-            priority=provider_dict.get("priority", 0),
-            rpm_limit=provider_dict.get("rpm_limit"),
-            rpm_used=provider_dict.get("rpm_used", 0),
-            config=provider_dict.get("config"),
-            description=provider_dict.get("description"),
-        )
-
-        if provider_dict.get("rpm_reset_at"):
-            provider.rpm_reset_at = datetime.fromisoformat(provider_dict["rpm_reset_at"])
-
-        return provider
-
-    @staticmethod
-    def _endpoint_to_dict(endpoint: ProviderEndpoint) -> dict:
-        """将 Endpoint 对象转换为字典"""
-        return {
-            "id": endpoint.id,
-            "provider_id": endpoint.provider_id,
-            "name": endpoint.name,
-            "base_url": endpoint.base_url,
-            "is_active": endpoint.is_active,
-            "priority": endpoint.priority,
-            "weight": endpoint.weight,
-            "custom_path": endpoint.custom_path,
-            "config": endpoint.config,
-        }
-
-    @staticmethod
-    def _dict_to_endpoint(endpoint_dict: dict) -> ProviderEndpoint:
-        """从字典重建 Endpoint 对象"""
-        endpoint = ProviderEndpoint(
-            id=endpoint_dict["id"],
-            provider_id=endpoint_dict["provider_id"],
-            name=endpoint_dict["name"],
-            base_url=endpoint_dict["base_url"],
-            is_active=endpoint_dict["is_active"],
-            priority=endpoint_dict.get("priority", 0),
-            weight=endpoint_dict.get("weight", 1.0),
-            custom_path=endpoint_dict.get("custom_path"),
-            config=endpoint_dict.get("config"),
-        )
-        return endpoint
-
-    @staticmethod
-    def _api_key_to_dict(api_key: ProviderAPIKey) -> dict:
-        """将 API Key 对象转换为字典"""
-        return {
-            "id": api_key.id,
-            "endpoint_id": api_key.endpoint_id,
-            "key_value": api_key.key_value,
-            "is_active": api_key.is_active,
-            "max_rpm": api_key.max_rpm,
-            "current_rpm": api_key.current_rpm,
-            "health_score": api_key.health_score,
-            "circuit_breaker_state": api_key.circuit_breaker_state,
-            "adaptive_concurrency_limit": api_key.adaptive_concurrency_limit,
-        }
-
-    @staticmethod
-    def _dict_to_api_key(api_key_dict: dict) -> ProviderAPIKey:
-        """从字典重建 API Key 对象"""
-        api_key = ProviderAPIKey(
-            id=api_key_dict["id"],
-            endpoint_id=api_key_dict["endpoint_id"],
-            key_value=api_key_dict["key_value"],
-            is_active=api_key_dict["is_active"],
-            max_rpm=api_key_dict.get("max_rpm"),
-            current_rpm=api_key_dict.get("current_rpm", 0),
-            health_score=api_key_dict.get("health_score", 1.0),
-            circuit_breaker_state=api_key_dict.get("circuit_breaker_state"),
-            adaptive_concurrency_limit=api_key_dict.get("adaptive_concurrency_limit"),
-        )
-        return api_key

src/services/cache/user_cache.py

@@ -1,5 +1,22 @@
 """
 用户缓存服务 - 减少数据库查询
+
+架构说明
+========
+本服务采用混合 async/sync 模式：
+- 缓存操作（CacheService）：真正的 async，使用 aioredis
+- 数据库查询（db.query）：同步的 SQLAlchemy Session
+
+设计决策
+--------
+1. 保持 async 方法签名：因为缓存命中时完全异步，性能最优
+2. 缓存未命中时的同步查询：FastAPI 会在线程池中执行，不会阻塞事件循环
+3. 调用方必须在 async 上下文中使用 await
+
+使用示例
+--------
+    user = await UserCacheService.get_user_by_id(db, user_id)
+    await UserCacheService.invalidate_user_cache(user_id, email)
 """
 
 from typing import Optional
@@ -12,9 +29,12 @@ from src.core.logger import logger
 from src.models.database import User
 
 
-
 class UserCacheService:
-    """用户缓存服务"""
+    """用户缓存服务
+
+    提供 User 的缓存查询功能，减少数据库访问。
+    所有公开方法均为 async，需要在 async 上下文中调用。
+    """
 
     # 缓存 TTL（秒）- 使用统一常量
     CACHE_TTL = CacheTTL.USER

src/services/model/service.py

@@ -13,6 +13,7 @@ from src.core.exceptions import InvalidRequestException, NotFoundException
 from src.core.logger import logger
 from src.models.api import ModelCreate, ModelResponse, ModelUpdate
 from src.models.database import Model, Provider
+from src.api.base.models_service import invalidate_models_list_cache
 from src.services.cache.invalidation import get_cache_invalidation_service
 from src.services.cache.model_cache import ModelCacheService
 
@@ -75,6 +76,10 @@ class ModelService:
                 )
 
             logger.info(f"创建模型成功: provider={provider.name}, model={model.provider_model_name}, global_model_id={model.global_model_id}")
+
+            # 清除 /v1/models 列表缓存
+            asyncio.create_task(invalidate_models_list_cache())
+
             return model
 
         except IntegrityError as e:
@@ -197,6 +202,9 @@ class ModelService:
                 cache_service = get_cache_invalidation_service()
                 cache_service.on_model_changed(model.provider_id, model.global_model_id)
 
+            # 清除 /v1/models 列表缓存
+            asyncio.create_task(invalidate_models_list_cache())
+
             logger.info(f"更新模型成功: id={model_id}, 最终 supports_vision: {model.supports_vision}, supports_function_calling: {model.supports_function_calling}, supports_extended_thinking: {model.supports_extended_thinking}")
             return model
         except IntegrityError as e:
@@ -261,6 +269,9 @@ class ModelService:
                 cache_service = get_cache_invalidation_service()
                 cache_service.on_model_changed(cache_info["provider_id"], cache_info["global_model_id"])
 
+            # 清除 /v1/models 列表缓存
+            asyncio.create_task(invalidate_models_list_cache())
+
             logger.info(f"删除模型成功: id={model_id}, provider_model_name={cache_info['provider_model_name']}, "
                 f"global_model_id={cache_info['global_model_id'][:8] if cache_info['global_model_id'] else 'None'}...")
         except Exception as e:
@@ -295,6 +306,9 @@ class ModelService:
             cache_service = get_cache_invalidation_service()
             cache_service.on_model_changed(model.provider_id, model.global_model_id)
 
+        # 清除 /v1/models 列表缓存
+        asyncio.create_task(invalidate_models_list_cache())
+
         status = "可用" if is_available else "不可用"
         logger.info(f"更新模型可用状态: id={model_id}, status={status}")
         return model
@@ -358,6 +372,9 @@ class ModelService:
                 for model in created_models:
                     db.refresh(model)
                 logger.info(f"批量创建 {len(created_models)} 个模型成功")
+
+                # 清除 /v1/models 列表缓存
+                asyncio.create_task(invalidate_models_list_cache())
             except IntegrityError as e:
                 db.rollback()
                 logger.error(f"批量创建模型失败: {str(e)}")

src/services/orchestration/error_classifier.py

@@ -15,6 +15,7 @@ from src.core.enums import APIFormat
 from src.core.exceptions import (
     ConcurrencyLimitError,
     ProviderAuthException,
+    ProviderCompatibilityException,
     ProviderException,
     ProviderNotAvailableException,
     ProviderRateLimitException,
@@ -69,24 +70,31 @@ class ErrorClassifier:
     # 这些错误是由用户请求本身导致的，换 Provider 也无济于事
     # 注意：标准 API 返回的 error.type 已在 CLIENT_ERROR_TYPES 中处理
     # 这里主要用于匹配非标准格式或第三方代理的错误消息
+    #
+    # 重要：不要在此列表中包含 Provider Key 配置问题（如 invalid_api_key）
+    # 这类错误应该触发故障转移，而不是直接返回给用户
     CLIENT_ERROR_PATTERNS: Tuple[str, ...] = (
         "could not process image",  # 图片处理失败
         "image too large",  # 图片过大
         "invalid image",  # 无效图片
         "unsupported image",  # 不支持的图片格式
         "content_policy_violation",  # 内容违规
-        "invalid_api_key",  # 无效的 API Key（不同于认证失败）
         "context_length_exceeded",  # 上下文长度超限
         "content_length_limit",  # 请求内容长度超限 (Claude API)
-        "max_tokens",  # token 数超限
+        "content_length_exceeds",  # 内容长度超限变体 (AWS CodeWhisperer)
+        # 注意：移除了 "max_tokens"，因为 max_tokens 相关错误可能是 Provider 兼容性问题
+        # 如 "Unsupported parameter: 'max_tokens' is not supported with this model"
+        # 这类错误应由 COMPATIBILITY_ERROR_PATTERNS 处理
         "invalid_prompt",  # 无效的提示词
         "content too long",  # 内容过长
+        "input is too long",  # 输入过长 (AWS)
         "message is too long",  # 消息过长
         "prompt is too long",  # Prompt 超长（第三方代理常见格式）
         "image exceeds",  # 图片超出限制
         "pdf too large",  # PDF 过大
         "file too large",  # 文件过大
         "tool_use_id",  # tool_result 引用了不存在的 tool_use（兼容非标准代理）
+        "validationexception",  # AWS 验证异常
     )
 
     def __init__(
@@ -110,18 +118,137 @@ class ErrorClassifier:
     # 表示客户端错误的 error type（不区分大小写）
     # 这些 type 表明是请求本身的问题，不应重试
     CLIENT_ERROR_TYPES: Tuple[str, ...] = (
-        "invalid_request_error",  # Claude/OpenAI 标准客户端错误类型
-        "invalid_argument",  # Gemini 参数错误
-        "failed_precondition",  # Gemini 前置条件错误
+        # Claude/OpenAI 标准
+        "invalid_request_error",
+        # Gemini
+        "invalid_argument",
+        "failed_precondition",
+        # AWS
+        "validationexception",
+        # 通用
+        "validation_error",
+        "bad_request",
     )
 
+    # 表示客户端错误的 reason/code 字段值
+    CLIENT_ERROR_REASONS: Tuple[str, ...] = (
+        "CONTENT_LENGTH_EXCEEDS_THRESHOLD",
+        "CONTEXT_LENGTH_EXCEEDED",
+        "MAX_TOKENS_EXCEEDED",
+        "INVALID_CONTENT",
+        "CONTENT_POLICY_VIOLATION",
+    )
+
+    # Provider 兼容性错误模式 - 这类错误应该触发故障转移
+    # 因为换一个 Provider 可能就能成功
+    COMPATIBILITY_ERROR_PATTERNS: Tuple[str, ...] = (
+        "unsupported parameter",  # 不支持的参数
+        "unsupported model",  # 不支持的模型
+        "unsupported feature",  # 不支持的功能
+        "not supported with this model",  # 此模型不支持
+        "model does not support",  # 模型不支持
+        "parameter is not supported",  # 参数不支持
+        "feature is not supported",  # 功能不支持
+        "not available for this model",  # 此模型不可用
+    )
+
+    def _parse_error_response(self, error_text: Optional[str]) -> Dict[str, Any]:
+        """
+        解析错误响应为结构化数据
+
+        支持多种格式:
+        - {"error": {"type": "...", "message": "..."}}  (Claude/OpenAI)
+        - {"error": {"message": "...", "__type": "..."}}  (AWS)
+        - {"errorMessage": "..."}  (Lambda)
+        - {"error": "..."}
+        - {"message": "...", "reason": "..."}
+
+        Returns:
+            结构化的错误信息: {
+                "type": str,      # 错误类型
+                "message": str,   # 错误消息
+                "reason": str,    # 错误原因/代码
+                "raw": str,       # 原始文本
+            }
+        """
+        result = {"type": "", "message": "", "reason": "", "raw": error_text or ""}
+
+        if not error_text:
+            return result
+
+        try:
+            data = json.loads(error_text)
+
+            # 格式 1: {"error": {"type": "...", "message": "..."}}
+            if isinstance(data.get("error"), dict):
+                error_obj = data["error"]
+                result["type"] = str(error_obj.get("type", ""))
+                result["message"] = str(error_obj.get("message", ""))
+
+                # AWS 格式: {"error": {"__type": "...", "message": "...", "reason": "..."}}
+                # __type 直接在 error 对象中，而不是嵌套在 message 里
+                if "__type" in error_obj:
+                    result["type"] = result["type"] or str(error_obj.get("__type", ""))
+                if "reason" in error_obj:
+                    result["reason"] = str(error_obj.get("reason", ""))
+                if "code" in error_obj:
+                    result["reason"] = result["reason"] or str(error_obj.get("code", ""))
+
+                # 嵌套 JSON 格式: message 字段本身是 JSON 字符串
+                # 支持多种嵌套格式：
+                # - AWS: {"__type": "...", "message": "...", "reason": "..."}
+                # - 第三方代理: {"error": {"type": "...", "message": "..."}}
+                if result["message"].startswith("{"):
+                    try:
+                        nested = json.loads(result["message"])
+                        if isinstance(nested, dict):
+                            # AWS 格式
+                            if "__type" in nested:
+                                result["type"] = result["type"] or str(nested.get("__type", ""))
+                                result["message"] = str(nested.get("message", result["message"]))
+                                result["reason"] = str(nested.get("reason", ""))
+                            # 第三方代理格式: {"error": {"message": "..."}}
+                            elif isinstance(nested.get("error"), dict):
+                                inner_error = nested["error"]
+                                inner_msg = str(inner_error.get("message", ""))
+                                if inner_msg:
+                                    result["message"] = inner_msg
+                            # 简单格式: {"message": "..."}
+                            elif "message" in nested:
+                                result["message"] = str(nested["message"])
+                    except json.JSONDecodeError:
+                        pass
+
+            # 格式 2: {"error": "..."}
+            elif isinstance(data.get("error"), str):
+                result["message"] = str(data["error"])
+
+            # 格式 3: {"errorMessage": "..."}  (Lambda)
+            elif "errorMessage" in data:
+                result["message"] = str(data["errorMessage"])
+
+            # 格式 4: {"message": "...", "reason": "..."}
+            elif "message" in data:
+                result["message"] = str(data["message"])
+                result["reason"] = str(data.get("reason", ""))
+
+            # 提取顶层的 reason/code
+            if not result["reason"]:
+                result["reason"] = str(data.get("reason", data.get("code", "")))
+
+        except (json.JSONDecodeError, TypeError, KeyError):
+            result["message"] = error_text[:500] if len(error_text) > 500 else error_text
+
+        return result
+
     def _is_client_error(self, error_text: Optional[str]) -> bool:
         """
         检测错误响应是否为客户端错误（不应重试）
 
-        判断逻辑：
+        判断逻辑（按优先级）：
         1. 检查 error.type 是否为已知的客户端错误类型
-        2. 检查错误文本是否包含已知的客户端错误模式
+        2. 检查 reason/code 是否为已知的客户端错误原因
+        3. 回退到关键词匹配
 
         Args:
             error_text: 错误响应文本
@@ -132,67 +259,72 @@ class ErrorClassifier:
         if not error_text:
             return False
 
-        # 尝试解析 JSON 并检查 error type
-        try:
-            data = json.loads(error_text)
-            if isinstance(data.get("error"), dict):
-                error_type = data["error"].get("type", "")
-                if error_type and any(
-                    t.lower() in error_type.lower() for t in self.CLIENT_ERROR_TYPES
-                ):
-                    return True
-        except (json.JSONDecodeError, TypeError, KeyError):
-            pass
+        parsed = self._parse_error_response(error_text)
 
-        # 回退到关键词匹配
-        error_lower = error_text.lower()
-        return any(pattern.lower() in error_lower for pattern in self.CLIENT_ERROR_PATTERNS)
+        # 1. 检查 error type
+        if parsed["type"]:
+            error_type_lower = parsed["type"].lower()
+            if any(t.lower() in error_type_lower for t in self.CLIENT_ERROR_TYPES):
+                return True
 
-    def _extract_error_message(self, error_text: Optional[str]) -> Optional[str]:
+        # 2. 检查 reason/code
+        if parsed["reason"]:
+            reason_upper = parsed["reason"].upper()
+            if any(r in reason_upper for r in self.CLIENT_ERROR_REASONS):
+                return True
+
+        # 3. 回退到关键词匹配（合并 message 和 raw）
+        search_text = f"{parsed['message']} {parsed['raw']}".lower()
+        return any(pattern.lower() in search_text for pattern in self.CLIENT_ERROR_PATTERNS)
+
+    def _is_compatibility_error(self, error_text: Optional[str]) -> bool:
         """
-        从错误响应中提取错误消息
+        检测错误响应是否为 Provider 兼容性错误（应触发故障转移）
 
-        支持格式：
-        - {"error": {"message": "..."}}  (OpenAI/Claude)
-        - {"error": {"type": "...", "message": "..."}}
-        - {"error": "..."}
-        - {"message": "..."}
+        这类错误是因为 Provider 不支持某些参数或功能导致的，
+        换一个 Provider 可能就能成功。
 
         Args:
             error_text: 错误响应文本
 
         Returns:
-            提取的错误消息，如果无法解析则返回原始文本
+            是否为兼容性错误
+        """
+        if not error_text:
+            return False
+
+        search_text = error_text.lower()
+        return any(pattern.lower() in search_text for pattern in self.COMPATIBILITY_ERROR_PATTERNS)
+
+    def _extract_error_message(self, error_text: Optional[str]) -> Optional[str]:
+        """
+        从错误响应中提取错误消息
+
+        Args:
+            error_text: 错误响应文本
+
+        Returns:
+            提取的错误消息
         """
         if not error_text:
             return None
 
-        try:
-            data = json.loads(error_text)
+        parsed = self._parse_error_response(error_text)
 
-            # {"error": {"message": "..."}} 或 {"error": {"type": "...", "message": "..."}}
-            if isinstance(data.get("error"), dict):
-                error_obj = data["error"]
-                message = error_obj.get("message", "")
-                error_type = error_obj.get("type", "")
-                if message:
-                    if error_type:
-                        return f"{error_type}: {message}"
-                    return str(message)
+        # 构建可读的错误消息
+        parts = []
+        if parsed["type"]:
+            parts.append(parsed["type"])
+        if parsed["reason"]:
+            parts.append(f"[{parsed['reason']}]")
+        if parsed["message"]:
+            parts.append(parsed["message"])
 
-            # {"error": "..."}
-            if isinstance(data.get("error"), str):
-                return str(data["error"])
-
-            # {"message": "..."}
-            if isinstance(data.get("message"), str):
-                return str(data["message"])
-
-        except (json.JSONDecodeError, TypeError, KeyError):
-            pass
+        if parts:
+            return ": ".join(parts) if len(parts) > 1 else parts[0]
 
         # 无法解析，返回原始文本（截断）
-        return error_text[:500] if len(error_text) > 500 else error_text
+        return parsed["raw"][:500] if len(parsed["raw"]) > 500 else parsed["raw"]
 
     def classify(
         self,
@@ -328,6 +460,16 @@ class ErrorClassifier:
                 ),
             )
 
+        # 400 错误：先检查是否为 Provider 兼容性错误（应触发故障转移）
+        if status == 400 and self._is_compatibility_error(error_response_text):
+            logger.info(f"检测到 Provider 兼容性错误，将触发故障转移: {extracted_message}")
+            return ProviderCompatibilityException(
+                message=extracted_message or "Provider 不支持此请求",
+                provider_name=provider_name,
+                status_code=400,
+                upstream_error=error_response_text,
+            )
+
         # 400 错误：检查是否为客户端请求错误（不应重试）
         if status == 400 and self._is_client_error(error_response_text):
             logger.info(f"检测到客户端请求错误，不进行重试: {extracted_message}")

src/services/provider/response_normalizer.py

@@ -1,61 +0,0 @@
-"""响应标准化服务，用于 STANDARD 模式下的响应格式验证和补全"""
-
-from typing import Any, Dict, Optional
-
-from src.core.logger import logger
-from src.models.claude import ClaudeResponse
-
-
-
-class ResponseNormalizer:
-    """响应标准化器 - 用于标准模式下验证和补全响应字段"""
-
-    @staticmethod
-    def normalize_claude_response(
-        response_data: Dict[str, Any], request_id: Optional[str] = None
-    ) -> Dict[str, Any]:
-        """
-        标准化 Claude API 响应
-
-        Args:
-            response_data: 原始响应数据
-            request_id: 请求ID（用于日志）
-
-        Returns:
-            标准化后的响应数据（失败时返回原始数据）
-        """
-        if "error" in response_data:
-            logger.debug(f"[ResponseNormalizer] 检测到错误响应，跳过标准化 | ID:{request_id}")
-            return response_data
-
-        try:
-            validated = ClaudeResponse.model_validate(response_data)
-            normalized = validated.model_dump(mode="json", exclude_none=False)
-
-            logger.debug(f"[ResponseNormalizer] 响应标准化成功 | ID:{request_id}")
-            return normalized
-
-        except Exception as e:
-            logger.debug(f"[ResponseNormalizer] 响应验证失败，透传原始数据 | ID:{request_id}")
-            return response_data
-
-    @staticmethod
-    def should_normalize(response_data: Dict[str, Any]) -> bool:
-        """
-        判断是否需要进行标准化
-
-        Args:
-            response_data: 响应数据
-
-        Returns:
-            是否需要标准化
-        """
-        # 错误响应不需要标准化
-        if "error" in response_data:
-            return False
-
-        # 已经包含新字段的响应不需要再次标准化
-        if "context_management" in response_data and "container" in response_data:
-            return False
-
-        return True

src/services/rate_limit/adaptive_concurrency.py

@@ -5,6 +5,10 @@
 - 使用滑动窗口采样，容忍并发波动
 - 基于窗口内高利用率采样比例决策，而非要求连续高利用率
 - 增加探测性扩容机制，长时间稳定时主动尝试扩容
+
+AIMD 参数说明：
+- 扩容：加性增加 (+INCREASE_STEP)
+- 缩容：乘性减少 (*DECREASE_MULTIPLIER，默认 0.85)
 """
 
 from datetime import datetime, timezone
@@ -34,7 +38,7 @@ class AdaptiveConcurrencyManager:
     核心算法：基于滑动窗口利用率的 AIMD
     - 滑动窗口记录最近 N 次请求的利用率
     - 当窗口内高利用率采样比例 >= 60% 时触发扩容
-    - 遇到 429 错误时乘性减少 (*0.7)
+    - 遇到 429 错误时乘性减少 (*0.85)
     - 长时间无 429 且有流量时触发探测性扩容
 
     扩容条件（满足任一即可）：

src/services/rate_limit/concurrency_manager.py

@@ -11,7 +11,6 @@
 
 import asyncio
 import math
-import os
 from contextlib import asynccontextmanager
 from datetime import timedelta  # noqa: F401 - kept for potential future use
 from typing import Optional, Tuple
@@ -40,6 +39,7 @@ class ConcurrencyManager:
         self._memory_lock: asyncio.Lock = asyncio.Lock()
         self._memory_endpoint_counts: dict[str, int] = {}
         self._memory_key_counts: dict[str, int] = {}
+        self._owns_redis: bool = False
         self._memory_initialized = True
 
     async def initialize(self) -> None:
@@ -47,41 +47,29 @@ class ConcurrencyManager:
         if self._redis is not None:
             return
 
-        # 优先使用 REDIS_URL，如果没有则根据密码构建 URL
-        redis_url = os.getenv("REDIS_URL")
-
-        if not redis_url:
-            # 本地开发模式：从 REDIS_PASSWORD 构建 URL
-            redis_password = os.getenv("REDIS_PASSWORD")
-            if redis_password:
-                redis_url = f"redis://:{redis_password}@localhost:6379/0"
-            else:
-                redis_url = "redis://localhost:6379/0"
-
         try:
-            self._redis = await aioredis.from_url(
-                redis_url,
-                encoding="utf-8",
-                decode_responses=True,
-                socket_timeout=5.0,
-                socket_connect_timeout=5.0,
-            )
-            # 测试连接
-            await self._redis.ping()
-            # 脱敏显示（隐藏密码）
-            safe_url = redis_url.split("@")[-1] if "@" in redis_url else redis_url
-            logger.info(f"[OK] Redis 连接成功: {safe_url}")
+            # 复用全局 Redis 客户端（带熔断/降级），避免重复创建连接池
+            from src.clients.redis_client import get_redis_client
+
+            self._redis = await get_redis_client(require_redis=False)
+            self._owns_redis = False
+            if self._redis:
+                logger.info("[OK] ConcurrencyManager 已复用全局 Redis 客户端")
+            else:
+                logger.warning("[WARN] Redis 不可用，并发控制降级为内存模式（仅在单实例环境下安全）")
         except Exception as e:
-            logger.error(f"[ERROR] Redis 连接失败: {e}")
-            logger.warning("[WARN] 并发控制将被禁用（仅在单实例环境下安全）")
+            logger.error(f"[ERROR] 获取全局 Redis 客户端失败: {e}")
+            logger.warning("[WARN] 并发控制将降级为内存模式（仅在单实例环境下安全）")
             self._redis = None
+            self._owns_redis = False
 
     async def close(self) -> None:
         """关闭 Redis 连接"""
-        if self._redis:
+        if self._redis and self._owns_redis:
             await self._redis.close()
-            self._redis = None
-            logger.info("Redis 连接已关闭")
+            logger.info("ConcurrencyManager Redis 连接已关闭")
+        self._redis = None
+        self._owns_redis = False
 
     def _get_endpoint_key(self, endpoint_id: str) -> str:
         """获取 Endpoint 并发计数的 Redis Key"""

src/services/rate_limit/rpm_limiter.py

@@ -3,7 +3,7 @@ RPM (Requests Per Minute) 限流服务
 """
 
 import time
-from datetime import datetime, timezone
+from datetime import datetime, timedelta, timezone
 from typing import Dict, Tuple
 
 from sqlalchemy.orm import Session
@@ -72,11 +72,7 @@ class RPMLimiter:
         # 获取当前分钟窗口
         now = datetime.now(timezone.utc)
         window_start = now.replace(second=0, microsecond=0)
-        window_end = (
-            window_start.replace(minute=window_start.minute + 1)
-            if window_start.minute < 59
-            else window_start.replace(hour=window_start.hour + 1, minute=0)
-        )
+        window_end = window_start + timedelta(minutes=1)
 
         # 查找或创建追踪记录
         tracking = (

src/services/system/audit.py

@@ -11,7 +11,6 @@ from sqlalchemy.orm import Session
 from src.core.logger import logger
 from src.database import get_db
 from src.models.database import AuditEventType, AuditLog
-from src.utils.transaction_manager import transactional
 
 
 
@@ -19,10 +18,13 @@ from src.utils.transaction_manager import transactional
 
 
 class AuditService:
-    """审计服务"""
+    """审计服务
+
+    事务策略：本服务不负责事务提交，由中间件统一管理。
+    所有方法只做 db.add/flush，提交由请求结束时的中间件处理。
+    """
 
     @staticmethod
-    @transactional(commit=False)  # 不自动提交，让调用方决定
     def log_event(
         db: Session,
         event_type: AuditEventType,
@@ -54,47 +56,44 @@ class AuditService:
 
         Returns:
             审计日志记录
+
+        Note:
+            不在此方法内提交事务，由调用方或中间件统一管理。
         """
-        try:
-            audit_log = AuditLog(
-                event_type=event_type.value,
-                description=description,
-                user_id=user_id,
-                api_key_id=api_key_id,
-                ip_address=ip_address,
-                user_agent=user_agent,
-                request_id=request_id,
-                status_code=status_code,
-                error_message=error_message,
-                event_metadata=metadata,
-            )
+        audit_log = AuditLog(
+            event_type=event_type.value,
+            description=description,
+            user_id=user_id,
+            api_key_id=api_key_id,
+            ip_address=ip_address,
+            user_agent=user_agent,
+            request_id=request_id,
+            status_code=status_code,
+            error_message=error_message,
+            event_metadata=metadata,
+        )
 
-            db.add(audit_log)
-            db.commit()  # 立即提交事务,释放数据库锁
-            db.refresh(audit_log)
+        db.add(audit_log)
+        # 使用 flush 使记录可见但不提交事务，事务由中间件统一管理
+        db.flush()
 
-            # 同时记录到系统日志
-            log_message = (
-                f"AUDIT [{event_type.value}] - {description} | "
-                f"user_id={user_id}, ip={ip_address}"
-            )
+        # 同时记录到系统日志
+        log_message = (
+            f"AUDIT [{event_type.value}] - {description} | "
+            f"user_id={user_id}, ip={ip_address}"
+        )
 
-            if event_type in [
-                AuditEventType.UNAUTHORIZED_ACCESS,
-                AuditEventType.SUSPICIOUS_ACTIVITY,
-            ]:
-                logger.warning(log_message)
-            elif event_type in [AuditEventType.LOGIN_FAILED, AuditEventType.REQUEST_FAILED]:
-                logger.info(log_message)
-            else:
-                logger.debug(log_message)
+        if event_type in [
+            AuditEventType.UNAUTHORIZED_ACCESS,
+            AuditEventType.SUSPICIOUS_ACTIVITY,
+        ]:
+            logger.warning(log_message)
+        elif event_type in [AuditEventType.LOGIN_FAILED, AuditEventType.REQUEST_FAILED]:
+            logger.info(log_message)
+        else:
+            logger.debug(log_message)
 
-            return audit_log
-
-        except Exception as e:
-            logger.error(f"Failed to log audit event: {e}")
-            db.rollback()
-            return None
+        return audit_log
 
     @staticmethod
     def log_login_attempt(

src/services/system/cleanup_scheduler.py

@@ -21,7 +21,7 @@ from sqlalchemy.orm import Session
 
 from src.core.logger import logger
 from src.database import create_session
-from src.models.database import Usage
+from src.models.database import AuditLog, Usage
 from src.services.system.config import SystemConfigService
 from src.services.system.scheduler import get_scheduler
 from src.services.system.stats_aggregator import StatsAggregatorService
@@ -91,6 +91,15 @@ class CleanupScheduler:
             name="Pending状态清理",
         )
 
+        # 审计日志清理 - 凌晨 4 点执行
+        scheduler.add_cron_job(
+            self._scheduled_audit_cleanup,
+            hour=4,
+            minute=0,
+            job_id="audit_cleanup",
+            name="审计日志清理",
+        )
+
         # 启动时执行一次初始化任务
         asyncio.create_task(self._run_startup_tasks())
 
@@ -145,6 +154,10 @@ class CleanupScheduler:
         """Pending 清理任务（定时调用）"""
         await self._perform_pending_cleanup()
 
+    async def _scheduled_audit_cleanup(self):
+        """审计日志清理任务（定时调用）"""
+        await self._perform_audit_cleanup()
+
     # ========== 实际任务实现 ==========
 
     async def _perform_stats_aggregation(self, backfill: bool = False):
@@ -330,6 +343,70 @@ class CleanupScheduler:
         finally:
             db.close()
 
+    async def _perform_audit_cleanup(self):
+        """执行审计日志清理任务"""
+        db = create_session()
+        try:
+            # 检查是否启用自动清理
+            if not SystemConfigService.get_config(db, "enable_auto_cleanup", True):
+                logger.info("自动清理已禁用，跳过审计日志清理")
+                return
+
+            # 获取审计日志保留天数（默认 30 天，最少 7 天）
+            audit_retention_days = max(
+                SystemConfigService.get_config(db, "audit_log_retention_days", 30),
+                7,  # 最少保留 7 天，防止误配置删除所有审计日志
+            )
+            batch_size = SystemConfigService.get_config(db, "cleanup_batch_size", 1000)
+
+            cutoff_time = datetime.now(timezone.utc) - timedelta(days=audit_retention_days)
+
+            logger.info(f"开始清理 {audit_retention_days} 天前的审计日志...")
+
+            total_deleted = 0
+            while True:
+                # 先查询要删除的记录 ID（分批）
+                records_to_delete = (
+                    db.query(AuditLog.id)
+                    .filter(AuditLog.created_at < cutoff_time)
+                    .limit(batch_size)
+                    .all()
+                )
+
+                if not records_to_delete:
+                    break
+
+                record_ids = [r.id for r in records_to_delete]
+
+                # 执行删除
+                result = db.execute(
+                    delete(AuditLog)
+                    .where(AuditLog.id.in_(record_ids))
+                    .execution_options(synchronize_session=False)
+                )
+
+                rows_deleted = result.rowcount
+                db.commit()
+
+                total_deleted += rows_deleted
+                logger.debug(f"已删除 {rows_deleted} 条审计日志，累计 {total_deleted} 条")
+
+                await asyncio.sleep(0.1)
+
+            if total_deleted > 0:
+                logger.info(f"审计日志清理完成，共删除 {total_deleted} 条记录")
+            else:
+                logger.info("无需清理的审计日志")
+
+        except Exception as e:
+            logger.exception(f"审计日志清理失败: {e}")
+            try:
+                db.rollback()
+            except Exception:
+                pass
+        finally:
+            db.close()
+
     async def _perform_cleanup(self):
         """执行清理任务"""
         db = create_session()

src/services/system/config.py

@@ -12,7 +12,6 @@ from src.core.logger import logger
 from src.models.database import Provider, SystemConfig
 
 
-
 class LogLevel(str, Enum):
     """日志记录级别"""
 
@@ -94,6 +93,35 @@ class SystemConfigService:
 
         return default
 
+    @classmethod
+    def get_configs(cls, db: Session, keys: List[str]) -> Dict[str, Any]:
+        """
+        批量获取系统配置值
+
+        Args:
+            db: 数据库会话
+            keys: 配置键列表
+
+        Returns:
+            配置键值字典
+        """
+        result = {}
+
+        # 一次查询获取所有配置
+        configs = db.query(SystemConfig).filter(SystemConfig.key.in_(keys)).all()
+        config_map = {c.key: c.value for c in configs}
+
+        # 填充结果，不存在的使用默认值
+        for key in keys:
+            if key in config_map:
+                result[key] = config_map[key]
+            elif key in cls.DEFAULT_CONFIGS:
+                result[key] = cls.DEFAULT_CONFIGS[key]["value"]
+            else:
+                result[key] = None
+
+        return result
+
     @staticmethod
     def set_config(db: Session, key: str, value: Any, description: str = None) -> SystemConfig:
         """设置系统配置值"""
@@ -111,6 +139,7 @@ class SystemConfigService:
 
         db.commit()
         db.refresh(config)
+
         return config
 
     @staticmethod
@@ -153,8 +182,8 @@ class SystemConfigService:
             for config in configs
         ]
 
-    @staticmethod
-    def delete_config(db: Session, key: str) -> bool:
+    @classmethod
+    def delete_config(cls, db: Session, key: str) -> bool:
         """删除系统配置"""
         config = db.query(SystemConfig).filter(SystemConfig.key == key).first()
         if config:

src/services/usage/stream.py

@@ -457,7 +457,7 @@ class StreamUsageTracker:
 
         logger.debug(f"ID:{self.request_id} | 开始跟踪流式响应 | 估算输入tokens:{self.input_tokens}")
 
-        # 更新状态为 streaming
+        # 更新状态为 streaming，同时更新 provider
         if self.request_id:
             try:
                 from src.services.usage.service import UsageService
@@ -465,6 +465,7 @@ class StreamUsageTracker:
                     db=self.db,
                     request_id=self.request_id,
                     status="streaming",
+                    provider=self.provider,
                 )
             except Exception as e:
                 logger.warning(f"更新使用记录状态为 streaming 失败: {e}")

src/services/user/apikey.py

@@ -210,7 +210,15 @@ class ApiKeyService:
 
     @staticmethod
     def check_rate_limit(db: Session, api_key: ApiKey, window_minutes: int = 1) -> tuple[bool, int]:
-        """检查速率限制"""
+        """检查速率限制
+
+        Returns:
+            (is_allowed, remaining): 是否允许请求，剩余可用次数
+            当 rate_limit 为 None 时表示不限制，返回 (True, -1)
+        """
+        # 如果 rate_limit 为 None，表示不限制
+        if api_key.rate_limit is None:
+            return True, -1  # -1 表示无限制
 
         # 计算时间窗口
         window_start = datetime.now(timezone.utc) - timedelta(minutes=window_minutes)

src/utils/auth_utils.py

@@ -3,6 +3,7 @@
 提供统一的用户认证和授权功能
 """
 
+import hashlib
 from typing import Optional
 
 from fastapi import Depends, Header, HTTPException, status
@@ -41,13 +42,20 @@ async def get_current_user(
     try:
         # 验证Token格式和签名
         try:
-            payload = await AuthService.verify_token(token)
+            payload = await AuthService.verify_token(token, token_type="access")
         except HTTPException as token_error:
             # 保持原始的HTTP状态码（如401 Unauthorized），不要转换为403
-            logger.error(f"Token验证失败: {token_error.status_code}: {token_error.detail}, Token前10位: {token[:10]}...")
+            token_fp = hashlib.sha256(token.encode()).hexdigest()[:12]
+            logger.error(
+                "Token验证失败: {}: {}, token_fp={}",
+                token_error.status_code,
+                token_error.detail,
+                token_fp,
+            )
             raise  # 重新抛出原始异常，保持状态码
         except Exception as token_error:
-            logger.error(f"Token验证失败: {token_error}, Token前10位: {token[:10]}...")
+            token_fp = hashlib.sha256(token.encode()).hexdigest()[:12]
+            logger.error("Token验证失败: {}, token_fp={}", token_error, token_fp)
             raise ForbiddenException("无效的Token")
 
         user_id = payload.get("user_id")
@@ -63,7 +71,8 @@ async def get_current_user(
             raise ForbiddenException("无效的认证凭据")
 
         # 仅在DEBUG模式下记录详细信息
-        logger.debug(f"尝试获取用户: user_id={user_id}, token前10位: {token[:10]}...")
+        token_fp = hashlib.sha256(token.encode()).hexdigest()[:12]
+        logger.debug("尝试获取用户: user_id={}, token_fp={}", user_id, token_fp)
 
         # 确保user_id是字符串格式（UUID）
         if not isinstance(user_id, str):
@@ -144,7 +153,7 @@ async def get_current_user_from_header(
     token = authorization.replace("Bearer ", "")
 
     try:
-        payload = await AuthService.verify_token(token)
+        payload = await AuthService.verify_token(token, token_type="access")
         user_id = payload.get("user_id")
 
         if not user_id:

src/utils/request_utils.py

@@ -7,29 +7,47 @@ from typing import Optional
 
 from fastapi import Request
 
+from src.config import config
+
 
 def get_client_ip(request: Request) -> str:
     """
     获取客户端真实IP地址
 
     按优先级检查：
-    1. X-Forwarded-For 头（支持代理链）
+    1. X-Forwarded-For 头（支持代理链，根据可信代理数量提取）
     2. X-Real-IP 头（Nginx 代理）
     3. 直接客户端IP
 
+    安全说明：
+    - 此函数根据 TRUSTED_PROXY_COUNT 配置来决定信任的代理层数
+    - 当 TRUSTED_PROXY_COUNT=0 时，不信任任何代理头，直接使用连接 IP
+    - 当服务直接暴露公网时，应设置 TRUSTED_PROXY_COUNT=0 以防止 IP 伪造
+
     Args:
         request: FastAPI Request 对象
 
     Returns:
         str: 客户端IP地址，如果无法获取则返回 "unknown"
     """
+    trusted_proxy_count = config.trusted_proxy_count
+
+    # 如果不信任任何代理，直接返回连接 IP
+    if trusted_proxy_count == 0:
+        if request.client and request.client.host:
+            return request.client.host
+        return "unknown"
+
     # 优先检查 X-Forwarded-For 头（可能包含代理链）
     forwarded_for = request.headers.get("X-Forwarded-For")
     if forwarded_for:
-        # X-Forwarded-For 格式: "client, proxy1, proxy2"，取第一个（真实客户端）
-        client_ip = forwarded_for.split(",")[0].strip()
-        if client_ip:
-            return client_ip
+        # X-Forwarded-For 格式: "client, proxy1, proxy2"
+        # 从右往左数 trusted_proxy_count 个，取其左边的第一个
+        ips = [ip.strip() for ip in forwarded_for.split(",") if ip.strip()]
+        if len(ips) > trusted_proxy_count:
+            return ips[-(trusted_proxy_count + 1)]
+        elif ips:
+            return ips[0]
 
     # 检查 X-Real-IP 头（通常由 Nginx 设置）
     real_ip = request.headers.get("X-Real-IP")
@@ -91,20 +109,32 @@ def get_request_metadata(request: Request) -> dict:
     }
 
 
-def extract_ip_from_headers(headers: dict) -> str:
+def extract_ip_from_headers(headers: dict, trusted_proxy_count: Optional[int] = None) -> str:
     """
     从HTTP头字典中提取IP地址（用于中间件等场景）
 
     Args:
         headers: HTTP头字典
+        trusted_proxy_count: 可信代理层数，None 时使用配置值
 
     Returns:
         str: 客户端IP地址
     """
+    if trusted_proxy_count is None:
+        trusted_proxy_count = config.trusted_proxy_count
+
+    # 如果不信任任何代理，返回 unknown（调用方需要用其他方式获取连接 IP）
+    if trusted_proxy_count == 0:
+        return "unknown"
+
     # 检查 X-Forwarded-For
     forwarded_for = headers.get("x-forwarded-for", "")
     if forwarded_for:
-        return forwarded_for.split(",")[0].strip()
+        ips = [ip.strip() for ip in forwarded_for.split(",") if ip.strip()]
+        if len(ips) > trusted_proxy_count:
+            return ips[-(trusted_proxy_count + 1)]
+        elif ips:
+            return ips[0]
 
     # 检查 X-Real-IP
     real_ip = headers.get("x-real-ip", "")

tests/api/test_pipeline.py

@@ -0,0 +1,421 @@
+"""
+API Pipeline 测试
+
+测试 ApiRequestPipeline 的核心功能：
+- 认证流程（API Key、JWT Token）
+- 配额计算
+- 审计日志记录
+"""
+
+import pytest
+from datetime import datetime, timezone
+from unittest.mock import AsyncMock, MagicMock, patch
+
+from fastapi import HTTPException
+
+from src.api.base.pipeline import ApiRequestPipeline
+
+
+class TestPipelineQuotaCalculation:
+    """测试 Pipeline 配额计算"""
+
+    @pytest.fixture
+    def pipeline(self) -> ApiRequestPipeline:
+        return ApiRequestPipeline()
+
+    def test_calculate_quota_remaining_with_quota(self, pipeline: ApiRequestPipeline) -> None:
+        """测试有配额限制时计算剩余配额"""
+        mock_user = MagicMock()
+        mock_user.quota_usd = 100.0
+        mock_user.used_usd = 30.0
+
+        remaining = pipeline._calculate_quota_remaining(mock_user)
+
+        assert remaining == 70.0
+
+    def test_calculate_quota_remaining_no_quota(self, pipeline: ApiRequestPipeline) -> None:
+        """测试无配额限制时返回 None"""
+        mock_user = MagicMock()
+        mock_user.quota_usd = None
+        mock_user.used_usd = 30.0
+
+        remaining = pipeline._calculate_quota_remaining(mock_user)
+
+        assert remaining is None
+
+    def test_calculate_quota_remaining_negative_quota(self, pipeline: ApiRequestPipeline) -> None:
+        """测试负配额时返回 None"""
+        mock_user = MagicMock()
+        mock_user.quota_usd = -1
+        mock_user.used_usd = 0.0
+
+        remaining = pipeline._calculate_quota_remaining(mock_user)
+
+        assert remaining is None
+
+    def test_calculate_quota_remaining_exceeded(self, pipeline: ApiRequestPipeline) -> None:
+        """测试配额已超时返回 0"""
+        mock_user = MagicMock()
+        mock_user.quota_usd = 100.0
+        mock_user.used_usd = 150.0
+
+        remaining = pipeline._calculate_quota_remaining(mock_user)
+
+        assert remaining == 0.0
+
+    def test_calculate_quota_remaining_none_user(self, pipeline: ApiRequestPipeline) -> None:
+        """测试用户为 None 时返回 None"""
+        remaining = pipeline._calculate_quota_remaining(None)
+
+        assert remaining is None
+
+
+class TestPipelineAuditLogging:
+    """测试 Pipeline 审计日志"""
+
+    @pytest.fixture
+    def pipeline(self) -> ApiRequestPipeline:
+        return ApiRequestPipeline()
+
+    def test_record_audit_event_success(self, pipeline: ApiRequestPipeline) -> None:
+        """测试记录成功的审计事件"""
+        mock_context = MagicMock()
+        mock_context.db = MagicMock()
+        mock_context.user = MagicMock()
+        mock_context.user.id = "user-123"
+        mock_context.api_key = MagicMock()
+        mock_context.api_key.id = "key-123"
+        mock_context.request_id = "req-123"
+        mock_context.client_ip = "127.0.0.1"
+        mock_context.user_agent = "test-agent"
+        mock_context.request = MagicMock()
+        mock_context.request.method = "POST"
+        mock_context.request.url.path = "/v1/messages"
+        mock_context.start_time = 1000.0
+
+        mock_adapter = MagicMock()
+        mock_adapter.name = "test-adapter"
+        mock_adapter.audit_log_enabled = True
+        mock_adapter.audit_success_event = None
+        mock_adapter.audit_failure_event = None
+
+        with patch.object(
+            pipeline.audit_service,
+            "log_event",
+        ) as mock_log:
+            with patch("time.time", return_value=1001.0):
+                pipeline._record_audit_event(
+                    mock_context, mock_adapter, success=True, status_code=200
+                )
+
+            mock_log.assert_called_once()
+            call_kwargs = mock_log.call_args[1]
+            assert call_kwargs["user_id"] == "user-123"
+            assert call_kwargs["status_code"] == 200
+
+    def test_record_audit_event_failure(self, pipeline: ApiRequestPipeline) -> None:
+        """测试记录失败的审计事件"""
+        mock_context = MagicMock()
+        mock_context.db = MagicMock()
+        mock_context.user = MagicMock()
+        mock_context.user.id = "user-123"
+        mock_context.api_key = MagicMock()
+        mock_context.api_key.id = "key-123"
+        mock_context.request_id = "req-123"
+        mock_context.client_ip = "127.0.0.1"
+        mock_context.user_agent = "test-agent"
+        mock_context.request = MagicMock()
+        mock_context.request.method = "POST"
+        mock_context.request.url.path = "/v1/messages"
+        mock_context.start_time = 1000.0
+
+        mock_adapter = MagicMock()
+        mock_adapter.name = "test-adapter"
+        mock_adapter.audit_log_enabled = True
+        mock_adapter.audit_success_event = None
+        mock_adapter.audit_failure_event = None
+
+        with patch.object(
+            pipeline.audit_service,
+            "log_event",
+        ) as mock_log:
+            with patch("time.time", return_value=1001.0):
+                pipeline._record_audit_event(
+                    mock_context, mock_adapter, success=False, status_code=500, error="Internal error"
+                )
+
+            mock_log.assert_called_once()
+            call_kwargs = mock_log.call_args[1]
+            assert call_kwargs["status_code"] == 500
+            assert call_kwargs["error_message"] == "Internal error"
+
+    def test_record_audit_event_no_db(self, pipeline: ApiRequestPipeline) -> None:
+        """测试没有数据库会话时跳过审计"""
+        mock_context = MagicMock()
+        mock_context.db = None
+
+        mock_adapter = MagicMock()
+        mock_adapter.audit_log_enabled = True
+
+        with patch.object(
+            pipeline.audit_service,
+            "log_event",
+        ) as mock_log:
+            # 不应该抛出异常
+            pipeline._record_audit_event(mock_context, mock_adapter, success=True)
+
+            # 不应该调用 log_event
+            mock_log.assert_not_called()
+
+    def test_record_audit_event_disabled(self, pipeline: ApiRequestPipeline) -> None:
+        """测试审计日志被禁用时跳过"""
+        mock_context = MagicMock()
+        mock_context.db = MagicMock()
+
+        mock_adapter = MagicMock()
+        mock_adapter.audit_log_enabled = False
+
+        with patch.object(
+            pipeline.audit_service,
+            "log_event",
+        ) as mock_log:
+            pipeline._record_audit_event(mock_context, mock_adapter, success=True)
+
+            mock_log.assert_not_called()
+
+    def test_record_audit_event_exception_handling(self, pipeline: ApiRequestPipeline) -> None:
+        """测试审计日志异常不影响主流程"""
+        mock_context = MagicMock()
+        mock_context.db = MagicMock()
+        mock_context.user = MagicMock()
+        mock_context.user.id = "user-123"
+        mock_context.api_key = MagicMock()
+        mock_context.api_key.id = "key-123"
+        mock_context.request_id = "req-123"
+        mock_context.client_ip = "127.0.0.1"
+        mock_context.user_agent = "test-agent"
+        mock_context.request = MagicMock()
+        mock_context.request.method = "POST"
+        mock_context.request.url.path = "/v1/messages"
+        mock_context.start_time = 1000.0
+
+        mock_adapter = MagicMock()
+        mock_adapter.name = "test-adapter"
+        mock_adapter.audit_log_enabled = True
+        mock_adapter.audit_success_event = None
+
+        with patch.object(
+            pipeline.audit_service,
+            "log_event",
+            side_effect=Exception("DB error"),
+        ):
+            with patch("time.time", return_value=1001.0):
+                # 不应该抛出异常
+                pipeline._record_audit_event(mock_context, mock_adapter, success=True)
+
+
+class TestPipelineAuthentication:
+    """测试 Pipeline 认证相关逻辑"""
+
+    @pytest.fixture
+    def pipeline(self) -> ApiRequestPipeline:
+        return ApiRequestPipeline()
+
+    def test_authenticate_client_missing_key(self, pipeline: ApiRequestPipeline) -> None:
+        """测试缺少 API Key 时抛出异常"""
+        mock_request = MagicMock()
+        mock_request.headers = {}
+        mock_request.url.path = "/v1/messages"
+        mock_request.state = MagicMock()
+
+        mock_db = MagicMock()
+
+        mock_adapter = MagicMock()
+        mock_adapter.extract_api_key = MagicMock(return_value=None)
+
+        with pytest.raises(HTTPException) as exc_info:
+            pipeline._authenticate_client(mock_request, mock_db, mock_adapter)
+
+        assert exc_info.value.status_code == 401
+        assert "API密钥" in exc_info.value.detail
+
+    def test_authenticate_client_invalid_key(self, pipeline: ApiRequestPipeline) -> None:
+        """测试无效的 API Key"""
+        mock_request = MagicMock()
+        mock_request.headers = {"Authorization": "Bearer sk-invalid"}
+        mock_request.url.path = "/v1/messages"
+        mock_request.state = MagicMock()
+
+        mock_db = MagicMock()
+
+        mock_adapter = MagicMock()
+        mock_adapter.extract_api_key = MagicMock(return_value="sk-invalid")
+
+        with patch.object(
+            pipeline.auth_service,
+            "authenticate_api_key",
+            return_value=None,
+        ):
+            with pytest.raises(HTTPException) as exc_info:
+                pipeline._authenticate_client(mock_request, mock_db, mock_adapter)
+
+        assert exc_info.value.status_code == 401
+
+    def test_authenticate_client_quota_exceeded(self, pipeline: ApiRequestPipeline) -> None:
+        """测试配额超限时抛出异常"""
+        mock_user = MagicMock()
+        mock_user.id = "user-123"
+        mock_user.quota_usd = 100.0
+        mock_user.used_usd = 100.0
+
+        mock_api_key = MagicMock()
+        mock_api_key.id = "key-123"
+        mock_api_key.is_standalone = False
+
+        mock_request = MagicMock()
+        mock_request.headers = {"Authorization": "Bearer sk-test"}
+        mock_request.url.path = "/v1/messages"
+        mock_request.state = MagicMock()
+
+        mock_db = MagicMock()
+
+        mock_adapter = MagicMock()
+        mock_adapter.extract_api_key = MagicMock(return_value="sk-test")
+
+        with patch.object(
+            pipeline.auth_service,
+            "authenticate_api_key",
+            return_value=(mock_user, mock_api_key),
+        ):
+            with patch.object(
+                pipeline.usage_service,
+                "check_user_quota",
+                return_value=(False, "配额不足"),
+            ):
+                from src.core.exceptions import QuotaExceededException
+
+                with pytest.raises(QuotaExceededException):
+                    pipeline._authenticate_client(mock_request, mock_db, mock_adapter)
+
+
+class TestPipelineAdminAuth:
+    """测试管理员认证"""
+
+    @pytest.fixture
+    def pipeline(self) -> ApiRequestPipeline:
+        return ApiRequestPipeline()
+
+    @pytest.mark.asyncio
+    async def test_authenticate_admin_missing_token(self, pipeline: ApiRequestPipeline) -> None:
+        """测试缺少管理员令牌"""
+        mock_request = MagicMock()
+        mock_request.headers = {}
+
+        mock_db = MagicMock()
+
+        with pytest.raises(HTTPException) as exc_info:
+            await pipeline._authenticate_admin(mock_request, mock_db)
+
+        assert exc_info.value.status_code == 401
+        assert "管理员凭证" in exc_info.value.detail
+
+    @pytest.mark.asyncio
+    async def test_authenticate_admin_invalid_token(self, pipeline: ApiRequestPipeline) -> None:
+        """测试无效的管理员令牌"""
+        mock_request = MagicMock()
+        mock_request.headers = {"authorization": "Bearer invalid-token"}
+
+        mock_db = MagicMock()
+
+        with patch.object(
+            pipeline.auth_service,
+            "verify_token",
+            side_effect=HTTPException(status_code=401, detail="Invalid token"),
+        ):
+            with pytest.raises(HTTPException) as exc_info:
+                await pipeline._authenticate_admin(mock_request, mock_db)
+
+            assert exc_info.value.status_code == 401
+
+    @pytest.mark.asyncio
+    async def test_authenticate_admin_success(self, pipeline: ApiRequestPipeline) -> None:
+        """测试管理员认证成功"""
+        mock_user = MagicMock()
+        mock_user.id = "admin-123"
+        mock_user.is_active = True
+
+        mock_request = MagicMock()
+        mock_request.headers = {"authorization": "Bearer valid-token"}
+        mock_request.state = MagicMock()
+
+        mock_db = MagicMock()
+        mock_db.query.return_value.filter.return_value.first.return_value = mock_user
+
+        with patch.object(
+            pipeline.auth_service,
+            "verify_token",
+            new_callable=AsyncMock,
+            return_value={"user_id": "admin-123"},
+        ):
+            result = await pipeline._authenticate_admin(mock_request, mock_db)
+
+        assert result == mock_user
+        assert mock_request.state.user_id == "admin-123"
+
+    @pytest.mark.asyncio
+    async def test_authenticate_admin_lowercase_bearer(self, pipeline: ApiRequestPipeline) -> None:
+        """测试 bearer (小写) 前缀也能正确解析"""
+        mock_user = MagicMock()
+        mock_user.id = "admin-123"
+        mock_user.is_active = True
+
+        mock_request = MagicMock()
+        mock_request.headers = {"authorization": "bearer valid-token"}
+        mock_request.state = MagicMock()
+
+        mock_db = MagicMock()
+        mock_db.query.return_value.filter.return_value.first.return_value = mock_user
+
+        with patch.object(
+            pipeline.auth_service,
+            "verify_token",
+            new_callable=AsyncMock,
+            return_value={"user_id": "admin-123"},
+        ) as mock_verify:
+            result = await pipeline._authenticate_admin(mock_request, mock_db)
+
+        mock_verify.assert_awaited_once_with("valid-token", token_type="access")
+        assert result == mock_user
+
+
+class TestPipelineUserAuth:
+    """测试普通用户 JWT 认证"""
+
+    @pytest.fixture
+    def pipeline(self) -> ApiRequestPipeline:
+        return ApiRequestPipeline()
+
+    @pytest.mark.asyncio
+    async def test_authenticate_user_lowercase_bearer(self, pipeline: ApiRequestPipeline) -> None:
+        """测试 bearer (小写) 前缀也能正确解析"""
+        mock_user = MagicMock()
+        mock_user.id = "user-123"
+        mock_user.is_active = True
+
+        mock_request = MagicMock()
+        mock_request.headers = {"authorization": "bearer valid-token"}
+        mock_request.state = MagicMock()
+
+        mock_db = MagicMock()
+        mock_db.query.return_value.filter.return_value.first.return_value = mock_user
+
+        with patch.object(
+            pipeline.auth_service,
+            "verify_token",
+            new_callable=AsyncMock,
+            return_value={"user_id": "user-123"},
+        ) as mock_verify:
+            result = await pipeline._authenticate_user(mock_request, mock_db)
+
+        mock_verify.assert_awaited_once_with("valid-token", token_type="access")
+        assert result == mock_user

tests/services/__init__.py

@@ -0,0 +1 @@
+"""服务层测试"""

tests/services/test_auth.py

@@ -0,0 +1,299 @@
+"""
+认证服务测试
+
+测试 AuthService 的核心功能：
+- JWT Token 创建和验证
+- 用户登录认证
+- API Key 认证
+"""
+
+import pytest
+from datetime import datetime, timedelta, timezone
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import jwt
+
+from src.services.auth.service import (
+    AuthService,
+    JWT_SECRET_KEY,
+    JWT_ALGORITHM,
+    JWT_EXPIRATION_HOURS,
+)
+
+
+class TestJWTTokenCreation:
+    """测试 JWT Token 创建"""
+
+    def test_create_access_token_contains_required_fields(self) -> None:
+        """测试访问令牌包含必要字段"""
+        data = {"sub": "user123", "email": "test@example.com"}
+        token = AuthService.create_access_token(data)
+
+        # 解码验证
+        payload = jwt.decode(token, JWT_SECRET_KEY, algorithms=[JWT_ALGORITHM])
+
+        assert payload["sub"] == "user123"
+        assert payload["email"] == "test@example.com"
+        assert payload["type"] == "access"
+        assert "exp" in payload
+
+    def test_create_access_token_expiration(self) -> None:
+        """测试访问令牌过期时间正确"""
+        data = {"sub": "user123"}
+        token = AuthService.create_access_token(data)
+
+        payload = jwt.decode(token, JWT_SECRET_KEY, algorithms=[JWT_ALGORITHM])
+
+        # 验证过期时间在预期范围内（允许1分钟误差）
+        exp_time = datetime.fromtimestamp(payload["exp"], tz=timezone.utc)
+        expected_exp = datetime.now(timezone.utc) + timedelta(hours=JWT_EXPIRATION_HOURS)
+
+        assert abs((exp_time - expected_exp).total_seconds()) < 60
+
+    def test_create_refresh_token_type(self) -> None:
+        """测试刷新令牌类型正确"""
+        data = {"sub": "user123"}
+        token = AuthService.create_refresh_token(data)
+
+        payload = jwt.decode(token, JWT_SECRET_KEY, algorithms=[JWT_ALGORITHM])
+
+        assert payload["type"] == "refresh"
+
+    def test_create_refresh_token_longer_expiration(self) -> None:
+        """测试刷新令牌过期时间更长"""
+        data = {"sub": "user123"}
+        access_token = AuthService.create_access_token(data)
+        refresh_token = AuthService.create_refresh_token(data)
+
+        access_payload = jwt.decode(access_token, JWT_SECRET_KEY, algorithms=[JWT_ALGORITHM])
+        refresh_payload = jwt.decode(refresh_token, JWT_SECRET_KEY, algorithms=[JWT_ALGORITHM])
+
+        # 刷新令牌应该比访问令牌过期时间更长
+        assert refresh_payload["exp"] > access_payload["exp"]
+
+
+class TestJWTTokenVerification:
+    """测试 JWT Token 验证"""
+
+    @pytest.mark.asyncio
+    async def test_verify_valid_access_token(self) -> None:
+        """测试验证有效的访问令牌"""
+        data = {"sub": "user123", "email": "test@example.com"}
+        token = AuthService.create_access_token(data)
+
+        with patch(
+            "src.services.auth.service.JWTBlacklistService.is_blacklisted",
+            new_callable=AsyncMock,
+            return_value=False,
+        ):
+            payload = await AuthService.verify_token(token, token_type="access")
+
+        assert payload["sub"] == "user123"
+        assert payload["type"] == "access"
+
+    @pytest.mark.asyncio
+    async def test_verify_expired_token_raises_error(self) -> None:
+        """测试验证过期令牌抛出异常"""
+        # 创建一个已过期的 token
+        data = {"sub": "user123", "type": "access"}
+        expire = datetime.now(timezone.utc) - timedelta(hours=1)
+        data["exp"] = expire
+        expired_token = jwt.encode(data, JWT_SECRET_KEY, algorithm=JWT_ALGORITHM)
+
+        from fastapi import HTTPException
+
+        with pytest.raises(HTTPException) as exc_info:
+            await AuthService.verify_token(expired_token)
+
+        assert exc_info.value.status_code == 401
+        assert "过期" in exc_info.value.detail
+
+    @pytest.mark.asyncio
+    async def test_verify_invalid_token_raises_error(self) -> None:
+        """测试验证无效令牌抛出异常"""
+        from fastapi import HTTPException
+
+        with pytest.raises(HTTPException) as exc_info:
+            await AuthService.verify_token("invalid.token.here")
+
+        assert exc_info.value.status_code == 401
+
+    @pytest.mark.asyncio
+    async def test_verify_wrong_token_type_raises_error(self) -> None:
+        """测试令牌类型不匹配抛出异常"""
+        data = {"sub": "user123"}
+        refresh_token = AuthService.create_refresh_token(data)
+
+        from fastapi import HTTPException
+
+        with patch(
+            "src.services.auth.service.JWTBlacklistService.is_blacklisted",
+            new_callable=AsyncMock,
+            return_value=False,
+        ):
+            with pytest.raises(HTTPException) as exc_info:
+                await AuthService.verify_token(refresh_token, token_type="access")
+
+        assert exc_info.value.status_code == 401
+        assert "类型错误" in exc_info.value.detail
+
+    @pytest.mark.asyncio
+    async def test_verify_blacklisted_token_raises_error(self) -> None:
+        """测试已撤销的令牌抛出异常"""
+        data = {"sub": "user123"}
+        token = AuthService.create_access_token(data)
+
+        from fastapi import HTTPException
+
+        with patch(
+            "src.services.auth.service.JWTBlacklistService.is_blacklisted",
+            new_callable=AsyncMock,
+            return_value=True,
+        ):
+            with pytest.raises(HTTPException) as exc_info:
+                await AuthService.verify_token(token)
+
+        assert exc_info.value.status_code == 401
+        assert "撤销" in exc_info.value.detail
+
+
+class TestUserAuthentication:
+    """测试用户登录认证"""
+
+    @pytest.mark.asyncio
+    async def test_authenticate_user_success(self) -> None:
+        """测试用户登录成功"""
+        # Mock 数据库和用户对象
+        mock_user = MagicMock()
+        mock_user.id = "user-123"
+        mock_user.email = "test@example.com"
+        mock_user.is_active = True
+        mock_user.verify_password.return_value = True
+
+        mock_db = MagicMock()
+        mock_db.query.return_value.filter.return_value.first.return_value = mock_user
+
+        with patch(
+            "src.services.auth.service.UserCacheService.invalidate_user_cache",
+            new_callable=AsyncMock,
+        ):
+            result = await AuthService.authenticate_user(mock_db, "test@example.com", "password123")
+
+        assert result == mock_user
+        mock_user.verify_password.assert_called_once_with("password123")
+        mock_db.commit.assert_called_once()
+
+    @pytest.mark.asyncio
+    async def test_authenticate_user_not_found(self) -> None:
+        """测试用户不存在"""
+        mock_db = MagicMock()
+        mock_db.query.return_value.filter.return_value.first.return_value = None
+
+        result = await AuthService.authenticate_user(mock_db, "nonexistent@example.com", "password")
+
+        assert result is None
+
+    @pytest.mark.asyncio
+    async def test_authenticate_user_wrong_password(self) -> None:
+        """测试密码错误"""
+        mock_user = MagicMock()
+        mock_user.email = "test@example.com"
+        mock_user.verify_password.return_value = False
+
+        mock_db = MagicMock()
+        mock_db.query.return_value.filter.return_value.first.return_value = mock_user
+
+        result = await AuthService.authenticate_user(mock_db, "test@example.com", "wrongpassword")
+
+        assert result is None
+
+    @pytest.mark.asyncio
+    async def test_authenticate_user_inactive(self) -> None:
+        """测试用户已禁用"""
+        mock_user = MagicMock()
+        mock_user.email = "test@example.com"
+        mock_user.is_active = False
+        mock_user.verify_password.return_value = True
+
+        mock_db = MagicMock()
+        mock_db.query.return_value.filter.return_value.first.return_value = mock_user
+
+        result = await AuthService.authenticate_user(mock_db, "test@example.com", "password123")
+
+        assert result is None
+
+
+class TestAPIKeyAuthentication:
+    """测试 API Key 认证"""
+
+    def test_authenticate_api_key_success(self) -> None:
+        """测试 API Key 认证成功"""
+        mock_user = MagicMock()
+        mock_user.id = "user-123"
+        mock_user.email = "test@example.com"
+        mock_user.is_active = True
+
+        mock_api_key = MagicMock()
+        mock_api_key.is_active = True
+        mock_api_key.expires_at = None
+        mock_api_key.user = mock_user
+        mock_api_key.balance_used_usd = 0.0
+
+        mock_db = MagicMock()
+        mock_db.query.return_value.options.return_value.filter.return_value.first.return_value = (
+            mock_api_key
+        )
+
+        with patch("src.services.auth.service.ApiKey.hash_key", return_value="hashed_key"):
+            with patch(
+                "src.services.auth.service.ApiKeyService.check_balance",
+                return_value=(True, 100.0),
+            ):
+                result = AuthService.authenticate_api_key(mock_db, "sk-test-key")
+
+        assert result is not None
+        assert result[0] == mock_user
+        assert result[1] == mock_api_key
+
+    def test_authenticate_api_key_not_found(self) -> None:
+        """测试 API Key 不存在"""
+        mock_db = MagicMock()
+        mock_db.query.return_value.options.return_value.filter.return_value.first.return_value = (
+            None
+        )
+
+        with patch("src.services.auth.service.ApiKey.hash_key", return_value="hashed_key"):
+            result = AuthService.authenticate_api_key(mock_db, "sk-invalid-key")
+
+        assert result is None
+
+    def test_authenticate_api_key_inactive(self) -> None:
+        """测试 API Key 已禁用"""
+        mock_api_key = MagicMock()
+        mock_api_key.is_active = False
+
+        mock_db = MagicMock()
+        mock_db.query.return_value.options.return_value.filter.return_value.first.return_value = (
+            mock_api_key
+        )
+
+        with patch("src.services.auth.service.ApiKey.hash_key", return_value="hashed_key"):
+            result = AuthService.authenticate_api_key(mock_db, "sk-inactive-key")
+
+        assert result is None
+
+    def test_authenticate_api_key_expired(self) -> None:
+        """测试 API Key 已过期"""
+        mock_api_key = MagicMock()
+        mock_api_key.is_active = True
+        mock_api_key.expires_at = datetime.now(timezone.utc) - timedelta(days=1)
+
+        mock_db = MagicMock()
+        mock_db.query.return_value.options.return_value.filter.return_value.first.return_value = (
+            mock_api_key
+        )
+
+        with patch("src.services.auth.service.ApiKey.hash_key", return_value="hashed_key"):
+            result = AuthService.authenticate_api_key(mock_db, "sk-expired-key")
+
+        assert result is None

tests/services/test_usage_service.py

@@ -0,0 +1,292 @@
+"""
+UsageService 测试
+
+测试用量统计服务的核心功能：
+- 成本计算
+- 配额检查
+- 用量统计查询
+"""
+
+import pytest
+from unittest.mock import MagicMock, patch, AsyncMock
+
+from src.services.usage.service import UsageService
+
+
+class TestCostCalculation:
+    """测试成本计算"""
+
+    def test_calculate_cost_basic(self) -> None:
+        """测试基础成本计算"""
+        # 价格：输入 $3/1M, 输出 $15/1M
+        result = UsageService.calculate_cost(
+            input_tokens=1000,
+            output_tokens=500,
+            input_price_per_1m=3.0,
+            output_price_per_1m=15.0,
+        )
+
+        input_cost, output_cost, cache_creation_cost, cache_read_cost, cache_cost, request_cost, total_cost = result
+
+        # 1000 tokens * $3 / 1M = $0.003
+        assert abs(input_cost - 0.003) < 0.0001
+        # 500 tokens * $15 / 1M = $0.0075
+        assert abs(output_cost - 0.0075) < 0.0001
+        # Total = $0.003 + $0.0075 = $0.0105
+        assert abs(total_cost - 0.0105) < 0.0001
+
+    def test_calculate_cost_with_cache(self) -> None:
+        """测试带缓存的成本计算"""
+        result = UsageService.calculate_cost(
+            input_tokens=1000,
+            output_tokens=500,
+            input_price_per_1m=3.0,
+            output_price_per_1m=15.0,
+            cache_creation_input_tokens=200,
+            cache_read_input_tokens=300,
+            cache_creation_price_per_1m=3.75,  # 1.25x input price
+            cache_read_price_per_1m=0.3,  # 0.1x input price
+        )
+
+        (
+            input_cost,
+            output_cost,
+            cache_creation_cost,
+            cache_read_cost,
+            cache_cost,
+            request_cost,
+            total_cost,
+        ) = result
+
+        # 验证缓存成本被计算
+        assert cache_creation_cost > 0
+        assert cache_read_cost > 0
+        assert cache_cost == cache_creation_cost + cache_read_cost
+
+    def test_calculate_cost_with_request_price(self) -> None:
+        """测试按次计费"""
+        result = UsageService.calculate_cost(
+            input_tokens=1000,
+            output_tokens=500,
+            input_price_per_1m=3.0,
+            output_price_per_1m=15.0,
+            price_per_request=0.01,
+        )
+
+        (
+            input_cost,
+            output_cost,
+            cache_creation_cost,
+            cache_read_cost,
+            cache_cost,
+            request_cost,
+            total_cost,
+        ) = result
+
+        assert request_cost == 0.01
+        # Total 包含 request_cost
+        assert total_cost == input_cost + output_cost + request_cost
+
+    def test_calculate_cost_zero_tokens(self) -> None:
+        """测试零 token 的成本计算"""
+        result = UsageService.calculate_cost(
+            input_tokens=0,
+            output_tokens=0,
+            input_price_per_1m=3.0,
+            output_price_per_1m=15.0,
+        )
+
+        (
+            input_cost,
+            output_cost,
+            cache_creation_cost,
+            cache_read_cost,
+            cache_cost,
+            request_cost,
+            total_cost,
+        ) = result
+
+        assert input_cost == 0
+        assert output_cost == 0
+        assert total_cost == 0
+
+
+class TestQuotaCheck:
+    """测试配额检查"""
+
+    def test_check_user_quota_sufficient(self) -> None:
+        """测试配额充足"""
+        mock_user = MagicMock()
+        mock_user.quota_usd = 100.0
+        mock_user.used_usd = 30.0
+        mock_user.role = MagicMock()
+        mock_user.role.value = "user"
+
+        mock_api_key = MagicMock()
+        mock_api_key.is_standalone = False
+
+        mock_db = MagicMock()
+
+        is_ok, message = UsageService.check_user_quota(mock_db, mock_user, api_key=mock_api_key)
+
+        assert is_ok is True
+
+    def test_check_user_quota_exceeded(self) -> None:
+        """测试配额超限（当有预估成本时）"""
+        mock_user = MagicMock()
+        mock_user.quota_usd = 100.0
+        mock_user.used_usd = 99.0  # 接近配额上限
+        mock_user.role = MagicMock()
+        mock_user.role.value = "user"
+
+        mock_api_key = MagicMock()
+        mock_api_key.is_standalone = False
+
+        mock_db = MagicMock()
+
+        # 当预估成本超过剩余配额时应该返回 False
+        is_ok, message = UsageService.check_user_quota(
+            mock_db, mock_user, estimated_cost=5.0, api_key=mock_api_key
+        )
+
+        assert is_ok is False
+        assert "配额" in message
+
+    def test_check_user_quota_no_limit(self) -> None:
+        """测试无配额限制（None）"""
+        mock_user = MagicMock()
+        mock_user.quota_usd = None
+        mock_user.used_usd = 1000.0
+        mock_user.role = MagicMock()
+        mock_user.role.value = "user"
+
+        mock_api_key = MagicMock()
+        mock_api_key.is_standalone = False
+
+        mock_db = MagicMock()
+
+        is_ok, message = UsageService.check_user_quota(mock_db, mock_user, api_key=mock_api_key)
+
+        assert is_ok is True
+
+    def test_check_user_quota_admin_bypass(self) -> None:
+        """测试管理员绕过配额检查"""
+        from src.models.database import UserRole
+
+        mock_user = MagicMock()
+        mock_user.quota_usd = 0.0
+        mock_user.used_usd = 1000.0
+        mock_user.role = UserRole.ADMIN
+
+        mock_api_key = MagicMock()
+        mock_api_key.is_standalone = False
+
+        mock_db = MagicMock()
+
+        is_ok, message = UsageService.check_user_quota(mock_db, mock_user, api_key=mock_api_key)
+
+        assert is_ok is True
+
+    def test_check_standalone_api_key_balance(self) -> None:
+        """测试独立 API Key 余额检查"""
+        mock_user = MagicMock()
+        mock_user.quota_usd = 0.0
+        mock_user.used_usd = 0.0
+        mock_user.role = MagicMock()
+        mock_user.role.value = "user"
+
+        mock_api_key = MagicMock()
+        mock_api_key.is_standalone = True
+        mock_api_key.current_balance_usd = 50.0
+        mock_api_key.balance_used_usd = 10.0
+
+        mock_db = MagicMock()
+
+        is_ok, message = UsageService.check_user_quota(mock_db, mock_user, api_key=mock_api_key)
+
+        assert is_ok is True
+
+    def test_check_standalone_api_key_insufficient_balance(self) -> None:
+        """测试独立 API Key 余额不足"""
+        mock_user = MagicMock()
+        mock_user.quota_usd = 100.0
+        mock_user.used_usd = 0.0
+        mock_user.role = MagicMock()
+        mock_user.role.value = "user"
+
+        mock_api_key = MagicMock()
+        mock_api_key.is_standalone = True
+        mock_api_key.current_balance_usd = 10.0
+        mock_api_key.balance_used_usd = 9.0  # 剩余 $1
+
+        mock_db = MagicMock()
+
+        # 需要 mock ApiKeyService.get_remaining_balance
+        with patch(
+            "src.services.user.apikey.ApiKeyService.get_remaining_balance",
+            return_value=1.0,
+        ):
+            # 预估成本 $5 超过剩余余额 $1
+            is_ok, message = UsageService.check_user_quota(
+                mock_db, mock_user, estimated_cost=5.0, api_key=mock_api_key
+            )
+
+        assert is_ok is False
+
+
+class TestUsageStatistics:
+    """测试用量统计查询
+
+    注意：get_usage_summary 方法内部使用了数据库方言特定的日期函数，
+    需要真实数据库或更复杂的 mock。这里只测试方法存在性。
+    """
+
+    def test_get_usage_summary_exists(self) -> None:
+        """测试 get_usage_summary 方法存在"""
+        assert hasattr(UsageService, "get_usage_summary")
+        assert callable(getattr(UsageService, "get_usage_summary"))
+
+
+class TestHelperMethods:
+    """测试辅助方法"""
+
+    @pytest.mark.asyncio
+    async def test_get_rate_multiplier_and_free_tier_default(self) -> None:
+        """测试默认费率倍数"""
+        mock_db = MagicMock()
+        # 模拟未找到 provider_api_key
+        mock_db.query.return_value.filter.return_value.first.return_value = None
+
+        rate_multiplier, is_free_tier = await UsageService._get_rate_multiplier_and_free_tier(
+            mock_db, provider_api_key_id=None, provider_id=None
+        )
+
+        assert rate_multiplier == 1.0
+        assert is_free_tier is False
+
+    @pytest.mark.asyncio
+    async def test_get_rate_multiplier_from_provider_api_key(self) -> None:
+        """测试从 ProviderAPIKey 获取费率倍数"""
+        mock_provider_api_key = MagicMock()
+        mock_provider_api_key.rate_multiplier = 0.8
+
+        mock_endpoint = MagicMock()
+        mock_endpoint.provider_id = "provider-123"
+
+        mock_provider = MagicMock()
+        mock_provider.billing_type = "standard"
+
+        mock_db = MagicMock()
+        # 第一次查询返回 provider_api_key
+        mock_db.query.return_value.filter.return_value.first.side_effect = [
+            mock_provider_api_key,
+            mock_endpoint,
+            mock_provider,
+        ]
+
+        rate_multiplier, is_free_tier = await UsageService._get_rate_multiplier_and_free_tier(
+            mock_db, provider_api_key_id="pak-123", provider_id=None
+        )
+
+        assert rate_multiplier == 0.8
+        assert is_free_tier is False