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

🌐 OmniRoute Proxy Guide (Kiswahili)

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

---

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?
• Muhtasari wa Usanifu
• Mfumo wa Proksi wa Viwango 4
• Rejista ya Proksi (CRUD)
• Soko Lisilolipishwa la 1proxy
• Ubadilishaji wa Proksi
• Kuzuia Ugunduzi na Ufichaji
• Hali za Proksi ya Upande wa Juu
• Kiolesura cha Dashibodi
• Marejeleo ya API
• Vigezo vya Mazingira
• Utatuzi wa Matatizo

---

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:

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

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

# 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

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

Kukabidhi Proksi kwa Mawanda

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

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:

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 — PR #1847 (Suala #1788)

OmniRoute huunganishwa na jukwaa la jumuiya la 1proxy 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:

# 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

# 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

# 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

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

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. 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:

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

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

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

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

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

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

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

# .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), 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) 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. 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 kwa orodha kamili ya vigezo.

---

📖 Nyaraka zinazohusiana:

• Mwongozo wa Mtumiaji — Usanidi na urekebishaji wa jumla
• Marejeleo ya API — Nyaraka kamili za API
• Usanidi wa Mazingira — Vigezo vyote vya mazingira