Initialisierung, Geräte-QR-Codes und Anmeldung mit sechsstelligen Codes

Der Standard-Exchange des Agents ist wss://exchange.ivjn.us; die Verwaltungs-API-Adresse für CLI/Console lautet https://exchange.ivjn.us. Vorhandene Konfigurationen haben Vorrang, selbst gehostete Exchange-Adressen werden nicht überschrieben.

SaaS-Registrierung und erste Anmeldung

remote-cli register --username alice --email alice@example.com
# 按隐藏输入提示设置密码，注册后向邮箱发送验证码。
remote-cli verify-email --username alice
# 隐藏输入邮件中的 8 位数字验证码，然后登录。
remote-cli login --email alice@example.com
# init 是 login 的别名，不带 --email 时交互输入邮箱和密码。
remote-cli init
# 原有令牌仍可使用：
remote-cli login --server https://exchange.ivjn.us --token-stdin

Registrierung und Anmeldung verbinden sich standardmäßig mit https://exchange.ivjn.us; für selbst gehostete Dienste kann --server ergänzt werden. Die Anmeldung verwendet die E-Mail-Adresse als Kontoidentität; Leerzeichen werden entfernt, die Adresse in Kleinschreibung umgewandelt und ungültige Formate direkt abgelehnt. Der Benutzername ist der bei der Registrierung gewählte Arbeitsbereichsname (3–64 Buchstaben, Ziffern oder ._-). Kontopasswörter haben keine Längen- oder Zeichenbeschränkungen; der Server speichert nur Passwort-Hashes. Automatisierung kann --password-stdin verwenden; schreiben Sie Passwörter nicht in Befehlsargumente. Neue Konten können sich erst nach Verifizierung ihrer E-Mail-Adresse anmelden. Die CLI speichert nur das zurückgegebene Sitzungstoken, kein Passwort, und behält während der ausstehenden Registrierungsverifizierung eine bestehende Anmeldung bei.

Jede Registrierung erstellt einen unabhängigen Arbeitsbereich; das Konto ist dessen Administrator. Geräte, Mitglieder, Remotesitzungen, Metriken und Audit-Daten sind voneinander isoliert; verschiedene Arbeitsbereiche können dieselbe Geräte-ID verwenden. Die Genehmigung eines sechsstelligen Codes fügt das Gerät oder neue Mitglied dem Arbeitsbereich der genehmigenden Person hinzu. Verwenden Sie zum Beitritt zu einem bestehenden Arbeitsbereich ein Token oder eine Genehmigung per sechsstelligen Code von dessen Administrator.

Android Console unterstützt ebenfalls Registrierung, Passwortanmeldung, Anmeldung mit vorhandenem Token und sechsstelligen Codes. Das Passwort wird nur für die aktuelle Anfrage verwendet; Zugangsdaten werden weiterhin im SecureStore gespeichert.

Passwort-Anmeldesitzungen sind 30 Tage gültig; jedes Konto darf höchstens 32 gültige Sitzungen besitzen. Wiederholte Anmeldungen verdrängen keine anderen Clients. POST /api/auth/logout meldet das aktuelle Bearer-Sitzungstoken ab; bestehende WebSockets werden innerhalb von höchstens 5 Sekunden geschlossen. Nach Ablauf ist eine erneute Anmeldung erforderlich. Geräte- und bisherige Betriebstokens behalten ihre ursprüngliche Lebensdauer.

Reine Token-Identitäten besitzen kein Passwortkonto und können nicht per E-Mail wiederhergestellt werden. Derzeit sind weder Abrechnung noch instanzübergreifendes WebSocket-Routing enthalten.

E-Mail-Verifizierung und Passwortwiederherstellung

remote-cli resend-verification --email alice@example.com
remote-cli verify-email --username alice
remote-cli forgot-password --email alice@example.com
remote-cli reset-password --email alice@example.com
# 按提示输入邮件验证码、新密码，再重新登录。

# 已登录的旧密码账号绑定或更换邮箱，需要再次验证当前密码。
remote-cli set-email --email alice@example.com
remote-cli verify-email --username alice

Verifizierung und Wiederherstellung verwenden getrennte achtstellige Zahlencodes mit unterschiedlichem Zweck. Sie sind 15 Minuten gültig und verfallen nach 5 aufeinanderfolgenden Fehleingaben. Erneutes Senden macht den alten Code ungültig; pro Konto und Zweck ist höchstens eine Nachricht pro Minute erlaubt. Verifizierungs- und Zurücksetzungsbefehle unterstützen --code für die Automatisierung; standardmäßig wird der Code verdeckt eingegeben. Ein erfolgreiches Zurücksetzen widerruft sämtliche Anmeldesitzungen dieses Kontos; bestehende WebSockets werden innerhalb von höchstens 5 Sekunden getrennt. Andere Mitglieder und Geräte des Arbeitsbereichs bleiben unberührt.

Auf der Console-Registrierungsseite wird die E-Mail-Adresse eingegeben; anschließend erscheint die Verifizierungsseite. Die Anmeldeseite bietet E-Mail verifizieren und Passwort vergessen. Beim Ändern der E-Mail bleibt die ursprüngliche Adresse bis zum Abschluss der Verifizierung erhalten. Anfragen zum erneuten Senden und zur Wiederherstellung liefern eine einheitliche Meldung und verraten nicht, ob eine Adresse registriert ist.

Die E-Mail-Funktion erfordert die Migration 0004_email.sql und SMTP-Konfiguration: SMTP_HOST, SMTP_PORT, SMTP_FROM, SMTP_USERNAME, SMTP_PASSWORD, SMTP_SECURITY. Standardmäßig wird STARTTLS verwendet; implizites TLS wird unterstützt. Unverschlüsseltes SMTP ist nur für lokale Tests an Loopback-Adressen erlaubt. SMTP-Zugangsdaten gehören in die Umgebungsdatei des Dienstes und dürfen nicht in Git eingecheckt werden. Ohne konfigurierten E-Mail-Dienst liefern die neuen Registrierungs- und Versandendpunkte 503; bestehende Konten können sich weiterhin anmelden. Daher muss die Versandkonfiguration vor der produktiven Aktivierung abgeschlossen sein. Ein vorübergehender SMTP-Fehler kann ein auf Verifizierung wartendes Konto hinterlassen; senden Sie nach der Wiederherstellung die Verifizierungsmail erneut, statt sich nochmals zu registrieren.

Exchange-Konto-API

Eine erfolgreiche Anmeldung liefert username, email (falls gebunden), tenant_id, token, expires_in und setzt Cache-Control: no-store. Kontopasswörter werden mit Argon2id-Standardparametern und Salt gespeichert. Pro TCP-Quell-IP sind höchstens 20 Kontoanfragen pro Minute erlaubt, pro Benutzername höchstens 10; höchstens 4 Passwort-Hashes werden gleichzeitig berechnet. Vom Client gelieferte Weiterleitungs-IPs werden nicht vertraut. Clients hinter einem Reverse Proxy teilen sich das IP-Kontingent; öffentliche Bereitstellungen sollten zusätzliche Ratenbegrenzung am vertrauenswürdigen Eingang konfigurieren.

Rust Exchange deaktiviert öffentliche Registrierung standardmäßig. Mit EXCHANGE_ALLOW_REGISTRATION=true und SMTP wird sie ausdrücklich aktiviert; false deaktiviert neue Registrierungen, bestehende Konten können sich weiter anmelden.

Einen sechsstelligen Code im Agent anzeigen

Android Remote Agent: Die Standardadresse ist bereits eingetragen; tippen Sie auf Connect with a six-digit code. Die Anwendung zeigt einen sechsstelligen Code mit 5 Minuten Gültigkeit an. Führen Sie in einer angemeldeten Administrator-CLI Folgendes aus:

remote-cli pair 012345
# 可选：覆盖默认 ID 和显示名称
remote-cli pair 012345 --device-id my-android --name "我的手机"

Beim Abrufen des Verbindungscodes zeigt die CLI Gerätenamen, Identitätstyp und vorgeschlagene Geräte-ID an. Genehmigen Sie erst, nachdem Sie Ihr eigenes Gerät erkannt haben. Die Standard-ID verwendet ASCII-Kleinbuchstaben, Ziffern und ._- aus dem Gerätenamen und entfernt Leerzeichen sowie andere Zeichen. Bleiben keine verwendbaren Zeichen übrig, wird device verwendet; maximal 64 Zeichen. Bei Namenskonflikten im selben Arbeitsbereich werden fortlaufend Zahlen angehängt, etwa realmev5, realmev51, realmev52; bei Bedarf wird die Basis-ID gekürzt. Exchange behandelt gleichzeitige Konflikte beim Erstellen, die CLI gibt die endgültig zugewiesene ID aus. Auch manuell angegebene kollidierende IDs erhalten einen Zahlenanhang. Android verwendet den Systemgerätenamen (falls nicht verfügbar das Modell), der native Agent den Hostnamen. Der Agent erhält automatisch ein eigenes Gerätetoken, speichert es verschlüsselt und beginnt die Verbindung. Bedienungshilfen oder Bildschirmsteuerung werden nicht automatisch aktiviert. Abbruch, Ablauf oder Authentifizierungsfehler ersetzen keine vorhandene Konfiguration; ein gerade verbindender Agent muss zuerst gestoppt werden.

Geräte mit Computer-, Router- und Linux-Agent hinzufügen

Bei Windows-, macOS-, OpenWrt- und Linux-Agents müssen Gerätetokens nicht manuell eingetragen werden. Wählen Sie eine der Methoden:

Methode 1: Der Agent beantragt einen sechsstelligen Code mit 5 Minuten Gültigkeit und zeigt zugleich einen QR-Code mit dem Inhalt remote://pair?code=012345&server=wss%3A%2F%2Fexchange.ivjn.us an (ohne Zugangsdaten). Der Administrator kann wählen: Android Console Gerät hinzufügen → Pairing-Code eingeben → Geräte-QR-Code scannen (mit Kamera scannen, nach Prüfung des übereinstimmenden Servers abfragen und Genehmigung bestätigen), den sechsstelligen Code eingeben, unter Pairing-Code genehmigen in Web Console einen sechsstelligen Code oder remote://pair?... einfügen oder remote-cli pair 012345 verwenden (akzeptiert auch diesen URI). Nach der Genehmigung speichert der Agent automatisch das Token und verbindet sich.

Methode 2: Der Administrator erstellt in Android Console unter Gerät hinzufügen → Durch Scannen hinzufügen eine einmalige Einladung und tippt auf Einladung kopieren (auf Computer / Router einfügen); alternativ führt er remote-cli qr --device-id pc-01 --text aus. Die Einladung ist das JSON im QR-Code ({"type":"remote-enrollment",...}), ist 5 Minuten gültig und nur einmal verwendbar. Der Inhalt von Gerätetoken-QR-Codes (remote-cli device qr) wird ebenfalls akzeptiert.

Speicherorte und Verbindung:

• Desktop-UI: Schreibt in die aktuelle Konfigurationsdatei (standardmäßig %LOCALAPPDATA%\remote-agent\config.json / ~/.config/remote-agent/config.json) und verbindet sich sofort.
• OpenWrt: Schreibt in UCI remote-agent.main (server / device_id / token, enabled=1) und startet dann den procd-Dienst neu.
• Kommandozeile: Schreibt standardmäßig in den Desktop-Konfigurationspfad (auf OpenWrt standardmäßig in UCI). --config PATH legt eine JSON-Datei fest, --uci erzwingt UCI. Nach dem Speichern erfolgt die Verbindung im Vordergrund (--no-connect speichert nur). Falls ein vorhandener Dienst diese Konfiguration verwendet, starten Sie ihn neu.

Bei bereits konfigurierten Zugangsdaten wird ein Austausch standardmäßig abgelehnt. Die Kommandozeile benötigt --force; Desktop-UI und LuCI verlangen zuerst eine Bestätigung. Die vorhandene Token-Methode (--device-id/--token, Konfigurationsdatei, LuCI-Einstellungsseite) bleibt bestehen.

remote-agent pair                       # 显示六位码 + 二维码，批准后保存并连接
remote-agent pair --server wss://your-exchange.example.com --config ./agent.json
remote-agent join '{"type":"remote-enrollment","version":1,...}'
remote-agent join - < invite.txt --no-connect

Natives Pairing verlangt wss://; nur lokales Loopback erlaubt ws:// für Tests. Android- und Console-Pairing verlangen HTTPS/WSS.

Console-Anmeldung mit sechsstelligen Codes

Tippen Sie auf der Anmeldeseite von Android Remote Console auf Mit sechsstelligen Code anmelden. Wählen Sie in Web Console (/console) auf der Anmeldekarte die Registerkarte Sechsstelliger Code und rufen Sie einen Anmeldecode ab. Ein Administrator kann eine der folgenden Genehmigungsmethoden verwenden:

remote-cli pair 012345 --operator-name mobile-alice
# 只读客户端：追加 --role readonly

Oder klicken Sie im Arbeitsbereich einer angemeldeten Web Console auf Pairing-Code genehmigen (nur Administratoren sichtbar; Operatoren mit Leserechten haben diesen Einstieg nicht), geben Sie den sechsstelligen Code vom Bildschirm der anderen Person ein und genehmigen Sie nach Prüfung von Typ und Bezeichnung.

Standardmäßig wird ein eigenständiges operator-Konto erstellt; das eigene Administrator-Token wird nicht kopiert. Der Administrator kann ausdrücklich --role admin oder --role readonly angeben. Android Console prüft die Zugangsdaten nach Erhalt der Genehmigung erneut, speichert sie im SecureStore und öffnet die Geräteliste. Web Console hält die Operator-Zugangsdaten im Arbeitsspeicher der aktuellen Seite (wie bei Konto-/Token-Anmeldung) und öffnet die Geräteliste. Nach Abbruch oder Fehler kann weiterhin die bisherige Konto- oder Token-Anmeldung verwendet werden; Eingaben anderer anschließend verwendeter Anmeldemethoden werden nicht gelöscht.

Remote Agent durch Scannen eines CLI-Codes anmelden

remote-cli qr --device-id my-phone
# 输出 SVG 供手机扫描：
remote-cli qr --device-id my-phone --output ./phone-login.svg

Erstellen Sie den QR-Code in einer angemeldeten Administrator-CLI. Tippen Sie auf dem Telefon in Remote Agent auf Scan connection QR code, prüfen Sie Server und Geräte-ID und tippen Sie auf Connect. Der QR-Code enthält nur ein zufälliges temporäres 256-Bit-Ticket, das 5 Minuten gültig ist, nur ein Gerät binden kann und kein langfristiges Gerätetoken enthält. Nach dem Scannen stellt Exchange ein Gerätetoken aus; das Telefon speichert es über den Keystore und verbindet sich. Die Geräte-ID des QR-Codes muss neu sein; vorhandene Geräte werden weder ersetzt noch rotiert.

Abrufanfragen desselben Telefons enthalten eine feste zufällige claim_id; ein erneuter Versuch nach Netzunterbrechung kann dasselbe Ergebnis abrufen. Andere claim_id-Werte können es nicht erneut beanspruchen. Nach dem Speichern bestätigt das Telefon die Löschung des Tickets. Temporäre Tickets liegen im Prozessspeicher und verfallen bei Exchange-Neustart; bereits begonnene Abrufresultate werden zusätzlich höchstens 5 Minuten für Wiederholungsversuche des ursprünglichen Clients aufbewahrt.

Geräte-QR-Code erzeugen

# 创建设备，同时在终端显示二维码
remote-cli device add my-android --qr
# 新建 SVG 文件，可在电脑打开后供手机扫描
remote-cli device add another-phone --qr-output ./another-phone.svg
# 使用手里已有的设备令牌，不创建或轮换设备
remote-cli device qr my-android --output ./my-android.svg
# 明确轮换令牌并生成二维码；原令牌立即失效
remote-cli device rotate-token my-android --qr

device qr liest das Gerätetoken verdeckt ein und unterstützt auch --token-stdin. Geräte-QR-Codes enthalten nur Gerätetokens; Betriebstokens sind nicht zulässig. Ausgabedateien dürfen nicht überschrieben werden und enthalten Zugangsdaten; bewahren Sie sie sicher auf und löschen Sie sie nach Gebrauch. QR-Codes erfordern HTTPS/WSS.

Android Console: Nach dem Erstellen eines neuen Geräts wird direkt der Geräte-QR-Code angezeigt. Token rotieren und QR-Code erzeugen in den Gerätedetails erklärt zuerst die Auswirkungen auf die Verbindung und verlangt Bestätigung. Der Server speichert nur Token-Hashes; ein alter QR-Code lässt sich aus bestehenden Gerätedatensätzen nicht rekonstruieren. Daher erfolgt zum bloßen Anzeigen eines QR-Codes keine stille Token-Rotation.

Exchange-Pairing-API

Der sechsstellige Code dient ausschließlich dazu, dass ein authentifizierter Administrator die Anfrage findet und bestätigt; er kann weder zum Polling noch zum Eintauschen gegen Zugangsdaten verwendet werden. Die Polling-Zugangsdaten sind ein zufälliges 256-Bit-Geheimnis und gelangen nicht in URLs. Wiederholte Genehmigung wird abgelehnt. Schlägt die Identitätserstellung fehl, wird die Belegung der Autorisierung für einen erneuten Versuch freigegeben. Das genehmigte Ergebnis kann mit denselben privaten Polling-Zugangsdaten erneut gelesen werden, damit ein einzelner Paketverlust keine Zugangsdaten dauerhaft vernichtet. Nach dem Speichern bestätigt der Client die Löschung.

Auf Genehmigung wartende und genehmigte, noch nicht abgeholte Autorisierungen bleiben jeweils höchstens 5 Minuten erhalten. Ohne REDIS_URL liegen temporäre Sitzungen nur im Speicher des aktuellen Exchange-Prozesses. Nach Neustart ist ein neuer Code erforderlich; bei mehreren Instanzen müssen Pairing-Anfragen dieselbe Instanz erreichen. Mit Redis werden Pairing-Einträge und Ratenbegrenzungszähler in Redis geschrieben (an die 5-Minuten-TTL angepasst); Anfragen dürfen beliebig auf Instanzen verteilt werden und benötigen keine Sitzungsbindung. Pro tatsächlicher TCP-Quell-IP sind höchstens 10 Codeabrufe pro Minute erlaubt; Administratoren dürfen pro Minute höchstens 20 Abfragen oder Genehmigungen durchführen. Im Speichermodus gilt zusätzlich die globale Grenze von 256 ausstehenden Sitzungen. Durch Proxys weitergeleitete Client-IPs gelten nicht als vertrauenswürdige Ratenbegrenzungsgrundlage; Benutzer hinter demselben Reverse Proxy teilen sich das Quellkontingent. Abgelaufene Daten werden durch TTL/regelmäßige Bereinigung entfernt. Antworten setzen Cache-Control: no-store; Pairing-Geheimnisse und ausgestellte Tokens werden nicht im Klartext protokolliert.

Bestehende Geräte-IDs/Konten im Backend können durch Pairing-Anfragen nicht überschrieben werden. Administratoren sollten Code und anfragenden Client prüfen; genehmigen Sie keine Anmeldecodes, die andere Ihnen durch Täuschung vorlegen.

Verbindungscode-API: POST /api/pairing/start akzeptiert optional device_name und gibt den Gerätenamen zurück. Administrator-GET /api/pairing/{code} liefert device_name und die suggested_device_id für den aktuellen Arbeitsbereich; eine Abfrage reserviert keine ID. Die Geräte-identity in POST /api/pairing/approve darf ausgelassen werden; Erfolg liefert 200 und {identity} (endgültige ID, ohne Token). Der native WebSocket /ws/pairing?device_name=... unterstützt URL-codierte Gerätenamen.