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

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

---

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

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

---

## Садржај

- [Зашто користити проксије?](#why-use-proxies)
- [Преглед архитектуре](#architecture-overview)
- [Систем проксија са 4 нивоа](#4-level-proxy-system)
- [Регистар проксија (CRUD)](#proxy-registry-crud)
- [Бесплатно 1proxy тржиште](#1proxy-free-proxy-marketplace)
- [Ротација проксија](#proxy-rotation)
- [Заштита од откривања и прикривеност](#anti-detection--stealth)
- [Режими спољног проксија](#upstream-proxy-modes)
- [Кориснички интерфејс контролне табле](#dashboard-ui)
- [Референца API-ја](#api-reference)
- [Променљиве окружења](#environment-variables)
- [Решавање проблема](#troubleshooting)

---

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

Многи 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-ја:**

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

### Ажурирање проксија

```bash
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` задржаће сачуване вредности.

### Брисање проксија

```bash
# Не успева ако је прокси додељен било ком опсегу
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"
```

### Листање проксија

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

### Додељивање проксија опсезима

```bash
# Додели глобалном опсегу
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}}'
```

### Разрешавање ефективног проксија

Проверите који би прокси био коришћен за дату везу:

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

Враћа разрешени прокси са његовим нивоом (`account`, `provider` или `global`) и извором.

### Групна додела

Доделите један прокси већем броју добављача или веза одједном:

```bash
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](https://github.com/oyi77)** — PR [#1847](https://github.com/diegosouzapw/OmniRoute/pull/1847) (проблем [#1788](https://github.com/diegosouzapw/OmniRoute/issues/1788))

OmniRoute се интегрише са платформом заједнице **[1proxy](https://1proxy-api.aitradepulse.com)** како би омогућио приступ **стотинама бесплатних, проверених проксија** из целог света. Ово је идеално за кориснике који немају сопствену прокси инфраструктуру.

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

```
┌─────────────┐  Синхронизација  ┌─────────────────┐   Ротација   ┌───────────────┐
│  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-ја:**

```bash
# Покрени синхронизацију
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 }
```

### Филтрирање проксија

```bash
# Филтрирај према протоколу
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`
- Неактивни проксији се искључују из ротације

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

```bash
# Ротација према квалитету (најбољи прокси је први) — подразумевано
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 проксија

```bash
# Избриши један 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     |

Конфигуришите за сваког добављача:

```bash
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](./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 не успева

Проверите статус синхронизације:

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

Ако је `consecutiveFailures >= 5`, сигурносни прекидач је активиран. Поново покрените сервер да бисте га ресетовали или сачекајте ручно ресетовање.

---

## Шема базе података

### Табела `proxy_registry`

```sql
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`

```sql
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  | Избегавање учесталог испитивања које би могло да активира ограничења брзине |

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

```ts
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                                              |

### Приступ подацима

```bash
# Недавни догађаји проксија
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-а. Кориснички интерфејс контролне табле може да нуди агрегиране приказе.

### Уобичајени обрасци

**Откривање нестабилног проксија** (наизменично успешни и неуспешни захтеви):

```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):

```sql
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 тржишту већ самостално аутоматски деградира неисправне проксије (погледајте
[Оцене квалитета проксија](#proxy-quality-scores)). За
проксије које сте **ви** додали у регистар, позадински планер провере исправности
(`src/lib/proxyHealth/scheduler.ts`) пружа исто понашање „аутоматског искључивања
неисправног члана из ланца“, без брисања било чега:

```bash
# .env — привремено онемогући прокси након 3 узастопне неуспешне провере и поново га омогући
# аутоматски чим поново почне да одговара на провере.
PROXY_AUTO_DISABLE=true
PROXY_AUTO_REMOVE_AFTER=3
```

Како се ово уклапа у ланац са више проксија:

1. Планер проверава сваки регистровани прокси у интервалу `PROXY_HEALTH_INTERVAL_MS`
   (подразумевано 10 мин; најмање 1 мин).
2. Након `PROXY_AUTO_REMOVE_AFTER` узастопних **недвосмислених** неуспеха (стварни
   неуспех везе — истек времена или сопствени 5xx одговор циља провере никада се не рачунају, погледајте
   [Проверу исправности проксија](#proxy-health-checking-v3816)), `status` проксија
   поставља се на `dead`.
3. `dead` је један од статуса које филтер активних статуса, коришћен при разрешавању
   скупа/ротације, искључује, тако да ротација опсега (редом / насумично / са задржавањем /
   према кашњењу — погледајте [Стабло одлучивања за стратегију ротације](#rotation-strategy-decision-tree))
   одмах престаје да додељује тај прокси новим захтевима. То не утиче ни на један други прокси у
   скупу, а цео скуп никада неприметно не прелази на директну
   везу — погледајте заштиту затвореног отказа у одељку [Систем проксија са 4 нивоа](#4-level-proxy-system).
4. Планер наставља да проверава `dead` проксије у истом интервалу. Прва следећа
   успешна провера враћа `status` на `active`, након чега се прокси поново укључује у ротацију —
   није потребно ручно поновно додавање.

Ово је намерно **опционо и недеструктивно**: планер подразумевано само
броји и евидентира неуспехе (погледајте политику C у `decision.ts`), док `PROXY_AUTO_DISABLE`
никада не брише ред — томе служи засебна, агресивнија
опција `PROXY_AUTO_REMOVE`. Ако су обе постављене на `true`, `PROXY_AUTO_REMOVE`
има предност (нема сврхе привремено онемогућавати прокси који ће бити избрисан). Погледајте
референтни документ [Конфигурација окружења](../reference/ENVIRONMENT.md) за комплетан
списак променљивих.

---

> 📖 **Повезана документација:**
>
> - [Корисничко упутство](../guides/USER_GUIDE.md) — Опште подешавање и конфигурација
> - [API референца](../reference/API_REFERENCE.md) — Комплетна API документација
> - [Конфигурација окружења](../reference/ENVIRONMENT.md) — Све променљиве окружења