将中继客户端部署为容器

将 Relay 客户端作为容器映像运行，建立从容器化环境到 Test Cloud 的安全出站隧道。在开始之前，请从 Relay 用户界面配置一个 Relay 组，并准备好客户端配置字符串。

先决条件

• 容器运行时：Podman、Docker 或 Kubernetes 集群。
• 中继客户端容器映像： registry.uipath.com/relay-client:<tag> 。将<tag>替换为UiPath Customer Portal下载页面中的中继版本。支持的最低版本为26.4.1 。
• 从 Relay 用户界面生成的 base64 编码配置文件。
• 接受许可协议：将LICENSE_AGREEMENT=accept设置为环境变量，或将--accept-license-agreement附加到启动命令。
• （可选）自定义 CA 证书（如果您的组织使用企业 PKI）。

有关硬件要求和特定于版本的网络先决条件，请参阅部署中继客户端。

步骤 1：获取配置

1. 打开 Relay 用户界面仪表板。
2. 创建或复制您的 Relay 配置。
3. 保存用户界面提供的 Base64 编码配置字符串。

步骤 2：配置环境变量

自定义 CA 证书

如果您的组织使用公司 CA 或自签名 CA，请在启动容器之前一起设置以下变量：

变量	用途	必填
RELAY_CUSTOM_CA_PATH	自定义 CA 证书的路径	否
RELAY_CA_BUNDLE_PATH	写入合并的 CA 捆绑包的路径	是，如果使用自定义 CA

在建立任何 TLS 连接之前，Relay 客户端会将自定义 CA 与系统证书捆绑包合并。这两个变量必须同时设置。

代理

要通过代理路由出站流量：

变量	用途	必填
HTTP_PROXY 与 HTTPS_PROXY	代理 URL	否
NO_PROXY	绕过代理的逗号分隔主机名、域名或 IP 地址	否

步骤 3：部署

Podman

为了获得高可用性，请在单独的节点上运行两个名称不同的容器。将<RELAY_ID>替换为 Relay 用户界面中的实际 ID，例如，在主机 1 上运行relay1-<RELAY_ID> ，在主机 2 上运行relay2-<RELAY_ID> 。

快速入门:

# Create a config file with the base64-encoded content from the Relay UI
echo "YOUR_BASE64_CONFIG_HERE" > /tmp/relay_config

# Run the container
podman run -it --name relay1-<RELAY_ID> --hostname relay1-<RELAY_ID> --rm \
  --read-only --read-only-tmpfs \
  -v /tmp/relay_config:/relay.config.b64enc:z \
  -e LICENSE_AGREEMENT=accept \
  registry.uipath.com/relay-client:<tag> \
  start --config-file /relay.config.b64enc --accept-license-agreement

使用自定义 CA 证书：

podman run -it --name relay1-<RELAY_ID> --hostname relay1-<RELAY_ID> --rm \
  --read-only --read-only-tmpfs \
  -v /tmp/relay_config:/relay.config.b64enc:z \
  -v /tls/custom-ca.crt:/custom-ca.crt:z \
  -v /tmp/writable:/writable:z \
  -e RELAY_CUSTOM_CA_PATH=/custom-ca.crt \
  -e RELAY_CA_BUNDLE_PATH=/writable/merged-ca.crt \
  registry.uipath.com/relay-client:<tag> \
  start --config-file /relay.config.b64enc --accept-license-agreement

“启动”命令选项：

选项	描述	示例
--config	内联 Base64 配置字符串	--config "base64string..."
--config-file	配置文件的路径	--config-file /relay.config.b64enc
--log-level	日志记录详细信息： trace 、 debug 、 info 、 warn或error	--log-level debug
--heartbeat-interval	心跳间隔，以秒为单位 (最小值: 10)	--heartbeat-interval 10
--reconnect-interval	重新连接间隔 (以秒为单位) (最小值: 1800)	--reconnect-interval 1800
--health-addr	/healthz端点的绑定地址。默认为0.0.0.0:9090 ；使用空值以禁用该功能	--health-addr=0.0.0.0:9090

Kubernetes

创建密码：

# Configuration secret
kubectl create secret generic relay-config \
  --from-file=relay.conf=/tmp/relay_config

# Custom CA certificate secret (optional)
kubectl create secret generic custom-ca \
  --from-file=custom-ca.crt=./custom-ca.crt

# Headless service for the StatefulSet
kubectl create service clusterip relay-client-<RELAY_ID> --clusterip="None"

部署有状态副本集：

在强制执行主机名限制时，使用状态副本集。状态集提供稳定、可预测的主机名（ relay-client-0 、 relay-client-1等），中继服务使用这些名称来识别和验证客户端。

apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: relay-client-<RELAY_ID>
spec:
  serviceName: relay-client-<RELAY_ID>
  replicas: 2
  selector:
    matchLabels:
      app: relay-client-<RELAY_ID>
  template:
    metadata:
      labels:
        app: relay-client-<RELAY_ID>
    spec:
      affinity:
        podAntiAffinity:
          requiredDuringSchedulingIgnoredDuringExecution:
          - labelSelector:
              matchExpressions:
              - key: app
                operator: In
                values:
                - relay-client-<RELAY_ID>
            topologyKey: "kubernetes.io/hostname"
      containers:
      - name: relay
        image: registry.uipath.com/relay-client:<tag>
        args:
        - start
        - --config-file=/config/relay.conf
        - --accept-license-agreement
        - --log-level=info
        - --heartbeat-interval=30
        env:
        - name: RELAY_CUSTOM_CA_PATH
          value: "/tls/custom-ca.crt"
        - name: RELAY_CA_BUNDLE_PATH
          value: "/writable/merged-ca.crt"
        imagePullPolicy: IfNotPresent
        securityContext:
          allowPrivilegeEscalation: false
          capabilities:
            drop:
            - ALL
          privileged: false
          readOnlyRootFilesystem: true
          runAsGroup: 1001
          runAsNonRoot: true
          runAsUser: 1001
        readinessProbe:
          httpGet:
            path: /healthz
            port: 9090
          initialDelaySeconds: 5
          timeoutSeconds: 1
          periodSeconds: 3
          successThreshold: 1
          failureThreshold: 2
        resources:
          requests:
            cpu: 50m
            memory: 100Mi
        volumeMounts:
        - name: relay-config
          mountPath: /config/relay.conf
          subPath: relay.conf
          readOnly: true
        - mountPath: /writable
          name: writable
        - name: custom-ca
          mountPath: /tls/custom-ca.crt
          subPath: custom-ca.crt
          readOnly: true
      volumes:
      - name: relay-config
        secret:
          secretName: relay-config
      - name: writable
        emptyDir: {}
      - name: custom-ca
        secret:
          secretName: custom-ca
      restartPolicy: Always
      terminationGracePeriodSeconds: 30

验证部署：

kubectl get statefulset relay-client-<RELAY_ID>

运营

Configuration details

配置文件必须包含 Relay 用户界面生成的 base64 编码的 JSON 字符串。启动时，Relay 客户端会读取配置，进行解码、验证，然后连接到指定的Relay 服务端点。

• 首次运行：配置加密存储在数据目录中。
• 后续运行：会自动解密和使用加密的配置。
• 配置文件更改：需要重新启动容器才能生效。

心跳间隔

心跳使空闲的 TCP 连接保持活动状态。如果您的防火墙、代理或网络地址转换 (NAT) 在 30 秒内丢弃空闲连接，请缩短时间间隔：

--heartbeat-interval=30    # Default
--heartbeat-interval=10    # For aggressive firewall or NAT environments

重新连接间隔

主动重新连接会按固定计划重新建立连接。在代理或负载均衡器具有空闲连接超时的环境中使用此功能：

--reconnect-interval=0     # Disabled (default)
--reconnect-interval=1800  # Reconnect every 30 minutes (minimum)

运行状况端点

备注：

--health-addr选项适用于中继客户端26.4.2及更高版本。

默认情况下，容器映像在0.0.0.0:9090上启用 HTTP /healthz端点。使用--health-addr=<address>更改绑定地址，或使用--health-addr=禁用端点。示例清单中的 Kubernetes 就绪情况探测器使用此端点。

访问日志

# Podman
podman logs -f relay1

# Kubernetes (current run)
kubectl logs -f relay-client-0

# Kubernetes (previous run, if the container restarted)
kubectl logs relay-client-0 --previous

容器日志保留由容器运行时或 Kubernetes 集群日志记录策略控制，而不是由 Relay 客户端控制。

安全性

在容器清单中应用以下安全设置：

• readOnlyRootFilesystem: true — 防止修改容器文件系统。
• runAsNonRoot: true — 以非根用户身份运行流程。
• allowPrivilegeEscalation: false — 防止权限升级。
• capabilities.drop: [ALL] — 放弃所有 Linux 功能。
• privileged: false — 禁用特权模式。

将中继配置存储在 Kubernetes 密码中，并使用基于角色的访问控制 (RBAC) 来限制密码访问。不要将 Base64 配置嵌入到容器映像中，也不要将其作为明文环境变量传递。

故障排除

症状	原因	分辨率
license agreement not accepted 启动时	未设置许可证标志或变量	将--accept-license-agreement添加到启动命令中，或设置LICENSE_AGREEMENT=accept
未找到配置文件	卷装载路径或密码不正确	运行kubectl describe secret relay-config和kubectl describe pod <pod-name>以验证安装
无法连接到中继服务	网络或防火墙问题	使用kubectl logs <pod-name>检查 Pod 日志，并在“部署中继客户端”中验证所需的出站目标
自定义 CA 合并失败	未能同时设置 CA 环境变量	同时设置RELAY_CUSTOM_CA_PATH和RELAY_CA_BUNDLE_PATH 。
中继服务无法识别主机名	Pod 名称是随机的（独立 Pod，不是有状态集）	使用 StatefulSet，而非独立 Pod
x509 证书错误	CA 证书无效或无法访问	使用openssl x509 -in custom-ca.crt -text -noout验证证书格式并检查文件权限