TavilyProxyManager: Ferramenta de proxy reverso para gerenciamento agregado de vários créditos de API de conta de pool de proxy da Tavily

O TavilyProxyManager é uma ferramenta para o Tavily O Tavily API é um sistema de proxy reverso transparente de código aberto projetado pela Tavily API. Sua função principal é a convergência unificada de várias chaves (Key) da API Tavily para um pool de proxy, sendo que o externo só expôs uma chave mestra personalizada para autenticação de segurança. Por meio desse mecanismo de gerenciamento de pooling de várias contas, o sistema é capaz de monitorar de forma inteligente a cota restante de cada chave e alocar automaticamente a tarefa de chamada, resolvendo efetivamente o problema de chamadas limitadas para uma única interface de conta gratuita, baixa frequência de simultaneidade (Rate Limit) e fragmentação de cota.

Além das funções básicas de encaminhamento de proxy, o sistema também tem um painel de gerenciamento visual da Web integrado baseado em Vue 3, que é conveniente para os usuários adicionarem/removerem chaves de API a qualquer momento, sincronizarem a cota restante de todas as contas com um único clique e oferecerem suporte à apresentação gráfica do volume histórico de chamadas e das tendências de consumo de cota. Devido à estratégia de proxy totalmente transparente, o TavilyProxyManager é compatível com todos os caminhos e parâmetros de solicitação da interface oficial original. Para o ecossistema de desenvolvimento assistido por IA, o sistema fornece nativamente pontos de extremidade HTTP MCP (Model Context Protocol) para acesso imediato e contínuo. Claude O projeto usa uma arquitetura leve de compilação de arquivo único da linguagem Go com uma solução de conteinerização do Docker para concluir a implantação rápida. O projeto adota uma arquitetura leve de compilação de arquivo único da linguagem Go com um esquema de conteinerização do Docker, que permite uma implantação rápida sob a premissa de consumo extremamente baixo de recursos.

Lista de funções

• Programação inteligente e simultânea do pool de chavesChave de API da Tavily: integre várias chaves de API da Tavily e determine automaticamente a cota restante de cada chave. A prioridade é dada às chaves de chamada com cota suficiente, e uma estratégia de dispersão aleatória é adotada para chaves com a mesma cota, o que reduz significativamente a pressão do acesso simultâneo a uma única chave e evita o erro de excesso de solicitação 429.
• Interceptação automática de falhas e comutação contínuaO mecanismo de recuperação de desastres de solicitações é configurado de modo que, quando uma chamada downstream encontra um código de status de exceção oficial, como 401 (não autorizado), 429 (solicitação muito frequente), 432/433 etc., a camada de proxy intercepta automaticamente o relatório de erro e muda silenciosamente a solicitação para a próxima chave alternativa saudável para nova tentativa.
• Visualização na Web Painel de gerenciamento centralizadoInterface gráfica do usuário: Incorporado a um console GUI completo (Vite + Vue 3), ele oferece as funções de adicionar, excluir, alterar e sincronizar em lote as informações de cota mais recentes de várias contas e, ao mesmo tempo, usa um gráfico de tendências para mostrar o consumo de solicitações e o status geral da operação.
• Auditoria global de registros de solicitaçõesRegistro em tempo real de todas as solicitações de pesquisa e detalhes de resposta (incluindo código de status, valor do consumo, tempo consumido etc.) encaminhados pelo agente. Suporta o uso de condições para filtrar o registro do histórico de pesquisa e vem com um mecanismo de limpeza manual e automático de armazenamento de longa duração.
• Suporte a endpoints HTTP MCP nativos:: Em conformidade com Model Context Protocol Especificação, sistema integrado /mcp Serviços de endpoint e suporte para os modos de operação com e sem estado, reduzindo consideravelmente o limite para configurar os recursos de pesquisa de rede para inteligências de IA (agentes) e editores.
• Chave mestra Autenticação de acesso unificadoO cliente e o código comercial não precisam se preocupar com quantas contas da Tavily estão conectadas na parte inferior; eles apenas substituem o nome de domínio da API pelo endereço do proxy e iniciam um processo padrão de Authorization: Bearer A autenticação pode ser chamada.
• Tarefas cíclicas automatizadas de O&MO script de tempo em segundo plano acionará automaticamente a lógica de redefinição de cota no dia 1º de cada mês e, ao mesmo tempo, poderá limpar automaticamente os dados de registro expirados e abandonados, de modo que todo o processo possa ser executado de forma estável por um longo período de tempo sem intervenção humana.
• Implementação extremamente leveOs recursos estáticos do back-end (Go 1.23+) e do front-end são compilados e agrupados em um único executável binário extremamente compacto, compatível com todas as principais plataformas arquitetônicas e, combinado com o Docker Compose, pode ser obtido e estar pronto para uso com um único clique.

Usando a Ajuda

🛠️ Guia detalhado de instalação e uso do TavilyProxyManager

Para permitir que os usuários gerenciem e usem sem problemas várias cotas da API da Tavily, este guia explicará em detalhes tudo, desde a configuração do ambiente do Docker, configurações de arquivos de configuração, gerenciamento de painéis, API e MCP Procedimentos operacionais completos para atracação de clientes.

I. Instalação recomendada: implantação de ambiente baseado no Docker Compose

Como o projeto é baseado em uma arquitetura que empacota o front-end e o back-end em um único arquivo binário, uma implantação em contêiner usando o Docker é a maneira mais eficiente de evitar a contaminação do ambiente do host. Certifique-se de ter o Docker e o plug-in Docker Compose instalados em seu servidor.

1. estabelecimento do catálogo de projetos e do arquivo de configuração
Crie uma nova pasta no terminal do servidor e crie um diretório nesse diretório chamado docker-compose.yml do arquivo de orquestração:

mkdir tavily-proxy && cd tavily-proxy
touch docker-compose.yml

2. preparação dos parâmetros de configuração
Abrir com um editor de texto docker-compose.ymlPreencha os campos a seguir e salve:

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. inicie e puxe o serviço de espelho
Execute o seguinte comando para iniciar o contêiner. O sistema buscará automaticamente a versão mais recente da imagem no Github Container Registry.

docker-compose up -d

Obtenção de credenciais principais: geração de uma chave mestra

O TavilyProxyManager impõe o uso do sistema Master Key para garantir que o serviço não seja abusado. No serviçolançamento inicialSe o banco de dados estiver vazio, o sistema gerará automaticamente uma chave mestra aleatória de alta resistência.

Obtenha essa senha inicial de administrador consultando o registro do contêiner:

docker logs tavily-proxy 2>&1 | grep "master key"

Saída do terminal de amostra:

level=INFO msg="no master key found, generated a new one" key=sk_master_xxxxxx

⚠️ Observações importantes: Por favor, transfira imediatamente este parágrafo para o key= Essa cadeia é salva em seu gerenciador de senhas. Essa senha é a senha exclusiva para fazer login no painel de monitoramento da Web e o token de portador que você precisa incluir nos cabeçalhos das solicitações de API subsequentes.

Operação básica do painel de visualização da Web

1. Sistema de loginPara acessar o IP do seu servidor em um navegador ou um nome de domínio vinculado (por exemplo http://<服务器IP>:8080 ). Digite a chave mestra que acabou de interceptar na tela de login para acessar o console.
2. Adição de um pool de chaves de agente：
   • Depois de fazer login, navegue até o módulo Key Management.
   • Clique em “Add Key” (Adicionar chave) para colar no sistema, uma a uma, várias chaves de API gratuitas ou pagas da Tavily para as quais você se registrou.
   • Após a conclusão da entrada, é recomendável clicar no botão “Synchronise Quota” (Sincronizar cota), o sistema enviará a verificação oficial da validade de todas as chaves e atualizará a [Current Remaining Calling Quota] na lista.
3. Monitorar o usoO Dashboard oferece uma visão intuitiva dos histogramas de frequência de solicitações e das taxas de sucesso do sistema, enquanto a página Logs retém o consumo de tempo específico e o status de acerto de cada comando de pesquisa, facilitando a solução de problemas e a auditoria de solicitações.

Diretrizes de acesso ao código: Modelo de proxy transparente da API REST

A especificação da interface exposta do sistema é consistente com o documento oficial 100% da Tavily, o que significa que os projetos de código aberto existentes podem ser migrados a custo zero.

Pontos principais de mudança:

• O URL da solicitação original é alterado de https://api.tavily.com Substitua pelo endereço de sua implantação http://<服务器IP>:8080
• As informações de autenticação são substituídas pelas informações de Master Key

Código de amostra de teste 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"}'

Observação: O sistema é totalmente compatível com muitas das convenções de passagem mais antigas, independentemente de você passar no corpo do Payload ou no {"api_key": "<MASTER_KEY>"} ou emendado no final do URL ?api_key=<MASTER_KEY> Todos podem ser identificados corretamente.

V. Integração avançada: acesso ao protocolo MCP (Model Context Protocol)

Um grande número de novas ferramentas de produtividade de IA (por exemplo, o aplicativo Claude Desktop, o VS Code no Cline plug-ins, etc.) são baseados no protocolo MCP para ampliar os recursos de invocação de ferramentas. Esse agente se integra nativamente a esse endpoint.

Exemplo de modificação de configuração de código VS (usado em conjunto com o mcp-remote):
Adicione o seguinte nó do servidor ao seu perfil do VS Code MCP:

{
"servers": {
"tavily-proxy": {
"command": "npx",
"args":[
"-y",
"mcp-remote",
"http://<您的服务器IP>:8080/mcp",
"--header",
"Authorization: Bearer <您的_MASTER_KEY>"
]
}
}
}

Princípio de operação: ativado por padrão MCP_STATELESS=true A variável de ambiente tem o objetivo de permitir que o proxy mantenha uma conexão sem estado. Como o protocolo MCP deve manter um estado SSE/WebSocket constante, o encaminhamento de proxy reverso e entre redes pode facilmente levar a desconexões de ID de sessão que resultam em erros. session not foundNo modo sem estado, cada instrução é chamada de forma independente. No modo sem estado, cada instrução é chamada de forma independente, garantindo a estabilidade máxima das ferramentas de IA em conexões longas.

cenário do aplicativo

1. Gerenciamento de pooling de cotas da equipe de desenvolvimento de aplicativos de IA
   Quando uma pequena equipe de P&D cria um fluxo de trabalho de agente que depende muito de mecanismos de pesquisa, a cota da versão gratuita oficial do Tavily não é suficiente para suportar a frequência de depuração. Os desenvolvedores podem registrar várias contas de teste para obter chaves e injetá-las no sistema, agregando cotas fragmentadas em um enorme pool de cotas sem modificar o código comercial subjacente no meio do processo.
2. Estratégias anti-bloqueio e de repetição para cenários de negócios de alta simultaneidade
   Ao rastrear resultados de pesquisa em grandes lotes ou ao receber chamadas repentinas de alto tráfego para o recurso de pesquisa, uma única chave Tavily está propensa a atingir um limite de taxa, resultando em um erro 429 que interrompe o processo. A implementação do sistema como uma camada de retransmissão minimiza o bloqueio simultâneo e as falhas de tarefas com seu algoritmo de dispersão aleatória suave e compensação automática de failover para erros.
3. Integração ecológica de programação assistida por IA imersiva
   O desenvolvedor usa um IDE localmente (por exemplo Cursor, Ao escrever um código que precise incorporar a documentação mais recente da Internet com um assistente de codificação de IA (VS Code), basta registrar o endereço TavilyProxyManager no IDE usando o nó MCP, após o que o modelo de IA executará autonomamente a operação de recuperação, e o desenvolvedor poderá verificar claramente se a IA está consumindo demais a API por meio do painel da Web, aumentando a transparência do faturamento.
4. Monitoramento de auditoria de interface de chamada compartilhada de nível empresarial
   A intranet corporativa fornece uniformemente uma chave mestra para os desenvolvedores de cada departamento usarem, e os administradores de TI podem localizar os scripts do lado do servidor com chamadas anormais em um loop morto monitorando as estatísticas de uso e os dados de registro no back-end e, ao mesmo tempo, executar automaticamente a reestimativa da cota mensal para atender aos requisitos de reutilização de ativos e controle interno em toda a empresa.

QA

1. Como a Tavily atualiza oficialmente a interface com frequência (por exemplo, adicionando parâmetros de pesquisa avançada), a ferramenta proxy relatará erros devido à incompatibilidade?
   R: Não há incompatibilidade. O sistema adota a filosofia de proxy de “transmissão transparente e não destrutiva”, e a camada de código intervém apenas no cabeçalho de autorização e na lógica de distribuição de proxy. Caminhos de URL específicos enviados por solicitações comerciais e quaisquer parâmetros personalizados no corpo da solicitação são roteados para a API oficial sem nenhuma alteração, de modo que ela tem imunidade e compatibilidade total com atualizações upstream.
2. Não consigo encontrar a chave mestra original no terminal. O que devo fazer e o painel ainda pode ser conectado?
   R: A chave mestra inicial é a única supercredencial para a sobrevivência do serviço. Se os logs do console tiverem sido substituídos de forma contínua, você poderá mapear a chave mestra no /data/proxy.db（Baixe o arquivo do banco de dados SQLite localmente e use uma ferramenta como o SQLiteStudio para abri-lo e analisar a tabela de configurações para recuperá-la ou alterá-la para sua própria senha de texto cifrado personalizada.
3. Por que ocorrem falhas ocasionais nas solicitações ou desconexões frequentes durante o acesso ao MCP?
   R: Isso geralmente é causado por flutuações na rede que provocam interrupções de conexão com estado. Recomenda-se confirmar primeiro docker-compose.yml na variável de ambiente MCP_STATELESS=true Se você tiver uma camada adicional de serviços de gateway autoconstruídos, como o Nginx/Caddy, aninhado na frente do contêiner de proxy, certifique-se de que o gateway não intercepte cabeçalhos de solicitação específicos e não trunque o formato de resposta do SSE com força bruta.
4. Como a estratégia de votação é tratada para chaves diferentes com o mesmo valor restante?
   R: Se o sistema determinar que mais de uma chave disponível tem o mesmo valor máximo, ele ignorará a alocação sequencial simples e usará o algoritmo Random Shuffle subjacente para o envio. Esse movimento evita ao máximo a rota fixa de solicitação nas primeiras chaves e, portanto, um único ponto para tocar o controle oficial de simultaneidade por segundo (limite de QPS).