部署本地连接器主机

了解为您的 Tulip 集成部署、配置和维护本地连接器主机（OPCH）的技术步骤。

本文是面向负责 OPCH 物理部署和生命周期管理的相关人员的技术参考指南。连接器主机是一项服务，用于促进从

外部 Web 服务、数据库和 OPC UA 服务器建立连接的服务。所有 Tulip 实例默认都配备一个云连接器主机。

在确定本地连接器主机是否适合当前架构时，需要考虑以下几点。

先决条件

在继续之前，请确保您已掌握 Tulip 连接器主机的基础知识：*连接器主机* 本地连接器主机

网络

部署本地连接器主机的最常见理由在于，它在连接本地网络内托管的系统时具有显著优势。采用本地部署方案时，Tulip 与外部系统之间的所有连接均始于您的本地网络内部。来自您网络的所有连接均通过安全的 WebSocket 向外连接至 Tulip。

这与云连接器主机形成对比，后者需要允许对服务的入站访问。通常需要 IT 部门做出决策，允许从Tulip 云端到该服务的入站安全 WebSocket 连接，这通常需要通过广域网路由器/防火墙上的端口转发规则来实现。

部署本地连接器主机

技术标准

当决定部署本地解决方案时，Tulip 建议采用基于分布式Docker镜像的自助服务方式。实现此方案最简单的方法是使用搭载 Linux 发行版的虚拟机。

Tulip 还建议每台虚拟机仅托管一个本地连接器主机，以避免站点出现单点故障。

虚拟机要求：

• 内存 - 4 GB
• 存储空间 - 8-16 GB
• CPU - 2 核
• Docker 版本 - 20.10 及以上

关于网络要求，本地连接器主机需满足以下条件：

• 一个 IP 地址
• 可解析至
• 通过 443 端口对外访问 Tulip（IP 地址列表见此处）
• 可访问此处的Docker 仓库
• 通过指定端口对外访问所有相关外部系统

请在此处查看完整的网络要求列表

部署

以下部分概述了如何在各种环境中部署本地连接器主机。AWS 和 Azure 均提供可运行该 Docker 镜像的容器服务。

AWS

请使用 Web 界面并参考此操作指南：https://aws.amazon.com/getting-started/hands-on/deploy-docker-containers/

Azure（Bash）：LTS16+ OPCH

az container create `-g <AZURE 中的资源组名称> `--name <容器名称> `--cpu 2 `--memory 3 `--restart-policy Always `--public.ecr.aws/tulip/connector-host：<TAG>--os-type Linux `-e TULIP_UUID='<UUID>' `TULIP_FACTORY='https://<您的站点>.tulip.co' `TULIP_MACHINE_SECRET='<密钥>' `TULIP_DEVICE_TYPE='onprem' `TULIP_LOGGING_TO_TULIP=true`TULIP_TELEMETRY_TO_TULIP=true`TULIP_CONNECTORS_HTTP_PROXY='' `TULIP_CONNECTORS_HTTPS_PROXY=''

Azure（Bash）：LTS16之前的OPCH

az container create `-g <AZURE 中的资源组名称> `--name <容器名称> `--cpu 2 `--memory 3 `--restart-policy Always `--public.ecr.aws/tulip/connector-host：<TAG> `--os-type Linux `-e TULIP_UUID='<UUID>' `TULIP_FACTORY='https://<您的站点>.tulip.co' `TULIP_MACHINE_SECRET='<密钥>' `TULIP_DEVICE_TYPE='onprem' `CONNECTORS_HTTP_PROXY='' `CONNECTORS_HTTPS_PROXY=''

Linux 虚拟机：LTS16+ OPCH

docker run -d \ --name tulip-connector-host \ -e TULIP_FACTORY='https://<FACTORY>.tulip.co' \ -e TULIP_UUID='<UUID>' \ -e TULIP_MACHINE_SECRET='<SECRET>' \ -e TULIP_DEVICE_TYPE='onprem' \ -e TULIP_LOGGING_TO_TULIP=true \ -e TULIP_TELEMETRY_TO_TULIP=true \ -e TULIP_CONNECTORS_HTTP_PROXY='' \ -e TULIP_CONNECTORS_HTTPS_PROXY='' \ --restart=always \ --net=host \ public.ecr.aws/tulip/connector-host:<TAG>

Linux 虚拟机：LTS16 之前的 OPCH

 --name tulip-connector-host \  
 -e TULIP\_FACTORY='https://.tulip.co' \  
 -e TULIP\_UUID='' \  
 -e TULIP\_MACHINE\_SECRET='' \  
 -e TULIP\_DEVICE\_TYPE='onprem' \  
 -e CONNECTORS\_HTTP\_PROXY='' \  
 -e CONNECTORS\_HTTPS\_PROXY='' \  
 -e EXIT\_ON\_DISCONNECT=true \ --restart=always \  
 --net=host \  
 --mount type=volume,source=tuliplog,target=/log \  
 public.ecr.aws/tulip/connector-host：

Windows (PowerShell)：LTS16+ OPCH

docker run -d --name tulip-connector-host -e TULIP_FACTORY='https://<FACTORY>.tulip.co' -e TULIP_UUID='<UUID>' -e TULIP_MACHINE_SECRET='<SECRET>' -e TULIP_DEVICE_TYPE='onprem' -e TULIP_LOGGING_TO_TULIP=true -e TULIP_TELEMETRY_TO_TULIP=true -e TULIP_CONNECTORS_HTTP_PROXY='' -e TULIP_CONNECTORS_HTTPS_PROXY='' --restart=always --net=host public.ecr.aws/tulip/connector-host:<TAG>

Windows（PowerShell）：LTS16 之前的 OPCH

docker run -d --name tulip-connector-host -e TULIP_FACTORY='https://<FACTORY>.tulip.co' -e TULIP_UUID='<UUID>' -e TULIP_MACHINE_SECRET='<SECRET>' -e TULIP_DEVICE_TYPE='onprem' -e HTTP_PROXY='' -e HTTPS_PROXY='' -e EXIT_ON_DISCONNECT=true --restart=always --net=host --mount type=volume,source=tuliplog,target=/log public.ecr.aws/tulip/connector-host:<TAG>

证书错误排查

如果 OPCH 因“证书链中存在自签名证书”错误而无法启动，根本原因可能是企业代理/防火墙使用了自定义证书，从而阻止了与 Tulip Cloud 的安全连接。

症状：- OPCH 显示“Never seen”状态- 启动过程中进程终止- 日志中出现 SSL 证书链错误

要解决此问题，可在 OPCH 启动时通过以下环境变量引用额外的证书颁发机构（CA）。请注意，该文件必须位于 Docker 容器中。

针对 LTS16 之前的 OPCH：-e CONNECTORS_EXTRA_TRUSTED_CAS_FROM_FILES='["/etc/tulipCa/ca.pem"]'

针对 LTS16 及以上版本的 OPCH：-e TULIP_CONNECTORS_EXTRA_TRUSTED_CAS_FROM_FILES='["/etc/tulipCa/ca.pem"]'

升级本地连接器主机

:::(警告) (您的 Edge IO 可能也需要升级)
OPCH 可在Edge IO 设备上运行。如果您的设备未启用自动升级，则必须手动进行升级。

如果您已完成所有 OPCH 升级后此警告横幅仍显示，请确保您的Edge IO 也已更新。
:::

Tulip 会根据我们的长期支持 (LTS) 发布计划，发布针对本地连接器主机的更新。要升级该服务，请按照以下说明操作：

OPCH 的升级过程会导致服务中断，因为在此期间 Pod 会被停止并重新创建。

1. 获取最新版本的本地连接器主机 Docker 镜像。

   docker pull public.ecr.aws/tulip/connector-host:<TAG>2. 运行以下命令获取 Docker 容器 ID。

   docker ps3. 如果您拥有TULIP_FACTORY、TULIP_UUID 和TULIP_MACHINE_SECRET 的访问权限，请跳至第 4 步。如果没有，请运行以下命令，并将该命令的输出保存在安全位置。

   docker exec <容器 ID> env4. 停止现有的 Docker 容器。

   docker stop <容器 ID>5. 删除现有的 Docker 容器。

   docker rm <容器 ID>6. 使用已保存的凭据集运行标准的Docker run命令。

对于 LTS16+ OPCH： docker run -d \ --name tulip-connector-host \ -e TULIP_FACTORY='https://<FACTORY>.tulip.co' \ -e TULIP_UUID='<UUID>' \ -e TULIP_MACHINE_SECRET='<SECRET>' \ -e TULIP_DEVICE_TYPE='onprem' \ -e TULIP_LOGGING_TO_TULIP=true \ -e TULIP_TELEMETRY_TO_TULIP=true \ -e TULIP_CONNECTORS_HTTP_PROXY='' \ -e TULIP_CONNECTORS_HTTPS_PROXY='' \ --restart=always \ --net=host \ public.ecr.aws/tulip/connector-host：<TAG>对于 LTS16 之前的 OPCH： docker run -d \ --name tulip-connector-host \ -e TULIP_FACTORY='https://<FACTORY>.tulip.co' \ -e TULIP_UUID='<UUID>' \ -e TULIP_MACHINE_SECRET='<SECRET>' \ -e TULIP_DEVICE_TYPE='onprem' \ -e CONNECTORS_HTTP_PROXY='' \ -e CONNECTORS_HTTPS_PROXY='' \ -e EXIT_ON_DISCONNECT=true \ --restart=always \ --net=host \ --mount type=volume,source=tuliplog,target=/log \ public.ecr.aws/tulip/connector-host:<TAG>

1. 确认新的 Docker 容器已处于活动状态。

   docker ps

使用连接器环境测试升级

每个连接器有三个不同的环境（生产、预生产和开发），每个环境都可以拥有自己的连接器主机，且版本可能不同。根据应用程序的状态（开发版本、待审批、已发布），可以使用不同的环境。进行连接器主机验证的预期流程应为：1. 升级开发环境的 OPCH；2. 升级验证连接器主机（此处预生产环境指向开发环境） 1. 在“连接器”页面或应用程序的开发模式下测试连接器；3. 验证测试完成后，升级生产环境的连接器主机

有关更多信息，请参阅“连接器环境”。

或者，您也可以先在开发实例上升级 OPCH，然后放心地升级生产环境。

将日志转发至外部日志管理工具

您可以将本地连接器主机日志转发至第三方工具，以便进行集中监控和故障排除。OPCH 通过环境变量支持 Datadog、Grafana Loki 和 Splunk。 可用的日志类型包括与 OPCH 运行状态相关的日志（尤其是与工厂的连接情况）、连接器调用执行日志以及订阅日志。作为 OPCH 启动流程的一部分，用户可以配置外部日志工具，指定日志的转发目标。如果添加了多个服务的凭据，日志将发送至所有服务

1. 选择目标
2. Datadog：全局端点；仅需 API 密钥。
3. Grafana Loki：客户自托管的 Loki；URL 可包含基本身份验证。
4. Splunk (HEC)：多实例；需要同时提供 URL 和令牌。
5. 添加环境变量：将以下变量添加到“连接器主机”环境中。仅使用与所选目标对应的变量。

Datadog
-TULIP_LOGGING_DATADOG_API_KEY=<您的_Datadog_API_密钥>

Grafana Loki
-TULIP_LOGGING_LOKI_URL=https://<用户名>:<密码>@loki.your-domain.com/loki/api/v1/push
（支持通过在 URL 中嵌入user:password进行基本身份验证——可选。）

Splunk (HEC)
-TULIP_LOGGING_SPLUNK_URL=https://splunk.your-domain.com:8088/services/collector
-TULIP_LOGGING_SPLUNK_TOKEN=<您的 Splunk HEC 令牌>

1. 重启连接器主机

重启服务以使新的环境变量生效。

1. 验证数据传输

生成活动（例如，运行连接器函数），并确认日志已出现在目标位置：

• Datadog：检查最近的日志中是否包含您的主机/服务名称。
• Loki：在 Grafana Explore 中通过主机标签或已知消息子字符串进行查询。
• Splunk：搜索来自您主机的近期事件（例如：index=<您的索引> source="tulip-connector-host"）。
• 更改或禁用日志记录
• 若要切换目标位置，请将变量更新为新提供商（并删除旧的）。
• 若要禁用，请删除日志记录变量并重启服务。

补充信息

基于 Grafana Alloy 导出器的实现：

Datadog 导出器：https://grafana.com/docs/alloy/next/reference/components/otelcol/otelcol.exporter.datadog/

Splunk HEC 导出器： https://grafana.com/docs/alloy/next/reference/components/otelcol/otelcol.exporter.splunkhec/

入站和出站调用负载

本节说明 OPCH 向 Tulip Cloud 发送的 HTTP 请求数量。这些请求可分为固定速率请求（始终运行）和可变速率请求（取决于您的配置和活动情况）。

固定速率请求

此类请求以稳定且可预测的速率发生：

可变速率的请求

这些请求取决于您的配置和活动情况。
发生的更改或事件越多，请求率就越高。

计算示例

假设以下配置：-1 个机器数据源- 500 个机器属性，每个属性以1Hz（每秒一次）的频率报告数据

最坏情况下的请求速率：`速率（最坏情况）= (6 + 1 + 20) + 40 + 60 + 240 = 367 次请求/分钟

其他参考资料

为 Docker 启用日志轮换

对于未使用 Docker 日志轮换功能的现有本地部署Connector Hosts ，请按照此处记录的说明操作，以确保磁盘空间得到妥善管理。

检查 OPCH 运行状态

若要将 OPCH 与基于 Azure 或 Kubernetes 的服务编排器集成，可使用以下配置：

对于 LTS16 及以上版本的 OPCH：

若要将 OPCH 与基于 Azure 或 Kubernetes 的服务调度器集成，可使用以下配置：健康检查端点会随机分配到某个端口，并通过根路径/health-check 对外暴露。 您也可以通过将TULIP_HEALTH_HTTP_PORT设置为指定端口来覆盖分配的端口。例如：TULIP_HEALTH_HTTP_PORT = 80。成功的响应将返回 HTTP 状态码204，表明 OPCH 服务状态正常且正在运行。

对于 LTS16 之前的 OPCH：

若要将 OPCH 与基于 Azure 或 Kubernetes 的服务调度器集成，可使用以下配置：需通过将环境变量CONNECTORS_HEALTHZ_SERVER_ENABLED设置为true 来启用健康检查端点。该端点位于9223端口，并在根路径/ 下提供访问。您也可以通过将CONNECTORS_PORT设置为指定端口来覆盖默认端口9223。例如：CONNECTORS_PORT = 80

成功响应将返回 HTTP 状态码200（OK），表明 OPCH 服务状态正常且正在运行。
此外，还可以通过将CONNECTORS_PORT设置为指定端口来覆盖默认端口9223。例如：CONNECTORS_PORT = 80

成功响应将返回 HTTP 状态码200（OK），表明 OPCH 服务状态正常且正在运行。