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 は今のところ非公開プロジェクトです。興味があればご連絡ください。

関連記事

2026-04-24

Task Workspace: Discord の中でそのままタスク管理

Discord と Telegram に双方向同期するタスク管理ツールを作りました。作った理由と、その仕組みを紹介します。

#product#task-management#discord
2026-04-24

VieChoice English: 間隔反復 + AI で英単語を学ぶ

間隔反復と AI を使った無料の英単語学習プラットフォーム。このプロダクトの裏にあるストーリーです。

#product#education#ai