Bereitstellen des Relay-Clients unter Windows

Diese Seite behandelt Windows-spezifische Details zur Einrichtung von Produktion. Plattformübergreifende Voraussetzungen und Netzwerkanforderungen finden Sie unter Bereitstellen des Relay-Clients.

Anforderungen des Betriebssystems

Der Relay-Client verwendet den Windows Service Control Manager (SCM) für die Installation und Verwaltung seines Hintergrunddiensts. SCM ist in alle unterstützten Windows-Versionen integriert – es ist keine zusätzliche Software erforderlich.

Edition	Mindestversion
Windows-Server	2019
Windows-Desktop	10 Unternehmen

Zusätzliche Anforderungen

• PowerShell 5.1+ – standardmäßig enthalten; Wird für die Dienstverwaltung verwendet (Get-Service, Test-NetConnection). Überprüfen: $PSVersionTable.PSVersion.
• Administratorrechte – erforderlich, um mit SCM für die Installation, das Starten, Anhalten und Löschen des Dienstes zu interagieren; in C:\ProgramData\UiPathRelay\ schreiben; kopieren Sie die Binärdatei nach C:\Program Files\UiPathRelay\.

Standardmäßig wird der Dienst als LocalSystem ausgeführt. Um unter einem bestimmten Konto auszuführen, verwenden Sie --service-account zur Startzeit – siehe Dienstkonto und Berechtigungen.

Checkliste vor der Installation

System

• Windows Server 2019+ oder Windows 10 Enterprise+
• PowerShell 5.1 oder höher
• Administratorzugriff auf die Zielmaschine
• Mindestens 200 MB freier Speicherplatz

Netzwerk

• Für den Relay-Client 26.4.2 oder höher ist ausgehendes HTTPS (Port 443) nach cloud.uipath.com zulässig, einschließlich WebSocket-Upgrades
• Für Relay-Client-Versionen vor 26.4.2 ist ausgehendes TLS (Port 443) zu <region>-relay.uipath.com zulässig und TLS-Password ist konfiguriert
• Der Relay-Knoten hat Netzwerkzugriff auf alle lokalen Dienste, die Sie verfügbar machen möchten

Sicherheit

• Dienstkonto erstellt (wenn LocalSystem nicht verwendet wird) – siehe Dienstkonto und Berechtigungen
• Ausnahmen von Windows Edge und Antivirenprogrammen geplant – siehe Virenschutz und Endpunktschutz

Konfiguration

• Relay-Gruppe erstellt und Client-Konfigurationszeichenfolge bereit – siehe Konfigurieren einer Relay-Gruppe

Validierungsbefehle (in PowerShell ausgeführt):

# Check PowerShell version (must be 5.1+)
$PSVersionTable.PSVersion

# Verify Administrator access
([Security.Principal.WindowsPrincipal][Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)

# Check available disk space
Get-PSDrive C | Select-Object Used, Free

Installieren

1. Herunterladen und Extrahieren

Laden Sie das Relay-Client-Archiv aus dem UiPath Customer Portal herunter.

Architektur	Archiv (Archive)
x86_64	Relay_windows_amd64.zip
ARM64	Relay_windows_arm64.zip

Extrahieren Sie das ZIP-Archiv. Er enthält eine einzelne relay.exe -Binärdatei, die ausgeführt werden kann.

2. Starten

Öffnen Sie PowerShell als Administrator, bevor Sie einen Startbefehl ausführen.

Sie können die Client-Konfigurationszeichenfolge (über die UiPath-Verwaltung – siehe Konfigurieren einer Relay-Gruppe) auf zwei Arten bereitstellen:

Option A – Inline. Übergeben Sie die Konfigurationszeichenfolge direkt. Keine Datei zum Erstellen oder Bereinigen:

.\relay.exe start --config "<your-config>"

Option B – Datei. Speichern Sie die Konfiguration in einer Datei und verweisen Sie dann darauf. Empfohlen – hält das Geheimnis aus dem Shell-Verlauf heraus:

Set-Content -Path "config.txt" -Value "<your-config>"
.\relay.exe start --config-file C:\path\to\config.txt

Die Flags --config und --config-file schließen sich gegenseitig aus. Um im Vordergrund statt als Hintergrunddienst ausgeführt zu werden (nützlich für das Debuggen), übergeben Sie --detach=false.

Der Relay-Client validiert die Verbindung, authentifiziert sich mit OAuth, registriert sich bei der Test Cloud, lädt die Proxykonfiguration herunter und installiert einen Windows-Dienst – alles in einem einzigen Befehl.

Erwartete Ausgabe:

Running prerequisite checks...
  ✓ Directory permissions: OK
  ✓ Cloud portal connectivity: OK
✓ All prerequisite checks passed
Waiting for service to start...
  ✓ Service is running

✓ Relay is now running in the background.
Check status:
  PowerShell: Get-Service "Relay-<id>"
  Services:   services.msc (look for "Relay - <id>")

Während des Starts kopiert der Relay-Client automatisch die Binärdatei nach C:\Program Files\UiPathRelay\relay.exe. Alle Relay-Gruppen auf der Maschine teilen sich diese einzelne Binärdatei. Überschreiben Sie das Installationsverzeichnis mit --bin-dir.

So starten Sie unter einem benutzerdefinierten Dienstkonto statt unter LocalSystem:

.\relay.exe start --config-file C:\path\to\config.txt `
  --service-account "DOMAIN\svc-relay" `
  --service-account-password "password"

3. Überprüfen

.\relay.exe list

Ein fehlerfreier Client zeigt ● running in der Spalte Status an. Der angezeigte ID -Wert wird in allen nachfolgenden Befehlen verwendet (.\relay.exe stop <id>, .\relay.exe logs <id> usw.). Sie finden sie auch in der UiPath-Verwaltung auf der Seite mit den Details zur Relay-Gruppe.

Bestätigen Sie, dass der Tunnel eingerichtet ist, indem Sie die Protokolle auf login to server success überprüfen:

.\relay.exe logs <id> -f

Verwalten

Alle Verwaltungsbefehle erfordern Administrator PowerShell, mit Ausnahme von list und version.

Liste

Zeigt alle installierten Relay-Gruppen auf dieser Maschine mit Status, Version und Gruppenname an, wenn verfügbar. Erfordert keine Administratorrechte.

.\relay.exe list
.\relay.exe list --json

Beschreiben

Hinweis:

Verfügbar mit Relay-Client 26.4.2 und höher. Führen Sie .\relay.exe version aus, um Ihre installierte Version zu überprüfen.

Zeigt detaillierte Informationen für eine Relay-Gruppe an, einschließlich Diensteinstellungen, konfigurierter Pfade, Status, Version und Gruppenname, sofern verfügbar. Erfordert keine Administratorrechte.

.\relay.exe describe <id>
.\relay.exe describe <id> --json

Stoppen

Stoppt den Relay-Dienst. Konfiguration und Protokolle werden beibehalten – der Relay-Dienst kann später neu gestartet werden.

.\relay.exe stop <id>

Neustart und Upgrade

Startet den Relay-Dienst neu und ruft die neueste Proxykonfiguration aus der Test Cloud ab.

.\relay.exe restart <id>

Binäres Upgrade: Laden Sie das neue relay.exe herunter und führen Sie .\relay.exe restart <id> damit aus. Der Befehl „Neustart“ vergleicht die laufende Binärdatei mit der installierten Kopie per SHA256-Hash und aktualisiert die installierte Binärdatei automatisch, wenn sie sich unterscheiden.

Szenario	Befehl
In der Test Cloud hinzugefügte oder entfernte Endpunkte	.\relay.exe restart <id>
Rotation des geheimen Clientschlüssels – inline	.\relay.exe restart --config "<new-config>"
Rotation des geheimen Clientschlüssels – Datei	.\relay.exe restart --config-file new-config.txt
Änderung der Protokollebene	.\relay.exe restart <id> --log-level debug
Änderung des Protokollverzeichnisses oder der Aufbewahrung	.\relay.exe restart <id> --logs-dir "D:\MyCompany" --log-retention-days 30
Binäres Upgrade	Dann neue Binärdatei herunterladen .\relay.exe restart <id>

Wenn --config oder --config-file angegeben ist, ist das <id> -Argument optional – es wird aus der Konfiguration extrahiert.

Löschen

Stoppt den Dienst, meldet sich von der Test Cloud ab und entfernt alle lokalen Konfigurations- und Protokolldateien.

.\relay.exe delete <id>

So erzwingen Sie die lokale Bereinigung ohne Cloud-Deregistrierung – z. B. wenn Anmeldeinformationen verloren gehen oder die cloudseitige Relay-Gruppe bereits gelöscht wurde:

.\relay.exe delete <id> --force

Version

.\relay.exe version

Es gibt kein automatisches Upgrade. Zum Aktualisieren laden Sie die neue Binärdatei herunter und führen .\relay.exe restart <id> für jede Gruppe aus.

Verzeichnisstruktur

Alle Verzeichnisse werden bei der ersten Ausführung automatisch erstellt.

C:\Program Files\UiPathRelay\
  relay.exe                                  # Shared binary

C:\ProgramData\UiPathRelay\
  groups\<id>\
    client_config                            # OAuth credentials (encrypted via DPAPI)
    metadata.json                            # State, PID, install timestamps
    .credentials.key                         # Encryption key
  logs\<id>\
    relay.log                                # Current log
    relay.YYYYMMDD-HHMMSS.log                # Rotated logs

Der Name des Windows-Dienstes ist Relay-<id> und der Anzeigename (angezeigt in services.msc) ist Relay - <id>. Der Starttyp ist automatisch; Standardkonto ist LocalSystem.

Benutzerdefinierte Pfade

Überschreiben Sie die Standardverzeichnisse beim Installieren des Relay-Clients.

.\relay.exe start --config-file C:\path\to\config.txt `
  --bin-dir "D:\MyCompany\bin" `
  --data-dir "D:\MyCompany" `
  --logs-dir "D:\MyCompany"

Markieren	Standard	Beschreibung
--bin-dir	C:\Program Files\UiPathRelay	Verzeichnis für die freigegebene Binärdatei
--data-dir	C:\ProgramData	Stamm für Konfigurationsdaten
--logs-dir	C:\ProgramData	Stamm für Protokolldateien; kann mit geändert werden restart

Der Relay-Client fügt UiPathRelay\ unter den benutzerdefinierten Daten- und Protokollstammsätzen an:

--bin-dir  D:\MyCompany\bin  =>  D:\MyCompany\bin\relay.exe
--data-dir D:\MyCompany      =>  D:\MyCompany\UiPathRelay\groups\<id>\
--logs-dir D:\MyCompany      =>  D:\MyCompany\UiPathRelay\logs\<id>\

--bin-dir und --data-dir werden nur vom Befehl start akzeptiert. --logs-dir wird von start und restart akzeptiert. Andere Befehle (stop, delete, list) erkennen Pfade automatisch in der Konfiguration des installierten Dienstes.

Dienstkonto und Berechtigungen

Dieser Abschnitt gilt nur, wenn der Dienst unter einem benutzerdefinierten Konto anstelle des Standardkontos LocalSystem ausgeführt wird.

Erforderliche Benutzerrechte

Rechts	Beschreibung	Konfigurieren
SeServiceLogonRight	Anmelden als Dienst	Lokale Sicherheitsrichtlinie > Zuweisung von Benutzerrechten > Als Dienst anmelden

Konfigurieren Sie dies für Domänenumgebungen direkt über die Gruppenrichtlinie, um die Konsistenz zwischen den Servern sicherzustellen.

NTFS-Berechtigungen

Pfad	Erforderliche Berechtigungen
C:\Program Files\UiPathRelay\	Read & Execute
C:\ProgramData\UiPathRelay\	Lesen, Schreiben, Ändern
C:\ProgramData\UiPathRelay\logs\	Lesen, Schreiben, Ändern, Löschen

Über PowerShell

$account = "DOMAIN\svc-relay"

$acl = Get-Acl "C:\Program Files\UiPathRelay"
$rule = New-Object System.Security.AccessControl.FileSystemAccessRule($account, "ReadAndExecute", "ContainerInherit,ObjectInherit", "None", "Allow")
$acl.SetAccessRule($rule)
Set-Acl "C:\Program Files\UiPathRelay" $acl

$acl = Get-Acl "C:\ProgramData\UiPathRelay"
$rule = New-Object System.Security.AccessControl.FileSystemAccessRule($account, "Modify", "ContainerInherit,ObjectInherit", "None", "Allow")
$acl.SetAccessRule($rule)
Set-Acl "C:\ProgramData\UiPathRelay" $acl

Beginnend mit einem benutzerdefinierten Dienstkonto

.\relay.exe start --config-file C:\path\to\config.txt `
  --service-account "DOMAIN\svc-relay" `
  --service-account-password "password"

--service-account-password ist für Domänen- oder lokale Benutzerkonten erforderlich. Verwaltete Dienstkonten (gMSA) erfordern kein Kennwort.

Gruppenverwaltete Dienstkonten (gMSA)

# Install the gMSA on the server (run once per server)
Install-ADServiceAccount -Identity "gMSA-Relay$"

# Start the Relay client with gMSA (no password required)
.\relay.exe start --config-file config.txt --service-account "DOMAIN\gMSA-Relay$"

gMSAs rotieren Kennwörter automatisch und beseitigen einen Aufwand für die Verwaltung von Anmeldeinformationen.

Details zum Windows-Dienst

Der Dienststatus wird angezeigt

Über die Dienstkonsole

1. Öffnen Sie Ausführung (Win + R) und geben Sie services.msc ein.
2. Suchen Sie den Dienst mit dem Anzeigenamen Relay - <id>.
3. Use the context menu to start, stop, restart, or view properties.

Über PowerShell

# All Relay services
Get-Service "Relay-*"

# Detailed information
Get-Service "Relay-<id>" | Format-List *

# Service configuration (account, start mode)
Get-CimInstance Win32_Service -Filter "Name LIKE 'Relay-%'" | Select-Object Name, StartMode, State, StartName

Dienstwiederherstellung

Wenn sich der Relay-Client selbst als Dienst installiert, konfiguriert er die automatische Wiederherstellung:

• Erster Fehler: Neustart nach 10 Sekunden
• Zweiter Fehler: Neustart nach 30 Sekunden
• Nachfolgende Fehler: Neustart mit eskalierenden Verzögerungen

Um die Wiederherstellungseinstellungen zu überprüfen oder anzupassen: Öffnen Sie services.msc > klicken Sie mit der rechten Maustaste auf den Dienst > Eigenschaften > Registerkarte Wiederherstellung .

Ereignisanzeige

Verwenden Sie die Ereignisanzeige (eventvwr.msc), um Dienstprobleme zu diagnostizieren.

Protokoll (Log)	Pfad	Events
System	Windows-Protokolle > System	Start, Stopp, Absturz und Wiederherstellung des Dienstes (7000-Serie)
Anwendung	Windows-Protokolle > Anwendung	Anwendungsfehler

Relay-Ereignisse über PowerShell abfragen

Get-WinEvent -FilterHashtable @{LogName='System'; ID=7000,7009,7031,7034,7036,7045} -MaxEvents 100 |
  Where-Object { $_.Message -like '*Relay*' } |
  Format-Table TimeCreated, Id, Message -Wrap

Ereignis-ID	Bedeutung
7000	Dienst konnte nicht gestartet werden – überprüfen Sie die Kontoberechtigungen
7009	Timeout beim Warten auf Dienst – überprüfen Sie die Netzwerkkonnektivität
7031	Dienst ist abgestürzt und Wiederherstellungsaktion wurde durchgeführt – prüfen relay.log
7034	Dienst unerwartet beendet – prüfen Sie, ob die Ressourcen erschöpft sind
7045	Neuer Dienst installiert – bestätigt erfolgreiche Installation

Proxykonfiguration

Windows-Dienste erben Umgebungsvariablen vom System (HKLM). Legen Sie Proxyvariablen auf Maschinenebene fest, bevor Sie den Relay-Client starten:

[Environment]::SetEnvironmentVariable("HTTPS_PROXY", "http://proxy.corp.example.com:8080", "Machine")
[Environment]::SetEnvironmentVariable("NO_PROXY", "localhost,127.0.0.1,.corp.example.com", "Machine")
.\relay.exe start --config "<your-config>"

Das Festlegen von Proxyvariablen auf Benutzerebene reicht nicht aus – die Systemdienste ignorieren Umgebungsvariablen auf Benutzerebene.

So aktualisieren Sie den Proxy: Ändern Sie die Variable auf Systemebene und führen Sie .\relay.exe restart <id> aus.

So entfernen Sie den Proxy: [Environment]::SetEnvironmentVariable("HTTPS_PROXY", $null, "Machine") und dann .\relay.exe restart <id>.

Zu überprüfen: [Environment]::GetEnvironmentVariable("HTTPS_PROXY", "Machine").

Unterstützte Proxyschemas und Authentifizierung finden Sie im Abschnitt Proxy unter Bereitstellen des Relay-Clients.

Windows-Firewall

Wenn der ausgehende Datenverkehr durch die Windows-Firewall eingeschränkt wird, fügen Sie eine ausgehende Regel für die Relay-Client-Binärdatei hinzu.

Einstellung	Wert
Richtung	Ausgehend
Programm	C:\Program Files\UiPathRelay\relay.exe
Protokoll/Port	TCP/443
Profile	Domäne, Privat

Über PowerShell

New-NetFirewallRule -DisplayName "UiPath Relay - Outbound HTTPS" `
  -Direction Outbound `
  -Program "C:\Program Files\UiPathRelay\relay.exe" `
  -Protocol TCP `
  -RemotePort 443 `
  -Action Allow `
  -Profile Domain,Private

# Verify rule
Get-NetFirewallRule -DisplayName "UiPath Relay*" | Format-Table Name, Enabled, Direction, Action

Über GUI (Windows Edge-Firewall mit erweiterter Sicherheit):

1. Öffnen Sie wf.msc.
2. Ausgehende Regeln > Neue Regel auswählen.
3. Wählen Sie Programm aus und geben Sie Folgendes an: C:\Program Files\UiPathRelay\relay.exe.
4. Wählen Sie die Verbindung zulassen aus.
5. Anwenden auf Domäne und die Profile „Privat“ .
6. Benennen Sie die Regel: UiPath Relay - Outbound HTTPS.

Wenn Ihre Organisation Firewallregeln über eine Gruppenrichtlinie oder eine Firewall eines Drittanbieters verwaltet, wenden Sie sich an Ihren Windows-Administrator, um eine gleichwertige Regel hinzuzufügen.

Viren- und Endpunktschutz

Fügen Sie Ausdrücke für die Relay-Client-Binärdatei und ihre Datenverzeichnisse hinzu, um Interferenzen zu verhindern.

Typ	Pfad
Binär	C:\Program Files\UiPathRelay\relay.exe
Daten und Protokolle	C:\ProgramData\UiPathRelay\

Wenn Sie benutzerdefinierte Pfade über --bin-dir, --data-dir oder --logs-dir verwendet haben, schließen Sie stattdessen diese Pfade aus.

Windows Docker – über PowerShell

Add-MpPreference -ExclusionPath "C:\Program Files\UiPathRelay"
Add-MpPreference -ExclusionPath "C:\ProgramData\UiPathRelay"
Add-MpPreference -ExclusionProcess "relay.exe"

Windows Docker – über GUI

1. Öffnen Sie Windows-Sicherheit > Viren- und Bedrohungsschutz > Einstellungen verwalten.
2. Wählen Sie unter Ausschluss die Option Ausschluss hinzufügen oder entfernen aus.
3. Ordnerausnahmen hinzufügen: C:\Program Files\UiPathRelay\ und C:\ProgramData\UiPathRelay\.
4. Prozessausschluss hinzufügen: relay.exe.

Für den zentral verwalteten Endpunktschutz (CrowdStrike, Attended, Microsoft Edge für den Endpunkt über Intune/SCCM) arbeiten Sie mit Ihrem Sicherheitsadministrator zusammen, um die oben genannten Ausnahmen hinzuzufügen.

Deinstallieren

1. Alle Relay-Clients löschen ( .\relay.exe list verwenden, um installierte Gruppen anzuzeigen):

   .\relay.exe delete <id>
   

2. Entfernen Sie die freigegebene Binärdatei:

   Remove-Item "C:\Program Files\UiPathRelay" -Recurse
   

3. Entfernen Sie verbleibende Datenverzeichnisse:

   Remove-Item "C:\ProgramData\UiPathRelay" -Recurse
   

4. Entfernen Sie Windows Docker-Ausnahmen:

   Remove-MpPreference -ExclusionPath "C:\Program Files\UiPathRelay"
   Remove-MpPreference -ExclusionPath "C:\ProgramData\UiPathRelay"
   Remove-MpPreference -ExclusionProcess "relay.exe"
   

5. Entfernen Sie die Windows-Firewall-Regel:

   Remove-NetFirewallRule -DisplayName "UiPath Relay - Outbound HTTPS"
   

Regeln, die über eine Gruppenrichtlinie oder eine Firewall eines Drittanbieters hinzugefügt wurden, entfernen Sie zusammen mit Ihrem Windows-Administrator.

Fehlersuche und ‑behebung

Symptome	Ursache	Resolution
Dienst kann nicht gestartet werden	Unzureichende Berechtigungen	Öffnen Sie PowerShell als Administrator
permission denied	Es kann nicht in Programmdateien oder Programmdaten geschrieben werden	Überprüfen Sie den Administratorzugriff, oder verwenden Sie --bin-dir / --data-dir für beschreibbare Pfade
does not have the 'Log on as a service' right	Benutzerdefiniertes Konto fehlt SeServiceLogonRight	Gewähren Sie über „Lokale Sicherheitsrichtlinie“ > „Zuweisung von Benutzerrechten“ oder verwenden Sie eine Gruppenrichtlinie
not a valid Windows account	Falsches Format für --service-account	Verwenden Sie .\username für lokale Konten oder DOMAIN\username für Domänenkonten
marked for deletion /Dienst ausstehende Löschung	services.msc ein offenes Handle hat	services.msc schließen und erneut versuchen; neu starten, wenn das Problem weiterhin besteht
service is disabled	Über services.msc oder Gruppenrichtlinie deaktiviert	Erneut aktivieren: Set-Service -Name "Relay-<id>" -StartupType Automatic
file is locked by another process	Binärdatei, die während der Aktualisierung verwendet wird	Halten Sie zuerst den Relay-Clientdienst an und versuchen Sie es dann erneut
path exceeds Windows path length limit	Der Daten-/Protokollpfad ist länger als 260 Zeichen	Kürzere Pfade für --data-dir und --logs-dirverwenden
Virenschutzblockierung relay.exe	Binärdatei für Endpunktschutz in Quarantäne	Ausfälle hinzufügen (siehe Virenschutz und Endpunktschutz); Quarantäne überprüfen und wiederherstellen
Dienst wird ausgeführt, aber Tunnel nicht eingerichtet	Netzwerk- oder Authentifizierungsproblem	Prüfen Sie relay.log auf login to server Fehler; Überprüfen Sie die Verbindung zu cloud.uipath.com; Überprüfen Sie bei Relay-Client-Versionen vor 26.4.2 den TLS-Passdurchlauf zum regionalen Relay-Hostnamen
DPAPI decrypt failed	Maschinenidentität nach VM-Klonen oder Reimage geändert	Stellen Sie das Relay mit einer neuen Konfiguration von der UiPath-Verwaltung erneut bereit
Proxy wird vom Dienst nicht verwendet	Proxy auf Benutzerebene festgelegt, nicht auf Systemebene	Legen Sie HTTPS_PROXY auf Maschinenebene fest (siehe Proxykonfiguration); Starten Sie den Dienst neu

Diagnosebefehle

# Real-time logs
.\relay.exe logs <id> -f

# Service details
Get-Service "Relay-<id>" | Format-List *

# Connectivity test
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

Informationen zu Authentifizierungs- und Verbindungsfehlern, die plattformübergreifend genutzt werden, finden Sie unter Fehlerbehebung.

Schnellreferenz

Aktion	Befehl
Starten	.\relay.exe start --config-file config.txt
Stoppen	.\relay.exe stop <id>
Neustart/Upgrade	.\relay.exe restart <id>
Löschen	.\relay.exe delete <id>
Löschen (erzwingen)	.\relay.exe delete <id> --force
Liste	.\relay.exe list
Beschreiben	.\relay.exe describe <id>
Protokolle	.\relay.exe logs <id> -f
Status des Dienstes	Get-Service "Relay-<id>"
Dienstekonsole	services.msc