limiteron 0.3.0-rc.4

中文 | English

Rust 统一流量控制框架

✨ 功能特性 • 🚀 快速开始 • 📚 文档 • 💻 示例 • 🤝 参与贡献

🚦 统一流量控制

一个 Governor 入口，多维限流与纵深管控协同决策：

📋 目录

✨ 功能特性
🚀 快速开始
🎨 特性标志
📚 文档
💻 示例
🏗️ 架构
🧪 测试
📊 性能
🔒 安全
🗺️ 开发路线图
🤝 参与贡献
📋 更新日志
📄 许可证
🙏 致谢
📞 联系与支持
⭐ Star 历史

✨ 功能特性

🎯 流量治理

✅ 多种限流算法 — 令牌桶（Token Bucket）、滑动窗口、分片滑动窗口、固定窗口、并发控制、GCRA、HTB 分层令牌桶（src/limiters/）
✅ 封禁管理 — IP / 用户 / MAC / Geo 目标封禁、CIDR 网段封禁、优先级体系、YAML 批量加载与热重载、跨实例同步（ban-sync）
✅ 配额控制 — 周期性配额分配、配额预警、配额透支（src/quota/）
✅ 熔断与降级 — 自动故障转移、状态恢复、降级策略（src/circuit/、src/fallback.rs）

⚡ 工程能力

🚀 高性能 — 令牌桶吞吐 12M+ ops/s、P99 延迟 < 1µs（见性能）
🧩 声明式接入 — #[flow_control] 过程宏、Tower 中间件、Admin REST API、limiteron-cli
🏢 多租户 — tenant+key 复合决策键，缓存/封禁/配额按租户隔离
📈 可观测性 — Prometheus 指标、OTLP 追踪导出、HMAC-SHA256 链式审计日志、K8s 探针端点
🔐 安全内建 — 标识符 key 消毒、日志脱敏、Webhook 签名防重放、Admin RBAC

决策链（DecisionChain）：按优先级级联执行多条规则，支持短路（src/decision_chain/）
标识符匹配：IP、用户 ID、设备 ID、API Key、地理位置（MaxMindDB）、设备信息（woothee）、自定义匹配器（src/matchers/）
L1 负缓存：仅缓存拒绝/封禁决策，命中不绕过限流与封禁语义（src/l1_cache.rs）
分布式限流：DistributedLimiter trait + 内存实现 + Redis Lua 实现（distributed + lua-script）
批量 API：批量决策检查、批量令牌预取（BatchTokenPrefetcher）
热更新：POST /api/v1/config 原子换配置、配置文件监听（config-watcher）、confers 集成热重载
事件系统：EventEmitter / EventDispatcher、Transactional Outbox、Webhook 外发签名
探针端点：/healthz、/readyz、/metrics（bypass 认证）
国际化：ICU4X locale 感知格式化（i18n）
限流预检：Limiter::peek(cost) / remaining() 非消费查询与 IETF RateLimit-* 头数据

🚀 快速开始

📦 安装

cargo add limiteron

环境要求：Rust 1.97.1+（见 rust-toolchain.toml）。默认特性为空（default = []），核心限流零外部存储依赖；需要持久化时启用存储特性：

[dependencies]
limiteron = { version = "0.3.0-rc.3", features = ["macros"] }

💡 最小可运行示例

以下示例来自 examples/src/bin/simple_rate_limit.rs，演示最基本的令牌桶限流：

use limiteron::limiters::{Limiter, TokenBucketLimiter};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 容量 10，每秒补充 1 个令牌
    let limiter = TokenBucketLimiter::new(10, 1);

    for i in 0..15 {
        match limiter.allow(1).await {
            Ok(true) => println!("请求 {} 允许", i),
            Ok(false) => println!("请求 {} 被限流", i),
            Err(e) => println!("请求 {} 错误: {:?}", i, e),
        }
    }
    Ok(())
}

运行方式：

cargo run -p limiteron-examples --bin simple_rate_limit

声明式宏（macros 特性，摘自现有示例风格）：

use limiteron::flow_control;

#[flow_control(rate = "100/s", quota = "10000/m", concurrency = 50)]
async fn api_handler(user_id: &str) -> Result<String, limiteron::error::LimiteronError> {
    Ok(format!("处理用户 {} 的请求", user_id))
}

🧭 核心概念

Governor：主控制器（src/governor.rs），输入 RequestContext，输出 Decision
FlowControlConfig：version / global / rules 三层配置，支持文件加载与环境变量覆盖（ConfigLoader::load_from_file_with_env）
Decision：三态结果 Allowed / Rejected / Banned（src/error/mod.rs）
DecisionChain：按优先级级联执行的责任链，节点即 Limiter（src/decision_chain/）
存储抽象：Storage / BanStorage / QuotaStorage（src/storage/），内存实现开箱即用，dbnexus 适配器提供 PostgreSQL / SQLite / MySQL

🎨 特性标志

Limiteron 默认不启用任何可选功能（default = []），按需组合。以下内容逐项对应 Cargo.toml 的 [features] 段：

特性预设

预设	说明	启用的特性
`minimal`	核心限流，无外部存储依赖	无
`standard`	核心功能 + SQLite 持久化	`sqlite`、`ban-manager`、`quota-control`、`circuit-breaker`
`full`	全部功能组合（含 `postgres`，不含 `sqlite` / `mysql` / `cli`）	25 项特性，见 Cargo.toml

⚠️ 存储驱动互斥：postgres / sqlite / mysql 均走 dbnexus，嵌入式与服务端驱动不可共存于同一构建，请勿使用 --all-features，应使用显式特性组合。

⚠️ no-op 特性：priority-queue、admission-control 仅为下游兼容声明，启用无任何效果，请勿依赖其做能力判断。

📚 文档

文档	说明
📖 用户指南	从安装、核心概念到进阶用法与故障排除的完整教程
📘 API 参考	全部公开 API 的详细说明
🏗️ 架构文档	设计理念、模块划分与扩展机制
❓ FAQ	常见问题解答与故障排除
🧪 测试指南	测试分类、运行命令与覆盖率说明
🧬 测试场景固化	测试金字塔基线与 E2E 场景定义
📈 覆盖率报告	历史基线数据（v0.1.0 时期生成，待 CI 覆盖率更新）
🔒 安全文档	安全设计、版本支持策略与漏洞报告流程
📋 更新日志	每个版本的变更记录
🤝 贡献指南	如何参与项目开发
📦 docs.rs 在线文档	自动生成的最新 API 文档
📦 crates.io	发布页面

💻 示例

examples/ 是 workspace 内的独立子 crate（limiteron-examples），含 21 个可运行示例。运行需要 feature 的示例时先启用对应特性：

cargo run -p limiteron-examples --bin simple_rate_limit
cargo run -p limiteron-examples --features "ban-manager,admin-api" --bin ban_http_api

示例	说明
`simple_rate_limit`	最基本的令牌桶限流使用方式
`rate_limiters`	五种限流算法：令牌桶、滑动窗口、固定窗口、并发限制器、GCRA
`macro_usage`	`flow_control` 宏的使用方式与当前版本的限制
`governor_demo`	Governor 三种构造模式、请求检查、决策解析与统计信息
`matchers_demo`	标识符提取器、请求上下文与规则匹配器的完整使用流程
`decision_chain`	责任链决策：组合多个限流器、按优先级执行、支持短路
`custom_matchers`	自定义匹配器 trait 实现、注册表与内置 Header / TimeWindow 匹配器
`authorization_demo`	授权提供者 trait 实现与内置 `SimpleAuthorizationProvider`
`graceful_shutdown`	监听 Ctrl+C 并调用 `Governor::shutdown()` 幂等优雅关闭
`circuit_breaker`	熔断器：故障检测、熔断打开、半开恢复探测与超时恢复
`quota_control`	配额消费跟踪、限额执行与用量百分比计算
`ban_manager`	IP / 用户 ID / MAC 目标的封禁创建、查询、更新与移除
`ban_file_loader`	从 YAML 加载封禁规则并支持文件变更热重载
`ban_http_api`	启动 AdminServer 并通过 HTTP 调用封禁管理端点
`validation_demo`	统一验证模块：IP、用户 ID、MAC、API Key、封禁目标校验
`storage_factory`	通过 `StorageFactory` 从 DSN 创建 Postgres / MySQL / SQLite 后端
`fallback_demo`	降级策略管理器：策略配置、故障注入、降级执行与孤岛模式
`audit_log_demo`	审计日志：事件记录、配置、统计与签名验证
`tower_middleware`	将 Governor 流量控制集成到 Tower Service 处理链
`telemetry_demo`	Prometheus 指标采集与 OpenTelemetry 分布式追踪
`device_geo_matching`	User-Agent 解析、设备识别、IP 地理查询与地理条件匹配

🏗️ 架构

Limiteron 采用分层架构：接入层（Tower 中间件、Admin API）将流量交给 Governor 主控制器，经 matchers 提取标识符并匹配规则后，沿规则各自的 decision_chain 决策链级联执行 limiters 限流算法；封禁、配额、熔断、降级作为领域组件参与决策；状态经 storage 抽象落地（默认内存，生产可切换 dbnexus 的 PostgreSQL / SQLite / MySQL 持久化）。

整体架构图、核心决策时序、模块职责表、存储后端清单与扩展机制见架构文档。

🎯 核心决策流程

一次 Governor::check(context) 的完整决策路径（提炼自 src/governor.rs）：标识符提取与规则匹配（只计算一次）→ L1 负缓存查询（fail-closed，仅缓存拒绝/封禁决策）→ 按优先级级联执行各规则决策链（任一规则拒绝即拒绝，全部允许才放行）→ 发射限流事件并返回 Allowed / Rejected / Banned。

完整决策时序图与逐条关键语义（含 parallel-checker 下封禁检查先于缓存读取的语义）见架构文档。

🔗 生态与集成

Limiteron 与同工作区的兄弟 crate 深度协作，均通过 feature 显式启用、默认不引入：

集成	特性	说明
dbnexus	`postgres` / `sqlite` / `mysql`	数据库抽象层，提供持久化存储适配器与指标传递
oxcache	`cache-service` / `cache-storage` / `lua-script` / `ban-sync`	统一缓存服务、Redis Lua 执行、Pub/Sub 封禁广播
trait-kit	`kit`	`LimiteronModule` 模块化接入 + 健康/生命周期端口
inklog	`inklog`	结构化日志（console/file/database sinks），含 `SinkRateLimit` 限流端口
confers	`config-confers` / `config-confers-reload`	配置源加载与热重载（验证失败自动回滚）

另通过 i18n 特性集成 ICU4X 提供 locale 感知格式化。

🧪 测试

测试策略矩阵（单元 / 集成与端到端 / 属性 / 文档 / 基准五层）与运行命令（与 CI 一致，含覆盖率门禁）见测试指南，分层基线与 E2E 场景定义见测试场景固化。

测试规模（按 #[test] / #[tokio::test] 属性 grep 统计，截至 v0.3.0-rc.3）：

统计项	数量
库内测试函数（`src/`）	2,160（#[test] 1,410 + #[tokio::test] 750）
外部测试函数（`tests/`）	599（#[test] 157 + #[tokio::test] 442）
属性测试组（proptest）	4

📊 性能

说明：以下数据为 2026-01-19 综合性能测试的实际结果。

吞吐量

限流器	实测	目标	达成
TokenBucket	12M+ ops/s	500K ops/s	✅ 24x
FixedWindow	20M+ ops/s	300K ops/s	✅ 66x
ConcurrencyLimiter	12M+ ops/s	200K ops/s	✅ 60x

延迟

分位	TokenBucket	FixedWindow
P50	< 100ns	< 100ns
P95	< 200ns	< 150ns
P99	< 1µs	< 500ns

TokenBucket: 12,088,759 ops/s
FixedWindow: 19,920,188 ops/s
ConcurrencyLimiter: 11,891,237 ops/s
并发测试：数据一致性 100%，限流正确性 1000/1000

基准设施：仓库自带四组 criterion 基准（均需 full 特性），用于复现与回归检测：

基准	文件	内容
吞吐量	`benches/throughput.rs`	单线程/并发吞吐量与扩展曲线
延迟	`benches/latency.rs`	P50/P90/P99/P99.9 延迟测量与操作对比
内存	`benches/memory.rs`	键规模内存占用、数据结构对比、泄漏检测
回归	`benches/regression.rs`	历史基准存储与自动对比告警

cargo bench --features full

🔒 安全

漏洞报告：请勿通过公开 issue 报告安全漏洞，请使用 GitHub Security Advisories 私密披露通道（"Report a vulnerability"）。维护者承诺 48 小时内确认、7 天内给出初步评估，采用协调披露。完整流程见 SECURITY.md。

安全设计要点（均可在源码与安全文档中对应）：

输入防线 — 标识符 key 消毒（ASCII 白名单 + 128 字符截断，防 key 注入与同形字符攻击）；IP / 用户 ID / MAC 格式校验（src/validation.rs）
算法边界 — 令牌桶时间差与补充使用饱和运算封顶；配额窗口内置时钟回退防护
Admin 自保护 — 管理端点自身限流 + 分桶内存上限 + 多 key 令牌认证与 admin/viewer 角色矩阵（RBAC）
数据保护 — secrecy 保护敏感数据、日志脱敏（log-redaction）、审计事件 HMAC-SHA256 链式签名与篡改检测
传输防线 — 可信代理 X-Forwarded-For 提取；Webhook 外发签名 + 时间戳防重放 + URL 校验（SSRF）
供应链 — rustls-webpki 最低版本锁（CVE-2025-48369）；cargo-deny 校验漏洞/许可证/重复依赖；CI Security 任务与 pre-push 钩子运行 cargo deny check 与 cargo audit

🗺️ 开发路线图

🤝 参与贡献

欢迎任何形式的贡献！开发环境、TDD 工作流、代码规范与 PR 流程详见贡献指南。

🐛 报告问题

发现了 Bug？创建 Issue

💡 功能建议

有好想法？发起讨论

🔧 提交代码

想参与开发？ Fork & PR

Rust 1.97.1（rust-toolchain.toml 统一锁定）；lefthook / pre-commit 钩子覆盖 fmt、clippy、供应链检查、私钥扫描与覆盖率门禁。环境搭建、钩子明细与提交规范全文见贡献指南。

📋 更新日志

完整变更记录见 CHANGELOG.md。近期版本要点：

0.3.0-rc.3（2026-09-10）— 多租户贯穿 Governor、CIDR 网段封禁、Admin RBAC、OTLP 追踪导出、MySQL 存储、HTB 分层令牌桶、舱壁隔离、AIMD 自适应限流、limiteron-cli、Webhook 签名、事件 Outbox、封禁跨实例同步
0.3.0-rc.2（2026-09-03）— 文档同步至 0.3 线、workspace 依赖路径本地化、Cargo.lock 纳入版本控制
0.2.10（2026-07-22）— 新增 76 个边界与异常场景测试、sea-orm 升级至 2.0 稳定版、清理未使用依赖

📄 许可证

🙏 致谢

🌟 依赖项目 — 本项目构建在这些优秀的项目之上：
- tokio — 异步运行时
- dbnexus — 数据库抽象层
- oxcache — 统一缓存服务
- trait-kit — trait 集成模块
- inklog — 结构化日志
- dashmap — 并发 HashMap
👥 贡献者 — 感谢所有贡献者！
💬 社区 — 特别感谢社区成员的支持

📞 联系与支持

🐛 Issues — 报告 Bug 与问题
💬 Discussions — 提问与交流想法
📦 GitHub 仓库 — 查看源代码
🤝 维护者：Kirky.X

⭐ Star 历史

💝 支持本项目

如果您觉得这个项目有用，请考虑给它一个 ⭐️！

Built with ❤️ by Kirky.X