Panduan Teknis 9Router decolua 2026: Arsitektur, Fallback

Satu sesi debugging dapat terhenti hanya karena kuota model utama habis. Masalahnya makin rumit ketika Claude Code, Codex, Cursor, dan Cline menyimpan endpoint serta kredensial yang berbeda. 9Router decolua mulai relevan ketika perpindahan akun dan provider sudah menjadi pekerjaan rutin.

Taruhannya bukan sekadar waktu konfigurasi. Router memproses prompt, potongan kode, token OAuth, API key, pemilihan model, dan data penggunaan. Kesalahan routing dapat memengaruhi biaya, keamanan, dan konsistensi hasil coding.

Pembahasan teknis ini akan mencakup:

• Arsitektur request: komponen yang bekerja sejak request masuk hingga respons kembali.
• Model konfigurasi: hubungan provider, connection, model, alias, dan combo.
• Pilihan deployment: karakteristik npm, Docker, serta instalasi dari source.
• Validasi fungsi: pengujian streaming, tool calling, fallback, dan RTK.
• Hardening operasional: pembatasan jaringan, backup, pembaruan, dan mitigasi versi lama.

Rincian berikut dapat dipakai sebagai dasar evaluasi sebelum 9Router dijalankan pada workstation, server internal, atau lingkungan produksi.

Arsitektur 9Router decolua dan jalur request

9Router decolua merupakan proxy AI mandiri yang menyediakan endpoint kompatibel dengan API OpenAI. Klien AI coding mengirim request ke endpoint tersebut, lalu 9Router meneruskannya ke provider yang dipilih oleh konfigurasi routing.

Satu endpoint 9Router dapat melayani beberapa klien, akun, dan provider AI. Klien tidak perlu mengetahui detail autentikasi setiap backend. Konfigurasi di sisi klien umumnya hanya berisi base URL, API key lokal, dan identitas model atau combo.

Endpoint yang sering dipakai meliputi:

• API utama: http://localhost:20128/v1
• Daftar model: GET /v1/models
• Chat completions: POST /v1/chat/completions
• Dashboard: pengelolaan provider, connection, combo, dan penggunaan.
• Endpoint tambahan: audio, MCP, atau layanan lain sesuai rilis.

Siklus pemrosesan request dapat dibagi menjadi beberapa lapisan:

flowchart LR
    A["Klien AI coding"] --> B["API Gateway 9Router"]
    B --> C["Validasi API key"]
    C --> D["Resolusi model atau alias"]
    D --> E["Pemilihan combo dan connection"]
    E --> F["Penerjemahan payload"]
    F --> G["Provider AI"]
    G --> H["Normalisasi respons"]
    H --> I["Streaming dan pencatatan usage"]
    I --> A

API gateway menerima payload yang mengikuti pola OpenAI. Lapisan resolusi mencari model, alias, atau combo yang sesuai. Executor provider kemudian menangani autentikasi, token refresh, format request, dan komunikasi dengan upstream.

Respons dari upstream tidak selalu memakai struktur yang sama. 9Router perlu menormalkan status error, metadata token, dan format streaming sebelum meneruskannya ke klien.

Keberhasilan request chat biasa belum membuktikan kompatibilitas penuh. Tool calling, structured output, reasoning parameter, multimodal input, streaming SSE, dan konteks panjang harus diuji secara terpisah.

Catatan: Angka jumlah provider berbeda antara dokumentasi dan materi pihak ketiga. Gunakan katalog pada versi yang terpasang sebagai acuan teknis.

Relasi provider, connection, model, alias, dan combo

Kesalahan konfigurasi umumnya muncul karena beberapa objek dianggap sama. Padahal, masing-masing berada pada lapisan yang berbeda.

• Provider: jenis backend, misalnya OpenAI, Gemini, Vertex AI, Copilot, Ollama, atau endpoint kompatibel.
• Connection: kredensial atau sesi tertentu pada provider, seperti API key dan token OAuth.
• Model: model yang diekspos oleh sebuah connection.
• Alias: identitas virtual yang menunjuk ke model atau jalur routing.
• Combo: kumpulan model atau connection dengan strategi pemilihan tertentu.

Satu provider dapat mempunyai beberapa connection. Tim dapat memisahkan akun produksi, pengujian, wilayah, serta proyek tanpa membuat definisi provider baru.

Gunakan nama connection yang menjelaskan konteks, misalnya OpenAI-Produksi, Vertex-Proyek-A, atau Ollama-Internal. Nama seperti Akun-1 menyulitkan audit log dan rotasi kredensial.

Alias berfungsi sebagai kontrak stabil bagi klien. Cursor dapat terus meminta coding-main, sementara administrator mengubah model di belakang alias tersebut. Konfigurasi pada setiap workstation tidak perlu disunting.

Combo menambahkan logika routing. Contoh susunannya:

1. Model utama: kualitas dan fitur telah diuji.
2. Cadangan setara: mendukung tool serta konteks serupa.
3. Cadangan hemat: dipakai untuk tugas berisiko rendah.

Fallback mempertahankan ketersediaan, tetapi tidak menjamin hasil antarmodel tetap identik. Perbedaan tokenizer, tool schema, batas konteks, dan perilaku reasoning dapat mengubah keluaran.

Runtime, penyimpanan, dan struktur data

Rilis modern 9Router memakai Node.js 22 pada jalur runtime tertentu. Persyaratan aktual tetap perlu diperiksa melalui package.json, Dockerfile, dan halaman rilis 9Router.

Dokumentasi lama dapat merujuk ke penyimpanan JSON berbasis lowdb. Generasi yang lebih baru menggunakan SQLite dengan beberapa implementasi adapter. Berkas yang dijumpai dapat mencakup:

• db.sqlite: konfigurasi provider, node, model, dan combo.
• usage.json: data token serta biaya.
• request-details.json: detail observabilitas bila fitur terkait aktif.
• db.json: format lama yang mungkin masih ada setelah migrasi.

Perubahan format penyimpanan membuat backup wajib dilakukan sebelum pembaruan lintas versi. Mengganti image aplikasi tanpa memahami migrasi database dapat menyebabkan rollback gagal.

Baca juga Muse Spark 1.2 Telah Rilis, Ini Fitur dan Kelebihannya

Direktori data harus berada pada storage persisten. Untuk Docker, image resmi saat ini menggunakan target volume /data. Hindari menyalin konfigurasi volume dari panduan lama tanpa memeriksa dokumentasi image yang dipakai.

Memilih metode instalasi

npm global sesuai untuk satu pengguna yang membutuhkan service lokal. Kondisi Node.js, npm, PATH, dan dependensi host harus tetap konsisten.

Docker lebih tepat untuk server tim. Runtime dipaketkan dalam image, sedangkan data disimpan melalui named volume. Tag image sebaiknya dikunci agar pembaruan tidak masuk tanpa pengujian.

Instalasi dari source berguna untuk audit dependensi, patch internal, atau pengembangan executor baru. Jalur ini menambah tanggung jawab terhadap build, uji regresi, migrasi data, dan pemeliharaan fork.

Tips: Catat versi aplikasi, image digest, konfigurasi environment, dan skema volume. Informasi tersebut mempercepat pemulihan saat update gagal.

Cara: memasang dan memvalidasi 9Router

1. Periksa runtime dan port

Untuk jalur npm atau source, periksa Node.js dan npm:

node --version
npm --version

Untuk Docker:

docker version

Port bawaan umumnya 20128. Pada Linux atau macOS, periksa konflik port:

lsof -i :20128

Jika port sudah digunakan, identifikasi prosesnya. Jangan menghentikan service sebelum mengetahui fungsi dan pemiliknya.

2. Jalankan instalasi npm atau Docker

Untuk npm global:

npm install -g 9router
9router

Jika perintah 9router tidak ditemukan, periksa lokasi binary npm global:

npm prefix -g
npm bin -g

Perintah kedua tidak tersedia pada seluruh versi npm. Jika gagal, gunakan output prefix untuk mencari direktori binary dan perbarui PATH.

Untuk Docker, gunakan image resmi dari Docker Hub decolua/9router:

docker run -d \
  --name 9router \
  --restart unless-stopped \
  -p 127.0.0.1:20128:20128 \
  -v 9router-data:/data \
  decolua/9router:latest

Binding 127.0.0.1 mencegah akses langsung dari antarmuka jaringan lain. Pada produksi, ganti latest dengan tag versi yang sudah lolos pengujian.

3. Verifikasi proses dan penyimpanan

Periksa status container:

docker ps --filter name=9router
docker logs --tail 100 9router

Container harus berstatus Up dan tidak terus-menerus restart. Log perlu diperiksa untuk menemukan:

• Konflik port
• Izin volume
• Direktori data salah
• Migrasi database gagal
• Environment variable tidak valid

Pastikan mount mengarah ke lokasi yang benar:

docker inspect 9router

Cari bagian Mounts, lalu pastikan named volume terhubung ke /data.

4. Buat satu connection

Buka dashboard dan tambahkan satu provider. Gunakan OAuth, API key, atau base URL sesuai mekanisme provider.

Jangan memasukkan seluruh akun sekaligus. Satu connection yang teruji memberi baseline untuk membedakan masalah autentikasi, translator, model, dan jaringan.

Nama connection sebaiknya mengandung fungsi atau lingkungan:

Baca juga OmniRoute: AI gateway self-hosted untuk routing model lintas provider

Copilot-Dev
OpenAI-Produksi
Vertex-Proyek-A
Ollama-Internal

Setelah tersambung, pastikan model yang diharapkan tampil pada dashboard.

5. Buat alias model

Buat alias seperti coding-main yang menunjuk ke model utama. Uji daftar model melalui endpoint:

curl http://localhost:20128/v1/models \
  -H "Authorization: Bearer KUNCI_9ROUTER"

Jika alias tidak muncul, periksa:

• Status connection
• Model upstream aktif
• Nama alias
• Izin akun
• Filter model pada versi tersebut

Respons 401 menunjukkan masalah pada API key klien. Respons 403 lebih sering terkait izin upstream atau autentikasi provider.

6. Uji request tanpa streaming

Kirim payload minimal:

curl http://localhost:20128/v1/chat/completions \
  -H "Authorization: Bearer KUNCI_9ROUTER" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "coding-main",
    "messages": [
      {
        "role": "user",
        "content": "Balas hanya dengan kata OK"
      }
    ]
  }'

Periksa status HTTP, body respons, model yang dipilih, dan catatan penggunaan. Jika request dasar gagal, jangan lanjut ke combo atau tool calling.

7. Tambahkan combo dan fallback

Setelah model utama stabil, buat combo dengan maksimal dua atau tiga jalur pada tahap awal. Terlalu banyak connection membuat diagnosis sulit karena request dapat berpindah beberapa kali.

Uji tiga jenis kegagalan:

1. Kuota habis: apakah router pindah ke cadangan?
2. Connection dinonaktifkan: apakah model berikutnya dipilih?
3. Payload tidak valid: apakah router mengembalikan error tanpa fallback yang keliru?

Kesalahan payload seharusnya tidak disamarkan sebagai gangguan provider. Jika semua error memicu fallback, biaya dan latensi dapat meningkat tanpa memperbaiki request.

8. Hubungkan klien sebenarnya

Konfigurasi dasar klien:

Base URL : http://localhost:20128/v1
API Key  : KUNCI_9ROUTER
Model    : coding-main

Setelah chat biasa berhasil, lanjutkan dengan:

• Streaming SSE
• Tool calling
• Structured output
• Pembacaan diff
• Konteks panjang
• Pembatalan request
• Fallback saat respons sedang berjalan

Masalah umum terjadi saat klien menambahkan /v1 secara otomatis. Jika log menunjukkan /v1/v1/chat/completions, hapus salah satu prefiks.

Strategi fallback dan distribusi request

9Router mendukung beberapa pola pemilihan connection. Masing-masing memiliki konsekuensi terhadap konsistensi, kuota, dan latensi.

Combo sebaiknya dipisahkan menurut karakter pekerjaan:

• quick-edit: format, rename, dan perubahan kecil.
• daily-code: implementasi fitur rutin serta unit test.
• architecture: refactor besar dengan model utama tetap.
• security-review: model terverifikasi tanpa fallback sembarang.
• local-private: hanya memakai backend internal.

Peringatan: Jangan izinkan data sensitif berpindah ke provider publik hanya karena backend privat mengalami timeout. Batas fallback harus menjadi bagian dari kebijakan data.

Error 429 atau gangguan upstream umumnya layak memicu fallback. Error 400 akibat payload salah perlu dikembalikan kepada klien agar sumber masalah dapat diperbaiki.

Menguji RTK Token Saver secara teknis

RTK Token Saver memadatkan output tool sebelum konten dikirim ke model. Targetnya antara lain git diff, git status, grep, find, daftar file, dan log berulang.

Penghematan token harus diuji bersama kualitas konteks yang dipertahankan. Output yang lebih pendek tidak berguna jika baris error, nama file, atau perubahan penting ikut terhapus.

Gunakan eksperimen A/B:

1. Jalankan tugas pada commit dan prompt yang sama.
2. Catat token input, output, latensi, biaya, dan hasil.
3. Ulangi dengan RTK aktif.
4. Bandingkan konteks yang hilang.
5. Hitung jumlah retry dan koreksi manual.

Klaim penghematan pada dokumentasi proyek sebaiknya diperlakukan sebagai referensi. Struktur repository, jenis tool, dan panjang output sangat memengaruhi hasil.

Baca juga Macaron-V1-Venti: Model 748B Terbuka Berbasis GLM-5.2

Audit keamanan, forensik, stack trace kompleks, serta pemeriksaan patch sering membutuhkan data utuh. Metrik yang lebih tepat ialah biaya per tugas yang selesai dengan benar, bukan token per request.

Keamanan endpoint dan CVE-2026-10269

9Router menangani API key, token OAuth, prompt, kode, dan metadata penggunaan. Posisi ini menjadikannya komponen dengan dampak tinggi jika host atau dashboard berhasil diakses pihak lain.

CVE-2026-10269 dilaporkan memengaruhi versi hingga 0.4.0. Jangan mempertahankan versi terdampak. Gunakan rilis terawat yang lebih baru, periksa changelog, dan rotasi secret jika instance lama pernah terbuka ke jaringan yang tidak tepercaya.

Port 20128 tidak sebaiknya dibuka langsung ke internet. Untuk pemakaian lokal, bind ke 127.0.0.1. Akses jarak jauh sebaiknya melewati VPN, SSH tunnel, atau reverse proxy dengan TLS.

Kontrol minimum meliputi:

• Key terpisah: bedakan API key klien dan kredensial provider.
• Segmentasi jaringan: izinkan hanya subnet yang membutuhkan akses.
• Rotasi token: ganti secret setelah insiden atau pergantian anggota tim.
• Log aman: hapus prompt, token, kode, dan alamat internal sebelum dibagikan.
• Backup terenkripsi: arsip data dapat memuat konfigurasi sensitif.
• Pembatasan dashboard: jangan samakan akses dashboard dengan akses API.

Fitur MITM proxy membutuhkan kontrol tambahan karena melibatkan sertifikat lokal dan intersepsi trafik. Dokumentasikan perangkat yang memasang sertifikat, masa berlaku, serta prosedur pencabutannya.

Backup, update, dan rollback

Named volume perlu dicadangkan sebelum update:

docker stop 9router
docker run --rm \
  -v 9router-data:/data \
  -v "$PWD":/backup \
  alpine tar -czf /backup/9router-data.tar.gz -C /data .
docker start 9router

Urutan pembaruan yang aman:

1. Catat versi aktif dan image digest.
2. Baca catatan rilis untuk perubahan konfigurasi atau database.
3. Buat backup dan verifikasi isi arsip.
4. Uji rilis baru pada salinan data.
5. Jalankan smoke test untuk model, streaming, tool, dan fallback.
6. Simpan image lama serta backup sebelum migrasi.

Rollback image tidak otomatis memulihkan database. Jika skema SQLite telah berubah, data perlu dikembalikan dari backup yang sesuai dengan versi lama.

Catatan: Jadwalkan uji pemulihan, bukan hanya pembuatan arsip. Backup yang tidak pernah direstore belum membuktikan kesiapan pemulihan.

Troubleshooting berdasarkan lapisan

Perintah Docker yang berguna:

docker inspect 9router
docker logs --since 10m 9router
docker exec 9router env

Klien dalam container tidak dapat memakai localhost untuk mengakses host tanpa pengaturan jaringan. Gunakan hostname yang sesuai, misalnya host.docker.internal pada lingkungan yang mendukungnya atau jaringan Docker khusus di Linux.

Kelebihan & Kekurangan

Kelebihan

• Endpoint terpadu: konfigurasi klien lebih konsisten.
• Abstraksi model: alias memisahkan klien dari backend aktual.
• Fallback otomatis: gangguan provider dapat ditangani tanpa perubahan manual.
• Observabilitas terpusat: usage dan error lebih mudah ditelusuri.
• Deployment mandiri: data router berada pada infrastruktur sendiri.

Kekurangan

• Titik kegagalan baru: router mati dapat memutus semua klien.
• Kredensial terkonsentrasi: kompromi host berdampak luas.
• Variasi model: fallback dapat mengubah kualitas dan perilaku tool.
• Kompleksitas operasi: tim harus mengelola jaringan, backup, dan update.
• Ketergantungan translator: fitur tertentu dapat berbeda antarprovider.

Untuk satu tool dan satu model, koneksi langsung lebih sederhana. 9Router lebih masuk akal ketika jumlah klien, akun, dan jalur provider sudah membutuhkan lapisan orkestrasi.

Checklist

• Versi: hindari 0.4.0 atau versi yang lebih lama.
• Runtime: cocokkan Node.js atau tag image dengan dokumentasi rilis.
• Port: bind endpoint ke localhost atau jaringan privat.
• Storage: pastikan volume persisten terpasang pada /data.
• Connection: uji satu akun dan model sebelum membuat combo.
• Fallback: bedakan error upstream dari payload tidak valid.
• Klien: validasi streaming, tool calling, dan konteks panjang.
• RTK: ukur token bersama kualitas hasil dan jumlah retry.
• Keamanan: pisahkan key klien dari kredensial provider.
• Pemulihan: uji backup dan rollback sebelum update produksi.

Inti Teknis 9Router

• Arsitektur terpusat: Satu endpoint menangani beberapa klien, akun, dan provider AI.
• Konfigurasi berlapis: Provider, connection, model, alias, dan combo memiliki fungsi berbeda.
• Deployment persisten: Docker memerlukan volume /data agar konfigurasi tetap tersimpan.
• Fallback terkontrol: Bedakan gangguan upstream dari payload tidak valid sebelum berpindah model.
• Validasi menyeluruh: Uji streaming SSE, tool calling, structured output, dan konteks panjang.
• Efisiensi terukur: Nilai RTK bersama kualitas konteks, latensi, dan jumlah retry.
• Hardening wajib: Hindari versi 0.4.0 atau lebih lama dan batasi port 20128.

9Router memberi lapisan orkestrasi saat klien dan provider AI mulai sulit dikelola langsung. Stabilitasnya bergantung pada konfigurasi presisi, pengujian berlapis, serta backup yang sudah diuji pemulihannya.