使用方法

この手順はオペレーター向けです。CLI とデバイス側プログラムを用意し、ログインしてデバイスを追加し、接続したデバイスでリモートコマンドを実行してシェルを開きます。ブラウザーコンソール、モバイルコンソール、Android デバイス側アプリ、ペアリング、自己更新については末尾のリンクを参照してください。それぞれのページの手順はここでは繰り返しません。

例のアドレスとトークンは自分のものに置き換えてください。トークンは作成時に一度しか表示されません。リポジトリには保存しないでください。

名前付き ID とアカウント権限。 グローバルな --profile <name> は REMOTE_CLI_PROFILE より優先されます。config.toml、暗号化 ID の秘密鍵、ルートの信頼、grant キャッシュは <config_base>/remote-cli/profiles/<name>/ に保存されます。config_base は従来の XDG_CONFIG_HOME、HOME/.config、Windows APPDATA です。名前は ASCII 英数字、点、ハイフン、下線の 1〜64 文字で、. と .. は使用できません。名前付き profile は REMOTE_CLI_CONFIG より優先されます。profile 未指定時は従来のパスと REMOTE_CLI_CONFIG の動作を維持します。profile ごとにログインし、以降も同じ profile を選択してください。

operator set はアカウント ID または一意の名前を受け取り、デバイス引数はデバイス ID です。--restricted は明示的に許可されたデバイスのみを表示し、--unrestricted はロールに基づく範囲に戻します。範囲変更は最高管理者のみ可能です。ロールと権限は最高管理者が管理し、最高管理者がいない場合は管理者が許可範囲内で管理できます。自身の変更は不可です。operator grant list は呼び出し元が閲覧できる権限のみ返します。データベースのデバイス権限と署名付き grant は別の検査であり、変更しても seal approve の代わりにはなりません。作成 API は範囲の原子的な設定をサポートしません。operator add の一度限りのトークンを保存してから、別リクエストで operator set / operator grant set を実行してください。

remote-cli --profile alice login --server https://exchange.example.com
remote-cli --profile root operator set alice --restricted
remote-cli --profile root operator set alice --role readonly
remote-cli --profile root operator grant list --operator alice -o json
remote-cli --profile root operator grant set alice lab --view
remote-cli --profile root operator grant set alice lab --manage
remote-cli --profile root operator grant remove alice lab
remote-cli --profile root operator set alice --unrestricted
remote-cli --profile root operator --json '{"op":"grant_set","operator":"alice","device":"lab","can_manage":false}' -o json

XML リクエストと出力

インストール済みバージョンの対応オプションを remote-cli --help で確認してください。--xml と --xml-file は既存の --json / --json-file リクエストに XML 入力を追加します。4 つの入力指定は排他的で、リクエスト本体全体を渡します。同じコマンドのオプションやサブコマンドと併用しないでください。デバイス位置引数の規則は変わりません。入力と出力は独立し、-o text|json|xml の既定はテキストです。

remote-cli device --xml '<request><op>list</op></request>' -o xml
remote-cli exec my-device --xml-file request.xml -o xml

子要素がなければ文字列、あればオブジェクトが既定です。数値、真偽値、配列、null にはそれぞれ type="number"、type="boolean"、type="array"、type="null" を指定します。配列の子要素は <item>、空オブジェクトは type="object" を使います。任意のキーには <field name="arbitrary key">value</field>、空リクエストには <request type="object"/> を使います。

<request>
  <command>echo hello</command>
  <timeout_secs type="number">30</timeout_secs>
  <hold type="boolean">false</hold>
  <env><GREETING>hello &amp; welcome</GREETING></env>
</request>

出力ルートは <response type="...">、オブジェクトのメンバーは <field name="..." type="...">、配列の要素は <item type="..."> です。型を明示し、テキストを XML 1.0 に従ってエスケープします。実行時エラーは ok=false / error と非ゼロ終了コードを返します。コマンドラインの構文エラーは引き続き stderr に出力します。

XML 出力は device list/update, operator list/add/set/grant, exec, session list/kill, ui, ubus, sensors, net, metrics, preset, audit, browser と exec ジョブ操作に対応します。その他のコマンドは -o xml を明示的に拒否しますが、XML 入力と既存の出力形式は使用できます。

ストリーム exec / sensors --live / browser session は 1 行につき独立した XML 文書を出力するため、行単位で解析します。exec データイベントには stream / encoding=base64 / data が含まれ、Base64 が元のバイト列を保持します。通常の exec は終了状態で終わります。browser session の対話入力は JSON Lines のままです。ui xml は -o xml を指定しなければ生の UI 階層 XML を返します。

リクエストの上限は 1 MiB、入れ子は 64 階層です。重複フィールド、テキストと子要素の混在、DTD、外部実体を拒否します。XML 1.0 で表現できない制御文字を含むテキストには JSON を選んでください。Agent 設定と通信プロトコルは JSON のままで、XML は CLI の入出力変換だけに使用します。

remote-cli と remote-agent の入手

リポジトリのルートでビルドします。

cargo build --release

CLI は target/release/remote-cli です。同じコマンドで target/release/remote-agent も生成されます。フラッシュ容量が少ないデバイスには、サイズを優先した agent を使用します。

cargo build -p agent --no-default-features --profile release-small

生成物は target/release-small/remote-agent です。

Windows、Linux、macOS では、Web サイトのインストールスクリプトでいずれか一方のバイナリを一度の操作でインストールすることもできます。マルチプラットフォームへのデバイス展開を参照してください。以下のコマンドは remote-cli と remote-agent が PATH にあることを前提とします。ローカルでビルドした直後なら、上記の target/... パスを使用してください。

中継サービスを自分で運用する場合は、開発ガイドに従い DATABASE_URL を設定して exchange を起動し、起動ログから管理者トークンを取得します。公開インスタンスを使う場合は、管理者から運用トークンを取得してください。

デバイスの追加

remote-cli device add lab-router --name "实验室路由"

<id> はデバイス ID です。英数字と - _ . のみ使用でき、最大 64 文字です。--name は省略可能で、省略すると表示名は ID と同じになります。出力されるデバイストークンは、このとき一度だけ表示されます。

agent の起動

管理対象のマシンで、サーバー、デバイス ID、先ほどのデバイストークンを指定してデバイス側プログラムを起動します。

remote-agent --server wss://127.0.0.1:8080 --device-id lab-router --token '<设备令牌>'

3 つの引数は環境変数 REMOTE_SERVER、REMOTE_DEVICE_ID、REMOTE_TOKEN でも指定できます。

--server は ws:// または wss:// で始まる必要があります。ホストのみ（例: wss://mgmt.example.com）を指定すると、agent は /ws/device を自動的に追加します。パスがある場合はそのまま使用します。ローカルの exchange に TLS がない場合は ws://127.0.0.1:8080 を使用してください。

プロセス引数にトークンを含めたくない場合は、server、device_id、token をキーとする JSON を作成します。

{
  "server": "wss://mgmt.example.com",
  "device_id": "lab-router",
  "token": "<设备令牌>"
}

その後 remote-agent --config /path/to/config.json を実行します。デスクトップシステムでのインストールと自動起動はマルチプラットフォームへのデバイス展開を参照してください。

remote-cli と remote-agent の WebSocket は、どちらも HTTPS_PROXY / https_proxy → ALL_PROXY / all_proxy → HTTP_PROXY / http_proxy の順にプロキシ設定を読み、NO_PROXY / no_proxy に従います。agent のヘッドレスモードと --ui モードは同じ接続経路を使用します。プロキシには HTTP CONNECT のサポートが必要です（SOCKS は非対応）。WSS の ALPN は http/1.1 のみを宣言します。バックグラウンドサービスではサービス環境に変数を設定してください。詳しくは外向きプロキシと接続の維持を参照してください。

デバイスが接続したら、次を実行します。

remote-cli device list

一覧でデバイスのオンライン状態を確認できます。

リモートコマンドの実行

-- 以降の内容はデバイスに渡され、ローカルの CLI では解析しません。

remote-cli exec lab-router -- uname -a

-- の後に指定する引数の数によって、リモート側の解釈が変わります。

複数の引数は argv としてそのまま送信し、引数ごとの境界を保持します。デバイス上でそれらの引数を直接入力するのと同じ動作です。必要に応じて CLI が自動で引用符を追加します（Windows デバイスでは PowerShell の規則を使用）。
引数が 1 つだけの場合は、文字列全体をデバイスのシェルがコマンドラインとして解析するため、パイプ、;、ワイルドカード、変数を使えます。

remote-cli exec lab-router -- sh -c 'uname -a; cat /proc/uptime'   # 多个参数，第三个参数完整交给 sh -c
remote-cli exec lab-router -- 'dmesg | tail -20'                    # 一个参数，管道在设备上执行

注意: 複数引数形式では、ローカルシェルからそのまま渡された * や $VAR（PowerShell でよく見られます）はリテラルとして扱われ、リモートでは展開されません。デバイス上で展開するには、-- 'ls /etc/*.conf' のように 1 つの引数にします。

exec は既定で hold が有効です。既定のタイムアウトは 3600 秒（絶対上限は 86400 秒）で、オペレーターが切断しても出力を切り離すだけでジョブは終了しません。--timeout で制限時間を指定できます。例: remote-cli exec lab-router --timeout 120 -- uname -a。--hold-timeout で hold の制限時間を上書きできます。--no-hold を付けるとオペレーターの切断時にキャンセルする動作になり、既定のタイムアウトは 60 秒です。コマンドが正常に戻ると、その終了コードが remote-cli の終了コードになります。

ジョブの確認と終了、セッション枠の解放

remote-cli exec-holds lab-router
remote-cli exec-hold-kill lab-router <job_id>
remote-cli exec-hold-tail lab-router <job_id>
remote-cli exec-hold-cat lab-router <job_id>
remote-cli exec-attach lab-router <job_id>
remote-cli sessions lab-router
remote-cli session-kill lab-router <session_id>

exec-holds は exec ジョブと進行中のダウンロード、アップロード、ディレクトリ照会を一覧表示します。job_id、kind、status、age_secs、現在のデバイス側 session_id（ある場合）、短く切り詰めたコマンドまたはパスの概要が表示されます。exec-hold-kill はジョブ番号を指定してプロセスグループを終了するか、ファイル転送を中止します。tail、cat、attach は exec ジョブ専用です。

sessions は Exchange のルーティングテーブルを直接読み、現在の count/limit とデバイス側のセッション番号を表示します。session-kill はこのデバイス側番号を使用してデバイスにキャンセル指示を送り、直ちに Exchange の枠を解放します。デバイスから応答がなくても解放できます。どちらもデバイスへの追加セッションを作らず、同時実行枠を消費しないため、枠が埋まって停止したセッションへの対処に適しています。読み取り専用アカウントは使用できません。

exec のタイムアウト時はプロセスグループ全体を終了します。出力の排出と終了メッセージの送信にも制限時間があります。Exchange は同時実行上限に達すると、オペレーターを失ったルートや期限切れのルートを自動回収してから、新しいセッションを試みます。exec の期限は実際の実行制限時間に 15 秒の猶予を加えたもの、ファイル転送は 3600 秒に 15 秒を加えたもの（デバイス側には別途 30 秒のアイドルタイムアウト）、その他のセッションは 24 時間です。hold exec は期限内であればオペレーターの切断だけでは終了せず、切断は引き続き detach として扱います。明示的な session-kill または期限超過では hold プロセスをキャンセルします。

シェルを開く

remote-cli shell lab-router

これはデバイス上の PTY セッションです。SSH ではありません。シェルを終了するとセッションも終了します。

その他の入口

ブラウザーコンソール: Web コンソール
モバイルコンソール: モバイルクライアント
Android デバイス側 APK: Android スタンドアロン APK
QR コード、6 桁コード、アカウント: 初期化とペアリング
CLI と agent の自己更新: 自己更新

エンドツーエンド暗号化（密封セッション）

remote-cli exec <设备> -- <命令>、remote-cli shell <设备> は追加の引数なしで、エンドツーエンドの密封セッションを使用します。Exchange は暗号文のみを中継し、コマンド、出力、端末内容を読み取れません。デバイスはワークスペースのルート（スーパー管理者の鍵。スーパー管理者のログイン時に自動生成）と、ルートが発行した認可のみを信頼します。ルートクライアントはアカウントの役割に従ってメンバーに自動発行します。初回のみ必要な設定はリンク先を参照してください。詳しくはエンドツーエンド密封セッションを参照してください。

すべての CLI デバイスセッションはエンドツーエンドの密封のみを使用し、追加の引数は不要です。デバイスの機能情報がない場合や密封ハンドシェイクに失敗した場合も、平文に切り替えることはありません。LAN 直接接続とブラウザー操作にも同じ密封要件が適用されます。

永続バックグラウンドタスク

tasks を公開する Agent は単一操作と宣言的 DAG をデバイス上で実行します。切断後も実行を継続し、再接続すると進捗、出力、成果物を取得できます。ランタイム再起動時は未完了の処理を interrupted にし、自動再実行しません。

作成には密封された manage/owner 権限が必要です。依存関係、固定条件、祖先の結果への JSON Pointer 参照、失敗方針、最大 5 回の明示的な再試行を設定できます。再試行は副作用を繰り返す場合があり、取消は元に戻しません。Web とモバイルはフォームと JSON 入出力に対応します。デスクトップ、Android、ブラウザ、LuCI のローカル画面で履歴、出力、取消、削除を管理します。

最初に操作一覧でデバイスの対応状況と除外理由を確認し、入力ファイルを準備してください。既定は履歴 30 日、1000 件、合計 64 MiB、タスクあたりテキスト 8 MiB、並列ステップ 4（OpenWrt は 2）です。ステップの既定制限は 30 分、最大 24 時間です。古い Agent にはタスク入口を表示しません。

remote-cli task DEVICE operations
remote-cli task DEVICE create pipeline.json --wait
remote-cli task DEVICE list
remote-cli task DEVICE get TASK_ID
remote-cli task DEVICE logs TASK_ID --offset 0
remote-cli task DEVICE cancel TASK_ID
remote-cli task DEVICE upload ./input.bin
remote-cli task DEVICE download TASK_ID STEP.artifact ./result.json
remote-cli task DEVICE delete TASK_ID

常駐サービス

Task の Service モードは、ネイティブのフォアグラウンドコマンドを管理します。実行状態の永続化、終了時の再起動、指数バックオフ、起動頻度の制限、Agent 再起動後の復帰に対応します。初期状態は停止です。編集や削除の前に停止を完了してください。権限の期限切れや取消で停止します。通常の DAG は再実行しません。Web、モバイル、デスクトップ、Android で管理でき、LuCI の設定は Console または CLI で行います。ブラウザー Agent はシステムプロセスを管理できません。

command.command または command.argv を使い、cwd/env、restart (never/on_failure/always)、start_secs、stop_grace_secs、backoff_secs、max_backoff_secs、restart_window_secs、max_starts を設定できます。Windows の正常終了には stop_command が必要です。Unix は SIGTERM を送り、猶予期間後にプロセスツリーを強制終了します。Agent の自動起動は別途設定します。service get の run_id を task get/logs で参照できます。

remote-cli task DEVICE service put worker.json
remote-cli task DEVICE service list
remote-cli task DEVICE service start worker
remote-cli task DEVICE service get worker
remote-cli task DEVICE service restart worker
remote-cli task DEVICE service stop worker
remote-cli task DEVICE service delete worker
remote-agent task service put worker.json