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

🌐 OmniRoute Proxy Guide (Igbo)

🌐 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 · 🇮🇹 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 · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW

---

Gafee mgbochi mpaghara, chebe njirimara gị, ma zipụ okporoụzọ AI site na proxy ọ bụla — na-enweghị mgbagwoju anya nhazi ọ bụla.

OmniRoute nwere usoro njikwa proxy zuru oke nke na-enye gị ohere izipu okporoụzọ ndị na-eweta AI dị n'elu site na proxy HTTP, HTTPS, ma ọ bụ SOCKS5. Ma ị nọ na mpaghara egbochiri, ịchọrọ ntụgharị IP, ma ọ bụ chọrọ izochi akara njirimara ngwaọrụ — ntuziaka a kpuchiri ihe niile.

---

Ndepụta Isiokwu

• Gịnị Mere E Ji Eji Proxy?
• Nchịkọta Nhazi Usoro
• Usoro Proxy Nwere Ọkwa 4
• Ndebanye Proxy (CRUD)
• Ebe Ahịa Proxy Efughị Ego nke 1proxy
• Ntughari Proxy
• Mgbochi Nchọpụta na Izo Ezo
• Ụdị Proxy Dị N'elu
• Ọdịdị Dashboard
• Ntụaka API
• Prom Environment
• Nchọpụta na Ndozi Nsogbu

---

Gịnị Mere E Ji Eji Proxy?

Ọtụtụ ndị na-eweta AI na-amachi ohere dabere na mpaghara ala. Ndị nrụpụta nọ na Russia, China, Iran, Cuba, Turkey, na mba ndị ọzọ na-ahụ njehie dịka:

unsupported_country_region_territory

Ọbụna n'èzí mpaghara ndị egbochiri, proxy bara uru maka:

Ihe E Ji Ya Eme	Nkọwa
Ịgafe mgbochi mpaghara	Nweta OpenAI, Anthropic, Codex, Copilot site na mba ndị egbochiri
Ntughari IP	Kesaa arịrịọ n'etiti ọtụtụ IP iji zere mmachi ọnụego
Nzuzo	Zoo ezigbo IP gị n'aka ndị na-eweta ọrụ dị n'elu
Nrube isi	Zipụ okporoụzọ site na mpaghara ikike iwu akọwapụtara
Nnwale	Mee ka arịrịọ yie nke sitere na mpaghara dị iche iche

---

Nchịkọta Nhazi Usoro

┌───────────────────────────────────────────────────────────────┐
│                       Sava OmniRoute                          │
│                                                               │
│  ┌─────────────┐    ┌──────────────┐    ┌──────────────────┐  │
│  │ Ndebanye    │    │ Onye Nkesa   │    │ Nweta            │  │
│  │ Proxy       │───▶│ Proxy        │───▶│ (undici)         │  │
│  │ (SQLite)    │    │ (cached)     │    │                  │  │
│  └─────────────┘    └──────────────┘    └────────┬─────────┘  │
│         ▲                                        │            │
│         │                                        ▼            │
│  ┌──────┴──────┐                        ┌──────────────────┐  │
│  │ Mmekọrịta   │                        │ API Onye Na-eweta│  │
│  │ 1proxy      │                        │ Dị N'elu         │  │
│  │ (free pool) │                        │                  │  │
│  └─────────────┘                        └──────────────────┘  │
└───────────────────────────────────────────────────────────────┘

Akụkụ Ndị Dị Mkpa

Akụkụ	Faịlụ	Ọrụ
Ndebanye Proxy	src/lib/db/proxies.ts	CRUD maka ntinye proxy na nkesa scope
Onye Nkesa Proxy	open-sse/utils/proxyDispatcher.ts	Na-emepụta ProxyAgent/SOCKS dispatcher nke undici nwere caching
Nweta Site na Proxy	open-sse/utils/proxyFetch.ts	Na-ekpuchi fetch() ma tinye proxy dispatcher
Route Ntọala	src/app/api/settings/proxy/route.ts	API nhazi proxy ochie (GET/PUT/DELETE)
Route Njikwa	src/app/api/v1/management/proxies/route.ts	API CRUD nke ndebanye (GET/POST/PATCH/DELETE)
DB 1proxy	src/lib/db/oneproxy.ts	Nchekwa na-adịgide adịgide nke ebe ahịa proxy efughị ego

---

Sistemụ Proxy Ọkwa Anọ

OmniRoute na-akwado nhazi proxy n’ókè anọ nọọrọ onwe ha, nke a na-ekpebi dịka usoro mkpa si dị:

Usoro Mkpebi Dịka Mkpa Si Dị (nke kachasị elu → nke kachasị ala):

  1. 🔵 Proxy Akaụntụ/Njikọ      →  maka API key / njikọ OAuth ọ bụla
  2. 🟡 Proxy Onye Na-eweta      →  maka onye na-eweta ọ bụla (dịka, okporoụzọ OpenAI niile)
  3. 🟠 Proxy Ngwakọta           →  maka nhazi ngwakọta/ntuziaka okporoụzọ ọ bụla
  4. 🟢 Proxy Izugbe             →  okporoụzọ niile, ndị na-eweta niile

Otu Mkpebi Si Arụ Ọrụ

Mgbe OmniRoute zigara onye na-eweta dị n’elu arịrịọ, ọ na-akpọ resolveProxyForConnectionFromRegistry() nke na-enyocha ọkwa nke ọ bụla n’usoro:

1. Ọkwa akaụntụ — È nwere proxy e kenyere ID njikọ a kpọmkwem?
2. Ọkwa onye na-eweta — È nwere proxy e kenyere onye na-eweta a (dịka, openai)?
3. Ọkwa izugbe — È nwere proxy izugbe ahaziri?
4. Enweghị proxy — Njikọ ozugbo na onye na-eweta.

Nke mbụ dakọtara na-emeri. Nke a pụtara na ị nwere ike ịtọ proxy izugbe dịka nhọrọ ndabere, ma dochie ya maka ndị na-eweta ma ọ bụ njikọ ụfọdụ.

Ihe Ndị A Na-ebufe Site na Proxy

Ụdị Okporoụzọ	A Na-ebufe Site na Proxy?	Nkọwa
Mmecha nkata	✅	Arịrịọ /v1/chat/completions niile
Embeddings	✅	/v1/embeddings
Mmepụta onyonyo	✅	/v1/images/generations
Ọdịyo (TTS/STT)	✅	/v1/audio/*
Mgbanwe token OAuth	✅	Na-edozi unsupported_country_region_territory
Nnwale njikọ	✅	Bọtịnụ "Nwalee Njikọ" na-eji proxy
Mmelite token	✅	Mmelite OAuth na-eme n’azụ
Mmekọrịta model	✅	Ndepụta na nchọpụta model

---

Ndebanye Proxy (CRUD)

Ndebanye proxy bụ tebụl SQLite (proxy_registry) nke na-echekwa proxy gị niile. Proxy nke ọ bụla nwere:

Ogige	Ụdị	Nkọwa
id	UUID	Ihe njirimara pụrụ iche
name	String	Akara mmadụ nwere ike ịgụ
type	String	Protocol: http, https, socks5
host	String	Aha host ma ọ bụ IP proxy
port	Integer	Nọmba port
username	String	Aha njirimara ikike (ezoro ezo mgbe echekwara)
password	String	Okwuntughe ikike (ezoro ezo mgbe echekwara)
region	String	Akara mpaghara ala
notes	String	Ihe ndetu ederede ọ bụla
status	String	active ma ọ bụ inactive
source	String	manual ma ọ bụ oneproxy

Ịmepụta Proxy

Site na Dashboard:

1. Gaa na Settings → Proxy
2. Pịa Add Proxy
3. Dejupụta ụdị, host, port, na ozi ikike nhọrọ
4. Chekwaa

Site na 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"
  }'

Imelite Proxy

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

Rịba ama: A na-echekwa ozi ikike belụsọ ma i zipụ nnọchi ndị na-adịghị efu n’ụzọ doro anya. Izipụ eriri efu maka username/password ga-edobe ụkpụrụ ndị echekwara.

Ihichapụ Proxy

# Ọ ga-ada ma ọ bụrụ na e kenyere proxy ahụ n’ókè ọ bụla
curl -X DELETE "http://localhost:20128/api/v1/management/proxies?id=proxy-uuid"

# Manye nhichapụ (na-ewepụkwa nkesa ndị ahụ)
curl -X DELETE "http://localhost:20128/api/v1/management/proxies?id=proxy-uuid&force=1"

Idepụta Proxy

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

Ikenye Proxy n’Ókè Dị Iche Iche

# Kenye n’ókè izugbe
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}}'

# Kenye otu onye na-eweta kpọmkwem
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}}'

# Kenye otu njikọ/key kpọmkwem
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}}'

Ikpebi Proxy Dị Irè

Lelee proxy a ga-eji maka otu njikọ enyere:

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

Ọ na-eweghachi proxy e kpebiri yana ọkwa ya (account, provider, ma ọ bụ global) na ebe o si bịa.

Nkesa N’Otu Nnukwu Otu

Kenye otu proxy nye ọtụtụ ndị na-eweta ma ọ bụ njikọ n’otu oge:

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

Mbubata/Mbupụ

A na-etinye proxy na sistemụ Nkwado/Mweghachi. Mgbe ị na-ebupụ nhazi OmniRoute gị:

1. Gaa na Dashboard → Settings → Backup
2. Pịa Export — a na-etinye ndebanye proxy na nkesa ya
3. Iji weghachi, pịa Import ma bulite faịlụ nkwado ahụ

Ndebanye proxy na-akwadokwa upsert site na host+port — ọ bụrụ na ibubata proxy dịbu adị (otu host na port), ọ ga-emelite ya kama ịmepụta oyiri.

Mbugharị Sistemụ Ochie

Ọ bụrụ na ị haziri proxies na ụdị ochie (tupu registry), OmniRoute ga-ebufe ha na-akpaghị aka:

Ebe nchekwa key_value ochie → proxy_registry + proxy_assignments

Nke a na-eme naanị otu ugboro na mbido mbụ mgbe emelitechara. Jiri migrateLegacyProxyConfigToRegistry({ force: true }) mee ya ọzọ.

---

1proxy Ahịa Proxy N'efu

🆕 Onye @oyi77 nyere aka — PR #1847 (Nsogbu #1788)

OmniRoute na-ejikọta na nyiwe obodo 1proxy iji nye ohere iji ọtụtụ narị proxy efu a kwadoro sitere n'akụkụ ụwa niile. Nke a dabara nke ọma maka ndị ọrụ na-enweghị akụrụngwa proxy nke ha.

Otu O Si Arụ Ọrụ

┌─────────────┐  Mekọrịta   ┌─────────────────┐   Gbanwee    ┌──────────┐
│  1proxy API │ ────────────▶ │  proxy_registry  │ ────────────▶ │ Onye na- │
│  (mpụga)    │ ruo proxy 500│  source=oneproxy │ site n'ogo  │ enye API │
└─────────────┘              └─────────────────┘               └──────────┘

1. Mekọrịta — OmniRoute na-ewepụta proxy ndị a kwadoro site na 1proxy API
2. Chekwaa — A na-echekwa proxy ndị ahụ n'otu tebụl proxy_registry ahụ nwere source = 'oneproxy'
3. Nyochaa — Jiri protocol, obodo, na akara ogo nyochaa ha
4. Gbanwee — Họrọ proxy kacha mma site n'iji atụmatụ ogo, enweghị usoro, ma ọ bụ usoro n'usoro
5. Wedata onwe ya — A na-ebelata akara ogo proxy ndị dara ada; ma ọ bụrụ na ọ daa n'okpuru oke → a ga-akara ya dị ka inactive

Imekọrịta Proxy

Site na Dashboard:

1. Gaa na taabụ Settings → 1proxy
2. Pịa "Sync Now"
3. Lelee ọnụ ọgụgụ: proxy niile, ọnụọgụ ndị nọ n'ọrụ, nkezi ogo, na nkewa dịka obodo

Site na API:

# Bido mmekọrịta
curl -X POST http://localhost:20128/api/settings/oneproxy \
  -H "Content-Type: application/json" \
  -d '{}'

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

Inyocha Proxy

# Nyochaa site na protocol
curl "http://localhost:20128/api/settings/oneproxy?protocol=socks5"

# Nyochaa site na obodo
curl "http://localhost:20128/api/settings/oneproxy?countryCode=US"

# Nyochaa site na akara ogo kacha nta
curl "http://localhost:20128/api/settings/oneproxy?minQuality=80"

# Jikọta ihe nzacha
curl "http://localhost:20128/api/settings/oneproxy?protocol=http&countryCode=DE&minQuality=70"

Akara Ogo Proxy

Proxy 1proxy ọ bụla na-abịa na metadata:

Mpaghara	Nkọwa
qualityScore	Ogo 0-100 sitere na nkwado 1proxy
latencyMs	Oge igbu oge netwọkụ a tụrụ
anonymity	transparent, anonymous, ma ọ bụ elite
googleAccess	Ma proxy ahụ nwere ike ịnweta ọrụ Google
countryCode	Koodu obodo ISO nwere mkpụrụedemede abụọ
lastValidated	Akara oge nkwado ikpeazụ

A na-agbanwe akara ogo n'ụzọ na-agbanwe agbanwe:

• Arịrịọ ndị dara ada na-ebelata akara ahụ site na isi 10
• Akara dara ruo ≤10 → a ga-akara proxy ahụ dị ka inactive
• A naghị etinye proxy ndị na-adịghị arụ ọrụ na ngbanwe

Atụmatụ Ngbanwe

# Gbanwee site n'ogo (proxy kacha mma na-ebu ụzọ) — ndabara
curl -X POST http://localhost:20128/api/settings/oneproxy/rotate \
  -H "Content-Type: application/json" \
  -d '{"strategy": "quality"}'

# Ngbanwe enweghị usoro
curl -X POST http://localhost:20128/api/settings/oneproxy/rotate \
  -d '{"strategy": "random"}'

# N'usoro (nke a kwadoro n'oge kacha ochie na-ebu ụzọ)
curl -X POST http://localhost:20128/api/settings/oneproxy/rotate \
  -d '{"strategy": "sequential"}'

Ihe Nkwụsị Sekit

Mmekọrịta 1proxy nwere ihe nkwụsị sekit arụnyere n'ime ya:

• Mgbe mmekọrịta dara ugboro 5 n'usoro, a na-egbochi mbọ mmekọrịta ndị ọzọ
• Tọgharịa ya site na: resetOneproxyCircuitBreaker() ma ọ bụ malite sava ahụ ọzọ
• Ọnọdụ mmekọrịta dị na GET /api/settings/oneproxy?action=status

Ihichapụ Proxy 1proxy

# Hichapụ otu proxy 1proxy
curl -X DELETE "http://localhost:20128/api/settings/oneproxy?id=proxy-uuid"

# Hichapụ proxy 1proxy NIILE (emetụghị proxy ndị e ji aka tinye)
curl -X DELETE "http://localhost:20128/api/settings/oneproxy?clearAll=1"

---

Mgbochi Nchọpụta & Izo Onwe

OmniRoute anaghị naanị ebufe okporo data site na proxy — ọ na-emekwa ka okporo data ahụ yie nke ziri ezi:

Nṅomi Mkpịsịaka TLS

Ọ na-eji wreq-js emepụta mkpịsịaka TLS yiri nke ihe nchọgharị, si otú ahụ gafee sistemụ nchọpụta bot ndị na-akara njikọ TLS na-esighị na ihe nchọgharị akara.

Ndakọrịta Mkpịsịaka CLI

Mgbanwe Mkpịsịaka CLI (Ntọala → Nche) na-ahazigharị nkụnyeisi HTTP na mpaghara ahụ JSON ka ha dakọọ kpọmkwem na akara nke faịlụ CLI binary izizi (Claude Code, Codex, wdg.). Nke a na-arụ ọrụ n'elu proxy ahụ:

IP gị (egbochiri) → IP Proxy (US) → API nke Onye Na-enye Ọrụ
                    + nṅomi TLS
                    + mkpịsịaka CLI

Ị na-enweta ma ikpuchi IP ma izi ezi nke arịrịọ n'otu oge.

Ichekwa IP Proxy

Baajị ndị e ji agba dị iche iche kaa akara na dashboard na-egosi ọkwa proxy nke na-arụ ọrụ:

Baajị	Ọkwa	Ihe ọ pụtara
🟢	Zuru ụwa ọnụ	Okporo data niile na-agafe na proxy a
🟡	Onye na-enye ọrụ	Naanị okporo data onye na-enye ọrụ a ka a na-ebufe site na proxy
🔵	Njikọ	Igodo/akaụntụ a kpọmkwem na-eji proxy a

Baajị ahụ na-egosikwa IP proxy a chọpụtara maka nkwenye.

---

Ụdị Proxy Upstream

Maka ndị na-enye ọrụ na-eji ụkpụrụ CLIProxyAPI, OmniRoute na-akwado ụdị proxy upstream atọ:

Ụdị	Nkọwa
native	OmniRoute na-ejikwa ntụgharị proxy ozugbo (ndabara)
cliproxyapi	Na-enyefe ya n'aka instance CLIProxyAPI mpụga
fallback	Na-ebu ụzọ nwaa native, ma laghachi na CLIProxyAPI ma ọ daa

Hazie ya maka onye na-enye ọrụ ọ bụla:

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

---

UI Dashboard

Ntọala → Taabụ Proxy

• Nhazi proxy zuru ụwa ọnụ (hazie ya otu ugboro maka okporo data niile)
• Mgbanwe proxy maka onye na-enye ọrụ ọ bụla
• Ekenye proxy maka njikọ ọ bụla
• Nnwale njikọ site na proxy ahaziri
• Baajị ndị e ji agba dị iche iche kaa akara na-egosi ọkwa proxy na-arụ ọrụ

Ntọala → Taabụ 1proxy

• Bọtịnụ Mekọrịta Ugbu a iji nweta proxy efu
• Kaadị ọnụ ọgụgụ: Ngụkọta, Ndị Na-arụ Ọrụ, Nkezi Ogo, Mmekọrịta Ikpeazụ
• Ihe nzacha: Protocol, Koodu Mba, Ogo Kacha Nta
• Tebụl proxy nwere host, protocol, mba, akara ogo, latency, anonymity, na ohere Google
• Panelụ ọnọdụ mmekọrịta nwere nsuso ihe ịga nke ọma/ọdịda na ọnụ ọgụgụ ọdịda na-esochi ibe ha
• Hichapụ Ha Niile iji wepụ ndenye 1proxy niile

---

Ntụaka API

API Ntọala Proxy

Usoro	Endpoint	Nkọwa
GET	/api/settings/proxy	Nweta nhazi proxy zuru ezu
GET	/api/settings/proxy?level=global	Nweta proxy zuru ụwa ọnụ
GET	/api/settings/proxy?level=provider&id=openai	Nweta proxy onye na-enye ọrụ
GET	/api/settings/proxy?resolve=connectionId	Chọpụta proxy na-arụ ọrụ
PUT	/api/settings/proxy	Melite nhazi proxy
DELETE	/api/settings/proxy?level=provider&id=openai	Wepụ proxy n'ọkwa ahụ

API Ndebanye Proxy

Usoro	Endpoint	Nkọwa
GET	/api/v1/management/proxies	Depụta proxy niile
GET	/api/v1/management/proxies?id=uuid	Nweta proxy site na ID
GET	/api/v1/management/proxies?id=uuid&where_used=1	Nweta ekenye proxy
POST	/api/v1/management/proxies	Mepụta proxy
PATCH	/api/v1/management/proxies	Melite proxy
DELETE	/api/v1/management/proxies?id=uuid	Hichapụ proxy
DELETE	/api/v1/management/proxies?id=uuid&force=1	Manye nhichapụ
POST	/api/v1/management/proxies/bulk-assign	Kenye ọtụtụ n'otu oge
GET	/api/v1/management/proxies/assignments	Depụta ekenye niile
GET	/api/v1/management/proxies/health	Ọnụ ọgụgụ ahụike proxy

API Tunnels

Maka ime ka instance OmniRoute gị dịrị na ịntanetị ọha (Cloudflare/ngrok/Tailscale) kama iziga okporo data na-apụ apụ site na proxy, lee TUNNELS_GUIDE.md. REST API nke tunnel dị n'okpuru /api/tunnels/{cloudflared,ngrok,tailscale}/*, ọ dịkwa iche na usoro proxy na-apụ apụ e depụtara n'elu.

API 1proxy

Usoro	Endpoint	Nkọwa
GET	/api/settings/oneproxy	Depụta proxy 1proxy
GET	/api/settings/oneproxy?action=stats	Nweta ọnụ ọgụgụ + ọnọdụ mmekọrịta
GET	/api/settings/oneproxy?action=status	Nweta naanị ọnọdụ mmekọrịta
POST	/api/settings/oneproxy	Malite mmekọrịta
POST	/api/settings/oneproxy/rotate	Gbanwee gaa na proxy na-esote
DELETE	/api/settings/oneproxy?id=uuid	Hichapụ otu
DELETE	/api/settings/oneproxy?clearAll=1	Hichapụ ha niile

API Proxy Upstream

Usoro	Endpoint	Nkọwa
GET	/api/upstream-proxy/:providerId	Nweta nhazi proxy upstream
PUT	/api/upstream-proxy/:providerId	Tọọ ụdị proxy upstream
DELETE	/api/upstream-proxy/:providerId	Wepụ nhazi proxy upstream

---

Mgbanwe Gburugburuwara

Mgbanwe	Ndabara	Nkọwa
ENABLE_SOCKS5_PROXY	true	Kwado nkwado proxy SOCKS5 (ndabara bụ true na .env.example)

---

Nchọpụta na Ndozi Nsogbu

"Agbanyụrụ proxy SOCKS5"

Tọọ ENABLE_SOCKS5_PROXY=true na faịlụ .env gị ma malitegharịa.

Njehie "socket hang up" site na proxy

Nke a bụ ihe a na-ahụkarị na proxy ndị dị ọnụ ala nke na-akwụsị njikọ ndị na-adịghị arụ ọrụ. OmniRoute ejirila ụzọ ndị a edozi nke a:

• Ịgbanyụ keep-alive na njikọ proxy (keepAliveTimeout: 1)
• Ịgbanyụ pipelining (pipelining: 0)
• Ịchekwa dispatchers na cache iji zere handshakes ugboro ugboro

Ọ bụrụ na ọ na-aga n'ihu, nwalee proxy ọzọ ma ọ bụ jiri atụmatụ ntụgharị 1proxy.

"unsupported_country_region_territory" n'oge OAuth

Gbaa mbọ hụ na ahaziri proxy ahụ tupu ịmalite usoro OAuth. OmniRoute na-ezipụ mgbanwe token OAuth site na proxy ahaziri. Buru ụzọ tọọ proxy zuru ụwa ọnụ ma ọ bụ nke ọkwa provider, wee jikọọ.

Anaghị eji proxy ahụ

Lelee usoro mkpebi:

1. Jiri GET /api/settings/proxy?resolve=your-connection-id nyochaa
2. Lelee ma status nke proxy ahụ bụ active (ọ bụghị inactive)
3. Gbaa mbọ hụ na scope nke ekenyere proxy dabara na njikọ gị

Mmekọrịta 1proxy anaghị aga nke ọma

Lelee ọnọdụ mmekọrịta:

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

Ọ bụrụ na consecutiveFailures >= 5, circuit breaker ahụ arụ ọrụ. Malitegharịa sava ahụ iji tọgharịa ya, ma ọ bụ chere ka e jiri aka tọgharịa ya.

---

Nhazi Ebe Nchekwa Data

Tebụl 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' ma ọ bụ 'oneproxy'
  quality_score INTEGER,                     -- 0-100 (naanị 1proxy)
  latency_ms INTEGER,                        -- milliseconds (naanị 1proxy)
  anonymity TEXT,                            -- transparent/anonymous/elite
  google_access INTEGER DEFAULT 0,           -- ọ nwere ike ịnweta Google? (1proxy)
  last_validated TEXT,                       -- akara oge ISO (1proxy)
  country_code TEXT,                         -- koodu ISO nwere mkpụrụedemede 2 (1proxy)
  created_at TEXT NOT NULL,
  updated_at TEXT NOT NULL
);

Tebụl 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,              -- ID provider, ID njikọ, ma ọ bụ ID combo
  created_at TEXT NOT NULL,
  updated_at TEXT NOT NULL,
  UNIQUE(scope, scope_id)
);

---

Nnyocha Ahụike Proxy (v3.8.16+)

Usoro proxy fast-fail nke OmniRoute (src/lib/proxyHealth.ts) na-achọpụta proxy ndị nwụrụ anwụ n'ime <2s site na nyocha njikọ TCP ngwa ngwa, wee chekwaa nsonaazụ ahụ na cache iji zere ibu ọrụ na arịrịọ ọ bụla.

Otu O Si Arụ Ọrụ

Arịrịọ ──▶ ProxyHealthCache.get(url)
             │
             ├─ Achọtara na cache + ọ ka dị ọhụrụ?  ──▶ weghachite ọnọdụ echekwara na cache
             │
             └─ Ahụghị na cache / ọ bụ ihe ochie?  ──▶ Jikọọ TCP na host:port
                                                        (oge ngwụcha: FAST_FAIL_TIMEOUT_MS)
                                                        ──▶ chekwaa na cache ruo HEALTH_CACHE_TTL_MS
                                                        ──▶ weghachite nsonaazụ

Na-enweghị nke a, proxy nwụrụ anwụ ga-egbochi arịrịọ ọ bụla ruo oge PROXY_TIMEOUT_MS zuru ezu (ndabara bụ 30s) tupu ọ daa.

Mgbanwe Gburugburuwara A Pụrụ Ịhazigharị

Mgbanwe	Ndabara	Ebumnuche
PROXY_FAST_FAIL_TIMEOUT_MS	2000	Oge ngwụcha njikọ TCP maka nyocha ahụike ọ bụla
PROXY_HEALTH_CACHE_TTL_MS	30000	Ogologo oge a ga-echekwa nsonaazụ ahụike na cache

Uru ndị akwadoro:

Ọnọdụ	Oge ngwụcha fast-fail	TTL cache	Ihe kpatara ya
Ọnụ ụzọ API nwere nnukwu arịrịọ	1500ms	60000ms	Ọdịda ngwa ngwa siri ike, cache dị ogologo iji belata nyocha
Nodes gbasasịrị n'ọtụtụ mpaghara	3000ms	15000ms	Netwọkụ ndị dị nwayọ chọrọ oge karịa; cache dị mkpụmkpụ maka failover ngwa ngwa
Mmepe / nnwale	1000ms	10000ms	Ntughari ngwa ngwa na proxy mpaghara
Nzuzo / mgbochi nchọpụta	2500ms	45000ms	Zere nyocha ngwa ngwa nke nwere ike ịkpalite oke ọnụego

Inyocha Ahụike Proxy

import { getAllProxyHealthStatuses, invalidateProxyHealth } from "omniroute/proxyHealth";

const statuses = getAllProxyHealthStatuses();
for (const s of statuses) {
  console.log(`${s.proxyUrl} → healthy=${s.healthy}, stale=${s.stale}`);
}

// Mee ka e nyochagharịa otu proxy kpọmkwem
invalidateProxyHealth("http://user:pass@203.0.113.7:8080");

Akara stale bụ true mgbe ntinye cache ahụ gafere HEALTH_CACHE_TTL_MS, arịrịọ na-esote ga-akpalite nyocha ọhụrụ.

Ndabara Maka Ụdị Proxy Ọ Bụla

Nnyocha ahụike ahụ na-eji ndabara kwesịrị ekwesị dabere na scheme URL:

Scheme	Port ndabara
http://	8080
https://	443
socks5:// / socks5h://	1080

Port ahaziri iche dị na URL (http://host:9999) na-ebute ụzọ mgbe niile karịa ndabara scheme.

---

Ntụle Proxy & Nleba Anya

OmniRoute na-enyocha ojiji proxy ọ bụla iji nyere ndị na-ahụ maka sistemụ aka ịchọpụta usoro ntụgharị arịrịọ, mmụba mberede nke oge nzaghachi, na ọdịda ndị na-eme ugboro ugboro.

Ihe A Na-enyocha

Maka arịrịọ ọ bụla na-agafe na proxy ahaziri, OmniRoute na-edekọ:

Metrik	Nkọwa
proxy_url	URL proxy zuru ezu (ezochiri ozi njirimara nnabata)
provider	ID nke onye na-eweta ọrụ dị n'elu (openai, anthropic, dgz.)
latency_ms	Ngụkọta oge njem ịga na ịlọta, gụnyere njikọ aka proxy
connect_ms	Naanị oge njikọ TCP
status	Koodu ọnọdụ HTTP sitere n'aka onye na-eweta ọrụ dị n'elu
error	Klas njehie ma ọ bụrụ na arịrịọ ahụ dara
timestamp	ISO 8601 UTC

Ịnweta Data Ahụ

# Ihe omume proxy ndị na-adịbeghị anya
curl -H "Authorization: Bearer $OMNIROUTE_KEY" \
  "http://localhost:20128/api/usage/proxy-logs?limit=100"

Endpoint n'ezie bụ /api/usage/proxy-logs (lee src/app/api/usage/proxy-logs/route.ts). Endpoint a na-akwado:

• GET /api/usage/proxy-logs — weghachite ndekọ proxy
• DELETE /api/usage/proxy-logs — hichapụ ndekọ proxy niile

Ọ bụrụ na ọ dị mkpa, enwere ike iji SQL jụọ ọnụ ọgụgụ nchịkọta ozugbo site na tebụl proxy_logs. UI dashboard nwere ike ịnye nlele nchịkọta.

Usoro Ndị A Na-ahụkarị

Chọpụta proxy na-agbanwe ọnọdụ ugboro ugboro (na-agbanweta n'etiti ịga nke ọma/ọdịda):

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;

Chọta proxy ndị dị nwayọ (oge nzaghachi p95 > 2s):

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;

---

Osisi Mkpebi Maka Atụmatụ Mgbanwe

Mgbe e kenyere ọtụtụ proxy n'otu oke, OmniRoute na-eji atụmatụ mgbanwe họrọ nke a ga-eji maka arịrịọ ọ bụla. A na-ahazi atụmatụ ahụ n'ọkwa oke (zuru ụwa ọnụ, maka onye na-eweta ọrụ ọ bụla, maka akaụntụ ọ bụla, maka ngwakọta ọ bụla).

Atụmatụ Ndị Dị

Atụmatụ	Mgbe a ga-eji ya	Ihe a na-achụ n'àjà
quality (ndabara)	Mmepụta nwere proxy ndị ogo ha dị iche iche	Na-akwado proxy nwere ọkwa dị elu; nwere ike ime ka ndị nwere ọkwa dị ala ghara inweta arịrịọ
random	Nkesa ibu ọrụ, nzuzo	Nkesa hà nhata; na-eleghara akara ogo anya
sequential	Nchọpụta nsogbu, nnwale nwere nsonaazụ a pụrụ ibu amụma	Na-agafe proxy n'usoro; ọ dị mfe ịghọta

Osisi Mkpebi

                    Ị nwere akara ogo maka proxy gị?
                    │
        ┌───────────┴───────────┐
        │                       │
       EE                      MBA
        │                       │
   Proxy niile hà              │
   fọrọ nke nta ka ha hara        │
   n'ogo?                       │
        │                       │
   ┌────┴────┐                  │
   │         │                  │
   EE       MBA               Jiri
   │         │              `random`
   │         │              (nkesa hà nhata
   │         │              na-emepụta data
   │         │              ogo ka oge na-aga)
   │         │
   │    Jiri `quality`
   │    (kachasị mma maka
   │    ogo dị iche iche)
   │
Jiri `random`
(kesaa ibu ọrụ
n'ụzọ hà nhata)

Mwepu Akpaka nke Proxy nke Gị Dara Ada

Ọdọ proxy nke ahịa 1proxy na-ewedalarị ogo proxy ndị dara ada n'onwe ya (lee Akara Ogo Proxy). Maka proxy ndị ị tinyere na ndekọ ahụ, onye nhazi nyocha ọnọdụ nke na-arụ ọrụ n'azụ (src/lib/proxyHealth/scheduler.ts) na-enye otu omume ahụ nke “iwepu onye otu nwụrụ anwụ na yinye ahụ na-akpaghị aka,” na-ehichapụghị ihe ọ bụla:

# .env — gbanyụọ proxy n'ụzọ dị nro mgbe nyocha 3 sochiri onwe ha dara ada, ma gbanye ya ọzọ
# na-akpaghị aka ozugbo ọ malitere ịzaghachi nyocha ọzọ.
PROXY_AUTO_DISABLE=true
PROXY_AUTO_REMOVE_AFTER=3

Otu o si arụ ọrụ n'ime yinye nwere ọtụtụ proxy:

1. Onye nhazi ahụ na-enyocha proxy ọ bụla edebanyere aha kwa PROXY_HEALTH_INTERVAL_MS (ndabara bụ nkeji 10; opekempe bụ nkeji 1).
2. Mgbe ọdịda doro anya sochiri onwe ha ruru PROXY_AUTO_REMOVE_AFTER (ezigbo ọdịda njikọ — oge gafere ma ọ bụ 5xx nke ebe a na-enyocha n'onwe ya anaghị agụnye, lee Nnyocha Ọnọdụ Proxy), a na-edobe status nke proxy ahụ ka ọ bụrụ dead.
3. dead bụ otu n'ime ọnọdụ ndị nzacha ọnọdụ-dị-ndụ nke mkpebi ọdọ/ntụgharị na-ewepu, ya mere ntụgharị nke scope (round-robin / random / sticky / latency — lee Osisi Mkpebi Atụmatụ Ntụgharị) na-akwụsị ozugbo inye proxy ahụ arịrịọ ọhụrụ. Nke a anaghị emetụta proxy ndị ọzọ dị na ọdọ ahụ, ọdọ ahụ dum anaghịkwa alaghachi na njikọ ozugbo n'enweghị ọkwa — lee nchedo fail-closed nke Sistemụ Proxy Ọkwa 4.
4. Onye nhazi ahụ na-aga n'ihu na-enyocha proxy ndị dead n'otu nkeji oge ahụ. Nnyocha na-esote nke gara nke ọma na-agbanwe status azụ ka ọ bụrụ active, proxy ahụ wee laghachi na ntụgharị — ọ dịghị mkpa iji aka tinye ya ọzọ.

E ji ụma mee nke a ka ọ bụrụ ihe a ga-ahọrọ ịgbanye, nke na-adịghị emebi ihe: na ndabara, onye nhazi ahụ na- agụta ma dekọọ naanị ọdịda (lee iwu C na decision.ts), ebe PROXY_AUTO_DISABLE anaghị ehichapụ ahịrị ọ bụla — ọkọlọtọ PROXY_AUTO_REMOVE dị iche, nke siri ike karị, bụ maka nke ahụ. Ọ bụrụ na edobere ha abụọ ka ha bụrụ true, PROXY_AUTO_REMOVE ga-emeri (proxy a na-achọ ihichapụ agaghị enwe uru site na mgbanyụ dị nro n'etiti usoro ahụ). Lee ntụaka Nhazi Gburugburụ maka ndepụta mgbanwe zuru ezu.

---

📖 Akwụkwọ metụtara ya:

• Ntuziaka Onye Ọrụ — Ntọala na nhazi izugbe
• Ntụaka API — Akwụkwọ API zuru ezu
• Nhazi Gburugburụ — Mgbanwe gburugburụ niile