Bedienung

Dieser Ablauf richtet sich an Operatoren: CLI und Geräte-Agent beschaffen, anmelden, ein Gerät hinzufügen und verbinden, dann einen Fernbefehl ausführen und eine Shell öffnen. Browserkonsole, mobile Konsole, Android-Agent, Kopplung und Selbstaktualisierung sind am Ende verlinkt; deren Schritte werden hier nicht wiederholt.

Ersetzen Sie Adressen und Tokens der Beispiele durch eigene Werte. Tokens werden nur bei der Erstellung einmal angezeigt und dürfen nicht ins Repository gelangen.

Benannte Identitäten und Kontoberechtigungen. Das globale --profile <name> hat Vorrang vor REMOTE_CLI_PROFILE. config.toml, private Sitzungsschlüssel, Root-Vertrauen und Grant-Caches liegen unter <config_base>/remote-cli/profiles/<name>/. config_base folgt weiterhin XDG_CONFIG_HOME, HOME/.config oder Windows APPDATA. Namen erlauben 1–64 ASCII-Buchstaben, Ziffern, Punkte, Bindestriche oder Unterstriche, außer . und ... Ein benanntes Profil hat Vorrang vor REMOTE_CLI_CONFIG; ohne Profil bleiben bisherige Pfade und REMOTE_CLI_CONFIG unverändert. Für jedes Profil separat anmelden und es bei weiteren Aufrufen auswählen.

operator set akzeptiert eine Konto-ID oder einen eindeutigen Namen; Geräteargumente sind Geräte-IDs. --restricted beschränkt die Sichtbarkeit auf explizit freigegebene Geräte, --unrestricted stellt rollenbasierte Sichtbarkeit wieder her. Nur Superadmin darf den Umfang ändern. Superadmin verwaltet Rollen und Grants; ohne Superadmin dürfen Admins innerhalb ihres erlaubten Umfangs handeln, jedoch nicht ihre eigenen Rechte ändern. operator grant list liefert nur sichtbare Grants. Datenbankberechtigungen und signierte Grants sind getrennte Prüfungen: Änderungen ersetzen seal approve nicht. Die Kontoerstellung unterstützt keine atomare Umfangszuweisung. Das einmalige Token aus operator add speichern, dann operator set / operator grant set als separate Anfragen ausführen.

Alle operator-Aktionen unterstützen -o text|json|xml. JSON verwendet op=list|add|set|grant_list|grant_set|grant_remove. set benötigt operator und mindestens eines von role / restricted; grant_set benötigt operator, device und den booleschen Pflichtwert can_manage. grant_list akzeptiert optional operator; grant_remove benötigt operator und device. --json nicht mit einem Unterbefehl kombinieren.

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-Anfragen und Ausgabe

Prüfen Sie die Optionen der installierten Version mit remote-cli --help. --xml und --xml-file ergänzen bestehende --json / --json-file-Anfragen um XML. Die vier Eingaben schließen sich gegenseitig aus und liefern den vollständigen Anfrageinhalt; nicht mit denselben Befehlsoptionen oder Unterbefehlen kombinieren. Geräte-Positionsargumente bleiben unverändert. Eingabe und Ausgabe sind unabhängig; -o text|json|xml verwendet standardmäßig Text.

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

Blattelemente sind standardmäßig Zeichenketten, Elemente mit Kindern Objekte. Verwenden Sie type="number", type="boolean", type="array" und type="null" für Zahlen, Wahrheitswerte, Arrays und null. Arrays enthalten <item>; leere Objekte benötigen type="object". Beliebige Schlüssel verwenden <field name="arbitrary key">value</field>, eine leere Anfrage <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>

Die Ausgabewurzel ist <response type="...">, Objektmitglieder sind <field name="..." type="...">, Arrayelemente <item type="...">. Typen bleiben explizit; Text wird für XML 1.0 maskiert. Laufzeitfehler liefern ok=false / error mit einem Exitcode ungleich null; Syntaxfehler der Befehlszeile erscheinen weiterhin auf stderr.

XML-Ausgabe unterstützt device list/update, operator list/add/set/grant, exec, session list/kill, ui, ubus, sensors, net, metrics, preset, audit, browser einschließlich exec-Auftragsoperationen. Andere Befehle lehnen -o xml ausdrücklich ab; XML-Anfragen mit den bisherigen Ausgabeformaten bleiben möglich.

Streaming mit exec / sensors --live / browser session liefert ein vollständiges XML-Dokument pro Zeile; jede Zeile separat parsen. Exec-Datenereignisse enthalten stream / encoding=base64 / data; Base64 erhält die ursprünglichen Bytes. Ein normaler exec-Aufruf endet mit dem Exitstatus. Interaktive Eingaben für browser session bleiben JSON Lines. ui xml ohne -o xml liefert weiterhin das ursprüngliche UI-Hierarchie-XML.

Anfragen sind auf 1 MiB und 64 Verschachtelungsebenen begrenzt. Doppelte Felder, gemischter Text mit Kindelementen, DTDs und externe Entitäten werden abgelehnt. Für Text mit in XML 1.0 nicht darstellbaren Steuerzeichen JSON wählen. Agent-Konfiguration und Netzwerkprotokoll bleiben JSON; XML konvertiert nur CLI-Ein- und Ausgabe.

remote-cli und remote-agent beschaffen

Im Repository-Stamm bauen:

cargo build --release

Die CLI liegt unter target/release/remote-cli. Derselbe Befehl erzeugt target/release/remote-agent. Für Geräte mit wenig Flash gibt es einen größenoptimierten Agent:

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

Das Ergebnis ist target/release-small/remote-agent.

Unter Windows, Linux und macOS können die Installationsskripte der Website eines der Programme direkt installieren; siehe Plattformübergreifende Gerätebereitstellung. Die folgenden Befehle setzen remote-cli und remote-agent im PATH voraus. Verwenden Sie bei lokalen Builds andernfalls die genannten target/...-Pfade.

Bei eigenem Relay starten Sie exchange zunächst mit DATABASE_URL gemäß Entwicklung und entnehmen das Administratortoken dem Startprotokoll. Bei einer öffentlichen Instanz erhalten Sie ein Operatortoken vom Administrator.

Anmelden

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

--server erwartet http:// oder https://. Die CLI leitet WebSocket-Adressen mit gleicher Sicherheitsstufe ab: https ergibt wss, http ergibt ws.

Nach erfolgreicher Anmeldung wird die Konfiguration hier gespeichert:

• Linux / macOS: $XDG_CONFIG_HOME/remote-cli/config.toml, ohne XDG_CONFIG_HOME unter ~/.config/remote-cli/config.toml
• Windows: %APPDATA%\remote-cli\config.toml

Die Datei enthält nur server und token. Für einen anderen Pfad setzen Sie REMOTE_CLI_CONFIG. device, exec und shell lesen anschließend diese Konfiguration; das Token muss nicht erneut angegeben werden.

Gerät hinzufügen

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

<id> ist die Geräte-ID. Sie darf ausschließlich Buchstaben, Ziffern und - _ . enthalten und höchstens 64 Zeichen lang sein. --name ist optional; ohne Angabe entspricht der Anzeigename der ID. Das Gerätetoken in der Ausgabe erscheint nur dieses eine Mal.

Agent starten

Starten Sie den Agent auf dem zu verwaltenden Rechner mit Server, Geräte-ID und dem gerade erzeugten Gerätetoken:

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

Alternativ dienen die Umgebungsvariablen REMOTE_SERVER, REMOTE_DEVICE_ID und REMOTE_TOKEN.

--server muss mit ws:// oder wss:// beginnen. Bei einer reinen Hostadresse wie wss://mgmt.example.com ergänzt der Agent /ws/device; vorhandene Pfade bleiben unverändert. Verwenden Sie für einen lokalen Exchange ohne TLS ws://127.0.0.1:8080.

Soll das Token nicht in Prozessargumenten stehen, erstellen Sie eine JSON-Datei mit server, device_id und token:

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

Starten Sie dann remote-agent --config /path/to/config.json. Installation und Autostart auf Desktops beschreibt Plattformübergreifende Gerätebereitstellung.

Die WebSockets von remote-cli und remote-agent lesen Proxys in der Reihenfolge HTTPS_PROXY / https_proxy → ALL_PROXY / all_proxy → HTTP_PROXY / http_proxy und beachten NO_PROXY / no_proxy. Der Agent verwendet ohne Oberfläche und mit --ui denselben Verbindungsweg. Proxys müssen HTTP CONNECT unterstützen, SOCKS wird nicht unterstützt. WSS kündigt per ALPN nur http/1.1 an. Setzen Sie Variablen für Hintergrunddienste in deren Dienstumgebung; siehe Ausgehender Proxy und Verbindungsaufrechterhaltung.

Nach der Geräteverbindung:

remote-cli device list

Die Liste zeigt den Onlinezustand des Geräts.

Fernbefehle ausführen

Alles hinter -- wird dem Gerät übergeben und nicht mehr von der lokalen CLI ausgewertet:

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

Die Anzahl der Argumente hinter -- bestimmt ihre Interpretation:

• Mehrere Argumente werden unverändert als argv übertragen. Ihre Grenzen bleiben erhalten, wie beim direkten Aufruf auf dem Gerät. Bei Bedarf ergänzt die CLI Anführungszeichen, für Windows-Geräte nach PowerShell-Regeln.
• Ein einzelnes Argument wird als ganze Befehlszeile an die Geräteshell übergeben. Pipes, ;, Platzhalter und Variablen sind möglich.

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

Achtung: Bei mehreren Argumenten werden von der lokalen Shell unverändert übergebene * und $VAR (häufig in PowerShell) wörtlich behandelt und auf dem Gerät nicht expandiert. Verwenden Sie zur Expansion dort ein einzelnes Argument, etwa -- 'ls /etc/*.conf'.

exec aktiviert standardmäßig hold: Das Timeout beträgt 3600 Sekunden, die feste Obergrenze 86400 Sekunden. Wird die Operatorverbindung getrennt, wird nur die Ausgabe abgekoppelt; der Auftrag läuft weiter. Mit --timeout setzen Sie eine Frist, etwa remote-cli exec lab-router --timeout 120 -- uname -a; --hold-timeout überschreibt die hold-Frist. Mit --no-hold wird der Auftrag bei Operatortrennung wieder abgebrochen; das Standardtimeout beträgt dann 60 Sekunden. Bei regulärem Abschluss übernimmt remote-cli den Exitcode des Befehls.

Aufträge anzeigen und beenden, Sitzungsplätze freigeben

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 zeigt exec-Aufträge und laufende Downloads, Uploads und Verzeichnisabfragen mit job_id, kind, status, age_secs, aktueller geräteseitiger session_id (falls vorhanden) und gekürzter Befehls-/Pfadzusammenfassung. exec-hold-kill beendet anhand der Auftragsnummer die Prozessgruppe oder Dateiübertragung. tail, cat und attach gelten nur für exec-Aufträge.

sessions liest direkt die Exchange-Routingtabelle und zeigt count/limit und geräteseitige Sitzungsnummern. session-kill verwendet diese geräteseitige Nummer, sendet einen Abbruch an das Gerät und gibt den Exchange-Platz sofort frei, auch ohne Geräteantwort. Beide eröffnen keine zusätzliche Gerätesitzung und belegen keinen Parallelitätsplatz. Sie eignen sich für festhängende Sitzungen bei erreichtem Limit; schreibgeschützte Konten können sie nicht verwenden.

Ein exec-Timeout beendet die gesamte Prozessgruppe. Auch das vollständige Auslesen der noch ausstehenden Ausgabe und der Versand der Abschlussnachricht sind zeitlich begrenzt. Bei erreichtem Parallelitätslimit bereinigt Exchange zunächst Routen ohne Operator oder mit überschrittener Frist und versucht dann eine neue Sitzung: Für exec gilt die tatsächliche Ausführungsfrist plus 15 Sekunden, für Dateiübertragungen 3600 Sekunden plus 15 Sekunden (das Gerät hat zusätzlich 30 Sekunden Inaktivitätslimit), für andere Sitzungen 24 Stunden. hold-exec wird innerhalb seiner Frist durch Operatortrennung nur abgekoppelt. Ausdrückliches session-kill oder Fristüberschreitung beendet auch hold-Prozesse.

Shell öffnen

remote-cli shell lab-router

Dies ist eine PTY-Sitzung auf dem Gerät, keine SSH-Verbindung. Beim Verlassen der Shell endet die Sitzung.

Weitere Einstiege

• Browserkonsole: Webkonsole
• Mobile Konsole: Mobiler Client
• Android-Agent-APK: Eigenständige Android-APK
• QR-Code, sechsstelliger Code und Konten: Initialisierung und Kopplung
• Selbstaktualisierung von CLI und Agent: Selbstaktualisierung

Ende-zu-Ende-Verschlüsselung (versiegelte Sitzungen)

remote-cli exec <设备> -- <命令> und remote-cli shell <设备> verwenden Ende-zu-Ende-versiegelte Sitzungen, ohne zusätzliche Parameter. Exchange leitet nur Chiffretext weiter und kann Befehle, Ausgaben und Terminalinhalte nicht lesen. Das Gerät vertraut ausschließlich der Arbeitsbereichs-Root (dem Schlüssel des Superadministrators, der bei dessen Anmeldung automatisch erzeugt wird) und den von ihr signierten Berechtigungen. Der Root-Client stellt Mitgliedern entsprechend ihrer Kontorolle automatisch Berechtigungen aus. Die einmalige Einrichtung beschreibt Ende-zu-Ende-versiegelte Sitzungen.

Alle CLI-Gerätesitzungen verwenden ausschließlich Ende-zu-Ende-Versiegelung, ohne zusätzliche Parameter. Bei fehlenden Gerätefähigkeitsinformationen oder einem fehlgeschlagenen versiegelten Handshake erfolgt kein Wechsel zu Klartext. Für direkte LAN-Verbindungen und Browseroperationen gelten dieselben Versiegelungsanforderungen.

Dauerhafte Hintergrundaufgaben

Agents mit tasks führen einzelne Aktionen und deklarative DAGs auf dem Gerät aus. Aufgaben laufen nach dem Trennen der Konsole weiter. Nach erneutem Verbinden sind Fortschritt, Ausgabe und Artefakte abrufbar. Ein Neustart setzt offene Aufgaben auf interrupted; sie werden nicht automatisch wiederholt.

Erstellen erfordert versiegelte manage/owner-Rechte. Formulare unterstützen Abhängigkeiten, feste Bedingungen, JSON-Pointer-Verweise auf Vorgänger, Fehlerregeln und bis zu fünf ausdrückliche Wiederholungen. Wiederholungen können Effekte duplizieren; Abbruch macht sie nicht rückgängig. Web und Mobil unterstützen Formulare und JSON-Import/Export. Desktop, Android, Browser und LuCI bieten lokale Historie, Ausgabe, Abbruch und Löschen.

Prüfen Sie zuerst den Aktionskatalog des Geräts. Eingabedateien müssen vorab bereitgestellt werden. Standard: 30 Tage, 1000 Aufgaben, insgesamt 64 MiB, 8 MiB Text je Aufgabe, vier parallele Schritte (zwei auf OpenWrt), 30 Minuten je Schritt bis maximal 24 Stunden. Alte Agents zeigen keinen Aufgabeneintrag.

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

Verwaltete Dienste

Der Service-Modus von Task überwacht native Vordergrundprozesse mit dauerhaftem Sollzustand, Neustartregeln, exponentieller Wartezeit, Startbegrenzung und Wiederherstellung nach einem Agent-Neustart. Neue Definitionen sind gestoppt. Vor Bearbeitung oder Löschung stoppen und das Ende abwarten. Abgelaufene oder widerrufene Berechtigungen stoppen den Dienst. Normale DAG-Ausführungen werden nicht wiederholt. Verwaltung über Web, Mobilgerät, Desktop und Android; LuCI-Konfiguration über Console oder CLI. Browser-Agents unterstützen keine Systemprozessüberwachung.

command.command oder command.argv verwenden, optional mit cwd/env, restart (never/on_failure/always), start_secs, stop_grace_secs, backoff_secs, max_backoff_secs, restart_window_secs und max_starts. Geordnetes Beenden unter Windows benötigt stop_command; Unix verwendet SIGTERM und beendet den Prozessbaum nach der Frist zwangsweise. Den Agent-Autostart separat konfigurieren. service get liefert run_id für 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