TavilyProxyManager 是一个针对 Tavily API 设计的开源透明反向代理系统。它的核心功能是将开发者手中的多个 Tavily API 密钥（Key）统一汇聚到一个代理池中，对外仅暴露一个自定义的 Master Key 进行安全鉴权。通过这种多账号池化管理机制，系统能够智能监测各个密钥的剩余额度并自动分配调用任务，有效解决了单个免费账号接口调用受限、并发频率低（Rate Limit）以及额度碎片化的问题。
除了代理转发基础功能，系统还内嵌了基于 Vue 3 打造的可视化 Web 管理面板，方便用户随时添加/移除 API 密钥、一键同步所有账号的剩余配额，并支持以图表形式直观呈现历史调用量与额度消耗趋势。由于采用完全透明的代理策略，TavilyProxyManager 兼容原版官方接口的所有请求路径及参数形式。针对 AI 辅助开发生态，系统原生提供了 HTTP MCP（Model Context Protocol）端点，使其可以开箱即用地无缝接入 Claude 桌面端、VS Code 智能插件等主流 AI 工作流体系。项目采用轻量化的 Go 语言单文件编译架构，搭配 Docker 容器化方案，在资源占用极低的前提下即可完成快速部署。
功能列表
- 智能密钥池并发调度：整合录入的多个 Tavily API Key，自动判断各 Key 剩余额度。优先调用额度充裕的密钥，针对同等额度的密钥采用随机打散策略，大幅降低单一 Key 的并发访问压力，规避 429 请求超限错误。
- 自动故障拦截与无缝切换：建立请求容灾机制，在向下游发起调用遇到 401（未授权）、429（请求过于频繁）、432/433 等官方异常状态码时，代理层将自动截获报错，并静默将该次请求切换至下一个健康的备用 Key 进行重试。
- Web 可视化集中管理面板：内嵌完整的图形界面控制台（Vite + Vue 3），提供多账号的增删改查、批量同步最新额度信息的功能，同时使用趋势走势图展示请求量消耗与整体运行状态。
- 全局请求日志审计：后台实时记录每一次经过代理转发的搜索请求和响应明细（包含状态码、消耗额度、耗时等）。支持使用条件过滤搜索历史日志，并自带长效存储的手动和自动清理机制。
- 原生 HTTP MCP 端点支持：符合 Model Context Protocol 规范，系统内置
/mcp端点服务，并支持有状态与无状态（Stateless）两种运行模式，极大地降低了 AI 智能体（Agent）和编辑器的网络搜索能力配置门槛。 - Master Key 统一访问鉴权：客户端和业务代码无需关心底层连接了多少个 Tavily 账号，只需将 API 域名替换为代理地址，并通过一个总控 Master Key 发起标准的
Authorization: Bearer认证即可调用。 - 周期性自动运维任务：后台定时脚本将于每月 1 号自动触发额度重置逻辑，同时可自动清算过期废弃的日志数据，全程无需人工干预即可长期稳定运行。
- 极致的轻量化部署：后端（Go 1.23+）与前端静态资源编译捆绑为一个极其精简的单一二进制执行文件，支持所有主流架构平台，结合 Docker Compose 可以做到一键拉起即用。
使用帮助
🛠️ TavilyProxyManager 详细安装与使用指南
为了让用户能够流畅管理和使用多个 Tavily API 额度，本使用指南将详细讲解从 Docker 环境搭建、配置文件设定、面板管理到 API 与 MCP 客户端对接的完整操作流程。
一、 推荐安装方式：基于 Docker Compose 的环境部署
由于项目采用将前后端打包为一个二进制文件的架构，使用 Docker 容器化部署是最高效且能够避免主机环境污染的方法。请确保您的服务器已安装 Docker 及 Docker Compose 插件。
1. 建立工程目录与配置文件
在服务器终端中创建一个新文件夹，并在该目录下创建名为 docker-compose.yml 的编排文件：
mkdir tavily-proxy && cd tavily-proxy
touch docker-compose.yml
2. 编写配置参数
使用文本编辑器打开 docker-compose.yml，填入如下内容并保存：
version: "3.8"
services:
tavily-proxy:
image: ghcr.io/xuncv/tavilyproxymanager:latest
container_name: tavily-proxy
ports:
- "8080:8080"
environment:
# 代理服务内部监听地址与端口
- LISTEN_ADDR=:8080
# 设定内置 SQLite 数据库的存储路径
- DATABASE_PATH=/app/data/proxy.db
# 上游 Tavily 官方 API 基准地址
- TAVILY_BASE_URL=https://api.tavily.com
# 请求超时断开时间
- UPSTREAM_TIMEOUT=30s
# MCP 模式，默认 true 代表无状态模式，防止客户端报会话丢失
- MCP_STATELESS=true
volumes:
# 将宿主机的 data 目录映射给容器，持久化存储数据库
- ./data:/app/data
# 映射系统时间以保障日志时区正确
- /etc/localtime:/etc/localtime:ro
restart: unless-stopped
3. 启动并拉取镜像服务
运行以下命令启动容器。系统会自动从 Github Container Registry 获取最新版镜像。
docker-compose up -d
二、 获取核心凭据：生成 Master Key
TavilyProxyManager 为保证服务不被滥用，强制使用 Master Key 体系。在服务首次启动时，若数据库中为空，系统会自动生成一段高强度的随机 Master Key。
请通过查询容器日志获取这个初始管理密码：
docker logs tavily-proxy 2>&1 | grep "master key"
终端输出样例：
level=INFO msg="no master key found, generated a new one" key=sk_master_xxxxxx
⚠️ 重要提示：请立刻将这段 key= 后的字符串保存至您的密码管理器中。该密码既是登录 Web 监控面板的唯一口令，也是后续各种 API 请求头中所需携带的 Bearer Token。
三、 Web 可视化面板的基础操作
- 登录系统：在浏览器中访问您的服务器 IP 或绑定的域名（如
http://<服务器IP>:8080）。在登录界面输入刚才截获的 Master Key 进入控制台。 - 添加代理密钥池：
- 登录后，导航至【Key 管理】（Key Management）模块。
- 点击“新增 Key”，将您注册申请的多个 Tavily 免费或付费 API Key 逐一粘贴录入系统。
- 录入完毕后，建议点击“同步额度”按钮，系统会并发去官方核实所有 Key 的有效性，并将【当前剩余调用配额】刷新至列表中。
- 监控使用情况：导航至【仪表盘】（Dashboard），可以直观地查看请求频次柱状图和系统成功率；【请求日志】（Logs）页面则留存了每一次搜索指令的具体耗时和命中状态，方便进行请求排查与审计。
四、 代码接入指引：REST API 透明代理模式
系统对外暴露的接口规范与 Tavily 官方文档 100% 保持一致，这意味着现有的各类开源项目均能实现零成本迁移。
核心改动点：
- 将原本请求的 URL 从
https://api.tavily.com更换为您部署的地址http://<服务器IP>:8080 - 鉴权信息换为刚才的 Master Key
CURL 测试示例代码：
curl -X POST "http://<服务器IP>:8080/search" \
-H "Authorization: Bearer <您的_MASTER_KEY>" \
-H "Content-Type: application/json" \
-d '{"query": "2026年最新AI模型架构解析", "search_depth": "basic"}'
注：系统充分兼容多种旧版传参习惯，无论你在 Payload 体内传入 {"api_key": "<MASTER_KEY>"} 或在网址末尾拼接 ?api_key=<MASTER_KEY> 均可被正确识别。
五、 进阶集成：MCP (Model Context Protocol) 协议接入
目前大量新型 AI 生产力工具（如 Claude Desktop 应用端、VS Code 中的 Cline 插件等）均基于 MCP 协议扩展工具调用能力。本代理原生集成该端点。
VS Code 配置修改案例（结合 mcp-remote 使用）：
在您的 VS Code MCP 配置文件中添加如下 Server 节点：
{
"servers": {
"tavily-proxy": {
"command": "npx",
"args":[
"-y",
"mcp-remote",
"http://<您的服务器IP>:8080/mcp",
"--header",
"Authorization: Bearer <您的_MASTER_KEY>"
]
}
}
}
工作原理说明：默认启用的 MCP_STATELESS=true 环境变量旨在让代理保持无状态连接。因为 MCP 协议本意维持持续的 SSE / WebSocket 状态，但跨网络及反向代理转发极易导致 Session ID 断联从而报错 session not found。在无状态模式下，每次指令均为独立调用，保障了 AI 工具长连接时的极致稳定性。
应用场景
- AI应用研发团队额度池化管理
小型研发团队在搭建重度依赖搜索引擎的智能体（Agent）工作流时，Tavily 官方免费版的额度不足以支撑调试频次。开发人员可通过注册多个测试账号获取 Key 并统一注入系统，将碎片化额度聚合成海量配额池，无需中途修改底层业务代码。 - 高并发业务场景防封锁与重试策略
在大批量爬取搜索结果、或遭遇突发大流量调用搜索能力时，单个 Tavily Key 容易命中速率限制（Rate Limit）从而导致 429 报错中断流程。部署该系统作为中继层，依靠其平滑的随机打散算法与错误自动 Failover 切换补偿功能，可将并发阻塞和任务失败率降至最低。 - 沉浸式 AI 辅助编程生态集成
开发者在本地使用 IDE（如 Cursor, VS Code）搭配 AI 编码助手编写需要结合最新互联网文档的代码时，只需利用 MCP 节点将 TavilyProxyManager 地址注册进 IDE。此后 AI 模型将自主进行检索操作，开发者能通过 Web 面板清楚审查 AI 是否过度消耗 API，增强计费透明度。 - 企业级共享调用接口审计监控
企业内网统一提供一个 Master Key 给各部门开发者使用。IT 管理员通过监控后台的用量统计和日志数据，定位存在死循环异常调用的服务端脚本，同时自动执行每月额度重估计算，满足企业化资产复用与内控需求。
QA
- 由于 Tavily 官方经常升级接口（如新增高级搜索参数），代理工具会因不兼容而报错吗？
答：不会出现不兼容情况。系统采取“透明化无损透传”的代理哲学，代码层仅对 Authorization 头及代理分发逻辑作介入处理。业务请求发送的特定 URL 路径、请求体内的任意自定参数均原封不动路由至官方 API，故而拥有对上游升级前瞻性的免疫与完全兼容力。 - 我通过终端找不到最初生成的 Master Key 怎么办，面板还能登录吗？
答：初始的 Master Key 是服务存续的唯一超级凭据。如果控制台日志已被滚动覆盖，您可以将映射在宿主机的/data/proxy.db（SQLite数据库文件）下载至本地，使用诸如 SQLiteStudio 的工具打开查阅相关设置表，即可直接找回或将其修改为您自己自定义的密文密码。 - MCP 接入时为什么偶发请求失败或频繁断开连接？
答：通常是因为网络波动引起有状态连接中断造成的。建议首先确认docker-compose.yml中的环境变量MCP_STATELESS=true是否生效；如果您在代理容器前还额外嵌套了一层 Nginx/Caddy 等自建网关服务，请确保网关端不拦截特定的请求头部，且对于 SSE 响应格式不要做暴力缓冲截断。 - 同等剩余额度的不同 Key，是如何处理轮询策略的？
答：系统在调度时如果判断多个处于可用状态的 Key 拥有相同的最高额度数值，将跳出简单的顺序分配，而采用系统底层的随机打散算法（Random Shuffle）进行派发。此举最大程度避免了请求固定路由在头几个 Key 从而单点触碰官方每秒并发控制（QPS 阈值）。
