ax128/AegisGate
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/completionsPOST /v1/responsesPOST /v1/messages— Anthropic Messages 专用端点(完整安全管道);支持原样透传到 Anthropic 兼容上游,或通过 tokencompat模式自动转换为 OpenAI Responses 格式POST /v1/files、POST /v1/images/edits、POST /v1/images/variations— multipart 上传专用路由(注册在通用透传之前):表单字段参与脱敏,体积上限走AEGIS_MAX_MULTIPART_BODY_BYTES(60MB)而非AEGIS_MAX_REQUEST_BODY_BYTESPOST /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 后仍保持 Anthropictype/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、税号、德国 SteuernummerDE_STEUERNR、奥地利 SV-NummerAT_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 共用):
v1支持两种方式:默认上游直连(配置AEGIS_UPSTREAM_BASE_URL)或 token 路径/v1/__gw__/t/<token>/...v2必须走 token 路径:/v2/__gw__/t/<token>/...(避免非 token 的通用代理暴露)- token 路径会先被中间件重写到真实路由,并把 token 绑定信息注入请求上下文
- 安全边界中间件执行基础限制:请求体大小限制、可选 loopback-only、可选 HMAC/nonce 防重放
v1 链路(OpenAI 兼容):
- 请求侧过滤:
exact_value_redaction -> redaction -> system_prompt_guard -> untrusted_content_guard -> request_sanitizer -> rag_poison_guard - 转发到上游 LLM(chat/responses/generic 子路径)
- 响应侧过滤:
exact_value_redaction -> anomaly_detector -> injection_detector -> rag_poison_guard -> privilege_guard -> tool_call_guard -> restoration -> post_restore_guard -> output_sanitizer - 按风险处置:
allow / sanitize / block(危险片段自动遮挡/分割,不走确认流程) - 记录审计事件(含风险标签、处置原因、确认状态)
说明:
- 上述顺序表示默认流水线构造顺序;实际是否执行仍取决于策略
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 代理):
- 读取
x-target-url请求头获取原始目标 URL(必须是http://或https://完整 URL,含 query string) - 请求侧:仅做请求体脱敏(可选,默认开启),不做其他拦截
- 转发到目标 HTTP(S) 地址(
follow_redirects=false:不自动跟随 3xx 重定向,直接透传给客户端) - 响应侧:仅对响应正文做高危代码检测(HTTP 走私、响应拆分等嵌入式攻击特征)
- 非流式文本/JSON 命中时:保留原响应状态码与 JSON/文本结构,只替换危险片段,并在响应头输出
x-aegis-v2-response-sanitized、x-aegis-v2-response-rule-ids - 流式文本/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 命中后的处理方式(怎么处理)
allow:直接透传结果。sanitize:过滤器就地替换敏感/可疑片段(如危险标签/URI/命令/垃圾内容)后直接返回。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):渲染即发出请求,不需要点击。规则要求 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 keyreadonly_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)。
建议:
- LLM 主链路用
v1(具备完整安全过滤与审计)。 - 通用 HTTP 安检用
v2(命中即阻断,响应更直接)。 - 外部 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"}'
建议:
- 上游使用 v1 基路径,例如
AEGIS_UPSTREAM_BASE_URL=http://localhost:8317/v1。 - 该模式只适合 localhost / 内网来源;外部来源访问非 token
/v1/...会收到403 token_route_required。例外:若请求携带正确的x-aegis-proxy-token(值为config/aegis_proxy_token.key),则不再校验来源 IP——这是给前置反向代理用的互信通道,详见 §1.7 自定义 HTTP 头。 - 该模式仅适用于
v1;v2仍必须使用 token 路径,并额外配置AEGIS_V2_TARGET_ALLOWLIST。 - 多上游场景建议使用 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"]
}
说明:
- token 长度为 24 位纯字母数字(
a-zA-Z0-9,不含-_等符号),约 142 位熵。 v1必须是一对一:一个 token 对应一个upstream_baseURL(不支持upstream_base传 list)。v2可复用该 token,因为 v2 转发目标由x-target-url决定,不绑定upstream_base。whitelist_key可选,支持字符串/数组(集合语义去重)。命中这些字段名的键值片段会跳过请求体脱敏,例如bn_key=...、"bn_key": {...}、URL 参数?bn_key=...。字段名会被统一转小写,且必须匹配^[A-Za-z0-9_][A-Za-z0-9_.-]{0,63}$;不匹配的键会被静默丢弃,请以返回体中的whitelist_key为准核对实际生效值。- 所有管理端点(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 兼容上游。
配置步骤:
在
config/gw_tokens.json中注册 compat token(upstream_base可选,走端口路径时不需要):{ "tokens": { "claude-to-gpt": { "compat": "openai_chat" } } }在
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" } }放开 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 ...
说明:
- 过滤模式仅对当前请求生效,不改变 token 本身的注册状态。
- 端口路由同样支持:
/v1/__gw__/t/8317__redact/...、/v1/__gw__/t/8317__passthrough/...。 - 无效的模式名(如
__foo)会返回400 invalid_filter_mode。 - 客户端自带的
x-aegis-filter-modeHeader 会被剥离;如需切换模式,请使用 token URL 后缀。 - 审计日志会记录使用的过滤模式(
filter_mode:redact或filter_mode:passthrough安全标签)。 passthrough模式跳过所有安全过滤器,但仍保留最小协议兼容层:会剥离网关内部字段,并保留 Chat/Responses 的参数兼容转换,避免上游因请求格式不兼容返回400。- 安全提示:
passthrough模式跳过所有安全检查,建议仅在受信环境或调试场景使用。 - 公网提示:默认情况下,纯数字端口 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 对外网站访问接入建议:
- 可走
v1:/v1/__gw__/t/<TOKEN>/...(推荐,检查链路更完整)。 - 可走
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
- 启动态打开开关(两项均为启动时固定):
AEGIS_ENABLE_GATEWAY_FORWARD=true
AEGIS_TRUSTED_PROXY_IPS=127.0.0.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" }
}
}
}
- 客户端 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时,网关已知的全部域名一律 403forward_config_invalid(连续多次保存坏文件也不会放行),控制台在文件修好或删除前不会覆盖它;单条非法只影响该域名。重启也不会放行:上次成功加载的域名清单记在config/.gw_forwards.json.hosts(0600),文件能解析时也会拒绝其中列出的域名;删除规则文件表示不再转发,清单随之删除。 - 保留路径会被遮蔽:上游如果也用
/metrics、/health,这些路径不会到达上游;规则停用或非法时保留路径照常由网关响应。 - 控制台不在转发域名上提供:转发域名承载上游自己的页面与脚本,与控制台同源会让上游脚本读取 CSRF token、带会话 cookie 调管理接口或截获登录表单。任何命中的转发域名上
/__ui__*一律 403forward_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 是否持久化:
- 调
POST /__gw__/register注册 token。 - 确认宿主机出现
./config/gw_tokens.json。 - 执行
docker compose restart aegisgate。 - 用原 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 直接指定最终地址。