将中继客户端部署为容器

使用 Podman、Docker 或 Kubernetes 将 UiPath Relay 客户端部署为容器映像，以在容器化环境中建立安全的出站隧道。

将 Relay 客户端作为容器映像运行，以建立从容器化环境中到 Test Cloud 的安全出站隧道。开始之前，请先配置 Relay 组，并准备好来自 Relay UI 的客户端配置 string。

先决条件

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

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

重要提示：

对于受支持的基于 TCP 的连接（例如 SAP BAPI），您需要部署中继客户端与第二个容器，即内部部署执行程序。如果您需要，请跳过步骤 3，转而遵循SAP BAPI 和其他基于 TCP 的连接。该部分涵盖 Docker 和 Podman。

步骤 1：获取配置

1. 打开 Relay 用户界面仪表板。
2. 创建或复制您的 Relay 配置。
3. 在主机上为配置文件创建一个目录。任何目录均可；此页面以 /opt/uipath/relay/config 为例。在 Windows 上，使用 Windows 路径，例如 C:\uipath\relay\config。
4. 将用户界面中的 base64 编码配置字符串另存为 relay.config.b64enc。部署命令将此目录作为 /relay-config 装载到容器中；将示例路径替换为您的路径。

步骤 2：配置环境变量

在步骤 3 中，使用 Podman 或 Docker 将这些变量作为 -e 标志传递，或在 Kubernetes 清单中作为 env: 条目传递。

自定义 CA 证书

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

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

在建立任何 TLS 连接之前，Relay 客户端会将自定义 CA 与系统证书捆绑包合并。

代理

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

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

步骤 3：部署

将 <RELAY_ID> 替换为 Relay 用户界面中的实际 ID。为了实现 Docker 或 Podman 的高可用性，请在单独的节点上运行两个名称不同的容器，例如 relay1-<RELAY_ID> 在主机 1 上运行，relay2-<RELAY_ID> 在主机 2 上运行。在 Kubernetes 中，使用两个具有 Pod 反关联的副本，如下面的清单所示。成功启动日志 All prerequisite checks passed。

下面的 Podman 和 Docker 命令通过 -it --rm 在前台运行，因此您可以看到容器在首次启动和停止时被移除。对于长时间运行的部署，请将 -it --rm 替换为 -d。

Podman

快速入门:

podman run -it --name relay1-<RELAY_ID> --hostname relay1-<RELAY_ID> --rm \
  --read-only --read-only-tmpfs \
  -v /opt/uipath/relay/config:/relay-config:ro,z \
  registry.uipath.com/relay-client:<tag> \
  start --config-file /relay-config/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 /opt/uipath/relay/config:/relay-config:ro,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/relay.config.b64enc --accept-license-agreement

Docker

快速入门:

docker run -it --name relay1-<RELAY_ID> --hostname relay1-<RELAY_ID> --rm \
  --read-only --tmpfs /tmp \
  -v /opt/uipath/relay/config:/relay-config:ro \
  registry.uipath.com/relay-client:<tag> \
  start --config-file /relay-config/relay.config.b64enc --accept-license-agreement

使用自定义 CA 证书：

docker run -it --name relay1-<RELAY_ID> --hostname relay1-<RELAY_ID> --rm \
  --read-only --tmpfs /tmp \
  -v /opt/uipath/relay/config:/relay-config:ro \
  -v /tls/custom-ca.crt:/custom-ca.crt:ro \
  -v /tmp/writable:/writable \
  -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/relay.config.b64enc --accept-license-agreement

Kubernetes

创建密码：

# Configuration secret
kubectl create secret generic relay-config \
  --from-file=relay.conf=/opt/uipath/relay/config/relay.config.b64enc

# 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-<RELAY_ID>-0、relay-client-<RELAY_ID>-1 等），Relay 服务使用这些主机名来识别和验证客户端。

清单文件装载 custom-ca 密码，并设置两个 RELAY_* 变量。如果您不使用自定义 CA，请删除这两个变量、卷装载 custom-ca 和 custom-ca 卷。就绪探测器使用运行状况端点，这需要中继客户端 26.4.2 或更高版本。

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>

启动命令选项

这些内容适用于每个运行时。

选项	描述	示例
--config	内联 Base64 配置字符串	--config "base64string..."
--config-file	配置文件的路径	--config-file /relay-config/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
--enable-onprem-executor	连接到默认端口 18080 上的内部部署执行程序容器。请参阅SAP BAPI 和其他基于 TCP 的连接	--enable-onprem-executor
--onprem-executor-listen-port	此端口上连接到内部部署执行程序容器，该端口必须与容器的 SERVER_PORT 匹配。任一标志都会启用执行程序	--onprem-executor-listen-port 18080

SAP BAPI 和其他基于 TCP 的连接

重要提示：

需要 26.4.3 或更高版本的中继客户端。本节介绍 Docker 和 Podman。

对于受支持的基于 TCP 的连接（例如 SAP BAPI），您可以在同一台主机上运行两个容器：

• 中继客户端容器：打开与 UiPath 的安全出站连接。
• 本地执行程序容器：连接到本地部署系统并处理基于 TCP 的连接。

执行程序容器共享 Relay 客户端的网络，因此 Relay 客户端可以访问 localhost 上的执行程序。

先决条件

• 内部部署执行程序容器映像：registry.uipath.com/relay-onprem-executor:<tag>。使用与中继客户端映像相同的 <tag>。支持的最低版本为 26.4.3。
• SAP JCo 3 库 sapjco3.jar、sapidoc3.jar 和 libsapjco3.so。请从 SAP 支持门户下载它们，该门户需要 SAP 帐户； UiPath 未发行它们。
  • sapjco3.jar和libsapjco3.so包含在适用于Linux on x86_64 的SAP Java Connector 3.1包中。执行程序映像为 linux/amd64，因此不会加载适用于任何其他平台的包。
  • sapidoc3.jar位于单独的SAP Java IDoc ClassLibrary 3.1包中。
• Relay 主机可以解析并访问 SAP 系统的主机名和端口。

暂存 JCo 库

库可以位于主机上的任何目录中。本页使用 /opt/uipath/relay/executor-deps 作为示例；重要的是部署命令会在执行程序容器内的 /opt/uipath/onprem-runtime/dep-libs 处装载您的目录。这些命令使用 sudo，因为 /opt 需要在 Linux 上的根用户；对于您拥有的目录，请省略它。

1. 创建目录：

   sudo mkdir -p /opt/uipath/relay/executor-deps
   

2. 将这三个文件复制到其中。将它们直接放置在目录中，而不是子目录中：

   sudo cp sapjco3.jar sapidoc3.jar libsapjco3.so /opt/uipath/relay/executor-deps/
   

3. 确认原生库是为 x86-64 构建的：

   file /opt/uipath/relay/executor-deps/libsapjco3.so
   # Expect: ELF 64-bit LSB shared object, x86-64
   

   如果输出显示 ARM aarch64 或其他架构，请改为下载 Linux on x86_64 包。在 file 不可用的 Windows 上，请检查您提取的包：正确的包名为 sapjco3-linuxx86_64-<version>。

部署两个容器

按此顺序运行命令：先运行 Relay 客户端，然后运行执行程序。执行程序加入中继客户端的网络，因此执行程序启动时中继客户端必须正在运行。

警告：

如果重新启动或重新创建中继客户端，执行程序将失去网络，并且不会自行恢复。之后重新启动执行程序，如重新启动和升级中所述。

运行命令之前：

• 将/opt/uipath/relay/config和/opt/uipath/relay/executor-deps替换为您在步骤 1 中选择的主机目录并暂存 JCo 库。保留容器端路径，如下所示。
• 如果您已在第 3 步中启动了中继客户端，请将其停止并删除。无法更改正在运行的容器的参数。
• 如果使用自定义 CA 或代理，请将步骤 2 中的变量添加到中继客户端命令。对于自定义 CA，请将步骤 3 中的两个变量添加到中继客户端命令。中继客户端是连接到 UiPath 的容器。
• 不要使用 -p 发布执行程序端口。只有中继客户端即可访问该资源。

使用以下任一标志在中继客户端上启用执行程序：

标记	效果
--enable-onprem-executor	通过默认端口连接到执行程序 18080
--onprem-executor-listen-port <port>	连接到 <port> 上的执行程序。必须与执行程序容器的 SERVER_PORT 匹配

其他执行程序标志（--onprem-executor-java-home 和 --onprem-executor-dep-dir）在容器中无效：执行程序映像包含自己的 Java Runtime，并从 /opt/uipath/onprem-runtime/dep-libs 读取其库。

Podman

# 1. Relay client. It owns the network namespace that the executor joins.
podman run -d --name relay1-<RELAY_ID> --hostname relay1-<RELAY_ID> \
  --read-only --read-only-tmpfs \
  -v /opt/uipath/relay/config:/relay-config:ro,z \
  registry.uipath.com/relay-client:<tag> \
  start --config-file /relay-config/relay.config.b64enc \
  --accept-license-agreement \
  --onprem-executor-listen-port 18080

# 2. On-prem executor. SERVER_ADDRESS=127.0.0.1 restricts it to loopback,
#    which is where the Relay client reaches it. Without it, the executor
#    image listens on all interfaces of the shared namespace.
podman run -d --name relay-executor-<RELAY_ID> \
  --network container:relay1-<RELAY_ID> \
  -e SERVER_ADDRESS=127.0.0.1 \
  -e SERVER_PORT=18080 \
  -v /opt/uipath/relay/executor-deps:/opt/uipath/onprem-runtime/dep-libs:ro,z \
  registry.uipath.com/relay-onprem-executor:<tag>

或者，也可以使用 --pod 创建一个 Podman Podman，并在其中运行两个容器。Pod 的基础架构容器拥有网络命名空间，因此任一容器都可以自行重新启动。

Docker

# 1. Relay client. It owns the network namespace that the executor joins.
docker run -d --name relay1-<RELAY_ID> --hostname relay1-<RELAY_ID> \
  --read-only --tmpfs /tmp \
  -v /opt/uipath/relay/config:/relay-config:ro \
  registry.uipath.com/relay-client:<tag> \
  start --config-file /relay-config/relay.config.b64enc \
  --accept-license-agreement \
  --onprem-executor-listen-port 18080

# 2. On-prem executor. SERVER_ADDRESS=127.0.0.1 restricts it to loopback,
#    which is where the Relay client reaches it. Without it, the executor
#    image listens on all interfaces of the shared namespace.
docker run -d --name relay-executor-<RELAY_ID> \
  --network container:relay1-<RELAY_ID> \
  -e SERVER_ADDRESS=127.0.0.1 \
  -e SERVER_PORT=18080 \
  -v /opt/uipath/relay/executor-deps:/opt/uipath/onprem-runtime/dep-libs:ro \
  registry.uipath.com/relay-onprem-executor:<tag>

验证

读取包含适用于您运行时的命令的日志：

运行时	中继客户端日志	执行程序日志
Podman	podman logs relay1-<RELAY_ID>	podman logs relay-executor-<RELAY_ID>
Docker	docker logs relay1-<RELAY_ID>	docker logs relay-executor-<RELAY_ID>

1. 在中继客户端日志中，确认先决条件行 On-prem executor checks: OK。
2. 在相同的日志中，找到名为 relay1-<RELAY_ID>-system-onprem-executor-<id> 的执行程序端点，并确认其到达 health check success。
3. 在执行程序日志中，确认 Started OnPremRuntimeApplication。
4. 从使用此端点的连接器运行测试调用，以确认完整路径有效。

备注：

当执行程序容器仍在启动时，第 2 步可能会首先显示 health check failed: dial tcp [::1]:18080: connect: connection refused。这是预期结果，会在大约 10 秒后进行下一次检查时清除，而无需重新启动中继客户端。

有关问题，请先参阅此页面的故障排除，然后参阅本地执行程序问题。

重新启动和升级

您可以自行重新启动或升级执行程序。如果您重新启动或重新创建中继客户端，之后也请重新启动或重新创建执行程序：执行程序在中继客户端的网络中运行，重新启动或重新创建中继客户端会替换该网络，因此现有的执行程序容器无法自行恢复。升级时，对两个映像使用相同的 <tag>。对于 Podman，将 docker 替换为 podman。

任务	待执行操作
重新启动执行程序	docker restart relay-executor-<RELAY_ID>。 Relay 客户端继续运行
升级执行程序	docker rm -f relay-executor-<RELAY_ID>，然后使用新的名称再次运行执行程序命令 <tag>
重新启动中继客户端	docker restart relay1-<RELAY_ID>，然后 docker restart relay-executor-<RELAY_ID>
升级中继客户端	删除两个容器，然后使用新的 <tag>（首先是中继客户端）再次运行这两个命令。重新创建的中继客户端是一个新容器，因此执行程序也必须重新创建

运营

配置详细信息

配置文件必须包含 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 及更高版本。

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

访问日志

# Podman
podman logs -f relay1-<RELAY_ID>

# Docker
docker logs -f relay1-<RELAY_ID>

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

# Kubernetes (previous run, if the container restarted)
kubectl logs relay-client-<RELAY_ID>-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 验证证书格式并检查文件权限
执行程序端点永远无法到达 health check success	执行程序容器不共享中继客户端的网络命名空间，或者 --onprem-executor-listen-port 与执行程序的 SERVER_PORT 不匹配	使用 --network container:relay1-<RELAY_ID> 启动执行程序，并将两个端口设置为相同的值
重新启动一个容器后，另一个容器将失去所有网络访问权限，并且无法恢复	使用 --network container:，当所属容器重新启动时，加入容器的网络将被破坏。Podman Pod 不受影响，因为其基础架构容器拥有命名空间	先启动中继客户端，使其拥有命名空间。在重新启动任何 Relay 客户端后，执行程序容器也将重新启动
执行程序找不到 JCo 库	文件位于已装载卷的子目录中，或者该卷装载到错误的路径中	将直接包含文件的目录（不带子目录）装载到 /opt/uipath/onprem-runtime/dep-libs

对于并非特定于容器的执行程序问题，例如为错误的架构构建的 JCo 原生库，请参阅内部部署执行程序问题。