# 🌐 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) · 🇧🇩 [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) · 🇺🇦 [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. **Ниво на акаунт** — Има ли прокси, зададено на този конкретен идентификатор на връзка?
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. За да възстановите, щракнете върху **Импортиране** и качете архивния файл

Регистърът на прокситата поддържа също **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 на     │ ───────────────▶ │  proxy_registry  │ ────────────▶ │ API на   │
│  1proxy     │  до 500 проксита │  source=oneproxy │  по качество │ доставчик│
└─────────────┘                  └─────────────────┘               └──────────┘
```

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

### 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 (`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`   | Идентификатор на доставчика нагоре по веригата (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) — Всички променливи на средата