# 🌐 OmniRoute Proxy Guide (Kiswahili)

🌐 **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) · 🇮🇳 [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)

---

> **Pita vizuizi vya kijiografia, linda utambulisho wako, na pitisha trafiki ya AI kupitia proksi yoyote — bila utata wowote wa usanidi.**

OmniRoute inajumuisha mfumo kamili wa usimamizi wa proksi unaokuwezesha kupitisha trafiki ya watoa huduma wa AI wa upande wa juu kupitia proksi za HTTP, HTTPS, au SOCKS5. Iwe uko katika eneo lililozuiwa, unahitaji ubadilishaji wa IP, au unataka ufichaji wa alama za utambulisho — mwongozo huu unashughulikia kila kitu.

---

## Yaliyomo

- [Kwa Nini Utumie Proksi?](#why-use-proxies)
- [Muhtasari wa Usanifu](#architecture-overview)
- [Mfumo wa Proksi wa Viwango 4](#4-level-proxy-system)
- [Rejista ya Proksi (CRUD)](#proxy-registry-crud)
- [Soko Lisilolipishwa la 1proxy](#1proxy-free-proxy-marketplace)
- [Ubadilishaji wa Proksi](#proxy-rotation)
- [Kuzuia Ugunduzi na Ufichaji](#anti-detection--stealth)
- [Hali za Proksi ya Upande wa Juu](#upstream-proxy-modes)
- [Kiolesura cha Dashibodi](#dashboard-ui)
- [Marejeleo ya API](#api-reference)
- [Vigezo vya Mazingira](#environment-variables)
- [Utatuzi wa Matatizo](#troubleshooting)

---

## Kwa Nini Utumie Proksi?

Watoa huduma wengi wa AI huzuia ufikiaji kulingana na eneo la kijiografia. Wasanidi programu nchini **Urusi, Uchina, Iran, Kuba, Uturuki**, na nchi nyingine hukumbana na hitilafu kama:

```
unsupported_country_region_territory
```

Hata nje ya maeneo yaliyozuiwa, proksi zinafaa kwa:

| Hali ya Matumizi                   | Maelezo                                                                      |
| ---------------------------------- | ---------------------------------------------------------------------------- |
| **Kupita vizuizi vya kijiografia** | Fikia OpenAI, Anthropic, Codex, Copilot kutoka nchi zilizozuiwa              |
| **Ubadilishaji wa IP**             | Sambaza maombi kwenye IP nyingi ili kuepuka vizuizi vya kiwango cha matumizi |
| **Faragha**                        | Ficha IP yako halisi dhidi ya watoa huduma wa upande wa juu                  |
| **Uzingatiaji**                    | Pitisha trafiki kupitia maeneo mahususi ya mamlaka                           |
| **Majaribio**                      | Iga maombi kutoka maeneo tofauti                                             |

---

## Muhtasari wa Usanifu

```
┌───────────────────────────────────────────────────────────────┐
│                       Seva ya OmniRoute                       │
│                                                               │
│  ┌─────────────┐    ┌──────────────┐    ┌──────────────────┐  │
│  │ Rejista ya  │    │ Kisambazaji  │    │ Uchotaji         │  │
│  │ Proksi      │───▶│ cha Proksi   │───▶│ (undici)         │  │
│  │ (SQLite)    │    │ (akiba)      │    │                  │  │
│  └─────────────┘    └──────────────┘    └────────┬─────────┘  │
│         ▲                                        │            │
│         │                                        ▼            │
│  ┌──────┴──────┐                        ┌──────────────────┐  │
│  │ Ulandanishi │                        │ API ya Mtoa      │  │
│  │ wa 1proxy   │                        │ Huduma wa Juu    │  │
│  │ (hazina ya  │                        │                  │  │
│  │  bure)      │                        │                  │  │
│  └─────────────┘                        └──────────────────┘  │
└───────────────────────────────────────────────────────────────┘
```

### Vipengele Muhimu

| Kipengele                  | Faili                                        | Jukumu                                                             |
| -------------------------- | -------------------------------------------- | ------------------------------------------------------------------ |
| **Rejista ya Proksi**      | `src/lib/db/proxies.ts`                      | CRUD ya maingizo ya proksi pamoja na ugawaji wa mawanda            |
| **Kisambazaji cha Proksi** | `open-sse/utils/proxyDispatcher.ts`          | Huunda visambazaji vya `undici` ProxyAgent/SOCKS kwa kutumia akiba |
| **Uchotaji wa Proksi**     | `open-sse/utils/proxyFetch.ts`               | Hufunika `fetch()` kwa kuingiza kisambazaji cha proksi             |
| **Njia ya Mipangilio**     | `src/app/api/settings/proxy/route.ts`        | API ya usanidi wa proksi ya zamani (GET/PUT/DELETE)                |
| **Njia ya Usimamizi**      | `src/app/api/v1/management/proxies/route.ts` | API ya CRUD ya rejista (GET/POST/PATCH/DELETE)                     |
| **DB ya 1proxy**           | `src/lib/db/oneproxy.ts`                     | Uhifadhi endelevu wa soko la proksi lisilolipishwa                 |

---

## Mfumo wa Proksi wa Ngazi 4

OmniRoute inasaidia usanidi wa proksi katika **mawanda manne huru**, yanayotatuliwa kulingana na mpangilio wa kipaumbele:

```
Mpangilio wa Utatuzi wa Kipaumbele (cha juu zaidi → cha chini zaidi):

  1. 🔵 Proksi ya Akaunti/Muunganisho  →  kwa kila ufunguo wa API / muunganisho wa OAuth
  2. 🟡 Proksi ya Mtoa Huduma          →  kwa kila mtoa huduma (k.m., trafiki yote ya OpenAI)
  3. 🟠 Proksi ya Mchanganyiko         →  kwa kila usanidi wa mchanganyiko/uelekezaji
  4. 🟢 Proksi ya Kimataifa            →  trafiki yote, watoa huduma wote
```

### Jinsi Utatuzi Unavyofanya Kazi

OmniRoute inapotuma ombi kwa mtoa huduma wa nje, huita `resolveProxyForConnectionFromRegistry()` ambayo hukagua kila ngazi kwa mpangilio:

1. **Ngazi ya akaunti** — Je, kuna proksi iliyokabidhiwa kwa kitambulisho hiki mahususi cha muunganisho?
2. **Ngazi ya mtoa huduma** — Je, kuna proksi iliyokabidhiwa kwa mtoa huduma huyu (k.m., `openai`)?
3. **Ngazi ya kimataifa** — Je, kuna proksi ya kimataifa iliyosanidiwa?
4. **Hakuna proksi** — Muunganisho wa moja kwa moja kwa mtoa huduma.

Ya kwanza inayolingana ndiyo hutumika. Hii inamaanisha unaweza kuweka proksi ya kimataifa kama chaguo mbadala lakini ukaibatilisha kwa watoa huduma au miunganisho mahususi.

### Kinachopitishwa Kupitia Proksi

| Aina ya Trafiki                   | Inapitishwa Kupitia Proksi? | Maelezo                                        |
| --------------------------------- | --------------------------- | ---------------------------------------------- |
| Ukamilishaji wa gumzo             | ✅                          | Maombi yote ya `/v1/chat/completions`          |
| Uwakilishaji wa vekta             | ✅                          | `/v1/embeddings`                               |
| Uzalishaji wa picha               | ✅                          | `/v1/images/generations`                       |
| Sauti (TTS/STT)                   | ✅                          | `/v1/audio/*`                                  |
| Ubadilishanaji wa tokeni za OAuth | ✅                          | Hutatua `unsupported_country_region_territory` |
| Majaribio ya muunganisho          | ✅                          | Kitufe cha "Jaribu Muunganisho" hutumia proksi |
| Uonyeshaji upya wa tokeni         | ✅                          | Usasishaji wa OAuth wa chinichini              |
| Usawazishaji wa modeli            | ✅                          | Uorodheshaji na ugunduzi wa modeli             |

---

## Sajili ya Proksi (CRUD)

Sajili ya proksi ni jedwali la SQLite (`proxy_registry`) linalohifadhi proksi zako zote. Kila proksi ina:

| Sehemu     | Aina    | Maelezo                                                                            |
| ---------- | ------- | ---------------------------------------------------------------------------------- |
| `id`       | UUID    | Kitambulisho cha kipekee                                                           |
| `name`     | String  | Lebo inayoeleweka na binadamu                                                      |
| `type`     | String  | Itifaki: `http`, `https`, `socks5`                                                 |
| `host`     | String  | Jina la mwenyeji au IP ya proksi                                                   |
| `port`     | Integer | Nambari ya kituo                                                                   |
| `username` | String  | Jina la mtumiaji la uthibitishaji (limesimbwa kwa njia fiche wakati limehifadhiwa) |
| `password` | String  | Nenosiri la uthibitishaji (limesimbwa kwa njia fiche wakati limehifadhiwa)         |
| `region`   | String  | Lebo ya eneo la kijiografia                                                        |
| `notes`    | String  | Madokezo ya maandishi huru                                                         |
| `status`   | String  | `active` au `inactive`                                                             |
| `source`   | String  | `manual` au `oneproxy`                                                             |

### Kuunda Proksi

**Kupitia Dashibodi:**

1. Nenda kwenye **Mipangilio → Proksi**
2. Bofya **Ongeza Proksi**
3. Jaza aina, mwenyeji, kituo, na vitambulisho vya hiari vya uthibitishaji
4. Hifadhi

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

### Kusasisha Proksi

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

> **Kumbuka:** Vitambulisho huhifadhiwa isipokuwa utume vibadala visivyo tupu kwa njia ya wazi. Kutuma mifuatano tupu kwa `username`/`password` kutahifadhi thamani zilizopo.

### Kufuta Proksi

```bash
# Hushindwa ikiwa proksi imekabidhiwa kwa wigo wowote
curl -X DELETE "http://localhost:20128/api/v1/management/proxies?id=proxy-uuid"

# Lazimisha kufuta (huondoa pia makabidhiano)
curl -X DELETE "http://localhost:20128/api/v1/management/proxies?id=proxy-uuid&force=1"
```

### Kuorodhesha Proksi

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

### Kukabidhi Proksi kwa Mawanda

```bash
# Kabidhi kwa wigo wa kimataifa
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}}'

# Kabidhi kwa mtoa huduma mahususi
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}}'

# Kabidhi kwa muunganisho/ufunguo mahususi
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}}'
```

### Kutatua Proksi Inayotumika

Angalia ni proksi ipi itakayotumika kwa muunganisho fulani:

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

Hurejesha proksi iliyotatuliwa pamoja na ngazi yake (`account`, `provider`, au `global`) na chanzo.

### Ukabidhianaji kwa Wingi

Kabidhi proksi moja kwa watoa huduma au miunganisho mingi kwa wakati mmoja:

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

### Uingizaji/Uhamishaji

Proksi zinajumuishwa katika mfumo wa **Hifadhi Nakala/Rejesha**. Unapohamisha usanidi wako wa OmniRoute:

1. Nenda kwenye **Dashibodi → Mipangilio → Hifadhi Nakala**
2. Bofya **Hamisha** — sajili ya proksi na makabidhiano yanajumuishwa
3. Ili kurejesha, bofya **Ingiza** na upakie faili ya hifadhi nakala

Sajili ya proksi pia inasaidia **upsert kwa host+port** — ukiingiza proksi ambayo tayari ipo (mwenyeji na kituo sawa), huisasisha badala ya kuunda nakala nyingine.

### Uhamishaji kutoka Mfumo wa Zamani

Ikiwa ulisanidi proksi katika toleo la zamani (kabla ya registry), OmniRoute huzihamisha kiotomatiki:

```
Hifadhi ya zamani ya key_value → proxy_registry + proxy_assignments
```

Hili hutokea mara moja wakati wa uanzishaji wa kwanza baada ya kusasisha. Tumia `migrateLegacyProxyConfigToRegistry({ force: true })` ili kuiendesha tena.

---

## Soko la Proksi Bila Malipo la 1proxy

> 🆕 **Imechangiwa na [@oyi77](https://github.com/oyi77)** — PR [#1847](https://github.com/diegosouzapw/OmniRoute/pull/1847) (Suala [#1788](https://github.com/diegosouzapw/OmniRoute/issues/1788))

OmniRoute huunganishwa na jukwaa la jumuiya la **[1proxy](https://1proxy-api.aitradepulse.com)** ili kutoa ufikiaji wa **mamia ya proksi zisizolipishwa na zilizothibitishwa** kutoka kote ulimwenguni. Hii ni bora kwa watumiaji ambao hawana miundombinu yao wenyewe ya proksi.

### Jinsi Inavyofanya Kazi

```
┌─────────────┐  Usawazishaji  ┌─────────────────┐  Mzunguko   ┌──────────┐
│  API ya     │ ─────────────▶ │  proxy_registry  │ ──────────▶ │ Mtoa     │
│  1proxy     │  hadi proksi   │  source=oneproxy │ kwa ubora   │ huduma   │
│  (ya nje)   │      500       │                  │             │ wa API   │
└─────────────┘                └─────────────────┘              └──────────┘
```

1. **Usawazishaji** — OmniRoute hupakua proksi zilizothibitishwa kutoka API ya 1proxy
2. **Uhifadhi** — Proksi huhifadhiwa kwenye jedwali lilelile la `proxy_registry` zikiwa na `source = 'oneproxy'`
3. **Uchujaji** — Chuja kulingana na itifaki, nchi na alama ya ubora
4. **Mzunguko** — Chagua proksi bora kwa kutumia mikakati ya ubora, nasibu au mfuatano
5. **Upunguzaji wa kiotomatiki** — Proksi zilizoshindwa hupunguziwa alama ya ubora; zikishuka chini ya kiwango → huwekwa alama ya kutotumika

### Kusawazisha Proksi

**Kupitia Dashibodi:**

1. Nenda kwenye kichupo cha **Settings → 1proxy**
2. Bofya **"Sync Now"**
3. Tazama takwimu: jumla ya proksi, idadi inayotumika, wastani wa ubora na mgawanyo kulingana na nchi

**Kupitia API:**

```bash
# Anzisha usawazishaji
curl -X POST http://localhost:20128/api/settings/oneproxy \
  -H "Content-Type: application/json" \
  -d '{}'

# Jibu:
# { "success": true, "added": 127, "updated": 45, "failed": 2, "total": 172 }
```

### Kuchuja Proksi

```bash
# Chuja kulingana na itifaki
curl "http://localhost:20128/api/settings/oneproxy?protocol=socks5"

# Chuja kulingana na nchi
curl "http://localhost:20128/api/settings/oneproxy?countryCode=US"

# Chuja kulingana na alama ya chini kabisa ya ubora
curl "http://localhost:20128/api/settings/oneproxy?minQuality=80"

# Unganisha vichujio
curl "http://localhost:20128/api/settings/oneproxy?protocol=http&countryCode=DE&minQuality=70"
```

### Alama za Ubora wa Proksi

Kila proksi ya 1proxy huja na metadata:

| Sehemu          | Maelezo                                            |
| --------------- | -------------------------------------------------- |
| `qualityScore`  | Ukadiriaji wa 0-100 kutoka uthibitishaji wa 1proxy |
| `latencyMs`     | Ucheleweshaji wa mtandao uliopimwa                 |
| `anonymity`     | `transparent`, `anonymous`, au `elite`             |
| `googleAccess`  | Ikiwa proksi inaweza kufikia huduma za Google      |
| `countryCode`   | Msimbo wa nchi wa ISO wenye herufi mbili           |
| `lastValidated` | Muhuri wa muda wa uthibitishaji wa mwisho          |

Alama za ubora hurekebishwa kwa mabadiliko:

- **Maombi yaliyoshindwa** hupunguza alama kwa pointi 10
- **Alama ikishuka hadi ≤10** → proksi huwekwa alama ya `inactive`
- Proksi zisizotumika huondolewa kwenye mzunguko

### Mikakati ya Mzunguko

```bash
# Zungusha kulingana na ubora (proksi bora kwanza) — chaguo-msingi
curl -X POST http://localhost:20128/api/settings/oneproxy/rotate \
  -H "Content-Type: application/json" \
  -d '{"strategy": "quality"}'

# Mzunguko wa nasibu
curl -X POST http://localhost:20128/api/settings/oneproxy/rotate \
  -d '{"strategy": "random"}'

# Mfuatano (iliyoidhinishwa zamani zaidi kwanza)
curl -X POST http://localhost:20128/api/settings/oneproxy/rotate \
  -d '{"strategy": "sequential"}'
```

### Kivunja Mzunguko

Usawazishaji wa 1proxy una kivunja mzunguko kilichojengewa ndani:

- Baada ya **kushindwa kwa usawazishaji mara 5 mfululizo**, majaribio zaidi ya kusawazisha huzuiwa
- Weka upya kwa kutumia: `resetOneproxyCircuitBreaker()` au anzisha seva upya
- Hali ya usawazishaji inapatikana kupitia `GET /api/settings/oneproxy?action=status`

### Kufuta Proksi za 1proxy

```bash
# Futa proksi moja ya 1proxy
curl -X DELETE "http://localhost:20128/api/settings/oneproxy?id=proxy-uuid"

# Futa proksi ZOTE za 1proxy (proksi zilizowekwa mwenyewe haziguswi)
curl -X DELETE "http://localhost:20128/api/settings/oneproxy?clearAll=1"
```

---

## Kuzuia Utambuzi na Kuficha Utambulisho

OmniRoute haipitishi tu trafiki kupitia proksi — huifanya trafiki ionekane halali:

### Uigaji wa Alama ya Utambulisho ya TLS

Hutumia `wreq-js` kutengeneza alama za utambulisho za TLS zinazofanana na za kivinjari, hivyo kukwepa mifumo ya utambuzi wa roboti inayotambua miunganisho ya TLS isiyotoka kwenye kivinjari.

### Ulinganishaji wa Alama ya Utambulisho ya CLI

**Kibadilishaji cha Alama ya Utambulisho ya CLI** (`Mipangilio → Usalama`) hupanga upya vichwa vya HTTP na sehemu za mwili wa JSON ili zilingane na saini kamili ya faili asilia za kutekelezwa za CLI (Claude Code, Codex, n.k.). Hii hufanya kazi **juu ya** proksi:

```
IP yako (imezuiwa) → IP ya proksi (Marekani) → API ya mtoa huduma
                     + uigaji wa TLS
                     + alama ya utambulisho ya CLI
```

Unapata **ufichaji wa IP** na **uhalisi wa ombi** kwa wakati mmoja.

### Uhifadhi wa IP ya Proksi

Beji zenye rangi tofauti katika dashibodi huonyesha kiwango cha proksi kinachotumika:

| Beji | Kiwango     | Maana                                                             |
| ---- | ----------- | ----------------------------------------------------------------- |
| 🟢   | Kimataifa   | Trafiki yote hupitia proksi hii                                   |
| 🟡   | Mtoa huduma | Trafiki ya mtoa huduma huyu pekee ndiyo hupitishwa kupitia proksi |
| 🔵   | Muunganisho | Ufunguo/akaunti hii mahususi hutumia proksi hii                   |

Beji pia huonyesha IP ya proksi iliyotambuliwa kwa ajili ya uthibitishaji.

---

## Modi za Proksi ya Juu

Kwa watoa huduma wanaotumia muundo wa CLIProxyAPI, OmniRoute inasaidia modi tatu za proksi ya juu:

| Modi          | Maelezo                                                                         |
| ------------- | ------------------------------------------------------------------------------- |
| `native`      | OmniRoute hushughulikia moja kwa moja upitishaji kupitia proksi (chaguo-msingi) |
| `cliproxyapi` | Hukabidhi jukumu kwa instansi ya nje ya CLIProxyAPI                             |
| `fallback`    | Hujaribu modi asilia kwanza, kisha hutumia CLIProxyAPI ikishindikana            |

Sanidi kwa kila mtoa huduma:

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

---

## Kiolesura cha Dashibodi

### Mipangilio → Kichupo cha Proksi

- Usanidi wa **proksi ya kimataifa** (weka mara moja kwa trafiki yote)
- Mipangilio mbadala ya **proksi kwa kila mtoa huduma**
- Ugawaji wa **proksi kwa kila muunganisho**
- **Jaribio la muunganisho** kupitia proksi iliyosanidiwa
- **Beji zenye rangi tofauti** zinazoonyesha kiwango cha proksi kinachotumika

### Mipangilio → Kichupo cha 1proxy

- Kitufe cha **Sawazisha Sasa** ili kupata proksi zisizolipishwa
- **Kadi za takwimu**: Jumla, Zinazotumika, Wastani wa Ubora, Usawazishaji wa Mwisho
- **Vichujio**: Itifaki, Msimbo wa Nchi, Ubora wa Chini Zaidi
- **Jedwali la proksi** lenye seva mwenyeji, itifaki, nchi, alama ya ubora, ucheleweshaji, kutotambulika, ufikiaji wa Google
- Paneli ya **hali ya usawazishaji** yenye ufuatiliaji wa kufanikiwa/kushindwa na idadi ya kushindwa mfululizo
- **Futa Zote** ili kuondoa maingizo yote ya 1proxy

---

## Marejeleo ya API

### API ya Mipangilio ya Proksi

| Mbinu    | Endpoint                                       | Maelezo                          |
| -------- | ---------------------------------------------- | -------------------------------- |
| `GET`    | `/api/settings/proxy`                          | Pata usanidi kamili wa proksi    |
| `GET`    | `/api/settings/proxy?level=global`             | Pata proksi ya kimataifa         |
| `GET`    | `/api/settings/proxy?level=provider&id=openai` | Pata proksi ya mtoa huduma       |
| `GET`    | `/api/settings/proxy?resolve=connectionId`     | Tambua proksi inayotumika        |
| `PUT`    | `/api/settings/proxy`                          | Sasisha usanidi wa proksi        |
| `DELETE` | `/api/settings/proxy?level=provider&id=openai` | Ondoa proksi katika kiwango hiki |

### API ya Sajili ya Proksi

| Mbinu    | Endpoint                                          | Maelezo                   |
| -------- | ------------------------------------------------- | ------------------------- |
| `GET`    | `/api/v1/management/proxies`                      | Orodhesha proksi zote     |
| `GET`    | `/api/v1/management/proxies?id=uuid`              | Pata proksi kwa ID        |
| `GET`    | `/api/v1/management/proxies?id=uuid&where_used=1` | Pata migawo ya proksi     |
| `POST`   | `/api/v1/management/proxies`                      | Unda proksi               |
| `PATCH`  | `/api/v1/management/proxies`                      | Sasisha proksi            |
| `DELETE` | `/api/v1/management/proxies?id=uuid`              | Futa proksi               |
| `DELETE` | `/api/v1/management/proxies?id=uuid&force=1`      | Lazimisha kufuta          |
| `POST`   | `/api/v1/management/proxies/bulk-assign`          | Gawa kwa wingi            |
| `GET`    | `/api/v1/management/proxies/assignments`          | Orodhesha migawo          |
| `GET`    | `/api/v1/management/proxies/health`               | Takwimu za afya ya proksi |

### API ya Tunnels

Kwa kuweka instansi yako ya OmniRoute wazi kwenye intaneti ya umma (Cloudflare/ngrok/Tailscale) badala ya kuelekeza trafiki ya kutoka kupitia proksi, angalia [TUNNELS_GUIDE.md](./TUNNELS_GUIDE.md). API ya REST ya tunnel inapatikana chini ya `/api/tunnels/{cloudflared,ngrok,tailscale}/*` na inajitegemea kutoka kwenye mnyororo wa proksi ya trafiki inayotoka uliofafanuliwa hapo juu.

### API ya 1proxy

| Mbinu    | Endpoint                               | Maelezo                             |
| -------- | -------------------------------------- | ----------------------------------- |
| `GET`    | `/api/settings/oneproxy`               | Orodhesha proksi za 1proxy          |
| `GET`    | `/api/settings/oneproxy?action=stats`  | Pata takwimu + hali ya usawazishaji |
| `GET`    | `/api/settings/oneproxy?action=status` | Pata hali ya usawazishaji pekee     |
| `POST`   | `/api/settings/oneproxy`               | Anzisha usawazishaji                |
| `POST`   | `/api/settings/oneproxy/rotate`        | Hamia kwenye proksi inayofuata      |
| `DELETE` | `/api/settings/oneproxy?id=uuid`       | Futa moja                           |
| `DELETE` | `/api/settings/oneproxy?clearAll=1`    | Futa zote                           |

### API ya Proksi ya Juu

| Mbinu    | Endpoint                          | Maelezo                        |
| -------- | --------------------------------- | ------------------------------ |
| `GET`    | `/api/upstream-proxy/:providerId` | Pata usanidi wa proksi ya juu  |
| `PUT`    | `/api/upstream-proxy/:providerId` | Weka modi ya proksi ya juu     |
| `DELETE` | `/api/upstream-proxy/:providerId` | Ondoa usanidi wa proksi ya juu |

---

## Vigezo vya Mazingira

| Kigezo                | Chaguo-msingi | Maelezo                                                                            |
| --------------------- | ------------- | ---------------------------------------------------------------------------------- |
| `ENABLE_SOCKS5_PROXY` | `true`        | Washa usaidizi wa proksi ya SOCKS5 (chaguo-msingi ni `true` katika `.env.example`) |

---

## Utatuzi wa Matatizo

### "Proksi ya SOCKS5 imezimwa"

Weka `ENABLE_SOCKS5_PROXY=true` katika faili yako ya `.env` kisha uanzishe upya.

### Hitilafu za "socket hang up" kupitia proksi

Hili ni jambo la kawaida kwa proksi za bei nafuu ambazo hukata miunganisho isiyotumika. OmniRoute tayari hushughulikia hili kwa:

- Kuzima keep-alive kwenye miunganisho ya proksi (`keepAliveTimeout: 1`)
- Kuzima pipelining (`pipelining: 0`)
- Kuhifadhi dispatchers kwenye akiba ili kuepuka handshakes zinazojirudia

Ikiwa tatizo litaendelea, jaribu proksi tofauti au utumie kipengele cha kubadilisha proksi cha 1proxy.

### "unsupported_country_region_territory" wakati wa OAuth

Hakikisha proksi imesanidiwa **kabla** ya kuanzisha mtiririko wa OAuth. OmniRoute hupitisha ubadilishanaji wa tokeni za OAuth kupitia proksi iliyosanidiwa. Weka kwanza proksi ya kimataifa au ya kiwango cha mtoa huduma, kisha unganisha.

### Proksi haitumiki

Angalia mpangilio wa utatuzi:

1. Thibitisha kwa `GET /api/settings/proxy?resolve=your-connection-id`
2. Angalia ikiwa `status` ya proksi ni `active` (si `inactive`)
3. Hakikisha upeo wa ugawaji wa proksi unalingana na muunganisho wako

### Usawazishaji wa 1proxy unashindwa

Angalia hali ya usawazishaji:

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

Ikiwa `consecutiveFailures >= 5`, circuit breaker imewashwa. Anzisha seva upya ili kuiweka upya, au subiri iwekwe upya mwenyewe.

---

## Muundo wa Hifadhidata

### Jedwali la `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' au 'oneproxy'
  quality_score INTEGER,                     -- 0-100 (1proxy pekee)
  latency_ms INTEGER,                        -- milisekunde (1proxy pekee)
  anonymity TEXT,                            -- transparent/anonymous/elite
  google_access INTEGER DEFAULT 0,           -- inaweza kufikia Google? (1proxy)
  last_validated TEXT,                       -- muhuri wa muda wa ISO (1proxy)
  country_code TEXT,                         -- msimbo wa ISO wenye herufi 2 (1proxy)
  created_at TEXT NOT NULL,
  updated_at TEXT NOT NULL
);
```

### Jedwali la `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,              -- kitambulisho cha mtoa huduma, kitambulisho cha muunganisho, au kitambulisho cha combo
  created_at TEXT NOT NULL,
  updated_at TEXT NOT NULL,
  UNIQUE(scope, scope_id)
);
```

---

## Ukaguzi wa Afya ya Proksi (v3.8.16+)

Utaratibu wa **kushindwa haraka kwa proksi** wa OmniRoute (`src/lib/proxyHealth.ts`) hutambua proksi zisizofanya kazi ndani ya <2s kupitia ukaguzi wa haraka wa muunganisho wa TCP, kisha **huhifadhi matokeo kwenye akiba** ili kuepuka gharama ya ziada kwa kila ombi.

### Jinsi Unavyofanya Kazi

```
Ombi ──▶ ProxyHealthCache.get(url)
          │
          ├─ Imepatikana kwenye akiba + ni mpya?  ──▶ rudisha hali iliyohifadhiwa
          │
          └─ Haipo kwenye akiba / imepitwa na wakati?  ──▶ unganisha TCP kwenye host:port
                                                            (muda wa kuisha: FAST_FAIL_TIMEOUT_MS)
                                                            ──▶ hifadhi kwenye akiba kwa HEALTH_CACHE_TTL_MS
                                                            ──▶ rudisha matokeo
```

Bila hili, proksi isiyofanya kazi ingezuia kila ombi kwa muda wote wa `PROXY_TIMEOUT_MS` (chaguo-msingi ni 30s) kabla ya kushindwa.

### Vigezo vya Mazingira Vinavyoweza Kurekebishwa

| Kigezo                       | Chaguo-msingi | Kusudi                                                        |
| ---------------------------- | ------------- | ------------------------------------------------------------- |
| `PROXY_FAST_FAIL_TIMEOUT_MS` | `2000`        | Muda wa kuisha wa muunganisho wa TCP kwa kila ukaguzi wa afya |
| `PROXY_HEALTH_CACHE_TTL_MS`  | `30000`       | Muda ambao matokeo ya afya huhifadhiwa kwenye akiba           |

**Thamani zinazopendekezwa:**

| Hali                             | Muda wa kushindwa haraka | TTL ya akiba | Sababu                                                                      |
| -------------------------------- | ------------------------ | ------------ | --------------------------------------------------------------------------- |
| Lango la API lenye trafiki kubwa | 1500ms                   | 60000ms      | Kushindwa haraka kwa ukali, akiba ndefu zaidi ili kupunguza ukaguzi         |
| Nodi zilizosambazwa kijiografia  | 3000ms                   | 15000ms      | Mitandao ya polepole huhitaji muda zaidi; akiba fupi kwa uhamisho wa haraka |
| Uendelezaji / majaribio          | 1000ms                   | 10000ms      | Marudio ya haraka kwenye proksi za ndani                                    |
| Usiri / kuzuia utambuzi          | 2500ms                   | 45000ms      | Epuka uchunguzi wa mara kwa mara unaoweza kuanzisha vikomo vya kasi         |

### Kukagua Afya ya Proksi

```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}`);
}

// Lazimisha ukaguzi upya wa proksi maalum
invalidateProxyHealth("http://user:pass@203.0.113.7:8080");
```

Alama ya `stale` huwa `true` wakati ingizo la akiba limezidi `HEALTH_CACHE_TTL_MS`, na ombi linalofuata litaanzisha ukaguzi mpya.

### Chaguo-msingi kwa Kila Aina ya Proksi

Ukaguzi wa afya hutumia chaguo-msingi zinazofaa kulingana na mpangilio wa URL:

| Mpangilio                  | Porti chaguo-msingi |
| -------------------------- | ------------------- |
| `http://`                  | 8080                |
| `https://`                 | 443                 |
| `socks5://` / `socks5h://` | 1080                |

Porti maalum katika URL (`http://host:9999`) hupewa kipaumbele kila wakati kuliko chaguo-msingi la mpangilio.

---

## Uchanganuzi na Uangalizi wa Proksi

OmniRoute hufuatilia matumizi ya kila proksi ili kuwasaidia waendeshaji kutambua mifumo ya uelekezaji, ongezeko la ghafla la ucheleweshaji, na hitilafu zinazojirudia.

### Kinachofuatiliwa

Kwa kila ombi linalopitia proksi iliyosanidiwa, OmniRoute hurekodi:

| Kipimo       | Maelezo                                                                       |
| ------------ | ----------------------------------------------------------------------------- |
| `proxy_url`  | URL kamili ya proksi (vitambulisho vya uthibitishaji vimefichwa)              |
| `provider`   | Kitambulisho cha mtoa huduma wa juu (openai, anthropic, n.k.)                 |
| `latency_ms` | Jumla ya muda wa kwenda na kurudi, ikijumuisha mawasiliano ya awali ya proksi |
| `connect_ms` | Muda wa kuunganisha TCP pekee                                                 |
| `status`     | Msimbo wa hali wa HTTP kutoka kwa huduma ya juu                               |
| `error`      | Aina ya hitilafu ikiwa ombi halikufaulu                                       |
| `timestamp`  | ISO 8601 UTC                                                                  |

### Kufikia Data

```bash
# Matukio ya hivi karibuni ya proksi
curl -H "Authorization: Bearer $OMNIROUTE_KEY" \
  "http://localhost:20128/api/usage/proxy-logs?limit=100"
```

Endpoint halisi ni `/api/usage/proxy-logs` (angalia `src/app/api/usage/proxy-logs/route.ts`). Endpoint hii inasaidia:

- `GET /api/usage/proxy-logs` — kupata kumbukumbu za proksi
- `DELETE /api/usage/proxy-logs` — kufuta kumbukumbu zote za proksi

Ikihitajika, takwimu zilizojumlishwa zinaweza kuulizwa moja kwa moja kutoka kwenye jedwali la `proxy_logs` kupitia SQL. Kiolesura cha dashibodi kinaweza kutoa mionekano ya takwimu zilizojumlishwa.

### Mifumo ya Kawaida

**Tambua proksi inayobadilika-badilika** (hubadilishana kati ya kufaulu/kutofaulu):

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

**Tafuta proksi zenye kasi ndogo** (ucheleweshaji wa p95 > sekunde 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;
```

---

## Mti wa Maamuzi wa Mkakati wa Mzunguko

Proksi nyingi zinapowekwa kwenye mawanda fulani, OmniRoute hutumia **mkakati wa mzunguko** kuchagua proksi ya kutumia kwa kila ombi. Mkakati husanidiwa katika kiwango cha mawanda (kimataifa, kwa kila mtoa huduma, kwa kila akaunti, kwa kila mchanganyiko).

### Mikakati Inayopatikana

| Mkakati                   | Wakati wa kutumia                                    | Faida na hasara                                                                                              |
| ------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `quality` (chaguo-msingi) | Uzalishaji wenye proksi za viwango tofauti vya ubora | Hupendelea proksi zilizopewa ukadiriaji wa juu; huenda zisizipe nafasi proksi zilizopewa ukadiriaji wa chini |
| `random`                  | Usambazaji wa mzigo, faragha                         | Usambazaji sawa; hupuuza viashiria vya ubora                                                                 |
| `sequential`              | Utatuzi, majaribio yanayoweza kutabirika             | Hupitia proksi kwa mpangilio; ni rahisi kuelewa                                                              |

### Mti wa Maamuzi

```
                    Je, una alama za ubora za proksi zako?
                    │
        ┌───────────┴───────────┐
        │                       │
       NDIYO                   HAPANA
        │                       │
   Je, proksi zote             │
   zina ubora unaokaribiana?   │
        │                       │
   ┌────┴────┐                  │
   │         │                  │
 NDIYO     HAPANA             Tumia
   │         │              `random`
   │         │              (usambazaji sawa
   │         │              hujenga data ya
   │         │              ubora kadiri ya muda)
   │         │
   │    Tumia `quality`
   │    (bora zaidi kwa
   │    ubora mchanganyiko)
   │
Tumia `random`
(sambaza mzigo
kwa usawa)
```

## Kutenga Kiotomatiki Proksi Zako Mwenyewe Zinaposhindwa

Kundi la soko la 1proxy tayari hupunguza kiotomatiki matumizi ya proksi zilizoshindwa lenyewe (angalia
[Alama za Ubora wa Proksi](#proxy-quality-scores)). Kwa
proksi ambazo **wewe** umeongeza kwenye rejista, kipanga-ratiba cha ukaguzi wa afya kinachofanya kazi chinichini
(`src/lib/proxyHealth/scheduler.ts`) hutoa tabia ileile ya "kumwondoa mwanakikundi aliyekufa
kwenye mnyororo kiotomatiki", bila kufuta chochote:

```bash
# .env — zima proksi kwa muda baada ya ukaguzi 3 mfululizo kushindwa, kisha uiwashe tena
# kiotomatiki mara tu inapoanza kujibu ukaguzi tena.
PROXY_AUTO_DISABLE=true
PROXY_AUTO_REMOVE_AFTER=3
```

Jinsi inavyofanya kazi ndani ya mnyororo wa proksi nyingi:

1. Kipanga-ratiba hukagua kila proksi iliyosajiliwa kila baada ya `PROXY_HEALTH_INTERVAL_MS`
   (chaguo-msingi dakika 10; kiwango cha chini dakika 1).
2. Baada ya kushindwa mara `PROXY_AUTO_REMOVE_AFTER` mfululizo kwa njia **thabiti** (hitilafu halisi ya
   muunganisho — kuisha kwa muda au hitilafu ya 5xx ya lengo lenyewe la ukaguzi hazihesabiwi kamwe, angalia
   [Ukaguzi wa Afya ya Proksi](#proxy-health-checking-v3816)), `status` ya proksi
   huwekwa kuwa `dead`.
3. `dead` ni mojawapo ya hali zinazotengwa na kichujio cha hali hai kinachotumiwa na utatuzi wa kundi/mzunguko,
   kwa hivyo mzunguko wa upeo husika (round-robin / nasibu / thabiti /
   muda wa kusubiri — angalia [Mti wa Maamuzi wa Mkakati wa Mzunguko](#rotation-strategy-decision-tree))
   huacha mara moja kuipa proksi hiyo maombi mapya. Hakuna proksi nyingine kwenye
   kundi inayoathiriwa, na kundi lote halirudi kimyakimya kutumia muunganisho wa moja kwa moja —
   angalia kinga ya kufunga mfumo unaposhindwa katika
   [Mfumo wa Proksi wa Viwango 4](#4-level-proxy-system).
4. Kipanga-ratiba huendelea kukagua proksi zenye hali ya `dead` kwa kipindi kilekile. Ukaguzi unaofuata
   uliofanikiwa hubadilisha `status` kuwa `active` na proksi hiyo huingia tena kwenye mzunguko —
   hakuna haja ya kuiongeza tena mwenyewe.

Hii imeundwa kimakusudi kuwa ya **hiari na isiyoharibu**: kwa chaguo-msingi, kipanga-ratiba
huhesabu na kuweka kumbukumbu za hitilafu pekee (angalia sera C katika `decision.ts`), na `PROXY_AUTO_DISABLE`
haifuti kamwe safu — hilo ndilo lengo la alama tofauti na kali zaidi ya
`PROXY_AUTO_REMOVE`. Ikiwa zote zimewekwa kuwa `true`, `PROXY_AUTO_REMOVE`
hutangulia (proksi inayokaribia kufutwa haina haja ya kuzimwa kwa muda katikati). Angalia
marejeleo ya [Usanidi wa Mazingira](../reference/ENVIRONMENT.md) kwa orodha kamili
ya vigezo.

---

> 📖 **Nyaraka zinazohusiana:**
>
> - [Mwongozo wa Mtumiaji](../guides/USER_GUIDE.md) — Usanidi na urekebishaji wa jumla
> - [Marejeleo ya API](../reference/API_REFERENCE.md) — Nyaraka kamili za API
> - [Usanidi wa Mazingira](../reference/ENVIRONMENT.md) — Vigezo vyote vya mazingira