Implantando o cliente de Relay no Windows

Esta página abrange detalhes de configuração de produção específicos do Windows. Para obter pré-requisitos entre plataformas e requisitos de rede, consulte Implantação do cliente de Relay.

Requisitos do sistema operacional

O cliente de Relay usa o Gerenciador de Controle de Serviço (SCM) do Windows para instalar e gerenciar seu serviço em segundo plano. O SCM é integrado a todas as versões do Windows compatíveis — nenhum software adicional é necessário.

Edição	Versão mínima
Windows Server	2019
Área de Trabalho do Windows	10 Enterprise

Requisitos adicionais

• PowerShell 5.1+ — incluído por padrão; usado para gerenciamento de serviços (Get-Service, Test-NetConnection). Verificar: $PSVersionTable.PSVersion.
• Privilégios de administrador — necessários para interagir com o SCM para instalação, início, interrupção e exclusão de serviços; gravar em C:\ProgramData\UiPathRelay\; copie o binário para C:\Program Files\UiPathRelay\.

Por padrão, o serviço é executado como LocalSystem. Para executar em uma conta específica, use --service-account no horário de início — consulte Conta de serviço e permissões.

Lista de verificação de pré-instalação

System

• Windows Server 2019+ ou Windows 10 Enterprise+
• PowerShell 5.1 ou posterior
• Acesso de administrador à máquina de destino
• Espaço mínimo em disco de 200 MB

Rede

• HTTPS de saída (porta 443) para cloud.uipath.com é permitido
• A saída TLS (porta 443) para <region>-relay.uipath.com é permitida
• Passagem TLS configurada para o endpoint do relay (sem inspeção TLS)
• O nó de relay tem acesso à rede para todos os serviços locais que você planeja expor

Segurança

• Conta de serviço criada (se não estiver usando LocalSystem) — consulte Conta de serviço e permissões
• Exclusões do Windows SharePoint e de antivírus planejadas — consulte Proteção de antivírus e ponto de extremidade

Configuração

• Grupo de Relay criado e string de configuração do cliente pronta — consulte Configuração de um grupo de Relay

Comandos de validação (executados no 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

Instalar

1. Baixe e extraia

Arquitetura	Arquivar
x86_64	relay-windows-amd64.zip
ARM 64	relay-windows-arm64.zip

Extraia o arquivo zip. Ele contém um único binário relay.exe , pronto para ser executado.

2. Iniciar

Abra o PowerShell como administrador antes de executar qualquer comando de início.

Você pode fornecer a string de configuração do cliente (da Administração do UiPath — consulte Configuração de um grupo de Relay) de duas maneiras:

Opção A — Em linha. Passe a string de configuração diretamente. Nenhum arquivo para criar ou limpar:

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

Opção B — Arquivo. Salve a configuração em um arquivo e, depois, faça referência a ela. Recomendado — mantém o segredo fora do histórico do shell:

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

Os sinalizadores --config e --config-file são mutuamente exclusivos. Para executar em primeiro plano em vez de como um serviço em segundo plano (útil para depuração), passe --detach=false.

O cliente de Relay valida a conectividade, autentica-se com o OAuth, registra-se no Test Cloud, baixa a configuração de proxy e instala um serviço do Windows, tudo em um único comando.

Saída esperada:

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>")

Durante a inicialização, o cliente de Relay copia automaticamente o binário C:\Program Files\UiPathRelay\relay.exe. Todos os grupos de Relay na máquina compartilham esse binário único. Substitua o diretório de instalação por --bin-dir.

Para iniciar em uma conta de serviço personalizada em vez de LocalSystem:

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

3. Verificar

.\relay.exe list

Um cliente íntegro mostra ● running na coluna Status. O valor ID mostrado é usado em todos os comandos subsequentes (.\relay.exe stop <id>, .\relay.exe logs <id>, e assim por diante). Você também pode encontrá-lo na UiPath Administration na página de detalhes do grupo de Relay.

Confirme que o túnel foi estabelecido verificando os logs para login to server success:

.\relay.exe logs <id> -f

Gerenciar

Todos os comandos de gerenciamento exigem o Administrator PowerShell, exceto list e version.

List

Mostra todos os grupos de relay instalados nesta máquina com status e versão. Não requer privilégios de Administrator.

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

Parar

Interrompe o Serviço de Relay. A configuração e os logs são retidos — o relay pode ser reiniciado posteriormente.

.\relay.exe stop <id>

Reiniciar e atualizar

Reinicia o serviço de Relay e busca a configuração de proxy mais recente do Test Cloud.

.\relay.exe restart <id>

Atualização binária: baixe o novo relay.exe e execute .\relay.exe restart <id> a partir dele. O comando restart compara o binário em execução com a cópia instalada pelo hash SHA256 e atualiza o binário instalado automaticamente se eles forem diferentes.

Cenário	Command
Pontos de extremidade adicionados ou removidos no Test Cloud	.\relay.exe restart <id>
Rotação de segredo do cliente — em linha	.\relay.exe restart --config "<new-config>"
Rotação de segredo do cliente — arquivo	.\relay.exe restart --config-file new-config.txt
Atualização binária	Baixe novo binário e, em seguida, .\relay.exe restart <id>

Quando ou --config é fornecido, <id> --config-file opcional — ele é extraído da configuração.

Excluir

Interrompe o serviço, cancela o registro do Test Cloud e remove todas as configurações locais e arquivos de log.

.\relay.exe delete <id>

Para forçar a limpeza local sem o cancelamento do registro da nuvem — por exemplo, se as credenciais forem perdidas ou o grupo de relay do lado da nuvem já tiver sido excluído:

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

Versão

.\relay.exe version

Não há atualização automática. Para atualizar, baixe o novo binário e .\relay.exe restart <id> para cada grupo.

Estrutura de diretório

Todos os diretórios são criados automaticamente na primeira execução.

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

O nome de serviço do Windows é Relay-<id> e o nome de exibição (exibido em services.msc) é Relay - <id>. O tipo de inicialização é Automático; a conta padrão é LocalSystem.

Caminhos personalizados

Substitua os diretórios padrão no momento da instalação:

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

Bandeira	Padrão	Description
--bin-dir	C:\Program Files\UiPathRelay	Diretório para o binário compartilhado
--data-dir	C:\ProgramData	Raiz dos dados de configuração
--logs-dir	C:\ProgramData	Raiz dos arquivos de log

O cliente de Relay anexa UiPathRelay\ sob os dados personalizados e raiz de log:

--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 e --logs-dir são aceitos apenas pelo comando start . Outros comandos (stop, restart, delete, list) descobrem caminhos automaticamente a partir da configuração do serviço instalado.

Conta de serviço e permissões

Esta seção se aplica apenas ao executar o serviço em uma conta personalizada em vez da padrão LocalSystem.

Direitos de usuário necessários

Direita	Description	Como configurar
SeServiceLogonRight	Fazer login como um serviço	Política de Segurança Local > Atribuição de Direitos do Usuário > Fazer logon como um serviço

Para ambientes de domínio, configure esse direito por meio da Política de Grupo para garantir a consistência entre os servidores.

Permissões do NTFS

Path	Permissões necessárias
C:\Program Files\UiPathRelay\	Ler e Executar
C:\ProgramData\UiPathRelay\	Ler, Escrever, Modificar
C:\ProgramData\UiPathRelay\logs\	Ler, Escrever, Modificar, Excluir

Via 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

Começando com uma conta de serviço personalizada

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

--service-account-password é necessário para contas de usuário de domínio ou local. As contas de serviço gerenciado (gMSA) não exigem uma senha.

Contas de serviço gerenciado por grupo (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$"

Os gMSAs rotacionam senhas automaticamente e eliminam a sobrecarga de gerenciamento de credenciais.

Detalhes do Serviço do Windows

Visualização do status do serviço

Por meio do console de Serviços

1. Abra Executar (Win + R) e digite services.msc.
2. Localize o serviço com o nome de exibição Relay - <id>.
3. Clique com o botão direito do mouse para iniciar, parar, reiniciar ou exibir as propriedades.

Via 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

Recuperação de serviço

Quando o cliente de Relay se instala como um serviço, ele configura a recuperação automática:

• Primeira falha: reiniciar após 10 segundos
• Segunda falha: reiniciar após 30 segundos
• Falhas subsequentes: reinicie com atrasos escalonados

Para revisar ou ajustar as configurações de recuperação: services.msc > clique com o botão direito do mouse no serviço > Propriedades > guia Recuperação .

Visualizador de eventos

Use o Visualizador de eventos (eventvwr.msc) para diagnosticar problemas de serviço.

Registro	Path	Events
System	Logs do Windows > Sistema	Início, interrupção, falha e recuperação do serviço (série 7000)
Aplicativo	Logs do Windows > Aplicativo	Erros do aplicativo

Consultar eventos de relay por meio do 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 do Evento	Significado
7000	Falha ao iniciar o serviço. Verifique as permissões da conta
7009	Tempo limite aguardando serviço — verifique a conectividade de rede
7031	Serviço falhou e ação de recuperação realizada — verificar relay.log
7034	O serviço foi encerrado de forma inesperada — verifique se há esgotamento do recurso
7045	Novo serviço instalado — confirma a instalação bem-sucedida

Proxy Configuration

Os serviços do Windows herdam variáveis de ambiente do sistema (HKLM). Defina variáveis de proxy no nível da máquina antes de iniciar o cliente de Relay:

[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>"

Definir variáveis de proxy no nível do usuário não é suficiente — os serviços do sistema ignoram variáveis de ambiente no nível do usuário.

Para atualizar o proxy: altere a variável de nível do sistema e .\relay.exe restart <id>.

Para remover o proxy: [Environment]::SetEnvironmentVariable("HTTPS_PROXY", $null, "Machine"), em seguida, .\relay.exe restart <id>.

Para verificar: [Environment]::GetEnvironmentVariable("HTTPS_PROXY", "Machine").

Para esquemas de proxy e autenticação compatíveis, consulte a seção proxy em Implantação do cliente de Relay.

Firewall do Windows

Se o tráfego de saída for restrito pelo Firewall do Windows, adicione uma regra de saída para o binário do cliente de Relay.

Configuração	Valor
Direction	Perdida
Programa	C:\Program Files\UiPathRelay\relay.exe
Protocolo/Porta	TCP/443
Perfis	Domínio, Particular

Via 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

Por meio da GUI (Firewall do Windows Firewall com Segurança Avançada):

1. Abra wf.msc.
2. Selecione Regras de saída > Nova regra.
3. Escolha Programa e especifique: C:\Program Files\UiPathRelay\relay.exe.
4. Selecione Permitir a conexão.
5. Aplicar aos perfis Domínio e Privado .
6. Nomeie a regra: UiPath Relay - Outbound HTTPS.

Se sua organização gerenciar regras de firewall por meio da Política de Grupo ou de um firewall de terceiros, trabalhe com seu administrador do Windows para adicionar uma regra equivalente.

Proteção de antivírus e ponto de extremidade

Adicione exclusões para o binário do cliente de Relay e seus diretórios de dados para evitar interferência.

Tipo	Path
Binário	C:\Program Files\UiPathRelay\relay.exe
Dados e logs	C:\ProgramData\UiPathRelay\

Se você usou caminhos personalizados por meio de --bin-dir, --data-dir ou --logs-dir, exclua esses caminhos em vez disso.

Windows Dever — por meio do PowerShell

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

Windows Dever — via GUI

1. Abra Segurança do Windows > Proteção de email e ameaças > Gerenciar configurações.
2. Em Exclusões, selecione Adicionar ou remover exclusões.
3. Adicione as exclusões de pasta: C:\Program Files\UiPathRelay\ e C:\ProgramData\UiPathRelay\.
4. Adicionar exclusão de processo: relay.exe.

Para proteção de ponto de extremidade gerenciada centralmente (CrowdStrike, Cyber Dindos, Orchestrator

Desinstalar

1. Exclua todos os clientes do Relay (use .\relay.exe list para ver os grupos instalados):

   .\relay.exe delete <id>
   

2. Remova o binário compartilhado:

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

3. Remova os diretórios de dados restantes:

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

4. Remova exclusões do Windows Developer:

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

5. Remova a regra do Firewall do Windows:

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

Para regras adicionadas por meio da Política de Grupo ou de um firewall de terceiros, trabalhe com o administrador do Windows para removê-las.

Solução de problemas

Problema	Causa	Resolution
Falha ao iniciar o serviço	Permissões insuficientes	Abra o PowerShell como administrador
permission denied	Não é possível gravar em Arquivos de Programa ou DadosDePrograma	Verifique o acesso do Administrator ou use --bin-dir / --data-dir para caminhos graváveis
does not have the 'Log on as a service' right	Conta personalizada ausente SeServiceLogonRight	Conceda por meio da Política de Segurança Local > Atribuição de Direitos do Usuário ou use a Política de Grupo
not a valid Windows account	Formato incorreto para --service-account	Use .\username para contas locais ou DOMAIN\username para contas de domínio
marked for deletion / serviço pendente de exclusão	services.msc tem um identificador aberto	services.msc e tente novamente; reinicie se o problema persistir
service is disabled	Desabilitado por meio de services.msc ou da Política de Grupo	Reabilitar: Set-Service -Name "Relay-<id>" -StartupType Automatic
file is locked by another process	Binário em uso durante a atualização	Interrompa o serviço do cliente de Relay primeiro e depois tente novamente
path exceeds Windows path length limit	O caminho de dados/logs excede 260 caracteres	Use caminhos mais curtos para --data-dir e --logs-dir
Bloqueio de antivírus relay.exe	Binário em quarentena da proteção do endpoint	adicionar exclusões (consulte Proteção de antivírus e ponto de extremidade); verificar quarentena e restaurar
Serviço em execução, mas túnel não estabelecido	Problema de rede ou autenticação	Verifique se login to server relay.log ; verificar senha do TLS
DPAPI decrypt failed	Identidade da máquina alterada após clonagem ou nova imagem da VM	Reprovisione o relay com uma nova configuração da administração do UiPath
Proxy não usado pelo serviço	Proxy definido no nível do usuário, não no nível do sistema	Defina HTTPS_PROXY no nível da máquina (consulte Configuração do proxy); reinicie o serviço

Comandos de diagnóstico

# 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

Para erros de autenticação e conectividade compartilhados entre plataformas, consulte Solução de problemas.

Referência rápida

Ação	Command
Iniciar	.\relay.exe start --config-file config.txt
Parar	.\relay.exe stop <id>
Reiniciar/atualizar	.\relay.exe restart <id>
Excluir	.\relay.exe delete <id>
Excluir (forçar)	.\relay.exe delete <id> --force
List	.\relay.exe list
Logs	.\relay.exe logs <id> -f
Status do serviço	Get-Service "Relay-<id>"
Console de serviços	services.msc