🌐 OmniRoute Proxy Guide (Deutsch)

Inhaltsverzeichnis

• Warum Proxys verwenden?
• Architekturübersicht
• 4-stufiges Proxy-System
• Proxy-Registry (CRUD)
• Kostenloser 1proxy-Marktplatz
• Proxy-Rotation
• Anti-Erkennung & Verschleierung
• Vorgelagerte Proxy-Modi
• Dashboard-Oberfläche
• API-Referenz
• Umgebungsvariablen
• Fehlerbehebung

---

Warum Proxys verwenden?

Viele KI-Anbieter beschränken den Zugriff nach geografischer Region. Entwickler in Russland, China, Iran, Kuba, der Türkei und anderen Ländern stoßen auf Fehler wie:

unsupported_country_region_territory

Auch außerhalb gesperrter Regionen sind Proxys für Folgendes nützlich:

Anwendungsfall	Beschreibung
Umgehung geografischer Sperren	Zugriff auf OpenAI, Anthropic, Codex und Copilot aus gesperrten Ländern
IP-Rotation	Anfragen auf mehrere IPs verteilen, um Ratenbegrenzungen zu vermeiden
Datenschutz	Ihre tatsächliche IP-Adresse vor vorgelagerten Anbietern verbergen
Compliance	Datenverkehr durch bestimmte Rechtsräume leiten
Tests	Anfragen aus verschiedenen Regionen simulieren

---

Architekturübersicht

┌───────────────────────────────────────────────────────────────┐
│                       OmniRoute-Server                        │
│                                                               │
│  ┌─────────────┐    ┌──────────────┐    ┌──────────────────┐  │
│  │ Proxy-      │    │ Proxy-       │    │ Proxy-           │  │
│  │ Registry    │───▶│ Dispatcher   │───▶│ Fetch (undici)   │  │
│  │ (SQLite)    │    │ (gecacht)    │    │                  │  │
│  └─────────────┘    └──────────────┘    └────────┬─────────┘  │
│         ▲                                        │            │
│         │                                        ▼            │
│  ┌──────┴──────┐                        ┌──────────────────┐  │
│  │ 1proxy-Sync │                        │ Vorgelagerte     │  │
│  │ (kostenloser│                        │ Anbieter-API     │  │
│  │  Pool)      │                        │                  │  │
│  └─────────────┘                        └──────────────────┘  │
└───────────────────────────────────────────────────────────────┘

Hauptkomponenten

Komponente	Datei	Aufgabe
Proxy-Registry	src/lib/db/proxies.ts	CRUD für Proxy-Einträge und Bereichszuweisungen
Proxy-Dispatcher	open-sse/utils/proxyDispatcher.ts	Erstellt undici-ProxyAgent-/SOCKS-Dispatcher mit Caching
Proxy-Fetch	open-sse/utils/proxyFetch.ts	Umschließt fetch() und bindet einen Proxy-Dispatcher ein
Einstellungsroute	src/app/api/settings/proxy/route.ts	Legacy-API zur Proxy-Konfiguration (GET/PUT/DELETE)
Verwaltungsroute	src/app/api/v1/management/proxies/route.ts	Registry-CRUD-API (GET/POST/PATCH/DELETE)
1proxy-Datenbank	src/lib/db/oneproxy.ts	Persistenz für den kostenlosen Proxy-Marktplatz

---

4-stufiges Proxy-System

OmniRoute unterstützt die Proxy-Konfiguration auf vier unabhängigen Ebenen, die nach Priorität aufgelöst werden:

Prioritätsreihenfolge der Auflösung (höchste → niedrigste):

  1. 🔵 Konto-/Verbindungs-Proxy  →  pro API-Schlüssel/OAuth-Verbindung
  2. 🟡 Anbieter-Proxy            →  pro Anbieter (z. B. gesamter OpenAI-Datenverkehr)
  3. 🟠 Kombinations-Proxy        →  pro Kombinations-/Routing-Konfiguration
  4. 🟢 Globaler Proxy            →  gesamter Datenverkehr, alle Anbieter

Funktionsweise der Auflösung

Wenn OmniRoute eine Anfrage an einen Upstream-Anbieter sendet, ruft es resolveProxyForConnectionFromRegistry() auf, wodurch jede Ebene der Reihe nach geprüft wird:

1. Kontoebene — Ist dieser spezifischen Verbindungs-ID ein Proxy zugewiesen?
2. Anbieterebene — Ist diesem Anbieter (z. B. openai) ein Proxy zugewiesen?
3. Globale Ebene — Ist ein globaler Proxy konfiguriert?
4. Kein Proxy — Direkte Verbindung zum Anbieter.

Der erste Treffer wird verwendet. Das bedeutet, dass Sie einen globalen Proxy als Rückfalloption festlegen und ihn für bestimmte Anbieter oder Verbindungen überschreiben können.

Was über einen Proxy geleitet wird

Datenverkehrstyp	Über Proxy?	Hinweise
Chat-Vervollständigungen	✅	Alle /v1/chat/completions-Anfragen
Einbettungen	✅	/v1/embeddings
Bilderzeugung	✅	/v1/images/generations
Audio (TTS/STT)	✅	/v1/audio/*
OAuth-Token-Austausch	✅	Behebt unsupported_country_region_territory
Verbindungstests	✅	Die Schaltfläche „Verbindung testen“ verwendet den Proxy
Token-Aktualisierung	✅	OAuth-Erneuerung im Hintergrund
Modellsynchronisierung	✅	Modellauflistung und -erkennung

---

Proxy-Registry (CRUD)

Die Proxy-Registry ist eine SQLite-Tabelle (proxy_registry), in der alle Ihre Proxys gespeichert werden. Jeder Proxy verfügt über folgende Felder:

Feld	Typ	Beschreibung
id	UUID	Eindeutige Kennung
name	String	Benutzerfreundliche Bezeichnung
type	String	Protokoll: http, https, socks5
host	String	Proxy-Hostname oder -IP-Adresse
port	Integer	Portnummer
username	String	Benutzername für die Authentifizierung (verschlüsselt gespeichert)
password	String	Passwort für die Authentifizierung (verschlüsselt gespeichert)
region	String	Bezeichnung der geografischen Region
notes	String	Freitextnotizen
status	String	active oder inactive
source	String	manual oder oneproxy

Erstellen eines Proxys

Über das Dashboard:

1. Navigieren Sie zu Einstellungen → Proxy
2. Klicken Sie auf Proxy hinzufügen
3. Geben Sie Typ, Host, Port und optional die Anmeldedaten ein
4. Speichern Sie die Angaben

Über die API:

curl -X POST http://localhost:20128/api/v1/management/proxies \
  -H "Content-Type: application/json" \
  -d '{
    "name": "US Proxy",
    "type": "http",
    "host": "proxy.example.com",
    "port": 8080,
    "username": "user",
    "password": "pass",
    "region": "US"
  }'

Aktualisieren eines Proxys

curl -X PATCH http://localhost:20128/api/v1/management/proxies \
  -H "Content-Type: application/json" \
  -d '{
    "id": "proxy-uuid-here",
    "host": "new-proxy.example.com",
    "port": 9090
  }'

Hinweis: Anmeldedaten bleiben erhalten, sofern Sie nicht ausdrücklich nicht leere Ersatzwerte senden. Wenn Sie leere Zeichenfolgen für username/password senden, bleiben die gespeicherten Werte erhalten.

Löschen eines Proxys

# Schlägt fehl, wenn der Proxy einer Ebene zugewiesen ist
curl -X DELETE "http://localhost:20128/api/v1/management/proxies?id=proxy-uuid"

# Erzwingt das Löschen (entfernt auch Zuweisungen)
curl -X DELETE "http://localhost:20128/api/v1/management/proxies?id=proxy-uuid&force=1"

Auflisten von Proxys

curl "http://localhost:20128/api/v1/management/proxies?limit=50&offset=0"

Zuweisen von Proxys zu Ebenen

# Der globalen Ebene zuweisen
curl -X PUT http://localhost:20128/api/settings/proxy \
  -H "Content-Type: application/json" \
  -d '{"level": "global", "proxy": {"type":"http","host":"proxy.example.com","port":8080}}'

# Einem bestimmten Anbieter zuweisen
curl -X PUT http://localhost:20128/api/settings/proxy \
  -H "Content-Type: application/json" \
  -d '{"level": "provider", "id": "openai", "proxy": {"type":"socks5","host":"socks.example.com","port":1080}}'

# Einer bestimmten Verbindung/einem bestimmten Schlüssel zuweisen
curl -X PUT http://localhost:20128/api/settings/proxy \
  -H "Content-Type: application/json" \
  -d '{"level": "key", "id": "connection-uuid", "proxy": {"type":"http","host":"key-proxy.com","port":3128}}'

Ermitteln des effektiven Proxys

Prüfen Sie, welcher Proxy für eine bestimmte Verbindung verwendet würde:

curl "http://localhost:20128/api/settings/proxy?resolve=connection-uuid"

Gibt den ermittelten Proxy mit seiner Ebene (account, provider oder global) und Quelle zurück.

Massenzuweisung

Weisen Sie einen Proxy gleichzeitig mehreren Anbietern oder Verbindungen zu:

curl -X POST http://localhost:20128/api/v1/management/proxies/bulk-assign \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "provider",
    "scopeIds": ["openai", "anthropic", "codex"],
    "proxyId": "proxy-uuid"
  }'

Import/Export

Proxys sind im Sicherungs-/Wiederherstellungssystem enthalten. Wenn Sie Ihre OmniRoute-Konfiguration exportieren:

1. Navigieren Sie zu Dashboard → Einstellungen → Sicherung
2. Klicken Sie auf Exportieren — die Proxy-Registry und die Zuweisungen sind enthalten
3. Klicken Sie zum Wiederherstellen auf Importieren und laden Sie die Sicherungsdatei hoch

Die Proxy-Registry unterstützt außerdem Upserts anhand von Host+Port — wenn Sie einen bereits vorhandenen Proxy importieren (gleicher Host und Port), wird dieser aktualisiert, anstatt ein Duplikat zu erstellen.

Migration von Altdaten

Wenn Sie Proxys in einer älteren Version (vor Einführung der Registry) konfiguriert haben, migriert OmniRoute diese automatisch:

Veralteter key_value-Speicher → proxy_registry + proxy_assignments

Dies erfolgt einmalig beim ersten Start nach dem Upgrade. Verwenden Sie migrateLegacyProxyConfigToRegistry({ force: true }), um die Migration erneut auszuführen.

---

1proxy – kostenloser Proxy-Marktplatz

🆕 Beigetragen von @oyi77 — PR #1847 (Issue #1788)

OmniRoute ist in die Community-Plattform 1proxy integriert und bietet Zugriff auf Hunderte kostenlose, validierte Proxys aus aller Welt. Dies ist ideal für Benutzer, die keine eigene Proxy-Infrastruktur besitzen.

Funktionsweise

┌─────────────┐  Synchronisieren  ┌─────────────────┐  Rotieren   ┌──────────────┐
│  1proxy API │ ────────────────▶ │  proxy_registry  │ ──────────▶ │ Anbieter-API │
│  (extern)   │   bis zu 500      │  source=oneproxy │  nach       │              │
└─────────────┘    Proxys         └─────────────────┘  Qualität    └──────────────┘

1. Synchronisieren — OmniRoute ruft validierte Proxys von der 1proxy API ab
2. Speichern — Proxys werden in derselben Tabelle proxy_registry mit source = 'oneproxy' gespeichert
3. Filtern — Nach Protokoll, Land und Qualitätsbewertung filtern
4. Rotieren — Den besten Proxy anhand einer qualitätsbasierten, zufälligen oder sequenziellen Strategie auswählen
5. Automatisch herabstufen — Bei fehlgeschlagenen Proxys wird die Qualitätsbewertung reduziert; unterhalb des Schwellenwerts → als inaktiv markiert

Proxys synchronisieren

Über das Dashboard:

1. Navigieren Sie zur Registerkarte Settings → 1proxy
2. Klicken Sie auf „Sync Now“
3. Zeigen Sie Statistiken an: Gesamtzahl der Proxys, Anzahl aktiver Proxys, durchschnittliche Qualität und Aufschlüsselung nach Land

Über die API:

# Synchronisierung auslösen
curl -X POST http://localhost:20128/api/settings/oneproxy \
  -H "Content-Type: application/json" \
  -d '{}'

# Antwort:
# { "success": true, "added": 127, "updated": 45, "failed": 2, "total": 172 }

Proxys filtern

# Nach Protokoll filtern
curl "http://localhost:20128/api/settings/oneproxy?protocol=socks5"

# Nach Land filtern
curl "http://localhost:20128/api/settings/oneproxy?countryCode=US"

# Nach minimaler Qualitätsbewertung filtern
curl "http://localhost:20128/api/settings/oneproxy?minQuality=80"

# Filter kombinieren
curl "http://localhost:20128/api/settings/oneproxy?protocol=http&countryCode=DE&minQuality=70"

Proxy-Qualitätsbewertungen

Jeder Proxy von 1proxy enthält Metadaten:

Feld	Beschreibung
qualityScore	Bewertung von 0–100 aus der 1proxy-Validierung
latencyMs	Gemessene Netzwerklatenz
anonymity	transparent, anonymous oder elite
googleAccess	Gibt an, ob der Proxy auf Google-Dienste zugreifen kann
countryCode	Zweistelliger ISO-Ländercode
lastValidated	Zeitstempel der letzten Validierung

Qualitätsbewertungen werden dynamisch angepasst:

• Fehlgeschlagene Anfragen reduzieren die Bewertung um 10 Punkte
• Bewertung sinkt auf ≤10 → Proxy wird als inactive markiert
• Inaktive Proxys werden von der Rotation ausgeschlossen

Rotationsstrategien

# Nach Qualität rotieren (bester Proxy zuerst) — Standard
curl -X POST http://localhost:20128/api/settings/oneproxy/rotate \
  -H "Content-Type: application/json" \
  -d '{"strategy": "quality"}'

# Zufällige Rotation
curl -X POST http://localhost:20128/api/settings/oneproxy/rotate \
  -d '{"strategy": "random"}'

# Sequenziell (zuletzt am längsten nicht validierter Proxy zuerst)
curl -X POST http://localhost:20128/api/settings/oneproxy/rotate \
  -d '{"strategy": "sequential"}'

Circuit Breaker

Die 1proxy-Synchronisierung verfügt über einen integrierten Circuit Breaker:

• Nach 5 aufeinanderfolgenden Synchronisierungsfehlern werden weitere Synchronisierungsversuche blockiert
• Zurücksetzen mit: resetOneproxyCircuitBreaker() oder durch einen Neustart des Servers
• Der Synchronisierungsstatus ist unter GET /api/settings/oneproxy?action=status verfügbar

1proxy-Proxys löschen

# Einen einzelnen 1proxy-Proxy löschen
curl -X DELETE "http://localhost:20128/api/settings/oneproxy?id=proxy-uuid"

# ALLE 1proxy-Proxys löschen (manuelle Proxys bleiben unberührt)
curl -X DELETE "http://localhost:20128/api/settings/oneproxy?clearAll=1"

---

Schutz vor Erkennung & Tarnung

OmniRoute leitet den Datenverkehr nicht nur über einen Proxy — es lässt ihn auch legitim erscheinen:

TLS-Fingerprint-Spoofing

Verwendet wreq-js, um browserähnliche TLS-Fingerprints zu erzeugen und dadurch Bot-Erkennungssysteme zu umgehen, die TLS-Handshakes von Nicht-Browsern kennzeichnen.

CLI-Fingerprint-Abgleich

Der CLI-Fingerprint-Schalter (Einstellungen → Sicherheit) ordnet HTTP-Header und Felder im JSON-Textkörper neu an, um exakt der Signatur nativer CLI-Binärdateien (Claude Code, Codex usw.) zu entsprechen. Dies funktioniert zusätzlich zum Proxy:

Ihre IP (blockiert) → Proxy-IP (USA) → Anbieter-API
                      + TLS-Spoofing
                      + CLI-Fingerprint

Sie erhalten gleichzeitig sowohl IP-Maskierung als auch Authentizität der Anfragen.

Beibehaltung der Proxy-IP

Farbcodierte Badges im Dashboard zeigen an, welche Proxy-Ebene aktiv ist:

Badge	Ebene	Bedeutung
🟢	Global	Der gesamte Datenverkehr läuft über diesen Proxy
🟡	Anbieter	Nur der Datenverkehr dieses Anbieters wird weitergeleitet
🔵	Verbindung	Dieser spezifische Schlüssel/dieses Konto verwendet diesen Proxy

Das Badge zeigt zur Überprüfung außerdem die aufgelöste Proxy-IP an.

---

Upstream-Proxy-Modi

Für Anbieter, die das CLIProxyAPI-Muster verwenden, unterstützt OmniRoute drei Upstream-Proxy-Modi:

Modus	Beschreibung
native	OmniRoute übernimmt das Proxy-Routing direkt (Standard)
cliproxyapi	Delegiert an eine externe CLIProxyAPI-Instanz
fallback	Versucht zuerst den nativen Modus und greift auf CLIProxyAPI zurück

Konfiguration pro Anbieter:

curl -X PUT "http://localhost:20128/api/upstream-proxy/openai" \
  -H "Content-Type: application/json" \
  -d '{"mode": "native", "enabled": true}'

---

Dashboard-Benutzeroberfläche

Einstellungen → Tab „Proxy“

• Konfiguration des globalen Proxys (einmalig für den gesamten Datenverkehr festlegen)
• Anbieterspezifische Proxy-Überschreibungen
• Verbindungsspezifische Proxy-Zuweisungen
• Verbindungstest über den konfigurierten Proxy
• Farbcodierte Badges, die die aktive Proxy-Ebene anzeigen

Einstellungen → Tab „1proxy“

• Schaltfläche Jetzt synchronisieren, um kostenlose Proxys abzurufen
• Statistikkarten: Gesamt, Aktiv, Durchschnittliche Qualität, Letzte Synchronisierung
• Filter: Protokoll, Ländercode, Mindestqualität
• Proxy-Tabelle mit Host, Protokoll, Land, Qualitätsbewertung, Latenz, Anonymität und Google-Zugriff
• Synchronisierungsstatus mit Nachverfolgung von Erfolgen/Fehlern und Anzahl aufeinanderfolgender Fehler
• Alle löschen, um sämtliche 1proxy-Einträge zu entfernen

---

API-Referenz

API für Proxy-Einstellungen

Methode	Endpunkt	Beschreibung
GET	/api/settings/proxy	Vollständige Proxy-Konfiguration abrufen
GET	/api/settings/proxy?level=global	Globalen Proxy abrufen
GET	/api/settings/proxy?level=provider&id=openai	Anbieter-Proxy abrufen
GET	/api/settings/proxy?resolve=connectionId	Effektiven Proxy auflösen
PUT	/api/settings/proxy	Proxy-Konfiguration aktualisieren
DELETE	/api/settings/proxy?level=provider&id=openai	Proxy auf dieser Ebene entfernen

API für die Proxy-Registrierung

Methode	Endpunkt	Beschreibung
GET	/api/v1/management/proxies	Alle Proxys auflisten
GET	/api/v1/management/proxies?id=uuid	Proxy anhand der ID abrufen
GET	/api/v1/management/proxies?id=uuid&where_used=1	Proxy-Zuweisungen abrufen
POST	/api/v1/management/proxies	Proxy erstellen
PATCH	/api/v1/management/proxies	Proxy aktualisieren
DELETE	/api/v1/management/proxies?id=uuid	Proxy löschen
DELETE	/api/v1/management/proxies?id=uuid&force=1	Löschen erzwingen
POST	/api/v1/management/proxies/bulk-assign	Massenzuweisung durchführen
GET	/api/v1/management/proxies/assignments	Zuweisungen auflisten
GET	/api/v1/management/proxies/health	Proxy-Zustandsstatistiken abrufen

Tunnel-API

Informationen dazu, wie Sie Ihre OmniRoute-Instanz im öffentlichen Internet verfügbar machen können (Cloudflare/ngrok/Tailscale), anstatt ausgehenden Datenverkehr über einen Proxy zu leiten, finden Sie unter TUNNELS_GUIDE.md. Die Tunnel-REST-API befindet sich unter /api/tunnels/{cloudflared,ngrok,tailscale}/* und ist unabhängig von der oben dokumentierten ausgehenden Proxy-Kette.

1proxy-API

Methode	Endpunkt	Beschreibung
GET	/api/settings/oneproxy	1proxy-Proxys auflisten
GET	/api/settings/oneproxy?action=stats	Statistiken und Synchronisierungsstatus abrufen
GET	/api/settings/oneproxy?action=status	Nur den Synchronisierungsstatus abrufen
POST	/api/settings/oneproxy	Synchronisierung auslösen
POST	/api/settings/oneproxy/rotate	Zum nächsten Proxy wechseln
DELETE	/api/settings/oneproxy?id=uuid	Einzelnen Eintrag löschen
DELETE	/api/settings/oneproxy?clearAll=1	Alle Einträge löschen

Upstream-Proxy-API

Methode	Endpunkt	Beschreibung
GET	/api/upstream-proxy/:providerId	Upstream-Proxy-Konfiguration abrufen
PUT	/api/upstream-proxy/:providerId	Upstream-Proxy-Modus festlegen
DELETE	/api/upstream-proxy/:providerId	Upstream-Proxy-Konfiguration entfernen

---

Umgebungsvariablen

Variable	Standardwert	Beschreibung
ENABLE_SOCKS5_PROXY	true	SOCKS5-Proxy-Unterstützung aktivieren (Standardwert true in .env.example)

---

Fehlerbehebung

„SOCKS5-Proxy ist deaktiviert“

Setzen Sie ENABLE_SOCKS5_PROXY=true in Ihrer .env-Datei und starten Sie neu.

„socket hang up“-Fehler bei Verwendung eines Proxys

Dies ist bei günstigen Proxys, die inaktive Verbindungen trennen, normal. OmniRoute behandelt dies bereits folgendermaßen:

• Keep-Alive wird für Proxy-Verbindungen deaktiviert (keepAliveTimeout: 1)
• Pipelining wird deaktiviert (pipelining: 0)
• Dispatcher werden zwischengespeichert, um wiederholte Handshakes zu vermeiden

Falls das Problem weiterhin besteht, verwenden Sie einen anderen Proxy oder die Rotationsfunktion von 1proxy.

„unsupported_country_region_territory“ während OAuth

Stellen Sie sicher, dass der Proxy konfiguriert ist, bevor Sie den OAuth-Ablauf starten. OmniRoute leitet den Austausch von OAuth-Token über den konfigurierten Proxy. Legen Sie zunächst einen globalen oder anbieterspezifischen Proxy fest und stellen Sie anschließend die Verbindung her.

Proxy wird nicht verwendet

Überprüfen Sie die Auflösungsreihenfolge:

1. Prüfen Sie sie mit GET /api/settings/proxy?resolve=your-connection-id
2. Prüfen Sie, ob der Proxy-status auf active (nicht inactive) gesetzt ist
3. Stellen Sie sicher, dass der Geltungsbereich der Proxy-Zuweisung mit Ihrer Verbindung übereinstimmt

1proxy-Synchronisierung schlägt fehl

Prüfen Sie den Synchronisierungsstatus:

curl "http://localhost:20128/api/settings/oneproxy?action=status"

Wenn consecutiveFailures >= 5 gilt, wurde der Schutzschalter ausgelöst. Starten Sie den Server neu, um ihn zurückzusetzen, oder warten Sie auf eine manuelle Zurücksetzung.

---

Datenbankschema

Tabelle proxy_registry

CREATE TABLE proxy_registry (
  id TEXT PRIMARY KEY,
  name TEXT NOT NULL,
  type TEXT NOT NULL DEFAULT 'http',
  host TEXT NOT NULL,
  port INTEGER NOT NULL,
  username TEXT DEFAULT '',
  password TEXT DEFAULT '',
  region TEXT,
  notes TEXT,
  status TEXT DEFAULT 'active',
  source TEXT NOT NULL DEFAULT 'manual',    -- 'manual' oder 'oneproxy'
  quality_score INTEGER,                     -- 0–100 (nur 1proxy)
  latency_ms INTEGER,                        -- Millisekunden (nur 1proxy)
  anonymity TEXT,                            -- transparent/anonymous/elite
  google_access INTEGER DEFAULT 0,           -- Zugriff auf Google möglich? (1proxy)
  last_validated TEXT,                       -- ISO-Zeitstempel (1proxy)
  country_code TEXT,                         -- zweistelliger ISO-Code (1proxy)
  created_at TEXT NOT NULL,
  updated_at TEXT NOT NULL
);

Tabelle proxy_assignments

CREATE TABLE proxy_assignments (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  proxy_id TEXT NOT NULL REFERENCES proxy_registry(id),
  scope TEXT NOT NULL,        -- 'global', 'provider', 'account', 'combo'
  scope_id TEXT,              -- Anbieter-ID, Verbindungs-ID oder Kombinations-ID
  created_at TEXT NOT NULL,
  updated_at TEXT NOT NULL,
  UNIQUE(scope, scope_id)
);

---

Proxy-Zustandsprüfung (v3.8.16+)

Der Proxy-Fast-Fail-Mechanismus von OmniRoute (src/lib/proxyHealth.ts) erkennt nicht erreichbare Proxys durch eine schnelle TCP-Verbindungsprüfung in <2s und speichert das Ergebnis anschließend zwischen, um zusätzlichen Aufwand bei jeder Anfrage zu vermeiden.

Funktionsweise

Anfrage ──▶ ProxyHealthCache.get(url)
             │
             ├─ Cache-Treffer + aktuell?  ──▶ zwischengespeicherten Status zurückgeben
             │
             └─ Cache-Fehltreffer / veraltet?  ──▶ TCP-Verbindung zu host:port herstellen
                                                    (Zeitüberschreitung: FAST_FAIL_TIMEOUT_MS)
                                                    ──▶ für HEALTH_CACHE_TTL_MS zwischenspeichern
                                                    ──▶ Ergebnis zurückgeben

Ohne diesen Mechanismus würde ein nicht erreichbarer Proxy jede Anfrage für die gesamte Dauer von PROXY_TIMEOUT_MS (standardmäßig 30s) blockieren, bevor sie fehlschlägt.

Anpassbare Umgebungsvariablen

Variable	Standardwert	Zweck
PROXY_FAST_FAIL_TIMEOUT_MS	2000	TCP-Verbindungszeitüberschreitung pro Zustandsprüfung
PROXY_HEALTH_CACHE_TTL_MS	30000	Dauer der Zwischenspeicherung eines Zustandsergebnisses

Empfohlene Werte:

Szenario	Fast-Fail-Zeitüberschreitung	Cache-TTL	Begründung
API-Gateway mit hohem Durchsatz	1500ms	60000ms	Aggressives schnelles Fehlschlagen, längerer Cache zur Reduzierung der Prüfungen
Geografisch verteilte Knoten	3000ms	15000ms	Langsamere Netzwerke benötigen mehr Zeit; kürzerer Cache für schnelles Failover
Entwicklung/Test	1000ms	10000ms	Schnelle Iteration mit lokalen Proxys
Tarnung/Erkennungsvermeidung	2500ms	45000ms	Schnelle Abfragen vermeiden, die Ratenbegrenzungen auslösen könnten

Überprüfen des Proxy-Zustands

import { getAllProxyHealthStatuses, invalidateProxyHealth } from "omniroute/proxyHealth";

const statuses = getAllProxyHealthStatuses();
for (const s of statuses) {
  console.log(`${s.proxyUrl} → healthy=${s.healthy}, stale=${s.stale}`);
}

// Erneute Prüfung eines bestimmten Proxys erzwingen
invalidateProxyHealth("http://user:pass@203.0.113.7:8080");

Das Flag stale ist true, wenn der Cache-Eintrag HEALTH_CACHE_TTL_MS überschritten hat und die nächste Anfrage eine erneute Prüfung auslöst.

Standards nach Proxy-Typ

Die Zustandsprüfung verwendet abhängig vom URL-Schema sinnvolle Standardwerte:

Schema	Standardport
http://	8080
https://	443
socks5:// / socks5h://	1080

Benutzerdefinierte Ports in der URL (http://host:9999) haben stets Vorrang vor dem Standardwert des Schemas.

---

Proxy-Analyse & Beobachtbarkeit

OmniRoute erfasst die Nutzung pro Proxy, damit Betreiber Routing-Muster, Latenzspitzen und wiederkehrende Fehler diagnostizieren können.

Erfasste Daten

Für jede Anfrage über einen konfigurierten Proxy zeichnet OmniRoute Folgendes auf:

Metrik	Beschreibung
proxy_url	Vollständige Proxy-URL (Anmeldedaten maskiert)
provider	ID des Upstream-Anbieters (openai, anthropic usw.)
latency_ms	Gesamte Umlaufzeit einschließlich Proxy-Handshake
connect_ms	Nur die Dauer des TCP-Verbindungsaufbaus
status	HTTP-Statuscode vom Upstream
error	Fehlerklasse, falls die Anfrage fehlgeschlagen ist
timestamp	ISO 8601 UTC

Zugriff auf die Daten

# Neueste Proxy-Ereignisse
curl -H "Authorization: Bearer $OMNIROUTE_KEY" \
  "http://localhost:20128/api/usage/proxy-logs?limit=100"

Der tatsächliche Endpunkt ist /api/usage/proxy-logs (siehe src/app/api/usage/proxy-logs/route.ts). Dieser Endpunkt unterstützt:

• GET /api/usage/proxy-logs — Proxy-Protokolle abrufen
• DELETE /api/usage/proxy-logs — alle Proxy-Protokolle löschen

Aggregierte Statistiken können bei Bedarf direkt per SQL aus der Tabelle proxy_logs abgefragt werden. Die Dashboard-Benutzeroberfläche kann aggregierte Ansichten bereitstellen.

Häufige Muster

Einen instabilen Proxy erkennen (wechselt zwischen Erfolg und Fehlschlag):

SELECT proxy_url,
       COUNT(*) AS total,
       SUM(CASE WHEN status >= 500 THEN 1 ELSE 0 END) AS errors,
       ROUND(100.0 * SUM(CASE WHEN status >= 500 THEN 1 ELSE 0 END) / COUNT(*), 1) AS error_pct
FROM proxy_logs
WHERE timestamp > datetime('now', '-1 hour')
GROUP BY proxy_url
HAVING error_pct > 5
ORDER BY error_pct DESC;

Langsame Proxys finden (p95-Latenz > 2 s):

WITH ranked AS (
  SELECT proxy_url, latency_ms,
         PERCENT_RANK() OVER (PARTITION BY proxy_url ORDER BY latency_ms) AS pct
  FROM proxy_logs
  WHERE timestamp > datetime('now', '-24 hour')
)
SELECT proxy_url, latency_ms
FROM ranked
WHERE pct >= 0.95
ORDER BY latency_ms DESC;

---

Entscheidungsbaum für die Rotationsstrategie

Wenn einem Geltungsbereich mehrere Proxys zugewiesen sind, verwendet OmniRoute eine Rotationsstrategie, um auszuwählen, welcher Proxy für die jeweilige Anfrage verwendet wird. Die Strategie wird auf Ebene des Geltungsbereichs konfiguriert (global, pro Anbieter, pro Konto, pro Kombination).

Verfügbare Strategien

Strategie	Empfohlener Einsatzbereich	Abwägung
quality (Standard)	Produktion mit Proxys unterschiedlicher Qualität	Bevorzugt hoch bewertete Proxys; kann niedrig bewertete benachteiligen
random	Lastverteilung, Datenschutz	Gleichmäßige Verteilung; ignoriert Qualitätssignale
sequential	Debugging, deterministische Tests	Durchläuft Proxys der Reihe nach; leicht nachvollziehbar

Entscheidungsbaum

                    Verfügen Ihre Proxys über Qualitätsbewertungen?
                    │
        ┌───────────┴───────────┐
        │                       │
       JA                      NEIN
        │                       │
   Sind alle Proxys            │
   qualitativ ungefähr         │
   gleichwertig?               │
        │                       │
   ┌────┴────┐                  │
   │         │                  │
  JA       NEIN              `random`
   │         │               verwenden
   │         │              (gleichmäßige
   │         │              Verteilung baut
   │         │              mit der Zeit
   │         │              Qualitätsdaten auf)
   │         │
   │    `quality` verwenden
   │    (am besten bei
   │    gemischter Qualität)
   │
`random` verwenden
(Last gleichmäßig
verteilen)

Automatischer Ausschluss ausgefallener eigener Proxys

Der 1proxy-Marktplatz-Pool stuft ausgefallene Proxys bereits automatisch herab (siehe Proxy-Qualitätsbewertungen). Für Proxys, die Sie zur Registry hinzugefügt haben, bietet der Hintergrund-Scheduler für Zustandsprüfungen (src/lib/proxyHealth/scheduler.ts) dasselbe Verhalten zum automatischen Ausschließen eines ausgefallenen Mitglieds aus der Kette, ohne etwas zu löschen:

# .env — einen Proxy nach 3 aufeinanderfolgenden fehlgeschlagenen Prüfungen vorübergehend deaktivieren und
# ihn automatisch wieder aktivieren, sobald er erneut auf Prüfungen antwortet.
PROXY_AUTO_DISABLE=true
PROXY_AUTO_REMOVE_AFTER=3

So funktioniert dies in einer Kette mit mehreren Proxys:

1. Der Scheduler prüft jeden registrierten Proxy alle PROXY_HEALTH_INTERVAL_MS (standardmäßig 10 Min.; mindestens 1 Min.).
2. Nach PROXY_AUTO_REMOVE_AFTER aufeinanderfolgenden eindeutigen Fehlern (einem tatsächlichen Verbindungsfehler – ein Timeout oder ein eigener 5xx-Fehler des Prüfungsziels zählt nie, siehe Proxy-Zustandsprüfung) wird der status des Proxys auf dead gesetzt.
3. dead ist einer der Statuswerte, die der bei der Pool-/Rotationsauflösung verwendete Aktivstatusfilter ausschließt. Daher weist die Rotation eines Geltungsbereichs (Round-Robin / zufällig / persistent / Latenz – siehe Entscheidungsbaum für Rotationsstrategien) diesen Proxy sofort keinen neuen Anfragen mehr zu. Andere Proxys im Pool sind davon nicht betroffen, und der gesamte Pool greift niemals unbemerkt auf eine direkte Verbindung zurück – siehe die Fail-Closed-Schutzvorrichtung im 4-stufigen Proxy-System.
4. Der Scheduler prüft dead-Proxys weiterhin im selben Intervall. Bei der nächsten erfolgreichen Prüfung wird der status wieder auf active gesetzt und der Proxy erneut in die Rotation aufgenommen – ein manuelles erneutes Hinzufügen ist nicht erforderlich.

Dies ist bewusst optional und nicht destruktiv: Standardmäßig zählt und protokolliert der Scheduler lediglich Fehler (siehe Richtlinie C in decision.ts), und PROXY_AUTO_DISABLE löscht niemals eine Zeile – dafür ist das separate, aggressivere Flag PROXY_AUTO_REMOVE vorgesehen. Wenn beide auf true gesetzt sind, hat PROXY_AUTO_REMOVE Vorrang (bei einem Proxy, der ohnehin gelöscht wird, ist eine zwischenzeitliche vorübergehende Deaktivierung nicht sinnvoll). Die vollständige Variablenliste finden Sie in der Referenz zur Umgebungskonfiguration.

---

📖 Verwandte Dokumentation:

• Benutzerhandbuch — Allgemeine Einrichtung und Konfiguration
• API-Referenz — Vollständige API-Dokumentation
• Umgebungskonfiguration — Alle Umgebungsvariablen

---

OmniRoute-Quellcode (a58000c7685f)