""" 缓存监控端点 提供缓存亲和性统计、管理和监控功能 """ from __future__ import annotations from dataclasses import dataclass from typing import Any from fastapi import APIRouter, Depends, HTTPException, Query, Request from fastapi.responses import PlainTextResponse from sqlalchemy.orm import Session from src.api.base.admin_adapter import AdminApiAdapter from src.api.base.context import ApiRequestContext from src.api.base.pagination import build_pagination_payload, paginate_sequence from src.api.base.pipeline import get_pipeline from src.clients.redis_client import get_redis_client_sync from src.core.crypto import crypto_service from src.core.logger import logger from src.core.redis_utils import scan_delete_pattern from src.database import get_db from src.models.database import ApiKey, User from src.services.scheduling.affinity_manager import get_affinity_manager from src.services.scheduling.aware_scheduler import CacheAwareScheduler, get_cache_aware_scheduler from src.services.system.config import SystemConfigService router = APIRouter(prefix="/api/admin/monitoring/cache", tags=["Admin - Monitoring: Cache"]) pipeline = get_pipeline() REDIS_SCAN_BATCH_SIZE = 200 REDIS_DELETE_BATCH_SIZE = 500 def mask_api_key(api_key: str | None, prefix_len: int = 8, suffix_len: int = 4) -> str | None: """ 脱敏 API Key，显示前缀 + 星号 + 后缀 例如: sk-jhiId-xxxxxxxxxxxAABB -> sk-jhiId-********AABB Args: api_key: 原始 API Key prefix_len: 显示的前缀长度，默认 8 suffix_len: 显示的后缀长度，默认 4 """ if not api_key: return None total_visible = prefix_len + suffix_len if len(api_key) <= total_visible: # Key 太短，直接返回部分内容 + 星号 return api_key[:prefix_len] + "********" return f"{api_key[:prefix_len]}********{api_key[-suffix_len:]}" def decrypt_and_mask(encrypted_key: str | None, prefix_len: int = 8) -> str | None: """ 解密 API Key 后脱敏显示 Args: encrypted_key: 加密后的 API Key prefix_len: 显示的前缀长度 """ if not encrypted_key: return None try: decrypted = crypto_service.decrypt(encrypted_key) return mask_api_key(decrypted, prefix_len) except Exception: # 解密失败时返回 None return None def resolve_user_identifier(db: Session, identifier: str) -> str | None: """ 将用户标识符（username/email/user_id/api_key_id）解析为 user_id 支持的输入格式： 1. User UUID (36位，带横杠) 2. Username (用户名) 3. Email (邮箱) 4. API Key ID (36位UUID) 返回： - user_id (UUID字符串) 或 None """ identifier = identifier.strip() # 1. 先尝试作为 User UUID 查询 user = db.query(User).filter(User.id == identifier).first() if user: logger.debug(f"通过User ID解析: {identifier[:8]}... -> {user.username}") return user.id # 2. 尝试作为 Username 查询 user = db.query(User).filter(User.username == identifier).first() if user: logger.debug(f"通过Username解析: {identifier} -> {user.id[:8]}...") # type: ignore[index] return user.id # 3. 尝试作为 Email 查询 user = db.query(User).filter(User.email == identifier).first() if user: logger.debug(f"通过Email解析: {identifier} -> {user.id[:8]}...") # type: ignore[index] return user.id # 4. 尝试作为 API Key ID 查询 api_key = db.query(ApiKey).filter(ApiKey.id == identifier).first() if api_key: logger.debug(f"通过API Key ID解析: {identifier[:8]}... -> User ID: {api_key.user_id[:8]}...") # type: ignore[index] return api_key.user_id # 无法识别 logger.debug(f"无法识别的用户标识符: {identifier}") return None @router.get("/stats") async def get_cache_stats( request: Request, db: Session = Depends(get_db), ) -> Any: """ 获取缓存亲和性统计信息 获取缓存调度器的运行统计数据，包括命中率、切换次数、调度器配置等。 用于监控缓存亲和性功能的运行状态和性能指标。 **返回字段**: - `status`: 状态（ok） - `data`: 统计数据对象 - `scheduler`: 调度器名称（cache_aware 或 random） - `total_affinities`: 总缓存亲和性数量 - `cache_hit_rate`: 缓存命中率（0.0-1.0） - `provider_switches`: Provider 切换次数 - `key_switches`: Key 切换次数 - `cache_hits`: 缓存命中次数 - `cache_misses`: 缓存未命中次数 - `scheduler_metrics`: 调度器详细指标 - `affinity_stats`: 亲和性统计数据 """ adapter = AdminCacheStatsAdapter() return await pipeline.run(adapter=adapter, http_request=request, db=db, mode=adapter.mode) @router.get("/affinity/{user_identifier}") async def get_user_affinity( user_identifier: str, request: Request, db: Session = Depends(get_db), ) -> Any: """ 查询指定用户的所有缓存亲和性 根据用户标识符查询该用户在各个端点上的缓存亲和性记录。 支持多种标识符格式的自动识别和解析。 **路径参数**: - `user_identifier`: 用户标识符，支持以下格式： - 用户名（username），如：yuanhonghu - 邮箱（email），如：user@example.com - 用户 UUID（user_id），如：550e8400-e29b-41d4-a716-446655440000 - API Key ID，如：660e8400-e29b-41d4-a716-446655440000 **返回字段**: - `status`: 状态（ok 或 not_found） - `message`: 提示消息（当无缓存时） - `user_info`: 用户信息 - `user_id`: 用户 ID - `username`: 用户名 - `email`: 邮箱 - `affinities`: 缓存亲和性列表 - `provider_id`: Provider ID - `endpoint_id`: Endpoint ID - `key_id`: Key ID - `api_format`: API 格式 - `model_name`: 模型名称（global_model_id） - `created_at`: 创建时间 - `expire_at`: 过期时间 - `request_count`: 请求计数 - `total_endpoints`: 缓存的端点数量 """ adapter = AdminGetUserAffinityAdapter(user_identifier=user_identifier) return await pipeline.run(adapter=adapter, http_request=request, db=db, mode=adapter.mode) @router.get("/affinities") async def list_affinities( request: Request, keyword: str | None = None, limit: int = Query(100, ge=1, le=1000, description="返回数量限制"), offset: int = Query(0, ge=0, description="偏移量"), db: Session = Depends(get_db), ) -> Any: """ 获取所有缓存亲和性列表 查询系统中所有的缓存亲和性记录，支持按关键词过滤和分页。 返回详细的用户、Provider、Endpoint、Key 信息。 **查询参数**: - `keyword`: 可选，支持以下过滤方式（可选） - 用户名/邮箱/User ID/API Key ID（精确匹配） - 任意字段的模糊匹配（affinity_key、user_id、username、email、provider_id、key_id） - `limit`: 返回数量限制（1-1000，默认 100） - `offset`: 偏移量（用于分页，默认 0） **返回字段**: - `status`: 状态（ok） - `data`: 分页数据对象 - `items`: 缓存亲和性列表 - `affinity_key`: API Key ID（用于缓存键） - `user_api_key_name`: 用户 API Key 名称 - `user_api_key_prefix`: 脱敏后的用户 API Key - `is_standalone`: 是否为独立 API Key - `user_id`: 用户 ID - `username`: 用户名 - `email`: 邮箱 - `provider_id`: Provider ID - `provider_name`: Provider 显示名称 - `endpoint_id`: Endpoint ID - `endpoint_url`: Endpoint 基础 URL - `key_id`: Key ID - `key_name`: Key 名称 - `key_prefix`: 脱敏后的 Provider Key - `rate_multipliers`: 按 API 格式的成本倍率 - `global_model_id`: GlobalModel ID - `model_name`: 模型名称 - `model_display_name`: 模型显示名称 - `api_format`: API 格式 - `created_at`: 创建时间 - `expire_at`: 过期时间 - `request_count`: 请求计数 - `meta`: 分页元数据 - `count`: 总数量 - `limit`: 每页数量 - `offset`: 当前偏移量 - `matched_user_id`: 匹配到的用户 ID（当关键词为用户标识时） """ adapter = AdminListAffinitiesAdapter(keyword=keyword, limit=limit, offset=offset) return await pipeline.run(adapter=adapter, http_request=request, db=db, mode=adapter.mode) @router.delete("/users/{user_identifier}") async def clear_user_cache( user_identifier: str, request: Request, db: Session = Depends(get_db), ) -> Any: """ 清除指定用户的缓存亲和性 清除指定用户或 API Key 的所有缓存亲和性记录。 支持按用户维度或单个 API Key 维度清除。 **路径参数**: - `user_identifier`: 用户标识符，支持以下格式： - 用户名（username） - 邮箱（email） - 用户 UUID（user_id） - API Key ID（清除该 API Key 的缓存） **返回字段**: - `status`: 状态（ok） - `message`: 操作结果消息 - `user_info`: 用户信息 - `user_id`: 用户 ID - `username`: 用户名 - `email`: 邮箱 - `api_key_id`: API Key ID（当清除单个 API Key 时） - `api_key_name`: API Key 名称（当清除单个 API Key 时） """ adapter = AdminClearUserCacheAdapter(user_identifier=user_identifier) 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: """ 清除单条缓存亲和性记录 根据精确的缓存键（affinity_key + endpoint_id + model_id + api_format） 清除单条缓存亲和性记录。用于精确控制缓存清除。 **路径参数**: - `affinity_key`: API Key ID（用于缓存的键） - `endpoint_id`: Endpoint ID - `model_id`: GlobalModel ID - `api_format`: API 格式（如：claude、openai、gemini） **返回字段**: - `status`: 状态（ok） - `message`: 操作结果消息 - `affinity_key`: API Key ID - `endpoint_id`: Endpoint ID - `model_id`: GlobalModel ID """ 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, db: Session = Depends(get_db), ) -> Any: """ 清除所有缓存亲和性 清除系统中所有用户的缓存亲和性记录。此操作会影响所有用户， 下次请求时将重新建立缓存亲和性。请谨慎使用。 **警告**: 此操作影响所有用户，使用前请确认 **返回字段**: - `status`: 状态（ok） - `message`: 操作结果消息 - `count`: 清除的缓存数量 """ adapter = AdminClearAllCacheAdapter() return await pipeline.run(adapter=adapter, http_request=request, db=db, mode=adapter.mode) @router.delete("/providers/{provider_id}") async def clear_provider_cache( provider_id: str, request: Request, db: Session = Depends(get_db), ) -> Any: """ 清除指定 Provider 的缓存亲和性 清除与指定 Provider 相关的所有缓存亲和性记录。 当 Provider 配置变更或下线时使用。 **路径参数**: - `provider_id`: Provider ID **返回字段**: - `status`: 状态（ok） - `message`: 操作结果消息 - `provider_id`: Provider ID - `count`: 清除的缓存数量 """ adapter = AdminClearProviderCacheAdapter(provider_id=provider_id) return await pipeline.run(adapter=adapter, http_request=request, db=db, mode=adapter.mode) @router.get("/config") async def get_cache_config( request: Request, db: Session = Depends(get_db), ) -> Any: """ 获取缓存相关配置 获取缓存亲和性功能的配置参数，包括缓存 TTL、预留比例、 动态预留机制配置等。 **返回字段**: - `status`: 状态（ok） - `data`: 配置数据 - `cache_ttl_seconds`: 缓存亲和性有效期（秒） - `cache_reservation_ratio`: 静态预留比例（已被动态预留替代） - `dynamic_reservation`: 动态预留机制配置 - `enabled`: 是否启用 - `config`: 配置参数 - `probe_phase_requests`: 探测阶段请求数阈值 - `probe_reservation`: 探测阶段预留比例 - `stable_min_reservation`: 稳定阶段最小预留比例 - `stable_max_reservation`: 稳定阶段最大预留比例 - `low_load_threshold`: 低负载阈值 - `high_load_threshold`: 高负载阈值 - `description`: 各参数说明 - `description`: 配置说明 """ adapter = AdminCacheConfigAdapter() return await pipeline.run(adapter=adapter, http_request=request, db=db, mode=adapter.mode) @router.get("/metrics", response_class=PlainTextResponse) async def get_cache_metrics( request: Request, db: Session = Depends(get_db), ) -> Any: """ 获取缓存调度指标（Prometheus 格式） 以 Prometheus 文本格式输出缓存调度器的监控指标， 方便接入 Prometheus/Grafana 等监控系统。 **返回格式**: Prometheus 文本格式（Content-Type: text/plain） **指标列表**: - `cache_scheduler_total_batches`: 总批次数 - `cache_scheduler_last_batch_size`: 最后一批候选数 - `cache_scheduler_total_candidates`: 总候选数 - `cache_scheduler_last_candidate_count`: 最后一批候选计数 - `cache_scheduler_cache_hits`: 缓存命中次数 - `cache_scheduler_cache_misses`: 缓存未命中次数 - `cache_scheduler_cache_hit_rate`: 缓存命中率 - `cache_scheduler_concurrency_denied`: 并发拒绝次数 - `cache_scheduler_avg_candidates_per_batch`: 平均每批候选数 - `cache_affinity_total`: 总缓存亲和性数量 - `cache_affinity_hits`: 亲和性命中次数 - `cache_affinity_misses`: 亲和性未命中次数 - `cache_affinity_hit_rate`: 亲和性命中率 - `cache_affinity_invalidations`: 亲和性失效次数 - `cache_affinity_provider_switches`: Provider 切换次数 - `cache_affinity_key_switches`: Key 切换次数 - `cache_scheduler_info`: 调度器信息（label: scheduler） """ adapter = AdminCacheMetricsAdapter() return await pipeline.run(adapter=adapter, http_request=request, db=db, mode=adapter.mode) # -------- 缓存监控适配器 -------- class AdminCacheStatsAdapter(AdminApiAdapter): async def handle(self, context: ApiRequestContext) -> dict[str, Any]: # type: ignore[override] try: redis_client = get_redis_client_sync() # 读取系统配置，确保监控接口与编排器使用一致的模式 priority_mode = SystemConfigService.get_config( context.db, "provider_priority_mode", CacheAwareScheduler.PRIORITY_MODE_PROVIDER, ) scheduling_mode = SystemConfigService.get_config( context.db, "scheduling_mode", CacheAwareScheduler.SCHEDULING_MODE_CACHE_AFFINITY, ) scheduler = await get_cache_aware_scheduler( redis_client, priority_mode=priority_mode, scheduling_mode=scheduling_mode, ) stats = await scheduler.get_stats() logger.info("缓存统计信息查询成功") context.add_audit_metadata( action="cache_stats", scheduler=stats.get("scheduler"), total_affinities=stats.get("total_affinities"), cache_hit_rate=stats.get("cache_hit_rate"), provider_switches=stats.get("provider_switches"), ) return {"status": "ok", "data": stats} except Exception as exc: logger.exception(f"获取缓存统计信息失败: {exc}") raise HTTPException(status_code=500, detail=f"获取缓存统计失败: {exc}") class AdminCacheMetricsAdapter(AdminApiAdapter): async def handle(self, context: ApiRequestContext) -> PlainTextResponse: try: redis_client = get_redis_client_sync() # 读取系统配置，确保监控接口与编排器使用一致的模式 priority_mode = SystemConfigService.get_config( context.db, "provider_priority_mode", CacheAwareScheduler.PRIORITY_MODE_PROVIDER, ) scheduling_mode = SystemConfigService.get_config( context.db, "scheduling_mode", CacheAwareScheduler.SCHEDULING_MODE_CACHE_AFFINITY, ) scheduler = await get_cache_aware_scheduler( redis_client, priority_mode=priority_mode, scheduling_mode=scheduling_mode, ) stats = await scheduler.get_stats() payload = self._format_prometheus(stats) context.add_audit_metadata( action="cache_metrics_export", scheduler=stats.get("scheduler"), metrics_lines=payload.count("\n"), ) return PlainTextResponse(payload) except Exception as exc: logger.exception(f"导出缓存指标失败: {exc}") raise HTTPException(status_code=500, detail=f"导出缓存指标失败: {exc}") def _format_prometheus(self, stats: dict[str, Any]) -> str: """ 将 scheduler/affinity 指标转换为 Prometheus 文本格式。 """ scheduler_metrics = stats.get("scheduler_metrics", {}) affinity_stats = stats.get("affinity_stats", {}) metric_map: list[tuple[str, str, float]] = [ ( "cache_scheduler_total_batches", "Total batches pulled from provider list", float(scheduler_metrics.get("total_batches", 0)), ), ( "cache_scheduler_last_batch_size", "Size of the latest candidate batch", float(scheduler_metrics.get("last_batch_size", 0)), ), ( "cache_scheduler_total_candidates", "Total candidates enumerated by scheduler", float(scheduler_metrics.get("total_candidates", 0)), ), ( "cache_scheduler_last_candidate_count", "Number of candidates in the most recent batch", float(scheduler_metrics.get("last_candidate_count", 0)), ), ( "cache_scheduler_cache_hits", "Cache hits counted during scheduling", float(scheduler_metrics.get("cache_hits", 0)), ), ( "cache_scheduler_cache_misses", "Cache misses counted during scheduling", float(scheduler_metrics.get("cache_misses", 0)), ), ( "cache_scheduler_cache_hit_rate", "Cache hit rate during scheduling", float(scheduler_metrics.get("cache_hit_rate", 0.0)), ), ( "cache_scheduler_concurrency_denied", "Times candidate rejected due to concurrency limits", float(scheduler_metrics.get("concurrency_denied", 0)), ), ( "cache_scheduler_avg_candidates_per_batch", "Average candidates per batch", float(scheduler_metrics.get("avg_candidates_per_batch", 0.0)), ), ] affinity_map: list[tuple[str, str, float]] = [ ( "cache_affinity_total", "Total cache affinities stored", float(affinity_stats.get("total_affinities", 0)), ), ( "cache_affinity_hits", "Affinity cache hits", float(affinity_stats.get("cache_hits", 0)), ), ( "cache_affinity_misses", "Affinity cache misses", float(affinity_stats.get("cache_misses", 0)), ), ( "cache_affinity_hit_rate", "Affinity cache hit rate", float(affinity_stats.get("cache_hit_rate", 0.0)), ), ( "cache_affinity_invalidations", "Affinity invalidations", float(affinity_stats.get("cache_invalidations", 0)), ), ( "cache_affinity_provider_switches", "Affinity provider switches", float(affinity_stats.get("provider_switches", 0)), ), ( "cache_affinity_key_switches", "Affinity key switches", float(affinity_stats.get("key_switches", 0)), ), ] lines = [] for name, help_text, value in metric_map + affinity_map: lines.append(f"# HELP {name} {help_text}") lines.append(f"# TYPE {name} gauge") lines.append(f"{name} {value}") scheduler_name = stats.get("scheduler", "cache_aware") lines.append(f'cache_scheduler_info{{scheduler="{scheduler_name}"}} 1') return "\n".join(lines) + "\n" @dataclass class AdminGetUserAffinityAdapter(AdminApiAdapter): user_identifier: str async def handle(self, context: ApiRequestContext) -> dict[str, Any]: # type: ignore[override] db = context.db try: user_id = resolve_user_identifier(db, self.user_identifier) if not user_id: raise HTTPException( status_code=404, detail=f"无法识别的用户标识符: {self.user_identifier}。支持用户名、邮箱、User ID或API Key ID", ) user = db.query(User).filter(User.id == user_id).first() redis_client = get_redis_client_sync() affinity_mgr = await get_affinity_manager(redis_client) # 获取该用户的所有缓存亲和性 all_affinities = await affinity_mgr.list_affinities() user_affinities = [aff for aff in all_affinities if aff.get("user_id") == user_id] if not user_affinities: response = { "status": "not_found", "message": f"用户 {user.username} ({user.email}) 没有缓存亲和性", "user_info": { "user_id": user_id, "username": user.username, "email": user.email, }, "affinities": [], } context.add_audit_metadata( action="cache_user_affinity", user_identifier=self.user_identifier, resolved_user_id=user_id, affinity_count=0, status="not_found", ) return response response = { "status": "ok", "user_info": { "user_id": user_id, "username": user.username, "email": user.email, }, "affinities": [ { "provider_id": aff["provider_id"], "endpoint_id": aff["endpoint_id"], "key_id": aff["key_id"], "api_format": aff.get("api_format"), "model_name": aff.get("model_name"), "created_at": aff["created_at"], "expire_at": aff["expire_at"], "request_count": aff["request_count"], } for aff in user_affinities ], "total_endpoints": len(user_affinities), } context.add_audit_metadata( action="cache_user_affinity", user_identifier=self.user_identifier, resolved_user_id=user_id, affinity_count=len(user_affinities), status="ok", ) return response except HTTPException: raise except Exception as exc: logger.exception(f"查询用户缓存亲和性失败: {exc}") raise HTTPException(status_code=500, detail=f"查询失败: {exc}") @dataclass class AdminListAffinitiesAdapter(AdminApiAdapter): keyword: str | None limit: int offset: int async def handle(self, context: ApiRequestContext) -> dict[str, Any]: # type: ignore[override] db = context.db redis_client = get_redis_client_sync() if not redis_client: raise HTTPException(status_code=503, detail="Redis未初始化，无法获取缓存亲和性") affinity_mgr = await get_affinity_manager(redis_client) matched_user_id = None matched_api_key_id = None raw_affinities: list[dict[str, Any]] = [] if self.keyword: # 首先检查是否是 API Key ID（affinity_key） api_key = db.query(ApiKey).filter(ApiKey.id == self.keyword).first() if api_key: # 直接通过 affinity_key 过滤 matched_api_key_id = str(api_key.id) matched_user_id = str(api_key.user_id) all_affinities = await affinity_mgr.list_affinities() raw_affinities = [ aff for aff in all_affinities if aff.get("affinity_key") == matched_api_key_id ] else: # 尝试解析为用户标识 user_id = resolve_user_identifier(db, self.keyword) if user_id: matched_user_id = user_id # 获取该用户所有的 API Key ID user_api_keys = db.query(ApiKey).filter(ApiKey.user_id == user_id).all() user_api_key_ids = {str(k.id) for k in user_api_keys} # 过滤出该用户所有 API Key 的亲和性 all_affinities = await affinity_mgr.list_affinities() raw_affinities = [ aff for aff in all_affinities if aff.get("affinity_key") in user_api_key_ids ] else: # 关键词不是有效标识，返回所有亲和性（后续会进行模糊匹配） raw_affinities = await affinity_mgr.list_affinities() else: raw_affinities = await affinity_mgr.list_affinities() # 收集所有 affinity_key (API Key ID) affinity_keys = { item.get("affinity_key") for item in raw_affinities if item.get("affinity_key") } # 批量查询用户 API Key 信息 user_api_key_map: dict[str, ApiKey] = {} if affinity_keys: user_api_keys = db.query(ApiKey).filter(ApiKey.id.in_(list(affinity_keys))).all() user_api_key_map = {str(k.id): k for k in user_api_keys} # 收集所有 user_id user_ids = {str(k.user_id) for k in user_api_key_map.values()} user_map: dict[str, User] = {} if user_ids: users = db.query(User).filter(User.id.in_(list(user_ids))).all() user_map = {str(user.id): user for user in users} # 收集所有provider_id、endpoint_id、key_id provider_ids = { item.get("provider_id") for item in raw_affinities if item.get("provider_id") } endpoint_ids = { item.get("endpoint_id") for item in raw_affinities if item.get("endpoint_id") } key_ids = {item.get("key_id") for item in raw_affinities if item.get("key_id")} # 批量查询Provider、Endpoint、Key信息 from src.models.database import Provider, ProviderAPIKey, ProviderEndpoint provider_map = {} if provider_ids: providers = db.query(Provider).filter(Provider.id.in_(list(provider_ids))).all() provider_map = {p.id: p for p in providers} endpoint_map = {} if endpoint_ids: endpoints = ( db.query(ProviderEndpoint).filter(ProviderEndpoint.id.in_(list(endpoint_ids))).all() ) endpoint_map = {e.id: e for e in endpoints} key_map = {} if key_ids: keys = db.query(ProviderAPIKey).filter(ProviderAPIKey.id.in_(list(key_ids))).all() key_map = {k.id: k for k in keys} # 收集所有 model_name（实际存储的是 global_model_id）并批量查询 GlobalModel from src.models.database import GlobalModel global_model_ids = { item.get("model_name") for item in raw_affinities if item.get("model_name") } global_model_map: dict[str, GlobalModel] = {} if global_model_ids: # model_name 可能是 UUID 格式的 global_model_id，也可能是原始模型名称 global_models = ( db.query(GlobalModel).filter(GlobalModel.id.in_(list(global_model_ids))).all() ) global_model_map = {str(gm.id): gm for gm in global_models} keyword_lower = self.keyword.lower() if self.keyword else None items = [] for affinity in raw_affinities: affinity_key = affinity.get("affinity_key") if not affinity_key: continue # 通过 affinity_key（API Key ID）找到用户 API Key 和用户 user_api_key = user_api_key_map.get(affinity_key) user = user_map.get(str(user_api_key.user_id)) if user_api_key else None user_id = str(user_api_key.user_id) if user_api_key else None provider_id = affinity.get("provider_id") endpoint_id = affinity.get("endpoint_id") key_id = affinity.get("key_id") provider = provider_map.get(provider_id) endpoint = endpoint_map.get(endpoint_id) key = key_map.get(key_id) # 用户 API Key 脱敏显示（解密 key_encrypted 后脱敏） user_api_key_masked = None if user_api_key and user_api_key.key_encrypted: user_api_key_masked = decrypt_and_mask(user_api_key.key_encrypted) # Provider Key 脱敏显示（解密 api_key 后脱敏） provider_key_masked = None if key and key.api_key: provider_key_masked = decrypt_and_mask(key.api_key) item = { "affinity_key": affinity_key, "user_api_key_name": user_api_key.name if user_api_key else None, "user_api_key_prefix": user_api_key_masked, "is_standalone": user_api_key.is_standalone if user_api_key else False, "user_id": user_id, "username": user.username if user else None, "email": user.email if user else None, "provider_id": provider_id, "provider_name": provider.name if provider else None, "endpoint_id": endpoint_id, "endpoint_url": endpoint.base_url if endpoint else None, "key_id": key_id, "key_name": key.name if key else None, "key_prefix": provider_key_masked, "rate_multipliers": key.rate_multipliers if key else None, "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")) else affinity.get("model_name") # 如果找不到 GlobalModel，显示原始值 ), "model_display_name": ( global_model_map.get(affinity.get("model_name")).display_name if affinity.get("model_name") and global_model_map.get(affinity.get("model_name")) else None ), "api_format": affinity.get("api_format"), "created_at": affinity.get("created_at"), "expire_at": affinity.get("expire_at"), "request_count": affinity.get("request_count", 0), } if keyword_lower and not matched_user_id and not matched_api_key_id: searchable = [ item["affinity_key"], item["user_api_key_name"] or "", item["user_id"] or "", item["username"] or "", item["email"] or "", item["provider_id"] or "", item["key_id"] or "", ] if not any(keyword_lower in str(value).lower() for value in searchable if value): continue items.append(item) items.sort(key=lambda x: x.get("expire_at") or 0, reverse=True) paged_items, meta = paginate_sequence(items, self.limit, self.offset) payload = build_pagination_payload( paged_items, meta, matched_user_id=matched_user_id, ) response = { "status": "ok", "data": payload, } result_count = meta.count if hasattr(meta, "count") else len(paged_items) context.add_audit_metadata( action="cache_affinity_list", keyword=self.keyword, matched_user_id=matched_user_id, matched_api_key_id=matched_api_key_id, limit=self.limit, offset=self.offset, result_count=result_count, ) return response @dataclass class AdminClearUserCacheAdapter(AdminApiAdapter): user_identifier: 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) # 首先检查是否直接是 API Key ID (affinity_key) api_key = db.query(ApiKey).filter(ApiKey.id == self.user_identifier).first() if api_key: # 直接按 affinity_key 清除 affinity_key = str(api_key.id) user = db.query(User).filter(User.id == api_key.user_id).first() all_affinities = await affinity_mgr.list_affinities() target_affinities = [ aff for aff in all_affinities if aff.get("affinity_key") == affinity_key ] count = 0 for aff in target_affinities: api_format = aff.get("api_format") model_name = aff.get("model_name") endpoint_id = aff.get("endpoint_id") if api_format and model_name: await affinity_mgr.invalidate_affinity( affinity_key, api_format, model_name, endpoint_id=endpoint_id ) count += 1 logger.info( f"已清除API Key缓存亲和性: api_key_name={api_key.name}, affinity_key={affinity_key[:8]}..., 清除数量={count}" ) response = { "status": "ok", "message": f"已清除 API Key {api_key.name} 的缓存亲和性", "user_info": { "user_id": str(api_key.user_id), "username": user.username if user else None, "email": user.email if user else None, "api_key_id": affinity_key, "api_key_name": api_key.name, }, } context.add_audit_metadata( action="cache_clear_api_key", user_identifier=self.user_identifier, resolved_api_key_id=affinity_key, cleared_count=count, ) return response # 如果不是 API Key ID，尝试解析为用户标识 user_id = resolve_user_identifier(db, self.user_identifier) if not user_id: raise HTTPException( status_code=404, detail=f"无法识别的标识符: {self.user_identifier}。支持用户名、邮箱、User ID或API Key ID", ) user = db.query(User).filter(User.id == user_id).first() # 获取该用户所有的 API Key user_api_keys = db.query(ApiKey).filter(ApiKey.user_id == user_id).all() user_api_key_ids = {str(k.id) for k in user_api_keys} # 获取该用户所有 API Key 的缓存亲和性并逐个失效 all_affinities = await affinity_mgr.list_affinities() user_affinities = [ aff for aff in all_affinities if aff.get("affinity_key") in user_api_key_ids ] count = 0 for aff in user_affinities: affinity_key = aff.get("affinity_key") api_format = aff.get("api_format") model_name = aff.get("model_name") endpoint_id = aff.get("endpoint_id") if affinity_key and api_format and model_name: await affinity_mgr.invalidate_affinity( affinity_key, api_format, model_name, endpoint_id=endpoint_id ) count += 1 logger.info( f"已清除用户缓存亲和性: username={user.username}, user_id={user_id[:8]}..., 清除数量={count}" ) response = { "status": "ok", "message": f"已清除用户 {user.username} 的所有缓存亲和性", "user_info": {"user_id": user_id, "username": user.username, "email": user.email}, } context.add_audit_metadata( action="cache_clear_user", user_identifier=self.user_identifier, resolved_user_id=user_id, cleared_count=count, ) return response except HTTPException: raise except Exception as exc: logger.exception(f"清除用户缓存亲和性失败: {exc}") 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: redis_client = get_redis_client_sync() affinity_mgr = await get_affinity_manager(redis_client) count = await affinity_mgr.clear_all() logger.warning(f"已清除所有缓存亲和性（管理员操作）: {count} 个") context.add_audit_metadata( action="cache_clear_all", cleared_count=count, ) return {"status": "ok", "message": "已清除所有缓存亲和性", "count": count} except Exception as exc: logger.exception(f"清除所有缓存亲和性失败: {exc}") raise HTTPException(status_code=500, detail=f"清除失败: {exc}") @dataclass class AdminClearProviderCacheAdapter(AdminApiAdapter): provider_id: str async def handle(self, context: ApiRequestContext) -> dict[str, Any]: # type: ignore[override] try: redis_client = get_redis_client_sync() affinity_mgr = await get_affinity_manager(redis_client) count = await affinity_mgr.invalidate_all_for_provider(self.provider_id) logger.info( f"已清除Provider缓存亲和性: provider_id={self.provider_id[:8]}..., count={count}" ) context.add_audit_metadata( action="cache_clear_provider", provider_id=self.provider_id, cleared_count=count, ) return { "status": "ok", "message": "已清除Provider的缓存亲和性", "provider_id": self.provider_id, "count": count, } except Exception as exc: logger.exception(f"清除Provider缓存亲和性失败: {exc}") raise HTTPException(status_code=500, detail=f"清除失败: {exc}") class AdminCacheConfigAdapter(AdminApiAdapter): async def handle(self, context: ApiRequestContext) -> dict[str, Any]: # type: ignore[override] from src.config.constants import ConcurrencyDefaults from src.services.rate_limit.adaptive_reservation import get_adaptive_reservation_manager from src.services.scheduling.affinity_manager import CacheAffinityManager # 获取动态预留管理器的配置 reservation_manager = get_adaptive_reservation_manager() reservation_stats = reservation_manager.get_stats() response = { "status": "ok", "data": { "cache_ttl_seconds": CacheAffinityManager.DEFAULT_CACHE_TTL, "cache_reservation_ratio": ConcurrencyDefaults.CACHE_RESERVATION_RATIO, "dynamic_reservation": { "enabled": True, "config": reservation_stats["config"], "description": { "probe_phase_requests": "探测阶段请求数阈值", "probe_reservation": "探测阶段预留比例", "stable_min_reservation": "稳定阶段最小预留比例", "stable_max_reservation": "稳定阶段最大预留比例", "low_load_threshold": "低负载阈值（低于此值使用最小预留）", "high_load_threshold": "高负载阈值（高于此值根据置信度使用较高预留）", }, }, "description": { "cache_ttl": "缓存亲和性有效期（秒）", "cache_reservation_ratio": "静态预留比例（已被动态预留替代）", "dynamic_reservation": "动态预留机制配置", }, }, } context.add_audit_metadata( action="cache_config", cache_ttl_seconds=CacheAffinityManager.DEFAULT_CACHE_TTL, cache_reservation_ratio=ConcurrencyDefaults.CACHE_RESERVATION_RATIO, dynamic_reservation_enabled=True, ) return response # ==================== 模型映射缓存管理 ==================== @router.get("/model-mapping/stats") async def get_model_mapping_cache_stats( request: Request, db: Session = Depends(get_db), ) -> Any: """ 获取模型映射缓存统计信息 获取模型解析缓存的详细统计信息，包括各类型缓存键数量、 映射关系列表、Provider 级别的模型映射缓存等。 **返回字段**: - `status`: 状态（ok） - `data`: 统计数据 - `available`: Redis 是否可用 - `message`: 提示消息（当 Redis 未启用时） - `ttl_seconds`: 缓存 TTL（秒） - `total_keys`: 总缓存键数量 - `breakdown`: 各类型缓存键数量分解 - `model_by_id`: Model ID 缓存数量 - `model_by_provider_global`: Provider-GlobalModel 缓存数量 - `global_model_by_id`: GlobalModel ID 缓存数量 - `global_model_by_name`: GlobalModel 名称缓存数量 - `global_model_resolve`: GlobalModel 解析缓存数量 - `mappings`: 模型映射列表（最多 100 条） - `mapping_name`: 映射名称（别名） - `global_model_name`: GlobalModel 名称 - `global_model_display_name`: GlobalModel 显示名称 - `providers`: 使用该映射的 Provider 列表 - `ttl`: 缓存剩余 TTL（秒） - `provider_model_mappings`: Provider 级别的模型映射（最多 100 条） - `provider_id`: Provider ID - `provider_name`: Provider 名称 - `global_model_id`: GlobalModel ID - `global_model_name`: GlobalModel 名称 - `global_model_display_name`: GlobalModel 显示名称 - `provider_model_name`: Provider 侧的模型名称 - `aliases`: 别名列表 - `ttl`: 缓存剩余 TTL（秒） - `hit_count`: 缓存命中次数 - `unmapped`: 未映射或无效的缓存条目 """ adapter = AdminModelMappingCacheStatsAdapter() return await pipeline.run(adapter=adapter, http_request=request, db=db, mode=adapter.mode) @router.delete("/model-mapping") async def clear_all_model_mapping_cache( request: Request, db: Session = Depends(get_db), ) -> Any: """ 清除所有模型映射缓存 清除系统中所有的模型映射缓存，包括 Model、GlobalModel、 模型解析等所有相关缓存。下次请求时将重新从数据库查询。 **警告**: 此操作会影响所有模型解析，请谨慎使用 **返回字段**: - `status`: 状态（ok） - `message`: 操作结果消息 - `deleted_count`: 删除的缓存键数量 """ adapter = AdminClearAllModelMappingCacheAdapter() return await pipeline.run(adapter=adapter, http_request=request, db=db, mode=adapter.mode) @router.delete("/model-mapping/{model_name}") async def clear_model_mapping_cache_by_name( model_name: str, request: Request, db: Session = Depends(get_db), ) -> Any: """ 清除指定模型名称的映射缓存 根据模型名称清除相关的映射缓存，包括 resolve 缓存和 name 缓存。 用于更新单个模型的配置后刷新缓存。 **路径参数**: - `model_name`: 模型名称（可以是 GlobalModel.name 或映射名称） **返回字段**: - `status`: 状态（ok） - `message`: 操作结果消息 - `model_name`: 模型名称 - `deleted_keys`: 删除的缓存键列表 """ adapter = AdminClearModelMappingCacheByNameAdapter(model_name=model_name) return await pipeline.run(adapter=adapter, http_request=request, db=db, mode=adapter.mode) @router.delete("/model-mapping/provider/{provider_id}/{global_model_id}") async def clear_provider_model_mapping_cache( provider_id: str, global_model_id: str, request: Request, db: Session = Depends(get_db), ) -> Any: """ 清除指定 Provider 和 GlobalModel 的模型映射缓存 清除特定 Provider 和 GlobalModel 组合的映射缓存及其命中次数统计。 用于 Provider 模型配置更新后刷新缓存。 **路径参数**: - `provider_id`: Provider ID - `global_model_id`: GlobalModel ID **返回字段**: - `status`: 状态（ok） - `message`: 操作结果消息 - `provider_id`: Provider ID - `global_model_id`: GlobalModel ID - `deleted_keys`: 删除的缓存键列表 """ adapter = AdminClearProviderModelMappingCacheAdapter( provider_id=provider_id, global_model_id=global_model_id ) return await pipeline.run(adapter=adapter, http_request=request, db=db, mode=adapter.mode) class AdminModelMappingCacheStatsAdapter(AdminApiAdapter): async def handle(self, context: ApiRequestContext) -> dict[str, Any]: # type: ignore[override] import json from src.clients.redis_client import get_redis_client from src.config.constants import CacheTTL from src.models.database import GlobalModel, Model, Provider db = context.db try: redis = await get_redis_client(require_redis=False) if not redis: return { "status": "ok", "data": { "available": False, "message": "Redis 未启用，模型映射缓存不可用", }, } # 统计各类型缓存键数量 model_id_keys = [] global_model_id_keys = [] global_model_name_keys = [] global_model_resolve_keys = [] provider_global_keys = [] # 扫描所有模型相关的缓存键 async for key in redis.scan_iter(match="model:*", count=100): key_str = key.decode() if isinstance(key, bytes) else key if key_str.startswith("model:id:"): model_id_keys.append(key_str) elif key_str.startswith("model:provider_global:"): # 过滤掉 hits 统计键，只保留实际的缓存键 if not key_str.startswith("model:provider_global:hits:"): provider_global_keys.append(key_str) async for key in redis.scan_iter(match="global_model:*", count=100): key_str = key.decode() if isinstance(key, bytes) else key if key_str.startswith("global_model:id:"): global_model_id_keys.append(key_str) elif key_str.startswith("global_model:name:"): global_model_name_keys.append(key_str) elif key_str.startswith("global_model:resolve:"): global_model_resolve_keys.append(key_str) total_keys = ( len(model_id_keys) + len(global_model_id_keys) + len(global_model_name_keys) + len(global_model_resolve_keys) + len(provider_global_keys) ) # 解析缓存内容，构建映射列表 mappings = [] unmapped_entries = [] for key in global_model_resolve_keys[:100]: # 最多处理 100 个 mapping_name = key.replace("global_model:resolve:", "") try: cached_value = await redis.get(key) ttl = await redis.ttl(key) if cached_value: cached_str = ( cached_value.decode() if isinstance(cached_value, bytes) else cached_value ) if cached_str == "NOT_FOUND": unmapped_entries.append( { "mapping_name": mapping_name, "status": "not_found", "ttl": ttl if ttl > 0 else None, } ) else: try: cached_data = json.loads(cached_str) global_model_id = cached_data.get("id") global_model_name = cached_data.get("name") global_model_display_name = cached_data.get("display_name") # 跳过 mapping_name == global_model_name 的情况（直接匹配，不是映射） if mapping_name == global_model_name: continue # 查询哪些 Provider 配置了这个映射名称 provider_names = [] if global_model_id: models = ( db.query(Model, Provider) .join(Provider, Model.provider_id == Provider.id) .filter( Model.global_model_id == global_model_id, Model.is_active, Provider.is_active, ) .all() ) # 只显示配置了该映射名称的 Provider for model, provider in models: # 检查是否是主模型名称 if model.provider_model_name == mapping_name: provider_names.append(provider.name) continue # 检查是否在映射列表中 if model.provider_model_mappings: mapping_list = [ a.get("name") for a in model.provider_model_mappings if isinstance(a, dict) ] if mapping_name in mapping_list: provider_names.append(provider.name) provider_names = sorted(list(set(provider_names))) mappings.append( { "mapping_name": mapping_name, "global_model_name": global_model_name, "global_model_display_name": global_model_display_name, "providers": provider_names, "ttl": ttl if ttl > 0 else None, } ) except json.JSONDecodeError: unmapped_entries.append( { "mapping_name": mapping_name, "status": "invalid", "ttl": ttl if ttl > 0 else None, } ) except Exception as e: logger.warning(f"解析缓存键 {key} 失败: {e}") unmapped_entries.append( { "mapping_name": mapping_name, "status": "error", "ttl": None, } ) # 按 mapping_name 排序 mappings.sort(key=lambda x: x["mapping_name"]) # 3. 解析 provider_global 缓存（Provider 级别的模型解析缓存） provider_model_mappings = [] # 预加载 Provider 和 GlobalModel 数据 provider_map = { str(p.id): p for p in db.query(Provider).filter(Provider.is_active.is_(True)).all() } global_model_map = { str(gm.id): gm for gm in db.query(GlobalModel).filter(GlobalModel.is_active.is_(True)).all() } for key in provider_global_keys[:100]: # 最多处理 100 个 # key 格式: model:provider_global:{provider_id}:{global_model_id} try: parts = key.replace("model:provider_global:", "").split(":") if len(parts) != 2: continue provider_id, global_model_id = parts cached_value = await redis.get(key) ttl = await redis.ttl(key) # 获取命中次数 hit_count_key = f"model:provider_global:hits:{provider_id}:{global_model_id}" hit_count_raw = await redis.get(hit_count_key) hit_count = int(hit_count_raw) if hit_count_raw else 0 if cached_value: cached_str = ( cached_value.decode() if isinstance(cached_value, bytes) else cached_value ) try: cached_data = json.loads(cached_str) provider_model_name = cached_data.get("provider_model_name") cached_model_mappings = cached_data.get("provider_model_mappings", []) # 获取 Provider 和 GlobalModel 信息 provider = provider_map.get(provider_id) global_model = global_model_map.get(global_model_id) if provider and global_model: # 提取映射名称 mapping_names = [] if cached_model_mappings: for mapping_entry in cached_model_mappings: if isinstance(mapping_entry, dict) and mapping_entry.get( "name" ): mapping_names.append(mapping_entry["name"]) # provider_model_name 为空时跳过 if not provider_model_name: continue # 只显示有实际映射的条目： # 1. 全局模型名 != Provider 模型名（模型名称映射） # 2. 或者有映射配置 has_name_mapping = global_model.name != provider_model_name has_mappings = len(mapping_names) > 0 if has_name_mapping or has_mappings: # 构建用于展示的映射列表 # 如果只有名称映射没有额外映射，则用 global_model_name 作为"请求名称" display_mappings = ( mapping_names if mapping_names else [global_model.name] ) provider_model_mappings.append( { "provider_id": provider_id, "provider_name": provider.name, "global_model_id": global_model_id, "global_model_name": global_model.name, "global_model_display_name": global_model.display_name, "provider_model_name": provider_model_name, "aliases": display_mappings, "ttl": ttl if ttl > 0 else None, "hit_count": hit_count, } ) except json.JSONDecodeError: pass except Exception as e: logger.warning(f"解析 provider_global 缓存键 {key} 失败: {e}") # 按 provider_name + global_model_name 排序 provider_model_mappings.sort(key=lambda x: (x["provider_name"], x["global_model_name"])) response_data = { "available": True, "ttl_seconds": CacheTTL.MODEL, "total_keys": total_keys, "breakdown": { "model_by_id": len(model_id_keys), "model_by_provider_global": len(provider_global_keys), "global_model_by_id": len(global_model_id_keys), "global_model_by_name": len(global_model_name_keys), "global_model_resolve": len(global_model_resolve_keys), }, "mappings": mappings, "provider_model_mappings": ( provider_model_mappings if provider_model_mappings else None ), "unmapped": unmapped_entries if unmapped_entries else None, } context.add_audit_metadata( action="model_mapping_cache_stats", total_keys=total_keys, ) return {"status": "ok", "data": response_data} except Exception as exc: logger.exception(f"获取模型映射缓存统计失败: {exc}") raise HTTPException(status_code=500, detail=f"获取统计失败: {exc}") # ==================== Redis 缓存分类管理 ==================== # 所有已知的 Redis 缓存分类 # 格式: (category_key, display_name, redis_pattern, description) # 注意: redis_pattern 必须与各模块实际使用的 key 前缀保持一致。 # 新增或修改缓存 key 前缀时，请同步更新此列表。 _CACHE_CATEGORIES: list[tuple[str, str, str, str]] = [ ("upstream_models", "上游模型", "upstream_models:*", "Provider 上游获取的模型列表缓存"), ("model_id", "模型 ID", "model:id:*", "Model 按 ID 缓存"), ( "model_provider_global", "模型映射", "model:provider_global:*", "Provider-GlobalModel 模型映射缓存", ), ( "provider_mapping_preview", "映射预览", "admin:providers:mapping-preview:*", "Provider 详情页 mapping-preview 缓存", ), ("global_model", "全局模型", "global_model:*", "GlobalModel 缓存（ID/名称/解析）"), ("models_list", "模型列表", "models:list:*", "/v1/models 端点模型列表缓存"), ("user", "用户", "user:*", "用户信息缓存（ID/Email）"), ("apikey", "API Key", "apikey:*", "API Key 认证缓存（Hash/Auth）"), ("api_key_id", "API Key ID", "api_key:id:*", "API Key 按 ID 缓存"), ("cache_affinity", "缓存亲和性", "cache_affinity:*", "请求路由亲和性缓存"), ("provider_billing", "Provider 计费", "provider:billing_type:*", "Provider 计费类型缓存"), ( "provider_rate", "Provider 费率", "provider_api_key:rate_multiplier:*", "ProviderAPIKey 费率倍数缓存", ), ("provider_balance", "Provider 余额", "provider_ops:balance:*", "Provider 余额查询缓存"), ("health", "健康检查", "health:*", "端点健康状态缓存"), ("endpoint_status", "端点状态", "endpoint_status:*", "用户端点状态缓存"), ("dashboard", "仪表盘", "dashboard:*", "仪表盘统计缓存"), ("activity_heatmap", "活动热力图", "activity_heatmap:*", "用户活动热力图缓存"), ("gemini_files", "Gemini 文件映射", "gemini_files:*", "Gemini Files API 文件-Key 映射缓存"), ("provider_oauth", "OAuth 状态", "provider_oauth_state:*", "Provider OAuth 授权流程临时状态"), ( "oauth_refresh_lock", "OAuth 刷新锁", "provider_oauth_refresh_lock:*", "OAuth Token 刷新分布式锁", ), ("concurrency_lock", "并发锁", "concurrency:*", "请求并发控制锁"), ] @router.get("/redis-keys") async def get_redis_cache_categories( request: Request, db: Session = Depends(get_db), ) -> Any: """ 获取 Redis 缓存分类概览 扫描 Redis 中所有已知的缓存键模式，返回各分类的键数量。 用于管理员全局了解缓存使用情况。 **返回字段**: - `status`: 状态（ok） - `data`: 分类列表 - `categories`: 各分类信息数组 - `key`: 分类标识 - `name`: 显示名称 - `pattern`: Redis 键模式 - `description`: 描述 - `count`: 键数量 - `total_keys`: 总键数 """ adapter = AdminRedisCacheCategoriesAdapter() return await pipeline.run(adapter=adapter, http_request=request, db=db, mode=adapter.mode) @router.delete("/redis-keys/{category}") async def clear_redis_cache_category( category: str, request: Request, db: Session = Depends(get_db), ) -> Any: """ 清除指定分类的 Redis 缓存 根据分类标识清除该分类下的所有缓存键。 **路径参数**: - `category`: 分类标识（如 upstream_models、user、dashboard 等） **返回字段**: - `status`: 状态（ok） - `message`: 操作结果消息 - `category`: 分类标识 - `deleted_count`: 删除的键数量 """ adapter = AdminClearRedisCacheCategoryAdapter(category=category) return await pipeline.run(adapter=adapter, http_request=request, db=db, mode=adapter.mode) class AdminRedisCacheCategoriesAdapter(AdminApiAdapter): async def handle(self, context: ApiRequestContext) -> dict[str, Any]: # type: ignore[override] import asyncio from src.clients.redis_client import get_redis_client try: redis = await get_redis_client(require_redis=False) if not redis: return { "status": "ok", "data": {"available": False, "message": "Redis 未启用"}, } semaphore = asyncio.Semaphore(4) async def _count_keys(pattern: str) -> int: async with semaphore: count = 0 async for _ in redis.scan_iter(match=pattern, count=500): count += 1 return count # 限制扫描并发，避免刷新监控页时对 Redis 造成瞬时压力 counts = await asyncio.gather( *[_count_keys(pattern) for _, _, pattern, _ in _CACHE_CATEGORIES] ) categories = [] total_keys = 0 for (cat_key, name, pattern, description), count in zip(_CACHE_CATEGORIES, counts): categories.append( { "key": cat_key, "name": name, "pattern": pattern, "description": description, "count": count, } ) total_keys += count context.add_audit_metadata( action="redis_cache_categories", total_keys=total_keys, category_count=len(categories), ) return { "status": "ok", "data": { "available": True, "categories": categories, "total_keys": total_keys, }, } except Exception as exc: logger.exception("获取 Redis 缓存分类失败: {}", exc) raise HTTPException(status_code=500, detail="获取缓存分类失败，请检查 Redis 连接") @dataclass class AdminClearRedisCacheCategoryAdapter(AdminApiAdapter): category: str async def handle(self, context: ApiRequestContext) -> dict[str, Any]: # type: ignore[override] from src.clients.redis_client import get_redis_client try: # 查找分类 target = None for cat_key, name, pattern, _desc in _CACHE_CATEGORIES: if cat_key == self.category: target = (cat_key, name, pattern) break if not target: raise HTTPException( status_code=404, detail=f"未知的缓存分类: {self.category}", ) cat_key, name, pattern = target redis = await get_redis_client(require_redis=False) if not redis: raise HTTPException(status_code=503, detail="Redis 未启用") deleted_count = await scan_delete_pattern(redis, pattern) logger.warning( "已清除 Redis 缓存分类（管理员操作）: {} ({}), pattern={}, deleted={}", name, cat_key, pattern, deleted_count, ) context.add_audit_metadata( action="redis_cache_clear_category", category=cat_key, category_name=name, pattern=pattern, deleted_count=deleted_count, ) return { "status": "ok", "message": f"已清除 {name} 缓存", "category": cat_key, "deleted_count": deleted_count, } except HTTPException: raise except Exception as exc: logger.exception("清除 Redis 缓存分类失败: {}", exc) raise HTTPException(status_code=500, detail="清除缓存失败，请检查 Redis 连接") class AdminClearAllModelMappingCacheAdapter(AdminApiAdapter): async def handle(self, context: ApiRequestContext) -> dict[str, Any]: # type: ignore[override] from src.clients.redis_client import get_redis_client try: redis = await get_redis_client(require_redis=False) if not redis: raise HTTPException(status_code=503, detail="Redis 未启用") deleted_count = await scan_delete_pattern(redis, "model:*") deleted_count += await scan_delete_pattern(redis, "global_model:*") logger.warning(f"已清除所有模型映射缓存（管理员操作）: {deleted_count} 个键") context.add_audit_metadata( action="model_mapping_cache_clear_all", deleted_count=deleted_count, ) return { "status": "ok", "message": f"已清除所有模型映射缓存", "deleted_count": deleted_count, } except HTTPException: raise except Exception as exc: logger.exception(f"清除模型映射缓存失败: {exc}") raise HTTPException(status_code=500, detail=f"清除失败: {exc}") @dataclass class AdminClearModelMappingCacheByNameAdapter(AdminApiAdapter): model_name: str async def handle(self, context: ApiRequestContext) -> dict[str, Any]: # type: ignore[override] from src.clients.redis_client import get_redis_client try: redis = await get_redis_client(require_redis=False) if not redis: raise HTTPException(status_code=503, detail="Redis 未启用") deleted_keys = [] # 清除 resolve 缓存 resolve_key = f"global_model:resolve:{self.model_name}" if await redis.exists(resolve_key): await redis.delete(resolve_key) deleted_keys.append(resolve_key) # 清除 name 缓存 name_key = f"global_model:name:{self.model_name}" if await redis.exists(name_key): await redis.delete(name_key) deleted_keys.append(name_key) logger.info(f"已清除模型映射缓存: model_name={self.model_name}, 删除键={deleted_keys}") context.add_audit_metadata( action="model_mapping_cache_clear_by_name", model_name=self.model_name, deleted_keys=deleted_keys, ) return { "status": "ok", "message": f"已清除模型 {self.model_name} 的映射缓存", "model_name": self.model_name, "deleted_keys": deleted_keys, } except HTTPException: raise except Exception as exc: logger.exception(f"清除模型映射缓存失败: {exc}") raise HTTPException(status_code=500, detail=f"清除失败: {exc}") @dataclass class AdminClearProviderModelMappingCacheAdapter(AdminApiAdapter): provider_id: str global_model_id: str async def handle(self, context: ApiRequestContext) -> dict[str, Any]: # type: ignore[override] from src.clients.redis_client import get_redis_client try: redis = await get_redis_client(require_redis=False) if not redis: raise HTTPException(status_code=503, detail="Redis 未启用") deleted_keys = [] # 清除 provider_global 缓存 provider_global_key = f"model:provider_global:{self.provider_id}:{self.global_model_id}" if await redis.exists(provider_global_key): await redis.delete(provider_global_key) deleted_keys.append(provider_global_key) # 清除对应的 hit_count 缓存 hit_count_key = f"model:provider_global:hits:{self.provider_id}:{self.global_model_id}" if await redis.exists(hit_count_key): await redis.delete(hit_count_key) deleted_keys.append(hit_count_key) logger.info( f"已清除 Provider 模型映射缓存: provider_id={self.provider_id[:8]}..., " f"global_model_id={self.global_model_id[:8]}..., 删除键={deleted_keys}" ) context.add_audit_metadata( action="provider_model_mapping_cache_clear", provider_id=self.provider_id, global_model_id=self.global_model_id, deleted_keys=deleted_keys, ) return { "status": "ok", "message": "已清除 Provider 模型映射缓存", "provider_id": self.provider_id, "global_model_id": self.global_model_id, "deleted_keys": deleted_keys, } except HTTPException: raise except Exception as exc: logger.exception(f"清除 Provider 模型映射缓存失败: {exc}") raise HTTPException(status_code=500, detail=f"清除失败: {exc}")