在 Windows 上部署中继客户端

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

操作系统要求

Relay 客户端使用Windows 服务控制管理器 (SCM)安装和管理其后台服务。SCM 内置在所有受支持的 Windows 版本中，无需其他软件。

版本	最低版本
Windows 服务器	2019 年
Windows 桌面	10 个企业

其他要求

• PowerShell 5.1+ — 默认包含；用于服务管理（ Get-Service 、 Test-NetConnection ）。验证： $PSVersionTable.PSVersion 。
• 管理员权限— 与 SCM 交互以安装、启动、停止和删除服务所需的权限；写入至C:\ProgramData\UiPathRelay\ ；将二进制文件复制到C:\Program Files\UiPathRelay\ 。

默认情况下，该服务以LocalSystem运行。要在特定帐户下运行，请在开始时使用--service-account — 请参阅服务帐户和权限。

安装前检查清单

系统

• Windows Server 2019+ 或 Windows 10 企业版+
• PowerShell 5.1 或更高版本
• 目标计算机的 Administrator 访问权限
• 至少 200 MB 可用磁盘空间

网络

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

安全性

• 已创建服务帐户（如果未使用LocalSystem ）— 请参阅服务帐户和权限
• 已计划的 Windows Defender 和防病毒排除项 — 请参阅防病毒和端点保护

配置

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

验证命令（在 PowerShell 中运行）：

# Check PowerShell version (must be 5.1+)
$PSVersionTable.PSVersion

# Verify Administrator access
([Security.Principal.WindowsPrincipal][Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)

# Check available disk space
Get-PSDrive C | Select-Object Used, Free

快速入门

1. 下载并提取

架构	存档
x86_64	Relay-windows-amd64.zip
ARM64	Relay-windows-arm64.zip

提取该 zip 存档。它包含一个relay.exe二进制文件，可随时运行。

2. 开始

在运行任何启动命令之前，以管理员身份打开 PowerShell 。

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

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

.\relay.exe start --config "<your-config>"

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

Set-Content -Path "config.txt" -Value "<your-config>"
.\relay.exe start --config-file C:\path\to\config.txt

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

Relay 客户端可验证连接、使用 OAuth 进行身份验证、向 Automation Cloud 注册、下载代理配置以及安装 Windows 服务 — 所有这些操作都只需一条命令即可完成。

预期输出：

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:
  PowerShell: Get-Service "Relay-<id>"
  Services:   services.msc (look for "Relay - <id>")

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

要在自定义服务帐户而不是LocalSystem下启动，请执行以下操作：

.\relay.exe start --config-file C:\path\to\config.txt `
  --service-account "DOMAIN\svc-relay" `
  --service-account-password "password"

3. 验证

.\relay.exe list

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

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

.\relay.exe logs <id> -f

管理

所有管理命令都需要管理员 PowerShell ，但list和version除外。

列表

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

.\relay.exe list
.\relay.exe list --json

停止

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

.\relay.exe stop <id>

重新启动并升级

重新启动中继服务，并从 Automation Cloud 获取最新的代理配置。

.\relay.exe restart <id>

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

场景	命令
在 Automation Cloud 中添加或删除的端点	.\relay.exe restart <id>
客户端密码轮换 — inline	.\relay.exe restart --config "<new-config>"
客户端密码轮换 — 文件	.\relay.exe restart --config-file new-config.txt
二进制升级	下载新的二进制文件，然后 .\relay.exe restart <id>

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

删除

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

.\relay.exe delete <id>

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

.\relay.exe delete <id> --force

版本

.\relay.exe version

不会自动升级。要更新，请下载新的二进制文件，然后为每组运行.\relay.exe restart <id> 。

目录结构

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

C:\Program Files\UiPathRelay\
  relay.exe                                  # Shared binary

C:\ProgramData\UiPathRelay\
  groups\<id>\
    client_config                            # OAuth credentials (encrypted via DPAPI)
    metadata.json                            # State, PID, install timestamps
    .credentials.key                         # Encryption key
  logs\<id>\
    relay.log                                # Current log
    relay.YYYYMMDD-HHMMSS.log                # Rotated logs

Windows 服务名称为Relay-<id> ，显示名称（显示在services.msc中）为Relay - <id> 。“启动类型”为“自动”；默认帐户为LocalSystem 。

自定义路径

覆盖安装时的默认目录：

.\relay.exe start --config-file C:\path\to\config.txt `
  --bin-dir "D:\MyCompany\bin" `
  --data-dir "D:\MyCompany" `
  --logs-dir "D:\MyCompany"

标记	默认	描述
--bin-dir	C:\Program Files\UiPathRelay	共享二进制文件的目录
--data-dir	C:\ProgramData	配置数据的根
--logs-dir	C:\ProgramData	日志文件的根目录

Relay 客户端会在自定义数据和日志根目录下附加UiPathRelay\ ：

--bin-dir  D:\MyCompany\bin  =>  D:\MyCompany\bin\relay.exe
--data-dir D:\MyCompany      =>  D:\MyCompany\UiPathRelay\groups\<id>\
--logs-dir D:\MyCompany      =>  D:\MyCompany\UiPathRelay\logs\<id>\

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

服务帐户和权限

本部分仅适用于在自定义帐户而不是默认帐户LocalSystem下运行服务的情况。

所需用户权限

右侧	描述	如何配置
SeServiceLogonRight	作为服务登录	“本地安全策略”>“用户权限分配”>“作为服务登录”

对于域环境，请通过组策略配置此权限，以确保服务器之间的一致性。

NTFS 权限

路径	所需权限
C:\Program Files\UiPathRelay\	Read & Execute
C:\ProgramData\UiPathRelay\	读取、写入、修改
C:\ProgramData\UiPathRelay\logs\	读取、写入、修改、删除

通过 PowerShell

$account = "DOMAIN\svc-relay"

$acl = Get-Acl "C:\Program Files\UiPathRelay"
$rule = New-Object System.Security.AccessControl.FileSystemAccessRule($account, "ReadAndExecute", "ContainerInherit,ObjectInherit", "None", "Allow")
$acl.SetAccessRule($rule)
Set-Acl "C:\Program Files\UiPathRelay" $acl

$acl = Get-Acl "C:\ProgramData\UiPathRelay"
$rule = New-Object System.Security.AccessControl.FileSystemAccessRule($account, "Modify", "ContainerInherit,ObjectInherit", "None", "Allow")
$acl.SetAccessRule($rule)
Set-Acl "C:\ProgramData\UiPathRelay" $acl

从自定义服务帐户开始

.\relay.exe start --config-file C:\path\to\config.txt `
  --service-account "DOMAIN\svc-relay" `
  --service-account-password "password"

域或本地用户帐户需要--service-account-password 。托管服务帐户 (gMSA) 不需要密码。

组托管服务帐户 (gMSA)

# Install the gMSA on the server (run once per server)
Install-ADServiceAccount -Identity "gMSA-Relay$"

# Start the Relay client with gMSA (no password required)
.\relay.exe start --config-file config.txt --service-account "DOMAIN\gMSA-Relay$"

gMSA 会自动轮换密码，并消除凭据管理开销。

Windows 服务详细信息

查看服务状态

通过“服务”控制台

1. 打开“运行” ( Win + R )，然后输入services.msc 。
2. 找到显示名称为Relay - <id>服务。
3. 单击右键以启动、停止、重新启动或查看属性。

通过 PowerShell

# All Relay services
Get-Service "Relay-*"

# Detailed information
Get-Service "Relay-<id>" | Format-List *

# Service configuration (account, start mode)
Get-CimInstance Win32_Service -Filter "Name LIKE 'Relay-%'" | Select-Object Name, StartMode, State, StartName

服务恢复

当中继客户端将自身安装为服务时，它会配置自动恢复：

• 第一次失败： 10 秒后重新启动
• 第二次失败： 30 秒后重新启动
• 后续故障：重新启动，且延迟时间逐步升级

要查看或调整恢复设置：打开services.msc > 右键单击服务 > “属性” > “恢复”选项卡。

事件查看器

使用事件查看器 ( eventvwr.msc ) 诊断服务问题。

日志	路径	Events
系统	“Windows 日志”>“系统”	服务的启动、停止、崩溃和恢复（7000 系列）
应用程序	Windows 日志 > 应用程序	应用程序错误

通过 PowerShell 查询中继事件

Get-WinEvent -FilterHashtable @{LogName='System'; ID=7000,7009,7031,7034,7036,7045} -MaxEvents 100 |
  Where-Object { $_.Message -like '*Relay*' } |
  Format-Table TimeCreated, Id, Message -Wrap

活动 ID	意义
7000	服务启动失败 — 请检查帐户权限
7009	等待服务超时 — 检查网络连接
7031	服务已崩溃并已采取恢复操作 — 检查 relay.log
7034	服务意外终止 — 检查资源是否耗尽
7045	已安装新服务 — 确认安装成功

代理配置

Windows 服务从系统 (HKLM) 继承环境变量。在启动中继客户端之前，在“计算机”级别设置代理变量：

[Environment]::SetEnvironmentVariable("HTTPS_PROXY", "http://proxy.corp.example.com:8080", "Machine")
[Environment]::SetEnvironmentVariable("NO_PROXY", "localhost,127.0.0.1,.corp.example.com", "Machine")
.\relay.exe start --config "<your-config>"

在用户级别设置代理变量是不够的，系统服务会忽略用户级别的环境变量。

要更新代理：更改系统级变量并运行.\relay.exe restart <id> 。

要删除代理： [Environment]::SetEnvironmentVariable("HTTPS_PROXY", $null, "Machine") ，然后是.\relay.exe restart <id> 。

待验证： [Environment]::GetEnvironmentVariable("HTTPS_PROXY", "Machine") 。

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

Windows 防火墙

如果出站流量受到 Windows 防火墙的限制，请为中继客户端二进制文件添加出站规则。

设置	值
方向	呼出电话
程序	C:\Program Files\UiPathRelay\relay.exe
协议/端口	TCP/443
配置文件	域，私有

通过 PowerShell

New-NetFirewallRule -DisplayName "UiPath Relay - Outbound HTTPS" `
  -Direction Outbound `
  -Program "C:\Program Files\UiPathRelay\relay.exe" `
  -Protocol TCP `
  -RemotePort 443 `
  -Action Allow `
  -Profile Domain,Private

# Verify rule
Get-NetFirewallRule -DisplayName "UiPath Relay*" | Format-Table Name, Enabled, Direction, Action

通过 GUI （高级安全 Windows Defender 防火墙）：

1. 打开wf.msc 。
2. 选择“出站规则” > “新建规则” 。
3. 选择“程序”并指定： C:\Program Files\UiPathRelay\relay.exe 。
4. 选择“允许连接” 。
5. 应用到域配置文件和私有配置文件。
6. 将规则命名为： UiPath Relay - Outbound HTTPS 。

如果您的组织通过组策略或第三方防火墙管理防火墙规则，请与 Windows 管理员合作添加等效规则。

防病毒和端点保护

为中继客户端二进制文件及其数据目录添加排除项，以防止干扰。

类型	路径
二进制	C:\Program Files\UiPathRelay\relay.exe
数据和日志	C:\ProgramData\UiPathRelay\

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

Windows Defender — 通过 PowerShell

Add-MpPreference -ExclusionPath "C:\Program Files\UiPathRelay"
Add-MpPreference -ExclusionPath "C:\ProgramData\UiPathRelay"
Add-MpPreference -ExclusionProcess "relay.exe"

Windows Defender — 通过 GUI

1. 打开“Windows 安全” > “病毒和威胁防护” > “管理设置” 。
2. 在“排除”下，选择“添加或删除排除” 。
3. 添加文件夹排除项： C:\Program Files\UiPathRelay\和C:\ProgramData\UiPathRelay\ 。
4. 添加流程排除项： relay.exe 。

对于集中管理的端点保护（通过 Intune/SCCM 进行的 CrowdStrike、Salesforce、Microsoft Defender for Endpoint），请与安全管理员合作添加上述排除项。

卸载

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

   .\relay.exe delete <id>
   

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

   Remove-Item "C:\Program Files\UiPathRelay" -Recurse
   

3. 删除剩余的数据目录：

   Remove-Item "C:\ProgramData\UiPathRelay" -Recurse
   

4. 删除 Windows Defender 排除项：

   Remove-MpPreference -ExclusionPath "C:\Program Files\UiPathRelay"
   Remove-MpPreference -ExclusionPath "C:\ProgramData\UiPathRelay"
   Remove-MpPreference -ExclusionProcess "relay.exe"
   

5. 删除 Windows 防火墙规则：

   Remove-NetFirewallRule -DisplayName "UiPath Relay - Outbound HTTPS"
   

对于通过组策略或第三方防火墙添加的规则，请与 Windows 管理员合作将其删除。

故障排除

症状	原因	分辨率
服务无法启动	权限不足	以管理员身份打开 PowerShell
permission denied	无法写入Program Files或ProgramData	验证管理员访问权限，或对可写路径使用--bin-dir / --data-dir
does not have the 'Log on as a service' right	缺少自定义帐户 SeServiceLogonRight	通过“本地安全策略”>“用户权限分配”授予，或使用组策略
not a valid Windows account	的格式错误 --service-account	使用.\username对于本地帐户或DOMAIN\username对于域帐户
marked for deletion /服务待删除	services.msc 有一个打开的句柄	关闭services.msc并重试；如果问题仍然存在，请重新启动
service is disabled	已通过services.msc或组策略禁用	重新启用： Set-Service -Name "Relay-<id>" -StartupType Automatic
file is locked by another process	更新期间使用的二进制文件	请先停止中继客户端服务，然后重试
path exceeds Windows path length limit	数据/日志路径超过 260 个字符	对--data-dir和--logs-dir使用较短路径
杀毒软件拦截 relay.exe	端点保护隔离的二进制文件	添加排除项（请参阅防病毒和端点保护）；选中隔离区和还原区
服务正在运行，但未建立隧道	网络或身份验证问题	检查relay.log的login to server错误；验证 TLS 直通
DPAPI decrypt failed	克隆或重新映像虚拟机后，计算机身份已更改	使用“UiPath 管理”中的新配置重新配置中继
服务未使用代理	代理设置在用户级别，而非系统级别	在计算机级别设置HTTPS_PROXY （请参阅代理配置）；重新启动服务

诊断命令

# Real-time logs
.\relay.exe logs <id> -f

# Service details
Get-Service "Relay-<id>" | Format-List *

# Connectivity test
Test-NetConnection -ComputerName <region>-relay.uipath.com -Port 443

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

快速参考

操作	命令
启动	.\relay.exe start --config-file config.txt
停止	.\relay.exe stop <id>
重新启动/升级	.\relay.exe restart <id>
删除	.\relay.exe delete <id>
删除 (强制)	.\relay.exe delete <id> --force
列表	.\relay.exe list
日志	.\relay.exe logs <id> -f
服务状态	Get-Service "Relay-<id>"
服务控制台	services.msc