İçeriğe geç

Mimari

Markdown olarak görüntüle GitHub üzerinde düzenle Dokümantasyon: 1675df8

Üst düzey akış

Varsayılan (yerel tmux + tünel):

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

Doğrudan sandbox modu (Daytona, tünel yok):

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

--no-tunnel ayarlandığında Termbridge, Cloudflare adımını atlar ve sağladığınız genel URL değerini kullanır.

Bileşenler

CLI süreci

  • UI varlıklarını sunan HTTP sunucusunu başlatır.
  • Terminal G/Ç'si için WebSocket sunucusunu başlatır.
  • Bir veya daha fazla tmux oturumu (ya da Daytona PTY) oluşturur.
  • Tek kullanımlık kullanım belirteçleri oluşturur.
  • Etkinleştirildiğinde tüneli başlatır ve izler (bugün Cloudflare).
  • Doğrudan sandbox modunda, Termbridge'i sandbox içinde başlatır ve paylaşım URL değerini bekler.

Terminal arka ucu

  • tmux arka ucu: Gerçek tuş girişleri ve çıktı için node-pty kullanarak tmux'ye bağlanır.
  • Daytona arka ucu: Sandbox içinde Daytona PTY'leri kullanır.
  • Tam renk desteği için TERM=xterm-256color ve COLORTERM=truecolor ayarlar.
  • tmux için, UI'i temiz tutmak amacıyla tmux durum çubuğunu devre dışı bırakır.

Terminal kayıt defteri

  • Kullanılabilir terminal oturumlarını izler.
  • UI için liste sağlar ve seçilen terminal kimliklerini doğrular.

Kimlik doğrulama ve oturum

  • Tek kullanımlık belirteç bir URL olarak yazdırılır ve bir QR koduna kodlanır.
  • GET /__tb/s/:token belirteci kullanır ve bir çerez oturumu ayarlar.
  • WebSocket bağlantıları geçerli bir oturum çerezi ve CSRF belirteci gerektirir.
  • CSRF belirteci GET /__tb/api/csrf üzerinden alınır ve WebSocket sorgu parametresinde iletilir.

Proxy modu

--proxy <port> aktarıldığında:

  • Tüm termbridge yolları /__tb/ önekinin altında yer alır
  • /__tb/ olmayan istekler hedef uygulamaya proxy edilir
  • UI, Görünümler değiştiricisi aracılığıyla Terminal/Önizleme görünümlerini sunar
  • Önizleme görünümü, / adresini gösteren bir iframe yükler
  • HMR için WebSocket bağlantıları hedefe iletilir

Güvenlik

  • CSRF koruması: Siteler arası ele geçirmeyi önlemek için WebSocket yükseltmeleri CSRF belirteci gerektirir.
  • Girdi sınırları: 64KB HTTP gövdesi, 1MB WebSocket mesajı, mesaj başına 64KB terminal girdisi.
  • Hız sınırlaması: Belirteç kullanımı ve WebSocket bağlantıları için IP başına sınırlar.

API uç noktaları

Proxy edilen uygulamalarla çakışmaları önlemek için tüm yollar /__tb/ önekinin altında yer alır:

  • GET /__tb/healthz - sistem durumu denetimi
  • GET /__tb/s/:token - belirteç kullanımı → çerez → yönlendirme
  • GET /__tb/api/terminals - terminalleri listeleme
  • GET /__tb/api/csrf - WebSocket için CSRF belirteci alma
  • GET /__tb/api/config - yapılandırma alma (proxyPort, devProxyUrl)
  • POST /__tb/api/terminals - yeni bir tmux oturumu oluşturma
  • GET /__tb/app/* - SPA yedeği
  • WS /__tb/ws/terminal/:terminalId?csrf=<token> - terminal G/Ç'sini aktarma

Proxy modu etkinleştirildiğinde:

  • GET / - proxy edilen uygulamaya yönlendirir (devre dışıysa /__tb/app)
  • * /* - hedef uygulamaya proxy edilir

WebSocket protokolü

İstemci -> sunucu:

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

Sunucu -> istemci:

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

UI yığını

  • Vite + TanStack Router
  • xterm.js + Fit eklentisi + WebGL oluşturucu
  • Mobil öncelikli düzen ve sabit giriş çubuğu
  • Üstel beklemeyle otomatik yeniden bağlanma (en fazla 10 deneme)
  • Bağlantı durumu göstergesi