在 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 排除（如果适用）（请参阅安全框架）
• 如果您使用内部部署执行程序：管理员拥有的依赖项目录和非特权帐户无法写入的 Java 安装。执行程序使用 Relay 服务帐户的权限从两者加载代码

配置

• 已创建 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

对于需要内部部署执行程序的受支持的基于 TCP 的连接，请先暂存连接器库，如“添加连接器依赖项”中所述，然后使用单个命令启动客户端。

添加连接器依赖项

某些连接器需要 Relay 客户端中未包含的第三方库。从连接器供应商处获取，并将其全部放置在 Relay 主机上的专用目录中。Relay 客户端存储目录路径，但不会复制库。

重要提示：

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

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

对于 SAP BAPI，请从 SAP 获取 SAP JCo 3 库，并将以下文件放置在依赖项目录中：

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

对于另一个受支持的连接器，请将该连接器文档中列出的供应商库放在同一目录中。

从内部部署执行程序开始

创建依赖项目录，将库复制到其中，然后启动中继客户端并启用执行程序。使用绝对路径将 --onprem-executor-java-home 指向 Java 21 或更高版本的运行时，以便执行程序使用您想要的运行时：

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 服务，所有这些都可以在单个命令中完成。

预期输出：

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

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

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>

升级：提取新的 Relay 客户端存档。将新的 relay 二进制文件和匹配的 onprem-executor.jar 保存在一起，然后从提取的目录中运行 sudo ./relay restart <id>。重新启动命令将更新安装的二进制文件，并在启用执行程序时更新其 JAR。

要在已安装的服务上启用执行程序，请从提取的存档目录中运行 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
中继客户端升级	提取新存档，然后运行 sudo ./relay restart <id>

备注：

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

删除

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

sudo relay delete <id>

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

sudo relay delete <id> --force

版本

relay version

备注：

不会自动升级。提取新存档，然后从其目录中为每组运行 sudo ./relay restart <id>。

目录结构

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

/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