Implantação do cliente de Relay

Instale e inicie o cliente de Relay em uma máquina dentro de sua rede para estabelecer o túnel de saída para o Test Cloud. Antes de começar, configure um grupo de Relay e tenha a string de configuração do cliente pronta.

Pré-requisitos

Requisitos de Hardware

Perfil	vCPU	BATER	Grupos de Relay	Endpoints por grupo	Use case
Padrão	1	2 GB	Até 10	Até 50	A maioria das implantações
Grande	2	4GB	10+	Até 50	Ambientes de alta taxa de transferência ou grande escala

Esses são requisitos mínimos para o processo do cliente de Relay. Se a máquina executar outras cargas de trabalho, provisione recursos adicionais conforme necessário.

Requisitos do disco

Perfil	Mínimo de disco livre
Padrão (1 a 10 grupos)	200 MB
Grande (mais de 10 grupos)	1 GB

Sistemas operacionais compatíveis

Arquitetura	Linux	Windows
x86_64 (amd64)	Suportado	Suportado
ARM64 (aarch64)	Suportado	Suportado

Requisitos de rede

O cliente de Relay requer conectividade apenas de saída. Nenhuma regra de firewall de entrada é necessária.

A partir do cliente de Relay 26.4.2, as novas configurações de cliente de Relay podem conectar o túnel persistente por meio da URL padrão do Automation Cloud, cloud.uipath.com. Essas configurações não exigem uma lista de permissões do nome do host do relay específica da região para o túnel.

Configuração do cliente de Relay	Protocol	Porta	Destino	Passagem TLS necessária	Finalidade
Cliente de Relay 26.4.2 ou posterior	HTTPS/WSS	443	cloud.uipath.com	Não é necessário	Autenticação, registro de relay e túnel persistente
Relay versões do cliente anteriores à 26.4.2	TLS	443	<region>-relay.uipath.com	Required	Túnel persistente

As versões do cliente de Relay anteriores a 26.4.2 continuam a funcionar com nomes de host de Relay regionais. Mantenha esses nomes de host na lista de permissões até que você mude para o cliente de Relay 26.4.2 ou posterior e conecte-se por meio de cloud.uipath.com.

Para versões do cliente de Relay anteriores a 26.4.2, substitua <region> pela região do seu tenant do Test Cloud.

Região	Nome do host do servidor de relay
NÓS	us-relay.uipath.com
UE	eu-relay.uipath.com
Canadá	ca-relay.uipath.com
Suíça	ch-relay.uipath.com
Austrália	au-relay.uipath.com
Singapura	sg-relay.uipath.com
Japão	jp-relay.uipath.com
Coreia do Sul	kr-relay.uipath.com
Emirados Árabes Unidos	ae-relay.uipath.com
Reino Unido	uk-relay.uipath.com
GXP UE	gxp-eu-relay.uipath.com
GXP EUA	gxp-us-relay.uipath.com

Observação:

Entre em contato com o suporte da UiPath para confirmar o nome do host do servidor de relay se a região do seu tenant não estiver listada acima.

Escolha a região que corresponde à sua região de tenant do UiPath Cloud, não a localização física do nó de relay. Por exemplo, se seu tenant for provisionado na região dos EUA, use us-relay.uipath.com que o próprio relay seja executado em uma geografia diferente. As configurações do cliente de Relay 26.4.2 que se conectam por meio de cloud.uipath.com não usam esse nome de host regional.

Latency considerations

Considerações sobre latência: como o tráfego atravessa o UiPath Cloud → Servidor de Relay → nó de Relay → serviço no local, colocar o nó de relay geograficamente próximo da região do seu tenant minimiza o tempo de ida e volta e melhora a taxa de transferência geral.

Relay client 26.4.2 configurations

For Relay client 26.4.2 configurations that connect through cloud.uipath.com, configure firewalls and proxies to allow HTTPS traffic and WebSocket upgrades to cloud.uipath.com:443.

If a proxy inspects TLS for cloud.uipath.com, install the proxy's signing CA in the OS trust store used by the Relay client, and make sure the proxy allows WebSocket upgrades.

Relay versões do cliente anteriores à 26.4.2

For Relay client versions earlier than 26.4.2, configure your firewall and any TLS-inspecting proxy or DLP appliance to allow TLS passthrough for <region>-relay.uipath.com:443; TLS inspection on the regional relay hostname breaks the relay tunnel.

A máquina que executa o cliente de Relay também deve ter acesso de rede direto a todos os serviços locais que você planeja expor. Planeje o posicionamento do cliente de Relay corretamente.

Importante:

O nó de relay deve ser capaz de resolver o nome do host e abrir uma conexão com a porta registrada para cada ponto de extremidade em seu grupo de relay no runtime. O caminho de roteamento é flexível — uma rota de rede direta, proxy de saída corporativo ou jump host são aceitáveis — desde que a conexão seja bem-sucedida a partir do nó de relay. Planeje o posicionamento para que todos os pontos de extremidade no grupo permaneçam acessíveis.

largura de banda

O canal de controle (pulsação e autenticação) usa aproximadamente 1–2 KB/minuto quando inativo. O tráfego de dados escala com o volume de solicitações que seus serviços de nuvem enviam para endpoints locais — o relay atua como um túnel transparente sem nenhum adicional além do TLS sobrecarga e estruturação WebSocket leve para conexões cloud.uipath.com .

Verificar conectividade

Antes de instalar o cliente de Relay, confirme se o tráfego de saída na porta 443 é permitido para os destinos necessários para sua configuração.

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

Um resultado bem-sucedido mostra TcpTestSucceeded : True no Windows e succeeded no Linux. Se uma verificação necessária falhar, revise suas regras de firewall. Para configurações do cliente de Relay 26.4.2 que se conectam por meio de cloud.uipath.com, confirme se as atualizações do WebSocket são permitidas; para versões do cliente de Relay anteriores à 26.4.2, confirme se a senha TLS está configurada para o nome do host do servidor de Relay.

Configure um proxy (se aplicável)

Se sua rede rotear o tráfego de saída por meio de um proxy, defina as seguintes variáveis de ambiente antes de relay start. O cliente de Relay aplica o proxy a todas as conexões de saída.

Variável	Finalidade
HTTPS_PROXY / https_proxy	URL do proxy (verificado primeiro)
HTTP_PROXY / http_proxy	URL do proxy (retorno)
NO_PROXY / no_proxy	Hosts ou domínios separados por vírgulas que ignoram o proxy

O URL do proxy deve usar um desses esquemas: http://, https://, socks5:// ou ntlm://. Formato: scheme://[user:password@]host:port.

Para proxies https:// : o cliente de Relay valida o certificado TLS do proxy contra o armazenamento de confiança do SO. Se seu proxy usar uma CA corporativa ou autoassinada, adicione essa CA ao armazenamento de confiança da máquina cliente de Relay antes de iniciar o relay; caso contrário, o handshake do TLS falhará com um erro de verificação de certificado.

For Relay client 26.4.2 configurations that connect through cloud.uipath.com, configure your proxy to allow long-lived HTTPS connections and WebSocket upgrades to cloud.uipath.com:443. If the proxy inspects TLS for cloud.uipath.com, install the proxy's signing CA in the OS trust store used by the Relay client.

For Relay client versions earlier than 26.4.2, configure your proxy to bypass TLS inspection for <region>-relay.uipath.com:443. PAC files, WPAD auto-discovery, and proxy chaining are not supported — set the proxy URL explicitly. When a proxy is detected, the prerequisite checks show via proxy in the output.

Segurança: o cliente de Relay edita senhas de proxy em logs. No entanto, as credenciais definidas em variáveis de ambiente podem ser visíveis em listagens de processos e arquivos de unidade do systemd. Use credenciais de serviço dedicadas e restrinja o acesso ao nó de relay adequadamente.

Configurar IPs confiáveis (se aplicável)

Se sua organização restringir o acesso por endereço IP, adicione o IP NAT da máquina que executa o cliente de Relay à lista de IPs Confiáveis na UiPath Administration. O tráfego de saída do cliente de Relay chega ao Test Cloud a partir desse endereço IP, portanto, você deve permiti-lo explicitamente.

Para obter instruções, consulte Adicionar intervalos de IP confiáveis.

Aceite o contrato de licença

Antes de iniciar o cliente de Relay, você deve aceitar o contrato de licença. Escolha um dos seguintes métodos:

Opção 1 (variável de ambiente) — Defina a variável de ambiente LICENSE_AGREEMENT para aceitar:

Linux

export LICENSE_AGREEMENT=accept

Windows

$env:LICENSE_AGREEMENT=accept

Opção 2 (parâmetro incorporado) — Acrescentar --accept-license-agreement ao comando relay start :

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

Guias de configuração

Para implantações de produção, consulte o guia de plataforma do seu sistema operacional — ele abrange a estrutura de diretório, gerenciamento de serviços, configuração da estrutura de segurança e procedimentos de desinstalação:

Plataforma	Guia
Linux	Implantação do cliente de Relay no Linux
Windows	Implantando o cliente de Relay no Windows
Contêiner	Implantação do cliente de Relay como um contêiner

Operações

Resiliência da conexão

O cliente de Relay mantém o túnel automaticamente:

• Pulsações a cada 30 segundos por padrão (configurável via --heartbeat-interval, mínimo 10 segundos). O tempo limite do túnel é 3 × o intervalo de pulsação. Reduza o intervalo se seu firewall, proxy ou NAT descartar conexões TCP ociosas antes de 30 segundos:

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

• Reconexão automática ao desconectar, usando o dimensionamento de espera exponencial para intervalos de 20 segundos.
• Reinicialização automática do serviço se o processo falhar, gerenciada pelo systemd no Linux e pelo Gerenciador de Controle de Serviços do Windows no Windows.
• Início automático do serviço na reinicialização do sistema.

Reconexão proativa

Algumas redes — por trás de um proxy corporativo, balanceador de carga ou firewall com um tempo limite de conexão ociosa — encerram silenciosamente conexões TLS de longa duração. A reconexão proativa restaura a conexão de controle em um cronograma fixo para evitar isso.

Habilite-o com o sinalizador --reconnect-interval :

relay start --config "<config>" --reconnect-interval 1800

O mínimo efetivo é de 1800 segundos (30 minutos). Defina o intervalo para aproximadamente metade do tempo limite ocioso de seu dispositivo de rede — por exemplo, 1800 segundos para um tempo limite de firewall de 60 minutos. Deixe desabilitado em redes estáveis sem um tempo limite de conexão ociosa.

• Descarga suave. Quando o intervalo transcorre, o cliente de Relay para de aceitar novo trabalho e aguarda as conexões em andamento serem concluídas — até um tempo limite de drenagem de 300 segundos — antes de fechar a conexão antiga e abrir uma nova. As solicitações ainda em andamento quando o tempo limite de drenagem é atingido são encerradas.

• Alta disponibilidade. Quando vários clientes do Relay são implantados no mesmo grupo, eles se coordenam para que apenas um cliente seja drenado de cada vez. O grupo continua atendendo o tráfego ao longo de cada ciclo de reconexão.

• Indica que a reconexão proativa é necessária: os logs mostram erros unexpected EOF ou desconexões silenciosas apesar de uma rede subjacente estável — normalmente causados por um tempo limite ocioso de 30 a 60 minutos em um firewall, proxy ou balanceador de carga.

Recarregar configuração

relay reload <id>

Busca novamente a configuração de proxy do Test Cloud e a aplica sem reiniciar. Alterações no lado da nuvem — novos pontos de extremidade, caminhos de verificação de integridade atualizados — chegam automaticamente a um cliente Relay em execução e normalmente não exigem recarregamento.Use esse comando como fallback apenas se um ponto de extremidade recém-adicionado retornar 404.

Geração de logs

Configuração	Valor
Nível padrão	info
Rotação	Daily
Retenção	7 dias
arquivo de log	relay.log (atual), relay.YYYYMMDD-HHMMSS.log (rotacionado)

Substitua o nível de log padrão por --log-level trace/debug/info/warn/error. No cliente de Relay 26.4.2 ou posterior, substitua a retenção de log rotacionado por --log-retention-days <days> em relay start ou relay restart; a retenção mínima é de 7 dias.

Referência de comando

Início do relay

Provisione um novo cliente de Relay e inicie-o como um serviço em segundo plano.

Configuração (uma necessária)

• -c, --config <string> — string de configuração codificada base64 embutida.
• --config-file <path> — caminho para um arquivo que contém a string de configuração. Recomendado — mantém o segredo fora do histórico do shell.

Ajuste (opcional)

• --heartbeat-interval <sec> intervalo de pulsação do túnel. Padrão 30. Mínimo de 10. O tempo limite do túnel é 3 × esse valor. Menor se seu firewall, NAT ou proxy eliminar o TCP ocioso antes de 30 segundos.
• --reconnect-interval <sec> — intervalo de reconexão proativo. Padrão 0 (desabilitado); mínimo efetivo 1800 (30 minutos) quando definido.
• --log-level <level> — trace, debug, info, warn ou error. Padrão info.
• --log-retention-days <days> — número de dias para reter arquivos de log rotacionados. Padrão 7. Mínimo de 7. Requer o cliente de Relay 26.4.2 ou posterior.
• -d, --detach=false — executado em primeiro plano em vez de como um serviço em segundo plano. Útil para depurar problemas de inicialização.

Caminhos de instalação não padrão (opcional)

• --data-dir <path> — diretório de configuração.
• --logs-dir <path> — diretório do arquivo de log.
• --bin-dir <path> — diretório de instalação binário.

Apenas Linux

• --user-mode — instale como um serviço de usuário do sistema (sem sudo necessário, usa caminhos XDG).

Windows apenas

• --service-account <DOMAIN\user> execute o serviço do Windows em uma conta específica. O padrão é LocalSystem.
• --service-account-password <password> — senha para --service-account.

Reinicialização do relay

Stop and restart the Relay client service. Detects updated binaries and applies service definition changes.

The following flags can be overridden at restart time (all default to unchanged unless noted):

• --config / --config-file — substitua a configuração do cliente.
• --accept-license-agreement aceite o contrato de licença durante a reinicialização, útil ao atualizar um serviço instalado mais antigo que não persistiu a aceitação da licença.
• --log-level altere o nível de log.
• --logs-dir <path> — realoque o diretório de logs do serviço instalado. Requer o cliente de Relay 26.4.2 ou posterior.
• --log-retention-days <days> alterar a retenção de log rotacionado. Mínimo de 7; passe -1 para deixar inalterado. Requer o cliente de Relay 26.4.2 ou posterior.
• --heartbeat-interval altere o intervalo de pulsação. Mínimo de 10; passe 0 para deixar inalterado.
• --reconnect-interval altere o intervalo de reconexão proativo. Mínimo de 1800 (30 minutos) quando definido. Passe 0 para desabilitar ou -1 para deixar inalterado.

Logs de relay

Mostre a saída de log para um cliente de Relay.

• -f, --follow — transmita novas linhas de log continuamente.
• -n, --lines <N> — número de linhas do final. Padrão 50.

Lista de relays

Mostra todos os clientes de Relay nesta máquina com status, versão, carimbos de data/hora de criação e atualização e nome do grupo quando disponível. Os nomes de grupos longos são truncados na saída da tabela.

• --json emita saída JSON para automação e script, incluindo nomes completos de grupos.

Descrição do relay (Cliente de Relay 26.4.2 ou posterior)

Mostre informações detalhadas para um cliente de Relay, incluindo ID e nome do grupo, ID do segredo, status, versão, modo de serviço e caminho executável, pulsação configurada e intervalos de reconexão, nível de log, caminhos locais e carimbos de data/hora.

• --json emita a saída JSON para automação e script.

Recarregar relay

Busque novamente a configuração de proxy do Test Cloud e aplique-a sem reiniciar. Use como fallback se um ponto de extremidade recém-adicionado retornar 404.

Parada do relay

Interrompa o serviço ao cliente do Relay. A configuração e as credenciais são preservadas — o cliente de Relay pode ser reiniciado mais tarde.

Exclusão do relay

Interrompa o serviço, cancele o registro do Test Cloud e remova todas as configurações e credenciais locais.

• -f, --force — remover localmente sem cancelamento de registro na nuvem. Use quando as credenciais forem ilegíveis ou os recursos do lado da nuvem já tiverem sido excluídos.

Pacote de suporte do relay [id]

Colete um arquivo redigido de configuração, logs e metadados do sistema para um tíquete de suporte da UiPath. Omita [id] para agrupar todos os clientes de Relay na máquina.As credenciais e chaves de criptografia nunca são incluídas. Consulte Solução de problemas de Relay para obter todos os detalhes.

Versão do relay

Visualize a versão do cliente de Relay, a data de compilação e o hash de confirmação do git.

Segurança de antivírus e ponto de extremidade

If your organization runs endpoint protection software, add exclusions for the relay binary and its data directory to prevent the Relay client from being blocked or quarantined. For Relay client 26.4.2 configurations that connect through cloud.uipath.com, allow cloud.uipath.com:443.

For Relay client versions earlier than 26.4.2, configure TLS-inspecting proxies, DLP appliances, and IDS/IPS systems to bypass inspection for <region>-relay.uipath.com:443.

Destino	Porta	Protocol	Ação
cloud.uipath.com	443	Https	Permitir
<region>-relay.uipath.com	443	TLS	Permitir + ignorar inspeção TLS para versões do cliente de Relay anteriores a 26.4.2