部署中继客户端

Relay 客户端的先决条件、最低要求以及将本地网络连接到 Test Cloud 的跨平台设置步骤。

请在网络内的计算机上安装并启动 Relay 客户端，以此建立通往 Test Cloud 的出站隧道。开始之前，请先配置 Relay 组并准备好所需的客户端配置 string。

先决条件

硬件要求

配置文件	vCPU	RAM	Relay组	每组端点	Use case
标准	1	2 GiB	最多 10 个	最多 50 个	大多数部署
大	2	4 GiB	10+	最多 50 个	高吞吐量或大规模环境

这些是未启用内部部署执行程序时中继客户端的最低要求。如果主机还运行其他工作负载，请在这些数字的基础上添加它们的容量。对于启用执行程序的部署，请改用资源规划中受支持的基于 TCP 的连接中的数字。

受支持的基于 TCP 的连接的资源规划

您安装的每个Relay组都作为自己的Relay客户端服务运行。启用内部部署执行程序后，该服务将启动并监督一个 Java 进程。下图适用于启用了执行程序的单个 Relay 组。

配置文件	vCPU	RAM	为执行程序保留的 RAM
标准（带执行程序）	2	4 GiB	1 GiB
大型（带执行程序）	4 个或更多	4 GiB 或更多	1 GiB 或更多

RAM 包括执行程序预留、操作系统和 Java Runtime。添加主机上用于监控和任何其他工作负载的容量。上线后，如果执行程序的内存使用量接近其预留量，请同时增加预留量和 RAM。

提示：

为了最大程度地减少资源使用量，请在单个“Relay 组”下注册所有基于 TCP 的端点。然后，其 Relay 客户端为每个基于 TCP 的端点运行一个内部部署执行程序，因此您可以为单个流程预留内存，调整主机大小并监控执行程序日志。

如果您的网络分段或可用性要求需要多个 Relay 组，且执行程序位于同一台主机上：

• 为每个组的执行程序分配唯一的 --onprem-executor-listen-port 值。
• 每增加一个执行程序流程，请再预留 1 GiB。
• 将 CPU 大小设置为所有组的总流量，而不是将每组的 CPU 数字乘以组数。
• 磁盘空间用于每组单独的执行程序 JAR 和日志文件。

磁盘要求

配置文件	可用磁盘下限
标准（1–10 组）	200 MB
大型（10 个以上组）	1 GB

上述最小值仅涵盖中继客户端。如果您启用内部部署执行程序，请为 Java Runtime、onprem-executor.jar、您提供的连接器库和保留的执行程序日志留出更多空间。日志增长取决于流量、日志级别和配置的保留期。

支持的操作系统

架构	Linux	Windows
x86_64 (amd64)	支持	支持
ARM64 (aarch64)	支持	支持

网络要求

中继客户端需要仅出站连接。不需要入站防火墙规则。

每个 Relay 客户端版本都需要达到 cloud.uipath.com ，以便进行身份验证和注册。从中继客户端 26.4.2 开始，新配置还通过同一 URL 携带持久隧道，因此不再需要将特定于区域的中继主机名列入允许列表。

中继客户端配置	协议	端口	目标	需要 TLS 直通	用途
所有 Relay 客户端版本	https	443	cloud.uipath.com	非必填	身份验证和中继注册
中继客户端 26.4.2 或更高版本	HTTPS/WSS	443	cloud.uipath.com	非必填	持久性隧道
低于以下版本的中继客户端版本 26.4.2	TLS	443	<region>-relay.uipath.com	必填	持久性隧道

低于 26.4.2 的中继客户端版本可继续使用区域中继主机名。将这些主机名保留在允许列表中，直到您转移到中继客户端 26.4.2 或更高版本并通过 cloud.uipath.com 进行连接。

对于 26.4.2 之前的 Relay 客户端版本，请将 <region> 替换为 Test Cloud 租户的区域。有关区域的完整列表，请参阅全球云区域。

区域	中继服务器主机名
us	us-relay.uipath.com
欧盟	eu-relay.uipath.com
加拿大	ca-relay.uipath.com
瑞士	ch-relay.uipath.com
澳大利亚	au-relay.uipath.com
新加坡	sg-relay.uipath.com
日本	jp-relay.uipath.com
韩国	kr-relay.uipath.com
阿拉伯联合酋长国	ae-relay.uipath.com
英国	uk-relay.uipath.com
欧盟（延迟区域）	gxp-eu-relay.uipath.com
美国（延迟区域）	gxp-us-relay.uipath.com

备注：

如果上面未列出您的租户区域，请联系 UiPath 支持团队，以确认中继服务器主机名。

选择与您的 UiPath 云租户区域匹配的区域，而不是中继节点的物理位置。例如，如果您的租户是在美国地区配置的，即使中继本身在不同的区域运行，也请使用 us-relay.uipath.com。通过 26.4.2 连接的中继客户端 cloud.uipath.com 配置不使用此区域主机名。

延迟注意事项：由于流量从 UiPath Cloud 流经中继服务器和中继节点到本地部署服务，因此将中继节点放置在靠近租户区域的位置可最大限度地减少往返时间，并提高整体吞吐量。

对于通过 26.4.2 连接的 Relay 客户端 cloud.uipath.com 配置，配置防火墙和代理，以允许 HTTPS 流量和 WebSocket 升级到 cloud.uipath.com:443。如果代理检查 cloud.uipath.com 的 TLS，请在 Relay 客户端使用的操作系统信任存储区中安装代理的签名 CA，并确保代理允许 WebSocket 升级。

对于早于26.4.2 的 Relay 客户端版本，配置防火墙和任何负责 TLS 检查的代理或 DLP 设备，以允许 TLS 通过<region>-relay.uipath.com:443；对区域性 Relay 主机名称进行 TLS 检查会破坏 Relay 隧道。

Relay 主机必须解析并连接到每个已注册的 HTTP 或 HTTPS 端点，以及每个受支持的基于 TCP 的端点的主机和端口。

路由路径很灵活。只要来自 Relay 主机的连接成功，即可使用直接网络路由、公司出口代理或跳转主机。规划放置，以便组中的每个目标都保持可访问。

带宽

空闲时，控制通道（心跳和身份验证）的使用量大约为每分钟 1–2 KB 。数据流量会随着云服务向本地部署端点发送的请求数量而增加。对于 HTTP 和 HTTPS 端点，中继充当透明隧道，除了 TLS 和用于 cloud.uipath.com 连接的轻量级 WebSocket 分帧之外，没有额外开销。

对于受支持的基于 TCP 的连接，内部部署执行程序会将每个请求转换为连接器的协议。因此，执行程序和目标系统之间的流量反映的是该协议，而不是原始请求的大小。Relay 客户端和执行程序之间的流量保留在环回接口上，不会离开主机。

验证连接

在安装中继客户端之前，请确认允许端口 443 上的出站流量到达您的配置的所需目标。

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

成功的结果在 Windows 上显示 TcpTestSucceeded : True，在 Linux 上显示 succeeded。如果所需检查失败，请查看防火墙规则。对于通过 26.4.2 连接的 Relay 客户端 cloud.uipath.com 配置，确认是否允许 WebSocket 升级；对于 26.4.2 之前的中继客户端版本，请确认是否为中继服务器主机名配置了 TLS 直通。

用于受支持的基于 TCP 的连接的内部部署执行程序

对于受支持的基于 TCP 的连接（例如 SAP BAPI），请求由本地部署执行程序处理，这是一个 Java 进程，会使用连接器协议并将调用转发到目标系统。在 Linux 和 Windows 服务部署中（如下所述），中继客户端将启动并监督该服务部署。在容器部署中，您可以将其作为单独的容器运行：请参阅SAP BAPI 和其他基于 TCP 的连接。

重要提示：

内部部署执行程序支持需要中继客户端 26.4.3 或更高版本。

在 Linux 和 Windows 服务部署中，Relay 客户端会为每个 Relay 客户端服务启动一个执行程序流程。默认情况下，执行程序仅在端口 localhost 上侦听 18080，并且无法从主机外部访问。与任何环回服务一样，同一主机上的其他流程可以访问它，因此将对 Relay 主机的本地访问视为敏感。

在启用之前：

• 准备好 Java 21 或更高版本的运行时。JRE 或 JDK 便已足够，现有安装即可。将 java 添加到运行 PATH 的帐户的 relay start 上，或使用 --onprem-executor-java-home 传递运行时的位置。
• 从同一存档中提取 Relay 二进制文件 relay（Linux 上）或 relay.exe（Windows），以及捆绑的 onprem-executor.jar。将这两个文件一起保留在提取目录中，然后从该目录运行安装或升级命令。
• 确保Relay 主机可以访问目标系统主机名和端口。
• 如果 UiPath 未附带连接器需要的库，请将它们全部放置在 Relay 服务帐户可以读取的持久目录中，然后将 --onprem-executor-dep-dir 指向该该连接器。中继客户端会存储路径，但不会复制文件。
• 对于 SAP BAPI，该目录包含 SAP JCo 3 文件 sapjco3.jar 和 sapidoc3.jar，以及与主机操作系统和 Java 运行时架构匹配的原生库。将 SAP 支持用于 SAP 系统和 Java 运行时的 SAP JCo 版本。
• 依赖项目录是执行程序的代码加载路径，它使用 Relay 服务帐户的权限运行。它必须由管理员所有，并且非特权用户不可写入。
• 在 Linux 上，对目录使用 0755，对文件使用 0644。在 Windows 中，将其置于 C:\Program Files 下，这将默认授予管理员写入权限，以及默认授予其他帐户读取和执行权限。

有关可复制的安装和验证命令，请参阅Linux或Windows 。安装完成后，relay describe <id> 会报告执行程序是否已启用以及它使用哪个 Java 主目录和依赖项目录。

重要提示：

在容器部署中，Relay 客户端不会启动执行程序，因此服务部署的 Java 运行时和依赖项目录要求不适用，并且 --onprem-executor-java-home 和 --onprem-executor-dep-dir 无效。应将执行程序作为单独的容器运行，如SAP BAPI 和其他基于 TCP 的连接中所述。

配置代理（如果适用）

如果您的网络通过代理路由出站流量，请在运行 relay start 之前设置以下环境变量。中继客户端将这些设置用于代理感知出站流量。

变量	用途
HTTPS_PROXY / https_proxy	代理 URL（优先勾选）
HTTP_PROXY / http_proxy	代理 URL（回退）
NO_PROXY / no_proxy	绕过代理的逗号分隔主机或域

代理 URL 必须使用以下方案之一： http:// 、 https:// 、 socks5://或ntlm:// 。格式： scheme://[user:password@]host:port 。

对于https://代理：中继客户端根据操作系统信任存储区验证代理的 TLS 证书。如果您的代理使用公司 CA 或自签名 CA，请在启动中继之前将该 CA 添加到中继客户端计算机的信任存储中；否则，TLS 握手将失败，并显示证书验证错误。

对于通过 连接的 Relay 客户端26.4.2配置cloud.uipath.com，配置代理，以允许长效 HTTPS 连接和 WebSocket 升级到 cloud.uipath.com:443。 如果代理检查 TLScloud.uipath.com，则在 Relay 客户端使用的操作系统信任存储中安装代理的签名 CA。

对于 26.4.2 之前的中继客户端版本，请配置代理以绕过 TLS 检查。<region>-relay.uipath.com:443不支持 pac 文件、WPAD 自动发现和代理链接。显式设置代理 URL。检测到代理时，先决条件检查会在输出中显示“via proxy”。

重要提示：

中继客户端会在日志中脱敏代理密码。但是，环境变量中设置的凭据可能在流程列表和 systemd 单元文件中可见。使用专用服务凭据，并相应地限制对Relay节点的访问。

配置受信任的 IP（如果适用）

如果您的组织启用了基于 IP 地址的访问限制，请将运行 Relay 客户端的计算机的 NAT IP 地址，添加到 UiPath Administration 的受信任 IP 列表中。Relay 客户端的出站流量会以该 IP 地址访问 Test Cloud，因此必须将该 IP 地址明确加入允许列表。

有关说明，请参阅添加受信任的 IP 范围。

接受许可协议

在启动中继客户端之前，您必须接受许可协议。选择以下方法之一：

选项 1（环境变量）。将 LICENSE_AGREEMENT 环境变量设置为接受：

Linux

export LICENSE_AGREEMENT=accept

Windows

$env:LICENSE_AGREEMENT=accept

选项 2（内联参数）。将 --accept-license-agreement 附加到 relay start 命令：

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

设置指南

对于生产部署，请参阅适用于您操作系统的平台指南。它涵盖快速入门命令、目录结构、服务管理、安全框架配置和卸载过程：

平台	指南
Linux	在 Linux 上部署中继客户端
Windows	在 Windows 上部署中继客户端
容器	将中继客户端部署为容器

运营

连接弹性

中继客户端自动维护隧道：

• 心跳默认情况下每 30 秒进行一次（可通过--heartbeat-interval配置，最短 10 秒）。隧道超时是心跳间隔的 3 倍。如果防火墙、代理或 NAT 在 30 秒前断开空闲 TCP 连接，请缩短间隔：

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

• 断开连接时自动重新连接，使用指数退避算法至 20 秒间隔。
• 进程崩溃时服务自动重新启动，由 Linux 上的 systemd 和 Windows 上的 Windows 服务控制管理器管理。
• 服务在系统重新启动时自动启动。

主动重新连接

空闲连接超时的公司代理、负载均衡器或防火墙后面的网络可以静默终止 TLS 长连接。主动重新连接会定期重新建立控制连接，以防止出现这种情况。

使用--reconnect-interval标志启用它：

relay start --config "<config>" --reconnect-interval 1800 --accept-license-agreement

最小值有效为 1800 秒（30 分钟）。将间隔设置为网络设备空闲超时的大约一半，例如，如果防火墙超时时间为 60 分钟，则将其设置为 1800 秒。在没有空闲连接超时的稳定网络上保持禁用状态。

• 正常排空。当经过该间隔时间后，Relay 客户端将停止接受新工作，并等待正在进行的连接完成，最长会等待 300 秒的排空超时，然后再关闭旧连接并打开新连接。在达到排出超时时间时，仍在处理中的请求将终止。

• 高可用性。当在同一组中部署多个 Relay 客户端时，它们将进行协调，以便一次只有一个客户端排空数据。该组将继续在每个重新连接周期提供流量。

• 需要主动重新连接的标志：日志显示尽管基础网络稳定，但定期出现unexpected EOF错误或静默断开连接，这通常由防火墙、代理或负载均衡器 30–60 分钟空闲超时引起。

重新加载配置

relay reload <id>

从 Test Cloud 重新获取代理配置并应用，无需重新启动。云端更改（例如新的端点或更新的运行状况检查路径）会自动推送到正在运行的 Relay 客户端，通常不需要重新加载。仅当新添加的端点返回 404 时，才使用此命令作为回退。

日志记录

设置	值
默认级别	info
旋转	Daily
保留	7 天
日志文件	relay.log （当前）， relay.YYYYMMDD-HHMMSS.log （已轮换）

使用 --log-level trace/debug/info/warn/error 覆盖默认日志级别。在 Relay 客户端 26.4.2 或更高版本中，在 --log-retention-days <days> 或 relay start 使用 relay restart 覆盖轮换的日志保留时间；最短保留时间为 7 天。

命令参考

中继启动

配置一个新的中继客户端，并将其作为后台服务启动。

许可协议（需要一个）

• --accept-license-agreement：接受最终用户许可协议内联。
• LICENSE_AGREEMENT=accept：与标志等效的环境变量。relay start 打印最终用户许可协议，如果两者均未设置，则退出。

配置（必填项）

• -c、--config <string>：内联 Base64 编码的配置字符串。
• --config-file <path>：包含配置字符串的文件路径。推荐：将密码保留在 Shell 历史记录中。

调整（可选）

• --heartbeat-interval <sec>：隧道心跳间隔。默认 30。最小值为 10。隧道超时为此值的 3 倍。如果防火墙、NAT 或代理在 30 秒前丢弃空闲 TCP，则更低。
• --reconnect-interval <sec>：主动重新连接间隔。默认 0（禁用）；设置后，最短 1800（30 分钟）生效。
• --log-level <level>：trace、debug、info、warn 或 error。默认 info。
• --log-retention-days <days>：轮换的日志文件的保留天数。默认 7。最小值为 7。需要中继客户端 26.4.2 或更高版本。
• -d、--detach=false：在前台运行，而不作为后台服务运行。用于调试启动问题。

内部部署执行程序（可选）

• --enable-onprem-executor：启用内部部署执行程序。在 Linux 和 Windows 服务部署中，Relay 客户端将启动捆绑的执行程序流程。在容器部署中，它通过默认端口 18080 连接到执行程序容器。
• --onprem-executor-listen-port <port>：内部部署执行程序侦听的端口。默认 18080。在容器部署中，使用执行程序容器的 SERVER_PORT 值。仅此标志也启用执行程序。
• --onprem-executor-java-home <path>：JAVA_HOME 用于运行内部部署执行程序。如果省略，则 java 根据 PATH 解析。在容器部署中无效。
• --onprem-executor-dep-dir <path>：保存每个连接器依赖项、JAR 和匹配的原生操作系统库的单个目录。对于 SAP BAPI，即 sapjco3.jar、sapidoc3.jar 和主机的 SAP JCo 原生库。在容器部署中无效，因为此路径由执行程序映像拥有。

执行程序地址固定为 localhost。Relay 日志级别和保留设置也适用于 onprem-executor.log。

非默认安装路径（可选）

• --data-dir <path>：配置目录。
• --logs-dir <path>：日志文件目录。
• --bin-dir <path>：二进制文件安装目录。

仅限 Linux

• --user-mode：作为 systemd 用户服务安装（不需要 sudo，使用 XDG 路径）。

仅限 Windows

• --service-account <DOMAIN\user>：在特定帐户下运行 Windows 服务。默认值为 LocalSystem。
• --service-account-password <password>：--service-account 的密码。

中继重新启动

停止并重新启动中继客户端服务。检测更新的二进制文件并应用服务定义更改。以下标志可以在重新启动时覆盖（除非特别说明，否则所有标志都默认保持不变）：

• --config / --config-file：替换客户端配置。
• --accept-license-agreement：在重新启动期间接受许可协议，这在升级已安装的且不接受许可证的较旧的服务时非常有用。
• --log-level：更改日志级别。
• --logs-dir <path>：移动已安装服务的日志目录。需要中继客户端 26.4.2 或更高版本。
• --log-retention-days <days>：更改轮换日志保留时间。最低 7；若要保持不变，请传递 -1。需要中继客户端 26.4.2 或更高版本。
• --heartbeat-interval：更改心跳间隔。最低 10；若要保持不变，请传递 0。
• --reconnect-interval：更改主动重新连接的间隔。设置后最短 1800（30 分钟）。发送 0 以禁用，或发送 -1 以保持不变。
• --enable-onprem-executor：启用或更新已安装服务上的内部部署执行程序设置。
• --disable-onprem-executor：删除暂留的内部部署执行程序设置，并在没有执行程序进程的情况下重新启动。
• --onprem-executor-listen-port、--onprem-executor-java-home、--onprem-executor-dep-dir：更新特定内部部署执行程序设置。传递这些标志中的任何一个都意味着需要更新执行程序。

如果已安装的服务已启用内部部署执行程序，则 relay restart <id> 会保留其设置。要将 Relay 和执行程序一起升级，请从新的存档文件中提取这两个文件，并使用新的 Relay 二进制文件运行 relay restart <id>。在停止服务之前运行 Java 和执行程序检查。

中继日志

显示 Relay 客户端的日志输出。

• -f、--follow：持续流式传输新的日志行。
• -n、--lines <N>：从末尾算起的行数。默认 50。

中继列表

显示该计算机上的所有 Relay 客户端，包括状态、版本、创建和更新时间戳以及组名称（如果可用）。表格输出中的长组名称会被截断。

• --json：发出 JSON 输出以用于自动化和脚本编写，包括完整的组名称。

中继描述（中继客户端26.4.2或更高版本）

显示一个 Relay 客户端的详细信息，包括组 ID 和名称、密码 ID、状态、版本、服务模式和可执行路径、配置的心跳和重新连接间隔、日志级别、本地路径和时间戳。

“On-Prem 执行程序”部分会报告是否启用了执行程序，以及在启用时报告侦听端口、Runtime 版本、Runtime 路径、Java 主目录和依赖项目录。

• --json：发出 JSON 输出，用于自动化和脚本编写。

中继重新加载

从 Test Cloud 重新获取代理配置并直接应用，此过程无需重启。如果新添加的端点返回404，请将其用作回退方案。

中继停止

停止中继客户端服务。配置和凭据将保留。中继客户端可以稍后重新启动。

中继删除

停止当前服务，从 Test Cloud 中取消注册，并移除所有本地配置和凭据。

• -f、--force：从本地删除而不在云取消注册。在凭据不可读或云端资源已被删除时使用。

Relay 支持捆绑包 [id]

收集 UiPath 支持工单的配置、日志和系统元数据的脱敏存档。省略[id]以捆绑计算机上的所有中继客户端。凭据和加密密钥永远不会包括在内。有关完整详细信息，请参阅收集支持捆绑包。

Relay 版本

打印 Relay 客户端版本、构建日期和 git 提交哈希值。

防病毒和端点安全

如果您的组织运行端点保护软件，请为中继二进制文件及其数据目录添加排除项，以防止中继客户端被阻止或隔离。对于通过 26.4.2 连接的中继客户端 cloud.uipath.com 配置，请允许 cloud.uipath.com:443。对于 26.4.2 之前的 Relay 客户端版本，请配置 TLS 检查代理、DLP 设备和 IDS/IPS 系统，以绕过 <region>-relay.uipath.com:443 的检查。

如果启用内部部署执行程序，请将这些排除项扩展到 Java 可执行文件、依赖项目录和 onprem-executor.log。中继服务会启动一个 Java 子进程，该子进程会加载第三方连接器库，而某些端点保护产品会默认阻止这些库。将排除的范围限定为这些路径，而不是整个目录树。

目标	端口	协议	操作
cloud.uipath.com	443	https	允许
<region>-relay.uipath.com	443	TLS	对于更低版本的中继客户端， 26.4.2