トンネル運用

本記事では、パネルの「トンネル運用」——グローバル IP を持たないサーバーをパネルに接続する機能——について説明します。

ひとことで理解

グローバル IP を持たないデバイス（社内マシン、NAT 配下のデバイス、Android スマートフォン）には、外部から「能動的に接続しに行く」ことができません。トンネル運用は、これらのデバイスから能動的に「外へ接続」させてパネルサーバーにつなげ、その後は通常のサーバーと同じように操作できるようにします。

機能概要

グローバルから到達可能なアドレスをまったく持たないデバイス（社内マシン、NAT 配下のデバイス、Android スマートフォンなど）は、直接 SSH 接続できません。トンネル運用はリバーストンネルを通じて、これらのデバイスから能動的にパネルサーバーへ接続させ、その後は通常のサーバーと同じように操作できるようにします。

原理

パネルサーバー（グローバル IP あり）がトンネルサービスを実行する
対象デバイスに軽量な Agent をインストールし、能動的に「発信」してパネルサーバーへ接続する
接続が確立すると、パネルはこのトンネルを通じて対象デバイスへ逆方向に SSH できる

> 分かりやすく言うと：対象デバイスがパネルサーバーへ「自分から電話をかける」ようなもので、通話がつながればパネルはこの「専用回線」を通じて逆にそれを制御できます。

適用シーン

家庭内の社内デバイス（Raspberry Pi、NAS、ソフトウェアルーター）を管理する
グローバル IP を持たない安価な VPS（NAT サーバー）を管理する
Android スマートフォン（Termux 環境）を管理する

使い方（3 ステップ）

1. 「トンネル運用」を開き、「ワンクリックインストールスクリプト」をクリックして独立したコマンドを生成します

2. そのコマンドを対象デバイスに貼り付けて一度実行します（Agent の自動インストール + 起動時の自動開始を設定）

3. 約 10 秒後、パネルにそのデバイスが自動的に表示され、SSH 接続してすべての機能を利用できます

> インストールコマンドは意図的に短くしています。まだインストールが済んでいない状態で手入力しやすいようにするためです：

> - Linux（curl）：curl -sSL http://server:5501/i/<token> | sudo bash

> - Termux：curl -sSL http://server:5501/t/<token> | bash

> - すでに root の場合は sudo を外せます；Alpine は wget -qO- … | sudo bash、BSD は fetch -o - … | sudo bash を使います

> インストール先：Linux はデフォルトで /opt/sshe-agent（/opt が存在しない、または書き込み不可の場合はスクリプトが自動的に ~/sshe-agent にフォールバックし、エラーにはなりません）；Termux は ~/sshe-agent（Termux の起動に追従）を使用します。

> パスワードなし接続：インストール後、パネルは事前に注入した鍵でそのデバイスにパスワードなしで接続でき、毎回パスワードを入力する必要はありません。

Agent が対応する環境

環境	インストール方法
Linux（apt/yum/dnf/apk）	ワンクリックスクリプト、依存関係の自動インストール + systemd による自動起動
Android / Termux	専用スクリプト（Agent の自動インストール + Termux の起動に追従）

> ⚠️ macOS は未対応：macOS はバージョンごとに SSH 認証の差異が大きく、バージョンをまたいだ安定した接続を保証できないため、本バージョンでは macOS のトンネル接続を提供していません。トンネル運用には Linux / Termux デバイスをご利用ください。

Agent のオンライン状態

オンライン：トンネル接続が正常で、いつでも操作できます
オフライン：デバイスが切断（電源オフ、ネットワーク断、Agent 停止）。オフラインの記録は一定期間保持され、再接続後に自動的にオンラインへ復帰します

> 📌 サーバーカードの判定：トンネルデバイスの「オンライン/オフライン」は Agent のハートビートによって決まります。Agent がオンラインになると、トンネルを通じて動的に SSH チャネルを確立し、実際のヘルスデータ（負荷/メモリ/ディスク/稼働時間/バッテリー/温度）を収集して、通常のサーバーと同様に扱います。

注意事項

1. Agent は、パネルが対象デバイスにインストールする唯一のプログラムです（「ゼロフットプリント」の理念の例外）。グローバル IP を持たないデバイスは能動的に接続できないため、デバイス側から能動的に接続してもらうしかありません。

2. Agent が消費するリソースはごくわずかです（Python プロセス 1 つ + 長い接続 1 本）。

3. Agent は暗号化トンネルで通信するため、通信は安全です。

4. デバイスの IP が変わった、または Agent が無効になった場合は、インストールスクリプトをもう一度実行すれば復旧します。

ポートトンネリングとの関係

トンネル運用は「デバイスをパネルに接続する」役割を担い、ポートトンネリングは「デバイス上のアプリケーションポートをグローバルに公開する」役割を担います。両者を組み合わせて使い、まずトンネル運用でグローバル IP のないデバイスを接続し、次にポートトンネリングでそのアプリ（Navidrome、Nextcloud など）をパネルサーバーのグローバルポートにマッピングします。

ドキュメント