OmniRoute 安全策略全解：从多层安全架构到生产加固实战

OmniRoute 安全策略全解：从多层安全架构到生产加固实战

【免费下载链接】OmniRouteNever stop coding. Free MIT AI gateway: one endpoint, 352 providers (150+ free), 1200+ models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline & Copilot. Quota-aware auto-fallback, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550+ contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute

OmniRoute 是一个统一接入 352+ 提供方、1200+ 模型的免费 MIT AI 网关，其安全模型贯穿「认证鉴权、静态加密、提示注入防护、PII 脱敏、网络边界、弹性容错、合规审计」七大层面。本篇以仓库 SECURITY.md 为骨架，结合 加密实现、Guardrails 框架、鉴权管道 等源码级证据，为你系统讲解 OmniRoute 的安全架构、环境变量配置、Docker 加固与供应链安全实践。读完你将掌握：如何正确初始化密钥、如何配置注入拦截与 PII 脱敏、如何理解熔断与幂等机制，以及如何用一套可审计的规则守住一个多租户 AI 网关的边界。

说明：本仓库为多语言文档仓库，阿塞拜疆语版 SECURITY.md 与各语言版本内容一致，本文以根目录 SECURITY.md（含最新 v3.8 增量内容）为权威主体，文中所有版本、路径与环境变量均以当前仓库实际内容为准。

一、安全模型总览：请求生命周期的七层防线

OmniRoute 采用多层安全模型，一次 LLM 请求从进入网关到转发上游，依次穿过以下防线：

Request → CORS → Authz pipeline (classify → policies → enforce) → Guardrails (PII masker, prompt injection, vision bridge) → Rate Limiter → Circuit Breaker → Cooldown → Model Lockout → Provider

与旧版“CORS → API Key Auth → Prompt Injection Guard → Input Sanitizer → Rate Limiter → Circuit Breaker → Provider”的单线模型相比，当前版本有两处关键演进：

1. 引入鉴权管道（Authz pipeline）：路由先被确定性分类为PUBLIC/CLIENT_API/MANAGEMENT三类，再执行策略评估与强制（enforce），分类不可判定的请求一律回退为MANAGEMENT（fail-closed），详见 AUTHZ_GUIDE.md。
2. 引入 Guardrails 框架：PII 脱敏与提示注入检测被收纳进统一、可热重载、可注册自定义插件的守卫注册表，而非散落各处的中间件，详见 GUARDRAILS.md。

防线末端还追加了Cooldown（冷却）与 Model Lockout（模型锁定）两道弹性机制，与熔断器配合防止故障蔓延（详见 RESILIENCE_GUIDE.md）。

二、认证与授权：四类凭证、一套管道

两种认证模式

模式一：API Key（Bearer），用于 OpenAI / Anthropic / Gemini 兼容的客户端 API，以及部分要求manage作用域的管理路由：

Authorization: Bearer <api-key>

由src/sse/services/auth.ts中的isValidApiKey()/extractApiKey()校验，并经 src/shared/utils/apiAuth.ts 重新导出；校验器同时接受OMNIROUTE_API_KEY/ROUTER_API_KEY环境变量作为持久透传密钥。

模式二：Dashboard 会话（auth_token Cookie），用于仪表盘页面与管理操作：

Cookie: auth_token=<JWT signed with JWT_SECRET>

由src/shared/utils/apiAuth.ts中的isDashboardSessionAuthenticated()验证；JWT 生命周期 30 天，剩余不足 7 天时管道会自动续签。部分管理路由同时接受 Cookie 或携带manage/admin作用域的Bearer密钥，这就是 v3.8 起“可通过 API 配置管理操作”的机制基础。

关于 API 密钥本身，其管理逻辑集中在 src/lib/db/apiKeys.ts，支持noLog（日志豁免）、isBanned（封禁）、allowedModels/allowedCombos（模型与组合白名单）、accessSchedule（访问时间窗）、rateLimits（速率限制）等一系列按密钥粒度控制的策略字段。

三、静态加密：AES-256-GCM + scrypt 派生

所有存入 SQLite 的敏感数据（API 密钥、访问令牌、刷新令牌、ID 令牌）使用AES-256-GCM加密，密钥由scrypt派生：

• 版本化密文格式：enc:v1:<iv>:<ciphertext>:<authTag>
• 未设置STORAGE_ENCRYPTION_KEY时进入透传模式（明文存储，仅用于开发便利）

# 生成加密密钥： STORAGE_ENCRYPTION_KEY=$(openssl rand -hex 32)

源码级细节：字段级加解密与旧密钥迁移

src/lib/db/encryption.ts 实现了字段级加解密：

• encrypt()使用scryptSync(secret, "omniroute-field-encryption-v1", 32)派生主密钥（静态盐），随机 16 字节 IV，并输出完整 16 字节 GCM 认证标签（AUTH_TAG_LENGTH = 16），从根上封堵 GCM 标签截断伪造向量；
• decrypt()先尝试静态盐主密钥，失败则回退到旧版动态盐密钥（sha256(secret).slice(0,16)）以兼容历史数据，并在下一次encrypt()时自动迁移回主密钥格式；
• 对连接对象，encryptConnectionFields()/decryptConnectionFields()批量处理apiKey、accessToken、refreshToken、idToken四个字段；
• 若字段仍带enc:v1:前缀却解密失败，说明STORAGE_ENCRYPTION_KEY被更改或丢失，代码会置位credentialDecryptFailed并给出恢复提示（重新认证该账号，或确认密钥与存储时一致）；
• ensureSecretLoaded()的密钥装载优先级为：环境变量 → 数据目录.env→ 当前工作目录.env→~/.hermes/.env。

实践要点：STORAGE_ENCRYPTION_KEY一旦启用就不要随意更换——更换后历史密文将无法解密，只会得到如上所述的明确报错而非静默的“空凭据 401”。

四、Guardrails 框架：热重载的守卫注册表

OmniRoute 内置一个可热重载的守卫注册表（源码目录 src/lib/guardrails/），内置守卫按优先级排序：

注册机制与运行语义（registry.ts）：

• 自定义守卫通过registerGuardrail(new MyGuardrail())注册，同名守卫会覆盖旧实例，注册后按priority升序执行（数值小者先跑）；
• 模型为fail-open：某个守卫抛异常不会阻断流量，block: true必须是显式决策；
• 支持按请求粒度豁免：请求头x-omniroute-disabled-guardrails（兼容别名x-disabled-guardrails），或在 API 密钥、请求体disabledGuardrails、metadata.disabledGuardrails中声明，四者取并集去重。

五、提示注入防护：启发式守卫与严重性分级

OmniRoute 的提示注入防护是尽力而为的启发式中间件，官方文档明确声明：它不是完整的提示注入防火墙，可能对良性的 persona/RPG 提示产生误报（false positive），也可能漏掉 leetspeak、空格式变体、非英语模式（false negative）。

模式库与严重性

在 src/shared/utils/inputSanitizer.ts 中可以看到这六类模式的正则实现：例如system_override匹配ignore|disregard|forget … previous/prior/above/earlier … instructions/prompts/rules/context；system_prompt_leak要求出现system|initial|hidden|original限定词再加prompt|instructions，避免旧版正则把“show the instructions”这类正常编码流量误判为 High 级泄露。extractMessageContents()同时兼容 OpenAI/Claude 的messages[]与 Responses API 的input[]结构，并覆盖system、prompt、instructions、query、documents等字段。

阈值与热路径优化

只有High严重性检测才会在block模式下被拦截；Medium 家族仅记录日志、绝不阻断请求（injectionSeverity.ts 中shouldBlockDetections默认阈值high）。为保证热路径性能，正则扫描被截断到请求体前16 KB（MAX_INJECTION_SCAN_BYTES），因为注入指令通常位于提示词顶部，扫描整段粘贴代码 / RAG 上下文只会浪费 CPU 与 GC。

配置方式

可在仪表盘（Settings → Security）或.env中配置：

INPUT_SANITIZER_ENABLED=true INPUT_SANITIZER_MODE=block # warn | block（注入策略；遗留的 "redact" 不再剥离注入文本） INPUT_SANITIZER_BLOCK_THRESHOLD=high # high（默认） | medium | low —— block 模式下等于/高于该级别的会被拦截

模式解析链（promptInjection.ts）：options.mode→ 数据库 Feature FlagINJECTION_GUARD_MODE→ 环境变量INJECTION_GUARD_MODE→INPUT_SANITIZER_MODE→ 默认"warn"；即 DB 覆盖 > ENV > 默认值，且 DB 读取失败时安全回退到环境变量行为。另外INPUT_SANITIZER_ENABLED默认开启（opt-out），解析支持true/1/yes/on与false/0/no/off。

六、PII 脱敏：请求改写与响应净化双通道

自动检测并可选脱敏个人身份信息：

PII_REDACTION_ENABLED=true # 请求 PII 改写；独立于 INPUT_SANITIZER_MODE PII_RESPONSE_SANITIZATION=true # 可选：对返回给客户端的提供方响应中的 PII 进行脱敏

实现上，pii-masker守卫（src/lib/guardrails/piiMasker.ts）的preCall/postCall复用 inputSanitizer.ts 中的processPII()：PII_REDACTION_ENABLED由 DB Feature Flag 驱动（DB > env > 默认），并在字符串、数组、嵌套对象（text/content字段）中递归改写。需要注意：请求 PII 改写仅受PII_REDACTION_ENABLED控制，与INPUT_SANITIZER_MODE（只负责注入拦截策略）相互独立。

七、网络安全：CORS、IP 过滤、限流与指纹伪装

八、弹性与可用性：熔断、幂等与退避

熔断器实现位于 src/shared/utils/circuitBreaker.ts，实际是CLOSED → DEGRADED → OPEN → HALF_OPEN → CLOSED的扩展状态机：失败率升高先进入 DEGRADED 告警而不立即熔断，OPEN 后短路请求，HALF_OPEN 允许有限探测请求以验证恢复；重开→探测→再开循环会让重置超时自适应递增。状态经 src/lib/db/domainState.ts 持久化到 SQLite，进程重启后仍可恢复。简化版自适应熔断逻辑见 src/lib/resilience/adaptiveCircuit.ts（默认失败阈值 3 次、冷却 60 秒）。

重要实现细节：本地流生命周期错误（如客户端中途 Abort、Codex WebSocket→SSE 桥的Controller is already closed）不会被计为提供方故障（isLocalStreamLifecycleError()），避免一次用户断连级联成整个提供方的冷却/黑名单。

九、合规与审计：留痕、豁免与输入校验

十、必需环境变量：缺失即快速失败

所有密钥必须在启动服务器前配置好。服务器在缺失或密钥过弱时快速失败（fail fast）：

# REQUIRED — 缺失则服务器无法启动： JWT_SECRET=$(openssl rand -base64 48) # 最短 32 字符 API_KEY_SECRET=$(openssl rand -hex 32) # 最短 16 字符 # RECOMMENDED — 启用静态加密： STORAGE_ENCRYPTION_KEY=$(openssl rand -hex 32)

服务器会主动拒绝changeme、secret、password等已知弱值。在登录路由 src/app/api/auth/login/route.ts 中可见其强制行为：JWT_SECRET未设置时直接输出[SECURITY] FATAL并禁用登录认证，绝不使用硬编码兜底密钥。

十一、Docker 生产加固

docker run -d \ --name omniroute \ --restart unless-stopped \ --read-only \ -p 20128:20128 \ -v omniroute-data:/app/data \ -e JWT_SECRET="$(openssl rand -base64 48)" \ -e API_KEY_SECRET="$(openssl rand -hex 32)" \ -e STORAGE_ENCRYPTION_KEY="$(openssl rand -hex 32)" \ diegosouzapw/omniroute:latest

生产部署守则：

• 使用非 root 用户运行；
• 密钥以只读卷挂载（--read-only配合数据卷-v omniroute-data:/app/data）；
• 绝不把.env文件复制进 Docker 镜像；
• 使用.dockerignore排除敏感文件；
• 位于 HTTPS 反向代理之后时设置AUTH_COOKIE_SECURE=true。

十二、依赖与供应链安全

• 定期执行npm audit（npm run audit:deps覆盖主包 + electron）；
• 保持依赖更新；
• 项目使用husky+lint-staged做提交前检查（lint-staged + check-docs-sync + check:any-budget:t11）；
• CI 每次推送都运行 ESLint 安全规则（no-eval、no-implied-eval、no-new-func均为 error）；
• 提供方常量在模块加载时通过 Zod 校验（src/shared/validation/schemas.ts，旧路径 providerSchema.ts）；
• 优先选用安全默认库：dompurify/isomorphic-dompurify（防 XSS）、jose（JWT）、better-sqlite3（参数化查询，无 SQL 注入风险）、bcryptjs（密码哈希）。

供应链扫描器告警的官方说明

发布版omniroutenpm 产物捆绑了 Next.jsoutput: "standalone"构建，每个路由处理器（包括 MITM、Zed 导入、Cloud Sync、嵌入式服务监督等特权功能）都会进入.next/server/*.js压缩分块，因此启发式供应链扫描器（Socket.dev / Snyk 等）常将分块匹配为恶意软件特征。仓库的处理方式：

• 扫描器配置见根目录 socket.yml（Socket.dev GitHub App v2 格式），显式排除不随包发布的目录（tests/、docs/等），只报告真正触达用户的代码路径；
• 每个发现类别都有维护者逐条证明，见 SOCKET_DEV_FINDINGS.md（源文件 ↔ 被标记分块 ↔ 行为 ↔ 缓解措施）；源码中以SECURITY-AUDITOR-NOTE:注释回指同一文档；
• 若下游流水线无法放行告警，可用OMNIROUTE_BUILD_PROFILE=minimal npm run build构建：将四个敏感模块替换为运行时返回 HTTP 503feature-disabled的桩，使特权代码路径物理上从产物中消失。

十三、硬性安全规则（工具与评审共同强制）

1. 绝不提交密钥—.env已 gitignore；.env.example只作模板（仅注释，不含字面量），见 PUBLIC_CREDS.md；
2. 绝不使用eval()、new Function()或隐含 eval— ESLint 强制；
3. 未经操作员明确批准绝不绕过 Husky 钩子（--no-verify、--no-gpg-sign）；
4. 路由中绝不写裸 SQL— 一律经由 src/lib/db/ 参数化访问；
5. 始终用 Zod 校验输入— src/shared/validation/schemas.ts；
6. 始终消毒上游请求头— 单一权威拒绝名单在 src/shared/constants/upstreamHeaders.ts；
7. 凭据静态加密— AES-256-GCM，实现见 src/lib/db/encryption.ts；
8. 公开上游 OAuth 标识符经resolvePublicCred()解析— 绝不在源码中硬编码AIza…/GOCSPX-…/…apps.googleusercontent.com字面量；
9. 错误响应经buildErrorBody()/sanitizeErrorMessage()— 绝不在 HTTP / SSE / executor / MCP 响应体中暴露原始err.stack/err.message，见 ERROR_SANITIZATION.md；
10. exec()/spawn()运行时值经env选项传递— 绝不把外部路径或不可信值字符串插值进 shell 脚本，参考 src/mitm/cert/install.ts 中的updateNssDatabases；
11. 优先选用安全默认库（Helmet.js、DOMPurify、ssrf-req-filter、safe-regex、Google Tink 等），在自己造轮子之前先伸手去拿。

十四、安全相关文档地图

• docs/architecture/AUTHZ_GUIDE.md — 授权管道（分类 → 策略 → 强制）
• docs/security/GUARDRAILS.md — Guardrails 框架
• docs/security/COMPLIANCE.md — 审计日志与保留策略
• docs/security/PUBLIC_CREDS.md — 公开上游凭据的强制模式
• docs/security/ERROR_SANITIZATION.md — 错误响应的强制模式
• docs/security/SOCKET_DEV_FINDINGS.md — 供应链扫描器发现的维护者证明
• docs/architecture/RESILIENCE_GUIDE.md — 熔断器 + 冷却 + 锁定
• docs/security/STEALTH_GUIDE.md — TLS 指纹伪装（法律/伦理提示）
• docs/security/ROUTE_GUARD_TIERS.md — 管理路由三级守卫模型
• CLAUDE.md — 面向 AI Agent 的硬性规则

结语

OmniRoute 的安全体系不是一个单点开关，而是一条从「请求分类」开始、经「守卫改写/拦截」、到「熔断与冷却」收尾的完整管道，再以 fail-closed 的鉴权、字段级 AES-GCM 加密、快速失败的环境变量校验和可审计的硬性规则收口。无论是自托管接入 Claude Code、Codex、Cursor 还是 OpenCode，将本文的密钥初始化、Guardrails 配置、Docker 加固与供应链告警处置步骤逐一落地，就能把一个多提供方 AI 网关的暴露面压缩到可控范围。若你是需要设计类似网关安全模型的工程师，AUTHZ_GUIDE.md 与 GUARDRAILS.md 是继续深入的最佳起点。

【免费下载链接】OmniRouteNever stop coding. Free MIT AI gateway: one endpoint, 352 providers (150+ free), 1200+ models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline & Copilot. Quota-aware auto-fallback, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550+ contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute