OmniRoute 安全架构指南：从漏洞报告到 AES-256-GCM 加密、Prompt 注入防护与 Docker 加固

OmniRoute 安全架构指南：从漏洞报告到 AES-256-GCM 加密、Prompt 注入防护与 Docker 加固

【免费下载链接】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 是一个免费开源的 MIT AI 网关，单端点聚合 352+ 提供商、1200+ 模型，并天然兼容 Claude Code、Codex、Cursor、OpenCode、Cline 与 Copilot 等主流客户端。由于网关位于你的 API 密钥、OAuth 令牌与上游提供商之间，它的安全性直接决定了你的凭证与流量安全。本文以 docs/i18n/gu/SECURITY.md 为核心骨架，结合仓库源码与官方英文安全策略（SECURITY.md），系统讲解 OmniRoute 的多层安全模型、加密实现、注入防护、合规能力以及生产环境的 Docker 加固实践。读完本文，你将掌握如何正确配置密钥、如何理解并调优注入防护与 PII 脱敏、如何按官方流程上报漏洞，并能在生产环境以安全默认值完成部署。

1. 漏洞报告与响应时间线

1.1 负责任披露流程

OmniRoute 的安全团队要求所有漏洞通过私有渠道上报，禁止在公开的 GitHub Issue 中披露细节（防止 0-day 被滥用）：

1. 不要在 GitHub 上公开创建 Issue；
2. 使用 GitHub Security Advisories 的 New Advisory 表单提交；
3. 提交内容需包含：漏洞描述（description）、复现步骤（reproduction steps）、潜在影响（potential impact）。

1.2 响应时间线（SLA）

官方安全策略中给出了三个阶段的响应目标：

1.3 受支持版本

说明：i18n 翻译版（docs/i18n/gu/SECURITY.md）中的版本表格可能滞后于根目录英文版（SECURITY.md），部署前请以仓库根目录的最新策略为准。

2. 多层安全架构总览

OmniRoute 采用**纵深防御（Defense in Depth）**策略，请求在到达上游 Provider 之前会依次经过多道防线。根目录英文版的安全策略给出了更贴近当前代码库的完整管线：

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

从源码结构看，这条管线对应仓库中的几大实现区域：

• CORS：由src/server/cors/origins.ts维护跨域来源白名单；
• 授权管线（Authz Pipeline）：路由被分类为 PUBLIC / CLIENT_API / MANAGEMENT 三类，管理路由再按 LOCAL_ONLY / ALWAYS_PROTECTED / MANAGEMENT 三档守卫，详见 docs/architecture/AUTHZ_GUIDE.md 与 docs/security/ROUTE_GUARD_TIERS.md；
• Guardrails 框架：注册表位于src/lib/guardrails/，可热加载，详见 docs/security/GUARDRAILS.md；
• 弹性层：Circuit Breaker、Cooldown、Model Lockout 的细节在 docs/architecture/RESILIENCE_GUIDE.md。

i18n 版文档中的简化示意同样成立，可作为理解入口：

Request → CORS → API Key Auth → Prompt Injection Guard → Input Sanitizer → Rate Limiter → Circuit Breaker → Provider

3. 认证与授权

与授权相关的关键实现与文档还包括：

• Authz Pipeline：路由分类（PUBLIC / CLIENT_API / MANAGEMENT）见 docs/architecture/AUTHZ_GUIDE.md；
• 路由守卫分级：管理路由的 3 档模型（LOCAL_ONLY / ALWAYS_PROTECTED / MANAGEMENT）见 docs/security/ROUTE_GUARD_TIERS.md；
• 管理作用域 MCP：远程/api/mcp/*访问需具备manage作用域的 API Key，/api/cli-tools/runtime/*保持严格回环访问；
• MCP Scopes：32 个细粒度作用域（如read:health、write:combos、execute:completions），完整列表见 docs/frameworks/MCP-SERVER.md。

4. 静态加密：AES-256-GCM 与 scrypt 密钥派生

4.1 加密范围与密文格式

OmniRoute 使用AES-256-GCM对 SQLite 中存储的敏感数据进行加密，密钥通过scrypt派生：

• 加密对象：API 密钥、访问令牌、刷新令牌、ID 令牌；
• 版本化密文格式：enc:v1:<iv>:<ciphertext>:<authTag>；
• Passthrough 模式：当未设置STORAGE_ENCRYPTION_KEY时，明文存储（仅建议本地开发使用）。

4.2 生成加密密钥

STORAGE_ENCRYPTION_KEY=$(openssl rand -hex 32)

4.3 源码级实现剖析

字段级加密的实现位于 src/lib/db/encryption.ts，关键细节如下：

• 算法常量：aes-256-gcm，IV 长度 16 字节，密钥长度 32 字节，GCM 认证标签固定为完整的 16 字节（AUTH_TAG_LENGTH = 16）。源码注释明确指出，向createDecipheriv传入authTagLength会提前拒绝截断的认证标签，从而封堵 GCM 标签截断伪造向量；
• 静态盐派生：主密钥使用固定盐"omniroute-field-encryption-v1"经scryptSync派生。v3.7.9 起弃用了旧的动态盐（对密钥取 sha256 前 16 字节），因为两条路径派生出的密钥不一致，会导致“一条路径加密、另一条路径解不开”的循环解密失败与 CPU 飙升问题；
• 兼容迁移：decrypt()先尝试静态盐主密钥，失败后再回退旧动态盐密钥；一旦用旧密钥解出，encryptConnectionFields()会把它自动重新加密为静态盐密文（migrateLegacyEncryptedString供启动迁移脚本使用），实现数据库的渐进式迁移；
• 密钥加载顺序：ensureSecretLoaded()依次尝试环境变量STORAGE_ENCRYPTION_KEY、<DATA_DIR>/.env、cwd/.env、~/.hermes/.env；
• 解密失败告警：当存储的凭据带enc:v1:前缀但解密结果为 null，说明STORAGE_ENCRYPTION_KEY被更改或未设置，代码会打上credentialDecryptFailed标记并输出恢复提示，避免以空 Bearer 向供应商发出必然 401 的请求。

4.4 密钥版本与轮换

.env.example 中补充了两个相关变量：

• STORAGE_ENCRYPTION_KEY_VERSION=v1：密钥版本标签，轮换STORAGE_ENCRYPTION_KEY时递增；
• 官方提示轮换密钥后旧密文将无法解密，必须保留旧密钥或对受影响账户重新认证。

5. Guardrails 框架与 Prompt 注入防护

5.1 Guardrails 注册表

OmniRoute 提供可热加载的 guardrails 注册表（src/lib/guardrails/），内置多个 guardrail 按优先级顺序执行。当前仓库（docs/security/GUARDRAILS.md）注册了六个：

关键设计原则：

• Fail-open（开放失败）：某个 guardrail 抛异常时，注册表记录错误并继续执行下一个，而不是阻断整个请求——阻断必须是显式决策（block: true），绝不是意外；
• 自定义 guardrail 通过registerGuardrail(new MyGuardrail())注册；
• 每个请求可通过x-omniroute-disabled-guardrails请求头按需跳过特定 guardrail（registry.ts同时兼容x-disabled-guardrails别名）。

5.2 Prompt 注入检测模式

注入防护是“尽力而为（best-effort）”的启发式中间件，官方明确声明：它不是完整的 prompt 注入防火墙，可能产生误报（良性的 persona/RPG 提示词）与漏报（leet speak、空格变体、非英文模式）。

5.3 配置项与阻断阈值

在block模式下，只有High级别的检测会被阻断；Medium 级别家族会被记录日志但不会被sanitizeRequest阻断。通过 Dashboard（Settings → Security）或.env配置：

INPUT_SANITIZER_ENABLED=true INPUT_SANITIZER_MODE=block # warn | block（注入策略；legacy "redact" 不会剥离注入文本） INPUT_SANITIZER_BLOCK_THRESHOLD=high # high（默认）| medium | low —— block 模式下达到/超过该级别即阻断

.env.example还给出了响应侧与旧别名的补充：

# 旧版别名（效果相同） INJECTION_GUARD_MODE=warn INJECTION_GUARD_BLOCK_THRESHOLD=high

5.4 中间件实现

注入守卫的中间件实现位于 src/middleware/promptInjectionGuard.ts：

• withInjectionGuard(handler, options)仅对 POST/PUT/PATCH 生效；
• 请求体被克隆解析后交给evaluatePromptInjection（委托给src/lib/guardrails/promptInjection.ts）；
• 命中阻断时返回 HTTP 400，错误类型为injection_detected，错误码SECURITY_001，并在响应中附上检测数量；
• 非阻断但被标记（flagged）的请求会在请求头写入X-Injection-Flagged与X-Injection-Detections，供下游处理器与日志使用；
• 已解析的请求体会作为第三参数透传给下游 handler，避免在热路径上重复克隆解析（issue #4041）。

6. PII 检测与脱敏

6.1 支持的 PII 类型

自动检测并可选脱敏个人身份信息（PII），内置模式与替换规则如下：

6.2 配置方式

PII_REDACTION_ENABLED=true # 请求侧 PII 重写；与 INPUT_SANITIZER_MODE 相互独立 PII_RESPONSE_SANITIZATION=true # 可选：对返回给客户端的 Provider 响应也做 PII 脱敏

.env.example补充了更多细节：

• PII_RESPONSE_SANITIZATION_MODE=redact：redact（掩盖 PII）|warn（仅记录）|block（丢弃响应）；
• PII_WINDOW_SIZE=200：流式 PII 检测的最小窗口大小（字节），默认 200；
• CREDENTIAL_REDACTION_ENABLED=false：可选的已知 API 密钥/令牌模式脱敏（OpenAI、Anthropic、GitHub、Slack 等），由src/lib/guardrails/credentialMasker.ts实现；
• 响应侧清理器位于src/lib/piiSanitizer.ts，请求侧与注入守卫共用src/middleware/promptInjectionGuard.ts。

7. 网络安全

7.1 CORS 配置

.env.example中的 CORS 段：

# Used by: src/server/cors/origins.ts — 设置 Access-Control-Allow-Origin # 反代后的同源 Dashboard 请求不需要 CORS，使用会话绑定的 CSRF 防护。 # 除非设置 CORS_ALLOW_ALL=true，否则不会发送通配符。 CORS_ALLOWED_ORIGINS=https://your-frontend.example.com CORS_ORIGIN=https://your-frontend.example.com # legacy 单来源别名 CORS_ALLOW_ALL=false

7.2 SSRF 防护

.env.example中与出站 URL 安全相关的变量：

• OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS=false（默认）——阻止 Provider URL 指向私有/内网（localhost、192.168.x.x 等），这是 LM Studio、Ollama、vLLM 等自托管 Provider 所需的开关；
• OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS=true（默认，本地优先）——允许本机/局域网地址，但仍阻止云元数据地址（169.254.169.254、metadata.google.internal）；
• 实现位于src/shared/network/outboundUrlGuard.ts。

8. 弹性与可用性

熔断、冷却（Cooldown）与模型锁定的完整设计见 docs/architecture/RESILIENCE_GUIDE.md。

9. 合规能力

合规细节可进一步查阅 docs/security/COMPLIANCE.md（审计日志与保留策略）。

10. 必填环境变量与快速失败

10.1 必填与推荐密钥

所有机密必须在启动服务器前设置完毕。若缺失或过弱，服务器将**快速失败（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。

10.2 .env 契约中的其他安全变量

.env.example 的安全段还包含：

• INITIAL_PASSWORD=CHANGEME：首次启动时设置初始 Dashboard 管理员密码，必须在首次使用前修改，之后可在 Dashboard → Settings → Security 更改；
• AUTH_COOKIE_SECURE=false：任何非 localhost 部署必须设为true；
• REQUIRE_API_KEY=false：多用户/公网部署建议设为true，要求所有/v1/*代理端点携带 API Key；
• ALLOW_API_KEY_REVEAL=false：共享实例上开启会在 Dashboard 展示明文 API Key，存在安全风险；
• MAX_BODY_SIZE_BYTES=10485760：最大请求体 10 MB，由src/shared/middleware/bodySizeGuard.ts实现；
• NO_LOG_API_KEY_IDS=key_abc123,key_def456：跳过请求日志的 API Key ID 列表（GDPR/合规）；
• OMNIROUTE_WS_BRIDGE_SECRET：内部 Codex Responses WebSocket 桥接共享密钥，生产环境必填，未设置则所有 WS 桥接请求被拒绝。

11. Docker 安全加固

11.1 生产实践清单

官方建议的生产环境 Docker 安全基线：

• 生产环境使用非 root 用户运行；
• 将机密挂载为只读卷；
• 绝不把.env文件复制进 Docker 镜像；
• 使用.dockerignore排除敏感文件；
• HTTPS 反向代理之后必须设置AUTH_COOKIE_SECURE=true。

11.2 推荐的 docker run 命令

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

要点解读：

• --read-only：容器根文件系统只读，配合只读挂载的机密，降低被写入恶意文件的攻击面；
• -v omniroute-data:/app/data：SQLite 数据库与日志持久化到命名卷，容器重建不丢数据；
• 三个密钥用$(openssl rand ...)在启动时即时生成，避免复用弱值。

更多容器化部署方式可参考 docs/guides/DOCKER_GUIDE.md 与 docker-compose.yml。

12. 依赖安全与硬性安全规则

12.1 依赖管理

• 定期运行npm audit（官方脚本npm run audit:deps同时覆盖主包与 Electron）；
• 保持依赖更新；
• 项目使用husky+lint-staged做提交前检查（lint-staged + check-docs-sync + check:any-budget:t11）；
• CI 流水线在每次 push 时运行 ESLint 安全规则（no-eval、no-implied-eval、no-new-func为 error 级）；
• Provider 常量在模块加载时用 Zod 校验（src/shared/validation/schemas.ts）。

安全优先的默认库（avoid rolling your own）：

• dompurify/isomorphic-dompurify：XSS 防护；
• jose：JWT 处理；
• better-sqlite3：参数化查询，规避 SQL 注入；
• bcryptjs：密码哈希。

12.2 硬性安全规则（工具与评审强制）

官方在根目录 SECURITY.md 中明确了 11 条硬性规则，核心几条如下：

1. 绝不提交机密：.env被 gitignore；.env.example是模板，只允许注释，不出现字面值；
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. 上游 header 必须清洗：黑名单在src/shared/constants/upstreamHeaders.ts；
7. 静态加密凭据：AES-256-GCM，见 src/lib/db/encryption.ts；
8. 公开上游 OAuth 标识符走resolvePublicCred()：禁止在源码里内嵌AIza…/GOCSPX-…/…apps.googleusercontent.com字面值，详见 docs/security/PUBLIC_CREDS.md；
9. 错误响应走buildErrorBody()/sanitizeErrorMessage()：绝不在 HTTP / SSE / executor / MCP 响应体中输出原始err.stack/err.message，详见 docs/security/ERROR_SANITIZATION.md；
10. exec()/spawn()的运行时值通过env选项传入：绝不把外部路径或不可信值字符串插值进 shell 脚本（参考src/mitm/cert/install.ts::updateNssDatabases）。

13. 供应链扫描与最小化构建

根目录英文版 SECURITY.md 还记录了一个重要的供应链事实：发布的omniroutenpm 制品打包了 Next.jsoutput: "standalone"构建，因此包括 MITM、Zed 导入、Cloud Sync、嵌入式服务监督等特权功能在内的所有路由处理器都会进入.next/server/*.js压缩 chunk。启发式供应链扫描器（Socket.dev / Snyk 等）经常把这些 chunk 与恶意软件签名误匹配。

仓库的应对措施：

• 扫描器配置位于根目录 socket.yml（Socket.dev GitHub App 格式 v2），显式排除tests/、_tasks/、_references/、docs/等不随制品发布的目录，只报告实际到达用户的代码路径；
• 针对每类发现维护“维护者证明”（maintainer attestation）：见 docs/security/SOCKET_DEV_FINDINGS.md，并在每个被标记函数点内联SECURITY-AUDITOR-NOTE:注释；
• 对无法放宽告警的流水线，提供最小化构建：

OMNIROUTE_BUILD_PROFILE=minimal npm run build

该构建将四个敏感模块替换为运行时返回 HTTP 503feature-disabled的桩实现，使特权代码路径从产物中物理消失。完整发布配方见 docs/security/SOCKET_DEV_FINDINGS.md。

14. 延伸阅读

• 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 指纹（附法律/伦理说明）
• .env.example — 全部运行时环境变量契约
• src/lib/db/encryption.ts — 字段级 AES-256-GCM 加密实现
• src/middleware/promptInjectionGuard.ts — 注入守卫中间件

【免费下载链接】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