# 🐳 Docker Guide — OmniRoute (ខ្មែរ)

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

---

> ឯកសារយោងពេញលេញសម្រាប់ការដាក់ឱ្យដំណើរការជាមួយ Docker។ សម្រាប់ការចាប់ផ្តើមរហ័ស សូមមើល [ផ្នែក Docker ក្នុង README](../README.md#-docker)។

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

- [ដំណើរការរហ័ស](#quick-run)
- [ជាមួយឯកសារបរិស្ថាន](#with-environment-file)
- [Docker Compose](#docker-compose)
- [ប្រូហ្វាល់ដែលមាន](#available-profiles)
- [ការកំណត់រចនាសម្ព័ន្ធឧបករណ៍ CLI របស់ម៉ាស៊ីនមេ នៅពេល OmniRoute ដំណើរការក្នុង Docker](#configuring-host-cli-tools-when-omniroute-runs-in-docker)
- [Redis Sidecar](#redis-sidecar)
- [Compose សម្រាប់បរិស្ថានផលិតកម្ម](#production-compose)
- [ដំណាក់កាល Dockerfile](#dockerfile-stages)
- [អថេរបរិស្ថានសំខាន់ៗ](#critical-environment-variables)
- [Docker Compose ជាមួយ Caddy (HTTPS)](#docker-compose-with-caddy-https-auto-tls)
- [Cloudflare Quick Tunnel](#cloudflare-quick-tunnel)
- [ស្លាក Image](#image-tags)
- [លទ្ធភាពប្រើប្រាស់៖ SQLite លំនាំដើមគាំទ្រតែ replica មួយ](#availability-default-sqlite-is-single-replica)
- [កំណត់សម្គាល់សំខាន់ៗ](#important-notes)

---

## ការដំណើរការរហ័ស

> **បង្ហោះដោយខ្លួនឯងដោយប្រើពាក្យបញ្ជាតែមួយមែនទេ?** សូមមើល
> [មគ្គុទ្ទេសក៍បង្ហោះដោយខ្លួនឯង](../getting-started/SELF_HOST_GUIDE.md) —
> `docker compose -f docker-compose.selfhost.yml up -d` (image ដែលបានបោះពុម្ពផ្សាយ +
> Redis, សម្រាប់តែ loopback, មិនមានជម្រើស profile)។ ការដំណើរការរហ័សខាងក្រោមគឺជា
> វិធីប្រើ container តែមួយ សម្រាប់អ្នកប្រើដែលកំពុងដំណើរការ Redis នៅកន្លែងផ្សេងរួចហើយ។

```bash
docker run -d \
  --name omniroute \
  --restart unless-stopped \
  --stop-timeout 40 \
  -p 20128:20128 \
  -v omniroute-data:/app/data \
  diegosouzapw/omniroute:latest
```

## ជាមួយឯកសារបរិស្ថាន

```bash
# ជាដំបូង សូមចម្លង និងកែសម្រួល .env
cp .env.example .env

docker run -d \
  --name omniroute \
  --restart unless-stopped \
  --stop-timeout 40 \
  --env-file .env \
  -p 20128:20128 \
  -v omniroute-data:/app/data \
  diegosouzapw/omniroute:latest
```

## Docker Compose

```bash
# ប្រូហ្វាល់មូលដ្ឋាន (គ្មានឧបករណ៍ CLI)
docker compose --profile base up -d

# ប្រូហ្វាល់ CLI (ភ្ជាប់មកជាមួយ Claude Code, Codex, OpenClaw)
docker compose --profile cli up -d

# ប្រូហ្វាល់ម៉ាស៊ីនមេ (ផ្តោតលើ Linux ជាចម្បង; ម៉ោនឯកសារ binary របស់ CLI ពីម៉ាស៊ីនមេជាទម្រង់បានតែអាន)
docker compose --profile host up -d

# ប្រូហ្វាល់បណ្ដាញ (Chromium/Playwright សម្រាប់អ្នកផ្ដល់សេវាសម័យបណ្ដាញ)
docker compose --profile web up -d

# បញ្ចូល CLI + sidecar CLIProxyAPI រួមគ្នា
docker compose --profile cli --profile cliproxyapi up -d
```

## ប្រូហ្វាល់ដែលមាន

OmniRoute ផ្តល់ជូនប្រូហ្វាល់ Compose សម្រាប់ទម្រង់ដាក់ឱ្យដំណើរការសំខាន់ៗ។ ជ្រើសរើសមួយដែលសមស្របនឹងបរិស្ថានរបស់អ្នក។

| ប្រូហ្វាល់        | សេវាកម្ម         | ពេលណាត្រូវប្រើ                                                                                                                                                    | ពាក្យបញ្ជា                                   |
| ----------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
| `base` (លំនាំដើម) | `omniroute-base` | ម៉ាស៊ីនបម្រើគ្មានចំណុចប្រទាក់ក្រាហ្វិក / បរិស្ថានដំណើរការអប្បបរមា ដោយមិនមាន CLI របស់អ្នកផ្តល់សេវាភ្ជាប់មកជាមួយ                                                    | `docker compose --profile base up -d`        |
| `cli`             | `omniroute-cli`  | លំហូរការងារបែបភ្នាក់ងារដែលហៅ `omniroute providers/setup/doctor` និង CLI ដែលភ្ជាប់មកជាមួយ (Codex, Claude Code, Droid, OpenClaw)                                    | `docker compose --profile cli up -d`         |
| `host`            | `omniroute-host` | ម៉ាស៊ីនមេ Linux ដែលត្រូវការសិទ្ធិចូលប្រើ CLI របស់ម៉ាស៊ីនមេ ស្រដៀងនឹង `network_mode` តាមរយៈការម៉ោន `~/.local/bin`, `~/.codex`, `~/.claude` ជាដើម ក្នុងរបៀបបានតែអាន | `docker compose --profile host up -d`        |
| `cliproxyapi`     | `cliproxyapi`    | ដំណើរការ sidecar [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI) នៅលើច្រក `8317` សម្រាប់ការបញ្ជូនប្រូកស៊ី CLI ទៅ upstream                             | `docker compose --profile cliproxyapi up -d` |
| `web`             | `omniroute-web`  | អ្នកផ្តល់សេវាសម័យវេបដែលត្រូវការកម្មវិធីរុករក៖ `gemini-web`, `claude-web`, `claude-turnstile` (បង្កើត `runner-web` ដោយរួមបញ្ចូល Chromium)                          | `docker compose --profile web up -d`         |

> អាចបញ្ចូលប្រូហ្វាល់ច្រើនជាមួយគ្នាបាន៖ `docker compose --profile cli --profile cliproxyapi up -d`។

## ការកំណត់រចនាសម្ព័ន្ធឧបករណ៍ CLI របស់ម៉ាស៊ីន host នៅពេល OmniRoute ដំណើរការក្នុង Docker

`omniroute setup-codex`, `setup-claude`, `config set <tool>` និងប៊ូតុង
**រក្សាទុកការកំណត់រចនាសម្ព័ន្ធ** របស់ dashboard សុទ្ធតែសរសេរឯកសារដូចជា `~/.codex/*.config.toml`។ Path ទាំងនោះ
មានន័យតែនៅលើម៉ាស៊ីនដែល CLI ដំណើរការជាក់ស្តែងប៉ុណ្ណោះ។ ប្រសិនបើដំណើរការពួកវានៅក្នុង
container ការសរសេរនឹងចូលទៅក្នុង home ផ្ទាល់របស់ container (`/home/node` —
image ដំណើរការជា `USER node`) ដែល CLI នៅលើ host នឹងមិនអានឡើយ ហើយវានឹងត្រូវ
លុបចោលភ្លាមៗនៅពេល container ត្រូវបានបង្កើតឡើងវិញ។

OmniRoute រកឃើញស្ថានភាពនេះ ហើយបដិសេធការសរសេរ ព្រមទាំងបង្ហាញសេចក្តីណែនាំ ជំនួសឱ្យ
ការរាយការណ៍ជោគជ័យដែលអ្នកមិនអាចប្រើបាន៖ CLI បញ្ចប់ជាមួយកូដ `2` ហើយ API ឆ្លើយតប `422`
ជាមួយ `containerEphemeralTarget: true`។

### បានណែនាំ៖ ដំណើរការ CLI លើ host និង OmniRoute ក្នុង Docker

Container ផ្តល់សេវា API ខណៈ CLI កំណត់រចនាសម្ព័ន្ធឧបករណ៍នៅលើ host របស់អ្នក។

```bash
docker compose --profile base up -d

npm install -g omniroute
omniroute connect http://localhost:20128   # តម្រង់ CLI ទៅកាន់ container
omniroute setup-codex                      # សរសេរទៅកាន់ ~/.codex ពិតប្រាកដនៅលើ host របស់អ្នក
```

នេះជាជម្រើសត្រឹមត្រូវ នៅពេល Codex, Claude Code, Cursor ឬឧបករណ៍ស្រដៀងគ្នាដំណើរការលើ
laptop របស់អ្នក — ដែលនេះជាការដំឡើងធម្មតា។

### ជម្រើសផ្សេង៖ bind-mount ថត config របស់ host (profile `host`)

ប្រសិនបើអ្នកចង់ឱ្យ container ខ្លួនឯងសរសេរ config របស់ host សូម mount
ថតទាំងនោះចូល ហើយតម្រង់ `CLI_CONFIG_HOME` ទៅកាន់ mount root។ Profile `host`
បានធ្វើវារួចជាស្រេច៖

```yaml
environment:
  - CLI_CONFIG_HOME=/host-home
  - CLI_ALLOW_CONFIG_WRITES=true
volumes:
  - ~/.codex:/host-home/.codex:rw
  - ~/.claude:/host-home/.claude:rw
```

Bind mount គឺជាអ្វីដែលធ្វើឱ្យ path អាចទុកចិត្តបាន៖ OmniRoute អាន
`/proc/self/mountinfo` ហើយអនុញ្ញាតឱ្យសរសេរទៅកាន់ path ដែលបាន mount (និងទៅកាន់ថត
ដែលថតកូនរបស់វាជា mount ដែលត្រូវគ្នាពិតប្រាកដនឹងទម្រង់ `/host-home` ខាងលើ) ខណៈដែល
នៅតែបដិសេធថតដែលមិនបាន mount។

### ច្រកបម្រុង៖ កំណត់រចនាសម្ព័ន្ធ CLI ផ្ទាល់របស់ container (ប្រើតែនៅពេលចាំបាច់)

នៅពេល CLI ពិតជាស្ថិតនៅខាងក្នុង container (profile `cli`) ការសរសេរនោះ
គឺធ្វើឡើងដោយចេតនា។ បញ្ជូន `--allow-container-write` ទៅកាន់ command `setup-*` ណាមួយ ឬកំណត់
`OMNIROUTE_ALLOW_CONTAINER_CONFIG_WRITE=true` សម្រាប់ server។ ការសរសេរនឹងបន្ត
ជាមួយនឹងការព្រមានថា វានឹងមិននៅសល់ក្រោយពេល container ត្រូវបានបង្កើតឡើងវិញទេ។

> **ការព្រមានផ្នែកសុវត្ថិភាព — profile `cli` + ការ mount `docker.sock`។**
> Profile `cli` ធ្វើ bind-mount `/var/run/docker.sock` ដើម្បីឱ្យ
> auto-updater នៅក្នុង container អាចបង្កើត stack ឡើងវិញតាមរយៈ daemon របស់ host
> (`src/lib/system/autoUpdate.ts` ពិនិត្យរក socket នោះ ហើយរំលង
> Docker path នៅពេលវាមិនមាន)។ Socket នោះគឺជា **ព្រំដែនទំនុកចិត្តកម្រិត root របស់ host**៖
> អ្វីក៏ដោយដែលអាចចូលប្រើវាបាន អាចបញ្ជា Docker daemon របស់ host ជា
> root — វាអាចបង្កើត ពិនិត្យ បញ្ឈប់ និងលុប container ណាមួយនៅលើ host។
> ផលប៉ះពាល់៖
>
> 1. **កុំបើក port របស់ profile `cli` ទៅកាន់ network ជាដាច់ខាត។** Publish
>    វាលើ `127.0.0.1` (`ports: "127.0.0.1:${DASHBOARD_PORT:-20128}:..."`)
>    — profile `cli` ដែលអាចចូលប្រើបានពី LAN នឹងធ្វើឱ្យ RCE កម្រិត dashboard ណាមួយ
>    ក្លាយជាការគ្រប់គ្រង host ទាំងស្រុង។
> 2. **កុំ bind ថតបន្ថែមណាមួយរបស់ host ចូលក្នុង profile `cli`។**
>    Docker socket រួមជាមួយ mount បន្ថែមណាមួយ នឹងផ្តល់ឱ្យ container នូវសិទ្ធិ
>    អាន/សរសេរពេញលេញទៅលើ filesystem និង config របស់ host។ ប្រសិនបើអ្នកត្រូវការឱ្យឧបករណ៍មួយ
>    មើលឃើញ project សូមដំណើរការវានៅលើម៉ាស៊ីនផ្ទាល់ជាមួយ CLI binary — កុំ mount វា
>    ចូលទៅក្នុង container `cli`។
>
> ប្រសិនបើអ្នកមិនត្រូវការ auto-update ក្នុង container ទេ សូមកុំបើក profile `cli`
> (`COMPOSE_PROFILES=core,redis` ឬទម្រង់ខ្លីជាងនេះ)។ Profile ផ្សេងទៀតមិន
> mount Docker socket ទេ។
>
> សូមមើល `docs/security/MITM-TPROXY-DECRYPT.md` (git; មិនបាន compile ចូលក្នុង `/docs`) សម្រាប់ threat model ដែលពាក់ព័ន្ធ
> ជុំវិញ MITM និង `docs/security/SUPPLY_CHAIN.md` សម្រាប់ខ្សែសង្វាក់ប្រភពដើមនៃ binary
> `codex`/`claude-code`/`droid`/`openclaw`។

## Redis Sidecar

OmniRoute ពឹងផ្អែកលើ Redis ដើម្បីគាំទ្រកម្មវិធីកំណត់អត្រាបែបចែកចាយ និងឃ្លាំងសម្ងាត់រួម។ សេវា `redis` ត្រូវបាន **កំណត់ជានិច្ច** ក្នុង `docker-compose.yml` (វាមិនមានការកំណត់ដោយ profile ទេ) ហើយចាប់ផ្ដើមដំណើរការជាមួយ profile ផ្សេងទៀតណាមួយ។

| ព័ត៌មានលម្អិត                 | តម្លៃ                                      |
| ----------------------------- | ------------------------------------------ |
| Image                         | `redis:7-alpine`                           |
| ឈ្មោះ container               | `omniroute-redis`                          |
| Port ខាងក្នុង                 | `6379`                                     |
| Port របស់ host (កំណត់ជំនួស)   | `REDIS_PORT` (លំនាំដើមគឺ `6379`)           |
| ការចងភ្ជាប់ host (កំណត់ជំនួស) | `REDIS_BIND_HOST` (លំនាំដើមគឺ `127.0.0.1`) |
| Volume                        | `omniroute-redis-data` → `/data`           |
| ការត្រួតពិនិត្យសុខភាព         | `redis-cli ping` (ចន្លោះពេល 10 វិនាទី)     |

អថេរបរិស្ថានដែលពាក់ព័ន្ធ៖

- `REDIS_URL` — ខ្សែអក្សរតភ្ជាប់ដែលត្រូវបានបញ្ចូលទៅក្នុងកម្មវិធី (លំនាំដើមគឺ `redis://redis:6379`)។
- `REDIS_PORT` — ការផ្គូផ្គង port ផ្នែក host សម្រាប់ Redis container។
- `REDIS_BIND_HOST` — interface របស់ host ដែល port ត្រូវបានផ្សព្វផ្សាយនៅលើវា។ លំនាំដើមគឺ `127.0.0.1`។

> **ហេតុអ្វីបានជាប្រើ loopback ជាលំនាំដើម៖** sidecar ដំណើរការដោយគ្មាន `requirepass` ហើយ app
> container ភ្ជាប់ទៅវាតាមបណ្ដាញ compose (`redis:6379`) — port ដែលបានផ្សព្វផ្សាយ
> មានសម្រាប់តែឧបករណ៍ផ្នែក host ប៉ុណ្ណោះ (`redis-cli`, `npm run dev` នៅលើម៉ាស៊ីនមូលដ្ឋាន)។ ការផ្សព្វផ្សាយនៅលើ
> `0.0.0.0` នឹងបើកឱ្យគ្រប់ host នៅលើ LAN របស់អ្នកចូលប្រើ Redis ដែលមិនមានការផ្ទៀងផ្ទាត់។ ប្រសិនបើអ្នកកំណត់
> `REDIS_BIND_HOST=0.0.0.0` សូមបន្ថែម `--requirepass` ទៅក្នុង `command:` របស់សេវាផងដែរ។

**ការបិទ Redis** មិនត្រូវបានណែនាំទេ (កម្មវិធីកំណត់អត្រានឹងបន្ថយទៅប្រើជម្រើសបម្រុងក្នុងអង្គចងចាំ)។ ប្រសិនបើចាំបាច់ អ្នកអាចដកចេញ/ដាក់ជា comment នូវប្លុកសេវា `redis:` ក្នុង `docker-compose.yml` ឬកំណត់ទំហំវាទៅសូន្យ៖

```bash
docker compose up -d --scale redis=0
```

## Compose សម្រាប់ Production

សម្រាប់ snapshot នៃ production ដែលដាច់ដោយឡែក និងដំណើរការជាមួយបរិស្ថានអភិវឌ្ឍន៍ សូមប្រើ `docker-compose.prod.yml`។

| ព័ត៌មានលម្អិត           | តម្លៃ                                                                                         |
| ----------------------- | --------------------------------------------------------------------------------------------- |
| ឯកសារ                   | `docker-compose.prod.yml`                                                                     |
| Port dashboard លំនាំដើម | `PROD_DASHBOARD_PORT=20130` (ផ្គូផ្គងទៅ port ខាងក្នុង `${DASHBOARD_PORT:-20128}`)             |
| Port API លំនាំដើម       | `PROD_API_PORT=20131`                                                                         |
| Image                   | `omniroute:prod` (បាន build ពី target `runner-cli`)                                           |
| Redis container         | `omniroute-redis-prod` (`redis:8.6.2`, volume `redis-prod-data` ដាច់ដោយឡែក)                   |
| Volume ទិន្នន័យ         | `omniroute-prod-data` (មានឈ្មោះ និងត្រូវបានរក្សាទុកឆ្លងកាត់ការសាងសង់ឡើងវិញ)                   |
| ការត្រួតពិនិត្យសុខភាព   | `node healthcheck.mjs` + `redis-cli ping` ដោយ `depends_on` ត្រូវបានកំណត់អាស្រ័យលើសុខភាព Redis |

របៀបប្រើ៖

```bash
# Build និងចាប់ផ្ដើម production stack
docker compose -f docker-compose.prod.yml up -d --build

# បង្ហាញ log ជាបន្តបន្ទាប់
docker compose -f docker-compose.prod.yml logs -f

# បញ្ឈប់ និងដកចេញ (រក្សាទុក volume)
docker compose -f docker-compose.prod.yml down
```

Prod stack ដំណើរការស្របគ្នាជាមួយ dev compose (ឈ្មោះ container, port និង volume ខុសគ្នា) ដូច្នេះអ្នកអាចបន្តអភិវឌ្ឍនៅលើម៉ាស៊ីនមូលដ្ឋាន ខណៈដែល production នៅតែដំណើរការ។

## ដំណាក់កាល Dockerfile

ឃ្លាំងកូដនេះផ្ដល់ជូន Dockerfile ពហុដំណាក់កាល (`Dockerfile`)។ មានដំណាក់កាលចំនួនបួនដែលអាចប្រើបាន សូមជ្រើសរើស `target` ឱ្យសមស្របនឹងករណីប្រើប្រាស់របស់អ្នក។

| ដំណាក់កាល     | អ៊ីមេจមូលដ្ឋាន        | គោលបំណង                                                                                                                                                                                                                                                                                                             |
| ------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `builder`     | `node:26-trixie-slim` | ដំឡើង dependencies (`npm ci --legacy-peer-deps`) និងដំណើរការ `npm run build` (ប្រើ Turbopack តាមលំនាំដើម — សូមមើលធនធានពេល build ខាងក្រោម)                                                                                                                                                                           |
| `runner-base` | `node:26-trixie-slim` | បរិស្ថានដំណើរការ production ជាមួយលទ្ធផល standalone របស់ Next.js។ **មិនមានភ្ជាប់ CLI របស់ provider ទេ។**                                                                                                                                                                                                             |
| `runner-cli`  | `runner-base`         | បន្ថែម `git`, `docker.io`, `docker-compose` និង CLI សកល៖ `@openai/codex`, `@anthropic-ai/claude-code`, `droid`, `openclaw`។ **សូមជ្រើសរើសដំណាក់កាលនេះសម្រាប់ workflow បែប agentic។**                                                                                                                                |
| `runner-web`  | `runner-base`         | បន្ថែម Playwright + កម្មវិធីរុករក Chromium (`--with-deps`) សម្រាប់ provider ដែលប្រើ web session៖ `gemini-web`, `claude-web`, `claude-turnstile`។ **សូមជ្រើសរើសដំណាក់កាលនេះនៅពេលអ្នកប្រើ provider ទាំងនោះ** — អ៊ីមេจធម្មតានឹងបរាជ័យនៅពេលស្នើសុំ ប្រសិនបើគ្មានវា (សូមមើលកំណត់សម្គាល់ `-web` នៅក្រោមប៉ុស្តិ៍ចេញផ្សាយ)។ |

Build target ជាក់លាក់មួយដោយដៃ៖

```bash
docker build --target runner-base -t omniroute:base .
docker build --target runner-cli  -t omniroute:cli  .
docker build --target runner-web  -t omniroute:web  .
```

### ធនធានពេល build

build arg ចំនួនបីគ្រប់គ្រងការប្រើប្រាស់ធនធានរបស់ដំណាក់កាល `builder`។ ពួកវាប្រើតែនៅពេល build ប៉ុណ្ណោះ —
`OMNIROUTE_MEMORY_MB` (ខាងក្រោម) គឺជាការកំណត់សម្រាប់ runtime ដាច់ដោយឡែកមួយទៀត។

| Build arg                   | លំនាំដើម | ឥទ្ធិពល                                                                                        |
| --------------------------- | -------- | ---------------------------------------------------------------------------------------------- |
| `OMNIROUTE_USE_TURBOPACK`   | `1`      | `0` នឹង build ដោយប្រើ webpack ជំនួសវិញ។ ប្រើអង្គចងចាំនៅកម្រិតកំពូលតិចជាង ប៉ុន្តែយឺតជាង។        |
| `OMNIROUTE_BUILD_MEMORY_MB` | `6144`   | កម្រិតអតិបរមានៃ heap របស់ V8 (`--max-old-space-size`) សម្រាប់ `next build` ដែលត្រូវបានបង្កើត។  |
| `OMNIROUTE_BUILD_WORKERS`   | `2`      | បញ្ជូនតម្លៃទៅ `CIRCLE_NODE_TOTAL`; Next កំណត់ `workers = N - 1` សម្រាប់ការប្រមូលទិន្នន័យទំព័រ។ |

`OMNIROUTE_BUILD_WORKERS` គឺជាតម្លៃដែលគួរបង្កើននៅលើម៉ាស៊ីន build ធំ ហើយក៏ជាតម្លៃដែលគួរ
សង្ស័យនៅពេល build លើម៉ាស៊ីនដែលមានធនធានកម្របរាជ័យ **បន្ទាប់ពី** `✓ Compiled successfully`។ worker
សម្រាប់ទិន្នន័យទំព័រនីមួយៗគឺជា process ដាច់ដោយឡែក ហើយ process មេ `next build` ក៏ដូចគ្នា;
ការធ្វើតេស្តឡើងវិញលើ VPS ដែលកំពុងដំណើរការជាក់ស្ដែង (issue #7518) បានវាស់ឃើញថា RSS កម្រិតកំពូលរបស់ process នីមួយៗ
មានតម្លៃ ~4.5 GB ដោយឯករាជ្យពី flag heap របស់ `NODE_OPTIONS` (Turbopack compile នៅក្នុង
អង្គចងចាំ native/Rust ដែលនៅក្រៅ heap របស់ V8)។ តម្លៃលំនាំដើម `2` (→ worker 1, សរុប 2
process) ត្រូវបានកំណត់សម្រាប់ runner ដែល host ដោយ GitHub ទំហំ 16 GB / 4 vCPU ដែល
pipeline សម្រាប់ publish ប្រើ។ នៅតម្លៃ `8` (→ worker 7) runner នោះអស់អង្គចងចាំ ហើយ
buildkit បានធ្វើឱ្យជំហាននោះបរាជ័យជាមួយ `ResourceExhausted: ... cannot allocate memory`;
តម្លៃ `3` (→ worker 2) នៅតែមិនគ្រប់គ្រាន់ បន្ទាប់ពី RSS ក្នុងមួយ process ត្រូវបានវាស់
ដោយផ្ទាល់ ជំនួសឱ្យការប៉ាន់ស្មាន។ `tests/unit/docker-build-memory-budget.test.ts`
ធ្វើការគណនាដោយផ្អែកលើតួលេខដែលបានវាស់ ហើយនឹងបរាជ័យ ប្រសិនបើការកំណត់ណាមួយក្នុងចំណោមទាំងពីរ
លើសសមត្ថភាពរបស់ runner។

Turbopack compile នៅក្នុងអង្គចងចាំ native Rust ដែលស្ថិតនៅ **ក្រៅ** heap របស់ V8 ដូច្នេះ
`OMNIROUTE_BUILD_MEMORY_MB` មិនអាចកំណត់ព្រំដែនវាបានទេ។ នៅលើ host ដែលមានកម្រិតអង្គចងចាំ
build នឹងត្រូវបាន OOM killer បញ្ឈប់ដោយ SIGKILL ដោយមិនមានសារកំហុសអ្វីទាំងអស់ — វាគ្រាន់តែ
ឈប់នៅពាក់កណ្ដាល `Creating an optimized production build` ដែលមើលទៅដូចជាគាំង ជាជាង
អស់អង្គចងចាំ។ ប្រសិនបើ build host មានធនធានកម្រិតទាប សូមប្ដូរ bundler៖

```bash
docker build --target runner-base \
  --build-arg OMNIROUTE_USE_TURBOPACK=0 \
  -t omniroute:base .
```

`webpackBuildWorker` ត្រូវបានបើក ដូច្នេះ `next build` ដំណើរការ process មេ **និង** process worker
ហើយ process នីមួយៗគោរពតាម `OMNIROUTE_BUILD_MEMORY_MB` ដោយឡែកពីគ្នា។ កំណត់កម្រិតអង្គចងចាំរបស់ container
ឱ្យលើសប្រហែលពីរដងនៃតម្លៃនោះ មិនមែនត្រឹមមួយដងទេ។

បានវាស់នៅលើមែកធាងនេះ (`--target runner-base`, `OMNIROUTE_BUILD_MEMORY_MB=6144`)៖

| Bundler   | កម្រិតអង្គចងចាំរបស់ container | លទ្ធផល                                             |
| --------- | ----------------------------- | -------------------------------------------------- |
| Turbopack | 8 GiB / 16 GiB                | ត្រូវបាន OOM-killed នៅកម្រិតទាំងពីរ ដោយស្ងាត់ស្ងៀម |
| webpack   | 8 GiB                         | build worker ត្រូវបាន SIGKILL                      |
| webpack   | 12 GiB                        | ជោគជ័យ ដោយឡើងដល់កម្រិតកំពូល 11.1 GiB               |

### តម្លៃលំនាំដើមពេល runtime

តម្លៃលំនាំដើមដែល export ដោយ `runner-base`៖ `PORT=20128`, `HOSTNAME=0.0.0.0`, `OMNIROUTE_MEMORY_MB=1024`, `NODE_OPTIONS=--max-old-space-size=1024`, `DATA_DIR=/app/data`, `OMNIROUTE_MIGRATIONS_DIR=/app/migrations`។

ឥរិយាបថអង្គចងចាំនៅក្នុង Docker៖

- Image កំណត់ `OMNIROUTE_MEMORY_MB=1024` ហើយទាញយក `NODE_OPTIONS=--max-old-space-size=1024` ពីវា។
- ដំណើរការ server ជាក់ស្តែងត្រូវបានចាប់ផ្ដើមដោយ standalone launcher ដែលអាន `OMNIROUTE_MEMORY_MB` ហើយបន្ថែម `--max-old-space-size=<OMNIROUTE_MEMORY_MB>`។
- Node ប្រើតម្លៃ `--max-old-space-size` ដែលបានបញ្ជាក់ម្តងទៀតចុងក្រោយ ដូច្នេះការកំណត់ `OMNIROUTE_MEMORY_MB` គ្រប់គ្រងដែនកំណត់ heap ជាក់ស្តែងរបស់ Docker។
- ដោយសារ image តែងតែកំណត់វា fallback ដែលកែតម្រូវតាម RAM របស់ launcher នឹងមិនត្រូវបានប្រើក្រោម Docker ទេ។ សូមបង្កើនវាដោយជាក់លាក់សម្រាប់ workload (តារាងខាងក្រោម)។ `2048` នៅតែតូចពេកសម្រាប់ `/v1/responses` របស់ coding agent។

### RAM ពេលដំណើរការសម្រាប់ coding agent

តម្លៃលំនាំដើម 1 GiB របស់ Docker គឺជាកម្រិតអប្បបរមាសម្រាប់ dashboard/light chat មិនមែនជាទំហំសម្រាប់ production ទេ។ Body វែងៗរបស់ `POST /v1/responses` (មានសាររាប់រយ និង tools រាប់សិប) រក្សាទុកក្រាហ្វជាច្រើនក្នុង memory អំឡុងពេល compression។ Request ពីរដែលត្រួតគ្នា ដែលនីមួយៗមានទំហំប្រហែល ~3 MiB / ~750k-token បានធ្វើឱ្យ V8 បញ្ឈប់នៅ old-space ទំហំ **12 GiB** (`FATAL ERROR: Reached heap limit`) ហើយក៏បានប៉ះ cgroup OOM ទំហំ 16 GiB ផងដែរ។ សូមមើល [#7849](https://github.com/diegosouzapw/OmniRoute/issues/7849)។

កំណត់ទំហំ **cgroup `--memory` ឱ្យធំជាង heap** — native buffers, SQLite និងទិន្នន័យបណ្ដោះអាសន្នរបស់ compression ស្ថិតនៅក្រៅ V8។

| Workload                                   | `OMNIROUTE_MEMORY_MB`            | Container / cgroup             | កំណត់សម្គាល់                                                                                                                        |
| ------------------------------------------ | -------------------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| Dashboard និង light chat មួយ               | `1024` (តម្លៃលំនាំដើមរបស់ image) | ≥2 GiB                         |                                                                                                                                     |
| Coding agent មួយ (Claude/Codex/Grok)       | `8192`                           | ≥10 GiB                        | ជាទូទៅសម្រាប់ `/v1/responses` ក្នុង session តែមួយ                                                                                   |
| `/v1/responses` វែងពីរដែលដំណើរការដំណាលគ្នា | `10240`–`12288`                  | ≥12–16 GiB                     | បានវាស់ឃើញថា V8 បញ្ឈប់នៅ heap ទំហំប្រហែល ~12 GiB                                                                                    |
| Context វែងៗចំនួនបី ឬច្រើនជាងនេះ           | កុំដំណើរការលើ process តែមួយ      | ដំណើរការតាមលំដាប់ / RAM បន្ថែម | តាមលំនាំដើម ការទទួលយក workload ធ្ងន់ៗអនុញ្ញាតឱ្យមាន 1 in-flight; ការបង្កើនវាដោយគ្មាន RAM គ្រប់គ្រាន់នឹងធ្វើឱ្យការបញ្ឈប់នេះកើតឡើងវិញ |

`omniroute serve` នៅលើ bare metal កែតម្រូវទៅប្រហែល ~35% នៃ RAM (កំណត់ក្នុងចន្លោះ `[512, 4096]`) នៅពេល `OMNIROUTE_MEMORY_MB` **មិនត្រូវបានកំណត់**។ Docker តែងតែកំណត់វាជា `1024` ដូច្នេះការកែតម្រូវនោះមិនដែលដំណើរការនៅក្នុង official image ទេ។

```bash
docker run -d --name omniroute --restart unless-stopped --stop-timeout 40 \
  -e OMNIROUTE_MEMORY_MB=8192 --memory=10g \
  -p 127.0.0.1:20128:20128 -v omniroute-data:/app/data diegosouzapw/omniroute:latest
```

## អថេរបរិស្ថានសំខាន់ៗ

ក្រៅពីតម្លៃលំនាំដើមដែលបានចងក្រងជាឯកសារនៅក្នុង [ENVIRONMENT.md](../reference/ENVIRONMENT.md) អថេរខាងក្រោមមានសារៈសំខាន់បំផុតនៅពេលដំណើរការក្រោម Docker៖

| អថេរ                          | គោលបំណង                                                                                                                                                                                                                                                             | លំនាំដើម                      |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
| `OMNIROUTE_WS_BRIDGE_SECRET`  | ពាក្យសម្ងាត់រួមសម្រាប់ WebSocket bridge។ **តម្រូវឱ្យមានក្នុងបរិស្ថាន production** — កំណត់វាជាខ្សែអក្សរចៃដន្យដែលរឹងមាំ។                                                                                                                                              | មិនបានកំណត់ (ត្រូវតែផ្តល់ជូន) |
| `REDIS_URL`                   | ខ្សែអក្សរតភ្ជាប់សម្រាប់កម្មវិធីកំណត់អត្រា / cache backend                                                                                                                                                                                                           | `redis://redis:6379`          |
| `REDIS_PORT`                  | ច្រកនៅខាង host សម្រាប់ Redis container ដែលភ្ជាប់មកជាមួយ                                                                                                                                                                                                             | `6379`                        |
| `REDIS_BIND_HOST`             | host interface ដែលច្រក Redis ដែលភ្ជាប់មកជាមួយត្រូវបានបោះពុម្ពផ្សាយនៅលើវា (loopback លុះត្រាតែអ្នកបន្ថែម AUTH)                                                                                                                                                        | `127.0.0.1`                   |
| `AUTO_UPDATE_HOST_REPO_DIR`   | path នៅលើ host ដែលត្រូវបាន mount ចូលទៅក្នុង profile `cli` នៅ `/workspace/omniroute` សម្រាប់ដំណើរការ self-update                                                                                                                                                     | `.` (ថតបច្ចុប្បន្ន)           |
| `OMNIROUTE_MEMORY_MB`         | កម្រិតអតិបរមា Node heap ពេលដំណើរការសម្រាប់ Docker standalone server; ជំនួសតម្លៃលំនាំដើមរបស់ image ខាងលើ។ ភ្នាក់ងារសរសេរកូដ៖ `8192`+ (សូមមើល [RAM ពេលដំណើរការ](#runtime-ram-for-coding-agents))។                                                                     | `1024`                        |
| `DASHBOARD_PORT` / `API_PORT` | ជំនួសច្រកដែលបើកបង្ហាញសម្រាប់ dashboard (20128) និង API (20129)                                                                                                                                                                                                      | `20128` / `20129`             |
| `APP_BIND_HOST`               | host interface ដែល docker-compose បោះពុម្ពផ្សាយច្រក dashboard/API/live-WS នៅលើវា។ ជាមួយ `REQUIRE_API_KEY=false` (តម្លៃលំនាំដើម) `0.0.0.0` បើកបង្ហាញ proxy `/v1` អនាមិកទៅកាន់ LAN — ពង្រីកការចូលប្រើតែជាមួយ `REQUIRE_API_KEY=true` ឬ reverse proxy នៅខាងមុខប៉ុណ្ណោះ។ | `127.0.0.1`                   |
| `CLIPROXY_BIND_HOST`          | host interface ដែល docker-compose បោះពុម្ពផ្សាយ sidecar `cliproxyapi` នៅលើវា — data volume របស់វាផ្ទុកព័ត៌មានសម្គាល់អត្តសញ្ញាណរបស់ provider។                                                                                                                        | `127.0.0.1`                   |
| `OMNIROUTE_PLUGINS_DIR`       | ថតដែល runtime plugin scanner អាន និងដំឡើងចូល។ កំណត់វានៅពេល plugins ត្រូវបាន bind-mount៖ តម្លៃលំនាំដើមអនុវត្តតាម `HOME` ដែល image មិនចាំបាច់ export ទេ។                                                                                                              | `~/.omniroute/plugins`        |
| `OMNIROUTE_BASE_PATH`         | URL subpath នៅពេល app ត្រូវបានបោះពុម្ពផ្សាយនៅពីក្រោយ reverse proxy (ឧ. `/omniroute`)                                                                                                                                                                                | _(ទទេ = root)_                |
| `NEXT_PUBLIC_BASE_URL`        | browser origin សាធារណៈដែលរួមបញ្ចូល subpath (ឧ. `https://host/omniroute`)                                                                                                                                                                                            | មិនបានកំណត់                   |
| `PROD_DASHBOARD_PORT`         | ច្រក dashboard នៅខាង host សម្រាប់ `docker-compose.prod.yml`                                                                                                                                                                                                         | `20130`                       |
| `CLIPROXYAPI_PORT`            | ច្រកនៅខាង host សម្រាប់ sidecar `cliproxyapi`                                                                                                                                                                                                                        | `8317`                        |

## ប្រូកស៊ីបញ្ច្រាសលើផ្លូវរង (Traefik / nginx)

`basePath` របស់ Next.js ត្រូវបានចងក្រងបញ្ចូលក្នុងបណ្ណុំ standalone។ OmniRoute កត់ត្រាតម្លៃដែលបានបង្កប់នេះក្នុងឯកសារ sentinel នៅឫសរបស់កម្មវិធី (សរសេរកំឡុងពេល `npm run build`; អានដោយ `scripts/docker/ensure-docker-base-path.mjs`) ហើយប្រៀបធៀបវាជាមួយ `OMNIROUTE_BASE_PATH` នៅពេល container ចាប់ផ្ដើម។ នៅពេលតម្លៃទាំងពីរខុសគ្នា ហើយ image ត្រូវបាន build សម្រាប់ឫសដូមែន entrypoint នឹងសរសេរ standalone manifests ឡើងវិញ ព្រមទាំង literal `basePath`/`assetPrefix` ដែលបានបង្កប់ (Next 16 បង្កើត URL ធនធាន SSR ពី `assetPrefix` តែប៉ុណ្ណោះ — patcher នឹងចម្លងផ្លូវរងទៅក្នុងវាផងដែរ), URL ធនធាន `/_next/static` ដែលបានបង្កប់ (client-reference manifests, media imports, ទំព័រកំហុសដែលបាន prerender) និង shim `process.env` របស់ client មុនពេល `node dev/run-standalone.mjs` ដំណើរការ។

### ការ build ជាមួយ Compose (បានណែនាំ)

កំណត់អថេរទាំងពីរក្នុង `.env` រួច build ឡើងវិញ ដើម្បីឱ្យ image និង runtime មានតម្លៃដូចគ្នា៖

```bash
# .env
OMNIROUTE_BASE_PATH=/omniroute
NEXT_PUBLIC_BASE_URL=https://myhostname.example.com/omniroute
```

```bash
docker compose --profile base up -d --build
```

`docker-compose.yml` បញ្ជូនបន្ត `OMNIROUTE_BASE_PATH` ជា Docker build-arg និងជាអថេរបរិស្ថានពេល runtime។

### Root image ដែលបាន build ជាមុន + ផ្លូវរងពេល runtime

Image `diegosouzapw/omniroute:*` ដែលបានចេញផ្សាយ ត្រូវបាន build សម្រាប់ឫសដូមែន។ អ្នកនៅតែអាចកំណត់ `OMNIROUTE_BASE_PATH` នៅពេល runtime បាន; container នឹង patch បណ្ណុំមួយដងនៅពេលចាប់ផ្ដើម។ ប្រើវាជាមួយ public origin ដែលត្រូវគ្នា៖

```yaml
services:
  omniroute:
    image: diegosouzapw/omniroute:latest
    environment:
      OMNIROUTE_BASE_PATH: /omniroute
      NEXT_PUBLIC_BASE_URL: https://myhostname.example.com/omniroute
```

កំណត់រចនាសម្ព័ន្ធប្រូកស៊ីបញ្ច្រាសឱ្យបញ្ជូនបន្តផ្លូវខាងក្រៅ **ទាំងមូល** (កុំដក prefix ចេញ)។ Traefik គួរតែបញ្ជូន `PathPrefix(`/omniroute`)` ទៅ container ដោយគ្មាន `StripPrefix` ដើម្បីឱ្យ Next.js ទទួលបាន `/omniroute/...` និងបម្រើធនធានពី `/omniroute/_next/...`។

Docker healthcheck ពិនិត្យ lifecycle endpoint ទម្ងន់ស្រាល `/healthz` ដែលដាក់ prefix ដោយ `OMNIROUTE_BASE_PATH` កំពុងសកម្ម។ `/api/monitoring/health` នៅតែអាចប្រើបានសម្រាប់ការធ្វើរោគវិនិច្ឆ័យដោយមនុស្ស/dashboard; ដើម្បីឱ្យ HEALTHCHECK របស់ container ប្រើ endpoint នេះវិញ (ឧទាហរណ៍ សម្រាប់ការអនុវត្ត deep health យ៉ាងតឹងរ៉ឹង) សូមកំណត់ `OMNIROUTE_HEALTHCHECK_PATH=/api/monitoring/health`។ ផ្លូវនោះគឺជាការពិនិត្យ **ជ្រៅ** (DB + សេចក្ដីសង្ខេបការត្រួតពិនិត្យ) — សមស្របសម្រាប់ `HEALTHCHECK` ដែល Docker ដំណើរការមិនញឹកញាប់ ប្រសិនបើអ្នកជ្រើសរើសប្រើវាវិញ ប៉ុន្តែ **មិនសមស្រប** សម្រាប់ចន្លោះពេល `livenessProbe` របស់ Kubernetes ទេ។

សម្រាប់ប្រព័ន្ធ orchestration (Kubernetes, Nomad ជាដើម)៖

| Probe           | គួរប្រើ                                                       | គួរជៀសវាង                                          |
| --------------- | ------------------------------------------------------------- | -------------------------------------------------- |
| Liveness        | HTTP `GET /livez` ឬ TCP លើ port មេ (`PORT`, លំនាំដើម `20128`) | ប្រើ `/api/monitoring/health` ជា liveness          |
| Readiness       | HTTP `GET /healthz`                                           | timeout ខ្លីពេកដែលចាត់ទុក event-loop រវល់ថាបានដាច់ |
| Deep / blackbox | `/api/monitoring/health`                                      | —                                                  |

`/healthz` រាយការណ៍អំពី lifecycle របស់ process (`ok` / `starting` / `stopping`)។ `/livez` ពិនិត្យតែថា process នៅដំណើរការប៉ុណ្ណោះ (ត្រឡប់ 200 គ្រប់ពេលដែល handler អាចដំណើរការ; វាមិនរង់ចាំ readiness ទេ)។ ទាំងពីរនៅតែដំណើរការលើ Node event loop ដូចគ្នានឹងការគ្រប់គ្រង request ដូច្នេះការងារ catalog ឬ compression ដែលប្រើ CPU ច្រើនអាចធ្វើឱ្យពួកវាយឺត — រវល់ ≠ ដាច់។ គួរប្រើ TCP liveness ប្រសិនបើ HTTP probe អស់ពេល។ សេចក្ដីណែនាំពេញលេញអំពី probe៖
[មគ្គុទ្ទេសក៍ត្រួតពិនិត្យ — អនុសាសន៍អំពី probe របស់ Kubernetes](../ops/MONITORING_GUIDE.md#kubernetes-probe-recommendations)។

## Docker Compose ជាមួយ Caddy (HTTPS Auto-TLS)

OmniRoute អាចត្រូវបានបើកឱ្យចូលប្រើដោយសុវត្ថិភាព ដោយប្រើការផ្ដល់ SSL ដោយស្វ័យប្រវត្តិរបស់ Caddy។ សូមប្រាកដថា DNS A record របស់ដូមែនអ្នកចង្អុលទៅកាន់ IP របស់ម៉ាស៊ីនមេអ្នក។

```yaml
services:
  omniroute:
    image: diegosouzapw/omniroute:latest
    container_name: omniroute
    restart: unless-stopped
    volumes:
      - omniroute-data:/app/data
    environment:
      - PORT=20128
      # Origin ដែលបង្ហាញទៅកម្មវិធីរុករក សម្រាប់ OAuth callbacks តំណផ្ទាំងគ្រប់គ្រង និង URL សាធារណៈដែលបានបង្កើត។
      - NEXT_PUBLIC_BASE_URL=https://your-domain.com
      # URL ខាងក្នុងពីម៉ាស៊ីនមេទៅម៉ាស៊ីនមេ សម្រាប់ការងារដែលបានកំណត់ពេល / ការទាញយកខ្លួនឯង។
      - BASE_URL=http://omniroute:20128
      - AUTH_COOKIE_SECURE=true

  caddy:
    image: caddy:latest
    container_name: caddy
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    command: caddy reverse-proxy --from https://your-domain.com --to http://omniroute:20128

volumes:
  omniroute-data:
```

Caddy កំណត់បឋមកថាបញ្ជូនបន្តស្តង់ដារសម្រាប់កុងតឺន័រ upstream។ OmniRoute ប្រើ
`NEXT_PUBLIC_BASE_URL` ជា origin សាធារណៈស្តង់ដារ សម្រាប់ OAuth callbacks និងតំណសាធារណៈ
ដែលបានបង្កើត។ ប្រតិបត្តិការសរសេរដែលបានផ្ទៀងផ្ទាត់នៅលើផ្ទាំងគ្រប់គ្រង ប្រើសំណើ same-origin រួមជាមួយការការពារ CSRF
ដែលភ្ជាប់នឹង session។ បើក `OMNIROUTE_TRUST_PROXY` សម្រាប់តែការដាក់ឱ្យប្រើប្រាស់កម្រិតខ្ពស់ ដែលអ្នកមានបំណង
ឱ្យ OmniRoute កំណត់ origin សាធារណៈពីបឋមកថាបញ្ជូនបន្តដែលអាចទុកចិត្តបាន ជំនួសឱ្យការកំណត់រចនាសម្ព័ន្ធ
ច្បាស់លាស់។

## Cloudflare Quick Tunnel

ការគាំទ្រផ្ទាំងគ្រប់គ្រងសម្រាប់ការដាក់ឱ្យប្រើប្រាស់តាម Docker រួមមាន **Cloudflare Quick Tunnel** ដែលអាចដំណើរការដោយចុចតែម្តង នៅលើ `Dashboard → Endpoints`។ ការបើកជាលើកដំបូងទាញយក `cloudflared` តែនៅពេលត្រូវការ ចាប់ផ្ដើម tunnel បណ្ដោះអាសន្នទៅកាន់ endpoint `/v1` បច្ចុប្បន្នរបស់អ្នក ហើយបង្ហាញ URL `https://*.trycloudflare.com/v1` ដែលបានបង្កើត ដោយផ្ទាល់នៅខាងក្រោម URL សាធារណៈធម្មតារបស់អ្នក។

ផ្ទាំង tunnel របស់ endpoint (Cloudflare, Tailscale, ngrok) អាចត្រូវបានបង្ហាញ ឬលាក់ពី `Settings → Appearance` ដោយមិនផ្លាស់ប្ដូរស្ថានភាព tunnel ដែលកំពុងសកម្ម។

### កំណត់សម្គាល់អំពី Tunnel

- URL របស់ Quick Tunnel គឺបណ្ដោះអាសន្ន និងផ្លាស់ប្ដូរបន្ទាប់ពីការចាប់ផ្ដើមឡើងវិញនីមួយៗ។
- Quick Tunnels មិនត្រូវបានស្ដារឡើងវិញដោយស្វ័យប្រវត្តិ បន្ទាប់ពី OmniRoute ឬកុងតឺន័រចាប់ផ្ដើមឡើងវិញទេ។ សូមបើកវាឡើងវិញពីផ្ទាំងគ្រប់គ្រងនៅពេលត្រូវការ។
- ការដំឡើងដែលបានគ្រប់គ្រង បច្ចុប្បន្នគាំទ្រ Linux, macOS និង Windows នៅលើ `x64` / `arm64`។
- Managed Quick Tunnels ប្រើ HTTP/2 transport ជាលំនាំដើម ដើម្បីជៀសវាងការព្រមានអំពី QUIC UDP buffer ដែលរំខាន នៅក្នុងបរិស្ថានកុងតឺន័រដែលមានធនធានកម្រិត។ កំណត់ `CLOUDFLARED_PROTOCOL=quic` ឬ `auto` ប្រសិនបើអ្នកចង់ប្រើ transport ផ្សេង។
- Docker images មានបញ្ចូល system CA roots និងបញ្ជូនវាទៅកាន់ `cloudflared` ដែលបានគ្រប់គ្រង ដើម្បីជៀសវាងបញ្ហាបរាជ័យនៃការទុកចិត្ត TLS នៅពេល tunnel ចាប់ផ្ដើមនៅខាងក្នុងកុងតឺន័រ។
- កំណត់ `CLOUDFLARED_BIN=/absolute/path/to/cloudflared` ប្រសិនបើអ្នកចង់ឱ្យ OmniRoute ប្រើ binary ដែលមានស្រាប់ ជំនួសឱ្យការទាញយកថ្មី។

## ស្លាក Image

| Image                    | ស្លាក    | ទំហំ   | សេចក្ដីពិពណ៌នា                                                              |
| ------------------------ | -------- | ------ | --------------------------------------------------------------------------- |
| `diegosouzapw/omniroute` | `latest` | ~250MB | កំណែ SemVer ស្ថិរភាពដែលបាន **បោះពុម្ពផ្សាយ** ខ្ពស់បំផុត (មិនមែន git `main`) |
| `diegosouzapw/omniroute` | `3.8.0`  | ~250MB | ចងភ្ជាប់ស្លាកប្រភេទនេះសម្រាប់ GitOps                                        |

Manifest ពហុវេទិកា៖ `linux/amd64` + `linux/arm64` ដើម (Apple Silicon, AWS Graviton, Raspberry Pi)។ Docker ជ្រើសរើសស្ថាបត្យកម្មដែលត្រូវគ្នាដោយស្វ័យប្រវត្តិ; បញ្ជូន `--platform linux/amd64` ប្រសិនបើអ្នកត្រូវការបង្ខំការត្រាប់តាម AMD64 នៅលើម៉ាស៊ីនមេ ARM។

### ឆានែលចេញផ្សាយ

OmniRoute បោះពុម្ពផ្សាយឆានែល Docker ដាច់ដោយឡែកសម្រាប់ការចេញផ្សាយស្ថិរភាព ការសាកល្បង release branch ដែលកំពុងសកម្ម និង build សម្រាប់ការអភិវឌ្ឍ។

| ឆានែល                           | ប្រភព                                                   | ភាពអាចផ្លាស់ប្ដូរបាន                  | ការប្រើប្រាស់ដែលបានណែនាំ                                                                                                             |
| ------------------------------- | ------------------------------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `:<version>` / `:<version>-web` | ការចេញផ្សាយដែលបានចុះហត្ថលេខា/កំណត់កំណែ                  | មិនអាចផ្លាស់ប្ដូរបាន                  | ការដាក់ឱ្យដំណើរការក្នុង production ដែលចងភ្ជាប់ទៅនឹងកំណែចេញផ្សាយជាក់លាក់មួយ                                                           |
| `:latest` / `:latest-web`       | កំណែ SemVer ស្ថិរភាពដែលបាន **បោះពុម្ពផ្សាយ** ខ្ពស់បំផុត | ទ្រនិចស្ថិរភាពដែលអាចផ្លាស់ប្ដូរបាន    | តាមដានការចេញផ្សាយស្ថិរភាព **បន្ទាប់ពី** job បោះពុម្ពផ្សាយ SemVer — **មិន** តាមដាន `main` ឬ commit `release/v*` ដែលមិនទាន់បានចេញផ្សាយ |
| `:next` / `:next-web`           | branch `release/v*` លំនាំដើមបច្ចុប្បន្ន                 | ទ្រនិចមុនចេញផ្សាយដែលអាចផ្លាស់ប្ដូរបាន | សាកល្បងការកែតម្រូវដែលបានបញ្ចូលទៅក្នុង release branch សកម្ម ប៉ុន្តែមិនទាន់មានក្នុងការចេញផ្សាយស្ថិរភាព                                 |
| `:main` / `:main-web`           | branch `main`                                           | ទ្រនិចអភិវឌ្ឍន៍ដែលអាចផ្លាស់ប្ដូរបាន   | សម្រាប់តែការអភិវឌ្ឍ និងការសាកល្បងសមាហរណកម្មប៉ុណ្ណោះ                                                                                  |

#### អ្នកផ្ដល់សេវា web-session៖ image `-web`

ឆានែលនីមួយៗខាងលើមានស្លាក `-web` ផងដែរ (`:latest-web`, `:<version>-web`, `:next-web`, `:main-web`) ដែលត្រូវបាន build ពី stage `runner-web` — ជា image ដូចគ្នា បូកបន្ថែម Playwright និង browser Chromium។ image ធម្មតាត្រូវបានចែកចាយ **ដោយគ្មាន** Chromium; `gemini-web`, `claude-web` និង `claude-turnstile` ត្រូវការវា។

ការបរាជ័យត្រូវបានពន្យារពេល មិនមែនកើតឡើងនៅពេលចាប់ផ្ដើមទេ៖ អ្នកផ្ដល់សេវាទាំងនោះរាយបញ្ជី model របស់ពួកគេ និងបង្ហាញថាបានតភ្ជាប់នៅក្នុង dashboard ហើយមានតែ request ដំបូងប៉ុណ្ណោះដែលបរាជ័យជាមួយ

```
[500]: Failed to load external module playwright: Error: Cannot find module
'/app/node_modules/playwright/node_modules/playwright-core/browsers.json'
```

ប្រសិនបើអ្នកប្រើអ្នកផ្ដល់សេវាទាំងនោះ សូម pull ស្លាក `-web` នៃឆានែលដែលអ្នកកំពុងប្រើ — មិនមានអ្វីផ្សេងទៀតផ្លាស់ប្ដូរទេ។ សម្រាប់ការដំឡើងតាម npm/CLI (គ្មាន Docker image) សមាសភាគដែលខ្វះស្មើគ្នាគឺ browser binary៖ ដំណើរការ `npx playwright install chromium` នៅលើម៉ាស៊ីនមេ។

#### ការប្រើឆានែលមុនចេញផ្សាយ

ឆានែល `next` ត្រូវបាន build ឡើងវិញរាល់ពេល push ទៅ branch `release/v*` លំនាំដើមបច្ចុប្បន្ន ហើយត្រូវបានបោះពុម្ពផ្សាយសម្រាប់ទាំង AMD64 និង ARM64។ maintenance branch ចាស់ៗមិនអាចសរសេរជាន់លើវាបានទេ។ ឆានែលនេះផ្ដល់ image ដែលអាច pull បាន សម្រាប់ការកែតម្រូវដែលបាន merge ចូលទៅក្នុង release branch សកម្ម មុនពេលស្លាកស្ថិរភាពបន្ទាប់ត្រូវបានបង្កើត។

```bash
docker pull diegosouzapw/omniroute:next
docker pull diegosouzapw/omniroute:next-web
```

សម្រាប់ Docker Compose សូមកំណត់ជំនួសស្លាក image ដែលបានប្រើដោយ profile ដែលបានជ្រើសរើស បន្ទាប់មក pull និងបង្កើត service ឡើងវិញ៖

```yaml
services:
  omniroute:
    image: diegosouzapw/omniroute:next
```

```bash
docker compose pull
docker compose up -d
```

#### សុវត្ថិភាព និងការត្រឡប់ក្រោយ

`next` គឺជាឆានែលមុនចេញផ្សាយដែលអណ្ដែត។ វាអាចផ្លាស់ប្ដូរនៅពេល push ណាមួយទៅ release branch សកម្ម ហើយ **មិនត្រូវបានគាំទ្រសម្រាប់ការប្រើប្រាស់ក្នុង production ទេ**។ ចងភ្ជាប់ image digest ខណៈពេលវាយតម្លៃ build ជាក់លាក់មួយ៖

```bash
docker pull diegosouzapw/omniroute:next
docker image inspect diegosouzapw/omniroute:next --format '{{index .RepoDigests 0}}'
```

មុនពេលសាកល្បង សូមបម្រុងទុក OmniRoute data volume ឬ data directory ដែលបាន bind-mount។ ដើម្បីត្រឡប់ក្រោយ សូមស្ដារកំណែស្ថិរភាព ឬ digest ដែលបានប្រើពីមុន ហើយបង្កើត container ឡើងវិញ៖

```bash
docker pull diegosouzapw/omniroute:<stable-version>
docker compose up -d
```

build ពី release branch មិនអាចផ្លាស់ទី `latest` បានឡើយ; មានតែកំណែ semantic ស្ថិរភាពដែលមានសិទ្ធិប៉ុណ្ណោះ អាចលើកកម្ពស់ទ្រនិចស្ថិរភាពបាន។ image `next` រក្សាទុកការត្រួតពិនិត្យ image ចេញផ្សាយ និងច្រកទប់ស្កាត់ភាពងាយរងគ្រោះកម្រិត CRITICAL។

**`latest` មិនមែនជាការធានាថាទាន់សម័យជាមួយ git ទេ។** ការកែតម្រូវដែលបាន merge នៅលើ `main` ឬនៅលើ branch `release/v*` សកម្ម **មិន** មាននៅក្នុង `:latest` ទេ រហូតដល់ image SemVer ស្ថិរភាពត្រូវបានបោះពុម្ពផ្សាយ ហើយ job បោះពុម្ពផ្សាយលើកកម្ពស់ `:latest` (មាន digest ដូចគ្នានឹង SemVer នោះ)។ ប្រសិនបើ `latest` មើលទៅដូចជាមិនផ្លាស់ប្ដូរ ខណៈ GitHub បង្ហាញការកែតម្រូវរួចហើយ សូម pull `:next` ដើម្បីសាកល្បង release branch ឬរង់ចាំស្លាក SemVer។

| អ្វីដែលអ្នកចង់បាន                                                               | ប្រើ                               |
| ------------------------------------------------------------------------------- | ---------------------------------- |
| GitOps / production ដែលត្រូវតែមិនផ្លាស់ប្ដូរដោយខ្លួនឯង                          | ចងភ្ជាប់ `:X.Y.Z` (ឬ image digest) |
| តាមដានកំណែស្ថិរភាពដែលបានបោះពុម្ពផ្សាយ និងទទួលយកការបង្កើតឡើងវិញនៅរាល់ការចេញផ្សាយ | `:latest`                          |
| សាកល្បង commit `release/v*` ដែលមិនទាន់ចេញផ្សាយ                                  | `:next` (មិនមែន production)        |
| សាកល្បង `main`                                                                  | `:main` (មិនមែន production)        |

## ភាពអាចប្រើបាន៖ SQLite លំនាំដើមគាំទ្រតែ replica មួយ

OmniRoute លំនាំដើមលើ Docker / Kubernetes គឺ **ដំណើរការ Node មួយ + កម្មវិធីសរសេរ SQLite មួយ**។ ភាពអាចប្រើបានខ្ពស់ **មិនត្រូវបានគាំទ្រ** លើ topology នេះទេ។

| កំហិត                                                        | ផលវិបាក                                                                                                                                                                                                                                                                                                                                       |
| ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| កម្មវិធីសរសេរតែមួយ                                           | **កុំ** ដំណើរការ replica ច្រើនដោយប្រើឯកសារ SQLite តែមួយ។ វានឹងធ្វើឱ្យ DB ខូច។                                                                                                                                                                                                                                                                 |
| ការបង្កើតឡើងវិញ / ចាប់ផ្ដើមឡើងវិញ / ការបញ្ឈប់ដោយ HEALTHCHECK | **ការដាច់សេវាទាំងស្រុង** ចំពោះ SSE ដែលកំពុងដំណើរការ, session របស់ dashboard និង state ក្នុងអង្គចងចាំ។ Client ដែលបានភ្ជាប់ទាំងអស់នឹងត្រូវផ្ដាច់។ Request ថ្មីក្នុងអំឡុងពេលដែលគ្មាន endpoint នឹងទទួលបាន reverse-proxy **`502 Bad Gateway: Unknown error`** មិនមែន OmniRoute JSON ទេ — client មិនអាចបែងចែកវាពីបញ្ហារបស់ provider បានទេ (#11015)។ |
| Event loop ដូចគ្នានឹង `/healthz`                             | ការងារ catalog ឬ compression tick ដែលមមាញឹកអាចពន្យារពេល probe បាន; បន្ទាប់មក timeout ខ្លីនឹងចាប់ផ្ដើម replica **តែមួយគត់** ឡើងវិញ។                                                                                                                                                                                                            |

**តារាង probe** (សូមមើលផងដែរ [អនុសាសន៍អំពី probe របស់ Kubernetes](../ops/MONITORING_GUIDE.md#kubernetes-probe-recommendations))៖

| Probe                        | គោលដៅ                                                       | កុំប្រើ                                                        |
| ---------------------------- | ----------------------------------------------------------- | -------------------------------------------------------------- |
| Liveness                     | TCP នៅលើ `PORT` (លំនាំដើម `20128`) ឬ HTTP `/healthz` បែបទន់ | `/api/monitoring/health`                                       |
| Readiness                    | HTTP `GET /healthz`                                         | Timeout ខ្លីពេកដែលចាត់ទុក event-loop ដែលមមាញឹកថាបានឈប់ដំណើរការ |
| ការត្រួតពិនិត្យជ្រៅ / មនុស្ស | `/api/monitoring/health`                                    | Liveness របស់ kubelet ដោយស្វ័យប្រវត្តិ                         |

**ការដំឡើងកំណែថ្មី៖** រំពឹងថា session ទាំងអស់នឹងត្រូវផ្ដាច់។ ផ្ទេរ client ចេញសិន ប្រសិនបើអាចធ្វើបាន; មិនមាន rolling update សម្រាប់ SQLite លំនាំដើមទេ។ Compose `restart: unless-stopped` រួមជាមួយ Docker `HEALTHCHECK` ក៏នឹងជំនួសដំណើរការតែមួយគត់ នៅពេល container ស្ថិតក្នុងស្ថានភាព Unhealthy ផងដែរ — មានវិសាលភាពផលប៉ះពាល់ដូចគ្នា។

បំណែកកូដ Kubernetes សម្រាប់ **replica តែមួយ** (តម្រូវឱ្យប្រើ Recreate; កុំបង្កើន `replicas` ដោយប្រើឯកសារ SQLite តែមួយ)៖

```yaml
spec:
  replicas: 1
  strategy:
    type: Recreate
  template:
    spec:
      terminationGracePeriodSeconds: 90
      containers:
        - name: omniroute
          lifecycle:
            preStop:
              exec:
                command: ["/bin/sleep", "15"]
          readinessProbe:
            httpGet:
              path: /healthz
              port: 20128
            periodSeconds: 5
          livenessProbe:
            tcpSocket:
              port: 20128
            periodSeconds: 20
```

ការផ្អាក `preStop` អនុញ្ញាតឱ្យ kube ដក Service endpoint ចេញមុនពេល SIGTERM ដូច្នេះ traffic **ថ្មី** ឈប់ត្រូវបានបញ្ជូនទៅដំណើរការដែលកំពុងបិទ។ SSE `/v1/responses` ដែលកំពុងដំណើរការត្រូវបានបង្ហូររហូតដល់ `SHUTDOWN_TIMEOUT_MS` (លំនាំដើម 30 វិនាទី) តាមរយៈ heavyweight admission leases (#11015)។ Request ថ្មីដែលនៅតែទៅដល់ដំណើរការនឹងទទួលបាន `503` + `Retry-After: 5`។ ចន្លោះពេលដែលគ្មាន endpoint របស់ Recreate រហូតដល់ការជំនួសស្ថិតក្នុងស្ថានភាព Ready នៅតែជាការដាច់សេវាទាំងស្រុង — នោះគឺជាលក្ខណៈរបស់ topology SQLite មិនមែនជាការកំណត់ probe ខុសទេ។

Postgres ខាងក្រៅ / multi-writer HA **មិនមែន** ជាវិធីលំនាំដើមដែលមានឯកសារណែនាំទេ។ ប្រសិនបើអ្នកត្រូវការ HA សូមរក្សា replica តែមួយ ឬដំណើរការ topology ដែលគម្រោងបានសាកល្បង និងចងក្រងជាឯកសារដោយឡែក។ ការងារ Postgres/MySQL មាននៅក្នុង [#8075](https://github.com/diegosouzapw/OmniRoute/issues/8075)។ រហូតដល់មុខងារនោះត្រូវបានចេញផ្សាយ វិធីតែមួយគត់ដែលត្រូវបានគាំទ្រសម្រាប់បង្កើនសមត្ថភាព `/v1/responses` **ធំៗ** គឺដំណើរការឯករាជ្យ N (ផ្នែកបន្ទាប់) មិនមែន `replicas > 1` នៅលើ volume តែមួយទេ។

## ការពង្រីកចេញ៖ ដំណើរការឯករាជ្យ N

ដំណើរការ Node មួយគឺជា **V8 heap មួយ**។ coding-agent `POST /v1/responses` ពីរ (RTK + Caveman) ដែលត្រួតគ្នា និងមានទំហំប្រហែល ~3 MiB / ~750k-token នឹងធ្វើឱ្យ heap នោះបញ្ឈប់នៅប្រហែល ~12 Gi (`FATAL ERROR: Reached heap limit`) ហើយអាចបង្ក OOM ដល់ cgroup ទំហំ 16 Gi។ សូមមើល [#7849](https://github.com/diegosouzapw/OmniRoute/issues/7849)។ ការវាស់វែងនោះគឺជាការព្រមានអំពី **កញ្ចប់ថវិកាអង្គចងចាំ** មិនមែនជាកម្រិតអតិបរមាដាច់ខាតរបស់ផលិតផល ដែលអនុញ្ញាតតែ `/v1/responses` រយៈពេលវែងពីរដំណើរការព្រមគ្នានោះទេ។ ការទទួលយក chat ដែលប្រើធនធានខ្ពស់ត្រូវបានគ្រប់គ្រងដោយកញ្ចប់ថវិកាបៃសម្រាប់ ingest ដែលគណនាដោយស្វ័យប្រវត្តិ (`OMNIROUTE_CHAT_MAX_INFLIGHT_BYTES`, `src/shared/middleware/admissionBudget.ts`) ដោយកំណត់ទំហំផ្អែកលើពិដាន V8/cgroup ដដែលនោះ — ការកំណត់វាឡើងខ្ពស់ជាងមុន (ឬកំណត់កម្រិតចំនួនសំណើចាស់ `OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT`) លើដំណើរការដែលបានកំណត់ទំហំរួច នឹងនាំឱ្យមានការបញ្ឈប់ឡើងវិញ។ chat តូចៗ, `/healthz`, `/v1/models` និង MCP **មិន** ស្ថិតក្រោមកម្រិតនោះទេ។

### ដំណើរការតែមួយ៖ `/v1/responses` រយៈពេលវែងច្រើនជាងពីរ

ដំណើរការដែលមាន **សុខភាពល្អ** (heap ទាបជាង `OMNIROUTE_CHAT_ADMISSION_HEAP_SHED_RATIO` ដែលលំនាំដើមគឺ `0.75`) **អាច** ដំណើរការ `POST /v1/responses` រយៈពេលវែងច្រើនជាងពីរក្នុងពេលដំណាលគ្នា នៅពេលកញ្ចប់ថវិកាបៃកំពុងដំណើរការទូទាំងដំណើរការ (`OMNIROUTE_CHAT_MAX_INFLIGHT_BYTES` / #10110) នៅមានចន្លោះទំនេរ។ body ដែលមានទំហំស្មើ ឬធំជាង `OMNIROUTE_CHAT_LARGE_BODY_BYTES` (លំនាំដើម 256 KiB) ប្រើ lease ដែលប្រើធនធានខ្ពស់ដូចគ្នានឹងសំណើដែលមានរចនាសម្ព័ន្ធស្មុគស្មាញ ហើយប្រើផ្លូវបន្ធូរ `tryAcquireHealthyHeadroom` ដូចគ្នាពី [#10437](https://github.com/diegosouzapw/OmniRoute/pull/10437) (`OMNIROUTE_CHAT_ADMISSION_HEALTHY_HEADROOM`)។ client SSE រយៈពេលវែងជាច្រើនដប់ដែលដំណើរការព្រមគ្នា (ប្រតិបត្តិករជាញឹកញាប់ត្រូវការ 40–50) គឺជាបញ្ហា **កញ្ចប់ថវិកាអង្គចងចាំ** — ត្រូវកំណត់ទំហំ heap + slot ចម្បង/headroom + `OMNIROUTE_CHAT_MAX_INFLIGHT_BYTES` — មិនមែនជាកម្រិតផលិតផលដាច់ខាត “អតិបរមា 2” ទេ។ heap ដែលស្ថិតក្រោមសម្ពាធនៅតែកាត់បន្ថយបន្ទុកដោយប្រើ `503` ដែលអាចព្យាយាមឡើងវិញបាន ដើម្បីកុំឱ្យបញ្ហា #7849 ត្រឡប់មកវិញ។

ដើម្បី **បង្កើនចំនួន heap** (V8 old-space ឯករាជ្យ) **នៅពេលនេះ**៖

| ត្រូវធ្វើ                                                                                                                                                                      | កុំធ្វើ                                                      |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------ |
| ដំណើរការ **container/pod ចំនួន N** ដោយនីមួយៗមាន `DATA_DIR` / volume **ផ្ទាល់ខ្លួន**                                                                                            | កំណត់ `replicas > 1` ឱ្យប្រើឯកសារ SQLite តែមួយ               |
| កំណត់ទំហំ heavy in-flight + healthy-headroom ផ្អែកលើ heap / កញ្ចប់ថវិកាបៃកំពុងដំណើរការ; 1–2 គឺជាលំនាំដើមបែបប្រុងប្រយ័ត្នសម្រាប់ #7849 មិនមែនជាកម្រិតអតិបរមាដាច់ខាតរបស់ផលិតផលទេ | ផ្ដល់ RAM 8× ឱ្យដំណើរការតែមួយ និងកម្រិតចំនួនដែលគ្មានព្រំដែន  |
| ជាជម្រើស៖ `QUOTA_STORE_DRIVER=redis` + `QUOTA_STORE_REDIS_URL` សម្រាប់ **បញ្ជរបរិមាណកំណត់រួម**                                                                                 | ចាត់ទុក Redis ជា SQLite រួម — វាមិនមែនដូច្នោះទេ              |
| ចម្លង secret របស់ provider ទៅក្នុង instance នីមួយៗ (ឬទទួលយក dashboard ដែលបែងចែកដាច់ពីគ្នា)                                                                                     | រំពឹងថាមាន dashboard តែមួយ / call-log តែមួយនៅទូទាំង instance |
| ដាក់ load balancer ណាមួយនៅខាងមុខ; sticky តាម API key ឬ session គឺគ្រប់គ្រាន់                                                                                                   | តម្រូវឱ្យមាន middleware ដែលគិតពីទំហំ និងជាក់លាក់ចំពោះ vendor |

ផ្នែក hardware៖ ចំនួន `/v1/responses` រយៈពេលវែងដែលដំណើរការព្រមគ្នាក្នុងមួយ instance គឺជាបញ្ហា **កញ្ចប់ថវិកាអង្គចងចាំ** (heap + inflight-byte / #10110)។ `DATA_DIR` ឯករាជ្យចំនួន `N` នៅតែបង្កើនចំនួន heap៖ RAM របស់ host ត្រូវតែគ្រប់គ្រាន់សម្រាប់ `N × cgroup` មិនមែន “pod 16 Gi មួយដែលមាន N=8” ទេ។ កុំកំណត់ `replicas > 1` លើឯកសារ SQLite តែមួយជាដាច់ខាត។

គំរូ Compose (heap ពីរ, volume ពីរ — មិនមែន `deploy.replicas: 2`)៖

```yaml
services:
  omniroute-a:
    image: diegosouzapw/omniroute:3.8.49
    environment:
      DATA_DIR: /app/data
      OMNIROUTE_MEMORY_MB: "12288"
      QUOTA_STORE_DRIVER: redis
      QUOTA_STORE_REDIS_URL: redis://redis:6379
    volumes: [omniroute-a-data:/app/data]
    ports: ["20128:20128"]
  omniroute-b:
    image: diegosouzapw/omniroute:3.8.49
    environment:
      DATA_DIR: /app/data
      OMNIROUTE_MEMORY_MB: "12288"
      QUOTA_STORE_DRIVER: redis
      QUOTA_STORE_REDIS_URL: redis://redis:6379
    volumes: [omniroute-b-data:/app/data]
    ports: ["20138:20128"]
volumes:
  omniroute-a-data:
  omniroute-b-data:
```

ដង់ស៊ីតេក្នុងដំណើរការ (ការបង្ហាប់នៅក្រៅ HTTP isolate) មាននៅ [#11023](https://github.com/diegosouzapw/OmniRoute/issues/11023)។ cluster ឡូជីខលតែមួយលើស្ថានភាពអចិន្ត្រៃយ៍រួម មាននៅ [#8075](https://github.com/diegosouzapw/OmniRoute/issues/8075)។

## កំណត់ចំណាំសំខាន់ៗ

- **របៀប SQLite WAL:** គួរអនុញ្ញាតឱ្យ `docker stop` ដំណើរការរហូតដល់ចប់ ដើម្បីឱ្យ OmniRoute អាចធ្វើ checkpoint នៃការផ្លាស់ប្តូរចុងក្រោយត្រឡប់ទៅក្នុង `storage.sqlite`។ ឯកសារ Compose ដែលភ្ជាប់មកជាមួយបានកំណត់រយៈពេលអនុគ្រោះសម្រាប់ការបញ្ឈប់ចំនួន 40 វិនាទីរួចហើយ។ ប្រសិនបើអ្នកដំណើរការ image ដោយផ្ទាល់ សូមរក្សាទុក `--stop-timeout 40`។
- **`DISABLE_SQLITE_AUTO_BACKUP`:** កំណត់ជា `true` ប្រសិនបើការបម្រុងទុកតាមទម្លាប់/មុនពេលសរសេរត្រូវបានគ្រប់គ្រងពីខាងក្រៅ។ ការធ្វើ migration លើមូលដ្ឋានទិន្នន័យដែលមានស្រាប់ នៅតែទាមទារ snapshot សុវត្ថិភាពដ៏រឹងមាំផ្ទាល់ខ្លួន និងវិធានការការពារសម្រាប់ការធ្វើ migration ទ្រង់ទ្រាយធំ។
- **ការរក្សាទុកទិន្នន័យជាអចិន្ត្រៃយ៍:** ត្រូវ mount volume ទៅកាន់ `/app/data` ជានិច្ច ដើម្បីរក្សាមូលដ្ឋានទិន្នន័យ keys និងការកំណត់រចនាសម្ព័ន្ធរបស់អ្នក ឆ្លងកាត់ការចាប់ផ្ដើម container ឡើងវិញ។
- **ការកំណត់ Port:** កំណត់ជំនួស environment variable `PORT` ដើម្បីផ្លាស់ប្ដូរ port លំនាំដើម `20128`។

## សូមមើលផងដែរ

- [មគ្គុទ្ទេសក៍ដាក់ឱ្យដំណើរការលើ VM](../ops/VM_DEPLOYMENT_GUIDE.md) — ការរៀបចំ VM + nginx + Cloudflare
- [មគ្គុទ្ទេសក៍ដាក់ឱ្យដំណើរការលើ Fly.io](../ops/FLY_IO_DEPLOYMENT_GUIDE.md) — ដាក់ឱ្យដំណើរការលើ Fly.io
- [ការកំណត់រចនាសម្ព័ន្ធ Environment](../reference/ENVIRONMENT.md) — ឯកសារយោង `.env` ពេញលេញ