Bereitstellen des Relay-Clients

Installieren und starten Sie den Relay-Client auf einem Gerät in Ihrem Netzwerk, um den ausgehenden Tunnel zur Test Cloud zu erstellen. Bevor Sie beginnen, konfigurieren Sie eine Relay-Gruppe und halten Sie den Client-Konfigurationsstring bereit.

Voraussetzungen

Hardwareanforderungen

Profil	vCPU	RAM	Relay-Gruppen	Endpunkte pro Gruppe	Use case
Standard	1	2 GB	Bis zu 10	Bis zu 50	Die meisten Bereitstellungen
Groß	2	4 GB	10+	Bis zu 50	Umgebungen mit hohem Durchsatz oder großen Umgebungen

Dies sind Mindestanforderungen für den Relay-Clientprozess. Wenn die Maschine andere Workloads ausführt, stellen Sie entsprechende zusätzliche Ressourcen bereit.

Datenträger-Voraussetzungen

Profil	Minimaler freier Datenträger
Standard (1–10 Gruppen)	200 MB
Groß (10 + Gruppen)	1 GB

Unterstützte Betriebssysteme

Architektur	Linux	Windows
x86_64 (AMD64)	Wird unterstützt	Wird unterstützt
ARM64 (aarch64)	Wird unterstützt	Wird unterstützt

Netzwerkanforderungen

Der Relay-Client benötigt nur ausgehende Verbindungen. Es sind keine eingehenden Firewallregeln erforderlich.

Ab Relay-Client 26.4.2 können neue Relay-Client-Konfigurationen den persistenten Tunnel über die Standard-URL cloud.uipath.com von Automation Cloud verbinden. Diese Konfigurationen erfordern keine regionsspezifische Relay-Hostnamen-Zulassungsliste für den Tunnel.

Relay-Client-Konfiguration	Protokoll	Port	Ziel (Destination)	TLS-Password erforderlich	Zweck
Relay-Client 26.4.2 oder höher	HTTPS/WSS	443	cloud.uipath.com	Nicht erforderlich	Authentifizierung, Relay-Registrierung und persistenter Tunnel
Relay-Client-Versionen vor 26.4.2	TLS	443	<region>-relay.uipath.com	Erforderlich	Persistenter Tunnel

Relay-Client-Versionen vor 26.4.2 funktionieren weiterhin mit regionalen Relay-Hostnamen. Lassen Sie diese Hostnamen auf der Zulassungsliste, bis Sie zum Relay-Client 26.4.2 oder später wechseln und eine Verbindung über cloud.uipath.com herstellen.

Ersetzen Sie bei Relay-Client-Versionen vor 26.4.2 <region> durch die Region Ihres Test Cloud-Mandanten.

Region	Relay-Server-Hostname
uns	us-relay.uipath.com
EU	eu-relay.uipath.com
Kanada	ca-relay.uipath.com
Schweiz	ch-relay.uipath.com
Australien	au-relay.uipath.com
Singapur	sg-relay.uipath.com
Japan	jp-relay.uipath.com
Südkorea	kr-relay.uipath.com
VAE	ae-relay.uipath.com
Vereinigtes Königreich	uk-relay.uipath.com
GXP EU	gxp-eu-relay.uipath.com
GXP USA	gxp-us-relay.uipath.com

Hinweis:

Wenden Sie sich an den UiPath-Support, um den Hostnamen des Relay-Servers zu bestätigen, wenn Ihre Mandantenregion nicht oben aufgeführt ist.

Wählen Sie die Region aus, die der Region Ihres UiPath Cloud- Mandanten entspricht, nicht den physischen Standort des Relay-Knotens. Wenn Ihr Mandant beispielsweise in der Region der USA bereitgestellt wird, verwenden Sie us-relay.uipath.com auch wenn das Relay selbst in einer anderen Region ausgeführt wird. Relay-Client 26.4.2 -Konfigurationen, die eine Verbindung über cloud.uipath.com herstellen, verwenden diesen regionalen Hostnamen nicht.

Latency considerations

Überlegungen zur Latenz: Da der Datenverkehr UiPath Cloud → Relay-Server → Relay-Knoten → lokaler Dienst durchläuft, minimiert die Installation des Relay-Knotens in der Nähe der Region Ihres Mandanten die Round Trip Time und verbessert den Gesamtdurchsatz.

Relay client 26.4.2 configurations

For Relay client 26.4.2 configurations that connect through cloud.uipath.com, configure firewalls and proxies to allow HTTPS traffic and WebSocket upgrades to cloud.uipath.com:443.

If a proxy inspects TLS for cloud.uipath.com, install the proxy's signing CA in the OS trust store used by the Relay client, and make sure the proxy allows WebSocket upgrades.

Relay-Client-Versionen vor 26.4.2

For Relay client versions earlier than 26.4.2, configure your firewall and any TLS-inspecting proxy or DLP appliance to allow TLS passthrough for <region>-relay.uipath.com:443; TLS inspection on the regional relay hostname breaks the relay tunnel.

Die Maschine, auf der der Relay-Client ausgeführt wird, muss auch direkten Netzwerkzugriff auf alle lokalen Dienste haben, die Sie verfügbar machen möchten. Planen Sie die Platzierung des Relay-Clients entsprechend.

Wichtig:

Der Relay-Knoten muss in der Lage sein, den Hostnamen aufzulösen und eine Verbindung zum registrierten Port für jeden Endpunkt in seiner Relay-Gruppe zur Runtime zu öffnen. Der Routing-Pfad ist flexibel – eine direkte Netzwerkroute, ein Enterprise Egress Proxy oder ein Jump Host sind alle akzeptabel – solange die Verbindung über den Relay-Knoten erfolgreich ist. Planen Sie die Platzierung so, dass jeder Endpunkt in der Gruppe erreichbar bleibt.

Bandbreite

Der Steuerelementkanal (Heartbeats und Authentifizierung) verbraucht im Leerlauf ca. 1–2 KB/Minute . Der Datenverkehr skaliert mit dem Volumen der Anforderungen, die Ihre Cloud-Dienste an lokale Endpunkte senden – das Relay fungiert als transparenter Tunnel ohne zusätzlichen Overhead über TLS hinaus und ein einfaches WebSocket-Framework für cloud.uipath.com -Verbindungen.

Überprüfen Sie die Verbindung

Bevor Sie den Relay-Client installieren, bestätigen Sie, dass der ausgehende Datenverkehr auf Port 443 zu den erforderlichen Zielen für Ihre Konfiguration zugelassen ist.

Linux

nc -zv cloud.uipath.com 443

# Required only for Relay client versions earlier than 26.4.2
nc -zv <region>-relay.uipath.com 443

Windows (PowerShell)

Test-NetConnection -ComputerName cloud.uipath.com -Port 443

# Required only for Relay client versions earlier than 26.4.2
Test-NetConnection -ComputerName <region>-relay.uipath.com -Port 443

Ein erfolgreiches Ergebnis zeigt TcpTestSucceeded : True unter Windows und succeeded unter Linux. Wenn eine erforderliche Prüfung fehlschlägt, überprüfen Sie Ihre Firewallregeln. Bestätigen Sie bei Relay-Client- 26.4.2 -Konfigurationen, die eine Verbindung über cloud.uipath.com herstellen, dass WebSocket-Upgrades zulässig sind; Bestätigen Sie bei Relay-Client-Versionen vor 26.4.2, dass der TLS-Passwort für den Relay-Server-Hostnamen konfiguriert ist.

Konfigurieren eines Proxys (falls zutreffend)

Wenn Ihr Netzwerk ausgehenden Datenverkehr über einen Proxy weiterleitet, legen Sie die folgenden Umgebungsvariablen fest, bevor Sie relay start ausführen. Der Relay-Client wendet den Proxy auf alle ausgehenden Verbindungen an.

Variable	Zweck
HTTPS_PROXY / https_proxy	Proxy-URL (zuerst aktiviert)
HTTP_PROXY / http_proxy	Proxy-URL (Fallback)
NO_PROXY / no_proxy	Durch Kommas getrennte Hosts oder Domänen, die den Proxy umgehen

Die Proxy-URL muss eines dieser Schemas verwenden: http://, https://, socks5:// oder ntlm://. Format: scheme://[user:password@]host:port.

Für https:// -Proxys: Der Relay-Client überprüft das TLS-Zertifikat des Proxys anhand des Vertrauensspeichers des Betriebssystems. Wenn Ihr Proxy eine Unternehmens- oder selbstsignierte Zertifizierungsstelle verwendet, fügen Sie diese Zertifizierungsstelle zum Vertrauensspeicher der Relay-Clientmaschine hinzu, bevor Sie den Relay-Dienst starten; Andernfalls schlägt der TLS-Handshake mit einem Zertifikatüberprüfungsfehler fehl.

For Relay client 26.4.2 configurations that connect through cloud.uipath.com, configure your proxy to allow long-lived HTTPS connections and WebSocket upgrades to cloud.uipath.com:443. If the proxy inspects TLS for cloud.uipath.com, install the proxy's signing CA in the OS trust store used by the Relay client.

For Relay client versions earlier than 26.4.2, configure your proxy to bypass TLS inspection for <region>-relay.uipath.com:443. PAC files, WPAD auto-discovery, and proxy chaining are not supported — set the proxy URL explicitly. When a proxy is detected, the prerequisite checks show via proxy in the output.

Sicherheit: Der Relay-Client entfernt Proxy-Kennwörter in Protokollen. In Umgebungsvariablen festgelegte Anmeldeinformationen können jedoch in Prozessauflistungen und Dateien von Systemeinheiten sichtbar sein. Verwenden Sie dedizierte Dienstanmeldeinformationen und beschränken Sie den Zugriff auf den Relay-Knoten entsprechend.

Vertrauenswürdige IPs konfigurieren (falls zutreffend)

Wenn Ihre Organisation den Zugriff nach IP-Adresse einschränkt, fügen Sie die NAT-IP des Geräts, auf dem der Relay-Client ausgeführt wird, zur Liste der vertrauenswürdigen IPs in der UiPath-Verwaltung hinzu. Der ausgehende Datenverkehr des Relay-Clients erreicht die Test Cloud von dieser IP-Adresse, sodass er ausdrücklich zugelassen werden muss.

Anweisungen finden Sie unter Hinzufügen vertrauenswürdiger IP-Bereiche.

Akzeptieren Sie die Lizenzvereinbarung

Bevor Sie den Relay-Client starten, müssen Sie die Lizenzvereinbarung akzeptieren. Wählen Sie eine der folgenden Methoden aus:

Option 1 (Umgebungsvariable) – Legen Sie die Umgebungsvariable LICENSE_AGREEMENT auf accept fest:

Linux

export LICENSE_AGREEMENT=accept

Windows

$env:LICENSE_AGREEMENT=accept

Option 2 (Inline-Parameter) – Fügen Sie --accept-license-agreement an den Befehl relay start an:

./relay start --config "<your-config>" --accept-license-agreement

Einrichtungshandbücher

Produktionsbereitstellungen finden Sie im Plattformhandbuch für Ihr Betriebssystem – es behandelt die Verzeichnisstruktur, die Dienstverwaltung, die Konfiguration des Sicherheitsrahmens und die Deinstallationsverfahren:

Plattform	Anleitung (Guide)
Linux	Bereitstellen des Relay-Clients unter Linux
Windows	Bereitstellen des Relay-Clients unter Windows
Container	Bereitstellen des Relay-Clients als Container

Betrieb

Widerstandsfähigkeit der Verbindung

Der Relay-Client verwaltet den Tunnel automatisch:

• Heartbeats Standardmäßig alle 30 Sekunden (konfigurierbar über --heartbeat-interval, mindestens 10 Sekunden). Das Tunnel-Timeout ist das 3-fache des Heartbeat-Intervalls. Verringern Sie das Intervall, wenn Ihre Firewall, Ihr Proxy oder NAT inaktive TCP-Verbindungen vor 30 Sekunden verwirft:

  relay start --config "<config>" --heartbeat-interval 10
  relay restart <id> --heartbeat-interval 10
  

• Automatisches Wiederherstellen der Verbindung beim Trennen mithilfe einer exponentiellen Backoff-Skalierung auf 20-Sekunden-Intervalle.
• Automatischer Neustart des Dienstes , wenn der Prozess abstürzt, verwaltet von systemd unter Linux und Windows Service Control Manager unter Windows.
• Autostart des Dienstes beim Systemneustart.

Proaktive Verbindung erneut herstellen

Einige Netzwerke – hinter einem Unternehmensproxy, einem Lastausgleich oder einer Firewall mit einem Timeout bei Inaktivität der Verbindung – beenden im Hintergrund langlebige TLS-Verbindungen. Proaktive erneute Verbindung stellt die Steuerelementverbindung nach einem festen Zeitplan wieder her, um dies zu verhindern.

Aktivieren Sie es mit dem Flag --reconnect-interval :

relay start --config "<config>" --reconnect-interval 1800

Das effektive Minimum beträgt 1800 Sekunden (30 Minuten). Legen Sie das Intervall auf etwa die Hälfte des Inaktivitäts-Timeouts Ihres Netzwerkgeräts fest – z. B. 1800 Sekunden für ein 60-minütiges Firewall-Timeout. Lassen Sie in stabilen Netzwerken ohne Zeitüberschreitung bei Inaktivität die Verbindung deaktiviert.

• Gleitende Entleerung. Wenn das Intervall abläuft, akzeptiert der Relay-Client keine neue Arbeit mehr und wartet auf den Abschluss von In-Flight-Verbindungen – bis zu einem 300-Sekunden-Timeout –, bevor die alte Verbindung geschlossen und eine neue geöffnet wird. Anforderungen, die sich bei Erreichen des Timeouts für die Entleerung noch in Bearbeitung befinden, werden beendet.

• Hohe Verfügbarkeit (High Availability). Wenn mehrere Relay-Clients in derselben Gruppe bereitgestellt werden, koordinieren sie sich, sodass jeweils nur ein Client per Drain ausgeführt wird. Die Gruppe stellt weiterhin den Datenverkehr während jedes Wiederverbindungszyklus bereit.

• Zeichen dafür, dass eine proaktive erneute Verbindung erforderlich ist: Protokolle zeigen regelmäßige unexpected EOF -Fehler oder stille Trennungen trotz eines stabilen zugrunde liegenden Netzwerks an – normalerweise verursacht durch eine 30-60-minütige Leerlaufzeitüberschreitung auf einer Firewall, einem Proxy oder einem Lastausgleich.

Die Konfiguration neu laden

relay reload <id>

Ruft die Proxykonfiguration von der Test Cloud ab und wendet sie ohne Neustart an. Cloud-seitige Änderungen – neue Endpunkte, aktualisierte Zustandsprüfungspfade – werden automatisch an einen laufenden Relay-Client gesendet und erfordern in der Regel kein Neuladen. Verwenden Sie diesen Befehl nur als Ausweichlösung, wenn ein neu hinzugefügter Endpunkt 404 zurückgibt.

Protokollierung

Einstellung	Wert
Standardebene	info
Rotation	Daily
Aufbewahrung	7 Tage
Protokolldatei	relay.log (aktuell), relay.YYYYMMDD-HHMMSS.log (gerotiert)

Überschreiben Sie die Standardprotokollebene mit --log-level trace/debug/info/warn/error. Überschreiben Sie im Relay-Client 26.4.2 oder höher die rotierte Protokollaufbewahrung mit --log-retention-days <days> auf relay start oder relay restart; die Mindestaufbewahrung beträgt 7 Tage.

Befehlsreferenz

Relay-Start

Stellen Sie einen neuen Relay-Client bereit und starten Sie ihn als Hintergrunddienst.

Konfiguration (eine erforderlich)

• -c, --config <string> – Inline-Base64-codierte Konfigurationszeichenfolge.
• --config-file <path> – Pfad zu einer Datei, die die Konfigurationszeichenfolge enthält. Empfohlen – hält das Geheimnis aus dem Shell-Verlauf heraus.

Abstimmung (optional)

• --heartbeat-interval <sec> – Tunnel-Heartbeat-Intervall. Standardmäßig: 30. Mindestens 10. Die Tunnel-Timeout ist 3-mal diesen Wert. Niedriger, wenn Ihre Firewall, NAT oder Proxy TCP im Leerlauf vor 30 Sekunden auslöst.
• --reconnect-interval <sec> – proaktives Reconnect-Intervall. Standard: 0 (deaktiviert); effektives Minimum 1800 (30 Minuten), wenn festgelegt.
• --log-level <level> – trace, debug, info, warn oder error. Standardmäßig: info.
• --log-retention-days <days> – Anzahl der Tage, für die rotierte Protokolldateien aufbewahrt werden sollen. Standardmäßig: 7. Mindestens 7. Erfordert den Relay-Client 26.4.2 oder höher.
• -d, --detach=false – werden im Vordergrund anstatt als Hintergrunddienst ausgeführt. Nützlich für das Debuggen von Startproblemen.

Nicht standardmäßige Installationspfade (optional)

• --data-dir <path> – Konfigurationsverzeichnis.
• --logs-dir <path> – Protokolldateiverzeichnis.
• --bin-dir <path> – Binäres Installationsverzeichnis.

Nur Linux

• --user-mode – Installieren Sie als systemd-Benutzerdienst (kein sudo erforderlich, verwendet XDG-Pfade).

Nur Windows

• --service-account <DOMAIN\user> – Führen Sie den Windows-Dienst unter einem bestimmten Konto aus. Die Standardeinstellung ist LocalSystem.
• --service-account-password <password> – Kennwort für --service-account.

Relay-Neustart

Stop and restart the Relay client service. Detects updated binaries and applies service definition changes.

The following flags can be overridden at restart time (all default to unchanged unless noted):

• --config / --config-file – ersetzen Sie die Clientkonfiguration.
• --accept-license-agreement – Akzeptieren Sie die Lizenzvereinbarung während des Neustarts, was nützlich ist, wenn Sie einen älteren installierten Dienst aktualisieren, der die Lizenzannahme nicht beibehalten hat.
• --log-level – Ändern Sie die Protokollebene.
• --logs-dir <path> – Verschieben Sie das Protokollverzeichnis des installierten Dienstes. Erfordert den Relay-Client 26.4.2 oder höher.
• --log-retention-days <days> – Ändern Sie die rotierte Protokollaufbewahrung. Mindestens 7; Übergeben Sie -1 um unverändert zu lassen. Erfordert den Relay-Client 26.4.2 oder höher.
• --heartbeat-interval – Ändern Sie das Heartbeat-Intervall. Mindestens 10; Übergeben Sie 0 um unverändert zu lassen.
• --reconnect-interval – Ändern Sie das Intervall für die proaktive Wiederverbindung. Mindestens 1800 (30 Minuten), wenn festgelegt. Übergeben Sie 0 um sie zu deaktivieren, oder -1 um unverändert zu bleiben.

Relay-Protokolle

Protokollausgabe für einen Relay-Client anzeigen.

• -f, --follow – kontinuierlich neue Protokollzeilen streamen.
• -n, --lines <N> – Anzahl der Zeilen ab dem Ende. Standardmäßig: 50.

Relay-Liste

Alle Relay-Clients auf dieser Maschine mit Status, Version, Erstellungs- und Aktualisierungszeitstempeln sowie Gruppenname anzeigen, sofern verfügbar. Lange Gruppennamen werden in der Tabellenausgabe abgeschnitten.

• --json – Ausgabe einer JSON-Ausgabe für die Automatisierung und Skripterstellung, einschließlich vollständiger Gruppennamen.

Relay-Beschreibung (Relay-Client 26.4.2 oder höher)

Zeigen Sie detaillierte Informationen für einen Relay-Client an, einschließlich Gruppen-ID und -name, geheime ID, Status, Version, Dienstmodus und ausführbarer Pfad, konfigurierte Heartbeat- und erneute Verbindungsintervalle, Protokollebene, lokale Pfade und Zeitstempel.

• --json – Ausgabe einer JSON-Ausgabe für die Automatisierung und Skripterstellung.

Relay-Neuladen

Rufen Sie die Proxykonfiguration erneut aus der Test Cloud ab und wenden Sie sie ohne Neustart an. Verwenden Sie sie als Ausweichlösung, wenn ein neu hinzugefügter Endpunkt 404 zurückgibt.

Relay anhalten

Beenden Sie den Relay-Clientdienst. Konfiguration und Anmeldeinformationen werden beibehalten – der Relay-Client kann später neu gestartet werden.

Relay löschen

Halten Sie den Dienst an, melden Sie sich bei der Test Cloud ab und entfernen Sie die gesamte lokale Konfiguration und Anmeldeinformationen.

• -f, --force – lokal ohne Cloud-Deregistrierung entfernen. Zu verwenden, wenn Anmeldeinformationen nicht lesbar sind oder cloudseitige Ressourcen bereits gelöscht wurden.

Relay-Supportpaket [ID]

Sammeln Sie ein bearbeitetes Archiv mit Konfigurations-, Protokoll- und Systemmetadaten für ein UiPath-Support-Ticket.Lassen Sie [id] weg, um alle Relay-Clients auf dem Gerät zu bündeln.Anmeldeinformationen und Verschlüsselungsschlüssel sind nie enthalten. Vollständige Details finden Sie unter Relay-Fehlerbehebung.

Relay-Version

Geben Sie die Relay-Clientversion, das Builddatum und den Git Commit-Hash aus.

Virenschutz und Endpunktsicherheit

If your organization runs endpoint protection software, add exclusions for the relay binary and its data directory to prevent the Relay client from being blocked or quarantined. For Relay client 26.4.2 configurations that connect through cloud.uipath.com, allow cloud.uipath.com:443.

For Relay client versions earlier than 26.4.2, configure TLS-inspecting proxies, DLP appliances, and IDS/IPS systems to bypass inspection for <region>-relay.uipath.com:443.

Ziel (Destination)	Port	Protokoll	Aktion
cloud.uipath.com	443	https	Zulassen
<region>-relay.uipath.com	443	TLS	Erlauben und umgehen Sie die TLS-Prüfung für Relay-Client-Versionen vor 26.4.2