UiPath Documentation
test-cloud
latest
false
重要 :
新发布内容的本地化可能需要 1-2 周的时间才能完成。

Test Cloud 管理员指南

上次更新日期 2026年5月21日

在 Linux 上部署中继客户端

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

操作系统要求​

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

分布最低版本
Ubuntu20.04 LTS (Focal)
发行说明10（巴星）
Red Hat Enterprise Linux8
Amazon Linux2023 年
SUSE Linux 企业版服务器15
Oracle Linux8

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

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

安装前检查清单​

系统​

  • 支持 systemd 229+ 的 Linux 发行版
  • sudo (Root) 访问权限 — 或计划使用--user-mode
  • 至少 200 MB 可用磁盘空间

网络​

  • 允许至cloud.uipath.com出站 HTTPS（端口 443）
  • 允许至<region>-relay.uipath.com出站 TLS（端口 443）
  • 为中继端点配置 TLS 直通（无 TLS 检查）
  • Relay 节点已拥有对您计划公开的所有本地部署服务的网络访问权限

安全性​

  • 已配置 SELinux/AppArmo/fapolicyd 排除（如果适用）— 请参阅安全框架

配置​

  • 已创建 Relay 组，并已准备好客户端配置字符串 — 请参阅配置 Relay 组
Validation commands​
# Check systemd version (must be 229+)
systemctl --version

# Verify sudo access
sudo -v

# Check available disk space
df -h /var/lib
# Check systemd version (must be 229+)
systemctl --version

# Verify sudo access
sudo -v

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

安装​

1. 下载并提取​

unzip relay-linux-amd64.zip && chmod +x relay
unzip relay-linux-amd64.zip && chmod +x relay

2. 开始​

您可以通过两种方式提供客户端配置字符串（来自“UiPath 管理” — 请参阅“配置中继组”）：

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

sudo ./relay start --config "<your-config>"
sudo ./relay start --config "<your-config>"

选项 B — 文件。将配置保存到文件，然后引用该文件。推荐 — 将密码保留在 shell 历史记录中:

sudo ./relay start --config-file /path/to/config.txt
sudo ./relay start --config-file /path/to/config.txt

--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>
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
relay list

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

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

sudo relay logs <id> -f
sudo relay logs <id> -f

管理​

列表​

显示此计算机上所有已安装Relay组的状态和版本。不需要sudo 。

relay list
relay list --json
relay list
relay list --json

停止​

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

sudo relay stop <id>
sudo relay stop <id>

重新启动并升级​

Restarts the relay service and fetches the latest proxy configuration from Test Cloud.

sudo relay restart <id>
sudo relay restart <id>

二进制文件升级：下载新的relay二进制文件并运行sudo ./relay restart <id> 。重新启动命令通过 SHA256 哈希将正在运行的二进制文件与已安装的副本进行比较，并在它们不同时自动更新安装的二进制文件。

场景命令
Endpoints added or removed in Test Cloudsudo relay restart <id>
客户端密码轮换 — inlinesudo relay restart --config "<new-config>"
客户端密码轮换 — 文件sudo relay restart --config-file /path/to/new-config.txt
二进制升级下载新的二进制文件，然后 sudo ./relay restart <id>

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

删除​

Stops the service, deregisters from Test Cloud, and removes all local configuration and log files.

sudo relay delete <id>
sudo relay delete <id>

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

sudo relay delete <id> --force
sudo relay delete <id> --force

版本​

relay version
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)

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

/etc/systemd/system/
  relay-<id>.service                         # Systemd unit file
/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)

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

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

文件权限​

路径Mode原因
目录755Relay 读取/写入访问权限
client_config600包含加密的 OAuth 凭据
.credentials.key600AES-256-GCM 加密密钥
metadata.json644服务元数据（状态、PID、安装时间戳）
relay.log644可读用于故障排除
二进制755由 systemd 执行

自定义路径​

覆盖安装时的默认目录：

sudo ./relay start --config-file /path/to/config.txt \
  --bin-dir /opt/mycompany/bin \
  --data-dir /opt/mycompany \
  --logs-dir /opt/mycompany
sudo ./relay start --config-file /path/to/config.txt \
  --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日志文件的根目录

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  /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和--logs-dir仅start命令接受。其他命令（ stop 、 restart 、 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>"
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>"

如果没有-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，请确保允许使用中继客户端二进制文件及其数据目录。

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
# 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

应用程序护符​

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

fapolicyd​

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

要允许的路径​

类型默认路径
二进制/usr/local/bin/relay
数据/var/lib/uipath-relay/
日志/var/log/uipath-relay/

如果您使用了--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>
sudo loginctl enable-linger <username>

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

以用户模式启动​

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

用户模式目录布局​

~/.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)
  logs/<id>/
    relay.log
    relay.YYYYMMDD-HHMMSS.log

~/.config/systemd/user/
  relay-<id>.service                         # Systemd user unit file
~/.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)
  logs/<id>/
    relay.log
    relay.YYYYMMDD-HHMMSS.log

~/.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
relay list
relay stop <id>
relay restart <id>
relay delete <id>
relay logs <id> -f

何时使用用户模式​

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

卸载​

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

    sudo relay delete <id>
sudo relay delete <id>

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

    sudo rm /usr/local/bin/relay
sudo rm /usr/local/bin/relay

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

    sudo rm -rf /var/lib/uipath-relay /var/log/uipath-relay
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错误；验证 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或更高

Diagnostic commands​

# 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 <region>-relay.uipath.com 443

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

# Check AppArmor status
sudo aa-status
# 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 <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
停止sudo relay stop <id>
重新启动/升级sudo relay restart <id>
删除sudo relay delete <id>
删除 (强制)sudo relay delete <id> --force
列表relay list
日志relay logs <id> -f
服务状态systemctl status relay-<id>
Systemd 日志journalctl -u relay-<id> -f

此页面有帮助吗？

连接

需要帮助? 支持

想要了解详细内容？ UiPath Academy

有问题? UiPath 论坛

保持更新