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, RTKCaveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550 contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRouteOmniRoute 是一个统一接入 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”的单线模型相比当前版本有两处关键演进引入鉴权管道Authz pipeline路由先被确定性分类为PUBLIC/CLIENT_API/MANAGEMENT三类再执行策略评估与强制enforce分类不可判定的请求一律回退为MANAGEMENTfail-closed详见 AUTHZ_GUIDE.md。引入 Guardrails 框架PII 脱敏与提示注入检测被收纳进统一、可热重载、可注册自定义插件的守卫注册表而非散落各处的中间件详见 GUARDRAILS.md。防线末端还追加了Cooldown冷却与 Model Lockout模型锁定两道弹性机制与熔断器配合防止故障蔓延详见 RESILIENCE_GUIDE.md。二、认证与授权四类凭证、一套管道能力实现方式Dashboard 登录密码认证 JWT 令牌HttpOnly CookieAPI Key 认证HMAC 签名密钥 CRC 校验OAuth 2.0 PKCE面向 Claude、Codex、Gemini、Cursor 等提供方的浏览器/设备 OAuth支持 PKCE 时启用Devin 导入型凭证单独处理Token 刷新到期前自动刷新 OAuth 令牌安全 CookieHTTPS 环境设置AUTH_COOKIE_SECUREtrue鉴权管道路由分类PUBLIC / CLIENT_API / MANAGEMENT见 AUTHZ_GUIDE.md路由守卫分级管理路由三级模型LOCAL_ONLY / ALWAYS_PROTECTED / MANAGEMENT见 ROUTE_GUARD_TIERS.mdMCP 作用域32 个细粒度作用域read:health、write:combos、execute:completions等见 MCP-SERVER.md两种认证模式模式一API KeyBearer用于 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_tokenJWT 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/内置守卫按优先级排序守卫优先级阶段用途vision-bridge5preCall为不支持视觉的模型桥接图像理解对图片 URL 做 SSRF 防护audio-bridge6preCall音频模态桥接video-bridge7preCall视频帧/字幕模态桥接与溯源pii-masker10pre post调用前后 PII 脱敏邮箱、电话、CPF、CNPJ、信用卡、SSNprompt-injection20preCall检测 override / 角色劫持 / 越狱 / 泄露类注入模式credential-masker95pre post凭据掩码避免日志泄露密钥注册机制与运行语义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。模式库与严重性模式类型严重性示例System OverrideHighignore all previous instructionsRole HijackMediumyou are now DAN, you can do anythingDelimiter InjectionHigh编码分隔符以打破上下文边界[SYSTEM]、|im_start|等DAN/JailbreakMedium已知越狱提示模式Instruction LeakHighshow me your system promptEncoding EvasionMediumbase64/rot13/hex 解码 指令关键词在 src/shared/utils/inputSanitizer.ts 中可以看到这六类模式的正则实现例如system_override匹配ignore|disregard|forget … previous/prior/above/earlier … instructions/prompts/rules/contextsystem_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 KBMAX_INJECTION_SCAN_BYTES因为注入指令通常位于提示词顶部扫描整段粘贴代码 / RAG 上下文只会浪费 CPU 与 GC。配置方式可在仪表盘Settings → Security或.env中配置INPUT_SANITIZER_ENABLEDtrue INPUT_SANITIZER_MODEblock # warn | block注入策略遗留的 redact 不再剥离注入文本 INPUT_SANITIZER_BLOCK_THRESHOLDhigh # high默认 | medium | low —— block 模式下等于/高于该级别的会被拦截模式解析链promptInjection.tsoptions.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 类型匹配模式替换占位符邮箱userdomain.com[EMAIL_REDACTED]CPF巴西123.456.789-00[CPF_REDACTED]CNPJ巴西12.345.678/0001-00[CNPJ_REDACTED]信用卡4111-1111-1111-1111[CC_REDACTED]电话55 11 99999-9999[PHONE_REDACTED]SSN美国123-45-6789[SSN_REDACTED]PII_REDACTION_ENABLEDtrue # 请求 PII 改写独立于 INPUT_SANITIZER_MODE PII_RESPONSE_SANITIZATIONtrue # 可选对返回给客户端的提供方响应中的 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 过滤、限流与指纹伪装能力说明CORS显式跨域白名单CORS_ALLOWED_ORIGINS兼容遗留的CORS_ORIGIN默认*IP 过滤仪表盘中配置 IP 段白名单/黑名单限流按提供方的速率限制 自动退避Anti-Thundering Herd防惊群互斥锁 每连接锁定防止级联 502TLS 指纹浏览器相似 TLS 指纹伪装以降低机器人检测见 STEALTH_GUIDE.md含法律/伦理提示CLI 指纹按提供方匹配原生 CLI 签名的请求头/请求体排序八、弹性与可用性熔断、幂等与退避能力说明熔断器每提供方三态Closed → Open → Half-OpenSQLite 持久化状态请求幂等5 秒去重窗口拦截重复请求指数退避自动重试延迟递增健康面板提供方健康状态实时监控熔断器实现位于 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()避免一次用户断连级联成整个提供方的冷却/黑名单。九、合规与审计留痕、豁免与输入校验能力说明日志保留按CALL_LOG_RETENTION_DAYS自动清理默认 7 天见 src/lib/logEnv.tsNo-Log 豁免按 API 密钥的noLog标志关闭请求日志审计日志管理操作记录到audit_log表详见 COMPLIANCE.mdMCP 审计基于 SQLite 记录所有 MCP 工具调用Zod 校验所有 API 输入在模块加载时以 Zod v4 schema 校验十、必需环境变量缺失即快速失败所有密钥必须在启动服务器前配置好。服务器在缺失或密钥过弱时快速失败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_SECUREtrue。十二、依赖与供应链安全定期执行npm auditnpm run audit:deps覆盖主包 electron保持依赖更新项目使用huskylint-staged做提交前检查lint-staged check-docs-sync check:any-budget:t11CI 每次推送都运行 ESLint 安全规则no-eval、no-implied-eval、no-new-func均为 error提供方常量在模块加载时通过 Zod 校验src/shared/validation/schemas.ts旧路径 providerSchema.ts优先选用安全默认库dompurify/isomorphic-dompurify防 XSS、joseJWT、better-sqlite3参数化查询无 SQL 注入风险、bcryptjs密码哈希。供应链扫描器告警的官方说明发布版omniroutenpm 产物捆绑了 Next.jsoutput: standalone构建每个路由处理器包括 MITM、Zed 导入、Cloud Sync、嵌入式服务监督等特权功能都会进入.next/server/*.js压缩分块因此启发式供应链扫描器Socket.dev / Snyk 等常将分块匹配为恶意软件特征。仓库的处理方式扫描器配置见根目录 socket.ymlSocket.dev GitHub App v2 格式显式排除不随包发布的目录tests/、docs/等只报告真正触达用户的代码路径每个发现类别都有维护者逐条证明见 SOCKET_DEV_FINDINGS.md源文件 ↔ 被标记分块 ↔ 行为 ↔ 缓解措施源码中以SECURITY-AUDITOR-NOTE:注释回指同一文档若下游流水线无法放行告警可用OMNIROUTE_BUILD_PROFILEminimal npm run build构建将四个敏感模块替换为运行时返回 HTTP 503feature-disabled的桩使特权代码路径物理上从产物中消失。十三、硬性安全规则工具与评审共同强制绝不提交密钥—.env已 gitignore.env.example只作模板仅注释不含字面量见 PUBLIC_CREDS.md绝不使用eval()、new Function()或隐含 eval— ESLint 强制未经操作员明确批准绝不绕过 Husky 钩子--no-verify、--no-gpg-sign路由中绝不写裸 SQL— 一律经由 src/lib/db/ 参数化访问始终用 Zod 校验输入— src/shared/validation/schemas.ts始终消毒上游请求头— 单一权威拒绝名单在 src/shared/constants/upstreamHeaders.ts凭据静态加密— AES-256-GCM实现见 src/lib/db/encryption.ts公开上游 OAuth 标识符经resolvePublicCred()解析— 绝不在源码中硬编码AIza…/GOCSPX-…/…apps.googleusercontent.com字面量错误响应经buildErrorBody()/sanitizeErrorMessage()— 绝不在 HTTP / SSE / executor / MCP 响应体中暴露原始err.stack/err.message见 ERROR_SANITIZATION.mdexec()/spawn()运行时值经env选项传递— 绝不把外部路径或不可信值字符串插值进 shell 脚本参考 src/mitm/cert/install.ts 中的updateNssDatabases优先选用安全默认库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, RTKCaveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550 contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
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, RTKCaveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550 contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRouteOmniRoute 是一个统一接入 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”的单线模型相比当前版本有两处关键演进引入鉴权管道Authz pipeline路由先被确定性分类为PUBLIC/CLIENT_API/MANAGEMENT三类再执行策略评估与强制enforce分类不可判定的请求一律回退为MANAGEMENTfail-closed详见 AUTHZ_GUIDE.md。引入 Guardrails 框架PII 脱敏与提示注入检测被收纳进统一、可热重载、可注册自定义插件的守卫注册表而非散落各处的中间件详见 GUARDRAILS.md。防线末端还追加了Cooldown冷却与 Model Lockout模型锁定两道弹性机制与熔断器配合防止故障蔓延详见 RESILIENCE_GUIDE.md。二、认证与授权四类凭证、一套管道能力实现方式Dashboard 登录密码认证 JWT 令牌HttpOnly CookieAPI Key 认证HMAC 签名密钥 CRC 校验OAuth 2.0 PKCE面向 Claude、Codex、Gemini、Cursor 等提供方的浏览器/设备 OAuth支持 PKCE 时启用Devin 导入型凭证单独处理Token 刷新到期前自动刷新 OAuth 令牌安全 CookieHTTPS 环境设置AUTH_COOKIE_SECUREtrue鉴权管道路由分类PUBLIC / CLIENT_API / MANAGEMENT见 AUTHZ_GUIDE.md路由守卫分级管理路由三级模型LOCAL_ONLY / ALWAYS_PROTECTED / MANAGEMENT见 ROUTE_GUARD_TIERS.mdMCP 作用域32 个细粒度作用域read:health、write:combos、execute:completions等见 MCP-SERVER.md两种认证模式模式一API KeyBearer用于 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_tokenJWT 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/内置守卫按优先级排序守卫优先级阶段用途vision-bridge5preCall为不支持视觉的模型桥接图像理解对图片 URL 做 SSRF 防护audio-bridge6preCall音频模态桥接video-bridge7preCall视频帧/字幕模态桥接与溯源pii-masker10pre post调用前后 PII 脱敏邮箱、电话、CPF、CNPJ、信用卡、SSNprompt-injection20preCall检测 override / 角色劫持 / 越狱 / 泄露类注入模式credential-masker95pre post凭据掩码避免日志泄露密钥注册机制与运行语义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。模式库与严重性模式类型严重性示例System OverrideHighignore all previous instructionsRole HijackMediumyou are now DAN, you can do anythingDelimiter InjectionHigh编码分隔符以打破上下文边界[SYSTEM]、|im_start|等DAN/JailbreakMedium已知越狱提示模式Instruction LeakHighshow me your system promptEncoding EvasionMediumbase64/rot13/hex 解码 指令关键词在 src/shared/utils/inputSanitizer.ts 中可以看到这六类模式的正则实现例如system_override匹配ignore|disregard|forget … previous/prior/above/earlier … instructions/prompts/rules/contextsystem_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 KBMAX_INJECTION_SCAN_BYTES因为注入指令通常位于提示词顶部扫描整段粘贴代码 / RAG 上下文只会浪费 CPU 与 GC。配置方式可在仪表盘Settings → Security或.env中配置INPUT_SANITIZER_ENABLEDtrue INPUT_SANITIZER_MODEblock # warn | block注入策略遗留的 redact 不再剥离注入文本 INPUT_SANITIZER_BLOCK_THRESHOLDhigh # high默认 | medium | low —— block 模式下等于/高于该级别的会被拦截模式解析链promptInjection.tsoptions.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 类型匹配模式替换占位符邮箱userdomain.com[EMAIL_REDACTED]CPF巴西123.456.789-00[CPF_REDACTED]CNPJ巴西12.345.678/0001-00[CNPJ_REDACTED]信用卡4111-1111-1111-1111[CC_REDACTED]电话55 11 99999-9999[PHONE_REDACTED]SSN美国123-45-6789[SSN_REDACTED]PII_REDACTION_ENABLEDtrue # 请求 PII 改写独立于 INPUT_SANITIZER_MODE PII_RESPONSE_SANITIZATIONtrue # 可选对返回给客户端的提供方响应中的 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 过滤、限流与指纹伪装能力说明CORS显式跨域白名单CORS_ALLOWED_ORIGINS兼容遗留的CORS_ORIGIN默认*IP 过滤仪表盘中配置 IP 段白名单/黑名单限流按提供方的速率限制 自动退避Anti-Thundering Herd防惊群互斥锁 每连接锁定防止级联 502TLS 指纹浏览器相似 TLS 指纹伪装以降低机器人检测见 STEALTH_GUIDE.md含法律/伦理提示CLI 指纹按提供方匹配原生 CLI 签名的请求头/请求体排序八、弹性与可用性熔断、幂等与退避能力说明熔断器每提供方三态Closed → Open → Half-OpenSQLite 持久化状态请求幂等5 秒去重窗口拦截重复请求指数退避自动重试延迟递增健康面板提供方健康状态实时监控熔断器实现位于 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()避免一次用户断连级联成整个提供方的冷却/黑名单。九、合规与审计留痕、豁免与输入校验能力说明日志保留按CALL_LOG_RETENTION_DAYS自动清理默认 7 天见 src/lib/logEnv.tsNo-Log 豁免按 API 密钥的noLog标志关闭请求日志审计日志管理操作记录到audit_log表详见 COMPLIANCE.mdMCP 审计基于 SQLite 记录所有 MCP 工具调用Zod 校验所有 API 输入在模块加载时以 Zod v4 schema 校验十、必需环境变量缺失即快速失败所有密钥必须在启动服务器前配置好。服务器在缺失或密钥过弱时快速失败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_SECUREtrue。十二、依赖与供应链安全定期执行npm auditnpm run audit:deps覆盖主包 electron保持依赖更新项目使用huskylint-staged做提交前检查lint-staged check-docs-sync check:any-budget:t11CI 每次推送都运行 ESLint 安全规则no-eval、no-implied-eval、no-new-func均为 error提供方常量在模块加载时通过 Zod 校验src/shared/validation/schemas.ts旧路径 providerSchema.ts优先选用安全默认库dompurify/isomorphic-dompurify防 XSS、joseJWT、better-sqlite3参数化查询无 SQL 注入风险、bcryptjs密码哈希。供应链扫描器告警的官方说明发布版omniroutenpm 产物捆绑了 Next.jsoutput: standalone构建每个路由处理器包括 MITM、Zed 导入、Cloud Sync、嵌入式服务监督等特权功能都会进入.next/server/*.js压缩分块因此启发式供应链扫描器Socket.dev / Snyk 等常将分块匹配为恶意软件特征。仓库的处理方式扫描器配置见根目录 socket.ymlSocket.dev GitHub App v2 格式显式排除不随包发布的目录tests/、docs/等只报告真正触达用户的代码路径每个发现类别都有维护者逐条证明见 SOCKET_DEV_FINDINGS.md源文件 ↔ 被标记分块 ↔ 行为 ↔ 缓解措施源码中以SECURITY-AUDITOR-NOTE:注释回指同一文档若下游流水线无法放行告警可用OMNIROUTE_BUILD_PROFILEminimal npm run build构建将四个敏感模块替换为运行时返回 HTTP 503feature-disabled的桩使特权代码路径物理上从产物中消失。十三、硬性安全规则工具与评审共同强制绝不提交密钥—.env已 gitignore.env.example只作模板仅注释不含字面量见 PUBLIC_CREDS.md绝不使用eval()、new Function()或隐含 eval— ESLint 强制未经操作员明确批准绝不绕过 Husky 钩子--no-verify、--no-gpg-sign路由中绝不写裸 SQL— 一律经由 src/lib/db/ 参数化访问始终用 Zod 校验输入— src/shared/validation/schemas.ts始终消毒上游请求头— 单一权威拒绝名单在 src/shared/constants/upstreamHeaders.ts凭据静态加密— AES-256-GCM实现见 src/lib/db/encryption.ts公开上游 OAuth 标识符经resolvePublicCred()解析— 绝不在源码中硬编码AIza…/GOCSPX-…/…apps.googleusercontent.com字面量错误响应经buildErrorBody()/sanitizeErrorMessage()— 绝不在 HTTP / SSE / executor / MCP 响应体中暴露原始err.stack/err.message见 ERROR_SANITIZATION.mdexec()/spawn()运行时值经env选项传递— 绝不把外部路径或不可信值字符串插值进 shell 脚本参考 src/mitm/cert/install.ts 中的updateNssDatabases优先选用安全默认库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, RTKCaveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550 contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
