# 🌐 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) · 🇷🇸 [sr](../../../sr/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) · 🇵🇰 [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)

---

> **Обходьте географічні блокування, захищайте свою особу та спрямовуйте трафік ШІ через будь-який проксі — без жодних складнощів із налаштуванням.**

OmniRoute містить повнофункціональну систему керування проксі, яка дає змогу спрямовувати трафік до зовнішніх постачальників ШІ через проксі 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)

---

## Навіщо використовувати проксі?

Багато постачальників ШІ обмежують доступ за географічним регіоном. Розробники в **Росії, Китаї, Ірані, Кубі, Туреччині** та інших країнах стикаються з такими помилками:

```
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`          | Створює диспетчери `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` | API CRUD реєстру (GET/POST/PATCH/DELETE)                   |
| **БД 1proxy**              | `src/lib/db/oneproxy.ts`                     | Зберігання даних безкоштовного маркетплейсу проксі         |

---

## Стандартний стан проксі для нових облікових записів

в** Налаштування → Проксі → Глобальна конфігурація** , використання** Увімкнути проксі за замовчуванням для нових підключень** щоб вибрати початковий стан проксі для щойно доданих облікових записів постачальників.

Нове налаштування контролює початковий стан проксі-сервера щойно доданих облікових записів постачальників. Він не змінює існуючі облікові записи та не замінює глобальний перемикач проксі. Його початкове значення зберігає попередню поведінку. Вимкніть його один раз, щоб у майбутньому створювати облікові записи з вимкненим проксі-сервером за замовчуванням.

Параметри зберігаються як `defaultNewConnectionProxyEnabled` через наявні налаштування API. За замовчуванням встановлено `true` якщо ніколи не зберігається. Збереження `false` набуває чинності для наступних нових облікових записів без перезапуску. `POST /api/providers` приймає необов'язковий суворий логічний `proxyEnabled`; явний `true` або `false` має пріоритет над значенням за замовчуванням створення. Пропуск повторного облікового запису або повторне підключення OAuth зберігає збережений стан цього облікового запису. Окремі облікові записи можна буде ввімкнути або вимкнути пізніше.

Вибіркові передачі постачальників використовують параметри цільової інсталяції за замовчуванням для нових облікових записів і зберігають цільову політику під час заміни існуючих облікових записів. Перемикачі проксі не є переносними полями передачі. Повне відновлення резервної копії та історична міграція JSON/SQL зберігають свою існуючу семантику відновлення, включаючи збережені значення облікового запису та стандартні налаштування застарілої схеми; повне відновлення налаштувань також може відновити це налаштування.

Це налаштування не призначає проксі-сервер і не встановлює, що він справний чи використовується. Фактична маршрутизація все ще залежить від глобального перемикача проксі та відповідної конфігурації проксі. Синтетичні постачальники без постійного облікового запису, трафік OAuth до створення облікового запису, проксі-сервери environment/system і зовнішні серверні мережі не входять до його сфери.

## 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:**

```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. Щоб відновити дані, натисніть **Імпортувати** та завантажте файл резервної копії

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

### Міграція зі старої версії

Якщо ви налаштували проксі в попередній версії (до появи реєстру), OmniRoute автоматично перенесе їх:

```
Застаріле сховище key_value → 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)**, надаючи доступ до **сотень безкоштовних перевірених проксі** з усього світу. Це ідеальний варіант для користувачів, які не мають власної проксі-інфраструктури.

### Як це працює

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

1. **Синхронізація** — OmniRoute отримує перевірені проксі з API 1proxy
2. **Збереження** — Проксі зберігаються в тій самій таблиці `proxy_registry` із `source = 'oneproxy'`
3. **Фільтрація** — Фільтрування за протоколом, країною та оцінкою якості
4. **Ротація** — Вибір найкращого проксі за допомогою стратегій на основі якості, випадкового або послідовного вибору
5. **Автоматичне зниження рейтингу** — Для проксі, що завершилися помилкою, оцінка якості знижується; нижче порогового значення → позначаються як неактивні

### Синхронізація проксі

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

1. Перейдіть на вкладку **Settings → 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}/*`, і він не залежить від описаного вище ланцюжка вихідних проксі.

### 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

Перевірте стан синхронізації:

```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,                            -- transparent/anonymous/elite
  google_access INTEGER DEFAULT 0,           -- чи є доступ до Google? (1proxy)
  last_validated TEXT,                       -- часова позначка ISO (1proxy)
  country_code TEXT,                         -- 2-літерний код 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`) виявляє непрацюючі проксі менш ніж за 2 с за допомогою швидкої перевірки TCP-з’єднання, а потім **кешує результат**, щоб уникнути накладних витрат для кожного запиту.

### Як це працює

```
Запит ──▶ ProxyHealthCache.get(url)
           │
           ├─ Є актуальне значення в кеші? ──▶ повернути кешований стан
           │
           └─ Немає в кеші / застаріло?     ──▶ TCP-з’єднання з host:port
                                                  (тайм-аут: FAST_FAIL_TIMEOUT_MS)
                                                  ──▶ кешувати на HEALTH_CACHE_TTL_MS
                                                  ──▶ повернути результат
```

Без цього непрацюючий проксі блокував би кожен запит протягом усього часу `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  | Уникнення частого зондування, яке може спричинити обмеження частоти запитів          |

### Перевірка стану проксі

```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`   | Ідентифікатор провайдера вищого рівня (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 > 2 с):

```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) — Усі змінні середовища