在 Linux 上部署中继客户端

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

本页介绍特定于 Linux 的生产设置详细信息。有关跨平台先决条件和网络要求，请参阅部署中继客户端。

操作系统要求

中继客户端需要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) 访问权限，或计划使用 --user-mode
• 至少 200 MB 可用磁盘空间
• 如果您使用受支持的基于 TCP 的连接，且该连接需要内部部署执行程序：
  • 查看建议的主机和执行程序容量
  • 在 PATH 上运行或使用 --onprem-executor-java-home 传递的 Java 21 或更高版本的 JRE 或 JDK。现有安装有效。

网络

• 对于中继客户端 26.4.2 或更高版本，允许到 cloud.uipath.com 的出站 HTTPS（端口 443），包括 WebSocket 升级
• 对于 26.4.2 之前的中继客户端版本，允许到 <region>-relay.uipath.com 的出站 TLS（端口 443），并配置了 TLS 直通
• Relay 主机可以解析并连接到每个已注册的 HTTP 或 HTTPS 端点，以及每个受支持的基于 TCP 的端点的主机和端口

安全性

• 已配置 SELinux/AppArhor/fapolicyd 排除（如果适用）（请参阅安全框架）
• If you use the on-prem executor: a Java installation that no unprivileged account can write and, for SAP BAPI, an administrator-owned dependencies directory. The executor loads code from both, with the privileges of the Relay service account

配置

• 已创建 Relay 组，并准备好客户端配置字符串（请参阅配置 Relay 组）

验证先决条件

运行以下命令：

# 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

从中继客户端 26.4.3 开始，存档还包含 onprem-executor.jar。在提取的目录中，将其保留在 relay 二进制文件旁边，并从该目录运行安装或升级命令。

2. 开始

您可以通过两种方式提供客户端配置字符串（在“UiPath 管理中生成”，如配置 Relay 组中所述）：

选项 A：内联。直接传递配置字符串。没有要创建或清理的文件:

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

选项 B：文件。将配置保存到文件，然后引用该文件。推荐使用此选项，因为此选项可将密码保留在 Shell 历史记录之外：

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

For SAP BAPI, stage the SAP JCo libraries first, as described in Add connector dependencies. Snowflake and SQL Server need no libraries. Then follow Start with the on-prem executor.

添加连接器依赖项

For SAP BAPI, the SAP JCo 3 libraries are not included with the Relay client: place them in a dedicated directory on the Relay host. For Snowflake and SQL Server, no libraries are needed, because the JDBC drivers ship inside the on-prem executor; skip this section. The Relay client stores the directory path but does not copy the libraries.

重要提示：

内部部署执行程序使用 Relay 服务帐户的权限加载并执行这些库。保持目录、其父目录以及其中的每个文件仅由 root 拥有和写入，并对服务帐户具有读取权限。任何可以修改其内容的人都可以运行具有这些权限的代码。

对于没有根用户访问权限的安装，请参阅用户模式下的内部部署执行程序。

Obtain these files from SAP and place them in the dependency directory:

所需文件	用途
sapjco3.jar	SAP JCo Java 库
sapidoc3.jar	SAP IDoc Java 库
libsapjco3.so	与 Java 运行时架构匹配的 SAP JCo Linux 原生库

从内部部署执行程序开始

Start the Relay client with the executor enabled. For SAP BAPI, also pass --onprem-executor-dep-dir with the directory you prepared; omit it for Snowflake and SQL Server. 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 。

Relay 客户端可验证连接、使用 OAuth 进行身份验证、在 Test Cloud 中注册、下载代理配置、加密凭据以及安装 systemd 服务，所有这些都可以在单个命令中完成。

预期输出：

UiPath Relay <version>
Installing group <group name> (<id>) as a system service on <hostname>

Running prerequisite checks...
  ✓ Directory permissions: OK
  ✓ Cloud portal connectivity: OK
  ✓ On-prem executor checks: OK
✓ All prerequisite checks passed
  ✓ Service started
  ✓ Relay client provisioned (<N> endpoints)
  ✓ Connected to relay server (12.3s)

✓ Relay is running

Next steps
  sudo relay logs <id>
  sudo relay describe <id>
  sudo relay list

备注：

在启动期间，中继客户端会自动将二进制文件复制到/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

如果内部部署执行程序已启用，请确认其配置：

sudo relay describe <id>

内部部署执行程序部分报告Enabled: true其中包含其正在使用的侦听端口、运行时版本、运行时路径、Java 主目录和依赖项目录。检查 Java 主目录和依赖项目录是否在您想要的目录中。

然后确认执行程序是否已启动。准备就绪后，其日志将包含 Started OnPremRuntimeApplication 条目：

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

如果您配置了自定义日志目录，请改用其 onprem-executor.log 路径。然后从使用此端点的连接器运行测试调用，以确认完整路径有效。

管理

列表

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

relay list
relay list --json

描述

备注：

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

显示一个Relay组的详细信息，包括服务设置、配置的路径、状态、版本和组名称（如果可用）。不需要 sudo。对于已启用内部部署执行程序的系统服务，请使用 sudo 运行以包含执行程序版本，该版本读取自根用户拥有的 onprem-executor.jar 进程。

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

停止

停止中继服务。配置和日志将保留。中继可以稍后重新启动。

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 upgrade every group that relay list shows in one run, use sudo ./relay restart --all (Relay client 26.4.4 or later).

要在已安装的服务上启用执行程序，请从提取的存档目录中运行 sudo ./relay restart <id> --enable-onprem-executor，以提供匹配的 onprem-executor.jar。

场景	命令
在 Test Cloud 中新增或删除的端点	sudo relay restart <id>
客户端密码轮换（内联）	sudo relay restart --config "<new-config>"
客户端密码轮换（文件）	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
启用内部部署执行程序	sudo ./relay restart <id> --enable-onprem-executor
禁用内部部署执行程序	sudo relay restart <id> --disable-onprem-executor
中继客户端升级	Extract the new archive, then run sudo ./relay restart <id>, or sudo ./relay restart --all for every group that relay list shows

备注：

当提供 --config 或 --config-file 时，<id> 参数是可选的。该文件是从配置中提取的。

删除

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

sudo relay delete <id>

要在不取消云注册的情况下强制本地清理，例如，在凭据丢失或云端中继组已删除时，请执行以下操作：

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, or sudo ./relay restart --all to upgrade every group that relay list shows in one run (Relay client 26.4.4 or later).

目录结构

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

/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	已将执行程序运行时复制到受保护的服务存储中
relay.log	644	可读用于故障排除
二进制	755	由 systemd 执行
依赖项目录（仅限执行程序）	755，拥有者 root	您创建；执行程序从中将 JAR 和原生库作为代码加载
依赖项目录中的文件	644，拥有者 root	其中任何一个的写入权限是以服务帐户身份执行代码

中继客户端将创建并维护此表格中的所有路径，依赖项目录除外。该文件由您创建和维护：将其及其中的所有内容保留为root所有，并仅由 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会重置环境，并且代理设置将会丢失。

Relay 客户端将捕获的代理变量作为 Environment= 指令写入 systemd 单元文件中，因此后台服务使用这些变量，而不是系统范围内的 /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，请确保允许使用中继客户端二进制文件及其数据目录。

如果您启用内部部署执行程序，Relay 服务还会运行 Java 可执行文件，并从依赖项目录加载原生库。允许两者，否则执行程序将无法启动或无法加载其连接器库。

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

启用内部部署执行程序后，Relay 服务还会运行 Java 可执行文件，并从依赖项目录加载原生库。仅标记生成拒绝的路径。请先检查是否有拒绝情况。

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

如果拒绝结果显示 Java 进程拒绝读取或映射对依赖项目录的访问权限，则将原生库标记为共享库。

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

对于任何剩余的拒绝，构建一个策略模块，而不是禁用强制执行。

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/ 。如果使用自定义路径，请进行相应替换。

如果您的组织使用自己的 AppArmor 配置文件限制本地服务，并且启用了本地执行程序，则覆盖 Relay 二进制文件的配置文件还必须允许它执行 Java 运行时，并允许 Java 进程读取和映射依赖项目录中的连接器库。使用 sudo journalctl -k | grep -i apparmor 检查是否存在拒绝行为。

fapolicyd

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

启用内部部署执行程序后，fapolicyd 还必须信任 Java 可执行文件、执行程序运行时 JAR 和每个连接器库。从存档而不是分发包安装的 Java Runtime 不在包数据库中，默认情况下不受信任；打包运行时（例如 java-21-openjdk）不需要条目。

分别信任每个文件。

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

在替换受信任文件的任何升级后重新运行 fapolicyd-cli --file update <path> 和 fapolicyd-cli --update：Relay 客户端升级、替换 onprem-executor.jar、Java 升级或新的连接器库版本。信任条目记录每个文件的大小和哈希值，因此一旦文件发生更改，它们将停止匹配。如果执行程序无法在运行 fapolicyd 的主机上启动，请检查 sudo journalctl -u fapolicyd -n 50。

要允许的路径

类型	默认路径
二进制	/usr/local/bin/relay
数据	/var/lib/uipath-relay/
日志	/var/log/uipath-relay/
Java 可执行文件（仅限内部部署执行程序）	从 java 解析的 PATH 路径或 <java-home>/bin/java
连接器库（仅限内部部署执行程序）	传递到的目录 --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 登录	必需。su / sudo su 未提供用户服务所需的 D-bus 会话
loginctl linger	必需，以便服务在注销后保留并在启动时启动

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

sudo loginctl enable-linger <username>

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

以用户模式启动

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

用户模式下的本地部署执行程序

在用户模式下，执行程序将以您的用户帐户而非 root 身份运行，并且适用相同的执行程序标志：

./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>

依赖项目录不得为组可写或全局可写。如果管理员空闲，请让他们创建由对您的帐户具有读取权限的 root 所有，因此任何非特权帐户都无法更改执行程序加载的内容。否则，请自行创建，对目录使用 chmod 0755，对文件使用 0644。

用户模式目录布局

~/.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