Skip to content

EMBEDDED-SERVICES.md

Latest commit

 

History

History
916 lines (678 loc) · 78.1 KB

EMBEDDED-SERVICES.md

File metadata and controls

916 lines (678 loc) · 78.1 KB
Raw

Embedded Services (සිංහල)

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

අනුවාදය: v3.8.44 අවසන් වරට යාවත්කාලීන කළේ: 2026-09-09 ඉලක්ක පාඨකයින්: කාවැද්දූ සේවා (9Router, CLIProxyAPI, Mux, Bifrost, open-wa) එක් කරන, නඩත්තු කරන, හෝ දෝෂහරණය කරන ඉංජිනේරුවන්.

කාවැද්දූ සේවා යනු OmniRoute විසින් ස්ථාපනය කරන, අධීක්ෂණය කරන, සහ පළමු පන්තියේ මාර්ගගත කිරීමේ ඉලක්ක ලෙස නිරාවරණය කරන, දේශීයව ස්ථාපිත ක්රියාවලි sidecar මෙවලම් වේ. බාහිර සැපයුම්කරුවන් මෙන් නොව (ඒවා වෙත අන්තර්ජාලය හරහා API යතුරු භාවිතයෙන් ළඟා වේ), කාවැද්දූ සේවා OmniRoute තිබෙන යන්ත්රයේම ක්රියාත්මක වන අතර loopback හරහා සන්නිවේදනය කරයි.

පටුන

  1. දළ විශ්ලේෂණය
  2. ගෘහනිර්මාණය — ස්තර 4ක්
  3. ජීවන චක්ර තත්ත්ව යන්ත්රය
  4. API යොමුව
  5. ආරක්ෂාව
  6. නව කාවැද්දූ සේවාවක් එක් කිරීම
  7. දෝෂ නිරාකරණය
  8. නිතර අසන ප්රශ්න

1. දළ විශ්ලේෂණය

කාවැද්දූ සේවා අවශ්ය වන්නේ ඇයි?

සේවා හයක් කාවැද්දා ඇත:

සේවාව npm පැකේජය පෙරනිමි පෝට් එක අරමුණ
9Router 9router 20130 OmniRoute හට උප-සපයන්නෙකු ලෙස භාවිත කළ හැකි AI රවුටරයකි. ආකෘති 9router/{sub}/{model} ලෙස නිරාවරණය කෙරේ
CLIProxyAPI GitHub නිකුතු ද්විමය (cliproxy) 8317 Anthropic CLI සත්යාපන ප්රවාහ සඳහා දේශීය ප්රොක්සි ඇඩැප්ටරයකි. OAuth ටෝකන කල් ඉකුත් වූ විට විකල්ප රවුටින් සපයයි
Mux mux (හෙඩ්ලස් mux server) 8322 දේශීය නියෝජිත-සම්බන්ධීකරණ ඩීමනයකි (coder/mux). ජීවන චක්රය පමණක් කළමනාකරණය කෙරේ — රවුටින් ඉලක්කයක් නොවේ (LLM ප්රොක්සි කිරීමක් නොමැත).
Bifrost @maximhq/bifrost 8080 Go AI-ගේට්වේ රිලේ පසුබිම් සේවාවකි. ක්රියාත්මක වන විට, රිලේ මාර්ගය (/v1/relay/) මඟින් ස්වයංක්රීයව තෝරාගනු ලැබේ
Dario @askalf/dario 3456 Claude-දායකත්ව ප්රොක්සියකි — Claude-Code ආකාරයේ ගමනාගමනය සඳහා CLIProxyAPI වෙත විකල්පයක්/අසමත් වීමකදී භාවිත වන සේවාවක්; ඇතුළු කළ යතුර එහි /admin/* OAuth පාලන තලයට ප්රවේශය සීමා කරන DARIO_ADMIN_TOKEN බවට පත් වේ
open-wa @open-wa/wa-automate 8323 WhatsApp Web ස්වයංක්රීයකරණය (Puppeteer හරහා හෙඩ්ලස් Chromium). ජීවන චක්රය පමණක් කළමනාකරණය කෙරේ — රවුටින් ඉලක්කයක් නොවේ.

සේවා හයම එකම අධීක්ෂණ ආකෘතිය අනුගමනය කරයි:

  • OmniRoute ඒවා DATA_DIR/services/{name}/ යටතේ ස්ථාපනය කරයි (OmniRoute හිම package.json වෙතින් හුදකලා කර ඇත)
  • OmniRoute ඒවා උප-ක්රියාවලි ලෙස ආරම්භ කර අධීක්ෂණය කරයි
  • OmniRoute තාවකාලික API යතුරක් උප-ක්රියාවලියේ පරිසරයට ඇතුළු කර, සේවාව අක්රිය නොකර එය මාරු කරයි (අදාළ වන අවස්ථාවලදී)
  • සියලු කළමනාකරණ මාර්ග (/api/services/*) LOCAL_ONLY වේ — ලූප්බැක් වෙතින් පමණක් ප්රවේශ විය හැකිය (දැඩි නීතිය #17)

ප්රධාන තීරණ (සැලසුම් සැලැස්මෙන්)

තීරණය අගය
9Router ස්වදේශීය UI වෙත ඩෑෂ්බෝඩ් ප්රවේශය /dashboard/providers/services/9router/embed/* හි ප්රතිලෝම ප්රොක්සිය
ස්ථාපන යාන්ත්රණය execFile හරහා npm install {package} (ෂෙල් අන්තර්නිවේෂණයක් නොමැත)
පරිභෝජන ආකාරය රවුටින් එන්ජිම තුළ 9router/{sub}/{model} ලෙස ලියාපදිංචි කළ සපයන්නා
API යතුරු කළමනාකරණය OmniRoute විසින් ජනනය කරයි, නිශ්චල අවස්ථාවේදී සංකේතනය කරයි (AES-256-GCM), සහ env හරහා ඇතුළු කරයි
ඩෑෂ්බෝඩ් පිහිටීම /dashboard/providers/services (ටැබ් තුනක්)
ස්වයංක්රීය ආරම්භය එක් එක් සේවාව සඳහා ටොගලයක්, පෙරනිමියෙන් අක්රියයි

2. නිර්මාණ ශිල්පය — ස්තර 4ක්

┌────────────────────────────────────────────────────────────────────┐
│  ස්තරය 1 — UI                                                      │
│  /dashboard/providers/services  (ටැබ්: CLIProxyAPI | 9Router | Mux)│
│  සජීවී ලොග් (SSE), ආරම්භය/නැවැත්වීම/යළි ඇරඹීම/යාවත්කාලීන කිරීම, සැකසුම්, ස්ථාපනය │
│                                                                    │
│  src/app/(dashboard)/dashboard/providers/services/                 │
│    ├── page.tsx               කවචය + ?tab= අනුව ටැබ් මාර්ගගත කිරීම │
│    ├── tabs/                  CliproxyServiceTab, NinerouterServiceTab,│
│    │                          MuxServiceTab                        │
│    └── components/            ServiceStatusCard, ServiceLifecycleButtons,│
│                               ServiceLogsPanel, ApiKeyCard, ...    │
└──────────────────────┬─────────────────────────────────────────────┘
                       │ HTTP (Next.js fetch)
┌──────────────────────▼─────────────────────────────────────────────┐
│  ස්තරය 2 — API (LOCAL_ONLY — ලූප්බැක් පමණි)                       │
│                                                                    │
│  /api/services/9router/{install|start|stop|restart|update|         │
│                          rotate-key|status|auto-start|logs}        │
│  /api/services/cliproxy/{install|start|stop|restart|update|        │
│                           status|auto-start|logs}                  │
│  /api/services/mux/{install|start|stop|restart|update|             │
│                      status|auto-start|logs}                       │
│  /dashboard/providers/services/9router/embed/[...path]             │
│    (ප්රතිලෝම HTTP + WebSocket ප්රොක්සිය → 9Router upstream)       │
│                                                                    │
│  ද්වාරය: LOCAL_ONLY_API_PREFIXES තුළ "/api/services/" සහ           │
│        "/dashboard/providers/services/*/embed/" ඇතුළත් වේ          │
└──────────────────────┬─────────────────────────────────────────────┘
                       │ ක්රියාවලිය තුළ ඇමතුම්
┌──────────────────────▼─────────────────────────────────────────────┐
│  ස්තරය 3 — ServiceSupervisor (src/lib/services/)                   │
│                                                                    │
│  ServiceSupervisor.ts   සාමාන්ය අධීක්ෂකය (child_process.spawn)    │
│    ├── ස්ථාපනය:    execFile('npm', ['install', pkg, '--prefix'])   │
│    ├── ආරම්භය:     spawn(node, [entrypoint], {env, cwd})           │
│    ├── api_key:    crypto.randomBytes(32) → env NINEROUTER_API_KEY  │
│    ├── පෝට් එක:    9Router සඳහා 20130 (වින්යාස කළ හැකිය)          │
│    ├── ලොග්:       stdio වළලු බෆරය 5 MB → SSE සිදුවීම්             │
│    ├── සෞඛ්යය:    සෑම තත්. 2–5කටම HTTP GET /health, අවශ්ය විට ප්රතිසාධනය │
│    └── ජීවන චක්රය: SIGTERM තත්. 15 → SIGKILL                     │
│                                                                    │
│  registry.ts        getSupervisor(name) / registerSupervisor()     │
│  bootstrap.ts       ක්රියාවලිය ඇරඹෙන විට සියලු SERVICES[] ආරම්භ කරයි │
│  apiKey.ts          getOrCreateApiKey(), generateServiceApiKey()   │
│  modelSync.ts       ආවර්තිත GET /v1/models → service_models වගුව  │
│  ringBuffer.ts      චක්රීය ලොග් බෆරය (සේවාවකට 5 MB)              │
│  healthCheck.ts     ආවර්තිත HTTP සෞඛ්ය පරීක්ෂණය                  │
│  installers/        ninerouter.ts, cliproxy.ts, mux.ts, openwa.ts  │
│                      (ස්ථාපක ඇඩැප්ටර)                             │
└──────────────────────┬─────────────────────────────────────────────┘
                       │ OpenAI-අනුකූල HTTP (ලූප්බැක්)
┌──────────────────────▼─────────────────────────────────────────────┐
│  ස්තරය 4 — සපයන්නා / මාර්ගගත කිරීම                                │
│                                                                    │
│  open-sse/executors/ninerouter.ts                                  │
│    එක් එක් ඉල්ලීම සඳහා පෝට් එක සහ API යතුර නැවත සොයයි (හැඹිලිගත කිරීමක් නැත). │
│    ප්රොක්සි කිරීමට පෙර ආකෘති id වෙතින් "9router/" උපසර්ගය ඉවත් කරයි. │
│    අධීක්ෂකය "running" තත්ත්වයේ නොමැති නම් 503 service_not_running ලබා දෙයි. │
│                                                                    │
│  src/shared/constants/providers.ts                                 │
│    "9router" සඳහා ඇතුළත් කිරීම: isEmbeddedService: true            │
│                                                                    │
│  open-sse/config/providerRegistry.ts                               │
│    ආකෘති "9router/{sub}/{model}" ලෙස ගබඩා කෙරේ (උපසර්ග සහිතව).     │
│    modelSync.ts මඟින් සෑම මිනිත්තු 5කටම සමමුහුර්ත කෙරේ.           │
│                                                                    │
│  Mux සඳහා කළමනාකරණය කරන්නේ ජීවන චක්රය පමණි (ස්තර 1-3) — එය නියෝජිත-│
│  සංවිධාන ඩීමනයක් මිස LLM ප්රොක්සියක් නොවන බැවින්, එයට ස්තර 4     │
│  executor/provider ඇතුළත් කිරීමක් නොමැති අතර කිසිවිටෙක මාර්ගගත කිරීමේ ඉලක්කයක් නොවේ. │
└────────────────────────────────────────────────────────────────────┘

ප්රධාන මූලාශ්ර ගොනු

ගොනුව භූමිකාව
src/lib/services/ServiceSupervisor.ts මූලික පන්තිය: ජීවන චක්රය, අගුල, සෞඛ්යය, වළලු බෆරය
src/lib/services/bootstrap.ts ක්රියාවලි-මට්ටමේ ලියාපදිංචිය සහ ස්වයංක්රීය ආරම්භය
src/lib/services/registry.ts සිංගල්ටන් සිතියම tool → supervisor
src/lib/services/apiKey.ts යතුරු ජනනය, විවේකී තත්ත්වයේ AES-256-GCM සංකේතනය
src/lib/services/modelSync.ts කාලාන්තරික ආකෘති සමමුහුර්තකරණය (මිනිත්තු 5) + ඉල්ලුම මත
src/lib/services/ringBuffer.ts SSE දායකත්වය සහිත 5 MB වෘත්තාකාර ලොග් බෆරය
src/lib/services/healthCheck.ts HTTP සෞඛ්ය පිරික්සුම (වින්යාස කළ හැකි කාල අන්තරය)
src/lib/services/installers/ninerouter.ts 9Router සඳහා npm ස්ථාපනය/යාවත්කාලීන කිරීම/අස්ථාපනය
src/lib/services/installers/cliproxy.ts CLIProxyAPI සඳහා npm ස්ථාපනය/යාවත්කාලීන කිරීම/අස්ථාපනය
src/lib/services/installers/mux.ts Mux සඳහා npm ස්ථාපනය/යාවත්කාලීන කිරීම/අස්ථාපනය
src/lib/services/installers/openwa.ts open-wa සඳහා npm ස්ථාපනය/යාවත්කාලීන කිරීම/අස්ථාපනය
src/app/api/services/9router/_lib.ts getOrInitSupervisor() සහායකය
src/app/api/services/[name]/logs/route.ts හවුල් SSE ලොග් අන්ත ලක්ෂ්යය
open-sse/executors/ninerouter.ts සැපයුම්කරු ක්රියාත්මකකාරකය (ස්තරය 4)

3. ජීවන චක්ර තත්ත්ව යන්ත්රය

                    install()
  ┌─────────────┐ ──────────► ┌─────────────┐
  │ not_installed│             │   stopped   │◄──────────────────┐
  └─────────────┘             └──────┬──────┘                   │
                                     │ start()                   │
                                     ▼                           │ stop()
                               ┌──────────┐                      │
                               │ starting │                      │
                               └────┬─────┘                     │
                  සෞඛ්ය පිරික්සුම සාර්ථකයි │         බිඳවැටීම / SIGTERM    │
                               ┌────▼─────┐  (තත්පර 5ක් තුළ පිටවීම)   │
                               │ running  │──── බිඳවැටීම ──────────►┤
                               └────┬─────┘                   ┌─▼────┐
                             stop() │                          │error │
                                    ▼                          └──────┘
                               ┌──────────┐
                               │ stopping │
                               └──────────┘

තත්ත්වයන් version_manager DB වගුවේ (status තීරුව) ගබඩා කර ඇති අතර, ServiceSupervisor හි මතකය-තුළ තත්ත්වයෙහි ද පිළිබිඹු කෙරේ. ක්රියාත්මක වන ක්රියාවලියක් සඳහා මතකය-තුළ තත්ත්වය බලධාරී මූලාශ්රය වේ; ආරම්භයේදී DB තත්ත්වය ස්ථිර විකල්ප මූලාශ්රය වේ.

තත්ත්ව සංක්රාන්ති

ආරම්භක තත්ත්වය සිදුවීම අවසාන තත්ත්වය
not_installed install() සාර්ථක වේ stopped
stopped start() කැඳවනු ලැබේ starting
starting සෞඛ්ය පිරික්සුම 200 ලබා දෙයි running
starting සෞඛ්ය සම්පන්න වීමට පෙර ක්රියාවලිය පිටවේ error
running stop() කැඳවනු ලැබේ stopping → stopped
running ක්රියාවලිය අනපේක්ෂිතව පිටවේ (< තත්පර 5) error (වේගවත් බිඳවැටීම)
running ක්රියාවලිය අනපේක්ෂිතව පිටවේ (> තත්පර 5) error
error start() කැඳවනු ලැබේ starting
ඕනෑම එකක් stopping අතරතුර stop() ක්රියාවක් නැත

මෙහෙයුම් අගුල

ServiceSupervisor, async මෙහෙයුම් අගුලක් (withLock()) හරහා ජීවන චක්ර මෙහෙයුම් අනුක්රමික කරයි. එකම supervisor එක මත සමගාමී start() ඇමතුම් සිදු කළ විට හරියටම එක් ක්රියාවලි නිර්මාණයක් පමණක් සිදු වේ; දෙවන කැඳවුම්කරු රැඳී සිට පවතින තත්ත්වය ආපසු ලබා දෙයි. උදාහරණයක් ලෙස, ස්වයංක්රීය ආරම්භය සහ UI බොත්තමක් එකවර ක්රියාත්මක වන විට ඇති විය හැකි ධාවන තත්ත්ව ගැටුම් මෙය වළක්වයි.

4. API යොමුව

/api/services/ යටතේ ඇති සියලු මාර්ග LOCAL_ONLY වේ (loopback සඳහා පමණි, දැඩි රීතිය #17). සත්යාපන ටෝකනය නොසලකා, loopback නොවන ඉල්ලීම්වලට 403 LOCAL_ONLY ලැබේ.

4.1 9Router අන්ත ලක්ෂ්ය (මාර්ග 11)

POST /api/services/9router/install

npm වෙතින් 9Router ස්ථාපනය කරයි. එයටම අයත් package.json සහ node_modules/ සමඟ DATA_DIR/services/9router/ නිර්මාණය කරයි. OmniRoute හිම පරායත්තතා සමඟ ගැටීමක් ඇති නොකරයි.

ඉල්ලීම් බඳ (සියල්ල විකල්පීයයි):

{ "version": "latest" }
ක්ෂේත්රය වර්ගය පෙරනිමිය විස්තරය
version string "latest" ස්ථාපනය කළ යුතු npm අනුවාද ටැගය හෝ semver

ප්රතිචාර:

තත්ත්වය විස්තරය
200 { ok: true, installedVersion: "x.y.z", path: "..." }
400 වලංගු නොවන ඉල්ලීම් බඳ (Zod වලංගුකරණ අසමත් වීම)
409 දැනටමත් ස්ථාපනය වෙමින් පවතී (අගුල රඳවා ඇත)
500 npm ස්ථාපනය අසාර්ථකයි — හිතකාමී දෝෂ පණිවිඩය සඳහා message බලන්න

සටහන්: execFile('npm', [...]) භාවිත කරයි — shell එකක් හෝ අන්තර්නිවේෂණයක් නැත (දැඩි රීතිය #13). EACCES දෝෂ හිතකාමී පණිවිඩ ලෙස ඉදිරිපත් කෙරේ.

POST /api/services/9router/start

9Router ආරම්භ කරයි. දැනටමත් ලියාපදිංචි කර නොමැති නම් supervisor එකක් ලියාපදිංචි කර, ඉන්පසු supervisor.start() අමතයි. දැනටමත් ක්රියාත්මක වන විට මෙය idempotent වේ.

ඉල්ලීම් බඳ: නැත

ප්රතිචාර:

තත්ත්වය විස්තරය
200 ServiceStatus වස්තුව (පහත schema එක බලන්න)
409 9Router ස්ථාපනය කර නැත (status: "not_installed")
503 ආරම්භ කිරීම අසාර්ථකයි (ක්රියාවලි දෝෂය — lastError බලන්න)

ServiceStatus schema එක:

{
  "tool": "9router",
  "state": "running",
  "pid": 12345,
  "port": 20130,
  "health": "healthy",
  "startedAt": "2026-05-25T10:00:00.000Z",
  "lastError": null
}

POST /api/services/9router/stop

9Router ක්රමානුකූලව නවත්වයි. SIGTERM යවා තත්පර 15ක් රැඳී සිට, තවමත් සජීවී නම් SIGKILL යවයි. දැනටමත් නවතා ඇති විට මෙය idempotent වේ.

ඉල්ලීම් බඳ: නැත

ප්රතිචාර:

තත්ත්වය විස්තරය
200 ServiceStatus (state: "stopped")
503 අනපේක්ෂිත ලෙස නැවැත්වීම අසාර්ථක විය

POST /api/services/9router/restart

මෙහෙයුම් අගුල යටතේ stop() කිරීමෙන් පසු start() කිරීමට සමාන වේ.

ඉල්ලීම් බඳ: නැත

ප්රතිචාර: start හා සමානයි (අවසාන ServiceStatus ආපසු ලබා දෙයි).

POST /api/services/9router/update

9Router නව npm අනුවාදයකට යාවත්කාලීන කරයි. සේවාව ක්රියාත්මක වෙමින් පවතී නම්, එය පළමුව නවත්වනු ලැබේ, npm ස්ථාපනය ක්රියාත්මක කරයි (නව අනුවාදය එම ස්ථානයේම ස්ථාපනය කරමින්), ඉන්පසු සේවාව නැවත ආරම්භ කරයි.

ඉල්ලීම් බඳ (සියල්ල විකල්පීයයි):

{ "version": "latest" }

ප්රතිචාර:

තත්ත්වය විස්තරය
200 { ok: true, previousVersion: "...", installedVersion: "..." }
400 වලංගු නොවන බඳ
500 npm යාවත්කාලීන කිරීම අසාර්ථකයි

POST /api/services/9router/rotate-key

9Router සඳහා නව API යතුරක් ජනනය කර, එය නිශ්චල තත්ත්වයේදී සංකේතනය කර, සේවාව ක්රියාත්මක නම් නැවත ආරම්භ කරයි; එවිට එය තම පරිසරයෙන් නව යතුර ලබා ගනී. පැරණි යතුර වහාම අවලංගු කෙරේ.

ඉල්ලීම් බඳ: නැත

ප්රතිචාර:

තත්ත්වය විස්තරය
200 { keyRotated: true, restarted: boolean }
500 යතුර මාරු කිරීම අසාර්ථකයි

ආරක්ෂාව: නව යතුර කිසිවිටෙක ප්රතිචාරයේ ආපසු ලබා නොදේ (අක්තපත්ර කාන්දුවක් නැත). එය version_manager වගුවේ සංකේතනය කර (AES-256-GCM) ගබඩා කරයි.

GET /api/services/9router/status

අනුවාද පාරදත්ත සහ API යතුරු පෙරදසුන ඇතුළුව ඒකාබද්ධ සජීවී + DB තත්ත්වය ආපසු ලබා දෙයි.

ප්රතිචාර:

තත්ත්වය විස්තරය
200 පහත schema එක බලන්න
500 තත්ත්වය කියවීම අසාර්ථකයි

ප්රතිචාර schema එක:

{
  "tool": "9router",
  "state": "running",
  "pid": 12345,
  "port": 20130,
  "health": "healthy",
  "startedAt": "2026-05-25T10:00:00.000Z",
  "lastError": null,
  "installedVersion": "1.2.3",
  "latestVersion": "1.2.4",
  "updateAvailable": true,
  "apiKeyMasked": "nr_****abcd",
  "autoStart": false,
  "providerExpose": false
}

POST /api/services/9router/auto-start

ස්වයංක්රීය ආරම්භක සලකුණ මාරු කරයි. enabled: true වූ විට, ඊළඟ වතාවේ OmniRoute ආරම්භ වන විට (සේවාව ස්ථාපනය කර ඇත්නම්) සේවාව ස්වයංක්රීයව ආරම්භ වේ.

ඉල්ලීම් බඳ:

{ "enabled": true }

ප්රතිචාර:

තත්ත්වය විස්තරය
200 { autoStart: true }
400 වලංගු නොවන බඳ

GET /api/services/9router/logs

9Router හි stdout/stderr වළලු බෆරයෙන් සජීවී ලොග්වල SSE ප්රවාහය.

විමසුම් පරාමිති:

පරාමිතිය වර්ගය පෙරනිමිය විස්තරය
tail integer 200 පළමුව යැවිය යුතු ඓතිහාසික පේළි ගණන (උපරිම 1000)
filter string නැත අක්ෂර ප්රමාණයට සංවේදී නොවන උපතන්තු පෙරහන (regex නැත — ReDoS-ආරක්ෂිතයි)

SSE සිදුවීම්:

සිදුවීම දත්ත විස්තරය
snapshot LogLine[] ආරම්භක ඓතිහාසික tail එක
log LogLine සජීවී ලොග් පේළිය
heartbeat {} සෑම තත්පර 15කටම සම්බන්ධතාව සජීවීව තබයි

LogLine schema එක:

{
  "ts": 1716633600000,
  "stream": "stdout",
  "line": "[9router] Listening on :20130"
}

ප්රතිචාර:

තත්ත්වය විස්තරය
200 text/event-stream
400 filter පරාමිතිය දිග වැඩියි (> අක්ෂර 200)
404 සේවාව හමු නොවීය (අධීක්ෂකයේ ලියාපදිංචි කර නැත)

4.2 CLIProxyAPI අන්ත ලක්ෂ්ය (මාර්ග 10)

CLIProxyAPI සතුව rotate-key හැර 9Router හි ඇති අන්ත ලක්ෂ්ය ආකෘතියම ඇති අතර, ඊට අමතරව accounts, provider-expose සහ auto-restart-adopted ඇත. දැන් එයට ආරම්භ කරන අවස්ථාවේදී ඇතුළු කරන ලද, වෙන් කළ දත්ත-තල API යතුරක් ලැබේ (bootstrap.ts තුළ needsApiKey: true, ආකෘති සමමුහුර්ත කිරීම සඳහා භාවිත වේ); status හි ඇතුළත් වන්නේ අඩු ක්ෂේත්ර ගණනකි.

ක්රමය මාර්ගය විස්තරය
POST /api/services/cliproxy/install npm වෙතින් CLIProxyAPI ස්ථාපනය කරන්න
POST /api/services/cliproxy/start CLIProxyAPI ආරම්භ කරන්න
POST /api/services/cliproxy/stop CLIProxyAPI නවත්වන්න
POST /api/services/cliproxy/restart CLIProxyAPI නැවත ආරම්භ කරන්න
POST /api/services/cliproxy/update නව අනුවාදයකට යාවත්කාලීන කරන්න
GET /api/services/cliproxy/status සජීවී + DB තත්ත්වය (apiKeyMasked නැත)
POST /api/services/cliproxy/auto-start ස්වයංක්රීය ආරම්භය මාරු කරන්න

හවුල් GET /api/services/{name}/logs අන්ත ලක්ෂ්යය (§4.1 බලන්න) [name] ගතික ඛණ්ඩය භාවිත කරමින් සේවා හතරටම ක්රියා කරයි.

4.3 Mux අන්ත ලක්ෂ්ය (මාර්ග 8)

Mux සතුව CLIProxyAPI හි ඇති අන්ත ලක්ෂ්ය ආකෘතියම ඇත — API මතුපිටෙහි rotate-key මාර්ගයක් නොමැත (bearer ටෝකනය 9Router සඳහා මෙන්ම getOrCreateApiKey("mux") හරහා උත්පාදනය කර MUX_SERVER_AUTH_TOKEN පරිසර විචල්යය හරහා ඇතුළු කරයි, නමුත් තවමත් ඒ සඳහා වෙන් කළ භ්රමණ අන්ත ලක්ෂ්යයක් නොමැත). Mux සඳහා කළමනාකරණය කරන්නේ ජීවන චක්රය පමණි: 9Router මෙන් නොව, එයට Layer 4 ක්රියාත්මකකාරකයක් නොමැති අතර මාර්ගගත කිරීමේ සපයන්නෙකු ලෙස කිසිවිටෙක ලියාපදිංචි නොකෙරේ.

ක්රමය මාර්ගය විස්තරය
POST /api/services/mux/install npm වෙතින් Mux ස්ථාපනය කරන්න (npm i mux)
POST /api/services/mux/start Mux ආරම්භ කරන්න (mux server)
POST /api/services/mux/stop Mux නවත්වන්න
POST /api/services/mux/restart Mux නැවත ආරම්භ කරන්න
POST /api/services/mux/update නව npm අනුවාදයකට යාවත්කාලීන කරන්න
GET /api/services/mux/status සජීවී + DB තත්ත්වය
POST /api/services/mux/auto-start ස්වයංක්රීය ආරම්භය මාරු කරන්න

4.4 Bifrost අන්ත ලක්ෂ්ය (මාර්ග 8)

Bifrost යනු Go AI-gateway ප්රතිප්රේෂණ පසුඅන්තයකි (@maximhq/bifrost). එය CLIProxyAPI හි ඇති අන්ත ලක්ෂ්ය ආකෘතියම භාවිත කරයි (rotate-key නොමැත — Bifrost තමන්ගේම සපයන්නන්ගේ යතුරු, එහි -app-dir යටතේ ඇති config.json තුළ කළමනාකරණය කරයි).

ක්රමය මාර්ගය විස්තරය
POST /api/services/bifrost/install npm වෙතින් Bifrost ස්ථාපනය කරන්න (@maximhq/bifrost)
POST /api/services/bifrost/start 8080 පෝර්ට් එකේ Bifrost ආරම්භ කරන්න (පෙරනිමිය)
POST /api/services/bifrost/stop Bifrost නවත්වන්න
POST /api/services/bifrost/restart Bifrost නැවත ආරම්භ කරන්න
POST /api/services/bifrost/update නව අනුවාදයකට යාවත්කාලීන කරන්න
GET /api/services/bifrost/status සජීවී + DB තත්ත්වය
POST /api/services/bifrost/auto-start ස්වයංක්රීය ආරම්භය මාරු කරන්න
GET /api/services/bifrost/logs SSE ලොග් අග කොටස (හවුල් [name]/logs ගතික මාර්ගය හරහා)

මාර්ගගත කිරීමේ සම්බන්ධනය: BIFROST_BASE_URL සකසා නොමැති විට සහ අධීක්ෂණය කරන Bifrost අවස්ථාව ක්රියාත්මක වන විට, getBifrostRoutingConfig() (routingBackend.ts තුළ) ප්රතිප්රේෂණ මූලික URL එක ලෙස ස්වයංක්රීයව http://127.0.0.1:{port} භාවිත කරයි. පැහැදිලිව සකසන ලද BIFROST_BASE_URL පරිසර විචල්යයට සැමවිටම ප්රමුඛතාව හිමි වේ.

4.5 Dario අන්ත ලක්ෂ්ය (මාර්ග 12)

අනෙකුත් සේවාවලට සමාන ජීවන චක්ර ආකෘතියක් (install, start, stop, restart, update, status, auto-start, auto-restart-adopted) සහ admin/ යටතේ ටෝකනයකින් ආරක්ෂිත OAuth පාලන තලයක් ඇත: admin/accounts, admin/import-from-omniroute, admin/login-start, admin/login-complete (සියල්ල DARIO_ADMIN_TOKEN පිටුපස ඇත).

4.6 open-wa අන්ත ලක්ෂ්ය (මාර්ග 7)

open-wa (@open-wa/wa-automate) WhatsApp Web ස්වයංක්රීය කිරීම සඳහා ශීර්ෂ රහිත Chromium අවස්ථාවක් (Puppeteer හරහා) ධාවනය කරයි. එය Mux හි ඇති අන්ත ලක්ෂ්ය ආකෘතියම භාවිත කරයි (තවම rotate-key මාර්ගයක් නොමැත). ඒ සඳහා කළමනාකරණය කරන්නේ ජීවන චක්රය පමණි — එය මාර්ගගත කිරීමේ ඉලක්කයක් නොවන අතර, Layer 4 ක්රියාත්මකකාරකයක්/සපයන්නන්ගේ ඇතුළත් කිරීමක් ද නොමැත.

ක්රමය මාර්ගය විස්තරය
POST /api/services/openwa/install npm වෙතින් open-wa (@open-wa/wa-automate) ස්ථාපනය කරයි
POST /api/services/openwa/start open-wa 8323 port එකේ (පෙරනිමි) ආරම්භ කරයි
POST /api/services/openwa/stop open-wa නවත්වයි
POST /api/services/openwa/restart open-wa නැවත ආරම්භ කරයි
POST /api/services/openwa/update නව අනුවාදයකට යාවත්කාලීන කරයි
GET /api/services/openwa/status සජීවී + DB තත්ත්වය
POST /api/services/openwa/auto-start ස්වයංක්රීය ආරම්භය සක්රිය/අක්රිය කරයි
GET /api/services/openwa/logs SSE ලොග් අවසානය (හවුල් [name]/logs ගතික මාර්ගය හරහා)

API යතුර: WA_KEY ලෙස ඇතුළත් කෙරේ — open-wa හි සාමාන්ය WA_*-උපසර්ගිත පරිසර අතික්රමණය එය --key/-k CLI විකල්පයට අනුරූප කරයි (dist/cli/setup.js::envArgs(), ස්ථාපිත 4.76.0 package එක සමඟ සත්යාපනය කර ඇත). generateServiceApiKey() මඟින් ජනනය කරන විට ow_ උපසර්ගය යෙදේ. open-wa යතුර key/api_key HTTP header එකකින් නැවත කියවයි (Authorization: Bearer වෙතින් නොවේ); /api-docs* පරීක්ෂාවෙන් පැහැදිලිවම නිදහස් කර ඇත (dist/cli/server.js හි setupAuthenticationLayer), එබැවින් සෞඛ්ය පිරික්සුමට සත්යාපන header එකක් අවශ්ය නොවේ.

යුගල කිරීම: open-wa නිල නොවන අතර WhatsApp සමඟ අනුබද්ධ නොවේ — සම්බන්ධිත අංකයට WhatsApp හිම ස්වයංක්රීයකරණ හඳුනාගැනීම හේතුවෙන් තහනම් වීමේ අවදානමක් ඇත. පළමු ආරම්භයේදී, යුගල කිරීමේ QR කේතය stdout වෙත මුද්රණය කර පවතින ලොග් පැනලය/SSE ප්රවාහය හරහා පෙන්වයි — මෙම ඒකාබද්ධ කිරීම තුළ තවම කැපවූ QR-රූප endpoint එකක් නොමැත.

4.7 ප්රතිවිරුද්ධ ප්රොක්සිය (9Router dashboard කාවැද්දීම)

dashboard එක අභ්යන්තර ප්රතිවිරුද්ධ ප්රොක්සියක් හරහා iframe එකක් තුළ 9Router වෙබ් UI එක කාවද්දයි:

GET|POST|... /dashboard/providers/services/9router/embed/[...path]

මෙම ප්රොක්සිය:

  • ඉල්ලීම http://127.0.0.1:{port}/{path} වෙත යොමු කරයි (loopback පමණි)
  • පැමිණෙන cookie සහ authorization headers ඉවත් කරයි (OmniRoute සැසිය කාන්දු නොවේ)
  • 9Router සත්යාපනය සඳහා Authorization: Bearer {apiKey} ඇතුළත් කරයි
  • ප්රතිචාරයෙන් set-cookie, content-security-policy, x-frame-options, cross-origin-* ඉවත් කරයි
  • <base href> ඇතුළත් කිරීමට සහ නිරපේක්ෂ මාර්ග සාමාන්යකරණය කිරීමට (/foo → /dashboard/.../embed/foo) HTML ප්රතිචාර නැවත ලියයි

කාවැද්දූ dashboard එක සඳහා WebSocket upgrades, කැපවූ port එකක ඇති සහායක server එකක් මඟින් හසුරුවනු ලැබේ (src/lib/services/embedWsProxy.ts බලන්න).

ආරක්ෂාව: කාවැද්දුම් ප්රොක්සි මාර්ග LOCAL_ONLY_API_PREFIXES යටතේ වර්ගීකරණය කර ඇති අතර loopback වෙතින් පමණක් ප්රවේශ විය හැක. Cloudflare/Ngrok tunnel එකක් හරහා JWT එකක් ලබාගන්නා ප්රහාරකයෙකුට කාවැද්දූ සේවාවලට ප්රොක්සි කළ නොහැක.

5. ආරක්ෂාව

LOCAL_ONLY බලාත්මක කිරීම (දැඩි රීතිය #17)

/api/services/ සහ /dashboard/providers/services/*/embed/ යටතේ ඇති සියලුම routes, src/server/authz/routeGuard.ts තුළ LOCAL_ONLY ලෙස වර්ගීකරණය කර ඇත. ඕනෑම auth ශාඛාවකට පෙර loopback පරීක්ෂාව කොන්දේසි විරහිතව ක්රියාත්මක වේ:

ඉල්ලීම පැමිණේ
  → isLocalOnlyPath(path)?
      → loopback නොවේ → 403 LOCAL_ONLY (සෑම විටම, auth පරීක්ෂාවට පෙර)
      → loopback වේ   → සාමාන්ය auth වෙත ඉදිරියට යයි

මෙමගින් කාන්දු වූ JWT එකකට (උදා., tunnel එකක් හරහා) npm install හෝ process spawning ක්රියාත්මක කිරීම වළක්වයි. සම්පූර්ණ tier matrix එක සඳහා docs/security/ROUTE_GUARD_TIERS.md බලන්න.

API key ඇතුළත් කිරීම

9Router සහ Mux හිම HTTP endpoints සඳහා API key/bearer token එකක් අවශ්ය වේ. OmniRoute:

  1. සේවාවට විශේෂිත prefix එකක් (nr_ 9Router සඳහා, mx_ Mux සඳහා) සමඟ crypto.randomBytes(32).toString("base64url") හරහා key එකක් ජනනය කරයි.
  2. AES-256-GCM භාවිතයෙන් එය at-rest ආකාරයෙන් සංකේතනය කරයි (provider credentials සඳහා භාවිත කරන cipher එකම වේ).
  3. spawn කරන අවස්ථාවේ එය විකේතනය කර environment variable එකක් ලෙස ඇතුළත් කරයි — 9Router සඳහා NINEROUTER_API_KEY, Mux සඳහා MUX_SERVER_AUTH_TOKEN (කිසිවිටෙක CLI flag එකක් ලෙස නොවේ; එම නිසා token එක ps/process ලැයිස්තුගත කිරීම්වල කිසිවිටෙක නොපෙනේ).
  4. කිසිදු HTTP response එකක plaintext key එක කිසිවිටෙක ආපසු ලබා නොදෙයි.

CLIProxyAPI වෙත spawn කරන විට ඇතුළත් කරන වෙන් කළ data-plane key එකක් ලැබේ (needsApiKey: true — adapter එකට එරෙහි model sync කිරීම සඳහා භාවිත වේ).

SSRF ආරක්ෂණය

Reverse HTTP proxy එක (/dashboard/.../embed/[...path]) ඉල්ලීම් ඉදිරියට යැවීමට http://127.0.0.1:{port} පමණක් භාවිත වන ලෙස hardcode කර ඇත. එය loopback නොවන ගමනාන්ත වෙත යන redirects කිසිවිටෙක අනුගමනය නොකරයි. Loopback පරාසයෙන් පිටතට resolve වන ඕනෑම upstream URL එකක් ප්රතික්ෂේප කිරීමට ssrf-req-filter library එක භාවිත කරයි.

Shell ආරක්ෂාව (දැඩි රීතිය #13)

npm install කැඳවනු ලබන්නේ execFile('npm', ['install', pkg, '--prefix', dir]) හරහාය — template literals, shell එකක්, හෝ command string එක තුළට බාහිර paths interpolate කිරීමක් නොමැත. Runtime අගයන් (ports, API keys) child process එකේ env object එක හරහා යවනු ලැබේ.

Error පිරිසිදු කිරීම (දැඩි රීතිය #12)

/api/services/* වෙතින් ලැබෙන සියලුම error responses, buildErrorBody() හෝ sanitizeErrorMessage() හරහා යයි. අමු err.stack සහ err.message කිසිවිටෙක caller වෙත ඒ ආකාරයෙන්ම ආපසු ලබා නොදෙයි.

6. නව embedded service එකක් එක් කිරීම

මෙම පියවර 8 අනුගමනය කරන්න. ප්රමිතිය ලෙස අනුගමනය කළ යුතු canonical reference එක වශයෙන් src/lib/services/installers/ සහ src/app/api/services/ තුළ ඇති දැනට පවතින implementations කියවන්න.

පියවර 1 — Installer එක සාදන්න

ninerouter.ts ආදර්ශයට ගනිමින් src/lib/services/installers/{name}.ts සාදන්න:

export const NAME_PACKAGE = "your-npm-package";
export const NAME_DEFAULT_PORT = 20132; // භාවිතයේ නොමැති port එකක් තෝරන්න

export async function install(version = "latest"): Promise<InstallResult> { ... }
export async function update(version = "latest"): Promise<InstallResult> { ... }
export async function uninstall(): Promise<void> { ... }
export function resolveSpawnArgs(apiKey: string, port: number): SpawnArgs { ... }
export async function getInstalledVersion(): Promise<string | null> { ... }
export async function getLatestVersion(): Promise<string | null> { ... }

installers/utils.ts වෙතින් runNpm(['install', NAME_PACKAGE, '--prefix', dir]) භාවිත කරන්න — execSync හෝ shell interpolation කිසිවිටෙක භාවිත නොකරන්න.

පියවර 2 — Bootstrap තුළ ලියාපදිංචි කරන්න

src/lib/services/bootstrap.ts හි SERVICES array එකට ServiceEntry එකක් එක් කරන්න:

{
  tool: "myservice",
  port: NAME_DEFAULT_PORT,
  healthPath: "/health",
  healthIntervalMs: 5_000,
  stopTimeoutMs: 15_000,
  logsBufferBytes: 5_242_880,
  needsApiKey: true, // API key එකක් අවශ්ය නොවේ නම් false
}

cfg.tool === "myservice" හසුරුවන ලෙස buildSpawnArgsFactory() පුළුල් කරන්න.

සම්බන්ධ කළ හැකි provider-plugin contract එක (Phase 1, #7333)

src/lib/services/providerPlugins/ මඟින් backend එකක bootstrap.ts හි ServiceEntry fields සහ serviceBackends.ts හි manifest-template fields, එකිනෙකට සම්බන්ධ නොවන files දෙකක එකම backend එකේ ව්යුහය වෙන වෙනම ප්රකාශ කිරීම වෙනුවට, තනි object එකකට අසුරන ServiceProviderPlugin contract එකක් හඳුන්වා දෙයි. මෙය ලියන අවස්ථාව වන විට 9router පමණක් migrate කර ඇත — bootstrap.ts, එහි SERVICES[] entry එක getServiceProviderPlugin("9router") (src/lib/services/providerPlugins/registry.ts) වෙතින් ලබා ගන්නා අතර plugin එක නොමැති වුවහොත් startup error එකක් throw කරයි. cliproxy, mux, සහ bifrost වෙනස් කිරීමකින් තොරව පෙර පැවති inline SERVICES[] literals මතම පවතී.

open-sse/config/providerPluginManifest.ts වෙත SERVICE_BACKEND_MANIFEST_TEMPLATE entry එකකින් නිසි ලෙස සැකසූ ProviderPluginManifestEntry එකක් ගොඩනඟන additive createServiceBackendManifestEntry(pluginId, template) helper එකක්ද එක් කර ඇත — එය තවමත් කිසිදු සජීවී request path එකකට සම්බන්ධ කර නොමැත (generateProviderPluginManifestFromRegistry() හෝ /v1/providers/[provider]/models යන දෙකටම නොවේ); දෙවන backend එකක් සඳහා contract එක තහවුරු කළ පසු එය follow-up කාර්යයක් ලෙස පවතී.

Issue #7333 යටතේ නිරීක්ෂණය වන follow-up PRs වෙත කල් දැමූ කාර්යයන්: එකම registry එක හරහා cliproxyapi migrate කිරීම, mux/bifrost ServiceBackendPluginId union එකට සාමාන්යකරණය කිරීම, executor-routing සඳහා ඇති විශේෂ අවස්ථා හැසිරවීම (open-sse/executors/index.ts, open-sse/handlers/chatCore/executorProxy.ts) plugin contract එක තුළට ඒකාබද්ධ කිරීම, සහ createServiceBackendManifestEntry() සජීවී manifest/models code path එකකට සම්බන්ධ කිරීම.

පියවර 3 — Migration සහ DB seed එක එක් කරන්න

src/lib/db/migrations/ හි migration එකක් හරහා සේවාවට version_manager තුළ row එකක් ඇති බව සහතික කරන්න. එම row එකේ පහත දෑ තිබිය යුතුය:

INSERT OR IGNORE INTO version_manager (tool, status, auto_start, provider_expose)
VALUES ('myservice', 'not_installed', 0, 0);

පියවර 4 — API endpoints 7 සාදන්න

src/app/api/services/{name}/ යටතේ:

_lib.ts            getOrInitSupervisor() helper එක
install/route.ts   POST — installer.install() කැඳවයි
start/route.ts     POST — supervisor.start() කැඳවයි
stop/route.ts      POST — supervisor.stop() කැඳවයි
restart/route.ts   POST — supervisor.restart() කැඳවයි
update/route.ts    POST — installer.update() කැඳවයි
status/route.ts    GET  — සජීවී + DB තත්ත්වය ඒකාබද්ධ කරයි
auto-start/route.ts POST — auto_start flag එක toggle කරයි

හවුල් GET /api/services/[name]/logs route එක දැනටමත් සම්බන්ධ කර ඇත — එහි කිසිදු වෙනසක් අවශ්ය නොවේ.

සියලු දෝෂ ප්රතිචාර createErrorResponse() / buildErrorBody() හරහා පවරන්න.

පියවර 5 — LOCAL_ONLY_API_PREFIXES වෙත එක් කරන්න

src/server/authz/routeGuard.ts තුළ /api/services/ දැනටමත් ලැයිස්තුගත කර ඇති බව තහවුරු කරන්න. ඔබ නව prefix එකක් හඳුන්වා දෙන්නේ නම් (උදා., /api/tools/), එය LOCAL_ONLY_API_PREFIXES වෙතත්, එය processes ආරම්භ කරන්නේ නම් SPAWN_CAPABLE_PREFIXES වෙතත් එක් කරන්න. tests/unit/authz/routeGuard.test.ts තුළ test එකක් එක් කරන්න.

පියවර 6 — UI tab එක එක් කරන්න

src/app/(dashboard)/dashboard/providers/services/tabs/{Name}ServiceTab.tsx සාදන්න. හවුල් components නැවත භාවිත කරන්න:

  • ServiceStatusCard — සජීවී තත්ත්වය + සෞඛ්ය badge එක
  • ServiceLifecycleButtons — ආරම්භ කරන්න / නවත්වන්න / නැවත ආරම්භ කරන්න / යාවත්කාලීන කරන්න
  • ServiceLogsPanel — SSE log tail එක (/api/services/{name}/logs වෙත සම්බන්ධ වේ)
  • ApiKeyCard — key එක පෙන්වීම + මාරු කිරීම (needsApiKey: true නම්)

ServicesPageShell.tsx තුළ tab එක ලියාපදිංචි කරන්න.

පියවර 7 — provider entry එක එක් කරන්න (service එක routing target එකක් නම්)

embedded service එක OpenAI-අනුකූල /v1/chat/completions endpoint එකක් සපයන්නේ නම්:

  1. src/shared/constants/providers.ts තුළ isEmbeddedService: true සහිත provider entry එකක් එක් කරන්න.
  2. BaseExecutor දිගු කරන open-sse/executors/{name}.ts සාදන්න. එක් එක් request එක සඳහා port එක සහ API key එක නැවත සොයන්න (constructor එක තුළ කිසිවිටෙක cache නොකරන්න). supervisor තත්ත්වය "running" නොවන විට 503 service_not_running ප්රතිචාරයක් ලබා දෙන්න.
  3. service prefix එක සමඟ open-sse/config/providerRegistry.ts තුළ models ලියාපදිංචි කරන්න (උදා., myservice/sub/model). modelSync.ts ඒවා යාවත්කාලීනව තබා ගනී.

පියවර 8 — ලේඛනගත කර test කරන්න

  1. docs/frameworks/EMBEDDED-SERVICES.md (මෙම ගොනුව) යාවත්කාලීන කරන්න — §1 හි වගුවට service එක සහ §4 වෙත ඕනෑම නව endpoints එක් කරන්න.
  2. tests/unit/services/ තුළ unit tests එක් කරන්න (lifecycle, installer, API හැඩය).
  3. tests/integration/services/ තුළ integration test එකක් එක් කරන්න (RUN_SERVICES_INT=1 පිටුපස).
  4. නව endpoints සමඟ docs/openapi.yaml යාවත්කාලීන කරන්න.

7. දෝෂ නිරාකරණය

සේවාව ආරම්භ නොවේ

ලක්ෂණ: ආරම්භ කිරීමේ බොත්තම 503 ප්රතිචාරයක් ලබා දෙයි, තත්ත්වය "error" හෝ "starting" ලෙසම පවතී.

පිරික්සුම් ලැයිස්තුව:

  1. GET /api/services/{name}/logs පරීක්ෂා කරන්න (නැතහොත් උපකරණ පුවරුවේ Logs පැනලය). Error: ENOENT, address already in use, හෝ Cannot find module වැනි පේළි සොයන්න.
  2. npm PATH තුළ ඇති බව තහවුරු කරන්න: OmniRoute ධාවනය කරන එම පරිශීලක ගිණුමෙන් which npm ධාවනය කරන්න.
  3. සේවාව ස්ථාපනය කර ඇති බව තහවුරු කරන්න: installedVersion සඳහා GET /api/services/{name}/status පරීක්ෂා කරන්න. එය null නම්, පළමුව ස්ථාපනය ධාවනය කරන්න.
  4. DATA_DIR/services/{name}/node_modules/ පවතින බවත් එය හිස් නොවන බවත් පරීක්ෂා කරන්න.
  5. පිරිසිදු කරන ලද පිටවීමේ හේතුව සඳහා තත්ත්ව ප්රතිචාරයේ lastError ක්ෂේත්රය පරීක්ෂා කරන්න.

ශීත ආරම්භය මන්දගාමී වේ (running වෙත ළඟා වීමට > 10 s)

ලක්ෂණ: "running" හෝ "error" වෙත යාමට පෙර තත්ත්වය දිගු වේලාවක් "starting" ලෙසම පවතී.

පැහැදිලි කිරීම: 9Router හි ශීත ආරම්භයට විශාල පරායත්තතා වෘක්ෂ (DNS, tunnel, MITM මොඩියුල) ආයාත කිරීම ඇතුළත් වේ. අධීක්ෂකය කාල සීමාව ඉක්මවා ගිය බව ප්රකාශ කිරීමට පෙර පෙරනිමි සෞඛ්ය පරීක්ෂණ අන්තරය 2 s වන අතර උත්සාහ 3ක් සිදු කරයි (නමුත් විමසීම දිගටම කරගෙන යයි).

විසඳුම: healthIntervalMs සහ waitForHealthy කාල සීමාව (healthIntervalMs * 3) bootstrap.ts තුළ වින්යාස කළ හැකිය. දිගු ආරම්භක කාලයක් ඇති සේවා සඳහා, healthIntervalMs 5000 දක්වාත් stopTimeoutMs 30 000 දක්වාත් වැඩි කරන්න.

පෝට් ගැටීම (EADDRINUSE)

ලක්ෂණ: ලොග්වල address already in use :::20130 පෙන්වයි.

හේතු:

  • වෙනත් ක්රියාවලියක් දැනටමත් 20130 පෝට් එක භාවිත කරයි.
  • පෙර 9Router ක්රියාවලියක් සම්පූර්ණයෙන් නතර කර නොමැත (zombie PID).

විසඳුම:

  1. .env හි NINEROUTER_PORT පරිසර විචල්යය හරහා පෙරනිමි පෝට් එක වෙනස් කරන්න.
  2. ගැටෙන ක්රියාවලිය සොයා අවසන් කරන්න: lsof -ti :20130 | xargs kill -9.
  3. port ක්ෂේත්රය හරහා bootstrap.ts තුළ එක් එක් සේවාව සඳහා පෝට් එක වින්යාස කළ හැකිය.

සටහන: OmniRoute හි පෙරනිමි පෝට් එක වන 20128 සමඟ ගැටීම වැළැක්වීම සඳහා 9Router විශේෂයෙන් 20130 පෝට් එක පෙරනිමිය ලෙස භාවිත කරයි.

ස්ථාපනයේදී අවසර ප්රතික්ෂේප වීම (EACCES)

ලක්ෂණ: ස්ථාපනය 500 ප්රතිචාරයක් ලබා දෙයි, ලොග්වල EACCES හෝ permission denied පෙන්වයි.

හේතු:

  • DATA_DIR හෝ එහි මව් නාමාවලියට OmniRoute ක්රියාවලිය මඟින් ලිවිය නොහැක.
  • සිතියම්ගත කළ වොලියුමයට ලිවීමේ ප්රවේශය නොමැතිව rootless Docker තුළ ධාවනය කිරීම.

විසඳුම:

  1. DATA_DIR පරීක්ෂා කරන්න (පෙරනිමිය: ~/.omniroute/): ls -la ~/.omniroute/
  2. OmniRoute ක්රියාවලියේ පරිශීලකයාට නාමාවලියේ හිමිකාරිත්වය ඇති බව තහවුරු කරන්න: chown -R $USER ~/.omniroute/
  3. Docker තුළ, බහාලුම් පරිශීලකයා සඳහා වොලියුම් මවුන්ට් එකට නිවැරදි අවසර ඇති බව තහවුරු කරන්න.

යාවත්කාලීන කිරීම අසාර්ථක වේ (npm install කාල සීමාව ඉක්මවීම හෝ ජාල දෝෂය)

ලක්ෂණ: යාවත්කාලීන කිරීම InstallError සමඟ 500 ප්රතිචාරයක් ලබා දෙයි, ලොග්වල ජාල කාල සීමාව ඉක්මවීමක් පෙන්වයි.

පිරික්සුම් ලැයිස්තුව:

  1. npm registry වෙත ළඟා විය හැකි බව තහවුරු කරන්න: npm ping.
  2. ආයතනික proxy එකක් තිබේදැයි පරීක්ෂා කරන්න: npm config get proxy, npm config get https-proxy.
  3. ස්ථාපනය අතින් උත්සාහ කරන්න: npm install {package}@latest --prefix ~/.omniroute/services/{name}/.
  4. air-gap එකක් පිටුපස සිටී නම්, tarball එක කලින් බාගත කර npm install /path/to/tarball.tgz භාවිත කරන්න.

ආරම්භ කළ වහාම සේවාව "error" තත්ත්වය පෙන්වයි (වේගවත් බිඳවැටීම)

ලක්ෂණ: තත්ත්වය තත්පර 5කට අඩු කාලයකදී "starting" සිට "error" වෙත සංක්රමණය වේ. lastError මඟින් "Fast crash (exited with code 1)" පෙන්වයි.

පිරික්සුම් ලැයිස්තුව:

  1. සම්පූර්ණ ලොග් අවසාන කොටස කියවන්න: GET /api/services/{name}/logs?tail=500.
  2. පොදු හේතුව: සේවාව අපේක්ෂා කරන පරිසර විචල්ය නොමැති වීම.
  3. 9Router සඳහා: NINEROUTER_DISABLE_MITM=true සහ NINEROUTER_DISABLE_TUNNEL=true ක්රියාවලිය බිහි කරන විට ලබා දෙන env තුළ ඇති බව තහවුරු කරන්න ( installers/ninerouter.ts හි resolveSpawnArgs බලන්න).

8. නිතර අසන ප්රශ්න

ප්ර: කාවැද්දූ සේවාවල අන්ත ලක්ෂ්ය loopback නොවන සේවාලාභීන්ට නිරාවරණය කළ හැකිද?

නැත. LOCAL_ONLY මට්ටම හිතාමතාම පනවා ඇත (දැඩි රීතිය #17). npm install ක්රියාත්මක කළ හැකි හෝ node ක්රියාවලි ආරම්භ කළ හැකි මාර්ග loopback නොවන ගමනාගමනයෙන් ප්රවේශ විය නොහැකි විය යුතුය. එසේ නොවුවහොත්, උමඟක් (Cloudflare, Ngrok, Tailscale) හරහා JWT එකක් කාන්දු වීමෙන් අත්තනෝමතික ක්රියාවලි ආරම්භ කිරීමට ඉඩ ලැබේ. /api/services/ සඳහා මෙයින් බැහැර වීමේ විකල්පයක් නොමැත — /api/mcp/ මෙන් නොව, එය manage-scope මඟහැරීමේ ලැයිස්තුවෙන් බැහැර කර ඇත. docs/security/ROUTE_GUARD_TIERS.md බලන්න.

ප්ර: නිෂ්පාදන/වලාකුළු යෙදවුම් තුළ 9Router සහ CLIProxyAPI ලබාගත හැකි වේද?

ඔව්. සේවා දෙකම OmniRoute මෙන්ම local-first ආකෘතිය අනුගමනය කරයි. ඒවා එකම යන්ත්රයේ ක්රියාත්මක වන අතර loopback හරහා සන්නිවේදනය කරයි. මෙහි "නිෂ්පාදන" යන්නෙන් අදහස් කරන්නේ OmniRoute යොදවා ඇති VPS හෝ දේශීය සේවාදායකය මිස දුරස්ථ වලාකුළු සැපයුම්කරුවෙකු නොවේ.

ප්ර: supervisor එක දෝෂහරණය කරන්නේ කෙසේද?

  1. SSE ලොග් ප්රවාහයේ අවසානය සජීවීව නිරීක්ෂණය කරන්න: curl -N http://localhost:20128/api/services/9router/logs.
  2. service:supervisor namespace අනුව පෙරහන් කළ OmniRoute හි pino ප්රතිදානයේ ව්යුහගත ලොග් පරීක්ෂා කරන්න.
  3. DB පේළිය පරීක්ෂා කරන්න: sqlite3 ~/.omniroute/omniroute.db "SELECT * FROM version_manager WHERE tool='9router'".
  4. වත්මන් සජීවී තත්ත්වය, PID, සෞඛ්යය සහ lastError එකම ඇමතුමකින් බැලීමට GET /api/services/9router/status භාවිත කරන්න.

ප්ර: supervisor එක health: "degraded" හෝ health: "unknown" පෙන්වන නමුත් තත්ත්වය "running" වේ. එය ගැටලුවක්ද?

"degraded" යන්නෙන් අදහස් කරන්නේ සෞඛ්ය පරීක්ෂණයෙන් 200 නොවන ප්රතිචාරයක් ලැබුණු බවයි. "unknown" යන්නෙන් අදහස් කරන්නේ තවමත් කිසිදු පරීක්ෂණයක් සම්පූර්ණ වී නොමැති බවයි (පළමු poll කිරීම සමඟ ඇති race තත්ත්වයක්). ආරම්භයේදී මේ දෙකම තාවකාලික වේ. "running" වූ පසු healthIntervalMs * 3 ms කට වඩා සෞඛ්ය තත්ත්වය "degraded" ලෙස පවතී නම්, කාවැද්දූ සේවාව ක්රියාත්මක වන නමුත් එහි HTTP API එක ප්රතිචාර නොදක්වයි. තත්ත්ව ප්රතිචාරයේ port එක නිවැරදිද සහ සේවාව සැබවින්ම එම port එකේ සවන්දෙමින් සිටීද යන්න පරීක්ෂා කරන්න.

ප්ර: සම්පූර්ණයෙන් නැවත ආරම්භ කිරීමකින් තොරව 9Router API යතුර වෙනස් කළ හැකිද?

නැත. API යතුර 9Router වෙත යවනු ලබන්නේ ක්රියාවලිය ආරම්භ කරන අවස්ථාවේ environment variable එකක් හරහාය. ක්රියාත්මක වෙමින් පවතින ක්රියාවලියක environment variables වෙනස් කළ නොහැක. නව යතුර යෙදීම සඳහා POST .../rotate-key ස්වයංක්රීයව සේවාව නවත්වා නැවත ආරම්භ කරයි. යතුරු මාරු කිරීම සේවාවේ stopTimeoutMs (පෙරනිමියෙන් 15 s) සහ එහි ආරම්භක කාලය ඇතුළත ක්රියාත්මක වේ.

ප්ර: ring buffer සීමාව කුමක්ද, එය පිරුණු විට සිදු වන්නේ කුමක්ද?

සෑම සේවාවකටම වෙන්වූ 5 MB ring buffer එකක් ඇත. buffer එක පිරුණු විට, නව ලොග් පේළි සඳහා ඉඩ සැලසීමට පැරණිතම ලොග් පේළි ඉවත් කරනු ලැබේ. SSE snapshot සිදුවීම tail සීමාව තුළ ඇති වඩාත්ම මෑත පේළි ආපසු ලබා දෙයි. DB පේළියේ logsBufferPath සකසා නොමැති නම් ලොග් තැටියට ස්ථිරව සුරැකෙන්නේ නැත.

මෙයද බලන්න

  • docs/security/ROUTE_GUARD_TIERS.md — LOCAL_ONLY මට්ටමේ විස්තර
  • docs/architecture/CODEBASE_DOCUMENTATION.md — §3.2 කාවැද්දූ සේවා මොඩියුල සිතියම්කරණය
  • docs/architecture/ARCHITECTURE.md — පද්ධති මට්ටමේ සන්දර්භය
  • docs/openapi.yaml — යන්ත්රයෙන් කියවිය හැකි අන්ත ලක්ෂ්ය නිර්වචන
  • CLAUDE.md §"නව කාවැද්දූ සේවාවක් එක් කිරීම" — ඉක්මන් යොමු පිරික්සුම් ලැයිස්තුව