在 Linux 上部署中继客户端

在 Linux 上将 Relay 客户端作为 systemd 服务部署，以此在您的网络和 Test Cloud 之间建立出站隧道。

This page covers production setup details specific to Linux. For cross-platform prerequisites and network requirements, see Deploying the Relay client.

操作系统要求

中继客户端需要systemd 229 或更高版本。待验证： systemctl --version 。

分布	最低版本
Ubuntu	20.04 LTS (Focal)
发行说明	10（巴星）
Red Hat Enterprise Linux	8
Amazon Linux	2023 年
SUSE Linux 企业版服务器	15
Oracle Linux	8

任何使用 systemd 229+ 的 Linux 发行版预计都可以使用。对于没有 systemd 的环境，中继客户端可以在前台模式 ( --detach=false ) 下运行，但您需要负责流程管理、自动启动和恢复。

所需权限：需要sudo （根用户）访问权限才能安装 systemd 服务 ( /etc/systemd/system/ )，创建默认的数据和日志目录，以及将二进制文件复制到/usr/local/bin/ 。对于无根安装，请参阅用户模式。

先决条件

系统

• 支持 systemd 229+ 的 Linux 发行版
• sudo (root) access, or plan to use --user-mode
• 至少 200 MB 可用磁盘空间
• If you use a supported TCP-based connection that requires the on-prem executor:
  • Review the recommended host and executor capacity
  • A Java 21 or later JRE or JDK, either on the PATH or passed with --onprem-executor-java-home. An existing installation works.

网络

• 对于中继客户端 26.4.2 或更高版本，允许到 cloud.uipath.com 的出站 HTTPS（端口 443），包括 WebSocket 升级
• 对于 26.4.2 之前的中继客户端版本，允许到 <region>-relay.uipath.com 的出站 TLS（端口 443），并配置了 TLS 直通
• Relay host can resolve and connect to every registered HTTP or HTTPS endpoint, and to the host and port of each supported TCP-based endpoint

安全性

• SELinux / AppArmor / fapolicyd exclusions configured (if applicable) (see Security frameworks)
• If you use the on-prem executor: an administrator-owned dependencies directory and Java installation that no unprivileged account can write. The executor loads code from both, with the privileges of the Relay service account

配置

• Relay Group created and client configuration string ready (see Configuring a Relay group)

Validate prerequisites

运行以下命令：

# Check systemd version (must be 229+)
systemctl --version

# Verify sudo access
sudo -v

# Check available disk space
df -h /var/lib

# On-prem executor only: Java 21+ on PATH, or pass --onprem-executor-java-home
java -version

安装

1. 下载并提取

从UiPath Customer Portal下载适用于您的架构（x86_64 或 ARM64）的中继客户端存档。

unzip relay_linux_amd64.zip && chmod +x relay

Starting with Relay client 26.4.3, the archive also contains onprem-executor.jar. Leave it next to the relay binary in the extracted directory, and run installation or upgrade commands from that directory.

2. 开始

You can provide the client configuration string (generated in UiPath Administration, as described in Configuring a Relay group) in two ways:

Option A: Inline. Pass the configuration string directly. No file to create or clean up:

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

Option B: File. Save the configuration to a file, then reference it. This is the recommended option because it keeps the secret out of shell history:

sudo ./relay start --config-file /path/to/config.txt --accept-license-agreement

For a supported TCP-based connection that requires the on-prem executor, stage the connector libraries first, as described in Add connector dependencies, then start the client with a single command.

Add connector dependencies

Some connectors require third-party libraries that are not included with the Relay client. Obtain them from the connector vendor and place them all in a dedicated directory on the Relay host. The Relay client stores the directory path but does not copy the libraries.

重要提示：

The on-prem executor loads and executes these libraries with the permissions of the Relay service account. Keep the directory, its parents, and every file in it owned and writable only by root, with read access for the service account. Anyone who can modify its contents can run code with those permissions.

For installations without root access, see On-prem executor in user mode.

For SAP BAPI, obtain the SAP JCo 3 libraries from SAP and place these files in the dependency directory:

Required file	用途
sapjco3.jar	SAP JCo Java library
sapidoc3.jar	SAP IDoc Java library
libsapjco3.so	SAP JCo Linux native library matching the Java runtime architecture

For another supported connector, place the vendor libraries listed in that connector's documentation in the same directory.

Start with the on-prem executor

Create the dependency directory, copy the libraries into it, and start the Relay client with the executor enabled. Point --onprem-executor-java-home at a Java 21 or later runtime, using an absolute path, so the executor uses the runtime you intend:

sudo ./relay start --config-file /path/to/config.txt \
  --accept-license-agreement \
  --enable-onprem-executor \
  --onprem-executor-java-home /usr/lib/jvm/java-21-openjdk \
  --onprem-executor-dep-dir /opt/uipath/relay/executor-deps

备注：

--config与--config-file标志互斥。要在前台运行而不是作为后台服务运行（有助于调试），请传递--detach=false 。

The Relay client validates connectivity, authenticates with OAuth, registers with Test Cloud, downloads proxy configuration, encrypts credentials, and installs a systemd service, all in a single command.

预期输出：

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: systemctl status relay-<id>

备注：

在启动期间，中继客户端会自动将二进制文件复制到/usr/local/bin/relay 。计算机上的所有Relay组共享此二进制文件。使用--bin-dir覆盖安装目录。

3. 验证

relay list

正常的客户端会在“状态”列中显示● running 。显示的ID值将用于所有后续命令（ relay stop <id> 、 relay logs <id>等）。您也可以在“UiPath 管理”中的“中继组详细信息”页面下找到它。

通过检查login to server success日志来确认已建立隧道：

sudo relay logs <id> -f

If the on-prem executor is enabled, confirm its configuration:

sudo relay describe <id>

The On-Prem Executor section reports Enabled: true with the listen port, runtime version, runtime path, Java home, and dependencies directory it is using. Check that the Java home and dependencies directory are the ones you intended.

Then confirm that the executor started. Its log contains a Started OnPremRuntimeApplication entry once it is ready:

sudo grep "Started OnPremRuntimeApplication" /var/log/uipath-relay/logs/<id>/onprem-executor.log
sudo tail -n 20 /var/log/uipath-relay/logs/<id>/onprem-executor.log

If you configured a custom log directory, use its onprem-executor.log path instead. Then run a test call from the connector that uses this endpoint, to confirm the full path works.

管理

列表

显示此计算机上所有已安装的Relay组，包括状态、版本和组名称（如果可用）。不需要 sudo。

relay list
relay list --json

描述

备注：

适用于中继客户端 26.4.2 及更高版本。运行 relay version 以检查您安装的版本。

Shows detailed information for one relay group, including service settings, configured paths, status, version, and group name when available. Does not require sudo. For a system service with the on-prem executor enabled, run it with sudo to include the executor version, which is read from the root-owned onprem-executor.jar.

relay describe <id>
relay describe <id> --json

停止

Stops the relay service. Configuration and logs are retained. The relay can be restarted later.

sudo relay stop <id>

重新启动并升级

重新启动 Relay 服务，并从 Test Cloud 获取最新的代理配置。

sudo relay restart <id>

Upgrade: extract the new Relay client archive. Keep the new relay binary and matching onprem-executor.jar together, then run sudo ./relay restart <id> from the extracted directory. The restart command updates the installed binary and, when the executor is enabled, its JAR.

To enable the executor on a service that is already installed, run sudo ./relay restart <id> --enable-onprem-executor from the extracted archive directory, so the matching onprem-executor.jar is available.

场景	命令
在 Test Cloud 中新增或删除的端点	sudo relay restart <id>
Client secret rotation (inline)	sudo relay restart --config "<new-config>"
Client secret rotation (file)	sudo relay restart --config-file /path/to/new-config.txt
日志级别更改	sudo relay restart <id> --log-level debug
日志目录或保留更改	sudo relay restart <id> --logs-dir /opt/mycompany --log-retention-days 30
Enable the on-prem executor	sudo ./relay restart <id> --enable-onprem-executor
Disable the on-prem executor	sudo relay restart <id> --disable-onprem-executor
Relay client upgrade	Extract the new archive, then run sudo ./relay restart <id>

备注：

When --config or --config-file is provided, the <id> argument is optional. It is extracted from the configuration.

删除

停止当前服务，从 Test Cloud 取消注册，并清除所有本地配置和日志文件。

sudo relay delete <id>

To force local cleanup without cloud deregistration, for example if credentials are lost or the cloud-side relay group has already been deleted:

sudo relay delete <id> --force

版本

relay version

备注：

There is no auto-upgrade. Extract the new archive and run sudo ./relay restart <id> from its directory for each group.

目录结构

所有目录都会在首次运行时自动创建。

/usr/local/bin/
  relay                                      # Shared binary (755)

/var/lib/uipath-relay/                       # Data root (755)
  groups/<id>/
    client_config                            # OAuth credentials (encrypted, 600)
    metadata.json                            # State, PID, install timestamps (644)
    .credentials.key                         # AES-256-GCM encryption key (600)
    onprem-executor.jar                      # Executor runtime when enabled (600)

/var/log/uipath-relay/                       # Logs root (755)
  logs/<id>/
    relay.log                                # Current log (644)
    relay.YYYYMMDD-HHMMSS.log                # Rotated logs (644)
    onprem-executor.log                      # Executor log when enabled

/etc/systemd/system/
  relay-<id>.service                         # Systemd unit file

文件权限

路径	Mode	原因
目录	755	Relay 读取/写入访问权限
client_config	600	包含加密的 OAuth 凭据
.credentials.key	600	AES-256-GCM 加密密钥
metadata.json	644	服务元数据（状态、PID、安装时间戳）
onprem-executor.jar	600	Executor runtime copied into protected service storage
relay.log	644	可读用于故障排除
二进制	755	由 systemd 执行
Dependencies directory (executor only)	755, owned by root	You create it; the executor loads JARs and native libraries from it as code
Files in the dependencies directory	644, owned by root	Write access to any of them is code execution as the service account

The Relay client creates and maintains every path in this table except the dependencies directory. That one is yours to create and maintain: keep it, and everything in it, owned by root and writable only by root.

自定义路径

安装中继客户端时，覆盖默认目录。

sudo ./relay start --config-file /path/to/config.txt \
  --accept-license-agreement \
  --bin-dir /opt/mycompany/bin \
  --data-dir /opt/mycompany \
  --logs-dir /opt/mycompany

标记	默认	描述
--bin-dir	/usr/local/bin	共享二进制文件的目录
--data-dir	/var/lib	配置数据的根
--logs-dir	/var/log	日志文件的根目录；可以更改为 restart

Relay 客户端会在自定义数据和日志根目录下附加uipath-relay/ ：

--bin-dir  /opt/mycompany/bin  =>  /opt/mycompany/bin/relay
--data-dir /opt/mycompany      =>  /opt/mycompany/uipath-relay/groups/<id>/
--logs-dir /opt/mycompany      =>  /opt/mycompany/uipath-relay/logs/<id>/

备注：

--bin-dir 和 --data-dir 仅 start 命令接受。--logs-dir 已被 start 和 restart 接受。其他命令（stop、delete、list）自动从已安装的服务配置中派生路径。

代理配置

如果您的网络通过代理路由出站流量，请在运行relay start之前导出代理环境变量。使用sudo -E以在提升时保留环境：

export HTTPS_PROXY="http://proxy.corp.example.com:8080"
export NO_PROXY="localhost,127.0.0.1,.corp.example.com"
sudo -E ./relay start --config "<your-config>" --accept-license-agreement

如果没有-E ， sudo会重置环境，并且代理设置将会丢失。

The Relay client writes the captured proxy variables as Environment= directives in the systemd unit file, so the background service uses them, not system-wide /etc/environment.

要在安装后更新代理：导出新值并运行sudo -E relay restart <id> 。

要删除代理： unset HTTPS_PROXY HTTP_PROXY NO_PROXY ，然后是sudo relay restart <id> 。

要验证服务使用的内容，请执行以下操作： systemctl cat relay-<id> | grep -i environment 。

有关支持的代理方案和身份验证，请参阅部署中继客户端中的代理部分。

安全框架

如果您的环境使用 SELinux、AppArhor 或 fapolicyd，请确保允许使用中继客户端二进制文件及其数据目录。

If you enable the on-prem executor, the Relay service also runs the Java executable and loads native libraries from the dependencies directory. Allow both, or the executor fails to start or cannot load its connector libraries.

SELinux

# Check enforcement mode
getenforce

# Relabel the binary if a custom policy blocks it
sudo semanage fcontext -a -t bin_t '/usr/local/bin/relay'
sudo restorecon -v /usr/local/bin/relay

When the on-prem executor is enabled, the Relay service also runs the Java executable and loads native libraries from the dependencies directory. Label only the paths that generate denials. Check for denials first.

sudo ausearch -m AVC -ts recent | grep -i -e relay -e java

If the denials show the Java process refused read or map access to the dependencies directory, label the native libraries as shared libraries.

sudo semanage fcontext -a -t lib_t '/opt/uipath/relay/executor-deps(/.*\.so(\..*)?)?'
sudo restorecon -Rv /opt/uipath/relay/executor-deps

For any remaining denials, build a policy module rather than disabling enforcement.

sudo ausearch -m AVC -ts recent | audit2allow -M uipath-relay-executor
sudo semodule -i uipath-relay-executor.pp

应用程序护符

确保没有配置文件限制/usr/local/bin/relay的网络访问或文件写入/var/lib/uipath-relay/和/var/log/uipath-relay/ 。如果使用自定义路径，请进行相应替换。

If your organization confines local services with its own AppArmor profiles and the on-prem executor is enabled, the profile covering the Relay binary must also allow it to execute the Java runtime, and allow the Java process to read and map the connector libraries in the dependencies directory. Check for denials with sudo journalctl -k | grep -i apparmor.

fapolicyd

sudo fapolicyd-cli --file add /usr/local/bin/relay
sudo fapolicyd-cli --update

When the on-prem executor is enabled, fapolicyd must also trust the Java executable, the executor runtime JAR, and each connector library. A Java runtime installed from an archive rather than a distribution package is not in the package database and is untrusted by default; a packaged runtime such as java-21-openjdk needs no entry.

Trust each file individually.

sudo fapolicyd-cli --file add <java-home>/bin/java
sudo fapolicyd-cli --file add /var/lib/uipath-relay/groups/<id>/onprem-executor.jar
sudo fapolicyd-cli --file add /opt/uipath/relay/executor-deps/sapjco3.jar
sudo fapolicyd-cli --file add /opt/uipath/relay/executor-deps/sapidoc3.jar
sudo fapolicyd-cli --file add /opt/uipath/relay/executor-deps/libsapjco3.so
sudo fapolicyd-cli --update

Re-run fapolicyd-cli --file update <path> and fapolicyd-cli --update after any upgrade that replaces a trusted file: a Relay client upgrade, which replaces onprem-executor.jar, a Java upgrade, or a new connector library version. Trust entries record each file's size and hash, so they stop matching once a file changes. If the executor fails to start on a host running fapolicyd, check sudo journalctl -u fapolicyd -n 50.

要允许的路径

类型	默认路径
二进制	/usr/local/bin/relay
数据	/var/lib/uipath-relay/
日志	/var/log/uipath-relay/
Java executable (on-prem executor only)	The java path resolved from PATH, or <java-home>/bin/java
Connector libraries (on-prem executor only)	The directory passed to --onprem-executor-dep-dir

如果您使用了--bin-dir 、 --data-dir或--logs-dir ，请改为允许这些自定义路径。

用户模式

用户模式 ( --user-mode ) 会将中继客户端安装为systemd 用户服务而非系统服务，从而允许其在没有sudo的情况下运行。这适用于共享计算机和无法访问根用户的受限环境。

要求

要求	详细信息
systemd 229+	验证: systemctl --version
主目录	必须存在并由目标用户所有
systemd 用户会话	验证： systemctl --user is-system-running返回running或degraded
SSH 登录	Required. su / sudo su do not provide the D-Bus session that user services need
loginctl linger	必需，以便服务在注销后保留并在启动时启动

启用延迟（一次性，需要管理员权限）：

sudo loginctl enable-linger <username>

如果不设置延迟，用户服务将在您注销时停止，并且不会在引导时启动。

以用户模式启动

./relay start --user-mode --config-file /path/to/config.txt --accept-license-agreement

On-prem executor in user mode

In user mode the executor runs as your user account instead of root, and the same executor flags apply:

./relay start --user-mode --config-file /path/to/config.txt \
  --accept-license-agreement \
  --enable-onprem-executor \
  --onprem-executor-java-home <java-home> \
  --onprem-executor-dep-dir <dep-dir>

The dependencies directory must not be group- or world-writable. If an administrator is available, have them create it owned by root with read access for your account, so no unprivileged account can change what the executor loads. Otherwise, create it yourself with chmod 0755 on the directory and 0644 on the files.

用户模式目录布局

~/.local/bin/
  relay                                      # Shared binary (755)

~/.local/share/uipath-relay/
  groups/<id>/
    client_config                            # OAuth credentials (encrypted, 600)
    metadata.json                            # Service metadata (644)
    .credentials.key                         # Encryption key (600)
    onprem-executor.jar                      # Executor runtime when enabled (600)
  logs/<id>/
    relay.log
    relay.YYYYMMDD-HHMMSS.log
    onprem-executor.log                      # Executor log when enabled

~/.config/systemd/user/
  relay-<id>.service                         # Systemd user unit file

无法覆盖~/.config/systemd/user/路径。可以使用--bin-dir 、 --data-dir和--logs-dir自定义二进制路径、数据路径和日志路径。

用户模式下的管理命令

所有命令无需sudo即可正常运行：

relay list
relay stop <id>
relay restart <id>
relay delete <id>
relay logs <id> -f

何时使用用户模式

场景	推荐版本
具有根用户访问权限的生产服务器	系统模式（默认）
共享计算机，无根访问权限	用户模式
开发或测试	用户模式
安全敏感环境	系统模式（防篡改二进制路径）

卸载

1. 删除所有 Relay 客户端（使用relay list查看已安装的组）：

   sudo relay delete <id>
   

2. 删除共享二进制文件：

   sudo rm /usr/local/bin/relay
   

3. 移除剩余的数据和日志目录：

   sudo rm -rf /var/lib/uipath-relay /var/log/uipath-relay
   

对于用户模式，请将命令替换为用户模式下的等效命令（无sudo ），并删除~/.local/bin/relay和~/.local/share/uipath-relay 。

故障排除

症状	原因	分辨率
服务无法启动	权限不足	运行方式 sudo
permission denied	无法创建目录	验证sudo访问权限，或使用指向可写位置的自定义路径
systemctl: command not found	未安装 systemd	使用前台模式 ( --detach=false ) 或安装 systemd
服务启动，然后立即停止	配置或网络错误	检查relay.log是否存在启动错误
服务正在运行，但未建立隧道	网络或身份验证问题	检查 relay.log 的 login to server 错误；验证与 cloud.uipath.com 的连接；对于 26.4.2 之前的中继客户端版本，请验证 TLS 直通到区域中继主机名
SELinux 或 AppArcor 阻止执行	安全框架策略	请参阅安全框架
XDG_RUNTIME_DIR not found （用户模式）	未通过 SSH 登录	通过 SSH 登录，或启用延迟
D-Bus session bus unreachable （用户模式）	未通过 SSH 登录	通过 SSH 登录，或启用延迟
服务未使用代理	开始时未捕获变量	使用sudo -E重新运行，或使用systemctl cat relay-<id> | grep -i environment进行验证
CPU 或内存占用率过高	日志级别设置为trace或debug	将日志级别设置为info或更高

诊断命令

# Real-time logs
sudo relay logs <id> -f

# Systemd journal
journalctl -u relay-<id> -f

# Service status
systemctl status relay-<id>

# Connectivity test
nc -zv cloud.uipath.com 443

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

# Check if binary is blocked by SELinux
sudo ausearch -m AVC -ts recent

# Check AppArmor status
sudo aa-status

有关各平台共有的身份验证和连接错误，请参阅故障排除。

快速参考

操作	命令
启动	sudo relay start --config-file config.txt --accept-license-agreement
停止	sudo relay stop <id>
重新启动/升级	sudo relay restart <id>
删除	sudo relay delete <id>
删除 (强制)	sudo relay delete <id> --force
列表	relay list
描述	relay describe <id>
日志	relay logs <id> -f
服务状态	systemctl status relay-<id>
Systemd 日志	journalctl -u relay-<id> -f