Servis terminal API'si
Çalışan bir servis container'ına WebSocket üzerinden, tek kullanımlık bir biletle kimliği doğrulanmış, etkileşimli bir shell açın.
Servis terminal API'si, bir servisin çalışan container'ı içinde size canlı bir shell sağlar — bir servisin dashboard'ındaki Terminal sekmesinden aldığınız PTY'nin aynısıdır. Önce normal HTTP üzerinden kısa ömürlü bir bilet oluşturur, ardından bu bileti taşıyan ve tuş vuruşları ile çıktıyı aktaran bir WebSocket açarsınız. Her iki deployment modunda da çalışır: self-hosted instance'larda container'a bir docker exec komutudur; Alaf Server Cloud'da ise Mtntasci workspace'inizde bir shell'dir. Runtime, servisin aktif deployment'ından otomatik olarak seçilir.
Temel yol ve kimlik doğrulama
Tüm yollar, instance'ınıza göre /api altında yer alır — temel yol /api/services/terminal'dir. Bileti, alaf server token create ile oluşturulmuş, bearer header (Authorization: Bearer <token>) olarak bir kişisel erişim token'ı ile oluşturun; dashboard bunun yerine oturum çerezinizi kullanır. WebSocket yükseltmesinin kendisi hiçbir bearer header taşımaz — kimlik doğrulama handshake içinde gerçekleşir (aşağıya bakın). Ayrıntılar için API genel bakışına ve kimlik doğrulama modeline bakın.
Uç Noktalar
| Metot ve yol | İzin | Ne işe yarar |
|---|---|---|
POST /api/services/terminal/ticket | terminal:write | Bir servis için tek kullanımlık, kısa ömürlü bir WebSocket kimlik doğrulama bileti oluşturur. |
GET /api/services/terminal/ws/:serviceId | public | WebSocket yükseltmesi — kimlik doğrulama handshake içinde gerçekleşir (bilet alt protokolü veya oturum çerezi). |
Her iki rota da projede admin yetkisi gerektirir
Bir servis shell'i açmak admin düzeyindedir: container'a tam erişim sağlar. Bilet rotasındaki terminal:write etiketinin ötesinde, her iki uç nokta da çağrı yapanın servisin üst projesinde admin iznine sahip olup olmadığını kontrol eder. Yönetemediğiniz (veya aktif organizasyonunuzda olmayan) bir servis 404 döndürür — Alaf Server, varlığını asla admin olmayanlara doğrulamaz.
Bilet Oluşturma
POST /api/services/terminal/ticketProp
Type
Dönüş değeri { success: true, token, expiresIn } şeklindedir. Token tek kullanımlıktır ve expiresIn saniye sonra sona erer — socket'i açmadan hemen önce oluşturun. Bu rota, servis mevcut değilse, size ait değilse veya henüz aktif bir deployment'ı yoksa, servisi çözer ve erken 404 döndürür (bir WebSocket denemesini yakmadan önce).
curl -X POST https://your-host/api/services/terminal/ticket \
-H "Authorization: Bearer $ALAFSERVER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"serviceId":"svc_123"}'CLI karşılığı
Henüz çalışan bir CLI shell'i yok — alaf server service exec "çok yakında" yazdıran bir taslaktır (CLI, WebSocket client'ı içermez). Bu uç noktaları kullanan dashboard'ın servis Terminal sekmesini kullanın.
WebSocket'i Açma
GET /api/services/terminal/ws/:serviceIdBu yola bir WebSocket bağlayın. Çünkü 401 döndüren HTTP middleware'i handshake'i iptal ederdi, bu rota HTTP katmanında herkese açıktır ve bunun yerine yükseltme içinde kimlik doğrulaması yapar. İki şey bunu kısıtlar:
- Origin — istek
Origin'i, instance'ın güvenilen-origin'ler izin listesinde olmalıdır, aksi takdirde socket4403ile kapanır. - Kimlik —
/ticket'tan gelen bileti,alaf server.terminal.v1+önekiyle (örn.alaf server.terminal.v1+<token>) bir WebSocket alt protokolü olarak geçirin. Eğer bilet mevcut değilse, Alaf Server oturum çerezine geri döner (dashboard durumu). Park edilmiş bir oturumu sürdürmek için,alaf server.terminal.resume+<resumeToken>önekiyle ikinci bir alt protokol ekleyin.
Açıldıktan sonra, wire protokolü şöyledir:
- İkili frame'ler ham PTY baytlarıdır — tuş vuruşlarını ikili olarak gönderin; stdout/stderr ikili olarak gelir.
- Metin frame'leri JSON kontrol mesajlarıdır. Client → server:
{"type":"resize","cols":N,"rows":N}(sütunlar 1–1000, satırlar 1–500 aralığında),{"type":"ping"},{"type":"close"}. Server → client: Bağlantıda{"type":"ready","sessionId","resumeToken","resumed"}, shell sona erdiğinde{"type":"exit","code","signal"},{"type":"error","code","message"}, ve{"type":"pong"}(ayrıca her ~25 saniyede bir heartbeat olarak gönderilir).
# Bir bilet oluşturun, ardından websocat ile bağlanın, bileti bir alt protokol olarak geçirin:
websocat "wss://your-host/api/services/terminal/ws/svc_123" \
--protocol "alaf server.terminal.v1+$TICKET" \
-H "Origin: https://your-host"Görebileceğiniz Hatalar
WebSocket, bir {"type":"error"} frame'i göndererek ve ardından belirli bir kodla kapanarak hataları bildirir:
4401 — yetkisiz
Geçerli bir bilet veya oturum yok, aktif bir organizasyon yok veya biletin servisi :serviceId yoluyla eşleşmiyor. Yeni bir bilet oluşturun (tek kullanımlık ve kısa ömürlüdürler) ve hemen bağlanın.
4404 — servis bulunamadı veya deploy edilmedi
Servis aktif organizasyonunuzda değil, projesinde admin yetkiniz yok veya henüz çalışan bir container'ı yok (hala deploy ediliyor veya projenin aktif bir deployment'ı yok). Canlı olduğunu doğrulamak için Servisler API'si ile servisleri listeleyin.
4400 — terminal desteklenmiyor
Servisin runtime'ı etkileşimli bir shell (not_supported) sunmuyor veya :serviceId eksikti.
4429 — çok fazla oturum
Kullanıcı başına eşzamanlı oturum sınırına ulaştınız. Mevcut bir terminali kapatın ve tekrar deneyin.
4403 — origin'e izin verilmiyor
İstek Origin'i, güvenilen-origin'ler izin listesinde değil. Dashboard'ın kendi host'undan bağlanın.