AegisGate

Category: Tools & Productivity | Uploader: ax128 | Downloads: 0 | Version: v1.0（Latest）

本技能文档给 Agent 直接使用，目标是：在一台新机器上完成 AegisGate 的安装、启动、注册 token 或配置直连上游、以及客户端接入配置。

Changelog: Source: GitHub https://github.com/ax128/AegisGate

Directory Structure

Current level: Root

📁 .github/
- 📁 workflows/
  - 📄 ci.yml 747 B
📁 aegisgate/
- 📁 adapters/
  - 📁 openai_compat/
    
    📄 __init__.py 15 B
    
    📄 mapper.py 6.5 KB
    
    📄 router.py 199.2 KB
    
    📄 sanitize.py 13.2 KB
    
    📄 stream_utils.py 7.5 KB
    
    📄 upstream.py 9.0 KB
  - 📁 relay_compat/
    
    📄 __init__.py 15 B
    
    📄 mapper.py 567 B
    
    📄 router.py 2.9 KB
  - 📁 v2_proxy/
    
    📄 __init__.py 38 B
    
    📄 router.py 36.5 KB
  - 📄 __init__.py 15 B
- 📁 config/
  - 📄 __init__.py 15 B
  - 📄 feature_flags.py 1.9 KB
  - 📄 redact_values.py 3.7 KB
  - 📄 security_level.py 2.2 KB
  - 📄 security_rules.py 30.9 KB
  - 📄 settings.py 6.4 KB
- 📁 core/
  - 📄 __init__.py 15 B
  - 📄 audit.py 2.4 KB
  - 📄 confirmation.py 3.4 KB
  - 📄 confirmation_cache_task.py 1.9 KB
  - 📄 confirmation_flow.py 4.8 KB
  - 📄 context.py 1.2 KB
  - 📄 errors.py 286 B
  - 📄 gateway.py 34.3 KB
  - 📄 gateway_auth.py 5.9 KB
  - 📄 gateway_keys.py 5.8 KB
  - 📄 gateway_network.py 3.3 KB
  - 📄 gateway_ui_config.py 14.4 KB
  - 📄 gateway_ui_routes.py 31.5 KB
  - 📄 gw_tokens.py 8.2 KB
  - 📄 hot_reload.py 9.7 KB
  - 📄 models.py 676 B
  - 📄 pipeline.py 3.1 KB
  - 📄 registry.py 997 B
  - 📄 security_boundary.py 3.6 KB
  - 📄 semantic.py 16.2 KB
  - 📄 tfidf_model.py 3.9 KB
- 📁 filters/
  - 📄 __init__.py 15 B
  - 📄 anomaly_detector.py 12.2 KB
  - 📄 base.py 680 B
  - 📄 exact_value_redaction.py 1.6 KB
  - 📄 injection_detector.py 22.5 KB
  - 📄 output_sanitizer.py 137 B
  - 📄 post_restore_guard.py 4.1 KB
  - 📄 privilege_guard.py 5.4 KB
  - 📄 rag_poison_guard.py 11.1 KB
  - 📄 redaction.py 9.4 KB
  - 📄 request_sanitizer.py 10.5 KB
  - 📄 restoration.py 6.5 KB
  - 📄 sanitizer.py 10.8 KB
  - 📄 system_prompt_guard.py 2.2 KB
  - 📄 tool_call_guard.py 8.1 KB
  - 📄 untrusted_content_guard.py 4.7 KB
- 📁 models/
  - 📁 tfidf/
    
    📄 classifier.joblib 62.0 KB
    
    📄 vectorizer.joblib 103.7 KB
- 📁 observability/
  - 📄 __init__.py 903 B
  - 📄 logging.py 2.4 KB
  - 📄 metrics.py 4.8 KB
  - 📄 tracing.py 4.0 KB
- 📁 policies/
  - 📁 rules/
    
    📄 default.yaml 377 B
    
    📄 permissive.yaml 202 B
    
    📄 security_filters.yaml 35.3 KB
    
    📄 strict.yaml 265 B
  - 📄 __init__.py 15 B
  - 📄 policy_engine.py 5.4 KB
- 📁 storage/
  - 📄 __init__.py 728 B
  - 📄 crypto.py 3.5 KB
  - 📄 kv.py 572 B
  - 📄 postgres_store.py 18.9 KB
  - 📄 redis_store.py 14.8 KB
  - 📄 sqlite_store.py 17.4 KB
- 📁 tests/
  - 📄 __init__.py 15 B
  - 📄 conftest.py 2.0 KB
  - 📄 test_confirmation.py 1.7 KB
  - 📄 test_confirmation_routing.py 45.8 KB
  - 📄 test_disposition_controls.py 6.2 KB
  - 📄 test_gateway_boundary_access.py 8.0 KB
  - 📄 test_gateway_register.py 15.7 KB
  - 📄 test_generic_provider_proxy.py 8.5 KB
  - 📄 test_gw_token_rewrite_middleware.py 4.9 KB
  - 📄 test_gw_tokens.py 4.0 KB
  - 📄 test_init_config.py 4.5 KB
  - 📄 test_injection.py 2.2 KB
  - 📄 test_injection_advanced_rules.py 3.4 KB
  - 📄 test_local_ui.py 8.3 KB
  - 📄 test_logger.py 783 B
  - 📄 test_long_context_limits.py 10.7 KB
  - 📄 test_mapping_concurrency.py 1.8 KB
  - 📄 test_openai_error_paths.py 3.4 KB
  - 📄 test_pending_confirmation_store.py 5.5 KB
  - 📄 test_pipeline.py 1.7 KB
  - 📄 test_poison_traceback_audit.py 910 B
  - 📄 test_policy_engine.py 1.9 KB
  - 📄 test_post_restore_guard.py 1.6 KB
  - 📄 test_privilege.py 1.5 KB
  - 📄 test_rag_poison_guard.py 3.0 KB
  - 📄 test_redaction.py 6.1 KB
  - 📄 test_redaction_whitelist_util.py 1.0 KB
  - 📄 test_request_logging.py 4.8 KB
  - 📄 test_response_metadata.py 526 B
  - 📄 test_restoration.py 819 B
  - 📄 test_restoration_guard.py 1.9 KB
  - 📄 test_restoration_policy.py 1.6 KB
  - 📄 test_risk_models.py 2.9 KB
  - 📄 test_sanitize_hit_fragments.py 4.1 KB
  - 📄 test_sanitizer_bilingual.py 1.8 KB
  - 📄 test_security_boundary.py 1.5 KB
  - 📄 test_security_level.py 1.1 KB
  - 📄 test_security_rules.py 807 B
  - 📄 test_semantic_module.py 3.0 KB
  - 📄 test_semantic_service_client.py 2.4 KB
  - 📄 test_streaming_router.py 29.3 KB
  - 📄 test_system_prompt_guard.py 1.1 KB
  - 📄 test_tool_call_guard.py 2.8 KB
  - 📄 test_untrusted_content_guard.py 1.9 KB
  - 📄 test_untrusted_source_matrix.py 988 B
  - 📄 test_upstream_routing.py 4.7 KB
  - 📄 test_v2_proxy_router.py 29.5 KB
- 📁 util/
  - 📄 __init__.py 15 B
  - 📄 base64_detect.py 957 B
  - 📄 debug_excerpt.py 1.9 KB
  - 📄 logger.py 5.1 KB
  - 📄 masking.py 872 B
  - 📄 redaction_whitelist.py 2.7 KB
  - 📄 risk_scoring.py 1.3 KB
- 📄 __init__.py 74 B
- 📄 init_config.py 8.9 KB
📁 config/
- 📄 .env.example 3.4 KB
- 📄 README.md 4.3 KB
- 📄 security_filters.yaml 35.3 KB
📁 logs/
- 📄 .gitkeep 0 B
📁 scripts/
- 📄 caddy-entrypoint.sh 806 B
- 📄 local_launcher.py 15.8 KB
- 📄 openclaw-inject-proxy-fetch.py 42.8 KB
- 📄 redeploy.sh 1.3 KB
- 📄 train_tfidf.py 12.5 KB
📁 www/
- 📁 assets/
  - 📄 app.css 26.2 KB
  - 📄 app.js 40.2 KB
  - 📄 login.js 970 B
- 📄 index.html 31.5 KB
- 📄 login.html 2.3 KB
📄 .dockerignore 66 B
📄 .gitignore 873 B
📄 aegisgate-local.py 121 B
📄 AICLIENT2API-QUICKSTART.md 5.3 KB
📄 Caddyfile.example 3.0 KB
📄 CHANGELOG.md 11.6 KB
📄 CLIPROXY-QUICKSTART.md 3.9 KB
📄 docker-compose.aiclient2api.yml 2.7 KB
📄 docker-compose.cliproxy.yml 2.4 KB
📄 docker-compose.sub2api.yml 5.9 KB
📄 docker-compose.yml 1.4 KB
📄 Dockerfile 1.1 KB
📄 LICENSE 1.1 KB
📄 OPENCLAW_INJECT_PROXY_FETCH.md 4.5 KB
📄 OTHER_TERMINAL_CLIENTS_USAGE.md 5.0 KB
📄 pyproject.toml 1.2 KB
📄 README.md 32.8 KB
📄 SKILL.md 7.1 KB
📄 SUB2API-QUICKSTART.md 4.6 KB
📄 WEBUI-QUICKSTART.md 2.9 KB

SKILL.md

# AegisGate Agent Skill

本技能文档给 Agent 直接使用，目标是：在一台新机器上完成 AegisGate 的安装、启动、注册 token 或配置直连上游、以及客户端接入配置。

## 0) 先读项目要点（必须）

- AegisGate 是 LLM 安全网关：请求侧脱敏/清洗，响应侧检测/阻断/确认放行；`responses` 结构化 `input`（含 function/tool 输出）也会在转发上游前做脱敏。
- **两种路由模式**（可同时启用）：
  - **Token 路由**（推荐多租户场景）：每个 token 绑定独立的上游地址和网关密钥。
    - v1（LLM）：`http://<host>:18080/v1/__gw__/t/<TOKEN>/...`
    - v2（通用 HTTP 代理）：`http://<host>:18080/v2/__gw__/t/<TOKEN>`，须携带 `x-target-url: <完整目标URL>` 请求头
  - **直连上游**（单用户/Agent 快速接入）：设置 `AEGIS_UPSTREAM_BASE_URL=<上游地址>` 后，直接请求 `/v1/...` 或 `/v2/...`，无需注册 token。
- **脱敏豁免字段（whitelist_key）**：注册 token 时可指定逗号分隔的字段名列表（如 `api_key,secret,token`）。请求体中这些字段的值**不做 PII 脱敏**，直接透传到上游。适用于需要原始凭证通过的场景。支持以下匹配模式：
  - JSON：`"field":"value"` 或 `"field": "value"`
  - 等号赋值：`field=value`
  - 冒号赋值：`field:value`
  - URL 查询参数：`?field=value`
- 管理接口（`/__gw__/register|lookup|unregister|add|remove`）应只允许内网/管理机访问。

## 1) 环境检查

```bash
uname -a
cat /etc/os-release
which docker || true
which docker-compose || true
git --version || true
python3 --version || true
```

## 2) 如果没有 Docker：先安装 Docker（Ubuntu/Debian）

```bash
sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo $VERSION_CODENAME) stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo systemctl enable --now docker
docker --version
docker compose version
```

可选（免 sudo）：

```bash
sudo usermod -aG docker "$USER"
newgrp docker
```

## 3) 获取源码（Git 或源码包）

### 3.1 Git 方式

```bash
git clone https://github.com/ax128/AegisGate.git
cd AegisGate
```

### 3.2 已有源码目录

```bash
cd /path/to/AegisGate
```

## 4) 推荐安装方式：Docker 一键启动

```bash
docker compose up -d --build
docker compose ps
docker compose logs -f aegisgate
```

健康检查：

```bash
curl -sS http://127.0.0.1:18080/health
```

## 5) 可选安装方式：源码本地运行（无 Docker）

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
python -m pip install -e .
uvicorn aegisgate.core.gateway:app --host 127.0.0.1 --port 18080
```

## 6) 接入方式选择

### 6.1 Token 路由（多租户，推荐）

注册上游并生成 token：

```bash
# 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://your-upstream.example.com/v1","gateway_key":"<AEGIS_GATEWAY_KEY>"}'
```

期望返回：

```json
{
  "token": "Ab3k9Qx7Yp",
  "baseUrl": "http://127.0.0.1:18080/v1/__gw__/t/Ab3k9Qx7Yp"
}
```

注册时可附带脱敏豁免字段（如 `api_key` 字段值不做脱敏）：

```bash
curl -X POST http://127.0.0.1:18080/__gw__/register \
  -H "Content-Type: application/json" \
  -d '{"upstream_base":"https://your-upstream.example.com/v1","gateway_key":"<AEGIS_GATEWAY_KEY>","whitelist_key":"api_key,secret"}'
```

### 6.2 直连上游（单用户/Agent 快速接入）

在 `config/.env` 中设置：

```env
AEGIS_UPSTREAM_BASE_URL=https://your-upstream.example.com/v1
```

重启后直接请求 `/v1/...`，无需注册 token：

```bash
curl -X POST http://127.0.0.1:18080/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <UPSTREAM_API_KEY>" \
  -d '{"model":"gpt-4.1-mini","input":"hello"}'
```

## 7) 验证调用

### Token 路由

```bash
curl -X POST "http://127.0.0.1:18080/v1/__gw__/t/<TOKEN>/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <UPSTREAM_API_KEY>" \
  -d '{"model":"gpt-4.1-mini","input":"hello"}'
```

### 直连上游

```bash
curl -X POST "http://127.0.0.1:18080/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <UPSTREAM_API_KEY>" \
  -d '{"model":"gpt-4.1-mini","input":"hello"}'
```

## 8) 客户端配置模板（Agent/CLI）

### Token 路由

```yaml
provider: openai_compatible
base_url: http://127.0.0.1:18080/v1/__gw__/t/<TOKEN>
api_key: <UPSTREAM_API_KEY>
model: gpt-4.1-mini
```

### 直连上游

```yaml
provider: openai_compatible
base_url: http://127.0.0.1:18080/v1
api_key: <UPSTREAM_API_KEY>
model: gpt-4.1-mini
```

说明：
- 若客户端默认流式输出，网关会处理 `[DONE]` 断流恢复。
- 直连模式下不需要 `base_url` 携带 token 路径段。

## 9) 常用管理命令

查看 token：

```bash
curl -X POST http://127.0.0.1:18080/__gw__/lookup \
  -H "Content-Type: application/json" \
  -d '{"token":"<TOKEN>"}'
```

删除 token：

```bash
curl -X POST http://127.0.0.1:18080/__gw__/unregister \
  -H "Content-Type: application/json" \
  -d '{"token":"<TOKEN>"}'
```

查看所有 token（需要网关密钥）：

```bash
curl http://127.0.0.1:18080/__ui__/api/tokens \
  -H "X-Gateway-Key: <AEGIS_GATEWAY_KEY>"
```

查看日志：

```bash
docker compose logs -f aegisgate
```

重启：

```bash
docker compose restart aegisgate
```

升级：

```bash
git pull
docker compose up -d --build
```

## 10) 故障排查顺序（Agent 执行顺序）

1. `health` 是否正常（`curl http://127.0.0.1:18080/health`）。
2. 确认使用哪种路由模式：token 路由（路径含 `/v1/__gw__/t/<TOKEN>/...`）或直连上游（`AEGIS_UPSTREAM_BASE_URL` 是否已设置）。
3. Token 路由：token 是否存在（`/__gw__/lookup`）；上游地址与 API key 是否正确。
4. 直连模式：`.env` 中 `AEGIS_UPSTREAM_BASE_URL` 是否正确，是否已重启。
5. 看 `docker compose logs -f aegisgate` 是否有 `upstream` 错误、确认放行、阻断原因。
6. 若遇到高风险确认（`AEGIS_REQUIRE_CONFIRMATION_ON_BLOCK=true`），用户必须发送完整指令：
   - `yes cfm-<id>--act-<token>` 或 `no cfm-<id>--act-<token>`

## 11) 安全基线（必须遵守）

- 对外仅暴露业务入口，管理接口仅限内网。
- 默认监听建议使用 `127.0.0.1`，通过反向代理做外部暴露控制。
- 不在日志或工单中明文粘贴密钥、token、cookie、私钥、助记词。
- 生产环境定期轮换 `config/aegis_gateway.key`（替换文件内容后重启服务）。
- `whitelist_key` 字段只填真正需要豁免脱敏的字段名，最小化敏感数据明文透传范围。

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

AegisGate

Directory Structure

SKILL.md

Report

Notice