Elastic Compute Service:ワークベンチ CLI による ECS インスタンスの管理

前提条件

• お使いのコンピューターに Workbench CLI をインストールし、認証情報と最小限の RAM 権限を設定しておく必要があります。 詳細については、「Workbench CLI のインストールと認証情報の設定」をご参照ください。

• ターゲットの ECS インスタンスは実行中の Linux インスタンス であり、 Cloud Assistant エージェント がインストールされて実行中である必要があります。

• お使いのコンピューターから *.aliyuncs.com および Workbench バックエンドの WebSocket エンドポイントにアクセスできる必要があります。 upload および download コマンドでは、インスタンスが対応するリージョンの OSS 内部エンドポイントにアクセスできることも必要です。

グローバルパラメーター

以下の 3 つのグローバルパラメーターは、すべての workbench サブコマンドに適用されます。

リージョンは、インスタンス ID プレフィックスのマッピング → デーモン内のアクティブセッションのルックアップ → --region を手動で指定するように求めるエラーの順序で推定されます。インスタンスを初めて使用する場合、最初に workbench list ecs -r <region> を実行してインスタンス ID を確認することをお勧めします。

インスタンスリストの照会 (workbench list ecs)

このコマンドを使用すると、リージョン、ステータス、タグなどの条件で ECS インスタンスを照会し、対象のインスタンス ID をすばやく特定できます。 デフォルトで、workbench list は workbench list ecs と同等です。 一般的な使用例:

# 指定したリージョン内のすべてのインスタンスを照会
workbench list ecs -r cn-hangzhou

# 実行中のインスタンスのみを照会
workbench list ecs -r cn-hangzhou --status Running

# タグでフィルタリング (複数の --tag オプションは AND 条件として扱われます)
workbench list ecs -r cn-hangzhou --tag env=prod --tag app=web

# インスタンスタイプ、名前、VPC、その他の条件でフィルタリング
workbench list ecs -r cn-hangzhou --instance-type ecs.g7.large --instance-name "web-*"

# スクリプトや AI エージェントで利用するために JSON フォーマットで出力
workbench list ecs -r cn-hangzhou --output json

パラメーター：

--output json の出力構造は次のとおりです：

{
  "instances": [
    {
      "instance_id": "i-bp1xxxxx",
      "instance_name": "web-prod-01",
      "instance_type": "ecs.g7.large",
      "region_id": "cn-hangzhou",
      "status": "Running",
      "private_ip": "172.16.0.10",
      "public_ip": "",
      "os_type": "linux",
      "image_id": "aliyun_3_x64_20G_alibase_20230727.vhd",
      "tags": {"env": "prod"}
    }
  ]
}

対話型接続 (workbench connect)

workbench connect は対話型の PTY セッションを開始します。これは Workbench CLI の主要なコマンドです。一般的な例は次のとおりです。

# デフォルトは認証なし (Workbench のパスワードレスログイン)
workbench connect -i i-bp1a2b3c4d5e6f

# パスワード認証 (パスワードを対話形式で入力します。入力内容は表示されません)
workbench connect -i i-bp1a2b3c4d5e6f --auth-type password

# 公開鍵認証 (キーファイルのパスを対話形式で入力します。例: ~/.ssh/id_rsa)
workbench connect -i i-bp1a2b3c4d5e6f --auth-type certificate

# ログインユーザーとポートを指定
workbench connect -i i-bp1a2b3c4d5e6f -u admin -p 2222

# 新しいセッションを強制 (既存のセッションを再利用しない)
workbench connect -i i-bp1a2b3c4d5e6f --new

パラメーター：

Agent> Show the processes with the highest CPU usage
  ┌─ Running command ──────────
  │ ps aux --sort=-%cpu | head -10
  └────────────────────────
  Waiting for confirmation (Y/n): y
  [Executed]
  ... (エージェントが分析を継続し、結論を提示します)

リモートコマンド実行 (workbench exec)

workbench exec は、インスタンス上で単一のコマンドを実行し、結果を返します。connect の永続的なシェルとは異なり、exec の呼び出しは、毎回独立した環境で実行されます。同一インスタンスに複数回呼び出しても、基盤となる接続チャネルが再利用されるため、接続のセットアップを繰り返す必要はありません。一般的な例：

# コマンドを実行します
workbench exec -i i-bp1a2b3c4d5e6f -c "df -h"

# コマンドを組み合わせます：cd + 環境変数 + 実行
workbench exec -i i-bp1a2b3c4d5e6f -c "cd /opt/app && ./deploy.sh"

# タイムアウトを設定します
workbench exec -i i-bp1a2b3c4d5e6f -c "sleep 30" --timeout 10

# スクリプトや AI エージェント向けの JSON 出力
workbench exec -i i-bp1a2b3c4d5e6f -c "df -h" --output json

パラメーター：

--output json の戻り値の構造は次のとおりです：

{
  "output": "Filesystem ...\n",
  "stderr": "",
  "exit_code": 0
}

この構造では、output はコマンドの標準出力、stderr は標準エラー、exit_code はリモートコマンドの終了コード (整数) です。

ファイル転送 (workbench upload / download)

パブリック IP アドレスや SCP チャネルがない場合は、workbench upload / workbench download を使用してファイルを転送します。アップロード時には、リアルタイムのプログレスバーが表示されます。

アップロード例：

workbench upload ./app.jar /opt/app/app.jar -i i-bp1a2b3c4d5e6f

ダウンロード例：

# カレントディレクトリにダウンロード
workbench download /var/log/app.log ./ -i i-bp1a2b3c4d5e6f

# ダウンロードして名前を変更
workbench download /var/log/app.log ./local-copy.log -i i-bp1a2b3c4d5e6f

パラメーター：

セッション管理 (workbench session)

一般的なコマンド：

# すべてのアクティブセッションを表示します
workbench session list
workbench session list --output json

# 指定したセッションを閉じます
workbench session close <session-id>

# すべてのセッションを閉じます
workbench session close --all

セッションの状態遷移：

• OPEN：セッションが確立され、正常に読み書きできます。

• RECONNECTING：基盤となる WebSocket が切断され、再接続中です。

• BROKEN：再接続に失敗し、セッションは利用できません。

• CLOSED：セッションは閉じられています (ユーザーが閉じた、タイムアウトした、または TTL 制限に達した場合)。

同じインスタンスに対する複数のconnect、exec、upload、download 操作は同じセッションを共有します。これはデーモンが透過的に処理するため、セッション ID を意識する必要はありません。一度に同じセッションにアタッチできるターミナル (TTY) は 1 つだけです。ターミナルがすでにアタッチされている場合は、--new を使用して新しいセッションを作成するか、先に既存の接続を閉じる必要があります。

デーモン管理 (workbench daemon)

Workbench CLI では、ユーザー空間のバックグラウンドデーモンが WebSocket 接続を保持し、セッションを多重化します。デーモンのライフサイクルは完全に自動化されており、通常、手動での管理は不要です。

# デーモンのステータスを表示
workbench daemon status

# デーモンを停止 (すべてのセッションを閉じる)
workbench daemon stop

• 自動起動：デーモンは、いずれかの workbench コマンドを初めて実行したときに自動的に起動されます。

• 自動終了：デーモンは、最後のセッションが閉じてから 60 秒後に自動的に終了します。

• 単一インスタンス：デーモンインスタンスは、オペレーティングシステムユーザーごとに 1 つのみ許可されます (PID ファイルロックによって強制されます)。

• IPC チャネル：CLI とデーモンは、JSON-RPC プロトコルを使用して、~/.workbench/run/daemon.sock (UNIX ソケット) を介して通信します。

一般的なシナリオ

workbench upload ./app-2.0.tar.gz /opt/deploy/ -i i-bp1a2b3c4d5e6f
workbench exec -i i-bp1a2b3c4d5e6f -c "cd /opt/deploy && tar xzf app-2.0.tar.gz && ./deploy.sh"
workbench exec -i i-bp1a2b3c4d5e6f -c "curl -s http://localhost:8080/health"

workbench exec -i i-bp1a2b3c4d5e6f -c "df -h && free -m" --output json | jq '.output'
workbench exec -i i-bp1a2b3c4d5e6f -c "systemctl status nginx" --output json | jq '.exit_code'

workbench connect -i i-bp1a2b3c4d5e6f
# セッション内で tail -f または長時間実行タスクを実行
# その後 /detach を入力してデタッチ

# 後で元のセッションに再アタッチ
workbench connect -i i-bp1a2b3c4d5e6f

終了コード

workbench exec はリモートコマンドの終了コードをそのまま返します。CLI も同じ終了コードで終了します (SSH の動作と一致)。したがって、スクリプトは workbench exec の終了コードから直接、リモートコマンドが成功したかどうかを判断できます。

たとえば、次のコマンドはインスタンス上で exit 42 を実行し、CLI も 42 で終了します：

workbench exec -i i-bp1a2b3c4d5e6f -c "exit 42"
echo $?   # 42 が出力されます

パラメーター、認証、ネットワーク、または存在しないインスタンスなどの理由でコマンドが失敗した場合、--output json を使用すると、エラー詳細が次のフォーマットで出力されます：

{
  "code": 1,
  "message": "session resolve: login instance: ... InvalidParameter.InstanceId ..."
}

この構造では、code はゼロ以外のエラー識別子、message は判読可能なエラーの説明 (通常、基盤となる API のエラーコードと RequestId が含まれます) です。これらを使用して問題を特定できます。

トラブルシューティング

一般的な症状と最初の対応：

デバッグコマンド：

# デーモンのステータスを表示
workbench daemon status

# スクリプトによる解析を容易にする JSON エラー出力
workbench exec -i i-bp1a2b3c4d5e6f -c "echo test" --output json

デーモンログは ~/.workbench/log/daemon.log に保存されます。

参考資料

• Workbench CLI を使用したインスタンスへの接続：親トピックであり、ツールの位置付けとクイックスタートについて説明します。

• Workbench CLI のインストールと認証情報の設定： CLI のインストール、および認証情報と権限の設定。

• AI エージェントで Workbench CLI を使用した ECS インスタンスの操作： Wukong または opencode で、エージェントに Workbench コマンドを呼び出させます。

• Cloud Assistant エージェントのインストール： Workbench CLI は Cloud Assistant エージェントに依存します。