🌐 OmniRoute Proxy Guide (Русский)

Содержание

• Зачем использовать прокси?
• Обзор архитектуры
• Четырёхуровневая система прокси
• Реестр прокси (CRUD)
• Бесплатный маркетплейс 1proxy
• Ротация прокси
• Защита от обнаружения и скрытность
• Режимы вышестоящего прокси
• Интерфейс панели управления
• Справочник по API
• Переменные окружения
• Устранение неполадок

---

Зачем использовать прокси?

Многие поставщики ИИ ограничивают доступ по географическому признаку. Разработчики из России, Китая, Ирана, Кубы, Турции и других стран сталкиваются с такими ошибками, как:

unsupported_country_region_territory

Даже за пределами заблокированных регионов прокси полезны в следующих случаях:

Сценарий использования	Описание
Обход геоблокировок	Доступ к OpenAI, Anthropic, Codex и Copilot из заблокированных стран
Ротация IP-адресов	Распределение запросов между несколькими IP-адресами для обхода лимитов
Конфиденциальность	Сокрытие вашего реального IP-адреса от вышестоящих поставщиков
Соответствие требованиям	Маршрутизация трафика через определённые юрисдикции
Тестирование	Имитация запросов из разных регионов

---

Обзор архитектуры

┌───────────────────────────────────────────────────────────────┐
│                       Сервер OmniRoute                        │
│                                                               │
│  ┌─────────────┐    ┌──────────────┐    ┌──────────────────┐  │
│  │ Реестр      │    │ Диспетчер    │    │ Получение       │  │
│  │ прокси      │───▶│ прокси       │───▶│ данных (undici) │  │
│  │ (SQLite)    │    │ (кэшир.)     │    │                  │  │
│  └─────────────┘    └──────────────┘    └────────┬─────────┘  │
│         ▲                                        │            │
│         │                                        ▼            │
│  ┌──────┴──────┐                        ┌──────────────────┐  │
│  │ Синхр. с    │                        │ API вышестоящего │  │
│  │ 1proxy      │                        │ поставщика       │  │
│  │ (беспл. пул)│                        │                  │  │
│  └─────────────┘                        └──────────────────┘  │
└───────────────────────────────────────────────────────────────┘

Ключевые компоненты

Компонент	Файл	Назначение
Реестр прокси	src/lib/db/proxies.ts	CRUD для записей прокси и назначений областей действия
Диспетчер прокси	open-sse/utils/proxyDispatcher.ts	Создаёт ProxyAgent/SOCKS-диспетчеры undici с кэшированием
Прокси-запросы	open-sse/utils/proxyFetch.ts	Оборачивает fetch() с внедрением диспетчера прокси
Маршрут настроек	src/app/api/settings/proxy/route.ts	API устаревшей конфигурации прокси (GET/PUT/DELETE)
Маршрут управления	src/app/api/v1/management/proxies/route.ts	CRUD API реестра (GET/POST/PATCH/DELETE)
БД 1proxy	src/lib/db/oneproxy.ts	Хранение данных бесплатного маркетплейса прокси

---

4-уровневая система прокси

OmniRoute поддерживает настройку прокси на четырёх независимых уровнях, применяемых в порядке приоритета:

Порядок разрешения приоритетов (от высшего к низшему):

  1. 🔵 Прокси учётной записи/подключения  →  для каждого API-ключа / OAuth-подключения
  2. 🟡 Прокси провайдера                  →  для каждого провайдера (например, весь трафик OpenAI)
  3. 🟠 Прокси комбинации                  →  для каждой комбинации/конфигурации маршрутизации
  4. 🟢 Глобальный прокси                  →  весь трафик, все провайдеры

Как работает разрешение

Когда OmniRoute отправляет запрос вышестоящему провайдеру, он вызывает resolveProxyForConnectionFromRegistry(), которая последовательно проверяет каждый уровень:

1. Уровень учётной записи — назначен ли прокси этому конкретному ID подключения?
2. Уровень провайдера — назначен ли прокси этому провайдеру (например, openai)?
3. Глобальный уровень — настроен ли глобальный прокси?
4. Без прокси — прямое подключение к провайдеру.

Используется первое совпадение. Это означает, что можно настроить глобальный прокси как резервный вариант, но переопределить его для отдельных провайдеров или подключений.

Что передаётся через прокси

Тип трафика	Через прокси?	Примечания
Завершения чата	✅	Все запросы /v1/chat/completions
Векторные представления	✅	/v1/embeddings
Генерация изображений	✅	/v1/images/generations
Аудио (TTS/STT)	✅	/v1/audio/*
Обмен OAuth-токена	✅	Устраняет unsupported_country_region_territory
Тесты подключения	✅	Кнопка «Проверить подключение» использует прокси
Обновление токена	✅	Фоновое обновление OAuth
Синхронизация моделей	✅	Получение списка и обнаружение моделей

---

Реестр прокси (CRUD)

Реестр прокси — это таблица SQLite (proxy_registry), в которой хранятся все ваши прокси. Каждый прокси имеет следующие поля:

Поле	Тип	Описание
id	UUID	Уникальный идентификатор
name	Строка	Понятная пользователю метка
type	Строка	Протокол: http, https, socks5
host	Строка	Имя хоста или IP-адрес прокси
port	Целое число	Номер порта
username	Строка	Имя пользователя для аутентификации (зашифровано при хранении)
password	Строка	Пароль для аутентификации (зашифрован при хранении)
region	Строка	Метка географического региона
notes	Строка	Примечания в свободной форме
status	Строка	active или inactive
source	Строка	manual или oneproxy

Создание прокси

Через панель управления:

1. Перейдите в раздел Настройки → Прокси
2. Нажмите Добавить прокси
3. Укажите тип, хост, порт и необязательные учётные данные для аутентификации
4. Сохраните изменения

Через 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"
  }'

Обновление прокси

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
  }'

Примечание: Учётные данные сохраняются, если явно не отправить непустые значения для их замены. При отправке пустых строк в username/password сохранённые значения останутся без изменений.

Удаление прокси

# Завершается ошибкой, если прокси назначен какому-либо уровню
curl -X DELETE "http://localhost:20128/api/v1/management/proxies?id=proxy-uuid"

# Принудительное удаление (также удаляет назначения)
curl -X DELETE "http://localhost:20128/api/v1/management/proxies?id=proxy-uuid&force=1"

Получение списка прокси

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

Назначение прокси уровням

# Назначение глобальному уровню
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}}'

# Назначение конкретному провайдеру
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}}'

# Назначение конкретному подключению/ключу
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}}'

Определение фактически используемого прокси

Проверьте, какой прокси будет использоваться для указанного подключения:

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

Возвращает разрешённый прокси с его уровнем (account, provider или global) и источником.

Массовое назначение

Назначьте один прокси сразу нескольким провайдерам или подключениям:

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"
  }'

Импорт/экспорт

Прокси включаются в систему резервного копирования/восстановления. При экспорте конфигурации OmniRoute:

1. Перейдите в раздел Панель управления → Настройки → Резервное копирование
2. Нажмите Экспорт — реестр прокси и назначения будут включены
3. Для восстановления нажмите Импорт и загрузите файл резервной копии

Реестр прокси также поддерживает upsert по host+port — если импортируемый прокси уже существует (с теми же хостом и портом), он обновляется вместо создания дубликата.

Миграция устаревших данных

Если вы настроили прокси в более старой версии (до появления реестра), OmniRoute автоматически перенесёт их:

Устаревшее хранилище key_value → proxy_registry + proxy_assignments

Это выполняется однократно при первом запуске после обновления. Используйте migrateLegacyProxyConfigToRegistry({ force: true }), чтобы повторно выполнить миграцию.

---

Маркетплейс бесплатных прокси 1proxy

🆕 Добавлено @oyi77 — PR #1847 (задача #1788)

OmniRoute интегрируется с платформой сообщества 1proxy, предоставляя доступ к сотням бесплатных проверенных прокси-серверов со всего мира. Это идеальный вариант для пользователей, у которых нет собственной прокси-инфраструктуры.

Как это работает

┌─────────────┐  Синхронизация  ┌─────────────────┐    Ротация    ┌─────────────┐
│  API 1proxy │ ───────────────▶ │  proxy_registry  │ ────────────▶ │ API провайдера │
│  (внешний)  │   до 500 прокси  │  source=oneproxy │  по качеству  │               │
└─────────────┘                  └─────────────────┘                └─────────────┘

1. Синхронизация — OmniRoute получает проверенные прокси-серверы через API 1proxy
2. Хранение — прокси-серверы сохраняются в той же таблице proxy_registry с source = 'oneproxy'
3. Фильтрация — фильтрация по протоколу, стране и оценке качества
4. Ротация — выбор лучшего прокси-сервера с помощью стратегии по качеству, случайной или последовательной стратегии
5. Автоматическое снижение рейтинга — при сбоях оценка качества прокси-серверов снижается; при падении ниже порогового значения → прокси помечается как неактивный

Синхронизация прокси-серверов

Через панель управления:

1. Перейдите на вкладку Настройки → 1proxy
2. Нажмите «Синхронизировать сейчас»
3. Просмотрите статистику: общее количество прокси-серверов, количество активных, среднее качество и распределение по странам

Через API:

# Запуск синхронизации
curl -X POST http://localhost:20128/api/settings/oneproxy \
  -H "Content-Type: application/json" \
  -d '{}'

# Ответ:
# { "success": true, "added": 127, "updated": 45, "failed": 2, "total": 172 }

Фильтрация прокси-серверов

# Фильтрация по протоколу
curl "http://localhost:20128/api/settings/oneproxy?protocol=socks5"

# Фильтрация по стране
curl "http://localhost:20128/api/settings/oneproxy?countryCode=US"

# Фильтрация по минимальной оценке качества
curl "http://localhost:20128/api/settings/oneproxy?minQuality=80"

# Объединение фильтров
curl "http://localhost:20128/api/settings/oneproxy?protocol=http&countryCode=DE&minQuality=70"

Оценки качества прокси-серверов

Каждый прокси-сервер 1proxy содержит метаданные:

Поле	Описание
qualityScore	Оценка от 0 до 100 по результатам проверки 1proxy
latencyMs	Измеренная задержка сети
anonymity	transparent, anonymous или elite
googleAccess	Может ли прокси-сервер обращаться к сервисам Google
countryCode	Двухбуквенный код страны ISO
lastValidated	Временная метка последней проверки

Оценки качества корректируются динамически:

• Неудачные запросы снижают оценку на 10 баллов
• Оценка падает до ≤10 → прокси-сервер помечается как inactive
• Неактивные прокси-серверы исключаются из ротации

Стратегии ротации

# Ротация по качеству (сначала лучший прокси-сервер) — по умолчанию
curl -X POST http://localhost:20128/api/settings/oneproxy/rotate \
  -H "Content-Type: application/json" \
  -d '{"strategy": "quality"}'

# Случайная ротация
curl -X POST http://localhost:20128/api/settings/oneproxy/rotate \
  -d '{"strategy": "random"}'

# Последовательная ротация (сначала прокси, проверенный раньше остальных)
curl -X POST http://localhost:20128/api/settings/oneproxy/rotate \
  -d '{"strategy": "sequential"}'

Автоматический выключатель

Синхронизация с 1proxy оснащена встроенным автоматическим выключателем:

• После 5 последовательных сбоев синхронизации дальнейшие попытки синхронизации блокируются
• Сброс выполняется с помощью resetOneproxyCircuitBreaker() или перезапуска сервера
• Статус синхронизации доступен по адресу GET /api/settings/oneproxy?action=status

Удаление прокси-серверов 1proxy

# Удаление одного прокси-сервера 1proxy
curl -X DELETE "http://localhost:20128/api/settings/oneproxy?id=proxy-uuid"

# Удаление ВСЕХ прокси-серверов 1proxy (добавленные вручную прокси не затрагиваются)
curl -X DELETE "http://localhost:20128/api/settings/oneproxy?clearAll=1"

---

Защита от обнаружения и скрытность

OmniRoute не просто направляет трафик через прокси — он делает его похожим на легитимный:

Подмена TLS-отпечатка

Использует wreq-js для создания TLS-отпечатков, характерных для браузеров, обходя системы обнаружения ботов, которые помечают TLS-рукопожатия, не похожие на браузерные.

Соответствие отпечатку CLI

Переключатель отпечатка CLI (Настройки → Безопасность) изменяет порядок HTTP-заголовков и полей тела JSON так, чтобы они точно соответствовали сигнатуре нативных CLI-приложений (Claude Code, Codex и т. д.). Эта функция работает поверх прокси:

Ваш IP (заблокирован) → IP прокси (США) → API провайдера
                         + подмена TLS
                         + отпечаток CLI

Таким образом, вы одновременно получаете маскировку IP-адреса и аутентичность запросов.

Сохранение IP-адреса прокси

Цветные индикаторы на панели управления показывают активный уровень прокси:

Индикатор	Уровень	Значение
🟢	Глобальный	Весь трафик проходит через этот прокси
🟡	Провайдер	Через прокси проходит только трафик этого провайдера
🔵	Подключение	Этот конкретный ключ или аккаунт использует этот прокси

Индикатор также отображает определённый IP-адрес прокси для проверки.

---

Режимы вышестоящего прокси

Для провайдеров, использующих шаблон CLIProxyAPI, OmniRoute поддерживает три режима вышестоящего прокси:

Режим	Описание
native	OmniRoute обрабатывает маршрутизацию через прокси напрямую (по умолчанию)
cliproxyapi	Делегирует обработку внешнему экземпляру CLIProxyAPI
fallback	Сначала использует нативный режим, а при сбое — CLIProxyAPI

Настройка для каждого провайдера:

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

---

Интерфейс панели управления

Настройки → Вкладка «Прокси»

• Настройка глобального прокси (одна настройка для всего трафика)
• Переопределения прокси для отдельных провайдеров
• Назначение прокси для отдельных подключений
• Проверка подключения через настроенный прокси
• Цветные индикаторы, показывающие активный уровень прокси

Настройки → Вкладка «1proxy»

• Кнопка Синхронизировать сейчас для получения бесплатных прокси
• Карточки статистики: всего, активных, среднее качество, последняя синхронизация
• Фильтры: протокол, код страны, минимальное качество
• Таблица прокси с хостом, протоколом, страной, оценкой качества, задержкой, анонимностью и доступом к Google
• Панель состояния синхронизации с отслеживанием успешных и неудачных попыток, а также количества последовательных сбоев
• Очистить всё для удаления всех записей 1proxy

---

Справочник API

API настроек прокси

Метод	Конечная точка	Описание
GET	/api/settings/proxy	Получить полную конфигурацию прокси
GET	/api/settings/proxy?level=global	Получить глобальный прокси
GET	/api/settings/proxy?level=provider&id=openai	Получить прокси провайдера
GET	/api/settings/proxy?resolve=connectionId	Определить действующий прокси
PUT	/api/settings/proxy	Обновить конфигурацию прокси
DELETE	/api/settings/proxy?level=provider&id=openai	Удалить прокси на указанном уровне

API реестра прокси

Метод	Конечная точка	Описание
GET	/api/v1/management/proxies	Получить список всех прокси
GET	/api/v1/management/proxies?id=uuid	Получить прокси по ID
GET	/api/v1/management/proxies?id=uuid&where_used=1	Получить назначения прокси
POST	/api/v1/management/proxies	Создать прокси
PATCH	/api/v1/management/proxies	Обновить прокси
DELETE	/api/v1/management/proxies?id=uuid	Удалить прокси
DELETE	/api/v1/management/proxies?id=uuid&force=1	Принудительно удалить прокси
POST	/api/v1/management/proxies/bulk-assign	Массово назначить прокси
GET	/api/v1/management/proxies/assignments	Получить список назначений
GET	/api/v1/management/proxies/health	Получить статистику состояния прокси

API туннелей

Информацию о публикации экземпляра OmniRoute в интернете (через Cloudflare/ngrok/Tailscale) вместо маршрутизации исходящего трафика через прокси см. в TUNNELS_GUIDE.md. REST API туннелей находится по адресу /api/tunnels/{cloudflared,ngrok,tailscale}/* и не зависит от описанной выше цепочки исходящих прокси.

API 1proxy

Метод	Конечная точка	Описание
GET	/api/settings/oneproxy	Получить список прокси 1proxy
GET	/api/settings/oneproxy?action=stats	Получить статистику и состояние синхронизации
GET	/api/settings/oneproxy?action=status	Получить только состояние синхронизации
POST	/api/settings/oneproxy	Запустить синхронизацию
POST	/api/settings/oneproxy/rotate	Переключиться на следующий прокси
DELETE	/api/settings/oneproxy?id=uuid	Удалить один прокси
DELETE	/api/settings/oneproxy?clearAll=1	Очистить всё

API вышестоящего прокси

Метод	Конечная точка	Описание
GET	/api/upstream-proxy/:providerId	Получить конфигурацию вышестоящего прокси
PUT	/api/upstream-proxy/:providerId	Задать режим вышестоящего прокси
DELETE	/api/upstream-proxy/:providerId	Удалить конфигурацию вышестоящего прокси

---

Переменные среды

Переменная	По умолчанию	Описание
ENABLE_SOCKS5_PROXY	true	Включает поддержку прокси SOCKS5 (по умолчанию true в .env.example)

---

Устранение неполадок

«Прокси SOCKS5 отключён»

Установите ENABLE_SOCKS5_PROXY=true в файле .env и перезапустите приложение.

Ошибки «socket hang up» при работе через прокси

Это нормально для дешёвых прокси, которые разрывают неактивные соединения. OmniRoute уже обрабатывает такие ситуации следующим образом:

• Отключает keep-alive для прокси-соединений (keepAliveTimeout: 1)
• Отключает конвейерную обработку (pipelining: 0)
• Кэширует диспетчеры, чтобы избежать повторных рукопожатий

Если проблема сохраняется, попробуйте другой прокси или используйте функцию ротации 1proxy.

«unsupported_country_region_territory» во время OAuth

Убедитесь, что прокси настроен до запуска процесса OAuth. OmniRoute направляет обмен токенами OAuth через настроенный прокси. Сначала задайте глобальный прокси или прокси на уровне провайдера, а затем подключитесь.

Прокси не используется

Проверьте порядок разрешения:

1. Выполните проверку с помощью GET /api/settings/proxy?resolve=your-connection-id
2. Убедитесь, что status прокси имеет значение active (а не inactive)
3. Убедитесь, что область назначения прокси соответствует вашему подключению

Ошибка синхронизации 1proxy

Проверьте состояние синхронизации:

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

Если consecutiveFailures >= 5, сработал автоматический выключатель. Перезапустите сервер для сброса состояния или дождитесь ручного сброса.

---

Схема базы данных

Таблица 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' или 'oneproxy'
  quality_score INTEGER,                     -- 0–100 (только для 1proxy)
  latency_ms INTEGER,                        -- миллисекунды (только для 1proxy)
  anonymity TEXT,                            -- transparent/anonymous/elite
  google_access INTEGER DEFAULT 0,           -- доступен ли Google? (1proxy)
  last_validated TEXT,                       -- временная метка ISO (1proxy)
  country_code TEXT,                         -- двухбуквенный код ISO (1proxy)
  created_at TEXT NOT NULL,
  updated_at TEXT NOT NULL
);

Таблица 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,              -- ID провайдера, ID подключения или ID комбинации
  created_at TEXT NOT NULL,
  updated_at TEXT NOT NULL,
  UNIQUE(scope, scope_id)
);

---

Проверка работоспособности прокси (v3.8.16+)

Механизм быстрого отказа прокси OmniRoute (src/lib/proxyHealth.ts) обнаруживает неработающие прокси менее чем за 2 секунды с помощью быстрой проверки TCP-соединения, а затем кэширует результат, чтобы избежать дополнительных затрат при каждом запросе.

Как это работает

Request ──▶ ProxyHealthCache.get(url)
             │
             ├─ Cache hit + fresh?  ──▶ return cached status
             │
             └─ Cache miss / stale?  ──▶ TCP connect to host:port
                                          (timeout: FAST_FAIL_TIMEOUT_MS)
                                          ──▶ cache for HEALTH_CACHE_TTL_MS
                                          ──▶ return result

Без этого неработающий прокси блокировал бы каждый запрос на всё время PROXY_TIMEOUT_MS (по умолчанию 30 секунд), прежде чем завершиться ошибкой.

Настраиваемые переменные среды

Переменная	По умолчанию	Назначение
PROXY_FAST_FAIL_TIMEOUT_MS	2000	Тайм-аут TCP-соединения для каждой проверки состояния
PROXY_HEALTH_CACHE_TTL_MS	30000	Время кэширования результата проверки состояния

Рекомендуемые значения:

Сценарий	Тайм-аут быстрого отказа	TTL кэша	Обоснование
API-шлюз с высокой нагрузкой	1500ms	60000ms	Агрессивный быстрый отказ и более длительное кэширование для сокращения проверок
Геораспределённые узлы	3000ms	15000ms	Медленным сетям требуется больше времени; короткий кэш ускоряет переключение
Разработка / тестирование	1000ms	10000ms	Быстрые итерации при работе с локальными прокси
Скрытность / защита от обнаружения	2500ms	45000ms	Предотвращает частые проверки, которые могут активировать ограничения частоты

Проверка состояния прокси

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

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

// Принудительно повторно проверить определённый прокси
invalidateProxyHealth("http://user:pass@203.0.113.7:8080");

Флаг stale имеет значение true, если срок хранения записи в кэше превысил HEALTH_CACHE_TTL_MS, и следующий запрос запустит новую проверку.

Значения по умолчанию для типов прокси

При проверке состояния используются подходящие значения по умолчанию в зависимости от схемы URL:

Схема	Порт по умолчанию
http://	8080
https://	443
socks5:// / socks5h://	1080

Пользовательские порты в URL (http://host:9999) всегда имеют приоритет над портом по умолчанию для схемы.

---

Аналитика и наблюдаемость прокси

OmniRoute отслеживает использование каждого прокси, чтобы помочь операторам диагностировать особенности маршрутизации, всплески задержек и повторяющиеся сбои.

Что отслеживается

Для каждого запроса, проходящего через настроенный прокси, OmniRoute регистрирует:

Метрика	Описание
proxy_url	Полный URL прокси (учётные данные скрыты)
provider	Идентификатор вышестоящего провайдера (openai, anthropic и т. д.)
latency_ms	Общее время прохождения запроса и ответа, включая установление соединения с прокси
connect_ms	Только время установления TCP-соединения
status	Код состояния HTTP от вышестоящего сервера
error	Класс ошибки, если запрос завершился неудачно
timestamp	Время в формате ISO 8601 UTC

Доступ к данным

# Последние события прокси
curl -H "Authorization: Bearer $OMNIROUTE_KEY" \
  "http://localhost:20128/api/usage/proxy-logs?limit=100"

Фактическая конечная точка — /api/usage/proxy-logs (см. src/app/api/usage/proxy-logs/route.ts). Эта конечная точка поддерживает:

• GET /api/usage/proxy-logs — получить журналы прокси
• DELETE /api/usage/proxy-logs — очистить все журналы прокси

При необходимости агрегированную статистику можно получить напрямую из таблицы proxy_logs с помощью SQL. Интерфейс панели мониторинга также может предоставлять агрегированные представления.

Распространённые сценарии

Обнаружение нестабильного прокси (поочерёдно завершается успешно и с ошибкой):

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;

Поиск медленных прокси (задержка p95 > 2 с):

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;

---

Дерево выбора стратегии ротации

Когда одной области назначено несколько прокси, OmniRoute использует стратегию ротации, чтобы определить, какой из них применять для каждого запроса. Стратегия настраивается на уровне области (глобально, для отдельного провайдера, отдельной учётной записи или отдельной комбинации).

Доступные стратегии

Стратегия	Когда использовать	Компромисс
quality (по умолчанию)	Рабочая среда с прокси разного качества	Отдаёт предпочтение прокси с высоким рейтингом; прокси с низким рейтингом могут не получать трафик
random	Распределение нагрузки, конфиденциальность	Равномерное распределение; показатели качества игнорируются
sequential	Отладка, детерминированное тестирование	Перебирает прокси по порядку; поведение легко анализировать

Дерево решений

                    Есть ли у ваших прокси оценки качества?
                    │
        ┌───────────┴───────────┐
        │                       │
       ДА                      НЕТ
        │                       │
   Все ли прокси                │
   примерно одинаковы          │
   по качеству?                 │
        │                       │
   ┌────┴────┐                  │
   │         │                  │
  ДА        НЕТ          Используйте
   │         │              `random`
   │         │             (равномерное
   │         │            распределение
   │         │            со временем
   │         │          сформирует данные
   │         │             о качестве)
   │         │
   │    Используйте `quality`
   │      (оптимально для
   │    разного качества)
   │
Используйте `random`
(распределяйте нагрузку
равномерно)

Автоматическое исключение сбоев для ваших собственных прокси

Пул маркетплейса 1proxy уже автоматически понижает приоритет неисправных прокси (см. Оценки качества прокси). Для прокси, которые вы добавили в реестр, фоновый планировщик проверок состояния (src/lib/proxyHealth/scheduler.ts) обеспечивает аналогичное поведение — «автоматически исключить неработающий узел из цепочки», ничего при этом не удаляя:

# .env — программно отключить прокси после 3 последовательных неудачных проверок и
# автоматически включить его снова, как только он начнет отвечать на проверки.
PROXY_AUTO_DISABLE=true
PROXY_AUTO_REMOVE_AFTER=3

Как это работает в цепочке из нескольких прокси:

1. Планировщик проверяет каждый зарегистрированный прокси через каждые PROXY_HEALTH_INTERVAL_MS (по умолчанию — 10 мин; минимум — 1 мин).
2. После PROXY_AUTO_REMOVE_AFTER последовательных однозначных сбоев (реальный сбой подключения — тайм-аут или собственный ответ 5xx от целевого адреса проверки никогда не учитывается, см. Проверка состояния прокси) значение status прокси устанавливается в dead.
3. dead — один из статусов, исключаемых фильтром активных состояний, который используется при разрешении пула/ротации, поэтому ротация области действия (по кругу / случайная / закрепленная / по задержке — см. Дерево выбора стратегии ротации) немедленно перестает назначать этот прокси новым запросам. Это не влияет на другие прокси в пуле, и весь пул никогда незаметно не переключается на прямое подключение — см. защиту с запретом открытого отказа в разделе 4-уровневая система прокси.
4. Планировщик продолжает проверять прокси со статусом dead с тем же интервалом. Следующая успешная проверка возвращает status в значение active, и прокси снова включается в ротацию — повторное добавление вручную не требуется.

Эта функция намеренно сделана опциональной и неразрушающей: по умолчанию планировщик только подсчитывает и регистрирует сбои (см. политику C в decision.ts), а PROXY_AUTO_DISABLE никогда не удаляет строку — для этого предназначен отдельный, более агрессивный флаг PROXY_AUTO_REMOVE. Если оба параметра установлены в true, приоритет имеет PROXY_AUTO_REMOVE (нет смысла программно отключать прокси перед его удалением). Полный список переменных см. в справочнике Конфигурация окружения.

---

📖 Связанная документация:

• Руководство пользователя — Общая установка и настройка
• Справочник API — Полная документация API
• Конфигурация окружения — Все переменные окружения

---

Исходный код OmniRoute (a58000c7685f)