Zentinel 是一款基于 Cloudflare Pingora 构建的高性能反向代理。它提供明确的限制、可预测的行为以及生产级默认配置，适用于运维人员需要安心入睡的环境。
性能： 在针对 Envoy、HAProxy、Nginx 和 Caddy 的基准测试中拥有最低的 p99 延迟。100 万请求浸泡测试成功率 99.95%，零内存泄漏。纯 Rust WAF 引擎处理干净流量达 912K req/s —— 比 C++ ModSecurity 参考实现快 30 倍。
生产就绪的核心（代理、路由、TLS、缓存、负载均衡）。各 Agent 独立版本化 —— WAF、Auth 和 AI Gateway 已稳定；其他处于 beta 或 alpha 阶段。各 Agent 状态见 zentinelproxy.io/agents。
┌────────┐ ┌──────────┐
│ Client │ │ Upstream │
└────┬───┘ └─────▲────┘
│ │
▼ │
╔═══════════ Zentinel (core, single binary) ══════════╤════╗
║ │ ║
║ Listener ─▶ Routing ─▶ Filter chain ─▶ Forward ────┘ ║
║ TLS, H2 priority rate-limit, LB, ║
║ + LRU cache, hooks retries ║
║ │ ║
╚══════════════════════════════╪═══════════════════════════╝
│ UDS / gRPC (v2 agent protocol)
▼
╔═══════ External agents (separate processes) ═══════╗
║ WAF · Auth · Rate-limit · … ║
║ crash-isolated, any language ║
╚════════════════════════════════════════════════════╝
响应沿过滤器链回溯至客户端。访问日志和指标在完成时发出。
数据平面以单个二进制文件运行。解析繁重或运维风险高的安全与策略逻辑位于 UDS 或 gRPC 之后的外部 Agent 中，因此有缺陷的 Agent 无法拖垮代理。推理过程见宣言，各阶段细节见 crates/proxy/docs/architecture.md。
# Install (binary only)
curl -fsSL https://get.zentinelproxy.io | sh
# Install and start as a systemd service (Linux, root or sudo)
curl -fsSL https://get.zentinelproxy.io | sh -s -- --enable-service
# Or via Cargo
cargo install zentinel-proxy
# Or via Docker
docker run -v $(pwd)/zentinel.kdl:/etc/zentinel/zentinel.kdl \
ghcr.io/zentinelproxy/zentinel --config /etc/zentinel/zentinel.kdl
在 systemd 主机上，安装脚本还会放置 /etc/systemd/system/zentinel.service、一个 sysusers 片段，以及位于 /etc/zentinel/zentinel.kdl 的初始配置。服务启用和启动通过 --enable-service 选择加入。见 crates/proxy/docs/deployment.md。
将其保存为 zentinel.kdl —— 它将 localhost:8080 代理到端口 8081 上的后端：
system {
worker-threads 0 // auto-detect CPU cores
}
listeners {
listener "http" {
address "0.0.0.0:8080"
protocol "http"
}
}
routes {
route "default" {
matches {
path-prefix "/"
}
upstream "backend"
}
}
upstreams {
upstream "backend" {
target "127.0.0.1:8081"
}
}
# Run
zentinel --config zentinel.kdl
# Validate config without starting
zentinel test --config zentinel.kdl
要代理到 HTTPS 后端？ 为 upstream 添加 tls 块：
upstreams {
upstream "backend" {
target "api.example.com:443"
tls {
sni "api.example.com"
}
}
}
没有 tls 块时，无论端口如何，Zentinel 都以明文 HTTP 连接。
更多示例：config/examples/ 涵盖 API 网关、负载均衡、WebSocket、缓存、推理路由等。或使用配置构建器交互式生成配置。
| 功能 | 描述 |
|---|---|
| 服务类型 | Web、API、Static、Builtin 和 Inference（LLM/AI） |
| 负载均衡 | 14 种算法：轮询、加权、最少连接、Maglev、Peak EWMA 等 |
| 安全 | TLS/mTLS、速率限制、GeoIP 过滤、WAF、zip 炸弹防护 |
| Agentic 协议 | 原生 MCP 和 A2A 感知 —— 按方法和按工具的允许/拒绝，从 JSON-RPC 正文解析，而非信任镜像头 |
| Agent 协议 | 用于 WAF、认证和自定义逻辑的外部 Agent —— 崩溃隔离，支持任意语言 |
| HTTP 缓存 | 基于 Pingora 的响应缓存，具备缓存击穿防护和 LRU 淘汰（内存、磁盘或混合后端） |
| WebSocket 代理 | 符合 RFC 6455，支持逐帧 Agent 检查和会话亲和性 |
| 可观测性 | Prometheus 指标、结构化日志、OpenTelemetry 追踪 |
| 热重载 | 通过 SIGHUP 实现零停机配置更新，带验证和原子交换（路由、upstream、Agent；监听器变更需重启） |
完整功能分解见 zentinelproxy.io/features。
gpt-4*、claude-*）的模型路由、提示注入检测，以及针对 OpenAI、Anthropic 和通用 LLM 提供商的 PII 过滤Mcp-Name 头无法声明一个工具而正文调用另一个各场景示例配置：config/examples/
现代代理会积累隐藏行为、无界复杂性和在压力下才暴露的运维风险。Zentinel 采取不同的方法：
目标是正确、平静且可信赖的基础设施。完整理念见 MANIFESTO.md。
Zentinel 原生理解 MCP（Model Context Protocol）和 A2A（Agent2Agent）。路由声明允许哪些方法和工具，代理通过读取 JSON-RPC 信封来强制执行：
route "mcp" {
matches { path-prefix "/mcp" }
upstream "mcp-server"
mcp {
tools {
allow "get_weather" "search_docs"
deny "execute_sql"
}
}
}
策略从正文解析，绝不从镜像头解析。 MCP 的 Streamable HTTP 传输将方法和工具名复制到 Mcp-Method 和 Mcp-Name，以便中间件无需解析 JSON 即可路由。基于这些头构建允许列表，就是构建一个允许一切的允许列表：
Mcp-Name: read_file ← what a header-based allowlist checks
{"method":"tools/call","params":{"name":"delete_everything"}}
↑ what the server actually executes
Zentinel 读取头仅用于确认其与正文一致，并拒绝自相矛盾的请求。声称协议版本早于 2026-07-28 的请求默认被拒绝，因为这些版本从未要求两者匹配 —— 没有该检查，攻击者可通过声称旧版本绕过验证。
A2A 未定义镜像头，因此其策略直接读取正文，没有可欺骗的内容。
这决定调用是否可以发起。其内容是否安全 —— 参数中的提示注入、载荷中的 PII —— 仍属于 Agent 的工作。
完整参考：Agentic 协议
Zentinel 的安全性和可扩展性存在于 Agent 中 —— 挂接到每个请求阶段的外部进程。Agent 与代理崩溃隔离、可独立部署，并可用任意语言编写。