Kimosabey/limit-guard

# LimitGuard  ## 使用原子 Redis Lua 脚本的分布式限流器 **LimitGuard** 是一个生产级的分布式限流器。它通过直接**在 Redis 中使用 Lua 脚本**实现 **令牌桶算法 (Token Bucket Algorithm)**，解决了经典的“先检查后执行 (Check-Then-Act)”竞态条件。这确保了在分布式 API 集群中实现严格的 O(1) 原子性，同时维持了**故障开放 (Fail-Open)** 的可靠性姿态。 ## 🚀 快速开始 使用一条命令启动整个技术栈（基础设施 + 后端 + 控制面板）： ``` # 1. 安装 Dependencies npm install && cd dashboard && npm install && cd .. # 2. 运行 Dev Stack npm run dev ``` ## 📸 演示与架构 ### 实时监控控制面板  *以毫秒级精度可视化展示被拦截与被允许的请求。* ### 系统架构  *由原子中间件保护的分布式网关模式。* ### 并发验证  *50 个并发操作 -> 0 个竞态条件（严格执行限制）。* ## ✨ 核心功能 * **🛡️ 原子操作**：使用 `EVALSHA` 在 Redis 内部执行逻辑，防止竞态条件。 * **⚠️ 故障开放 (Fail-Open) 设计**：优先考虑可用性。如果 Redis 宕机，流量将被**允许**通过（熔断器）。  * **🔒 端到端 HTTPS**：包含自动化的自签名证书生成。 * **📊 实时遥测**：实时 Next.js 控制面板，展示请求量和重置情况。 ## 🏗️ 防护流程 了解请求在边缘节点是如何被验证的：  1. **拦截**：请求到达 Node.js 中间件。 2. **评估**：中间件通过 Lua 将用户的 IP 和规则发送到 Redis。 3. **原子检查**：Redis 在单个时钟周期内运行逻辑（无数据竞争）。 4. **决策**：返回 200（允许）或 429（请求过多）。 5. **遥测**：状态通过 WebSockets 或轮询推送到控制面板。 ## 📚 文档 | 文档 | 描述 | | :--- | :--- | | [**系统架构**](./docs/ARCHITECTURE.md) | Lua 逻辑、令牌桶算法及设计决策。 | | [**入门指南**](./docs/GETTING_STARTED.md) | 配置指南、环境变量和故障排除。 | | [**故障场景**](./docs/FAILURE_SCENARIOS.md) | 故障开放策略和并发测试。 | | [**面试问答**](./docs/INTERVIEW_QA.md) | “为什么使用 Lua？”和“如何防止竞态条件”。 | ## 🔧 技术栈 | 组件 | 技术 | 作用 | | :--- | :--- | :--- | | **中间件** | **Node.js (Express)** | 自定义限流中间件。 | | **逻辑** | **Lua** | 用于实现原子性的服务端脚本。 | | **状态** | **Redis** | 分布式令牌桶存储。 | | **前端** | **Next.js 14** | 监控控制面板。 | ## 👤 作者 **Harshan Aiyappa** 高级全栈混合 AI 工程师 语音 AI • 分布式系统 • 基础设施 [](https://kimo-nexus.vercel.app/) [](https://github.com/Kimosabey) [](https://linkedin.com/in/harshan-aiyappa) [](https://x.com/HarshanAiyappa) ## 📝 许可证 该项目基于 MIT 许可证授权 - 详情请参阅 [LICENSE](LICENSE) 文件。

标签：Lua, MITM代理, Redis, rizin, 令牌桶算法, 分布式系统, 响应大小分析, 微服务网关, 搜索引擎查询, 自定义脚本, 限流器