TavilyProxyManager: Reverse Proxy Tool für die aggregierte Verwaltung von mehreren Tavily Proxy Pool Account API Credits

Der TavilyProxyManager ist ein Werkzeug für die Tavily Tavily API ist ein Open-Source-transparentes Reverse-Proxy-System von Tavily API entwickelt. Seine Kernfunktion ist es, Entwickler in den Händen von mehreren Tavily API-Schlüssel (Key) einheitliche Konvergenz zu einem Proxy-Pool, der externe nur einen benutzerdefinierten Master Key für die Sicherheit Authentifizierung ausgesetzt. Durch diese Multi-Account-Pooling-Management-Mechanismus, ist das System in der Lage, intelligent zu überwachen, die verbleibende Quote der einzelnen Schlüssel und automatisch den Anruf Aufgabe, effektiv zu lösen das Problem der begrenzten Anrufe auf ein einziges freies Konto Schnittstelle, geringe Gleichzeitigkeit Frequenz (Rate Limit) und Quote Fragmentierung.

Zusätzlich zu den grundlegenden Proxy-Weiterleitungsfunktionen verfügt das System auch über ein eingebautes visuelles Web-Management-Panel, das auf Vue 3 basiert und es den Nutzern ermöglicht, jederzeit API-Schlüssel hinzuzufügen/zu entfernen, die verbleibenden Kontingente aller Konten mit einem einzigen Klick zu synchronisieren und die grafische Darstellung des historischen Anrufvolumens und der Kontingentverbrauchstrends zu unterstützen. Aufgrund der vollständig transparenten Proxy-Strategie ist TavilyProxyManager mit allen Abfragepfaden und Parametern der ursprünglichen offiziellen Schnittstelle kompatibel. Für das Ökosystem der KI-gestützten Entwicklung bietet das System nativ HTTP MCP (Model Context Protocol) Endpunkte für einen nahtlosen Out-of-the-Box-Zugriff. Claude Das Projekt verwendet eine leichtgewichtige Architektur für die Kompilierung der Sprache Go in einer einzigen Datei mit einer Docker-Containerisierungslösung, um eine schnelle Bereitstellung zu ermöglichen. Das Projekt verwendet eine leichtgewichtige Architektur für die Kompilierung der Sprache Go in einer einzigen Datei mit einem Docker-Container-System, das eine schnelle Bereitstellung unter der Prämisse eines extrem geringen Ressourcenverbrauchs ermöglicht.

Funktionsliste

• Intelligente gleichzeitige Planung des SchlüsselpoolsTavily-API-Schlüssel: Integrieren Sie mehrere Tavily-API-Schlüssel und ermitteln Sie automatisch die verbleibende Quote für jeden Schlüssel. Schlüssel mit ausreichendem Kontingent werden bevorzugt aufgerufen, und für Schlüssel mit gleichem Kontingent wird eine zufällige Verteilungsstrategie angewandt, die den Druck des gleichzeitigen Zugriffs auf einen einzigen Schlüssel erheblich reduziert und den Fehler 429 request overrun vermeidet.
• Automatische Fehlerabschaltung und nahtlose UmschaltungDer Disaster-Recovery-Mechanismus für Anfragen ist so eingerichtet, dass die Proxy-Schicht automatisch die Fehlermeldung abfängt und die Anfrage stillschweigend an den nächsten gesunden Alternativschlüssel weiterleitet, wenn bei einem nachgelagerten Aufruf ein offizieller Ausnahme-Statuscode wie 401 (nicht autorisiert), 429 (zu häufige Anfrage), 432/433 usw. auftritt.
• Web-Visualisierung Zentralisiertes Management-PanelEingebettet in eine vollständige GUI-Konsole (Vite + Vue 3) bietet es die Funktionen des Hinzufügens, Löschens, Änderns und der Batch-Synchronisierung der letzten Kontingentinformationen mehrerer Konten und zeigt gleichzeitig in einem Trenddiagramm den Verbrauch von Anfragen und den Gesamtbetriebsstatus an.
• Globale AnforderungsprotokollprüfungEchtzeit-Protokollierung aller Suchanfragen und Antwortdetails (einschließlich Statuscode, Verbrauchsmenge, verbrauchte Zeit usw.), die vom Agenten weitergeleitet werden. Unterstützung der Verwendung von bedingten Filterung Suche Geschichte log, und kommt mit einer lang anhaltenden Speicherung von manuellen und automatischen Reinigungsmechanismus.
• Native HTTP-MCP-Endpunktunterstützung:: Entspricht den Model Context Protocol Spezifikation, eingebautes System /mcp Endpunktdienste und Unterstützung für zustandsabhängige und zustandslose Betriebsmodi, wodurch die Schwelle für die Konfiguration von Netzwerksuchfunktionen für KI-Intelligenzen (Agenten) und Redakteure erheblich gesenkt wird.
• Master Key Einheitliche ZugangsauthentifizierungDer Client und der Geschäftscode müssen sich nicht darum kümmern, wie viele Tavily-Konten unten verbunden sind, sie ersetzen einfach den API-Domänennamen durch die Proxy-Adresse und initiieren eine Standard Authorization: Bearer Die Authentifizierung kann aufgerufen werden.
• Zyklische automatisierte O&M-AufgabenDas Skript zur Zeitsteuerung im Hintergrund löst automatisch am 1. eines jeden Monats die Logik zum Zurücksetzen der Quoten aus und kann gleichzeitig automatisch die abgelaufenen und aufgegebenen Protokolldaten löschen, so dass der gesamte Prozess über einen langen Zeitraum ohne menschliches Eingreifen stabil läuft.
• Extrem leichter EinsatzDas Back-End (Go 1.23+) und die statischen Frontend-Ressourcen werden kompiliert und in einer einzigen, extrem kompakten Binärdatei gebündelt, die alle wichtigen Architekturplattformen unterstützt. In Kombination mit Docker Compose kann sie mit einem einzigen Klick aufgerufen und verwendet werden.

Hilfe verwenden

🛠️ TavilyProxyManager Ausführliche Anleitung zur Installation und Verwendung

Damit Benutzer mehrere Tavily-API-Kontingente reibungslos verwalten und nutzen können, wird in diesem Leitfaden alles von der Einrichtung der Docker-Umgebung über die Einstellungen der Konfigurationsdateien und die Panel-Verwaltung bis hin zu API und MCP Vollständige operative Verfahren für das Andocken von Kunden.

I. Empfohlene Installation: Docker Compose-basierte Umgebungsbereitstellung

Da das Projekt auf einer Architektur basiert, die das Front-End und das Back-End in eine einzige Binärdatei packt, ist eine containerisierte Bereitstellung mit Docker der effizienteste Weg, um eine Verunreinigung der Hostumgebung zu vermeiden. Stellen Sie sicher, dass Sie Docker und das Docker Compose Plugin auf Ihrem Server installiert haben.

1. die Erstellung des Projektkatalogs und der Konfigurationsdatei
Erstellen Sie einen neuen Ordner im Server-Terminal und legen Sie darin ein Verzeichnis mit dem Namen docker-compose.yml der Orchestrierungsdatei:

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

2. die Vorbereitung der Konfigurationsparameter
Öffnen mit einem Texteditor docker-compose.ymlfüllen Sie das folgende Formular aus und speichern Sie es:

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. starten und ziehen Sie den Spiegelservice
Führen Sie den folgenden Befehl aus, um den Container zu starten. Das System holt automatisch die neueste Version des Images aus der Github Container Registry.

docker-compose up -d

Erlangung der wichtigsten Berechtigungsnachweise: Generierung eines Hauptschlüssels

TavilyProxyManager erzwingt die Verwendung des Hauptschlüssel-Systems, um sicherzustellen, dass der Dienst nicht missbraucht wird. Im DienstErsteinführungWenn die Datenbank leer ist, generiert das System automatisch einen hochgradig zufälligen Hauptschlüssel.

Dieses ursprüngliche Admin-Passwort erhalten Sie durch Abfrage des Container-Logs:

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

Beispielhafte Terminalausgabe:

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

⚠️ Wichtige Hinweise: Bitte übertragen Sie diesen Absatz sofort in die key= Diese Zeichenfolge wird in Ihrem Passwort-Manager gespeichert. Dieses Kennwort ist sowohl das eindeutige Kennwort für die Anmeldung beim Webüberwachungspanel als auch das Bearer Token, das Sie in den Kopfzeilen nachfolgender API-Anfragen angeben müssen.

Grundlegende Bedienung des Web-Visualisierungspanels

1. AnmeldesystemUm die IP-Adresse Ihres Servers in einem Browser oder einen gebundenen Domainnamen (z. B. http://<服务器IP>:8080 ). Geben Sie den Master Key ein, den Sie gerade auf dem Anmeldebildschirm abgefangen haben, um auf die Konsole zuzugreifen.
2. Hinzufügen eines Agent-Schlüsselpools：
   • Navigieren Sie nach dem Einloggen zum Modul Schlüsselverwaltung.
   • Klicken Sie auf “Schlüssel hinzufügen”, um mehrere kostenlose oder kostenpflichtige Tavily-API-Schlüssel, für die Sie sich registriert haben, nacheinander in das System einzufügen.
   • Nachdem die Eingabe abgeschlossen ist, wird empfohlen, auf die Schaltfläche “Quote synchronisieren” zu klicken. Das System sendet dann eine offizielle Überprüfung der Gültigkeit aller Schlüssel und aktualisiert die Liste der [aktuell verbleibenden Anruferquote].
3. Nutzung überwachenDas Dashboard bietet einen intuitiven Überblick über die Histogramme der Anfragehäufigkeit und die Erfolgsquoten des Systems, während die Seite Logs den spezifischen Zeitverbrauch und den Trefferstatus jedes Suchbefehls festhält, was die Fehlersuche und das Auditing von Anfragen erleichtert.

Richtlinien für den Codezugriff: Transparentes REST-API-Proxy-Modell

Die offengelegte Schnittstellenspezifikation des Systems stimmt mit dem offiziellen Dokument 100% von Tavily überein, was bedeutet, dass bestehende Open-Source-Projekte ohne Kosten migriert werden können.

Die wichtigsten Änderungspunkte:

• Die URL der ursprünglichen Anfrage wird geändert von https://api.tavily.com Ersetzen Sie durch die Adresse Ihrer Einrichtung http://<服务器IP>:8080
• Die Authentifizierungsinformationen werden durch die Master Key

CURL-Test Beispielcode:

curl -X POST "http://<服务器IP>:8080/search" \
-H "Authorization: Bearer <您的_MASTER_KEY>" \
-H "Content-Type: application/json" \
-d '{"query": "2026年最新AI模型架构解析", "search_depth": "basic"}'

Hinweis: Das System ist vollständig kompatibel mit vielen der älteren Übergabekonventionen, unabhängig davon, ob Sie im Payload-Body oder in der {"api_key": "<MASTER_KEY>"} oder am Ende der URL angefügt ?api_key=<MASTER_KEY> Alle können korrekt identifiziert werden.

V. Erweiterte Integration: MCP (Model Context Protocol) Protokollzugang

Eine große Anzahl neuer KI-Produktivitätswerkzeuge (z. B. die Claude Desktop App, VS Code im Cline Plugins usw.) basieren auf dem MCP-Protokoll, um die Möglichkeiten des Werkzeugaufrufs zu erweitern. Dieser Agent ist nativ mit diesem Endpunkt integriert.

Beispiel für die Änderung der VS-Code-Konfiguration (in Verbindung mit mcp-remote):
Fügen Sie den folgenden Serverknoten zu Ihrem VS Code MCP-Profil hinzu:

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

Prinzip der Arbeitsweise: standardmäßig aktiviert MCP_STATELESS=true Die Umgebungsvariable soll es dem Proxy ermöglichen, eine zustandslose Verbindung aufrechtzuerhalten. Da das MCP-Protokoll einen konstanten SSE/WebSocket-Zustand aufrechterhalten soll, kann die netzübergreifende und umgekehrte Proxy-Weiterleitung leicht zu Sitzungs-ID-Trennungen führen, die zu Fehlern führen session not foundIm zustandslosen Modus wird jede Anweisung unabhängig aufgerufen. Im zustandslosen Modus wird jede Anweisung unabhängig voneinander aufgerufen, was die ultimative Stabilität von KI-Tools über lange Verbindungen hinweg garantiert.

Anwendungsszenario

1. Quotenmanagement für AI-Anwendungsentwicklungsteams
   Wenn ein kleines Forschungs- und Entwicklungsteam einen Agenten-Workflow entwickelt, der sich stark auf Suchmaschinen stützt, reicht das Kontingent der offiziellen kostenlosen Version von Tavily nicht aus, um die Debugging-Häufigkeit zu unterstützen. Entwickler können mehrere Testkonten registrieren, um Schlüssel zu erhalten und sie in das System zu injizieren, wodurch fragmentierte Quoten zu einem massiven Quotenpool aggregiert werden, ohne dass der zugrunde liegende Geschäftscode in der Mitte des Prozesses geändert wird.
2. Anti-Blockier- und Wiederholungsstrategien für Geschäftsszenarien mit hoher Parallelität
   Beim Crawlen von Suchergebnissen in großen Stapeln oder bei plötzlichen Aufrufen der Suchfunktion mit hohem Datenverkehr kann ein einzelner Tavily-Schlüssel an ein Ratenlimit stoßen, was zu einem 429-Fehler führt, der den Prozess unterbricht. Durch den Einsatz des Systems als Relay-Layer werden gleichzeitige Blockierungen und Aufgabenausfälle durch den sanften Zufallsstreuungsalgorithmus und den automatischen Failover-Ausgleich bei Fehlern minimiert.
3. Immersive KI-gestützte Programmierung Ökointegration
   Entwickler, die eine IDE lokal verwenden (z. B. Cursor, Beim Schreiben von Code, der die neueste Internetdokumentation mit einem KI-Codierassistenten (VS Code) einbeziehen muss, registrieren Sie einfach die TavilyProxyManager-Adresse mit der IDE unter Verwendung des MCP-Knotens, woraufhin das KI-Modell den Abrufvorgang selbstständig durchführt und der Entwickler in der Lage ist, über das Web-Panel klar zu überprüfen, ob die KI die API übermäßig in Anspruch nimmt, was die Abrechnungstransparenz erhöht.
4. Überwachung der gemeinsamen Anrufschnittstelle auf Unternehmensebene
   Das Intranet des Unternehmens stellt Entwicklern in jeder Abteilung einheitlich einen Hauptschlüssel zur Verfügung, und IT-Administratoren können durch die Überwachung der Nutzungsstatistiken und Protokolldaten im Backend die serverseitigen Skripte mit anormalen Aufrufen in einer Sackgasse ausfindig machen und gleichzeitig automatisch die monatliche Neuschätzung des Kontingents vornehmen, um die Anforderungen der unternehmensweiten Wiederverwendung von Ressourcen und der internen Kontrolle zu erfüllen.

QA

1. Da Tavily offiziell die Schnittstelle häufig aktualisiert (z. B. durch Hinzufügen erweiterter Suchparameter), wird das Proxy-Tool Fehler aufgrund von Inkompatibilität melden?
   A: Es gibt keine Inkompatibilität. Das System folgt der Proxy-Philosophie der “transparenten und nicht-destruktiven Übertragung”, und die Codeschicht greift nur in den Autorisierungskopf und die Proxy-Verteilungslogik ein. Spezifische URL-Pfade, die von Geschäftsanforderungen gesendet werden, und alle benutzerdefinierten Parameter im Anforderungskörper werden ohne Änderungen an die offizielle API weitergeleitet, so dass es immun und vollständig kompatibel mit Upstream-Upgrades ist.
2. Ich kann den Original-Hauptschlüssel nicht über das Terminal finden. Was soll ich tun, und kann das Panel noch angemeldet werden?
   A: Der anfängliche Hauptschlüssel ist der einzige Super Credential für den Fortbestand des Dienstes. Wenn die Konsolenprotokolle regelmäßig überschrieben werden, können Sie den Hauptschlüssel auf der Hostseite /data/proxy.db（Laden Sie die SQLite-Datenbankdatei lokal herunter und verwenden Sie ein Tool wie SQLiteStudio, um sie zu öffnen und die Einstellungstabelle zu überprüfen, um Ihr eigenes benutzerdefiniertes Chiffre-Passwort abzurufen oder zu ändern.
3. Warum schlagen gelegentliche Anfragen fehl oder es kommt zu häufigen Verbindungsabbrüchen beim MCP-Zugriff?
   A: Dies wird in der Regel durch Netzwerkschwankungen verursacht, die zu einer Unterbrechung der Verbindung führen. Es wird empfohlen, zunächst zu bestätigen docker-compose.yml Umgebungsvariable in der MCP_STATELESS=true Wenn Sie eine zusätzliche Schicht von selbst erstellten Gateway-Diensten wie Nginx/Caddy vor dem Proxy-Container haben, stellen Sie sicher, dass das Gateway nicht bestimmte Anfrage-Header abfängt und das SSE-Antwortformat nicht mit Brute-Force-Puffer abschneidet.
4. Wie wird die Abfragestrategie bei verschiedenen Schlüsseln mit demselben Restbetrag gehandhabt?
   A: Wenn das System feststellt, dass mehr als ein verfügbarer Schlüssel denselben Maximalwert hat, überspringt es die einfache sequentielle Zuweisung und verwendet den zugrunde liegenden Random-Shuffle-Algorithmus für die Verteilung. Auf diese Weise wird die feste Route der Anfrage in den ersten paar Schlüsseln und damit ein einziger Punkt, an dem die offizielle Kontrolle der Gleichzeitigkeit pro Sekunde (QPS-Schwelle) berührt wird, weitestgehend vermieden.