WebShell

WebShell はブラウザ向けのターミナルで、プラットフォームの他の部分が使うのと同じ geminio トンネル経由ですべての登録 edge に届きます。別個の SSH 踏み台もジャンプボックスもインバウンドポートもありません。edge はダイヤルアウトを続け、manager がシェル I/O 用の多重化ストリームクラスを開きます。

ユースケース：

エージェントが修正を提案 → 「edge-prod-04 でシェルを開く」をクリック → SPA を離れずに変更を確認。
ベンダー / 契約者が VPN 登録なしに 1 つのホストを一回限り見る必要がある。
インシデント対応：すべてのコマンドが起源セッションの監査行と共に記録される。

アーキテクチャ

text

browser ──WebSocket──> manager:/v1/webshell/ws
                          │
                          ├─ Router.Register(sessionID, sink, ActiveSession)
                          │
                          └─ geminio Stream (shell class)
                                  │
                                  ▼
                              edge agent
                                  └─ pty.Start("/bin/bash")

manager 側ルーターは internal/manager/biz/webshell/router.go にあります。sessionID → Sink ディレクトリを維持：WebSocket ハンドラーが接続時に登録し、トンネル受信 dispatcher が edge の出力 / 終了プッシュを正しいブラウザにルーティングします。

// internal/manager/biz/webshell/router.go:57
type Router struct {
    mu          sync.RWMutex
    sinks       map[string]Sink
    meta        map[string]*ActiveSession // sessionID → metadata
    stdoutBytes sync.Map                  // sessionID → *uint64
}

HTTP / WebSocket ハンドラーは隣の internal/manager/server/webshell にあるので、ルーターは HTTP に依存せず単体テスト可能なまま保たれます。

2 つのストリームクラス

geminio トンネルは多重化します：

コントロールクラス —— JSON RPC（スキル実行、プラグインシグナリング、アラート evaluator プローブ）。
シェルクラス —— 生バイトストリーム（WebShell セッションごとに 1、 tail -f フォロワーごとに 1 など）。

トンネルレベルでの分割が重要なのは、シェル I/O がバースト的で枠なしだからです。コントロール RPC と混ぜると後者が飢餓状態になります。各クラスは独自のバックプレッシャー予算を持ちます。

セッションメタデータ

各ライブセッションは ActiveSession を持ちます：

// router.go:37
type ActiveSession struct {
    SessionID    string
    OngridUserID uint64
    SSHUser      string
    DeviceID     uint64
    EdgeID       uint64
    StartedAt    time.Time
    LastInputAt  time.Time // updated on every browser → edge frame
}

LastInputAt はキーストロークごとに tick（Router.TouchInput）。アイドルタイムアウト監視は最近の入力なしで設定された制限より古いセッションを退去させます —— 「実行中のコマンドが残ったままブラウザタブを閉じた」リークから守ります。

監査記録

2 つのレイヤー：

ヘッダー行 —— webshell_sessions テーブル：誰が、いつ、どの edge、終了コード、合計の入出力バイト。
ストリーム記録 —— manager 側の Recorder インターフェイスがワイヤーを越える全バイト（両方向、タイムスタンプ付き）を取り、 /var/lib/ongrid/webshell-recordings/<session_id>.cast の asciinema 互換 cast ファイルに追記します。admin の /admin/webshell ページが再生します。

Recorder インターフェイスは意図的に狭い —— 本番はファイルシンクを使用、テストは fake を注入、将来のクラウド blob バックエンドは残りのスタックを触らずに投入できます。

同時実行制限

ユーザーごとキャップ：WebSocket open ハンドラーから Router.CountByUser が呼ばれ、キャップ超え接続は HTTP 429 で拒否されます。デフォルトキャップは 5（設定可能）。edge ごとキャップは暴走エージェントが 100 並列シェルを開くのを防ぎます。

セッションの強制終了

3 つのパスがセッションを強制終了します：

ブラウザクローズ —— WebSocket 切断が edge に伝播し、edge が pty を kill -HUP する。
Admin 強制終了 —— admin SPA が Sink に Killer.Kill(reason="admin terminated") を呼び、edge にクローズをトンネルダウンする。理由はセッションの終了行に記録される。
アイドル退去 —— 監視が LastInputAt がキャップを超えたセッションに Kill("idle timeout") を発火する。

// router.go:50
type Killer interface {
    Kill(reason string)
}

manager 側ハンドラーは Sink を登録するときに Killer をインストールします。opt-in した Sink は admin 強制終了可能になり、それ以外はブラウザクローズ強制終了のみ可能です。

ロールゲーティング

WebShell は admin ロールでゲートされます（ADR-022 RBAC）。user ロールはエージェントとチャットできますがシェルは開けません。viewer は過去のセッションの記録を読めますが新規は開けません。ゲートは WebSocket アップグレードの前、HTTP ハンドラーエントリで動きます。

WebShell ​

アーキテクチャ ​

2 つのストリームクラス ​

セッションメタデータ ​

監査記録 ​

同時実行制限 ​

セッションの強制終了 ​

ロールゲーティング ​

関連 ​