# 🌐 OmniRoute Proxy Guide (ខ្មែរ)

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

---

> **រំលងការទប់ស្កាត់តាមភូមិសាស្ត្រ ការពារអត្តសញ្ញាណរបស់អ្នក និងបញ្ជូនចរាចរណ៍ AI តាមរយៈប្រូកស៊ីណាមួយ — ដោយគ្មានភាពស្មុគស្មាញក្នុងការកំណត់រចនាសម្ព័ន្ធ។**

OmniRoute រួមបញ្ចូលប្រព័ន្ធគ្រប់គ្រងប្រូកស៊ីដែលមានមុខងារពេញលេញ ដែលអនុញ្ញាតឱ្យអ្នកបញ្ជូនចរាចរណ៍ទៅកាន់អ្នកផ្តល់សេវា AI ខាងលើតាមរយៈប្រូកស៊ី HTTP, HTTPS ឬ SOCKS5។ មិនថាអ្នកស្ថិតនៅក្នុងតំបន់ដែលត្រូវបានទប់ស្កាត់ ត្រូវការបង្វិល IP ឬចង់បានការក្លែងស្នាមម្រាមដៃដោយសម្ងាត់ទេ — មគ្គុទ្ទេសក៍នេះគ្របដណ្តប់គ្រប់យ៉ាង។

---

## តារាងមាតិកា

- [ហេតុអ្វីត្រូវប្រើប្រូកស៊ី?](#why-use-proxies)
- [ទិដ្ឋភាពទូទៅនៃស្ថាបត្យកម្ម](#architecture-overview)
- [ប្រព័ន្ធប្រូកស៊ី 4 កម្រិត](#4-level-proxy-system)
- [បញ្ជីប្រូកស៊ី (CRUD)](#proxy-registry-crud)
- [ទីផ្សារប្រូកស៊ីឥតគិតថ្លៃ 1proxy](#1proxy-free-proxy-marketplace)
- [ការបង្វិលប្រូកស៊ី](#proxy-rotation)
- [ការប្រឆាំងការរកឃើញ និងភាពសម្ងាត់](#anti-detection--stealth)
- [របៀបប្រូកស៊ីខាងលើ](#upstream-proxy-modes)
- [ផ្ទាំងគ្រប់គ្រង UI](#dashboard-ui)
- [ឯកសារយោង API](#api-reference)
- [អថេរបរិស្ថាន](#environment-variables)
- [ការដោះស្រាយបញ្ហា](#troubleshooting)

---

## ហេតុអ្វីត្រូវប្រើប្រូកស៊ី?

អ្នកផ្តល់សេវា AI ជាច្រើនដាក់កម្រិតការចូលប្រើដោយផ្អែកលើតំបន់ភូមិសាស្ត្រ។ អ្នកអភិវឌ្ឍន៍នៅក្នុង **រុស្ស៊ី ចិន អ៊ីរ៉ង់ គុយបា តួកគី** និងប្រទេសផ្សេងទៀត ជួបប្រទះកំហុសដូចជា៖

```
unsupported_country_region_territory
```

ទោះបីជានៅក្រៅតំបន់ដែលត្រូវបានទប់ស្កាត់ក៏ដោយ ប្រូកស៊ីមានប្រយោជន៍សម្រាប់៖

| ករណីប្រើប្រាស់                        | សេចក្តីពិពណ៌នា                                                         |
| ------------------------------------- | ---------------------------------------------------------------------- |
| **ការរំលងការទប់ស្កាត់តាមភូមិសាស្ត្រ** | ចូលប្រើ OpenAI, Anthropic, Codex, Copilot ពីប្រទេសដែលត្រូវបានទប់ស្កាត់ |
| **ការបង្វិល IP**                      | ចែកចាយសំណើលើ IP ជាច្រើន ដើម្បីជៀសវាងការកំណត់អត្រា                      |
| **ឯកជនភាព**                           | លាក់ IP ពិតប្រាកដរបស់អ្នកពីអ្នកផ្តល់សេវាខាងលើ                          |
| **ការអនុលោមតាមបទប្បញ្ញត្តិ**          | បញ្ជូនចរាចរណ៍តាមរយៈដែនយុត្តាធិការជាក់លាក់                              |
| **ការធ្វើតេស្ត**                      | ក្លែងធ្វើសំណើពីតំបន់ផ្សេងៗ                                             |

---

## ទិដ្ឋភាពទូទៅនៃស្ថាបត្យកម្ម

```
┌───────────────────────────────────────────────────────────────┐
│                       ម៉ាស៊ីនមេ OmniRoute                     │
│                                                               │
│  ┌─────────────┐    ┌──────────────┐    ┌──────────────────┐  │
│  │ បញ្ជី       │    │ ឧបករណ៍បញ្ជូន │    │ ការទាញយក        │  │
│  │ ប្រូកស៊ី     │───▶│ ប្រូកស៊ី      │───▶│ (undici)         │  │
│  │ (SQLite)    │    │ (បានដាក់ឃ្លាំង)│    │                  │  │
│  └─────────────┘    └──────────────┘    └────────┬─────────┘  │
│         ▲                                        │            │
│         │                                        ▼            │
│  ┌──────┴──────┐                        ┌──────────────────┐  │
│  │ សមកាលកម្ម   │                        │ API របស់អ្នកផ្តល់ │  │
│  │ 1proxy      │                        │ សេវាខាងលើ        │  │
│  │ (ក្រុមឥតគិតថ្លៃ)│                        │                  │  │
│  └─────────────┘                        └──────────────────┘  │
└───────────────────────────────────────────────────────────────┘
```

### សមាសភាគសំខាន់ៗ

| សមាសភាគ                     | ឯកសារ                                        | តួនាទី                                                          |
| --------------------------- | -------------------------------------------- | --------------------------------------------------------------- |
| **បញ្ជីប្រូកស៊ី**           | `src/lib/db/proxies.ts`                      | CRUD សម្រាប់ធាតុប្រូកស៊ី និងការកំណត់វិសាលភាព                    |
| **ឧបករណ៍បញ្ជូនប្រូកស៊ី**    | `open-sse/utils/proxyDispatcher.ts`          | បង្កើតឧបករណ៍បញ្ជូន `undici` ProxyAgent/SOCKS ជាមួយការដាក់ឃ្លាំង |
| **ការទាញយកតាមប្រូកស៊ី**     | `open-sse/utils/proxyFetch.ts`               | រុំ `fetch()` ជាមួយការបញ្ចូលឧបករណ៍បញ្ជូនប្រូកស៊ី                |
| **ផ្លូវការកំណត់**           | `src/app/api/settings/proxy/route.ts`        | API កំណត់រចនាសម្ព័ន្ធប្រូកស៊ីចាស់ (GET/PUT/DELETE)              |
| **ផ្លូវគ្រប់គ្រង**          | `src/app/api/v1/management/proxies/route.ts` | API CRUD សម្រាប់បញ្ជី (GET/POST/PATCH/DELETE)                   |
| **មូលដ្ឋានទិន្នន័យ 1proxy** | `src/lib/db/oneproxy.ts`                     | ការរក្សាទុកជាអចិន្ត្រៃយ៍សម្រាប់ទីផ្សារប្រូកស៊ីឥតគិតថ្លៃ         |

---

## ប្រព័ន្ធប្រូកស៊ី 4 កម្រិត

OmniRoute គាំទ្រការកំណត់រចនាសម្ព័ន្ធប្រូកស៊ីនៅ **វិសាលភាពឯករាជ្យចំនួនបួន** ដែលត្រូវបានដោះស្រាយតាមលំដាប់អាទិភាព៖

```
លំដាប់ដោះស្រាយអាទិភាព (ខ្ពស់បំផុត → ទាបបំផុត)៖

  1. 🔵 ប្រូកស៊ីគណនី/ការតភ្ជាប់  →  ក្នុង API key / ការតភ្ជាប់ OAuth នីមួយៗ
  2. 🟡 ប្រូកស៊ីអ្នកផ្តល់សេវា    →  ក្នុងអ្នកផ្តល់សេវានីមួយៗ (ឧ. ចរាចរណ៍ OpenAI ទាំងអស់)
  3. 🟠 ប្រូកស៊ី Combo           →  ក្នុងការកំណត់រចនាសម្ព័ន្ធ combo/routing នីមួយៗ
  4. 🟢 ប្រូកស៊ីសកល             →  ចរាចរណ៍ទាំងអស់ និងអ្នកផ្តល់សេវាទាំងអស់
```

### របៀបដោះស្រាយ

នៅពេល OmniRoute ផ្ញើសំណើទៅកាន់អ្នកផ្តល់សេវាខាងលើ វាហៅ `resolveProxyForConnectionFromRegistry()` ដែលពិនិត្យកម្រិតនីមួយៗតាមលំដាប់៖

1. **កម្រិតគណនី** — តើមានប្រូកស៊ីដែលបានកំណត់ឱ្យ ID ការតភ្ជាប់ជាក់លាក់នេះដែរឬទេ?
2. **កម្រិតអ្នកផ្តល់សេវា** — តើមានប្រូកស៊ីដែលបានកំណត់ឱ្យអ្នកផ្តល់សេវានេះដែរឬទេ (ឧ. `openai`)?
3. **កម្រិតសកល** — តើមានប្រូកស៊ីសកលដែលបានកំណត់រចនាសម្ព័ន្ធដែរឬទេ?
4. **គ្មានប្រូកស៊ី** — តភ្ជាប់ដោយផ្ទាល់ទៅកាន់អ្នកផ្តល់សេវា។

ការផ្គូផ្គងដំបូងគេនឹងត្រូវបានប្រើ។ នេះមានន័យថា អ្នកអាចកំណត់ប្រូកស៊ីសកលជាជម្រើសបម្រុង ប៉ុន្តែអាចកំណត់ជំនួសវាសម្រាប់អ្នកផ្តល់សេវា ឬការតភ្ជាប់ជាក់លាក់។

### អ្វីខ្លះដែលត្រូវឆ្លងកាត់ប្រូកស៊ី

| ប្រភេទចរាចរណ៍              | ឆ្លងកាត់ប្រូកស៊ី? | កំណត់សម្គាល់                                    |
| -------------------------- | ----------------- | ----------------------------------------------- |
| ការបំពេញការជជែក            | ✅                | សំណើ `/v1/chat/completions` ទាំងអស់             |
| Embeddings                 | ✅                | `/v1/embeddings`                                |
| ការបង្កើតរូបភាព            | ✅                | `/v1/images/generations`                        |
| អូឌីយ៉ូ (TTS/STT)          | ✅                | `/v1/audio/*`                                   |
| ការផ្លាស់ប្តូរ token OAuth | ✅                | ដោះស្រាយ `unsupported_country_region_territory` |
| ការសាកល្បងការតភ្ជាប់       | ✅                | ប៊ូតុង "សាកល្បងការតភ្ជាប់" ប្រើប្រូកស៊ី         |
| ការធ្វើឱ្យ token ថ្មី      | ✅                | ការបន្តសុពលភាព OAuth នៅផ្ទៃខាងក្រោយ             |
| ការធ្វើសមកាលកម្មម៉ូដែល     | ✅                | ការរាយបញ្ជី និងការស្វែងរកម៉ូដែល                 |

---

## បញ្ជីប្រូកស៊ី (CRUD)

បញ្ជីប្រូកស៊ីគឺជាតារាង SQLite (`proxy_registry`) ដែលរក្សាទុកប្រូកស៊ីរបស់អ្នកទាំងអស់។ ប្រូកស៊ីនីមួយៗមាន៖

| វាល        | ប្រភេទ  | សេចក្តីពិពណ៌នា                                               |
| ---------- | ------- | ------------------------------------------------------------ |
| `id`       | UUID    | អត្តសញ្ញាណតែមួយគត់                                           |
| `name`     | String  | ស្លាកដែលមនុស្សអាចអានបាន                                      |
| `type`     | String  | ពិធីការ៖ `http`, `https`, `socks5`                           |
| `host`     | String  | ឈ្មោះម៉ាស៊ីន ឬ IP របស់ប្រូកស៊ី                               |
| `port`     | Integer | លេខច្រក                                                      |
| `username` | String  | ឈ្មោះអ្នកប្រើសម្រាប់ការផ្ទៀងផ្ទាត់ (បានអ៊ិនគ្រីបពេលរក្សាទុក) |
| `password` | String  | ពាក្យសម្ងាត់សម្រាប់ការផ្ទៀងផ្ទាត់ (បានអ៊ិនគ្រីបពេលរក្សាទុក)  |
| `region`   | String  | ស្លាកតំបន់ភូមិសាស្ត្រ                                        |
| `notes`    | String  | កំណត់សម្គាល់ជាអត្ថបទសេរី                                     |
| `status`   | String  | `active` ឬ `inactive`                                        |
| `source`   | String  | `manual` ឬ `oneproxy`                                        |

### ការបង្កើតប្រូកស៊ី

**តាមរយៈផ្ទាំងគ្រប់គ្រង៖**

1. ចូលទៅកាន់ **ការកំណត់ → ប្រូកស៊ី**
2. ចុច **បន្ថែមប្រូកស៊ី**
3. បំពេញប្រភេទ host ច្រក និងព័ត៌មានសម្គាល់អត្តសញ្ញាណដែលជាជម្រើស
4. រក្សាទុក

**តាមរយៈ API៖**

```bash
curl -X POST http://localhost:20128/api/v1/management/proxies \
  -H "Content-Type: application/json" \
  -d '{
    "name": "US Proxy",
    "type": "http",
    "host": "proxy.example.com",
    "port": 8080,
    "username": "user",
    "password": "pass",
    "region": "US"
  }'
```

### ការធ្វើបច្ចុប្បន្នភាពប្រូកស៊ី

```bash
curl -X PATCH http://localhost:20128/api/v1/management/proxies \
  -H "Content-Type: application/json" \
  -d '{
    "id": "proxy-uuid-here",
    "host": "new-proxy.example.com",
    "port": 9090
  }'
```

> **ចំណាំ៖** ព័ត៌មានសម្គាល់អត្តសញ្ញាណនឹងត្រូវបានរក្សាទុក លុះត្រាតែអ្នកផ្ញើតម្លៃជំនួសដែលមិនមែនជាតម្លៃទទេដោយច្បាស់លាស់។ ការផ្ញើខ្សែអក្សរទទេសម្រាប់ `username`/`password` នឹងរក្សាតម្លៃដែលបានទុកស្រាប់។

### ការលុបប្រូកស៊ី

```bash
# បរាជ័យ ប្រសិនបើប្រូកស៊ីត្រូវបានកំណត់ឱ្យវិសាលភាពណាមួយ
curl -X DELETE "http://localhost:20128/api/v1/management/proxies?id=proxy-uuid"

# បង្ខំលុប (លុបការកំណត់ភ្ជាប់ផងដែរ)
curl -X DELETE "http://localhost:20128/api/v1/management/proxies?id=proxy-uuid&force=1"
```

### ការរាយបញ្ជីប្រូកស៊ី

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

### ការកំណត់ប្រូកស៊ីឱ្យវិសាលភាព

```bash
# កំណត់ឱ្យវិសាលភាពសកល
curl -X PUT http://localhost:20128/api/settings/proxy \
  -H "Content-Type: application/json" \
  -d '{"level": "global", "proxy": {"type":"http","host":"proxy.example.com","port":8080}}'

# កំណត់ឱ្យអ្នកផ្តល់សេវាជាក់លាក់
curl -X PUT http://localhost:20128/api/settings/proxy \
  -H "Content-Type: application/json" \
  -d '{"level": "provider", "id": "openai", "proxy": {"type":"socks5","host":"socks.example.com","port":1080}}'

# កំណត់ឱ្យការតភ្ជាប់/key ជាក់លាក់
curl -X PUT http://localhost:20128/api/settings/proxy \
  -H "Content-Type: application/json" \
  -d '{"level": "key", "id": "connection-uuid", "proxy": {"type":"http","host":"key-proxy.com","port":3128}}'
```

### ការដោះស្រាយប្រូកស៊ីដែលមានប្រសិទ្ធភាព

ពិនិត្យមើលថា ប្រូកស៊ីមួយណានឹងត្រូវបានប្រើសម្រាប់ការតភ្ជាប់ដែលបានផ្តល់៖

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

វាត្រឡប់ប្រូកស៊ីដែលបានដោះស្រាយ ជាមួយកម្រិតរបស់វា (`account`, `provider`, ឬ `global`) និងប្រភព។

### ការកំណត់ជាក្រុម

កំណត់ប្រូកស៊ីមួយទៅឱ្យអ្នកផ្តល់សេវា ឬការតភ្ជាប់ច្រើនក្នុងពេលតែមួយ៖

```bash
curl -X POST http://localhost:20128/api/v1/management/proxies/bulk-assign \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "provider",
    "scopeIds": ["openai", "anthropic", "codex"],
    "proxyId": "proxy-uuid"
  }'
```

### ការនាំចូល/នាំចេញ

ប្រូកស៊ីត្រូវបានរួមបញ្ចូលក្នុងប្រព័ន្ធ **បម្រុងទុក/ស្ដារឡើងវិញ**។ នៅពេលអ្នកនាំចេញការកំណត់រចនាសម្ព័ន្ធ OmniRoute របស់អ្នក៖

1. ចូលទៅកាន់ **ផ្ទាំងគ្រប់គ្រង → ការកំណត់ → បម្រុងទុក**
2. ចុច **នាំចេញ** — បញ្ជីប្រូកស៊ី និងការកំណត់ភ្ជាប់ត្រូវបានរួមបញ្ចូល
3. ដើម្បីស្ដារឡើងវិញ ចុច **នាំចូល** ហើយផ្ទុកឡើងឯកសារបម្រុងទុក

បញ្ជីប្រូកស៊ីក៏គាំទ្រ **upsert តាម host+port** ផងដែរ — ប្រសិនបើអ្នកនាំចូលប្រូកស៊ីដែលមានរួចហើយ (host និង port ដូចគ្នា) វានឹងធ្វើបច្ចុប្បន្នភាព ជំនួសឱ្យការបង្កើតច្បាប់ចម្លង។

### ការផ្ទេរទិន្នន័យពីប្រព័ន្ធចាស់

ប្រសិនបើអ្នកបានកំណត់រចនាសម្ព័ន្ធប្រូកស៊ីនៅក្នុងកំណែចាស់ (មុនពេលមាន registry) OmniRoute នឹងផ្ទេរពួកវាដោយស្វ័យប្រវត្តិ៖

```
ឃ្លាំង key_value ចាស់ → proxy_registry + proxy_assignments
```

វានឹងកើតឡើងតែម្តងប៉ុណ្ណោះ នៅពេលចាប់ផ្ដើមជាលើកដំបូងបន្ទាប់ពីការដំឡើងកំណែ។ ប្រើ `migrateLegacyProxyConfigToRegistry({ force: true })` ដើម្បីដំណើរការឡើងវិញ។

---

## ទីផ្សារប្រូកស៊ីឥតគិតថ្លៃ 1proxy

> 🆕 **រួមចំណែកដោយ [@oyi77](https://github.com/oyi77)** — PR [#1847](https://github.com/diegosouzapw/OmniRoute/pull/1847) (បញ្ហា [#1788](https://github.com/diegosouzapw/OmniRoute/issues/1788))

OmniRoute រួមបញ្ចូលជាមួយវេទិកាសហគមន៍ **[1proxy](https://1proxy-api.aitradepulse.com)** ដើម្បីផ្តល់សិទ្ធិចូលប្រើ **ប្រូកស៊ីឥតគិតថ្លៃដែលបានផ្ទៀងផ្ទាត់រាប់រយ** ពីជុំវិញពិភពលោក។ វាស័ក្តិសមបំផុតសម្រាប់អ្នកប្រើប្រាស់ដែលមិនមានហេដ្ឋារចនាសម្ព័ន្ធប្រូកស៊ីផ្ទាល់ខ្លួន។

### របៀបដែលវាដំណើរការ

```
┌─────────────┐   ធ្វើសមកាលកម្ម   ┌─────────────────┐     បង្វិល      ┌──────────┐
│  1proxy API │ ────────────────▶ │  proxy_registry  │ ─────────────▶ │ Provider │
│ (ខាងក្រៅ)   │   រហូតដល់ 500    │  source=oneproxy │ តាមគុណភាព     │   API    │
└─────────────┘      ប្រូកស៊ី      └─────────────────┘                └──────────┘
```

1. **ធ្វើសមកាលកម្ម** — OmniRoute ទាញយកប្រូកស៊ីដែលបានផ្ទៀងផ្ទាត់ពី 1proxy API
2. **រក្សាទុក** — ប្រូកស៊ីត្រូវបានរក្សាទុកក្នុងតារាង `proxy_registry` ដូចគ្នា ជាមួយ `source = 'oneproxy'`
3. **ត្រង** — ត្រងតាមប្រូតូកូល ប្រទេស និងពិន្ទុគុណភាព
4. **បង្វិល** — ជ្រើសរើសប្រូកស៊ីល្អបំផុតដោយប្រើយុទ្ធសាស្ត្រផ្អែកលើគុណភាព ចៃដន្យ ឬតាមលំដាប់
5. **បន្ថយគុណភាពដោយស្វ័យប្រវត្តិ** — ប្រូកស៊ីដែលបរាជ័យនឹងត្រូវបន្ថយពិន្ទុគុណភាព។ ប្រសិនបើទាបជាងកម្រិតកំណត់ → ត្រូវបានសម្គាល់ថាអសកម្ម

### ការធ្វើសមកាលកម្មប្រូកស៊ី

**តាមរយៈផ្ទាំងគ្រប់គ្រង៖**

1. ចូលទៅកាន់ផ្ទាំង **Settings → 1proxy**
2. ចុច **"Sync Now"**
3. មើលស្ថិតិ៖ ប្រូកស៊ីសរុប ចំនួនសកម្ម គុណភាពមធ្យម និងការបែងចែកតាមប្រទេស

**តាមរយៈ API៖**

```bash
# ចាប់ផ្តើមការធ្វើសមកាលកម្ម
curl -X POST http://localhost:20128/api/settings/oneproxy \
  -H "Content-Type: application/json" \
  -d '{}'

# ការឆ្លើយតប៖
# { "success": true, "added": 127, "updated": 45, "failed": 2, "total": 172 }
```

### ការត្រងប្រូកស៊ី

```bash
# ត្រងតាមប្រូតូកូល
curl "http://localhost:20128/api/settings/oneproxy?protocol=socks5"

# ត្រងតាមប្រទេស
curl "http://localhost:20128/api/settings/oneproxy?countryCode=US"

# ត្រងតាមពិន្ទុគុណភាពអប្បបរមា
curl "http://localhost:20128/api/settings/oneproxy?minQuality=80"

# បញ្ចូលតម្រងចូលគ្នា
curl "http://localhost:20128/api/settings/oneproxy?protocol=http&countryCode=DE&minQuality=70"
```

### ពិន្ទុគុណភាពប្រូកស៊ី

ប្រូកស៊ី 1proxy នីមួយៗភ្ជាប់មកជាមួយទិន្នន័យមេតា៖

| វាល             | ការពិពណ៌នា                                    |
| --------------- | --------------------------------------------- |
| `qualityScore`  | ពិន្ទុ 0-100 ពីការផ្ទៀងផ្ទាត់របស់ 1proxy      |
| `latencyMs`     | ភាពយឺតនៃបណ្តាញដែលបានវាស់វែង                   |
| `anonymity`     | `transparent`, `anonymous` ឬ `elite`          |
| `googleAccess`  | ថាតើប្រូកស៊ីអាចចូលប្រើសេវាកម្ម Google បានឬអត់ |
| `countryCode`   | កូដប្រទេស ISO ពីរតួអក្សរ                      |
| `lastValidated` | ត្រាពេលវេលានៃការផ្ទៀងផ្ទាត់ចុងក្រោយ           |

ពិន្ទុគុណភាពត្រូវបានកែសម្រួលដោយថាមវន្ត៖

- **សំណើដែលបរាជ័យ** បន្ថយពិន្ទុចំនួន 10 ពិន្ទុ
- **ពិន្ទុធ្លាក់ចុះដល់ ≤10** → ប្រូកស៊ីត្រូវបានសម្គាល់ជា `inactive`
- ប្រូកស៊ីអសកម្មត្រូវបានដកចេញពីការបង្វិល

### យុទ្ធសាស្ត្របង្វិល

```bash
# បង្វិលតាមគុណភាព (ប្រូកស៊ីល្អបំផុតមុន) — លំនាំដើម
curl -X POST http://localhost:20128/api/settings/oneproxy/rotate \
  -H "Content-Type: application/json" \
  -d '{"strategy": "quality"}'

# ការបង្វិលចៃដន្យ
curl -X POST http://localhost:20128/api/settings/oneproxy/rotate \
  -d '{"strategy": "random"}'

# តាមលំដាប់ (ប្រូកស៊ីដែលបានផ្ទៀងផ្ទាត់មុនគេបង្អស់ត្រូវបានជ្រើសមុន)
curl -X POST http://localhost:20128/api/settings/oneproxy/rotate \
  -d '{"strategy": "sequential"}'
```

### ឧបករណ៍ផ្តាច់សៀគ្វី

ការធ្វើសមកាលកម្ម 1proxy មានឧបករណ៍ផ្តាច់សៀគ្វីដែលភ្ជាប់មកជាមួយ៖

- បន្ទាប់ពី **ការធ្វើសមកាលកម្មបរាជ័យជាប់គ្នា 5 ដង** ការព្យាយាមធ្វើសមកាលកម្មបន្ថែមនឹងត្រូវបានទប់ស្កាត់
- កំណត់ឡើងវិញដោយ៖ `resetOneproxyCircuitBreaker()` ឬចាប់ផ្តើមម៉ាស៊ីនបម្រើឡើងវិញ
- ស្ថានភាពធ្វើសមកាលកម្មអាចរកបាននៅ `GET /api/settings/oneproxy?action=status`

### ការសម្អាតប្រូកស៊ី 1proxy

```bash
# លុបប្រូកស៊ី 1proxy មួយ
curl -X DELETE "http://localhost:20128/api/settings/oneproxy?id=proxy-uuid"

# សម្អាតប្រូកស៊ី 1proxy ទាំងអស់ (ប្រូកស៊ីដែលបញ្ចូលដោយដៃមិនត្រូវបានប៉ះពាល់)
curl -X DELETE "http://localhost:20128/api/settings/oneproxy?clearAll=1"
```

---

## ការប្រឆាំងការរកឃើញ និងភាពលាក់លៀម

OmniRoute មិនត្រឹមតែបញ្ជូនចរាចរណ៍តាមរយៈប្រូកស៊ីប៉ុណ្ណោះទេ — វាធ្វើឱ្យចរាចរណ៍មើលទៅស្របច្បាប់ផងដែរ៖

### ការក្លែងបន្លំស្នាមម្រាមដៃ TLS

ប្រើ `wreq-js` ដើម្បីបង្កើតស្នាមម្រាមដៃ TLS ដែលមានលក្ខណៈដូចកម្មវិធីរុករក ដោយឆ្លងកាត់ប្រព័ន្ធរកឃើញបុតដែលសម្គាល់ការចាប់ដៃ TLS មិនមែនពីកម្មវិធីរុករក។

### ការផ្គូផ្គងស្នាមម្រាមដៃ CLI

**ប៊ូតុងបិទបើកស្នាមម្រាមដៃ CLI** (`Settings → Security`) រៀបលំដាប់ HTTP headers និងវាល JSON body ឡើងវិញ ដើម្បីផ្គូផ្គងនឹងហត្ថលេខាជាក់លាក់របស់ CLI binaries ដើម (Claude Code, Codex ជាដើម)។ វាដំណើរការ **បន្ថែមពីលើ** ប្រូកស៊ី៖

```
IP របស់អ្នក (ត្រូវបានទប់ស្កាត់) → IP ប្រូកស៊ី (US) → API របស់អ្នកផ្តល់សេវា
                                  + ការក្លែងបន្លំ TLS
                                  + ស្នាមម្រាមដៃ CLI
```

អ្នកទទួលបានទាំង **ការលាក់បាំង IP** និង **ភាពត្រឹមត្រូវនៃសំណើ** ក្នុងពេលដំណាលគ្នា។

### ការរក្សាទុក IP ប្រូកស៊ី

ផ្លាកសញ្ញាដែលមានកូដពណ៌នៅក្នុងផ្ទាំងគ្រប់គ្រងបង្ហាញថាកម្រិតប្រូកស៊ីណាមួយកំពុងសកម្ម៖

| ផ្លាកសញ្ញា | កម្រិត        | អត្ថន័យ                                                     |
| ---------- | ------------- | ----------------------------------------------------------- |
| 🟢         | សកល           | ចរាចរណ៍ទាំងអស់ឆ្លងកាត់ប្រូកស៊ីនេះ                           |
| 🟡         | អ្នកផ្តល់សេវា | មានតែចរាចរណ៍របស់អ្នកផ្តល់សេវានេះប៉ុណ្ណោះដែលឆ្លងកាត់ប្រូកស៊ី |
| 🔵         | ការតភ្ជាប់    | សោ/គណនីជាក់លាក់នេះប្រើប្រូកស៊ីនេះ                           |

ផ្លាកសញ្ញាក៏បង្ហាញ IP ប្រូកស៊ីដែលបានដោះស្រាយសម្រាប់ការផ្ទៀងផ្ទាត់ផងដែរ។

---

## របៀបប្រូកស៊ី Upstream

សម្រាប់អ្នកផ្តល់សេវាដែលប្រើលំនាំ CLIProxyAPI OmniRoute គាំទ្ររបៀបប្រូកស៊ី upstream ចំនួនបី៖

| របៀប          | សេចក្តីពិពណ៌នា                                              |
| ------------- | ----------------------------------------------------------- |
| `native`      | OmniRoute គ្រប់គ្រងការបញ្ជូនតាមប្រូកស៊ីដោយផ្ទាល់ (លំនាំដើម) |
| `cliproxyapi` | ផ្ទេរភារកិច្ចទៅ instance CLIProxyAPI ខាងក្រៅ                |
| `fallback`    | សាកល្បង native ជាមុន ហើយប្តូរទៅ CLIProxyAPI ប្រសិនបើបរាជ័យ  |

កំណត់រចនាសម្ព័ន្ធតាមអ្នកផ្តល់សេវានីមួយៗ៖

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

---

## UI ផ្ទាំងគ្រប់គ្រង

### Settings → ផ្ទាំង Proxy

- ការកំណត់រចនាសម្ព័ន្ធ **ប្រូកស៊ីសកល** (កំណត់ម្តងសម្រាប់ចរាចរណ៍ទាំងអស់)
- ការកំណត់ជំនួស **ប្រូកស៊ីតាមអ្នកផ្តល់សេវា**
- ការកំណត់ **ប្រូកស៊ីតាមការតភ្ជាប់**
- **ការសាកល្បងការតភ្ជាប់** តាមរយៈប្រូកស៊ីដែលបានកំណត់រចនាសម្ព័ន្ធ
- **ផ្លាកសញ្ញាដែលមានកូដពណ៌** បង្ហាញកម្រិតប្រូកស៊ីសកម្ម

### Settings → ផ្ទាំង 1proxy

- ប៊ូតុង **ធ្វើសមកាលកម្មឥឡូវនេះ** ដើម្បីទាញយកប្រូកស៊ីឥតគិតថ្លៃ
- **កាតស្ថិតិ**៖ សរុប, សកម្ម, គុណភាពមធ្យម, ការធ្វើសមកាលកម្មចុងក្រោយ
- **តម្រង**៖ ពិធីការ, កូដប្រទេស, គុណភាពអប្បបរមា
- **តារាងប្រូកស៊ី** ដែលមាន host, ពិធីការ, ប្រទេស, ពិន្ទុគុណភាព, ភាពយឺតយ៉ាវ, ភាពអនាមិក, ការចូលប្រើ Google
- ផ្ទាំង **ស្ថានភាពធ្វើសមកាលកម្ម** ដែលមានការតាមដានជោគជ័យ/បរាជ័យ និងចំនួនបរាជ័យជាប់ៗគ្នា
- **សម្អាតទាំងអស់** ដើម្បីលុបធាតុ 1proxy ទាំងអស់

---

## ឯកសារយោង API

### API ការកំណត់ប្រូកស៊ី

| វិធីសាស្ត្រ | Endpoint                                       | សេចក្តីពិពណ៌នា                                 |
| ----------- | ---------------------------------------------- | ---------------------------------------------- |
| `GET`       | `/api/settings/proxy`                          | ទទួលយកការកំណត់រចនាសម្ព័ន្ធប្រូកស៊ីពេញលេញ       |
| `GET`       | `/api/settings/proxy?level=global`             | ទទួលយកប្រូកស៊ីសកល                              |
| `GET`       | `/api/settings/proxy?level=provider&id=openai` | ទទួលយកប្រូកស៊ីរបស់អ្នកផ្តល់សេវា                |
| `GET`       | `/api/settings/proxy?resolve=connectionId`     | ដោះស្រាយប្រូកស៊ីដែលមានប្រសិទ្ធភាព              |
| `PUT`       | `/api/settings/proxy`                          | ធ្វើបច្ចុប្បន្នភាពការកំណត់រចនាសម្ព័ន្ធប្រូកស៊ី |
| `DELETE`    | `/api/settings/proxy?level=provider&id=openai` | លុបប្រូកស៊ីនៅកម្រិតនេះ                         |

### API បញ្ជីចុះឈ្មោះប្រូកស៊ី

| វិធីសាស្ត្រ | Endpoint                                          | សេចក្តីពិពណ៌នា             |
| ----------- | ------------------------------------------------- | -------------------------- |
| `GET`       | `/api/v1/management/proxies`                      | រាយបញ្ជីប្រូកស៊ីទាំងអស់    |
| `GET`       | `/api/v1/management/proxies?id=uuid`              | ទទួលយកប្រូកស៊ីតាម ID       |
| `GET`       | `/api/v1/management/proxies?id=uuid&where_used=1` | ទទួលយកការកំណត់ប្រូកស៊ី     |
| `POST`      | `/api/v1/management/proxies`                      | បង្កើតប្រូកស៊ី             |
| `PATCH`     | `/api/v1/management/proxies`                      | ធ្វើបច្ចុប្បន្នភាពប្រូកស៊ី |
| `DELETE`    | `/api/v1/management/proxies?id=uuid`              | លុបប្រូកស៊ី                |
| `DELETE`    | `/api/v1/management/proxies?id=uuid&force=1`      | បង្ខំលុប                   |
| `POST`      | `/api/v1/management/proxies/bulk-assign`          | កំណត់ជាក្រុម               |
| `GET`       | `/api/v1/management/proxies/assignments`          | រាយបញ្ជីការកំណត់           |
| `GET`       | `/api/v1/management/proxies/health`               | ស្ថិតិសុខភាពប្រូកស៊ី       |

### API ផ្លូវរូងក្រោមដី

សម្រាប់ការបើកឱ្យ instance OmniRoute របស់អ្នកអាចចូលប្រើបានតាមអ៊ីនធឺណិតសាធារណៈ (Cloudflare/ngrok/Tailscale) ជំនួសឱ្យការបញ្ជូនចេញតាមរយៈប្រូកស៊ី សូមមើល [TUNNELS_GUIDE.md](./TUNNELS_GUIDE.md)។ REST API របស់ផ្លូវរូងក្រោមដីស្ថិតនៅក្រោម `/api/tunnels/{cloudflared,ngrok,tailscale}/*` ហើយដាច់ដោយឡែកពីខ្សែសង្វាក់ប្រូកស៊ីចេញដែលបានចងក្រងជាឯកសារខាងលើ។

### API 1proxy

| វិធីសាស្ត្រ | Endpoint                               | សេចក្តីពិពណ៌នា                       |
| ----------- | -------------------------------------- | ------------------------------------ |
| `GET`       | `/api/settings/oneproxy`               | រាយបញ្ជីប្រូកស៊ី 1proxy              |
| `GET`       | `/api/settings/oneproxy?action=stats`  | ទទួលយកស្ថិតិ + ស្ថានភាពធ្វើសមកាលកម្ម |
| `GET`       | `/api/settings/oneproxy?action=status` | ទទួលយកតែស្ថានភាពធ្វើសមកាលកម្ម        |
| `POST`      | `/api/settings/oneproxy`               | កេះការធ្វើសមកាលកម្ម                  |
| `POST`      | `/api/settings/oneproxy/rotate`        | ប្តូរទៅប្រូកស៊ីបន្ទាប់               |
| `DELETE`    | `/api/settings/oneproxy?id=uuid`       | លុបមួយ                               |
| `DELETE`    | `/api/settings/oneproxy?clearAll=1`    | សម្អាតទាំងអស់                        |

### API ប្រូកស៊ី Upstream

| វិធីសាស្ត្រ | Endpoint                          | សេចក្តីពិពណ៌នា                              |
| ----------- | --------------------------------- | ------------------------------------------- |
| `GET`       | `/api/upstream-proxy/:providerId` | ទទួលយកការកំណត់រចនាសម្ព័ន្ធប្រូកស៊ី upstream |
| `PUT`       | `/api/upstream-proxy/:providerId` | កំណត់របៀបប្រូកស៊ី upstream                  |
| `DELETE`    | `/api/upstream-proxy/:providerId` | លុបការកំណត់រចនាសម្ព័ន្ធប្រូកស៊ី upstream    |

---

## អថេរបរិស្ថាន

| អថេរ                  | លំនាំដើម | សេចក្ដីពិពណ៌នា                                                            |
| --------------------- | -------- | ------------------------------------------------------------------------- |
| `ENABLE_SOCKS5_PROXY` | `true`   | បើកការគាំទ្រប្រូកស៊ី SOCKS5 (តម្លៃលំនាំដើមគឺ `true` ក្នុង `.env.example`) |

---

## ការដោះស្រាយបញ្ហា

### "ប្រូកស៊ី SOCKS5 ត្រូវបានបិទ"

កំណត់ `ENABLE_SOCKS5_PROXY=true` ក្នុងឯកសារ `.env` របស់អ្នក ហើយចាប់ផ្ដើមឡើងវិញ។

### កំហុស "socket hang up" តាមរយៈប្រូកស៊ី

នេះជារឿងធម្មតាសម្រាប់ប្រូកស៊ីតម្លៃថោកដែលផ្ដាច់ការតភ្ជាប់ដែលទំនេរ។ OmniRoute ដោះស្រាយបញ្ហានេះរួចហើយដោយ៖

- បិទ keep-alive លើការតភ្ជាប់ប្រូកស៊ី (`keepAliveTimeout: 1`)
- បិទ pipelining (`pipelining: 0`)
- រក្សាទុក dispatchers ក្នុងឃ្លាំងសម្ងាត់ ដើម្បីជៀសវាងការធ្វើ handshakes ម្ដងហើយម្ដងទៀត

ប្រសិនបើបញ្ហានៅតែបន្ត សូមសាកល្បងប្រូកស៊ីផ្សេង ឬប្រើមុខងារបង្វិលប្រូកស៊ីរបស់ 1proxy។

### "unsupported_country_region_territory" អំឡុងពេល OAuth

ត្រូវប្រាកដថាប្រូកស៊ីត្រូវបានកំណត់រចនាសម្ព័ន្ធ **មុនពេល** ចាប់ផ្ដើមលំហូរ OAuth។ OmniRoute បញ្ជូនការផ្លាស់ប្ដូរថូខឹន OAuth តាមរយៈប្រូកស៊ីដែលបានកំណត់រចនាសម្ព័ន្ធ។ ជាដំបូង សូមកំណត់ប្រូកស៊ីកម្រិតសកល ឬកម្រិតអ្នកផ្ដល់សេវា បន្ទាប់មកទើបភ្ជាប់។

### ប្រូកស៊ីមិនត្រូវបានប្រើ

ពិនិត្យមើលលំដាប់ដោះស្រាយ៖

1. ផ្ទៀងផ្ទាត់ជាមួយ `GET /api/settings/proxy?resolve=your-connection-id`
2. ពិនិត្យមើលថាតើ `status` របស់ប្រូកស៊ីគឺ `active` (មិនមែន `inactive`)
3. ត្រូវប្រាកដថាវិសាលភាពកំណត់ប្រូកស៊ីត្រូវគ្នានឹងការតភ្ជាប់របស់អ្នក

### ការធ្វើសមកាលកម្ម 1proxy បរាជ័យ

ពិនិត្យមើលស្ថានភាពសមកាលកម្ម៖

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

ប្រសិនបើ `consecutiveFailures >= 5` នោះ circuit breaker បានដំណើរការ។ ចាប់ផ្ដើមម៉ាស៊ីនមេឡើងវិញដើម្បីកំណត់ឡើងវិញ ឬរង់ចាំការកំណត់ឡើងវិញដោយដៃ។

---

## គ្រោងការណ៍មូលដ្ឋានទិន្នន័យ

### តារាង `proxy_registry`

```sql
CREATE TABLE proxy_registry (
  id TEXT PRIMARY KEY,
  name TEXT NOT NULL,
  type TEXT NOT NULL DEFAULT 'http',
  host TEXT NOT NULL,
  port INTEGER NOT NULL,
  username TEXT DEFAULT '',
  password TEXT DEFAULT '',
  region TEXT,
  notes TEXT,
  status TEXT DEFAULT 'active',
  source TEXT NOT NULL DEFAULT 'manual',    -- 'manual' ឬ 'oneproxy'
  quality_score INTEGER,                     -- 0-100 (សម្រាប់តែ 1proxy)
  latency_ms INTEGER,                        -- មិល្លីវិនាទី (សម្រាប់តែ 1proxy)
  anonymity TEXT,                            -- ថ្លា/អនាមិក/កម្រិតខ្ពស់
  google_access INTEGER DEFAULT 0,           -- អាចចូលប្រើ Google បានទេ? (1proxy)
  last_validated TEXT,                       -- ត្រាពេលវេលា ISO (1proxy)
  country_code TEXT,                         -- កូដ ISO 2 អក្សរ (1proxy)
  created_at TEXT NOT NULL,
  updated_at TEXT NOT NULL
);
```

### តារាង `proxy_assignments`

```sql
CREATE TABLE proxy_assignments (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  proxy_id TEXT NOT NULL REFERENCES proxy_registry(id),
  scope TEXT NOT NULL,        -- 'global', 'provider', 'account', 'combo'
  scope_id TEXT,              -- ID អ្នកផ្ដល់សេវា, ID ការតភ្ជាប់ ឬ ID បន្សំ
  created_at TEXT NOT NULL,
  updated_at TEXT NOT NULL,
  UNIQUE(scope, scope_id)
);
```

---

## ការត្រួតពិនិត្យសុខភាពប្រូកស៊ី (v3.8.16+)

យន្តការ **បរាជ័យរហ័សរបស់ប្រូកស៊ី** របស់ OmniRoute (`src/lib/proxyHealth.ts`) រកឃើញប្រូកស៊ីដែលលែងដំណើរការក្នុងរយៈពេល <2s តាមរយៈការត្រួតពិនិត្យការតភ្ជាប់ TCP រហ័ស ហើយបន្ទាប់មក **រក្សាទុកលទ្ធផលក្នុងឃ្លាំងសម្ងាត់** ដើម្បីជៀសវាងបន្ទុកបន្ថែមសម្រាប់សំណើនីមួយៗ។

### របៀបដំណើរការ

```
សំណើ ──▶ ProxyHealthCache.get(url)
          │
          ├─ រកឃើញក្នុងឃ្លាំងសម្ងាត់ + នៅថ្មី?  ──▶ ត្រឡប់ស្ថានភាពដែលបានរក្សាទុក
          │
          └─ មិនមានក្នុងឃ្លាំងសម្ងាត់ / ហួសសុពលភាព?  ──▶ TCP ភ្ជាប់ទៅ host:port
                                                              (អស់ពេលរង់ចាំ: FAST_FAIL_TIMEOUT_MS)
                                                              ──▶ រក្សាទុកសម្រាប់ HEALTH_CACHE_TTL_MS
                                                              ──▶ ត្រឡប់លទ្ធផល
```

បើគ្មានយន្តការនេះ ប្រូកស៊ីដែលលែងដំណើរការនឹងរារាំងសំណើនីមួយៗក្នុងរយៈពេលពេញលេញនៃ `PROXY_TIMEOUT_MS` (លំនាំដើម 30s) មុននឹងបរាជ័យ។

### អថេរបរិស្ថានដែលអាចកែសម្រួលបាន

| អថេរ                         | លំនាំដើម | គោលបំណង                                                        |
| ---------------------------- | -------- | -------------------------------------------------------------- |
| `PROXY_FAST_FAIL_TIMEOUT_MS` | `2000`   | ពេលអស់កំណត់នៃការតភ្ជាប់ TCP សម្រាប់ការត្រួតពិនិត្យសុខភាពនីមួយៗ |
| `PROXY_HEALTH_CACHE_TTL_MS`  | `30000`  | រយៈពេលរក្សាទុកលទ្ធផលសុខភាពក្នុងឃ្លាំងសម្ងាត់                   |

**តម្លៃដែលបានណែនាំ៖**

| សេណារីយ៉ូ                         | ពេលអស់កំណត់បរាជ័យរហ័ស | TTL ឃ្លាំងសម្ងាត់ | មូលហេតុ                                                                                         |
| --------------------------------- | --------------------- | ----------------- | ----------------------------------------------------------------------------------------------- |
| API gateway ដែលមានលំហូរខ្ពស់      | 1500ms                | 60000ms           | បរាជ័យឱ្យបានឆាប់យ៉ាងសកម្ម និងរក្សាទុកក្នុងឃ្លាំងសម្ងាត់យូរជាងមុន ដើម្បីកាត់បន្ថយការត្រួតពិនិត្យ |
| ថ្នាំងចែកចាយតាមភូមិសាស្ត្រ        | 3000ms                | 15000ms           | បណ្ដាញយឺតត្រូវការពេលច្រើនជាងមុន; ឃ្លាំងសម្ងាត់ខ្លីជាងមុនសម្រាប់ការប្ដូរទិសពេលបរាជ័យយ៉ាងរហ័ស     |
| ការអភិវឌ្ឍ / ការធ្វើតេស្ត         | 1000ms                | 10000ms           | ការធ្វើឡើងវិញយ៉ាងរហ័សលើប្រូកស៊ីមូលដ្ឋាន                                                         |
| ការលាក់ខ្លួន / ការប្រឆាំងការរកឃើញ | 2500ms                | 45000ms           | ជៀសវាងការស្ទង់មើលញឹកញាប់ ដែលអាចបង្កឱ្យមានដែនកំណត់អត្រា                                          |

### ការពិនិត្យមើលសុខភាពប្រូកស៊ី

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

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

// បង្ខំឱ្យត្រួតពិនិត្យប្រូកស៊ីជាក់លាក់មួយឡើងវិញ
invalidateProxyHealth("http://user:pass@203.0.113.7:8080");
```

ទង់ `stale` មានតម្លៃ `true` នៅពេលធាតុក្នុងឃ្លាំងសម្ងាត់បានលើស `HEALTH_CACHE_TTL_MS` ហើយសំណើបន្ទាប់នឹងបង្កឱ្យមានការត្រួតពិនិត្យថ្មី។

### តម្លៃលំនាំដើមតាមប្រភេទប្រូកស៊ីនីមួយៗ

ការត្រួតពិនិត្យសុខភាពប្រើតម្លៃលំនាំដើមសមស្រប ដោយផ្អែកលើគ្រោងការណ៍ URL៖

| គ្រោងការណ៍                 | ច្រកលំនាំដើម |
| -------------------------- | ------------ |
| `http://`                  | 8080         |
| `https://`                 | 443          |
| `socks5://` / `socks5h://` | 1080         |

ច្រកផ្ទាល់ខ្លួនក្នុង URL (`http://host:9999`) តែងតែមានអាទិភាពលើតម្លៃលំនាំដើមរបស់គ្រោងការណ៍។

---

## ការវិភាគ និងការសង្កេតមើលប្រូកស៊ី

OmniRoute តាមដានការប្រើប្រាស់តាមប្រូកស៊ីនីមួយៗ ដើម្បីជួយឱ្យប្រតិបត្តិករធ្វើរោគវិនិច្ឆ័យលំនាំបញ្ជូន ស្ថានភាពកើនឡើងភ្លាមៗនៃភាពយឺតយ៉ាវ និងកំហុសដែលកើតឡើងដដែលៗ។

### អ្វីខ្លះដែលត្រូវបានតាមដាន

សម្រាប់រាល់សំណើដែលឆ្លងកាត់ប្រូកស៊ីដែលបានកំណត់រចនាសម្ព័ន្ធ OmniRoute កត់ត្រា៖

| ម៉ែត្រវាស់   | ការពិពណ៌នា                                                             |
| ------------ | ---------------------------------------------------------------------- |
| `proxy_url`  | URL ប្រូកស៊ីពេញលេញ (ដោយលាក់ព័ត៌មានសម្ងាត់សម្រាប់ផ្ទៀងផ្ទាត់អត្តសញ្ញាណ) |
| `provider`   | ID របស់អ្នកផ្តល់សេវាខាងលើ (openai, anthropic ជាដើម)                    |
| `latency_ms` | រយៈពេលសរុបសម្រាប់ការធ្វើដំណើរទៅមក រួមទាំងការចាប់ដៃជាមួយប្រូកស៊ី        |
| `connect_ms` | រយៈពេលតភ្ជាប់ TCP ប៉ុណ្ណោះ                                             |
| `status`     | កូដស្ថានភាព HTTP ពីប្រភពខាងលើ                                          |
| `error`      | ប្រភេទកំហុស ប្រសិនបើសំណើបានបរាជ័យ                                      |
| `timestamp`  | ISO 8601 UTC                                                           |

### ការចូលប្រើទិន្នន័យ

```bash
# ព្រឹត្តិការណ៍ប្រូកស៊ីថ្មីៗ
curl -H "Authorization: Bearer $OMNIROUTE_KEY" \
  "http://localhost:20128/api/usage/proxy-logs?limit=100"
```

ចំណុចបញ្ចប់ពិតប្រាកដគឺ `/api/usage/proxy-logs` (សូមមើល `src/app/api/usage/proxy-logs/route.ts`)។ ចំណុចបញ្ចប់នេះគាំទ្រ៖

- `GET /api/usage/proxy-logs` — ទាញយកកំណត់ហេតុប្រូកស៊ី
- `DELETE /api/usage/proxy-logs` — សម្អាតកំណត់ហេតុប្រូកស៊ីទាំងអស់

ស្ថិតិសរុបអាចត្រូវបានសាកសួរដោយផ្ទាល់ពីតារាង `proxy_logs` តាមរយៈ SQL ប្រសិនបើចាំបាច់។ ចំណុចប្រទាក់អ្នកប្រើនៃផ្ទាំងគ្រប់គ្រងអាចផ្តល់ជូនទិដ្ឋភាពស្ថិតិសរុប។

### លំនាំទូទៅ

**រកឃើញប្រូកស៊ីដែលដំណើរការមិនស្ថិរភាព** (ប្តូរឆ្លាស់រវាងជោគជ័យ/បរាជ័យ)៖

```sql
SELECT proxy_url,
       COUNT(*) AS total,
       SUM(CASE WHEN status >= 500 THEN 1 ELSE 0 END) AS errors,
       ROUND(100.0 * SUM(CASE WHEN status >= 500 THEN 1 ELSE 0 END) / COUNT(*), 1) AS error_pct
FROM proxy_logs
WHERE timestamp > datetime('now', '-1 hour')
GROUP BY proxy_url
HAVING error_pct > 5
ORDER BY error_pct DESC;
```

**ស្វែងរកប្រូកស៊ីយឺត** (ភាពយឺតយ៉ាវ p95 > 2 វិនាទី)៖

```sql
WITH ranked AS (
  SELECT proxy_url, latency_ms,
         PERCENT_RANK() OVER (PARTITION BY proxy_url ORDER BY latency_ms) AS pct
  FROM proxy_logs
  WHERE timestamp > datetime('now', '-24 hour')
)
SELECT proxy_url, latency_ms
FROM ranked
WHERE pct >= 0.95
ORDER BY latency_ms DESC;
```

---

## មែកធាងសម្រេចចិត្តសម្រាប់យុទ្ធសាស្ត្រប្តូរវេន

នៅពេលប្រូកស៊ីច្រើនត្រូវបានកំណត់ទៅឱ្យវិសាលភាពមួយ OmniRoute ប្រើ **យុទ្ធសាស្ត្រប្តូរវេន** ដើម្បីជ្រើសរើសប្រូកស៊ីដែលត្រូវប្រើសម្រាប់សំណើនីមួយៗ។ យុទ្ធសាស្ត្រនេះត្រូវបានកំណត់រចនាសម្ព័ន្ធនៅកម្រិតវិសាលភាព (សកល តាមអ្នកផ្តល់សេវា តាមគណនី ឬតាមបន្សំ)។

### យុទ្ធសាស្ត្រដែលមាន

| យុទ្ធសាស្ត្រ         | ពេលដែលត្រូវប្រើ                                    | ការដោះដូរ                                                                                                  |
| -------------------- | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `quality` (លំនាំដើម) | បរិស្ថានផលិតកម្មដែលមានប្រូកស៊ីគុណភាពចម្រុះ         | ផ្តល់អាទិភាពដល់ប្រូកស៊ីដែលមានការវាយតម្លៃខ្ពស់ ប៉ុន្តែអាចធ្វើឱ្យប្រូកស៊ីដែលមានការវាយតម្លៃទាបមិនត្រូវបានប្រើ |
| `random`             | ការចែកចាយបន្ទុក និងឯកជនភាព                         | ចែកចាយស្មើគ្នា ប៉ុន្តែមិនអើពើនឹងសញ្ញាគុណភាព                                                                |
| `sequential`         | ការបំបាត់កំហុស និងការធ្វើតេស្តដែលអាចកំណត់លទ្ធផលបាន | ប្តូរឆ្លងកាត់ប្រូកស៊ីតាមលំដាប់ ហើយងាយស្រួលយល់អំពីឥរិយាបថរបស់វា                                             |

### មែកធាងសម្រេចចិត្ត

```
                    តើអ្នកមានពិន្ទុគុណភាពសម្រាប់ប្រូកស៊ីរបស់អ្នកដែរឬទេ?
                    │
        ┌───────────┴───────────┐
        │                       │
       មាន                     គ្មាន
        │                       │
   តើប្រូកស៊ីទាំងអស់           │
   មានគុណភាពប្រហាក់ប្រហែលគ្នា     │
   ដែរឬទេ?                     │
        │                       │
   ┌────┴────┐                  │
   │         │                  │
  មាន       គ្មាន             ប្រើ
   │         │              `random`
   │         │              (ការចែកចាយស្មើគ្នា
   │         │              បង្កើតទិន្នន័យគុណភាព
   │         │              ក្នុងរយៈពេលយូរ)
   │         │
   │    ប្រើ `quality`
   │    (ល្អបំផុតសម្រាប់
   │    គុណភាពចម្រុះ)
   │
ប្រើ `random`
(ចែកចាយបន្ទុក
ឱ្យស្មើគ្នា)
```

## ការដកប្រូកស៊ីរបស់អ្នកដែលបរាជ័យចេញដោយស្វ័យប្រវត្តិ

ក្រុមប្រូកស៊ីក្នុងទីផ្សារ 1proxy បន្ថយអាទិភាពប្រូកស៊ីដែលបរាជ័យដោយស្វ័យប្រវត្តិរួចហើយ (សូមមើល
[ពិន្ទុគុណភាពប្រូកស៊ី](#proxy-quality-scores))។ សម្រាប់
ប្រូកស៊ីដែល **អ្នក** បានបន្ថែមទៅក្នុងបញ្ជីចុះឈ្មោះ កម្មវិធីកំណត់ពេលត្រួតពិនិត្យសុខភាពនៅផ្ទៃខាងក្រោយ
(`src/lib/proxyHealth/scheduler.ts`) ផ្តល់ឥរិយាបថដូចគ្នា គឺ «ដកសមាជិកដែលលែងដំណើរការចេញពី
ខ្សែសង្វាក់ដោយស្វ័យប្រវត្តិ» ដោយមិនលុបអ្វីទាំងអស់៖

```bash
# .env — បិទប្រូកស៊ីជាបណ្ដោះអាសន្ន បន្ទាប់ពីការស្ទង់ពិនិត្យបរាជ័យជាប់គ្នា 3 ដង ហើយបើកវាឡើងវិញ
# ដោយស្វ័យប្រវត្តិ នៅពេលវាចាប់ផ្ដើមឆ្លើយតបនឹងការស្ទង់ពិនិត្យម្ដងទៀត។
PROXY_AUTO_DISABLE=true
PROXY_AUTO_REMOVE_AFTER=3
```

របៀបដែលវាដំណើរការនៅក្នុងខ្សែសង្វាក់ប្រូកស៊ីច្រើន៖

1. កម្មវិធីកំណត់ពេលនឹងស្ទង់ពិនិត្យប្រូកស៊ីដែលបានចុះឈ្មោះនីមួយៗ រៀងរាល់ `PROXY_HEALTH_INTERVAL_MS`
   (លំនាំដើម 10 នាទី; អប្បបរមា 1 នាទី)។
2. បន្ទាប់ពីមានការបរាជ័យ **ដែលអាចសន្និដ្ឋានបានច្បាស់លាស់** ជាប់គ្នាចំនួន `PROXY_AUTO_REMOVE_AFTER` ដង (ការបរាជ័យក្នុងការ
   តភ្ជាប់ពិតប្រាកដ — ការអស់ពេលរង់ចាំ ឬកំហុស 5xx របស់គោលដៅស្ទង់ពិនិត្យផ្ទាល់ មិនត្រូវបានរាប់ឡើយ សូមមើល
   [ការត្រួតពិនិត្យសុខភាពប្រូកស៊ី](#proxy-health-checking-v3816)) `status` របស់ប្រូកស៊ី
   នឹងត្រូវបានកំណត់ទៅជា `dead`។
3. `dead` គឺជាស្ថានភាពមួយក្នុងចំណោមស្ថានភាពដែលតម្រងស្ថានភាពនៅដំណើរការ ដែលប្រើដោយការដោះស្រាយក្រុម/ការប្ដូរវេន
   នឹងដកចេញ ដូច្នេះការប្ដូរវេនរបស់វិសាលភាពមួយ (round-robin / random / sticky /
   latency — សូមមើល [មែកធាងសម្រេចចិត្តសម្រាប់យុទ្ធសាស្ត្រប្ដូរវេន](#rotation-strategy-decision-tree))
   នឹងឈប់ប្រគល់ប្រូកស៊ីនោះទៅឱ្យសំណើថ្មីៗភ្លាមៗ។ ប្រូកស៊ីផ្សេងទៀតនៅក្នុង
   ក្រុមមិនរងផលប៉ះពាល់ទេ ហើយក្រុមទាំងមូលក៏មិនដែលប្ដូរទៅប្រើការតភ្ជាប់ផ្ទាល់ដោយស្ងៀមស្ងាត់ដែរ —
   សូមមើលរបាំងបិទនៅពេលបរាជ័យនៃ [ប្រព័ន្ធប្រូកស៊ី 4 កម្រិត](#4-level-proxy-system)។
4. កម្មវិធីកំណត់ពេលបន្តស្ទង់ពិនិត្យប្រូកស៊ី `dead` តាមចន្លោះពេលដដែល។ ការស្ទង់ពិនិត្យជោគជ័យលើកបន្ទាប់
   នឹងប្ដូរ `status` ត្រឡប់ទៅជា `active` ហើយវានឹងចូលក្នុងការប្ដូរវេនឡើងវិញ —
   មិនចាំបាច់បន្ថែមឡើងវិញដោយដៃទេ។

មុខងារនេះត្រូវបានរចនាឡើងដោយចេតនា ដើម្បីឱ្យ **ត្រូវបើកប្រើដោយខ្លួនឯង និងមិនបង្កការបំផ្លិចបំផ្លាញ**៖ តាមលំនាំដើម កម្មវិធីកំណត់ពេលគ្រាន់តែ
រាប់ និងកត់ត្រាការបរាជ័យប៉ុណ្ណោះ (សូមមើលគោលការណ៍ C ក្នុង `decision.ts`) ហើយ `PROXY_AUTO_DISABLE`
មិនដែលលុបជួរទិន្នន័យឡើយ — នោះជាមុខងាររបស់ទង់ `PROXY_AUTO_REMOVE` ដាច់ដោយឡែក ដែលមានលក្ខណៈតឹងរ៉ឹងជាង។
ប្រសិនបើទាំងពីរត្រូវបានកំណត់ទៅជា `true` នោះ `PROXY_AUTO_REMOVE`
មានអាទិភាព (ប្រូកស៊ីដែលហៀបនឹងត្រូវលុប មិនចាំបាច់ត្រូវបិទជាបណ្ដោះអាសន្ននៅចន្លោះពេលនោះទេ)។ សូមមើលឯកសារយោង
[ការកំណត់រចនាសម្ព័ន្ធបរិស្ថាន](../reference/ENVIRONMENT.md) សម្រាប់បញ្ជីអថេរទាំងមូល។

---

> 📖 **ឯកសារពាក់ព័ន្ធ៖**
>
> - [មគ្គុទ្ទេសក៍អ្នកប្រើប្រាស់](../guides/USER_GUIDE.md) — ការដំឡើង និងការកំណត់រចនាសម្ព័ន្ធទូទៅ
> - [ឯកសារយោង API](../reference/API_REFERENCE.md) — ឯកសារ API ពេញលេញ
> - [ការកំណត់រចនាសម្ព័ន្ធបរិស្ថាន](../reference/ENVIRONMENT.md) — អថេរបរិស្ថានទាំងអស់