xcluster: ホームラボのためのコントロールプレーン
ホームラボ全体をブラウザから管理するプラットフォームを作りました。SSH ターミナル、Docker、Wake-on-LAN、監視。Go で書いています。
私のホームラボには数台のマシンがあります。Docker を動かし、サービスをホストし、ときどき Kubernetes クラスターになります。それらを管理するには、ターミナルを開いて一台ずつ SSH で入り、CPU を確認し、コンテナを再起動し、次のマシンでまた同じことを繰り返す必要がありました。
5 台で 5 つのターミナルセッション。どのマシンで何が動いているか忘れる。どれが止まっているか分からない。起動したければ MAC アドレスを覚えておく必要がある。
そこで xcluster を書きました。
xcluster とは
ホームラボのすべてのマシンをブラウザから操作する ためのダッシュボードです。監視ツールではなく、本物の コントロールプレーン です。マシンに SSH で入る、コマンドを実行する、Docker を管理する、起動/シャットダウン/再起動する。すべてを一か所で行えます。
作っていて一番楽しかったところ
本物の Web ターミナル
ターミナルのふりをしたテキストボックスではありません。xcluster は WebSocket を 完全な PTY 割り当て 付きの SSH 接続にプロキシします。つまり、ブラウザで開いたターミナルが iTerm と同じように動きます。タブ補完、vim、htop、tmux、Ctrl+C、すべてです。
バックエンドは WebSocket のフレームを受け取り、SSH セッションに流し込み、出力を送り返します。接続は Gorilla WebSocket、SSH プロトコルは golang.org/x/crypto/ssh が担当します。ターミナルセッションはそれぞれ専用の goroutine で動くので、メインスレッドをブロックしません。
複数の SSH 認証方式
すべてのマシンが同じ方法で認証するわけではありません。xcluster は次に対応しています:
- パスワード: 昔ながらのパスワード。保存時は AES-256-GCM で暗号化
- PEM ファイル: 秘密鍵をアップロードし、暗号化して保存
- デフォルトの SSH キー: サーバーの
~/.ssh/id_rsaを使用 - xcluster キー: ED25519 の鍵ペアを自動生成し、対象マシンに自動で配置
すべての認証情報は保存前に暗号化されます。鍵はサーバーのシークレットから導出します。平文で保存することは一切ありません。
賢いクラスター操作
クラスターを再起動するとき、順序は重要です。worker より先に master を再起動するとダウンタイムが発生します。xcluster はトポロジーを理解しています:シャットダウンは worker が先、master が最後。起動はその逆で、master が先 です。
一括操作には並行数の制御があるので、全マシンに一度に負荷をかけることはありません。
エージェントなしのリアルタイムメトリクス
対象マシンにエージェントをインストールする必要はありません。xcluster が SSH で入り、cat /proc/stat、free -b、df -B1 を実行し、出力をパースしてメトリクスを保存します。バックグラウンドの cron ジョブが 30 分ごとに動きます。Pusher が接続中のすべてのダッシュボードにメトリクスを配信するので、リロードなしでライブ更新されます。
そう、メトリクスを取るために 30 分ごとに全マシンに SSH しています。Prometheus + node_exporter ほどエレガントではありませんが、対象マシンでのセットアップはゼロ。挿せばすぐ動きます。
SSH 経由の Docker 管理
xcluster はリモートマシンの Docker ソケットへのアクセスを必要としません。SSH で入り、docker ps、docker inspect を実行して JSON 出力をパースします。コンテナ、イメージ、ボリューム、ネットワーク、すべて SSH トンネル経由で管理します。
つまり、Docker API をネットワークに公開せずにリモートマシンの Docker を管理できます。デフォルトで安全です。
アーキテクチャ
Go backend: Go を選んだ理由は、並行 SSH セッションのための goroutine、小さなコンパイル済みバイナリ(Alpine イメージで約 20MB)、強い型付け、優れた SSH ライブラリです。
DDD で構成:domain/machine、domain/cluster、domain/metric、domain/docker、domain/terminal。各ドメインに handler → service → repository があり、DI コンテナがすべてをつなぎます。
React frontend: Vite + React 19 + TypeScript。ターミナル UI は xterm.js で、VS Code の統合ターミナルと同じライブラリです。設定の編集(YAML、JSON)には Monaco Editor。
型安全な SDK: OpenAPI 仕様は Go のコード(swag アノテーション)から自動生成されます。CI パイプラインがそれを TypeScript の型に変換し、SDK パッケージとして公開します。フロントエンドは SDK を import して型安全に API を呼びます。バックエンドで API を変えれば、フロントエンドの型が勝手に更新されます。手作業の同期はゼロです。
ロードマップ
Kubernetes 対応を開発中です:
- Kubernetes クラスターのプロビジョニング(kubeadm、k3s)
- ダッシュボードからの Pod/Deployment/Service 管理
- Helm チャートのデプロイ
- Pod からのログストリーミング
- リソースメトリクスのダッシュボード(Pod/ノードごとの CPU、メモリ)
- Web ターミナル経由の kubectl プロキシ
非公開
xcluster は今のところ非公開プロジェクトです。興味があればご連絡ください。
関連記事
Task Workspace: Discord の中でそのままタスク管理
Discord と Telegram に双方向同期するタスク管理ツールを作りました。作った理由と、その仕組みを紹介します。
2026-04-24VieChoice English: 間隔反復 + AI で英単語を学ぶ
間隔反復と AI を使った無料の英単語学習プラットフォーム。このプロダクトの裏にあるストーリーです。