SSH Operator
SSH/SFTP経由でリモートLinuxサーバーを操作し、アプリケーションのデプロイ、Dockerコンテナの管理、ランタイム状態の検査を行います。複数ファイル/複数フォルダのプロジェクトをサポートし、宝塔パネル環境に最適化されています。
呼び出すタイミング
- ユーザーがコードをサーバーにデプロイ、公開、リリースするよう依頼した場合。
- ユーザーがリモートサービスの再起動、再構築、更新を依頼した場合。
- ユーザーがファイルまたはフォルダ全体をリモートホストにアップロードするよう依頼した場合。
- ユーザーがリモートログの表示やサービスの状態確認を依頼した場合。
- ユーザーがリモートサーバーでコマンドの実行や問題の診断を依頼した場合。
- ユーザーがリモートのウェブサイト/ブログのソースファイルの編集を依頼した場合。
- ユーザーがブログ記事の公開またはブログプラットフォームの公開APIの検出を依頼した場合。
- ユーザーが宝塔パネル、
/www/wwwroot/、または中国のクラウドVPSホスティングについて言及した場合。
機能
- SSH（パスワードまたはキーベースの認証）でリモートホストに接続。
- SFTP経由でファイルのアップロード/ダウンロードおよびフォルダの再帰的アップロード。
- シェルコマンドの実行と出力のストリーミング。
- Dockerおよびdocker-composeワークロードの管理。
- サービスの健全性、ログ、ディスク使用量、プロセス状態の検査。
- デプロイした変更が有効であることを検証（チェックサム、プロセス再起動、HTTPヘルスチェック）。
- 宝塔パネルのディレクトリ構成とNginxリバースプロキシ設定にコマンドを適応。
- SSH経由でリモートのウェブサイト/ブログソースファイルを直接編集。
- ブログ公開API（WordPress、Ghost、Halo）を検出し、Pythonスクリプト経由でMarkdown記事を公開。
必要な入力
アクションを実行する前に、ユーザーまたは環境から以下の情報を収集します。
HOST— サーバーIPまたはホスト名。PORT— SSHポート（デフォルト22）。USER— SSHユーザー名。AUTH— パスワードまたは秘密鍵のパス。鍵を推奨します。機密情報をコミットされたファイルにハードコードしないでください。REMOTE_ROOT— サーバー上のベースプロジェクトパス（例:/www/wwwroot/ai-interviewer）。FILES_TO_UPLOAD—local_path -> remote_relative_pathペアのリスト。フォルダ全体を含みます。COMMANDS— 実行するデプロイまたは診断コマンド。
複数ファイル / 複数フォルダのデプロイ
ほとんどの実際のプロジェクトは単一ファイルではありません。以下のいずれかのアプローチを使用します。
オプション 1: 提供されたスクリプトテンプレートを使用
scripts/deploy-folder.py をプロジェクトリポジトリにコピーし、FILES_TO_UPLOAD リストを設定して実行します。このスクリプトはフォルダの再帰的アップロードを処理し、相対パスを保持します。
Unix系のローカル環境では、scripts/deploy-rsync.sh が、適切な除外ルールを備えたインクリメンタルなrsyncベースの代替手段を提供します。
オプション 2: エージェント駆動のSFTP
エージェントがSFTP/SSHツールを利用できる場合:
- SSHセッションを確立します。
- 変更された各フォルダについて、その内容を走査し、ファイルを個別にアップロードしてリモートディレクトリツリーを再作成します。
- 変更された各ファイルについて、対応するリモートの相対パスにアップロードします。
- デプロイコマンドを実行し、検証します。
オプション 3: ワンショットtarball
大規模プロジェクトの場合は、ローカルでパックしてリモートで展開する方が適しています。
# ローカル
tar czf deploy.tar.gz backend/app frontend/.next docker-compose.yml .env.production
scp deploy.tar.gz user@host:/tmp/
# リモート
ssh user@host "cd /www/wwwroot/project && tar xzf /tmp/deploy.tar.gz && docker-compose up -d --build"
スクリプトライブラリ
すぐに使える自動化スクリプトです。Pythonスクリプトは scripts/_ssh.py を接続/設定読み込みに使用し、.env ファイル（.env.example 参照）から資格情報を読み取ります。スクリプトを _ssh.py と一緒にプロジェクトにコピーしてください。
| スクリプト | 目的 |
|---|---|
scripts/_ssh.py | 共有ヘルパー: .env 設定を読み込み、SSH/SFTP接続を開く。 |
scripts/deploy-folder.py | ファイルとフォルダを再帰的にSFTPアップロードし、デプロイ後コマンドを実行。 |
scripts/deploy-rsync.sh | 一般的な除外ルール付きのインクリメンタルrsyncデプロイ。 |
scripts/blog_api_probe.py | 一般的なブログ公開API（WordPress、Ghost、Halo）を検出。 |
scripts/publish_post.py | MarkdownファイルをREST API経由でWordPressまたはGhostに公開。 |
scripts/backup_before_deploy.py | デプロイ前にコード、Nginx設定、Dockerボリューム、SQLiteをバックアップ。 |
scripts/server_health.py | CPU、メモリ、ディスク、Docker、Nginx、HTTPの健全性ステータスを収集。 |
scripts/log_collector.py | Docker、Nginx、宝塔のログを分析用にローカルファイルにプル。 |
scripts/nginx_manager.py | 宝塔のNginxサイト設定を読み取り/バックアップ/編集し、安全にリロード。 |
scripts/bt_panel.py | 宝塔のインストール、パネル情報の表示、Nginxのリロード、SSH経由でのDockerステータスの確認。 |
Pythonの依存関係は requirements.txt にリストされています。
標準デプロイワークフロー
- SSHセッションを確立 — 提供された認証情報と適切なタイムアウト（20秒以上）を使用します。
- 変更前にバックアップ —
scripts/backup_before_deploy.pyまたは同等のものを実行します。 REMOTE_ROOTが存在することを確認（mkdir -p）。- ファイル/フォルダをアップロード —
REMOTE_ROOT下の相対パスを保持します。 - コマンドを順番に実行 — 依存するコマンドは
&&で連結することを推奨します。 - サービスが起動するのを待つ（
sleep+docker-compose psまたはヘルスエンドポイントを使用）。 - 新しいコードが有効であることを確認（コンテナ内でgrep、
/healthにアクセス、ログを確認）。 - 結果を簡潔に報告 — 何が変更されたか、サービスが正常かどうか、エラーがあれば報告します。
一般的なコマンドパターン
# サービスの停止、再構築、再起動
cd ${REMOTE_ROOT} && docker-compose stop backend \
&& docker-compose rm -f backend \
&& docker-compose build backend \
&& docker-compose up -d backend
# サービスの状態確認
cd ${REMOTE_ROOT} && docker-compose ps
# 最近のログを表示
cd ${REMOTE_ROOT} && docker-compose logs --tail=50 backend
# 実行中のコンテナ内でコードを確認
docker exec ${CONTAINER_NAME} grep -n "await db.flush()" app/api/v1/interview.py
# ディスククリーンアップ
docker system prune -a -f
宝塔パネル適応
完全な運用ガイドについては references/baota.md を、bt CLIのチートシートについては references/bt-commands.md を参照してください。重要なポイントは以下の通りです。
- 公式サイト: https://www.bt.cn; インストールスクリプト: https://www.bt.cn/new/download.html。
- デフォルトのプロジェクトルート:
/www/wwwroot/<site-name>。 scripts/bt_panel.pyを使用して、宝塔のインストール、パネル情報の表示、SSH経由でのNginxのリロードを行います。- プロジェクトディレクトリ内でDocker Composeを使用し、CLIまたは宝塔Dockerプラグインを介してコンテナを管理します。
- Node/Pythonフロントエンドの場合は、宝塔サイトを追加し、
scripts/nginx_manager.pyを使用して127.0.0.1:3000へのNginxリバースプロキシロケーションを追加します。 /api/ルートをバックエンドコンテナ（例:127.0.0.1:8000）にルーティングします。- 宝塔ファイアウォールとクラウドプロバイダーのセキュリティグループの両方でポートを開放します。
- 高番号ポートをインターネットに直接公開せず、80/443でNginxを使用します。
問題が発生した場合は、references/troubleshooting.md を参照してください。
安全ルール
- 機密情報をコミットしないでください。
PASSや鍵のパスは、環境変数、gitから除外された.envファイル、またはシークレットマネージャーに保存します。 - 明示的なファイルリストを優先 し、幅広いアップロードによって予期しないファイルが上書きされるのを防ぎます。
- 診断時は非破壊的なチェックを最初に実行（ログ、ps、df）してからサービスを再起動します。
git push --forceや破壊的なrm -rfは避ける — ユーザーが明示的に要求した場合を除きます。- リスクの高いアクション（データベースマイグレーション、サービス全体の再起動、破壊的な削除）については、可能な限りユーザーに確認します。
- 一時ファイルをクリーンアップ（例: デプロイ後の
/tmp/deploy.tar.gz）。
クロスプラットフォームの注意点
- このスキルは、リモートホストがLinuxであり、ローカル環境にSSHクライアントまたは
paramikoなどのPythonライブラリがあることを前提としています。 - Windowsローカルホストでは、パスの正規化が必要になる場合があります。リモートパスは常にコマンド内で引用符で囲みます。
- 直接SSHツールを持たないエージェントの場合、以下にフォールバックします: (1) ユーザーが実行するデプロイスクリプトを生成する、(2) プラットフォームが提供するターミナル/リモート実行ツールを使用する。
- Claude Code、Codex、TRAE、Cursor間での最大限の移植性のために、メインの
SKILL.mdは500行未満に保ち、詳細なリファレンスはreferences/に移動します。
例
ユーザー: 「最新のバックエンド修正を私の宝塔サーバーにデプロイしてください。」
エージェント:
HOST、PORT、USER、認証情報、REMOTE_ROOTを尋ねるかロードします。- どのファイルが変更されたかを尋ねるか、最近の編集から推測します。
- 変更されたファイル/フォルダを
REMOTE_ROOT下のリモートパスにアップロードします。 - 影響を受けるDockerサービスを再構築して再起動します。
docker-compose psを確認し、ログの末尾を表示して健全性を確認します。- アップロードとサービスの状態に関する簡単なサマリーで応答します。