zentinelproxy/zentinel
GitHub: zentinelproxy/zentinel
基于 Pingora 构建的安全优先反向代理，提供高性能流量代理、WAF 防护和 AI 推理网关能力。
Stars: 44 | Forks: 8
Zentinel
一个为守护自由网络而构建的安全优先反向代理。
让边缘端的运维安枕无忧。
文档 •
演练场 •
基准测试 •
讨论 •
贡献
Zentinel 是一个基于 [Cloudflare Pingora](https://github.com/cloudflare/pingora) 构建的高性能反向代理。它提供明确的限制、可预测的行为以及生产级的默认设置，专为需要安稳睡眠的运维人员而设计。
**性能：** 在与 Envoy、HAProxy、Nginx 和 Caddy 的[基准测试](https://zentinelproxy.io/benchmarks/)中拥有最低的 p99 延迟。100 万请求浸泡测试成功率 99.95%，零内存泄漏。纯 Rust WAF 引擎处理干净流量的速度为 912K req/s —— 比 C++ ModSecurity 参考实现快 30 倍。
## 状态
核心功能已达到生产就绪状态（代理、路由、TLS、缓存、负载均衡）。Agent 单独版本化 —— WAF、Auth 和 AI Gateway 已稳定；其他为 beta 或 alpha 版本。请参阅 [zentinelproxy.io/agents](https://zentinelproxy.io/agents/) 查看各 Agent 状态。
## 快速开始
```
# 安装
curl -fsSL https://get.zentinelproxy.io | sh
# 或通过 Cargo
cargo install zentinel-proxy
# 或通过 Docker
docker run -v $(pwd)/zentinel.kdl:/etc/zentinel/zentinel.kdl \
ghcr.io/zentinelproxy/zentinel --config /etc/zentinel/zentinel.kdl
```
将此保存为 `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 --config zentinel.kdl
# 验证配置而不启动
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/`](config/examples/) 涵盖了 API 网关、负载均衡、WebSocket、缓存、推理路由等内容。或使用 [配置构建器](https://zentinelproxy.io/customize/) 交互式生成配置。
## 功能特性
| 功能 | 描述 |
|---------|-------------|
| **服务类型** | Web, API, Static, Builtin, 和 Inference (LLM/AI) |
| **负载均衡** | 14 种算法：round-robin, weighted, least connections, Maglev, Peak EWMA 等 |
| **安全** | TLS/mTLS, 速率限制, GeoIP 过滤, WAF, zip bomb 防护 |
| **Agent 协议** | 用于 WAF、auth 和自定义逻辑的外部 Agent —— 崩溃隔离，支持任何语言 |
| **HTTP 缓存** | 基于 Pingora 的响应缓存，具有拥挤预防 和 S3-FIFO + TinyLFU 驱逐策略 |
| **WebSocket 代理** | 符合 RFC 6455 标准，支持帧检查和流量镜像 |
| **可观测性** | Prometheus 指标, 结构化日志, OpenTelemetry 链路追踪 |
| **热重载** | 通过 SIGHUP 实现零停机配置更新，包含验证和原子交换 |
在 [zentinelproxy.io/features](https://zentinelproxy.io/features/) 查看完整功能细分。
### 使用案例
- **反向代理** — 为 Web 应用程序提供 TLS 终结、静态文件服务、压缩和安全头
- **API 网关** — 版本化路由、JWT/API key 认证、每客户端速率限制和 JSON 错误响应
- **负载均衡器** — 加权流量分配、健康检查、熔断器和蓝绿/金丝雀部署
- **推理网关** — 基于 Token 的速率限制、支持 glob 模式 (`gpt-4*`, `claude-*`) 的模型路由、提示词注入检测，以及针对 OpenAI、Anthropic 和通用 LLM 提供商的 PII 过滤
- **WebSocket 网关** — 持久连接代理，支持帧检查、消息速率限制和会话亲和性
- **安全网关** — WAF、GeoIP 过滤、mTLS 和可组合的 Agent 管道，用于自定义安全逻辑
每个案例的示例配置：[`config/examples/`](config/examples/)
## 为什么选择 Zentinel
现代代理积累了隐藏行为、无限复杂性和在压力下显现的运营风险。Zentinel 采用了不同的方法：
- **资源受限** — 内存限制、队列深度、确定性超时。没有意外行为。
- **显式故障模式** — 每个路由 Fail-open 或 fail-closed，绝不模棱两可。
- **外部可扩展性** — 安全逻辑存在于 Agent 中，而非核心。小巧、稳定的数据平面。
- **默认可观测** — 每个决策都被记录和计量。功能只有在受限、观测和测试后才会发布。
目标是构建**正确、冷静且值得信赖**的基础设施。请参阅 [`MANIFESTO.md`](MANIFESTO.md) 了解完整理念。
## Agents
Zentinel 的安全性和可扩展性存在于 **Agents** 中 —— 它们是接入每个请求阶段的外部进程。Agent 与代理崩溃隔离，可独立部署，并且可以用任何语言编写。
Agent SDKs: [Rust](https://github.com/zentinelproxy/zentinel-agent-rust-sdk) · [Go](https://github.com/zentinelproxy/zentinel-agent-go-sdk) · [Python](https://github.com/zentinelproxy/zentinel-agent-python-sdk) · [TypeScript](https://github.com/zentinelproxy/zentinel-agent-typescript-sdk) · [Elixir](https://github.com/zentinelproxy/zentinel-agent-elixir-sdk) · [Kotlin](https://github.com/zentinelproxy/zentinel-agent-kotlin-sdk) · [Haskell](https://github.com/zentinelproxy/zentinel-agent-haskell-sdk)
| Agent | 描述 |
|-------|-------------|
| [WAF](https://github.com/zentinelproxy/zentinel-agent-waf) | 纯 Rust WAF — 200+ 检测规则，ML 驱动的异常评分，零 C 依赖 |
| [AI Gateway](https://github.com/zentinelproxy/zentinel-agent-ai-gateway) | 提示词注入检测、越狱防护、LLM API 的 PII 过滤 |
| [Policy](https://github.com/zentinelproxy/zentinel-agent-policy) | 多引擎策略评估 (Rego/OPA 和 Cedar) — 用 Haskell 编写 |
| [Auth](https://github.com/zentinelproxy/zentinel-agent-auth) | JWT, OIDC, SAML, mTLS, API keys，带有基于 Cedar 的细粒度授权 |
| [Chaos](https://github.com/zentinelproxy/zentinel-agent-chaos) | 延迟注入、错误模拟、连接重置，带有安全防护栏 |
| [Lua](https://github.com/zentinelproxy/zentinel-agent-lua) | 沙箱化 Lua 脚本，具有 VM 池、热重载和资源限制 |
| [ZentinelSec](https://github.com/zentinelproxy/zentinel-agent-zentinelsec) | 纯 Rust ModSecurity — OWASP CRS 兼容的 SecLang 解析器，零 C 依赖 |
| [WebSocket Inspector](https://github.com/zentinelproxy/zentinel-agent-websocket-inspector) | 内容过滤、JSON/MessagePack 验证和 WebSocket 帧的速率限制 |
| [MQTT Gateway](https://github.com/zentinelproxy/zentinel-agent-mqtt-gateway) | IoT 协议安全，具有 Topic ACL、认证和 Payload 检查 |
在 [zentinelproxy.io/agents](https://zentinelproxy.io/agents/) 浏览所有 25+ 个 Agent。
Crates
每个 crate 都有自己的 `docs/` 目录，包含详细的文档。
| Crate | 描述 |
|-------|-------------|
| [`zentinel-proxy`](crates/proxy/) | 基于 Pingora 构建的核心反向代理 |
| [`zentinel-config`](crates/config/) | KDL 配置解析和验证 |
| [`zentinel-agent-protocol`](crates/agent-protocol/) | Agent 通信协议 (v2) |
| [`zentinel-common`](crates/common/) | 共享类型、错误和工具 |
| [`wasm-runtime`](crates/wasm-runtime/) | 使用 Wasmtime 的 WASM agent 运行时 |
| [`playground-wasm`](crates/playground-wasm/) | 配置演练场的浏览器绑定 |
| [`sim`](crates/sim/) | 兼容 WASM 的配置模拟器 |
| [`stack`](crates/stack/) | 用于代理和 Agent 的一体化进程管理器 |
## 控制平面
[**zentinel-control-plane**](https://github.com/zentinelproxy/zentinel-control-plane) — Zentinel 代理集群的舰队管理，使用 Elixir/Phoenix 构建。集中化配置、滚动部署以及跨 Zentinel 实例的实时可观测性。
## 社区
- 📖 [Documentation](https://docs.zentinelproxy.io/) — 指南、参考和示例
- 🎮 [Playground](https://zentinelproxy.io/playground/) — 在浏览器中试用路由引擎 (WASM)
- 📊 [Benchmarks](https://zentinelproxy.io/benchmarks/) — 性能、浸泡测试和 Envoy 对比
- 💬 [Discussions](https://github.com/zentinelproxy/zentinel/discussions) — 问题、想法、展示与分享
- 🐛 [Issues](https://github.com/zentinelproxy/zentinel/issues) — Bug 报告和功能请求
## 许可证
Apache 2.0 — 详见 [LICENSE](LICENSE)。
标签：AI网关, API网关, AppImage, Envoy替代, HTTP代理, JSONLines, Nginx替代, Pingora, Rust, TLS/SSL, WAF, Web应用防火墙, 中间件, 反向代理, 可视化界面, 流量管理, 用户代理, 缓存, 网关, 网络基础设施, 网络安全, 网络流量审计, 自定义请求头, 请求拦截, 负载均衡, 路由, 边缘计算, 通知系统, 隐私保护, 零信任