一个基于 Cloudflare Pingora 的反向代理,具备明确的资源限制、可预测的故障模式,并将安全逻辑置于崩溃隔离的 agent 中,专为想要安睡的操作者打造。
Zentinel 是一个基于 Cloudflare Pingora 构建的反向代理。 它提供有界资源、确定性超时,以及每条路由可显式选择的 fail-open 或 fail-closed 策略,并将解析密集或高风险的安全逻辑 (WAF、认证、策略)从数据平面移至外部 agent 中,因此有缺陷的 agent 无法连带拖垮代理。
在 zentinelproxy.io 上的基准测试中, Zentinel 在 10,000 req/s 下于五个代理(Zentinel、Envoy、HAProxy、Nginx、 Caddy)中拥有最低的 p99,并且一场 1 小时、1,000,000 次请求的浸泡测试以 99.95% 的成功率完成,未检测到内存泄漏。
核心部分(代理、路由、TLS、缓存、负载均衡)已可用于生产环境。 各 agent 独立进行版本管理;每个 agent 的状态见其 注册表页面。
curl -fsSL https://get.zentinelproxy.io | sh
将此保存为 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"
}
}
zentinel test -c zentinel.kdl # validate the config and exit
zentinel -c zentinel.kdl # run
system 块是必需的。更多示例见 config/examples/(API 网关、负载均衡、WebSocket、缓存、推理路由、ACME、命名空间等),或使用配置构建器以交互方式构建配置。
# Install script (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
# From crates.io (the crate is zentinel-proxy, the binary is zentinel).
# --locked builds with the tested dependency versions; without it a fresh
# resolve can pick tokio 1.54, which the current Pingora fork cannot run on (#624).
cargo install --locked zentinel-proxy
# Docker
docker run -p 8080:8080 -v $(pwd)/zentinel.kdl:/etc/zentinel/zentinel.kdl \
ghcr.io/zentinelproxy/zentinel -c /etc/zentinel/zentinel.kdl
在 systemd 主机上,安装脚本还会写入 /etc/systemd/system/zentinel.service、
一个 sysusers 片段以及位于 /etc/zentinel/zentinel.kdl 的初始配置。
启用并启动服务是可选的(--enable-service)。参见
crates/proxy/docs/deployment.md。
配置使用 KDL。zentinel test -c <file> 会解析并校验配置,
并拒绝未知的键,因此拼写错误会明确报错,而不是被忽略。
要代理到 HTTPS 后端? 请为上游添加一个 tls 块。否则,
无论端口是什么,Zentinel 都会使用明文 HTTP 连接。
upstreams {
upstream "backend" {
target "api.example.com:443"
tls {
sni "api.example.com"
}
}
}
完整参考文档:docs.zentinelproxy.io。
| 功能 | 作用 |
|---|---|
| 服务类型 | web、api、static、builtin 和 inference(LLM/AI)路由 |
| 负载均衡 | 14 种算法,包括轮询、加权、最少连接、一致性哈希、Maglev、Peak EWMA 和最少排队令牌数 |
| 安全 | TLS 和 mTLS、按 SNI 的证书、ACME、速率限制、GeoIP 过滤、解压缩(zip 炸弹)限制 |
| 智能体协议 | MCP 和 A2A 感知:按方法和按工具的允许/拒绝,从 JSON-RPC 请求体中解析 |
| 智能体 | 通过智能体协议 v2(UDS 或 gRPC)为 WAF、认证和自定义逻辑提供外部处理器,崩溃隔离,支持任意语言 |
| HTTP 缓存 | 基于 Pingora 的响应缓存,具备缓存击穿防护,支持内存、磁盘或混合后端 |
| WebSocket | RFC 6455 代理,支持逐帧智能体检查 |
| 可观测性 | Prometheus 指标和结构化日志;使用 --features opentelemetry 构建时启用 OpenTelemetry 追踪(发布的二进制文件未包含该功能) |
| 热重载 | SIGHUP 在验证后重载路由、上游和智能体,采用原子交换;监听器变更需要重启 |
完整说明:zentinelproxy.io/features。
gpt-4*、claude-*)的模型路由,以及通过智能体进行提示注入和 PII 过滤。每种场景的示例配置:config/examples/。
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)仍属于智能体的工作。
┌────────┐ ┌──────────┐
│ Client │ │ Upstream │
└────┬───┘ └─────▲────┘
│ │
▼ │
╔═══════════ Zentinel (core, single binary) ══════════╤════╗
║ │ ║
║ Listener ─▶ Routing ─▶ Filter chain ─▶ Forward ────┘ ║
║ TLS, H2 priority rate-limit, LB, ║
║ + LRU cache, hooks retries ║
║ │ ║
╚══════════════════════════════╪═══════════════════════════╝
│ UDS / gRPC (agent protocol v2)
▼
╔═══════ External agents (separate processes) ═══════╗
║ WAF · Auth · Rate-limit · … ║
║ crash-isolated, any language ║
╚════════════════════════════════════════════════════╝
响应会沿过滤器链回溯到客户端;访问日志和指标在完成时发出。数据平面是单个二进制文件。推理过程见 MANIFESTO.md,各阶段细节见 crates/proxy/docs/architecture.md。