# Entwicklung > HTML: https://remote.ivjn.us/docs/de/development/ Dieses Dokument beschreibt Build, Tests und den lokalen Betrieb von exchange. Bereitstellung, Protokollfelder und plattformspezifische Installation behandeln die am Ende verlinkten Fachseiten. ## Toolchain Der Workspace verwendet Rust 2021 und benötigt **Rust 1.88 oder neuer**. Die Version steht im Feld `rust-version` der `Cargo.toml` im Repository-Stamm. ## Workspace und Programme Der Rust-Workspace hat neun Mitglieder: acht unter `crates/` und das Erweiterungs-SDK unter `sdk/extend/rust`. Protokolltypen werden ausschließlich in `crates/proto` definiert. `exchange`, `agent` und `cli` verwenden dieses Crate; duplizieren Sie Nachrichtenstrukturen nicht in einzelnen Komponenten. | Crate | Pfad | Ergebnis | |---|---|---| | `proto` | `crates/proto` | Bibliothek; alleinige Definition von Steuernachrichten, Binärframes und gemeinsamen Datenstrukturen | | `exchange` | `crates/exchange` | Programm `exchange` (Paket- und Programmname identisch) | | `agent` | `crates/agent` | Programm `remote-agent` | | `cli` | `crates/cli` | Programm `remote-cli` | | `updater` | `crates/updater` | Bibliothek zur Selbstaktualisierung von `remote-agent` und `remote-cli` | | `telemetry` | `crates/telemetry` | Gemeinsame Bibliothek zur Fehler- und Protokollübermittlung aller drei Komponenten | | `tls-client` | `crates/tls-client` | Gemeinsame rustls-TLS-Richtlinie für Clients und optionale Proxyverbindungen | | `worker-proto` | `crates/worker-proto` | Protokollprüfung und Hashing von Zugangsdaten für Workers Exchange | | `remote-extend-sdk` | `sdk/extend/rust` | Bibliothek für Framing und Verträge von Erweiterungsprovidern | Der Einstiegspunkt von `exchange` ist `crates/exchange/src/main.rs`. Ohne separate `[[bin]]`-Tabelle erzeugt `cargo build -p exchange` das Programm `exchange`. Die `Cargo.toml`-Dateien von `agent` und `cli` nennen ihre Programme ausdrücklich `remote-agent` und `remote-cli`. Die Verbindungstabelle ist nach Zuständigkeit aufgeteilt: - `crates/exchange/src/hub.rs`: Onlinegeräte, Ersetzung bei Wiederverbindung und Verbindungskennung (epoch) - `crates/exchange/src/hub/session_table.rs`: Übersetzung zwischen Operator- und Geräte-Sitzungsnummern - `crates/exchange/src/hub/outbound.rs`: Begrenzte Sendequeue je Verbindung ## Bauen Führen Sie die Befehle im Repository-Stamm aus. Das Release-Profil (`opt-level = 2`, Thin-LTO, Stack-Unwinding bleibt erhalten) erzeugt Server, CLI und Agent: ```bash cargo build --release ``` Die Programme liegen unter: - `target/release/exchange` - `target/release/remote-cli` - `target/release/remote-agent` `release` behält Stack-Unwinding bei, weil exchange ein langlebiger Prozess mit vielen Verbindungen ist. Bei einer Panic in einer Verbindungsaufgabe kann tokio so nur diese Aufgabe stoppen, ohne Sitzungen anderer Geräte im selben Prozess zu beenden. Für Geräte gibt es außerdem ein größenoptimiertes Profil (`opt-level = "z"`, LTO, `panic = "abort"`, `strip`, `codegen-units = 1`): ```bash cargo build -p agent --no-default-features --profile release-small ``` Das Ergebnis ist `target/release-small/remote-agent`. Nach einem Absturz starten procd, systemd oder die Aufgabenplanung den Agent erneut. Daher kann hier `panic = "abort"` die Größe reduzieren. Die Datenbank wird beim Kompilieren nicht benötigt. `crates/exchange/src/db.rs` verwendet sqlx-Laufzeitabfragen statt `query!`-Makros; `cargo build` funktioniert ohne Datenbank. ## Tests ```bash cargo test --workspace ``` Unter Windows laufen Tests mit Unix-`/bin/sh` (beziehungsweise OpenWrt-`/bin/ash`) und PTY nicht. Das Testmodul in `crates/agent/src/pty.rs` ist durch `#[cfg(all(test, unix))]` geschützt und wird auf anderen Plattformen nicht kompiliert. Die PTY-Implementierung versucht zuerst `/bin/ash`, dann `/bin/sh`. Prozessgruppen und Unix-Signalpfade in `exec.rs` werden ebenfalls nur unter Unix kompiliert; Windows-Befehlstests verwenden PowerShell statt `/bin/sh`. Änderungen an Unix-Pfaden in `exec.rs` oder `pty.rs` erfordern zusätzlich `cargo test --workspace` unter Linux. Windows-Ergebnisse allein reichen nicht. Einzelne Crates oder Bereiche lassen sich gezielt testen, etwa mit `cargo test -p proto` oder `cargo test -p exchange -- hub::`. ## exchange lokal starten Stellen Sie PostgreSQL bereit und setzen Sie die Verbindungszeichenfolge in `DATABASE_URL`. Diese Variable entspricht `--database-url` von `exchange` (siehe `crates/exchange/src/config.rs`). Beim Start führt `db::connect` die beim Kompilieren eingebetteten Migrationen aus: ```rust sqlx::migrate!("../../migrations") ``` Die Migrationen liegen im Repository-Stamm unter `migrations/` und laufen beim Start automatisch; sqlx-cli wird nicht benötigt. Für Audit-Operationen ist außerdem ein Verschlüsselungsschlüssel erforderlich. Die folgenden Beispiele erzeugen einen lokalen Testschlüssel. Bewahren Sie ihn sicher auf und verwenden Sie ihn bei späteren Starts erneut. Ein neuer Schlüssel bei jedem Start verhindert die Entschlüsselung bestehender Audit-Details. ```bash export DATABASE_URL='postgres://luci:luci@127.0.0.1:5432/luci' export AUDIT_ENCRYPTION_KEY="$(python -c 'import base64, secrets; print(base64.b64encode(secrets.token_bytes(32)).decode())')" cargo run -p exchange -- --listen 127.0.0.1:8080 ``` Unter PowerShell zuerst die Umgebungsvariable setzen: ```powershell $env:DATABASE_URL = "postgres://luci:luci@127.0.0.1:5432/luci" $env:AUDIT_ENCRYPTION_KEY = python -c "import base64, secrets; print(base64.b64encode(secrets.token_bytes(32)).decode())" cargo run -p exchange -- --listen 127.0.0.1:8080 ``` Bei bereits gebautem Release ersetzen Sie `cargo run -p exchange --` durch `./target/release/exchange`. Die Standardadresse ist `0.0.0.0:8080`; zur lokalen Entwicklung empfiehlt sich die ausdrückliche Bindung an `127.0.0.1`. Enthält die Datenbank noch kein aktives Operatorkonto, erzeugt der Startvorgang einen Administrator und zeigt dessen Token einmalig im Startprotokoll. Der Klartext erscheint nur dieses eine Mal. Vollständige Hinweise zu Bereitstellung, Reverse Proxy und Konten stehen in `docs/deployment.md` im Repository. Die Seite enthält Serveradressen und wird auf dieser Website nicht veröffentlicht. ## Prüfungen vor dem Commit Führen Sie diese Prüfungen im Repository-Stamm aus. Beginnen Sie bei Rust-Änderungen mit gezielten Crate-Tests und prüfen Sie anschließend den Workspace. Bei bestehenden, nicht betroffenen Formatabweichungen nur geänderte Dateien formatieren. Android, Browser-Erweiterung und mobile Konsole benötigen zusätzlich eigene Builds und Tests; Rust-Tests decken diese Oberflächen nicht ab. ```sh cargo fmt --all -- --check cargo clippy --workspace --all-targets -- -D warnings cargo test --workspace ``` ## Dokumentation pflegen Prüfen Sie das Implementierungsverhalten, bevor Sie Anleitungen in `docs/` aktualisieren. Website-Themen haben eine Referenzquelle unter `website/docs/.md` und neun Übersetzungen unter `website/docs/content//.md`. Befehle, Felder, Codebeispiele und Überschriftenebenen müssen übereinstimmen. Seiten und Suchindizes mit dem Skript erzeugen, nicht nur HTML manuell bearbeiten. Folgende Befehle im Repository-Stamm benötigen Python 3.11+, markdown-it-py und Node.js: ```sh python -m pip install markdown-it-py python scripts/build-docs.py python scripts/build-docs.py --check python scripts/test-docs.py python scripts/test-docs-markdown.py node scripts/test-docs-locale.js python scripts/test-build-docs.py python scripts/test-site-seo.py ``` Die Generierungsprüfung vergleicht außerdem alle erzeugten Dateien Byte für Byte. Fehlende oder veraltete Ausgaben führen ohne Schreibzugriffe zum Fehler. CI führt diese Prüfung vor einer Neugenerierung aus. Die Prüfungen kontrollieren vollständige Übersetzungen, Codebeispiele, Überschriftenstruktur, Seitenlinks, Anker und Sprachrouting. Generierte Seiten zusammen mit den Quellen committen. Der Dokumentationsbau ändert nur lokale Dateien; Website-Deployment und Veröffentlichung von Downloads sind getrennte Vorgänge. ## Weitere Dokumentation - [Technik](/docs/de/architecture.md): Ausgehende Verbindungen, Sitzungsübersetzung, epoch, begrenzte Queues und Tokenspeicherung - [Bedienung](/docs/de/getting-started.md): Anmeldung, Geräte hinzufügen, Agent starten, Befehle und Shell - Bereitstellungsanleitung im Repository unter `docs/deployment.md` (mit Serveradressen, auf dieser Website nicht öffentlich) - [Wire-Protokoll](/docs/de/websocket-protocol.md) - [Plattformübergreifende Gerätebereitstellung](/docs/de/platform-installation.md)