feat: initial public release (MAESTRO)
This commit is contained in:
oss-sync
@@ -0,0 +1,86 @@
|
||||
---
|
||||
id: ssh
|
||||
title: SSH リモート操作
|
||||
category: advanced
|
||||
order: 140
|
||||
keywords: [SSH, リモート, exec, アップロード, コンソール, PTY, デプロイ]
|
||||
---
|
||||
|
||||
## SSH でできること
|
||||
|
||||
MAESTRO は、エージェントが SSH 経由でリモートホストを操作するための 2 つの仕組みを持ちます。どちらも admin が有効化し、接続を登録してから使います。
|
||||
|
||||
| 仕組み | 用途 | 対応 piece |
|
||||
|---|---|---|
|
||||
| ssh-ops | 単発コマンド実行・ファイル転送 (health check / config push / log fetch) | `ssh-ops` |
|
||||
| ssh-console | 対話的な PTY シェル (vim / tmux / tail など長時間作業) | `ssh-console` |
|
||||
|
||||
いずれもデフォルトでは無効です。admin が `config.yaml` で有効化し (`ssh.enabled: true`、コンソールは加えて `ssh.console.enabled: true`)、SSH 接続を登録したうえでジョブの所有者に grant を付与する必要があります。詳しくは [管理者ガイド](./19-admin.md) を参照してください。
|
||||
|
||||
## ssh-ops: 単発実行とファイル転送
|
||||
|
||||
`ssh-ops` piece は次の 3 軸をカバーする ops 向け piece です。
|
||||
|
||||
- Health check: `uptime` / `df -h` / `free -m` / プロセス状態 / `journalctl` などで状態を確認
|
||||
- Config push: ローカルで作った設定を `SshUpload` で配信し、`SshExec` でリロード
|
||||
- Log fetch: `SshDownload` でリモートのログを取得し、ローカルで grep / 集計 / 分析
|
||||
|
||||
使うツール: `SshExec`(単発コマンド) / `SshUpload` / `SshDownload` / `SshListConnections`。結果は `output/report.md` にまとめられます。機密値はコマンド文字列に直接書かず、レポートにも記録しません。
|
||||
|
||||
リモートへの書き込みは接続ごとの `remote_path_prefix` 配下に限られ、違反は `path_not_allowed` で拒否されます。出力が大きすぎてコマンド結果が `truncated` になる場合は、`SshDownload` でファイル経由に切り替えます。
|
||||
|
||||
## ssh-console: 対話的な PTY シェル
|
||||
|
||||
`ssh-console` piece は、AI と人間が共有する 1 つの PTY セッションをタスクに開きます。両者がコマンドを打ち、同じ画面出力を見られます。次のようなケースに向きます。
|
||||
|
||||
- ログを tail しながらの作業
|
||||
- vim / top / less / tmux など TUI が必要な操作
|
||||
- 複数ラウンドにわたる対話的な調査
|
||||
|
||||
使うツール (3 つ):
|
||||
|
||||
- `SshConsoleEnsure` — セッションを開く (冪等)
|
||||
- `SshConsoleSend` — キー入力を送る (`\n` 改行、`\x03` Ctrl-C などの制御文字も送れる)
|
||||
- `SshConsoleSnapshot` — 現在の画面 / scrollback を取得
|
||||
|
||||
ファイル転送 (`SshUpload` / `SshDownload`) は SFTP 経路で動き、PTY セッションとは独立しています。設定を置いてからコンソールでリロードコマンドを送る、といった組み合わせが可能です。
|
||||
|
||||
コンソールはアイドルや最大時間で自動クローズされます (既定でアイドル 30 分、最大 4 時間)。
|
||||
|
||||
### コンソールを開く・見る
|
||||
|
||||
`ssh-console` piece でタスクを実行すると、エージェントがコンソールセッションを開きます。アクティブなセッションがある間、タスク詳細に「SSH」タブが現れ、ここでターミナル画面をリアルタイムに見て、人間が直接コマンドを打つこともできます。タスク詳細での見方・介入は [実行中のタスクを見る・介入する](./03-running.md) を参照してください。
|
||||
|
||||
## SSH 接続プロファイルを登録する
|
||||
|
||||
接続は TopBar → ユーザーフォルダ → SSH 接続 から登録します。
|
||||
|
||||
1. 「+ 新規作成」で接続を作成 (label / host / user など)
|
||||
2. 鍵の公開鍵をリモートの `authorized_keys` に登録
|
||||
3. 「Test」を押してホストキーを検証する (TOFU: 初回接続で見たキーを記録)
|
||||
|
||||
ホストキー検証 (TOFU) を済ませないと、エージェント側は `host_key_not_verified` で停止します。検証後にキーが変わっていた場合は `host_key_mismatch` となり、MITM の疑いとして自動リトライせず中断します。
|
||||
|
||||
接続には個人接続と、admin が登録する全体接続があります。全体接続を使うには admin の grant が必要です。
|
||||
|
||||
## どう動かすか
|
||||
|
||||
1. admin が SSH を有効化し、接続と grant を整える
|
||||
2. ユーザーが該当接続を登録 (個人接続の場合) して Test でホストキーを検証
|
||||
3. `ssh-ops` または `ssh-console` を使うタスクを作成して実行
|
||||
4. ssh-console の場合はタスク詳細の SSH タブで画面を確認・操作
|
||||
|
||||
Piece の選び方や `allowed_tools` の考え方は [piece を使う・作る](./05-pieces.md) を参照してください。
|
||||
|
||||
## よくあるエラー
|
||||
|
||||
| エラーコード | 意味 | 対処 |
|
||||
|---|---|---|
|
||||
| `host_key_not_verified` | TOFU 未完了 | UI の Test で検証 |
|
||||
| `host_key_mismatch` | ホストキー不一致 (MITM 疑い) | 自動リトライしない。管理者に確認 |
|
||||
| `command_rejected` | allow/deny リストで拒否 | admin に許可パターン追加を相談 (ローカル回避しない) |
|
||||
| `path_not_allowed` | `remote_path_prefix` 外への書き込み | 許可パス内に変更 |
|
||||
| `no_grant` / `access_denied` | 権限不足 | admin に grant 追加を依頼 |
|
||||
| `abuse_locked` | 連続失敗でロック | admin に force-unlock を依頼 |
|
||||
|
||||
詳しい運用手順は `docs/ssh.md` を参照してください。
|
||||
Reference in New Issue
Block a user