fabriziosalmi/llmproxy

# LLMProxy — LLM 安全网关 面向大语言模型的安全优先代理，具备环形插件流水线、基于 WASM 沙箱的插件执行、NLP 驱动的 PII 检测以及实时安全运营中心 (SOC) UI。     [](https://github.com/fabriziosalmi/llmproxy/actions/workflows/ci.yml)  ## 目录 1. [架构概述](#architecture-overview) 2. [安全流水线](#security-pipeline) 3. [插件引擎](#plugin-engine) 4. [API 参考](#api-reference) 5. [安全与身份](#security--identity) 6. [可观测性与导出](#observability--export) 7. [前端 SOC](#frontend-soc) 8. [配置](#configuration) 9. [测试](#testing) 10. [安装与部署](#installation--deployment) ## 架构概述 LLMProxy 是一个专注于安全的 LLM 代理，具有分层防御流水线： 1. **ASGI Firewall** — 字节级 L7 请求过滤 2. **SecurityShield** — 注入评分、PII 掩码（Presidio NLP + 正则回退）、轨迹检测 3. **Ring Plugin Pipeline** — 5 环插件引擎 (INGRESS → PRE_FLIGHT → ROUTING → POST_FLIGHT → BACKGROUND) 4. **WASM Sandbox** — 基于 Extism 的沙箱插件执行，用于运行不受信任的代码 5. **Rate Limiter** — 基于 IP/Key 的令牌桶 ASGI 中间件 ### 路由架构 `RotatorAgent` 在 `proxy/routes/` 下编排了 9 个路由模块，每个模块均为工厂函数 (`create_router(agent) -> APIRouter`)： | 模块 | 路由 | 职责 | |--------|--------|----------------| | `chat.py` | `/v1/chat/completions` | 核心代理端点，包含 auth、identity、RBAC、零信任、预算跟踪 | | `completions.py` | `/v1/completions` | 传统文本补全端点 (prompt→messages 转换) | | `embeddings.py` | `/v1/embeddings` | 嵌入端点，含 PII 安全检查、多提供商转换 | | `models.py` | `/v1/models`, `/v1/models/{id}` | OpenAI 兼容的模型发现（聚合所有提供商） | | `admin.py` | `/api/v1/proxy/*`, `/api/v1/features/*`, `/api/v1/panic`, `/api/v1/analytics/*`, `/api/v1/audit` | 代理控制、功能开关、熔断、支出分析、审计日志 | | `registry.py` | `/api/v1/registry/*`, `/api/v1/telemetry/stream` | 端点 CRUD、SSE 遥测流 | | `identity.py` | `/api/v1/identity/*` | SSO 配置、用户信息、令牌交换 | | `plugins.py` | `/api/v1/plugins/*` | 插件生命周期（安装、卸载、热交换、回滚） | | `telemetry.py` | `/health`, `/metrics`, `/api/v1/logs` | 健康探针、Prometheus 指标、日志 SSE | 重度依赖（OpenTelemetry, Sentry）在路由处理器内部延迟导入，而非模块级别——无需 mock 整个导入链即可实现测试隔离。 ### 技术栈 | 层 | 技术 | |-------|-----------| | Backend | Python 3.12+, FastAPI (modular routers), uvicorn, aiohttp | | Frontend | Vanilla JS (ES Modules), Tailwind CSS, Chart.js, xterm.js | | Database | SQLite (aiosqlite) — endpoints, app state, spend analytics, audit log | | Observability | OpenTelemetry, Prometheus, Sentry | | Security | PyJWT, OIDC/JWKS, mTLS, Tailscale Zero-Trust | | Secrets | Infisical SDK + env fallback | ## API 参考 ### 模型代理 (端口 8090) | 端点 | 方法 | 描述 | |----------|--------|-------------| | `/v1/chat/completions` | `POST` | 统一推理端点 (OpenAI 兼容)。支持 15 个提供商、跨提供商回退、模型别名。 | | `/v1/completions` | `POST` | 传统文本补全端点。将 prompt 转换为 messages，支持流式传输。 | | `/v1/embeddings` | `POST` | 带 PII 安全检查的嵌入端点。支持 OpenAI, Google, Ollama, Azure。 | | `/v1/models` | `GET` | 模型发现 —— 聚合所有已配置提供商的模型。Cursor, OpenWebUI 等必需。 | | `/v1/models/{model_id}` | `GET` | 单个模型信息，带自动检测回退。 | | `/health` | `GET` | 存活/就绪探针，含连接池统计。 | | `/metrics` | `GET` | Prometheus 指标：req/s, errors, latency P50/P95/P99, budget, TTFT, circuit state。 | ### 注册与控制 | 端点 | 方法 | 描述 | |----------|--------|-------------| | `/api/v1/registry` | `GET` | 完整模型池状态 (Live/Discovered/Offline)。 | | `/api/v1/registry/{id}/toggle` | `POST` | 开启/关闭端点。 | | `/api/v1/registry/{id}/priority` | `POST` | 设置端点路由优先级。 | | `/api/v1/registry/{id}` | `DELETE` | 移除端点。 | | `/api/v1/proxy/toggle` | `POST` | 启用/禁用代理。 | | `/api/v1/proxy/status` | `GET` | 代理启用状态 + 优先级模式。 | | `/api/v1/proxy/priority/toggle` | `POST` | 切换优先级引导模式。 | ### 身份与 SSO | 端点 | 方法 | 描述 | |----------|--------|-------------| | `/api/v1/identity/me` | `GET` | 当前用户身份、角色和权限（来自 JWT 或 API Key）。 | | `/api/v1/identity/exchange` | `POST` | 将外部 OIDC JWT 交换为内部代理会话令牌。 | | `/api/v1/identity/config` | `GET` | 公开 SSO 提供商列表（用于前端 OAuth 流程）。 | ### 插件 | 端点 | 方法 | 描述 | |----------|--------|-------------| | `/api/v1/plugins` | `GET` | 列出所有插件及市场元数据（版本、作者、ui_schema）。 | | `/api/v1/plugins/install` | `POST` | 安装插件（经 AST 扫描后热交换）。 | | `/api/v1/plugins/{name}` | `DELETE` | 卸载插件。 | | `/api/v1/plugins/toggle` | `POST` | 启用/禁用插件。 | | `/api/v1/plugins/hot-swap` | `POST` | 零停机 RCU 重载及健康检查。 | | `/api/v1/plugins/rollback` | `POST` | 回滚到之前的插件状态。 | ### 系统 | 端点 | 方法 | 描述 | |----------|--------|-------------| | `/api/v1/features` | `GET` | 功能开关 (language_guard, injection_guard, link_sanitizer)。 | | `/api/v1/features/toggle` | `POST` | 切换安全功能。 | | `/api/v1/telemetry/stream` | `GET` | 系统事件的实时 SSE 流。 | | `/api/v1/logs` | `GET` | 用于终端的 SSE 日志流。 | | `/api/v1/panic` | `POST` | 紧急熔断开关 —— 阻断所有流量。 | | `/api/v1/admin/reload` | `POST` | 无需重启热重载 config.yaml。 | | `/api/v1/analytics/spend` | `GET` | 按模型/提供商/密钥/日期的支出明细。参数：`from`, `to`, `group_by`, `limit`。 | | `/api/v1/analytics/spend/topmodels` | `GET` | 按支出排名的顶级模型。 | | `/api/v1/audit` | `GET` | 持久化审计日志查询。参数：`from`, `to`, `model`, `key_prefix`, `status`, `blocked`。 | | `/api/v1/version` | `GET` | 当前版本。 | | `/api/v1/service-info` | `GET` | 主机、端口、URL。 | | `/api/v1/network/info` | `GET` | 网络及 Tailscale 状态。 | | `/api/v1/cache/stats` | `GET` | 缓存子系统状态（L1 负向 + L2 正向）。 | | `/api/v1/guards/status` | `GET` | 综合安全子系统状态。 | | `/api/v1/metrics/latency` | `GET` | 每环和每插件的延迟百分位数 (P50/P95/P99)。 | | `/api/v1/metrics/ring-timeline` | `GET` | 近期请求追踪及每环执行分解。 | | `/api/v1/webhooks` | `GET` | 已配置的 Webhook 端点和事件类型。 | | `/api/v1/export/status` | `GET` | 导出子系统状态及近期文件。 | | `/api/v1/rbac/roles` | `GET` | RBAC 角色权限矩阵。 | ## 安全与身份 ### 字节级防火墙 (`core/firewall_asgi.py`) ASGI 中间件，扫描请求体字节以查找注入模式： - **模式匹配** 注入签名（11 种模式：`ignore previous instructions`, `bypass guardrails`, `reveal your system prompt` 等）。 - **即时 403 响应**：在请求到达 LLM 之前终止，避免产生成本。 - **局限性**：仅基于模式 —— 不能替代基于 ML 的注入检测。复杂的提示词注入可能绕过静态模式。 ### SecurityShield (`core/security.py`) 在请求链中预先连接于 INGRESS 之前的深度检查层： - **多轮轨迹检测**：跟踪每个会话的提示词评分历史，通过滑动窗口分析检测升级的越狱尝试。 - **注入评分**：基于正则的威胁评分，具有可配置阈值。 - **PII 检测与掩码**：双模式 —— Presidio NLP（可选，18 种实体类型）配合正则回退（email, phone, SSN, credit card, IBAN）。`mask_pii()` 将 PII 替换为保管库令牌；`demask_pii()` 恢复原始内容。 - **接入 `RotatorAgent.proxy_request()`**：在插件 INGRESS 环之前运行 —— 被拦截的请求返回 403 及诊断信息。 ### 身份与 SSO (`core/identity.py`) 无状态多提供商 OIDC/JWT 验证： - **提供商**：Google, Microsoft, Apple —— 通过知名 OIDC 发现自动配置。 - **JWKS 缓存**：密钥缓存 1 小时 TTL，轮换时自动刷新。 - **认证流程**：外部 OIDC JWT → 通过 JWKS 验证 → 交换为内部代理 JWT → 将 `IdentityContext` 附加到请求。 - **回退链**：JWT → API Key → Tailscale identity（通过 LocalAPI socket）。 - **无用户数据库**：身份完全源自加密令牌声明。 ### OAuth 前端 (`ui/services/auth.js`) 基于浏览器的 SSO 登录流程： - **弹窗式 OAuth**：点击提供商按钮 → 弹窗打开 OIDC 授权 URL → 从 URL 片段中提取 `id_token`。 - **回调处理器**：`oauth-callback.html` 通过 `postMessage` 将令牌中继到打开者窗口。 - **令牌交换**：`POST /api/v1/identity/exchange` 将外部 JWT 转换为内部代理会话令牌（存储在 `localStorage` 中）。 - **路由守卫**：如果启用了身份验证且不存在有效会话，则显示毛玻璃登录覆盖层。 - **API Key 回退**：用于无 SSO 环境的手动 API Key 输入。 ### RBAC (`core/r.py`) 具有细粒度权限的四种内置角色： | 角色 | 关键权限 | |------|----------------| | `admin` | 完全访问：proxy, registry, chat, logs, plugins, users, budget。 | | `operator` | Proxy 切换, registry 写入, plugins 管理, features 切换。 | | `user` | Proxy 使用, registry 读取, chat, logs 读取。 | | `viewer` | Registry 读取, logs 只读。 | - JWT claims → 通过 `config.yaml` (`role_mappings`) 进行角色映射。 - 角色持久化在 SQLite `user_roles` 表中。 - 每个 API Key 的预算配额强制执行。 ### 零信任 - **Tailscale LocalAPI**：通过 Unix socket (`whois` API) 验证机器/用户身份。 - **URL 注入防护**：所有用户提供的 IP/URL 均通过 `urllib.parse.quote()` 进行转义。 ## 插件引擎 **双模式** 环形架构 (`core/plugin_engine.py`)，包含 5 个处理阶段。支持传统原始函数和 `BasePlugin` 类实例并存 —— 零破坏性变更。 | 环 | 阶段 | 用途 | |------|-------|---------| | 1 | **Ingress** | 认证, 零信任, 全局速率限制 | | 2 | **Pre-Flight** | PII 掩码, 提示词变异, 预算守卫, 循环中断器, 缓存查找, 复杂度评分 | | 3 | **Routing** | 动态模型选择, 负载均衡, 优先级引导 | | 4 | **Post-Flight** | JSON 修复, 响应清洗, 质量门控, SLA 守卫 | | 5 | **Background** | FinOps 跟踪, 遥测导出, 影子流量 | ### 插件 SDK (`core/plugin_sdk.py`) 用于构建市场插件的官方 SDK： ``` from core.plugin_sdk import BasePlugin, PluginResponse, PluginHook from core.plugin_engine import PluginContext class MyPlugin(BasePlugin): name = "my_plugin" hook = PluginHook.PRE_FLIGHT version = "1.0.0" timeout_ms = 50 # Strict timeout enforcement async def execute(self, ctx: PluginContext) -> PluginResponse: # Your logic here return PluginResponse.passthrough() # or .block(), .modify(), .cache_hit() ``` **PluginResponse** 类型化契约： | 动作 | 效果 | |--------|--------| | `passthrough` | 让请求原样继续 | | `modify` | 变更请求体，继续流水线 | | `block` | 停止链路，向客户端返回错误（状态码 + 错误类型） | | `cache_hit` | 返回缓存响应，跳过路由 | ### 双模式执行 - **类插件**（`BasePlugin` 子类）：`execute(ctx) → PluginResponse`，带有 `on_load()` / `on_unload()` 生命周期钩子。 - **函数插件**（传统）：原始 `async def func(ctx)` —— 现有插件无需更改即可工作。 - **自动检测**：引擎检查入口点 —— 如果是继承自 `BasePlugin` 的类，则其实例化；否则视为原始函数。 ### 严格超时强制 每个插件均在 `asyncio.wait_for(timeout)` 下运行： - 通过 manifest 中的 `timeout_ms` 按插件配置（函数默认 500ms，类插件默认 50ms）。 - 超时会终止协程并记录警告。 - Ingress/Routing 超时是致命的（停止链路）。 ### 每插件指标 由引擎自动跟踪： - `invocations`, `errors`, `blocks`, `timeouts`, `total_latency_ms`, `avg_latency_ms`。 - 可通过 `PluginManager.get_plugin_stats(name)` 查询单个，或 `get_plugin_stats()` 查询所有。 ### 市场插件 所有市场插件均使用 `BasePlugin` SDK，并通过 `ui_schema` 实现动态 SOC UI 配置表单。 | 插件 | 环 | 默认 | 描述 | |--------|------|---------|-------------| | **Smart Budget Guard** | Pre-Flight | 启用 | 具有地面持久化和成本估算的按会话/团队预算强制。 | | **Agentic Loop Breaker** | Pre-Flight | 启用 | 通过带滑动窗口的 SHA-256 提示词哈希检测陷入重试循环的 AI 代理。 | | **Per-Model Rate Limiter** | Pre-Flight | 禁用 | 针对每个 (租户, 模型) 对的细粒度速率限制，使用滑动窗口计数器。 | | **Prompt Complexity Scorer** | Pre-Flight | 禁用 | 基于 4 个信号（深度、轮次、代码、指令）对提示词复杂度 (0-1) 评分，用于智能模型路由。 | | **Model Downgrader** | Pre-Flight | 禁用 | 针对简单提示词自动降级昂贵模型（节省 10-20 倍成本）。与 Complexity Scorer 协同工作。 | | **Context Window Guard** | Pre-Flight | 禁用 | 拦截超过目标模型上下文窗口的请求（返回清晰的 413 而非隐晦的上游 400）。 | | **Response Quality Gate** | Post-Flight | 禁用 | 检测空、拒绝、仅道歉以及被截断的 LLM 响应。 | | **Latency SLA Guard** | Post-Flight | 禁用 | 测量 TTFT 和总延迟及滚动百分位数，标记 SLA 违规（警告/违约）。 | | **Canary Detector** | Post-Flight | 禁用 | 检测响应中的系统提示词泄露（数据渗透防护）。可选自动拦截模式。 | | **Token Counter** | Background | 禁用 | 从 API 响应中提取真实 Token 计数，用实际数据修正预算启发式估算。 | 详见 [`plugins/marketplace/README.md`](plugins/marketplace/README.md) 获取完整插件开发指南。 ### 默认插件（传统函数） 9 个内置函数插件（向后兼容，始终启用）： - Ingress Auth & Zero-Trust, Context Minifier, PII Neural Masker, WAF-Aware Cache Lookup, Enterprise Neural Router, Speculative Kill-Switch, Post-Flight Sanitizer, JSON Auto-Healer, Unified Telemetry & FinOps. 详见 [`plugins/default/README.md`](plugins/default/README.md) 获取优先级映射和插件详情。 ### 安全扫描 所有 Python 插件在加载前均经过 **AST 扫描**： - 拦截：`os`, `subprocess`, `socket`, `ctypes`, `sys` 导入。 - 拦截：`exec()`, `eval()`, `__import__()`, `.system()`, `.popen()` 调用。 - 违规时抛出 `PluginSecurityError` —— 插件永远不会被加载。 ### 零停机热交换 (RCU) 1. 在所有现有 `BasePlugin` 实例上调用 `on_unload()`。 2. 快照当前环状态（回滚目标）。 3. 将新插件配置加载到新环中。 4. 在新 `BasePlugin` 实例上调用 `on_load()`。 5. 健康检查：通过所有环运行虚拟上下文。 6. 原子交换：替换活动环引用。 7. 任何失败时自动回滚。 ### WASM 插件支持 (`core/wasm_runner.py`) 通过 Extism SDK 执行编译为 WebAssembly 的 Rust/Go/C 插件： - **内存安全沙箱**：WASM 插件在隔离的 VM 中运行 —— 崩溃不会影响 Python 进程。 - **非阻塞执行**：所有 WASM 调用均通过 `asyncio.to_thread()` 运行，释放 GIL 并保持事件循环空闲。 - **JSON I/O 协议**：Input (`body`, `metadata`, `session_id`, `config`) → Output (`action`, `body`, `status_code`, `message`)。与 `PluginResponse` 契约对齐。 - **传统兼容**：将 WASM 动作 (`ALLOW`/`BLOCK`/`MODIFIED`) 映射到标准动作 (`passthrough`/`block`/`modify`)。 - **优雅回退**：如果未安装 Extism，WASM 插件将被静默跳过（无崩溃）。 - **同等保证**：超时强制、每插件指标和 fail_policy 对 WASM 插件的应用与 Python 插件完全一致。 详见 [`plugins/wasm/README.md`](plugins/wasm/README.md) 获取完整的 Rust 插件开发指南（Cargo.toml, lib.rs 模板, 构建说明）。 ### 市场 API 通过 REST API 安装、卸载、切换、热交换和回滚插件。插件 manifest 支持 `ui_schema` 以实现动态 UI 渲染、版本控制、作者元数据以及按插件 `config` 块。 ## 可观测性与导出 ### Prometheus 指标 (`/metrics`) | 指标 | 类型 | 描述 | |--------|------|-------------| | `llm_proxy_requests_total` | Counter | 按方法、端点、状态统计的总请求数。 | | `llm_proxy_request_errors_total` | Counter | 按错误类别统计的失败请求 (4xx/5xx)。 | | `llm_proxy_request_latency_seconds` | Histogram | 延迟，含 P50/P95/P99 桶 (10ms → 60s)。 | | `llm_proxy_streaming_ttft_seconds` | Histogram | 流式响应的首 Token 时间 (TTFT)。 | | `llm_proxy_token_usage_total` | Counter | 按端点和角色统计的 Token 使用量。 | | `llm_proxy_cost_total` | Counter | 按端点和模型估算的美元成本。 | | `llm_proxy_budget_consumed_usd` | Gauge | 当日预算消耗。 | | `llm_proxy_circuit_open` | Gauge | 每个端点的熔断器状态。 | | `llm_proxy_injection_blocked_total` | Counter | 被拦截的注入尝试。 | | `llm_proxy_auth_failures_total` | Counter | 按原因分类的认证失败。 | ### OpenTelemetry - **Traces**：通过 OTLP 进行分布式追踪，可选控制台导出器。 - **资源标签**：用于多实例识别的 `service.name`。 - **FastAPI 自动插桩**：所有路由自动追踪。 - **优雅降级**：如果未安装 `opentelemetry`，所有追踪函数变为空操作 —— 代理全速运行，无任何可观测性依赖。 ### Sentry 集成 - FastAPI + aiohttp 集成的异常跟踪。 - PII 过滤 (`send_default_pii=False`)。 - 事件采样（10% 事务，5% 性能分析）。 - 丢弃 HTTPException 事件以减少噪音。 ### 数据集导出 (`core/export.py`) - **异步 JSONL 写入器**，支持每日文件轮转。 - **PII 清洗**：自动编校 Emails, IPs, API keys, JWTs。 - **Gzip 压缩** 轮转时压缩。 - **可选 Parquet 转换** 通过 pyarrow 使用 zstd 压缩。 ### SQLite 复制（计划中） 基于 Litestream 的 WAL 模式 SQLite → S3 持续复制已在计划中，但尚未配置。 ### Webhooks (`core/webhooks.py`) - **Slack** (Block Kit), **Teams** (MessageCard), **Discord** (Embeds), **Generic** (JSON). - 7 种事件类型：`circuit_open`, `budget_threshold`, `injection_blocked`, `endpoint_down`, `endpoint_recovered`, `auth_failure`, `panic_activated`。 - 30 秒防抖以防止洪泛。 ## 前端 SOC 安全运营中心 UI —— 原生 JS SPA (`ui/`)，使用 Tailwind CSS, Chart.js, xterm.js。 ### 视图 | 视图 | 描述 | |------|-------------| | **Threats** | KPI 卡片, Chart.js 威胁时间线, SSE 安全事件流 | | **Guards** | 主代理开关、按守卫启用/禁用（注入、语言、链接净化器）及描述 | | **Plugins** | 基于环的安全插件流水线网格、热交换重载 | | **Endpoints** | LLM 端点注册表，含切换/删除操作 | | **Audit Log** | xterm.js 终端，WebGL 渲染，JSON 语法高亮，安全事件过滤 | | **Settings** | 身份与访问、速率限制配置、系统信息 | ### 交互 - **命令面板**：`Cmd+K` 支持跨所有视图的模糊搜索。 - **熔断开关**：侧边栏底部的紧急停止按钮。 - **网络心跳**：5s ping, LIVE/OFFLINE 状态指示器。 - **影院模式**：按 `F` 进入无干扰视图。 ## 配置 ### `config.yaml` 结构 ``` server: host: 0.0.0.0 port: 8090 tls: { enabled: true, min_version: "1.2" } auth: { enabled: true, api_keys_env: "LLM_PROXY_API_KEYS" } identity: enabled: false providers: - name: google client_id_env: "OIDC_GOOGLE_CLIENT_ID" - name: microsoft client_id_env: "OIDC_MICROSOFT_CLIENT_ID" role_mappings: {} session_ttl: 3600 rotation: strategy: "round_robin" # weighted, least_used, random failover: { enabled: true, max_retries: 3 } webhooks: enabled: false endpoints: - name: slack-ops target: slack url_env: "SLACK_WEBHOOK_URL" events: ["circuit_open", "budget_threshold", "panic_activated"] rate_limiting: enabled: true requests_per_minute: 60 observability: tracing: { enabled: true, service_name: "llmproxy" } sentry: { dsn_env: "SENTRY_DSN" } export: { enabled: false, output_dir: "exports", scrub_pii: true } budget: daily_limit: 50.0 soft_limit: 40.0 fallback_to_local_on_limit: true ``` ### 预算持久化 每日预算消耗通过 `app_state` 键值表持久化到 SQLite： - **启动时**：加载 `budget:daily_total` 和 `budget:daily_date` —— 新的一天自动重置。 - **每次请求时**：即发即弃 `asyncio.create_task(store.set_state(...))` —— 非阻塞，重启后依然存在。 - **插件级**：`SmartBudgetGuard 通过 `PluginState.extra["store"]` DI 持久化按会话和按团队的支出。 ### 密钥管理 所有敏感值均通过 **Infisical SDK** 加载，并带有环境变量回退： - `LLM_PROXY_API_KEYS` — 逗号分隔的 API Keys。 - `LLM_PROXY_MASTER_KEY` — 加密主密钥（用于静态密钥）。 - `LLM_PROXY_IDENTITY_SECRET` — 内部 JWT 签名密钥。 - `LLM_PROXY_FEDERATION_SECRET` — 联邦信任密钥。 - `OIDC_*_CLIENT_ID` — 按提供商的 OIDC 客户端 ID。 - `SENTRY_DSN` — Sentry 错误跟踪 DSN。 - `TELEGRAM_BOT_TOKEN` — Telegram ChatOps 机器人令牌。 - `SLACK_WEBHOOK_URL` / `DISCORD_WEBHOOK_URL` — Webhook URLs。 ## 测试 16 个模块共 449 个测试，全部通过。每个子系统的单元测试 + HTTP 级 E2E 集成测试。 ``` # 运行完整套件 (449 个测试) python -m pytest tests/ -v --ignore=tests/test_store.py --ignore=tests/integrated_test.py --ignore=tests/test_export.py # 运行特定模块 python -m pytest tests/test_marketplace_plugins.py -v # 仅运行 E2E 集成测试 python -m pytest tests/test_e2e.py -v ``` | 模块 | 测试数 | 覆盖范围 | |--------|-------|----------| | `test_e2e.py` | 34 | 完整 HTTP E2E：health, metrics, version, proxy toggle, priority, panic, features, registry CRUD, plugins, identity, chat (auth on/off), budget persistence, state persistence | | `test_marketplace_plugins.py` | 30 | Loop Breaker (7), Budget Guard (5), Engine dual-mode (5), Fail policy (2), AST blocking (5), Validation (4), DI State (2) | | `test_marketplace_new_plugins.py` | 24 | Prompt Complexity Scorer (7), Response Quality Gate (9), Latency SLA Guard (8) | | `test_marketplace_plugins_v2.py` | 31 | Token Counter (5), Model Downgrader (5), Canary Detector (7), Model Rate Limiter (6), Context Window Guard (8) | | `test_cache.py` | 27 | CacheBackend (12), StreamFaker (4), CacheCheck plugin (4), NegativeCache (7) | | `test_wasm_runner.py` | 15 | JSON protocol, legacy action mapping, error handling, engine integration | | `test_plugin_engine.py` | 8 | AST scan (safe/forbidden: os/subprocess/exec/eval), allowed modules | | `test_openapi_contracts.py` | 18 | OpenAPI schema validation, route presence, response shapes | | `test_pii_detection.py` | 17 | Presidio NLP + regex PII detection, masking, vault, demasking | | `test_rate_limiter.py` | 8 | Token bucket, per-key isolation, auto-eviction | | `test_identity.py` | 7 | OIDC verify, proxy JWT gen/verify/expire, role mapping | | `test_rbac.py` | 7 | Admin/user/viewer permissions, multi-role, quota, user CRUD | | `test_webhooks.py` | 6 | Slack/Teams/Discord/Generic format, severity mapping | ### E2E 测试架构 E2E 套件 (`test_e2e.py`) 使用 `LightweightAgent`，针对 `InMemoryRepository` 挂载 **真实路由模块** (`proxy/routes/`)，而无需导入完整的 `RotatorAgent` 或其 20 多个传递依赖（OpenTelemetry, Sentry, ChromaDB 等）。这实现了亚秒级执行且无需外部服务的真实 HTTP 级覆盖。 ## 安装与部署 ### 快速开始 ``` # 克隆 git clone https://github.com/fabriziosalmi/llmproxy cd llmproxy # 安装依赖 pip install -r requirements.txt # 复制 env 模板并配置 cp .env.example .env # 运行 python main.py # UI 可访问 http://localhost:8090/ui # API 可访问 http://localhost:8090/v1/chat/completions # 指标位于 http://localhost:8090/metrics ``` ### Docker Compose ``` # 复制 env 模板 cp .env.example .env # 使用您的 API keys 和 secrets 编辑 .env # 启动 docker compose up -d # 日志 docker compose logs -f llmproxy # 健康检查 curl http://localhost:8090/health ``` `docker-compose.yml` 包含： - 健康检查（30s 间隔，3 次重试，15s 启动期）。 - 卷挂载：`llmproxy-data` 用于持久化，`config.yaml` 和 `plugins/` 只读。 - 资源限制：2GB 内存限制，512MB 预留。 - 端口：8090 (API) + 9091 (Prometheus)。 ### CI/CD (GitHub Actions) **`.github/workflows/ci.yml`** — 每次推送/PR 时运行： - **Lint**：ruff check（Python 代码质量）。 - **Test**：pytest 及插件/WASM 测试套件。 - **Syntax**：所有 Python 文件的 AST 解析。 **`.github/workflows/docker.yml`** — 版本标签 (`v*`) 触发运行： - 构建 Docker 镜像并推送到 GitHub Container Registry (GHCR)。 - 标签：semver (`1.0.0`), minor (`1.0`), 以及 commit SHA。 ### 可选依赖 ``` # NLP 驱动的 PII 检测 (Presidio) pip install presidio-analyzer presidio-anonymizer # Parquet 导出 pip install pyarrow # Sentry 集成 pip install sentry-sdk[fastapi] # WASM 插件支持 pip install extism ``` ## 许可证 详见 [LICENSE](LICENSE)。

标签：AI网关, API安全, ASGI, AV绕过, CISA项目, DevSecOps, DLL 劫持, DLL注入, DNS 反向解析, Extism, FastAPI, JSON输出, NLP, PII检测, Presidio, Python, Streamlit, WAF, WASM沙箱, WebAssembly, 上游代理, 反向代理, 大语言模型, 安全代理, 安全运营中心, 应用层防火墙, 开源安全工具, 插件引擎, 敏感信息过滤, 数据脱敏, 无后门, 注入攻击防御, 流量审计, 用户代理, 网络安全, 网络映射, 自定义请求头, 访问控制, 请求响应过滤, 请求拦截, 逆向工具, 逆向工程平台, 隐私保护