Déploiement du client de relais

Installez et démarrez le client Relay sur une machine à l'intérieur de votre réseau pour établir le tunnel sortant vers Test Cloud. Avant de commencer, configurez un groupe Relay et préparez la chaîne de configuration du client.

Prérequis

Prérequis matériels

Profil	vCPU	RAM	Groupes de relais	Points de terminaison par groupe	Use case
Standard	1	2 Go	Jusqu’à 10	Jusqu’à 50	La plupart des déploiements
Grande	2	4 Go	10+	Jusqu’à 50	Environnements à haut débit ou à grande échelle

Il s'agit de la configuration minimale requise pour le processus du client de relais. Si la machine exécute d’autres charges de travail, enregistrez des ressources supplémentaires en conséquence.

Prérequis pour le disque

Profil	Disque libre minimum
Standard (1 à 10 groupes)	200 Mo
Grand (au moins 10 groupes)	1 Go

Systèmes d'exploitation pris en charge

Architecture	Linux	Windows
x86_64	Pris en charge	Pris en charge
ARM64	Pris en charge	Pris en charge

Configuration requise pour le réseau

Le client de relais nécessite une connectivité sortante uniquement. Aucune règle de pare-feu entrant n’est nécessaire.

À partir du client de relais 26.4.2, les nouvelles configurations de client de relais peuvent connecter le tunnel persistant via l'URL Automation Cloud standard, cloud.uipath.com. Ces configurations ne nécessitent pas une liste d’autorisation de nom d’hôte de relais spécifique à une région pour le tunnel.

Configuration du client de relais	Protocole	Port	Destination	Autorisation TLS requise	Objectif
Client de relais 26.4.2 ou version ultérieure	HTTPS/WSS	443	cloud.uipath.com	Non requis	Authentification, enregistrement du Relay et tunnel persistant
Versions de client de relais antérieures à 26.4.2	TLS	443	<region>-relay.uipath.com	Requis	Tunnel persistant

Les versions du client de relais antérieures à 26.4.2 continuent de fonctionner avec les noms d’hôte de relais régionaux. Conservez ces noms d'hôtes dans la liste d'autorisation jusqu'à ce que vous passiez au client de relais 26.4.2 ou à une version ultérieure, et que vous vous connectiez via cloud.uipath.com.

Pour les versions de client Relay antérieures à 26.4.2, remplacez <region> par la région de votre locataire Test Cloud.

Region	Nom d'hôte du serveur de relais
us	us-relay.uipath.com
UE	eu-relay.uipath.com
Canada	ca-relay.uipath.com
Suisse	ch-relay.uipath.com
Australie	au-relay.uipath.com
Singapour	sg-relay.uipath.com
Japon	jp-relay.uipath.com
Corée du Sud	kr-relay.uipath.com
UAE	ae-relay.uipath.com
Royaume-Uni	uk-relay.uipath.com
GxP UE	gxp-eu-relay.uipath.com
GxP US	gxp-us-relay.uipath.com

Remarque :

Contactez l’assistance UiPath pour confirmer le nom d’hôte du serveur de relais si votre région de locataire n’est pas répertoriée ci-dessus.

Choisissez la région qui correspond à votre région de locataire UiPath Cloud, et non l'emplacement physique du nœud Relay. Par exemple, si votre locataire est enregistré dans la région États-Unis, utilisez us-relay.uipath.com même si le relais s'exécute dans une zone différente. Les configurations du client de relais 26.4.2 qui se connectent via cloud.uipath.com n’utilisent pas ce nom d’hôte régional.

Latency considerations

Considérations sur la latence: étant donné que le trafic passe par UiPath Cloud → serveur de relais → nœud de relais → service local, placer le nœud de relais à proximité géographique de la région de votre locataire minimise le temps d’aller-retour et améliore le débit global.

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.

Versions de client de relais antérieures à 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.

La machine exécutant le client de relais doit également avoir un accès réseau direct à tous les services locaux que vous prévoyez d'exposer. Planifiez en conséquence le placement du client de relais.

Important :

Le nœud de relais doit être en mesure de résoudre le nom d'hôte et d'ouvrir une connexion au port enregistré pour chaque point de terminaison de son groupe de relais au moment du runtime. Le chemin de routage est flexible - une route réseau directe, un proxy de sortie d'entreprise ou un hôte intermédiaire sont tous acceptables - tant que la connexion réussit à partir du nœud de Relay. Planifiez l'emplacement de sorte que chaque point de terminaison du groupe reste accessible.

Bande passante

Le canal de contrôle (pulsations et authentification) utilise environ 1 à 2 Ko/minute lorsqu’il est inactif. Le trafic de données s'adapte au volume de demandes que vos services cloud envoient aux points de terminaison locaux: le Relay agit comme un tunnel transparent sans frais généraux supplémentaires au-delà du TLS et d'un structuration WebSocket léger pour les connexions cloud.uipath.com .

Vérifier la connectivité

Avant d’installer le client de relais, confirmez que le trafic sortant sur le port 443 est autorisé vers les destinations requises pour votre configuration.

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

Un résultat réussi affiche TcpTestSucceeded : True sous Windows et succeeded sous Linux. Si une vérification requise échoue, examinez vos règles de pare-feu. Pour les configurations du client de relais 26.4.2 qui se connectent via cloud.uipath.com, confirmez que les mises à niveau de WebSocket sont autorisées; pour les versions de client de relais antérieures à 26.4.2, confirmez que l’authentification unique TLS est configurée pour le nom d’hôte du serveur de relais.

Configurer un proxy (le cas échéant)

Si votre réseau achemine le trafic sortant via un proxy, définissez les variables d’environnement suivantes avant d’exécuter relay start. Le client de relais applique le proxy à toutes les connexions sortantes.

Variable	Objectif
HTTPS_PROXY / https_proxy	URL du proxy (première vérification)
HTTP_PROXY / http_proxy	URL du proxy (de secours)
NO_PROXY / no_proxy	Hôtes ou domaines séparés par des virgules qui contournent le proxy

L’URL du proxy doit utiliser l’un de ces schémas: http://, https://, socks5:// ou ntlm://. Format: scheme://[user:password@]host:port.

Pour les https:// proxys: le client de relais valide le certificat TLS du proxy par rapport au magasin de confiance du système d’exploitation. Si votre proxy utilise une autorité de certification d’entreprise ou auto-signée, ajoutez cette autorité de certification au magasin approuvé de la machine du client de relais avant de démarrer le relais; sinon, l'établissement de la liaison TLS échoue avec une erreur de vérification du certificat.

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.

Sécurité: le client de relais caviarde les mots de passe proxy dans les journaux. Cependant, les informations d'identification définies dans les variables d'environnement peuvent être visibles dans les listes de processus et les fichiers d'unités système. Utilisez des informations d’identification de service dédiées et restreignez l’accès au nœud Relay en conséquence.

Configurer les IP approuvées (le cas échéant)

Si votre organisation restreint l'accès par adresse IP, ajoutez l'IP NAT de la machine exécutant le client Relay à la liste d'IP approuvées dans Administration UiPath. Le trafic sortant du client Relay atteint Test Cloud à partir de cette adresse IP, vous devez donc l'autoriser explicitement.

Pour obtenir des instructions, consultez Ajouter des plages d'adresses IP approuvées.

Accepter le contrat de licence

Avant de démarrer le client de relais, vous devez accepter le contrat de licence. Choisissez l’une des méthodes suivantes:

Option 1 (variable d'environnement) - Définissez la variable d'environnement LICENSE_AGREEMENT pour accepter:

Linux

export LICENSE_AGREEMENT=accept

Windows

$env:LICENSE_AGREEMENT=accept

Option 2 (paramètre en ligne) : Ajoutez --accept-license-agreement à la commande relay start :

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

Guides de configuration

Pour les déploiements de production, reportez-vous au guide de la plateforme de votre système d'exploitation ; il couvre la structure des répertoires, la gestion des services, la configuration du cadre de sécurité et les procédures de désinstallation :

Plate-forme	Guide
Linux	Déploiement du client de relais sur Linux
Windows	Déploiement du client de relais sous Windows
Conteneur	Déploiement du client de relais en tant que conteneur

Opérations

Résilience de la connexion

Le client de relais maintient automatiquement le tunnel:

• Pulsation toutes les 30 secondes par défaut (configurable via --heartbeat-interval, minimum 10 secondes). Le délai d'expiration du tunnel est de 3 × l'intervalle des pulsations. Réduisez l'intervalle si votre pare-feu, votre proxy ou NAT abandonne les connexions TCP inactives avant 30 secondes:

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

• Reconnexion automatique à la déconnexion à l'aide d'une mise à l'échelle exponentielle du retrait à des intervalles de 20 secondes.
• Redémarrage automatique du service si le processus se bloque, géré par systemd sous Linux et Windows Service Control Manager sous Windows.
• Démarrage automatique du service au redémarrage du système.

Reconnexion proactive

Certains réseaux, derrière un proxy d’entreprise, un équilibreur de charge ou un pare-feu avec un délai d’expiration de connexion inactif, mettent fin en mode silencieux aux connexions TLS de longue durée. La reconnexion proactive rétablit la connexion de contrôle selon une planification fixe pour éviter cela.

Activez-le avec l'indicateur --reconnect-interval :

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

La durée minimale effective est de 1 800 secondes (30 minutes). Définissez l'intervalle sur la moitié environ du délai d'inactivité de votre appareil réseau, par exemple 1 800 secondes pour un délai d'expiration du pare-feu de 60 minutes. Laissez cette option désactivée sur les réseaux stables sans délai d’inactivité pour la connexion.

• Vidage en douceur. Lorsque l'intervalle s'est écoulé, le client de relais cesse d'accepter le nouveau travail et attend la fin des connexions en vol (jusqu'à expiration d'un délai de drainage de 300 secondes) avant de fermer l'ancienne connexion et d'en ouvrir une nouvelle. Les requêtes encore en cours lorsque le délai d’expiration du drainage est atteint sont terminées.

• Haute disponibilité. Lorsque plusieurs clients de relais sont déployés dans le même groupe, ils se coordonnent de sorte qu’un seul client se draine à la fois. Le groupe continue de servir le trafic pendant chaque cycle de reconnexion.

• Signe qu'une reconnexion proactive est nécessaire: les journaux affichent des erreurs périodiques unexpected EOF ou des déconnexions silencieuses malgré un réseau sous-jacent stable, généralement causé par un délai d'inactivité de 30 à 60 minutes sur un pare-feu, un proxy ou un équilibreur de charge.

Recharger la configuration

relay reload <id>

Récupère la configuration du proxy à partir de Test Cloud et l'applique sans redémarrer. Les modifications côté Cloud (nouveaux points de terminaison, chemins de vérification de l'état mis à jour) se propagent automatiquement vers un client Relay en cours d'exécution et ne nécessitent normalement pas de rechargement. Utilisez cette commande comme solution de secours uniquement si un point de terminaison nouvellement ajouté renvoie 404.

Journalisation

Paramètre	Valeur (Value)
Niveau par défaut	info
Rotation	Daily
Rétention	7 jours
Fichier journal (Log File)	relay.log (actuel), relay.YYYYMMDD-HHMMSS.log ( pivoté)

Remplacez le niveau de journalisation par défaut par --log-level trace/debug/info/warn/error. Dans le client de relais 26.4.2 ou version ultérieure, la rétention des journaux pivotés a été remplacée par --log-retention-days <days> sur relay start ou relay restart; la rétention minimale est de 7 jours.

Référence de commande

Début du relais

Enregistrez un nouveau client de relais et démarrez-le en tant que service d’arrière-plan.

Configuration (obligatoire)

• -c, --config <string> — chaîne de configuration encodée en base64 en ligne.
• --config-file <path> — chemin d'accès à un fichier contenant la chaîne de configuration. Recommandé: maintient le secret en dehors de l’historique du shell.

Ajustement (facultatif)

• --heartbeat-interval <sec> — intervalle de pulsation du tunnel. 30 par défaut. 10 minimum. Le délai d’expiration du tunnel est de 3 × cette valeur. Réduit si votre pare-feu, NAT ou proxy désactive le TCP inactif avant 30 secondes.
• --reconnect-interval <sec> — intervalle de reconnexion proactive. 0 par défaut (désactivé); minimum efficace 1800 (30 minutes) lorsqu'il est défini.
• --log-level <level> — trace, debug, info, warn, ou error Par défaut info.
• --log-retention-days <days> — nombre de jours pendant lesquels conserver les fichiers journaux pivotés. 7 par défaut. 7 minimum. Nécessite le client de relais 26.4.2 ou une version ultérieure.
• -d, --detach=false — exécuté au premier plan plutôt qu'en tant que service d'arrière-plan. Utile pour déboguer les problèmes de démarrage.

Chemins d'installation non par défaut (facultatif)

• --data-dir <path> — répertoire de configuration.
• --logs-dir <path> — répertoire du fichier journal.
• --bin-dir <path> — répertoire d'installation binaire.

Linux uniquement

• --user-mode — installer en tant que service utilisateur systemd (aucun sudo requis, utilise des chemins XDG).

Windows uniquement

• --service-account <DOMAIN\user> — exécutez le service Windows sous un compte spécifique. La valeur par défaut est LocalSystem.
• --service-account-password <password> — mot de passe pour --service-account.

Redémarrage du relais

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 — remplace la configuration client.
• --accept-license-agreement — accepte le contrat de licence lors du redémarrage, utile lors de la mise à niveau d'un service installé plus ancien qui ne persistait pas l'acceptation de la licence.
• --log-level — modifiez le niveau de journalisation.
• --logs-dir <path> — déplacez le répertoire du journal du service installé. Nécessite le client de relais 26.4.2 ou une version ultérieure.
• --log-retention-days <days> — modifiez la rétention du journal pivoté. 7 minimum; transmettez -1 pour laisser inchangé. Nécessite le client de relais 26.4.2 ou une version ultérieure.
• --heartbeat-interval — modifiez l'intervalle des pulsations. 10 minimum; transmettez 0 pour laisser inchangé.
• --reconnect-interval — modifier l'intervalle de reconnexion proactive. Minimum de 1800 (30 minutes) lorsque défini. Saisissez 0 pour désactiver ou -1 pour laisser inchangé.

journaux de relais

Afficher la sortie du journal pour un client de relais.

• -f, --follow — diffuser de nouvelles lignes de journal en continu.
• -n, --lines <N> — nombre de lignes à partir de la fin. Par défaut 50.

liste de Relay

Affichez tous les clients du relais sur cette machine avec le statut, la version, les horodatages de création et de mise à jour, ainsi que le nom du groupe lorsqu'il est disponible. Les noms de groupe longs sont tronqués dans la sortie de la table.

• --json — émettez une sortie JSON pour l'automatisation et les scripts, y compris les noms de groupe complets.

Description du relais (Client de relais 26.4.2 ou version ultérieure)

Affichez des informations détaillées pour un client de relais, y compris l’ID et le nom du groupe, l’ID du secret, le statut, la version, le mode service et le chemin exécutable, la pulsation et les intervalles de reconnexion configurés, le niveau de journalisation, les chemins locaux et les horodatages.

• --json — émettez une sortie JSON pour l'automatisation et les scripts.

Rechargement du relais

Récupérez la configuration du proxy à partir de Test Cloud et appliquez-la sans redémarrer. Utilisez comme solution de secours si un point de terminaison nouvellement ajouté renvoie 404.

arrêt de Relay

Arrêtez le service client de relais. La configuration et les informations d'identification sont conservées — le client de relais peut être redémarré ultérieurement.

suppression du relais

Arrêtez le service, désinscrivez-vous de Test Cloud et supprimez toutes les configurations et les identifiants locaux.

• -f, --force — supprimer localement sans désenregistrement du Cloud. À utiliser lorsque les informations d’identification ne sont pas lisibles ou que les ressources côté cloud ont déjà été supprimées.

pack d’assistance de Relay [id]

Collectez une archive anonymisée de configuration, de journaux et de métadonnées système pour un ticket d'assistance UiPath. Omettez [id] pour regrouper tous les clients Relay sur la machine. Nous n'incluons jamais les identifiants ni les clés de chiffrement. Consultez Résolution des problèmes de Relay pour plus de détails.

Version du relais

imprimez la version du client de relais, la date de création et le hachage de validation git.

Sécurité antivirus et des points de terminaison

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.

Destination	Port	Protocole	Action
cloud.uipath.com	443	https	Autoriser
<region>-relay.uipath.com	443	TLS	Autoriser + contourner l’inspection TLS pour les versions de client de relais antérieures à 26.4.2