Preskočiť na obsah

Architektúra

Zobraziť ako Markdown Upraviť na GitHub Dokumentácia na 1675df8

Vysokoúrovňový tok

Predvolené nastavenie (lokálny tmux + tunel):

Kód
Browser (phone)
  |
  | HTTPS
  v
Cloudflare Quick Tunnel
  |
  | HTTP/WS
  v
Local Termbridge server
  |
  | PTY
  v
Tmux session

Priamy režim sandboxu (Daytona, bez tunela):

Kód
Browser (phone)
  |
  | HTTPS
  v
Daytona preview link
  |
  | HTTP/WS
  v
Termbridge server (sandbox)
  |
  | PTY
  v
Tmux session (sandbox)

Keď je nastavené --no-tunnel, Termbridge preskočí Cloudflare a použije vami zadané verejné URL.

Komponenty

Proces CLI

  • Spustí server HTTP, ktorý poskytuje zdroje UI.
  • Spustí server WebSocket pre vstup a výstup terminálu.
  • Vytvorí jednu alebo viac relácií tmux (alebo Daytona PTY).
  • Vydá jednorazové tokeny na uplatnenie.
  • Spustí a monitoruje tunel, ak je povolený (aktuálne Cloudflare).
  • V priamom režime sandboxu spustí Termbridge v sandboxe a čaká na zdieľací URL.

Backend terminálu

  • Backend tmux: Používa node-pty na pripojenie k tmux pre skutočný vstup z klávesnice a výstup.
  • Backend Daytona: Používa PTY Daytona v sandboxe.
  • Nastaví TERM=xterm-256color a COLORTERM=truecolor na plnú podporu farieb.
  • Pre tmux vypne stavový riadok tmux, aby rozhranie UI zostalo prehľadné.

Register terminálov

  • Sleduje dostupné relácie terminálu.
  • Poskytuje zoznam pre UI a overuje vybrané ID terminálov.

Overovanie a relácia

  • Jednorazový token sa vypíše ako URL a zakóduje do kódu QR.
  • GET /__tb/s/:token uplatní token a nastaví relačnú cookie.
  • Pripojenia WebSocket vyžadujú platnú relačnú cookie a token CSRF.
  • Token CSRF sa načíta cez GET /__tb/api/csrf a odovzdá sa ako parameter dotazu WebSocket.

Režim proxy

Keď je zadané --proxy <port>:

  • Všetky trasy termbridge sa nachádzajú pod prefixom /__tb/
  • Požiadavky, ktoré nie sú /__tb/, sa presmerujú na cieľovú aplikáciu
  • UI sprístupňuje zobrazenia Terminál/Náhľad cez prepínač zobrazení
  • Zobrazenie Náhľad načíta iframe smerujúci na /
  • Pripojenia WebSocket pre HMR sa presmerujú na cieľ

Zabezpečenie

  • Ochrana CSRF: Aktualizácia pripojenia WebSocket vyžaduje token CSRF, aby sa zabránilo únosu z inej stránky.
  • Limity vstupu: telo HTTP s veľkosťou 64 KB, správa WebSocket s veľkosťou 1 MB, vstup terminálu s veľkosťou 64 KB na správu.
  • Obmedzenie frekvencie: Limity na uplatnenie tokenov a pripojenia WebSocket pre každé IP.

Koncové body API

Všetky trasy sa nachádzajú pod prefixom /__tb/, aby nedochádzalo ku konfliktom s aplikáciami, na ktoré sa presmerúva:

  • GET /__tb/healthz – kontrola stavu
  • GET /__tb/s/:token – uplatnenie tokenu → cookie → presmerovanie
  • GET /__tb/api/terminals – zoznam terminálov
  • GET /__tb/api/csrf – získanie tokenu CSRF pre WebSocket
  • GET /__tb/api/config – získanie konfigurácie (proxyPort, devProxyUrl)
  • POST /__tb/api/terminals – vytvorenie novej relácie tmux
  • GET /__tb/app/* – záložná trasa SPA
  • WS /__tb/ws/terminal/:terminalId?csrf=<token> – streamovanie vstupu a výstupu terminálu

Keď je povolený režim proxy:

  • GET / – presmeruje na aplikáciu proxy (alebo /__tb/app, ak je vypnutá)
  • * /* – presmeruje sa na cieľovú aplikáciu

Protokol WebSocket

Klient -> server:

JSON
{ "type": "input", "data": "ls -la" }
{ "type": "resize", "cols": 120, "rows": 32 }
{ "type": "control", "key": "ctrl_c" }

Server -> klient:

JSON
{ "type": "output", "data": "..." }
{ "type": "status", "state": "connected" }

Zásobník UI

  • Vite + TanStack Router
  • xterm.js + doplnok Fit + vykresľovač WebGL
  • Rozloženie navrhnuté najprv pre mobilné zariadenia s pevným panelom vstupu
  • Automatické opätovné pripojenie s exponenciálnym predlžovaním intervalov (najviac 10 pokusov)
  • Indikátor stavu pripojenia