使用說明

這條路徑面向操作員：拿到命令列和裝置端，登入，新增一臺裝置，讓裝置連上，然後執行一條遠端命令並開啟 shell。瀏覽器控制台、手機控制台、Android 裝置端、配對和自更新見文末連結，這裡不重複那些頁面的步驟。

示例裡的地址和令牌請換成你自己的。令牌只在建立時出現一次，不要把它寫進倉庫。

多重身分與帳號授權。 全域 --profile <name> 優先於 REMOTE_CLI_PROFILE。命名身分將 config.toml、密封身分私鑰、根信任及 grants 快取儲存在 <config_base>/remote-cli/profiles/<name>/；config_base 沿用 XDG_CONFIG_HOME、HOME/.config 或 Windows APPDATA。名稱限 1–64 個 ASCII 字母、數字、點、連字號或底線，不能為 . 或 ..。命名 profile 優先於 REMOTE_CLI_CONFIG；未指定 profile 時，原有設定路徑及 REMOTE_CLI_CONFIG 行為不變。各 profile 分別登入，後續呼叫須選取相同 profile。

operator set 接受帳號 ID 或唯一名稱；裝置參數為裝置 ID。--restricted 僅顯示明確授權裝置，--unrestricted 恢復依角色決定的範圍。僅超級管理員可修改範圍；角色與裝置授權由超級管理員管理，沒有超級管理員時管理員可在允許範圍內管理，不能修改自身。operator grant list 僅傳回呼叫者可見的授權。資料庫裝置授權與密封簽章授權是兩層檢查：修改 grant 不能取代 seal approve。建立介面目前不支援原子設定範圍，請先保存 operator add 傳回的一次性權杖，再執行 operator set / operator grant set；這些是獨立請求。

所有 operator 動詞支援 -o text|json|xml。JSON 請求使用 op=list|add|set|grant_list|grant_set|grant_remove；set 接受 operator 與可選 role / restricted（至少一個），grant_set 接受 operator、device 與必填布林值 can_manage。grant_list 可選 operator，grant_remove 接受 operator 與 device。--json 不與子命令混用。

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 輸入；四個輸入選項互斥，仍是完整請求內容，不可混用相同命令的選項或子命令，裝置位置參數規則不變。輸入與輸出獨立選擇，-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

沒有子元素時預設為字串，有子元素時預設為物件。數字、布林值、陣列、空值分別使用 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 每行輸出一份獨立 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

命令列是 target/release/remote-cli。同一命令也會編出 target/release/remote-agent。給 flash 緊張的裝置用體積優先的 agent：

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

產物是 target/release-small/remote-agent。

Windows、Linux、macOS 也可以用網站上的安裝指令碼一次裝好其中一個二進位，說明在 多平臺裝置部署。下面的命令假定 remote-cli 和 remote-agent 已經在 PATH 裡；若剛在本機編出來，改用上面的 target/... 路徑。

自建中轉服務時，先按 開發說明 用 DATABASE_URL 啟動 exchange，從啟動紀錄拿到管理員令牌。使用公共例項時，向管理員要運維令牌即可。

登入

remote-cli login --server http://127.0.0.1:8080 --token '<运维令牌>'

--server 填 http:// 或 https://。命令列會按同樣的安全級別推導 WebSocket 地址：https 對應 wss，http 對應 ws。

登入成功後，設定寫在：

• Linux / macOS：$XDG_CONFIG_HOME/remote-cli/config.toml，未設定 XDG_CONFIG_HOME 時為 ~/.config/remote-cli/config.toml
• Windows：%APPDATA%\remote-cli\config.toml

檔案裡只有兩個鍵：server 和 token。要用別的路徑時設定 REMOTE_CLI_CONFIG。之後的 device、exec、shell 都讀這份設定，不必每次再傳令牌。

新增裝置

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 '<设备令牌>'

三個參數也可以用環境變數：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。

不想把令牌放在程序參數裡時，寫一份 JSON，鍵名為 server、device_id、token：

{
  "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

列表裡能看到這臺裝置的線上狀態。

執行遠端命令

-- 後面的內容交給裝置，不再由本機命令列解析：

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

-- 後面給幾個參數，決定了遠端怎麼理解它們：

• 多個參數按 argv 原樣傳過去，每個參數的邊界都保留，和在裝置上直接敲這幾個參數效果一樣。需要時 CLI 會自動加引號（Windows 裝置按 PowerShell 規則）。
• 只有一個參數時，整串交給裝置的 shell 當命令列解析，可以用管道、;、萬用字元和變數。

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

注意：多參數形式下，本機 shell 原樣傳過來的 *、$VAR（在 PowerShell 裡很常見）會被當作字面量，不會在遠端展開。想讓裝置來展開，就寫成單個參數，例如 -- 'ls /etc/*.conf'。

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 程序。

開啟 shell

remote-cli shell lab-router

這是裝置上的一個 PTY 會話，不是 SSH。退出 shell 即結束這次會話。

其它入口

• 瀏覽器控制台：Web 控制台
• 手機控制台：移動用戶端
• Android 裝置端 APK：Android 獨立 APK
• 二維碼、六位碼和帳號：初始化與配對
• 命令列與 agent 的自更新：自更新

端到端加密（密封會話）

remote-cli exec <设备> -- <命令>、remote-cli shell <设备> 使用端到端密封，無需額外引數，讓 Exchange 只轉發密文，看不到命令、輸出和終端內容；裝置只信任工作區根（超級管理員的金鑰，超級管理員登入時自動生成）以及根簽發的授權；根客戶端按賬號角色自動給成員簽發。詳見下文連結中的一次性設定。詳見 端到端密封會話。

所有 CLI 裝置會話只使用端到端密封，無需額外引數。缺少裝置能力資訊或密封握手失敗時，不會改用明文。LAN 直連和瀏覽器操作使用相同的密封要求。

持久背景工作

宣告 tasks 能力的 Agent 在裝置上執行單一操作或宣告式 DAG。提交後控制端斷線仍繼續執行；重新連線可查詢進度、輸出與本機產物。執行階段重新啟動會將未完成工作標為 interrupted，不會自動重播。

建立需要密封 manage/owner 授權。表單可設定相依項、固定條件、祖先結果的 JSON Pointer 參照、失敗策略及最多五次明確重試。重試可能重複產生副作用，取消不會復原。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