kydehq/gateway

# KYDE Gateway — AI Agent 的行为防火墙 [](https://github.com/kydehq/gateway/actions/workflows/ci.yml)   没有人会把真正的责任交给一个无人信任的 agent。Agent 总是卡在每一步等待人类批准——因为一旦出了问题，没人能证明发生了什么。提供商的日志存在于他们自己的基础设施上，用他们自己的密钥签名：这相当于让嫌疑人来写警情报告。 KYDE Gateway 是一个易于植入的、兼容 OpenAI 的代理，它位于 agent 外部，直接部署在调用路径上。每一个动作都会被拦截，并记录到一个由 Ed25519 签名、通过哈希链接的账本中——它独立于任何模型提供商，任何 agent 都无法删除，即使是正在被调查的 agent 也不行。在记录的同时，它还能监控上游传输的内容：你的 prompt、trace 和修正，防止它们在不知不觉中成为别人的训练数据。 **防止不该发生的事情。证明发生过的事情。掌控你的 agent 产出的内容。** **两种启动方式 — 相同的安装，只需一个开关：** | | 作用 | 设置 | |---|---|---| | 🔍 **观察** (从这里开始) | 记录一切，但不拦截任何请求。零风险，零代码修改。第一周你就会知道：你的 agent 做了什么，哪些数据离开了你的网络，成本是多少。 | 一行命令：`export OPENAI_BASE_URL=http://localhost:4000/v1` — [快速开始](#quickstart-docker-compose) | | 🛡️ **强制执行** (准备就绪后) | 按照模式开启 DLP 拦截并设置 MCP 工具允许/拒绝 — 超出范围的请求在到达上游之前会收到 403 错误。 | [策略执行](docs/reference.md#policy-enforcement-dlp-prevention) | ## 它的功能 ``` Agent ──► your-proxy:4000/v1 ──► OpenAI/Anthropic/Gemini/Copilot/any LLM │ ▼ Behavioral Ledger (Postgres, JSONB) ┌─────────────────────────────────────────────┐ │ entry_id │ timestamp │ agent_id │ │ action │ model │ why (context) │ │ tool_calls │ prev_hash │ entry_hash │ │ signature (Ed25519) │ └─────────────────────────────────────────────┘ ``` 每条记录都： - **经过签名** 使用 Ed25519（可通过 PKCS#11 / HSM 实现硬件级信任根） - **哈希链接** — 篡改任何过去的记录会破坏所有后续的哈希 - **因果关联** — 在每次工具调用之前捕获推理上下文（*为什么*） 一个 gateway 实例可以同时代理**所有支持的提供商** — OpenAI、Anthropic、Gemini、Copilot 以及任何本地 LLM。上游会根据请求路径自动检测；auth header 原封不动地透传。完整路由表：[参考](docs/reference.md#multi-provider-routing)。 ## 快速开始 (Docker Compose) 该架构包含五个容器：LLM 代理、admin API、dashboard UI、regex DLP 引擎，以及用于账本的 Postgres。以下两种选项的最终效果相同 — 任选其一即可。 ### 选项 A — 运行已发布的镜像 (推荐) 从 GHCR 拉取最新的公共镜像；你的主机上不需要构建任何内容，仅发布 UI — 且仅限本地回环访问，开箱即具备生产级的安全姿态。 ``` git clone https://github.com/kydehq/gateway.git cd gateway cp .env.starter.example .env.starter # 编辑 .env.starter：设置 POSTGRES_PASSWORD（例如 `openssl rand -base64 32`） docker compose --env-file .env.starter \ -f docker-compose.yml -f docker-compose.prod.yml up -d ``` ### 选项 B — 从源码构建 从本仓库构建 gateway 和 UI 镜像，并额外将每个服务的端口直接发布到主机（gateway `8081`，admin API `8501`，DLP regex `8002`，Postgres 本地回环 `5432`）— 这对开发非常方便。 ``` git clone https://github.com/kydehq/gateway.git cd gateway docker compose up -d --build ``` ### 验证 (两个选项通用) ``` curl -fsS http://localhost:4000/health # LLM proxy curl -fsS -o /dev/null -w "%{http_code}\n" http://localhost:8080/ # admin UI → 200 docker compose ps # everything "healthy" ``` 所有服务应该在约 40 秒内变为健康状态。 ### 将你的 agent 指向它 只需一行命令 — gateway 会原封不动地转发你真实的 API key： ``` # OpenAI 风格的客户端（VS Code、Cursor、大多数 SDK） export OPENAI_BASE_URL=http://localhost:4000/v1 # Anthropic 风格的客户端（Claude Code、Claude SDK） export ANTHROPIC_BASE_URL=http://localhost:4000 ``` 你可以选择使用 `X-Agent-ID` header 为你的 agent 命名；如果不提供，gateway 将从 API key 哈希中派生出一个稳定的匿名 ID ([详情](docs/reference.md#agent-identity))。 ### 在账本中查看 打开 **http://localhost:8080/** — 首次启动时，UI 会引导你进入 `/setup` 创建管理员账户。运行一次你的 agent，刷新仪表板：请求已经在那里了，被通过哈希链接到了账本中，并附带了其因果上下文、工具调用、token 计数和 DLP 检查结果。 这就是一屏展示的全部核心卖点。接下来：TLS、备份、升级，以及可选的 neural-DLP / validator 服务，请参阅 [部署指南](docs/deployment.md)。 ## 版本 上面的快速启动运行的是 **starter** 版本 — 即本仓库的公共镜像： 具备哈希链接但未签名的账本，仅观察模式的 DLP。**enterprise** 版本 （`ghcr.io/kydehq/gateway-distribution/*`）增加了 Ed25519/TPM 审计签名和内联强制执行，且使用相同的 compose 文件 — 版本的切换仅仅是一个 env 文件开关。参见 [部署指南 §3](docs/deployment.md#3-the-two-knobs-edition-and-posture) 和 [企业版支持](docs/deployment.md#12-enterprise-support)。 ## 文档 | 指南 | 涵盖内容 | | --- | --- | | [部署指南](docs/deployment.md) | 安装和运行完整技术栈 — Docker Compose、版本、TLS、备份、升级 | | [参考](docs/reference.md) | 提供商路由、MCP 路由、`config.yaml`、CLI、agent 身份、账本格式 | | [用户手册](docs/user-manual.md) | 使用仪表板 — 角色、DLP 告警和策略、用户、设置 | | [构建镜像](docs/building-images.md) | 构建容器镜像以及 starter/enterprise 版本的区别 | | [CI](docs/ci.md) | CI 和发布流水线（公开和私有） | ## 开发 (pip install) 如果你想在代理本身上进行修改，或者将其嵌入到现有的 Python 环境中，你可以跳过容器： ``` pip install -e . # installs the `kyde` CLI kyde keygen # generate a signing keypair (~/.agent-ledger/) kyde serve --port 8000 # start the proxy ``` 这会运行纯粹的代理，而不包含 dashboard UI、DLP sidecar 或 Postgres 账本 — 请参阅 [部署指南 §8](docs/deployment.md#8-deployment-b--local-pip-install) 了解如何单独连接这些组件，以及 [CLI 参考](docs/reference.md#cli)。 ## 尚未实现的功能 - 针对行为流的语义异常检测 - 多 Agent 关联（在同一任务中链接不同 agent 的记录） - 基于账本状态的策略执行（感知历史的拦截/允许） - 分布式账本 / 外部验证 - 用于提取工具调用的流式重组（流式响应中的工具调用 会被捕获，但重构是不完整的）

标签：AI安全, Chat Copilot, LLMOps, 人工智能, 测试用例, 版权保护, 用户模式Hook绕过, 网关代理, 行为审计, 请求拦截, 逆向工具