TunnelDeck デスクトップ版ガイド：ssh -L を保存できるトンネルへ

SSH のローカルポート転送は便利ですが、コマンドが増えるとポート、転送先、秘密鍵の場所を管理しにくくなります。TunnelDeck は ssh -L を保存・編集し、すぐに開始／停止できる軽量なクロスプラットフォームデスクトップアプリです。ホスト指紋の確認、OS の認証情報ストア、ローカルのみの待ち受けといった重要な安全策も維持します。

たとえば、次のコマンドをそのままインポートできます。

ssh -L 9108:127.0.0.1:9108 -p 33899 root@ssh.example.com

接続後、手元の PC から 127.0.0.1:9108 を開くと、通信は SSH サーバーを経由し、SSH サーバーから見た 127.0.0.1:9108 へ転送されます。

この記事ではデスクトップ版 v0.3.1 を中心に、インストール、接続の作成、パスワード／秘密鍵認証、初回の指紋確認、ブラウザーショートカット、トラブルシューティングまで順に説明します。

TunnelDeck が向いている用途

現在の TunnelDeck は SSH の ローカルポート転送（-L） に特化しています。

サーバーのループバックアドレスだけで待ち受ける管理画面へのアクセス；
踏み台サーバー経由でのデータベース、開発サービス、社内 Web アプリへのアクセス；
よく使う複数のトンネルを保存し、必要なものだけを開始；
毎回長い ssh -L コマンドを組み立て直さずに接続；
Web 用トンネルを、明示的な操作後にだけ既定ブラウザーで開く。

VPN ではなく、リモート転送 -R、SOCKS 動的転送 -D、リモートシェルは提供しません。インポーターは、外部コマンドを実行し得る ProxyCommand なども拒否します。

4 つの接続先を理解する

冒頭のコマンドは次の設定に対応します。

項目	例	意味
SSH サーバー	`ssh.example.com:33899`	TunnelDeck がログインする SSH ホストとポート
SSH ユーザー	`root`	SSH のログインアカウント
ローカル入口	`127.0.0.1:9108`	手元の PC 上でアプリが接続するアドレス
リモート転送先	`127.0.0.1:9108`	SSH サーバーから見た転送先

最後の項目が特に重要です。リモート転送先の 127.0.0.1 は、TunnelDeck を動かす PC ではなく SSH サーバー自身 を指します。サービスが SSH サーバーから到達できる別の LAN ホストにある場合は、たとえば 10.0.0.20:8080 のように、そのホストのアドレスを設定します。

ローカルアプリ
  └─ 127.0.0.1:9108
       └─ 暗号化 SSH 接続 → ssh.example.com:33899
            └─ SSH サーバーから接続 → 127.0.0.1:9108

1. デスクトップ版をインストールする

現在、プロジェクトには Apple／Windows のコード署名 ID がないため、v0.3.1 では 未署名のビルド済みデスクトップインストーラーを配布していません。インストールスクリプトが環境を確認し、固定リリースのソースを取得してローカルでビルドします。未署名バイナリのために Gatekeeper や SmartScreen を回避する必要はありません。

macOS と Linux

まず依存関係だけを確認します。

curl -fsSL https://raw.githubusercontent.com/Nciae-Zyh/TunnelDeck/v0.3.1/install.sh \
  | sh -s -- --check

出力を確認してからインストールします。

curl -fsSL https://raw.githubusercontent.com/Nciae-Zyh/TunnelDeck/v0.3.1/install.sh | sh

curl がない場合：

wget -qO- https://raw.githubusercontent.com/Nciae-Zyh/TunnelDeck/v0.3.1/install.sh | sh

Windows PowerShell

irm https://raw.githubusercontent.com/Nciae-Zyh/TunnelDeck/v0.3.1/install.ps1 | iex

インストーラーは Go 1.25+、Node.js 20+、各 OS のビルド依存関係を確認します。Go または Node.js がない場合は公式 SHA-256 を検証し、TunnelDeck 専用のユーザーディレクトリへ配置します。グローバルの PATH は変更しません。

macOS では Xcode Command Line Tools も必要で、~/Applications/TunnelDeck.app にインストール；
Linux では GTK3 と WebKitGTK 4.1 が必要で、~/.local/bin/TunnelDeck にインストール；
Windows では WebView2 が必要で、%LOCALAPPDATA%\Programs\TunnelDeck\ とスタートメニューに登録。

リモートスクリプトをシェルへ渡す前に、v0.3.1 のインストールスクリプトを確認してください。全依存関係と手動ビルド手順はソースインストールガイドにあります。

2. 既存の ssh -L コマンドをインポートする

すでに動作しているコマンドがある場合：

TunnelDeck を開き、「コマンドをインポート」を選択；
完全な ssh -L コマンドを貼り付け；
解析された SSH ホスト、ポート、ユーザー、ローカル入口、転送先を確認；
分かりやすいプロファイル名を設定；
認証方法を選び、保存して開始。

TunnelDeck は引数を解析し、Go の SSH ライブラリから直接接続します。入力を Shell コマンドへ連結して実行することはありません。監査しやすい範囲に保つため、1 つのローカル転送だけを受け付け、リモートコマンド、-R、-D、ProxyCommand は拒否します。

3. トンネルを手動で作成する

「新規」を選び、次の順に入力します。

名前：例「開発環境の管理画面」；
SSH サーバーとポート：例 ssh.example.com と 33899；
SSH ユーザー名：サーバーで許可されたアカウント；
ローカル待ち受けアドレスとポート：通常は 127.0.0.1 のまま、空いているポートを指定；
リモート転送先とポート：SSH サーバーから到達できるサービス；
認証方法：パスワードまたは SSH 秘密鍵；
「保存して開始」を選択。

既定の 127.0.0.1 では、同じ PC 上のプログラムだけがトンネルを利用できます。LAN 内の別端末にも公開する明確な理由があり、OS のファイアウォールも設定済みの場合を除き、0.0.0.0 や :: へ変更しないでください。TunnelDeck も公開リスクを警告します。

4. パスワード認証と秘密鍵認証

パスワード

SSH のログインパスワードを入力します。「認証情報を記憶」は既定のまま無効にするのが基本です。その場合、パスワードは現在の実行中だけメモリに保持され、トンネル停止時にトンネルオブジェクトから消去されます。

秘密鍵

秘密鍵ファイルを選択します。暗号化された鍵ならパスフレーズも入力します。公開鍵は、あらかじめサーバー側アカウントの authorized_keys に登録してください。

認証情報の保存を明示的に有効にした場合、TunnelDeck は OS の安全なストアを利用します。

macOS Keychain；
Windows Credential Manager；
Linux Secret Service。

通常の profiles.json にパスワード、秘密鍵の内容、鍵のパスフレーズは保存されません。それでもサーバー側では最小権限、接続元制限、鍵のローテーションを行ってください。

5. 初回接続でホスト指紋を確認する

初めて SSH サーバーへ接続すると、TunnelDeck は SHA-256 ホスト指紋を表示します。ダイアログが出たという理由だけで承認せず、サーバーコンソール、運用記録、別の信頼できる経路と照合してから「信頼して接続」を選びます。

確認した鍵は TunnelDeck 専用の known_hosts に保存されます。後からサーバー鍵が変わると、TunnelDeck は新しい鍵を暗黙に受け入れず、接続を停止します。正規のサーバー再構築でも変わることはありますが、信頼情報を更新する前に原因を確認してください。ホスト名の誤りや中間者攻撃の可能性もあります。

6. 接続後にサービスを利用する

トンネルが「実行中」になったら、クライアントをローカル入口へ向けます。

Web アプリ：http://127.0.0.1:9108 を開く；
データベース：クライアントの接続先を 127.0.0.1 と設定したローカルポートにする；
その他の TCP：各クライアントで同じローカル入口を指定。

HTTP／HTTPS の場合は「これは Web サービス」を有効にし、プロトコルを選択できます。トンネルの実行中に「Web ページを開く」ボタンが表示され、ユーザーが選択したときだけ既定ブラウザーを起動します。

アプリ起動時、トンネル開始時、自動再接続時に TunnelDeck が勝手にページを開くことはありません。転送対象の多くは HTTP ではないため、接続とブラウザー起動を分けることで、無効な URL や繰り返し開くウィンドウを防ぎます。

7. 日常管理と自動再接続

プロファイル一覧には状態とアクティブ接続数が表示されます。開始、停止、編集、削除を必要に応じて行えます。実行中の設定を変更するときは古いトンネルを停止してから反映し、古いリスナーを新設定と取り違えないようにします。

TunnelDeck は SSH keepalive を送り、一時的な切断には 2〜30 秒の指数バックオフで再接続します。再接続はトンネルを復元するだけで、ブラウザーは開きません。

トラブルシューティング

ローカルポートを開けない

別プロセスが使用している可能性があります。ローカルポートを変更するか、使用中のプロセスを確認します。

lsof -nP -iTCP:9108 -sTCP:LISTEN

SSH サーバーへ到達できない

ホスト名、SSH ポート、ユーザー名、ファイアウォール、現在のネットワークから接続が許可されているかを確認します。同じ非機密パラメーターでターミナルから接続すると切り分けに役立ちますが、パスワードをコマンドやスクリーンショットへ入れないでください。

トンネルは動くが転送先が応答しない

SSH サーバーの視点で転送先を確認します。127.0.0.1 を指定したなら、サービスは SSH サーバー自身で動いている必要があります。対象ポートで実際に待ち受けているか、SSH ホストからの接続を許可しているかも確認します。

秘密鍵が使えない

.pub ではなく秘密鍵を選んだか、鍵形式が対応しているか、暗号化鍵のパスフレーズが正しいかを確認します。秘密鍵は現在の OS ユーザーだけが読める権限にしてください。

ホスト鍵変更の警告が出る

接続を止め、サーバーが再構築されたか、ホスト名の向き先が変わったかを確認します。信頼できる経路で新しい指紋を照合した場合だけ登録を更新してください。警告を消すためだけに検証を無効化してはいけません。

デスクトップ版が軽量な理由

TunnelDeck は Go、Wails、Vue 3 で構築されています。Chromium 一式を同梱せず OS の WebView を利用し、トンネルは golang.org/x/crypto/ssh から直接確立します。現在の macOS ARM64 アプリバンドルは約 8.7 MB です。

MIT License のオープンソースで、ソース、インストーラー、リリース履歴は TunnelDeck GitHub リポジトリから確認できます。現在の安定版ソースは v0.3.1です。

Chrome ウェブストア版を公開しました

TunnelDeck Chrome サイドパネル拡張 v0.3.1は Chrome ウェブストアで一般公開され、ストアから直接インストールできるようになりました。ソースコード、デスクトップ版のインストールスクリプト、問題報告は引き続き TunnelDeck GitHub リポジトリで管理しています。

次の順序でインストールしてください。

この記事の第 1 節または GitHub README に従って TunnelDeck デスクトップ版をインストール；
Chrome ウェブストアから拡張機能をインストール；
デスクトップ版を起動し、「Chrome ブラウザー統合」で正式な拡張 ID jnfkjehpbkmfnidfcilehhkpbjjinmod を確認；
未登録と表示された場合は「Chrome サービスを登録」を選び、拡張機能を再読み込み；
Chrome ツールバーの TunnelDeck アイコンからサイドパネルを開いて接続を管理。

拡張機能は Native Messaging を通じて同じ PC の TunnelDeck を操作します。接続の作成、編集、インポート、開始、停止に対応し、Web サービスとして指定した接続もユーザーが操作したときだけ開きます。ブラウザープロセス内で SSH を確立するものではなく、ストア拡張は操作を便利にし、実際の SSH トンネルはデスクトップ版が実行します。

コメント