# Bedienung

> HTML: https://remote.ivjn.us/docs/de/usage/

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.

```bash
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.

```powershell
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"/>`.

```xml
<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:

```bash
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:

```bash
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](/docs/de/platform-installation.md#installation-mit-einem-befehl-windows--linux--macos--freebsd--netbsd). 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](/docs/de/development.md) und entnehmen das Administratortoken dem Startprotokoll. Bei einer öffentlichen Instanz erhalten Sie ein Operatortoken vom Administrator.

## Anmelden

```bash
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

```bash
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:

```bash
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`:

```json
{
  "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](/docs/de/platform-installation.md).

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](/docs/de/platform-installation.md#ausgehende-proxys-und-verbindungserhaltung).

Nach der Geräteverbindung:

```bash
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:

```bash
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.

```bash
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

```bash
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

```bash
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](/docs/de/web-console-and-notifications.md)
- Mobile Konsole: [Mobiler Client](/docs/de/platform-installation.md)
- Android-Agent-APK: [Eigenständige Android-APK](/docs/de/platform-installation.md#eigenständige-android-apk)
- QR-Code, sechsstelliger Code und Konten: [Initialisierung und Kopplung](/docs/de/pairing-and-enrollment.md)
- Selbstaktualisierung von CLI und Agent: [Selbstaktualisierung](/docs/de/self-update.md)

## 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](/docs/de/sealed-sessions.md).

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.
```sh
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.

```sh
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
```