OmniRoute/docs/i18n/sr/docs/ops/PROXY_GUIDE.md

🌐 OmniRoute Proxy Guide (Српски)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇱 he · 🇮🇳 hi · 🇭🇷 hr · 🇭🇺 hu · 🇦🇲 hy · 🇮🇩 id · 🇳🇬 ig · 🇮🇹 it · 🇯🇵 ja · 🇬🇪 ka · 🇰🇭 km · 🇮🇳 kn · 🇰🇷 ko · 🇱🇹 lt · 🇱🇻 lv · 🇮🇳 ml · 🇮🇳 mr · 🇲🇾 ms · 🇲🇹 mt · 🇲🇲 my · 🇳🇵 ne · 🇳🇱 nl · 🇳🇴 no · 🇮🇳 or · 🇮🇳 pa · 🇵🇭 phi · 🇵🇱 pl · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇱🇰 si · 🇸🇰 sk · 🇸🇮 sl · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW

---

Заобиђите географске блокаде, заштитите свој идентитет и усмеравајте AI саобраћај преко било ког проксија — без сложене конфигурације.

OmniRoute обухвата потпуно опремљен систем за управљање проксијима који вам омогућава да саобраћај ка спољним AI провајдерима усмеравате преко HTTP, HTTPS или SOCKS5 проксија. Без обзира на то да ли се налазите у блокираном региону, потребна вам је ротација IP адреса или желите прикривено маскирање дигиталног отиска — овај водич покрива све.

---

Садржај

• Зашто користити проксије?
• Преглед архитектуре
• Систем проксија са 4 нивоа
• Регистар проксија (CRUD)
• Бесплатно 1proxy тржиште
• Ротација проксија
• Заштита од откривања и прикривеност
• Режими спољног проксија
• Кориснички интерфејс контролне табле
• Референца API-ја
• Променљиве окружења
• Решавање проблема

---

Зашто користити проксије?

Многи AI провајдери ограничавају приступ према географском региону. Програмери у Русији, Кини, Ирану, Куби, Турској и другим земљама наилазе на грешке попут:

unsupported_country_region_territory

Чак и ван блокираних региона, проксији су корисни за:

Случај употребе	Опис
Заобилажење географских ограничења	Приступ сервисима OpenAI, Anthropic, Codex и Copilot из блокираних земаља
Ротација IP адреса	Расподела захтева на више IP адреса ради избегавања ограничења учесталости
Приватност	Скривање ваше стварне IP адресе од спољних провајдера
Усклађеност	Усмеравање саобраћаја кроз одређене јурисдикције
Тестирање	Симулација захтева из различитих региона

---

Преглед архитектуре

┌───────────────────────────────────────────────────────────────┐
│                       OmniRoute сервер                        │
│                                                               │
│  ┌─────────────┐    ┌──────────────┐    ┌──────────────────┐  │
│  │ Регистар    │    │ Диспечер     │    │ Преузимање      │  │
│  │ проксија    │───▶│ проксија     │───▶│ (undici)         │  │
│  │ (SQLite)    │    │ (кеширано)   │    │                  │  │
│  └─────────────┘    └──────────────┘    └────────┬─────────┘  │
│         ▲                                        │            │
│         │                                        ▼            │
│  ┌──────┴──────┐                        ┌──────────────────┐  │
│  │ 1proxy      │                        │ API спољног      │  │
│  │ синхронизац.│                        │ провајдера       │  │
│  │ (беспл. скуп)│                       │                  │  │
│  └─────────────┘                        └──────────────────┘  │
└───────────────────────────────────────────────────────────────┘

Кључне компоненте

Компонента	Датотека	Улога
Регистар проксија	src/lib/db/proxies.ts	CRUD за уносе проксија и доделе опсега
Диспечер проксија	open-sse/utils/proxyDispatcher.ts	Креира undici ProxyAgent/SOCKS диспечере са кеширањем
Прокси преузимање	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	String	Ознака читљива људима
type	String	Протокол: http, https, socks5
host	String	Име хоста или IP адреса проксија
port	Integer	Број порта
username	String	Корисничко име за аутентификацију (шифровано при складиштењу)
password	String	Лозинка за аутентификацију (шифрована при складиштењу)
region	String	Ознака географског региона
notes	String	Напомене у слободном тексту
status	String	active или inactive
source	String	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. Да бисте вратили конфигурацију, кликните на Увези и отпремите датотеку резервне копије

Регистар проксија такође подржава уметање или ажурирање према host+port — ако увезете прокси који већ постоји (исти хост и порт), он се ажурира уместо да се креира дупликат.

Миграција застареле конфигурације

Ако сте конфигурисали проксије у старијој верзији (пре регистра), OmniRoute их аутоматски мигрира:

Legacy key_value store → proxy_registry + proxy_assignments

Ово се дешава једном, при првом покретању након надоградње. Користите migrateLegacyProxyConfigToRegistry({ force: true }) да бисте поново покренули миграцију.

---

1proxy тржиште бесплатних проксија

🆕 Допринос корисника @oyi77 — PR #1847 (проблем #1788)

OmniRoute се интегрише са платформом заједнице 1proxy како би омогућио приступ стотинама бесплатних, проверених проксија из целог света. Ово је идеално за кориснике који немају сопствену прокси инфраструктуру.

Како функционише

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

1. Синхронизација — OmniRoute преузима проверене проксије из 1proxy API-ја
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}/* и независан је од претходно документованог ланца одлазних проксија.

1proxy API

Метод	Крајња тачка	Опис
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 ово већ обрађује на следеће начине:

• Онемогућавањем одржавања прокси веза активним (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,                            -- провидан/анониман/елитни
  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) открива неисправне проксије за <2s помоћу брзе провере TCP везе, а затим кешира резултат како би се избегло додатно оптерећење при сваком захтеву.

Како функционише

Захтев ──▶ ProxyHealthCache.get(url)
             │
             ├─ Погодак у кешу + свеж?  ──▶ врати кеширани статус
             │
             └─ Промашај у кешу / застарео?  ──▶ TCP повезивање са host:port
                                                  (истек времена: FAST_FAIL_TIMEOUT_MS)
                                                  ──▶ кеширај током HEALTH_CACHE_TTL_MS
                                                  ──▶ врати резултат

Без овога би неисправан прокси блокирао сваки захтев током целог периода PROXY_TIMEOUT_MS (подразумевано 30s) пре него што би захтев био неуспешан.

Подесиве променљиве окружења

Променљива	Подразумевано	Намена
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	ID добављача узводне услуге (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 кашњење > 2s):

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 документација
• Конфигурација окружења — Све променљиве окружења