TDengine PI Data Ingestion Prerequisites: Complete Pre-Deployment Checklist for taosX PI Connector
TDengine PI Data Ingestion Prerequisites: Complete Pre-Deployment Checklist for taosX PI Connector
📅 发布时间:2026/9/20 2:59:32👁 浏览次数:
TDengine PI Data Ingestion Prerequisites: Complete Pre-Deployment Checklist for taosX PI Connector【免费下载链接】tdengineTDengine is an open source, high-performance, cloud native time-series database optimized for Internet of Things (IoT), Connected Cars, Industrial IoT and DevOps.项目地址: https://gitcode.com/taosdata/tdengine本文是基于 TDengine 开源仓库中 PI Data Ingestion Prerequisites 文档 整理的技术指南涵盖从 OSIsoft/AVEVA PI System 向 TDengine 迁移数据之前必须确认的全部前置条件。你将掌握 PI Data Archive / PI AF Server 的端口与协议要求、Windows 集成认证机制、服务账号最小权限配置、PI AF SDK 软件依赖以及一份可以直接照做的上线前验证清单。这些前置检查是后续创建实时PI与回填PI backfill数据同步任务的第一步建议由 PI 管理员与网络管理员共同核对完成。为什么 PI 数据接入需要专门的前置检查TDengine 通过 taosX 数据接入框架中的 PI 连接器插件taosx-pi.exe读取 PI 系统中的实时与历史数据再写入 TDengine 集群。与普通数据库连接不同PI 系统有自己特有的接入约束PI 连接器依赖PI AF SDKPI AF Client而该 SDK仅支持 Windows 操作系统认证由Windows 操作系统Kerberos / NTLM 集成认证完成而不是 PI 系统内部的账号体系PI 系统的端口、防火墙策略、权限模型Mapping ACL 两层都需要在创建任务前确认就绪。因此官方前置检查文档 把所有需要验证的项分成网络连通性、认证与权限、软件依赖三大类并要求 PI 管理员与网络管理员在创建 PI 数据接入任务之前共同完成检查。PI 系统连接要求PI Data Archive 连接参数PI Data ArchivePI 数据归档服务器是 PI 系统的核心数据存储组件PI 连接器必须能够访问它才能读取 PI Point 数据。项目说明服务器地址PI Data Archive 服务器的主机名Hostname或 IP 地址默认端口5450PI Data Archive 标准端口协议PI SDK / PI AF SDK 专有协议PI AF Server 连接参数AF 模式当使用 AF 模式PI Data Archive AF Server即资产框架模式时还需要额外连接 PI AF Server项目说明AF Server 地址PI AF Server 的主机名AF 数据库名称要连接的 AF Database 名称默认端口5457PI AF Server 标准端口协议PI AF SDK 专有协议关于端口的说明上面列出的端口是 PI 系统的默认端口。PI 连接器taosx-pi.exe通过 PI AF SDK 与 PI 系统通信端口由 SDK 内部管理连接器中无需手动配置端口。但防火墙必须放行这些端口否则 SDK 连接会失败。如果你的 PI 系统使用了非标准端口请向 PI 管理员确认实际端口号。网络与防火墙要求运行 taosX或 taosX-Agent的主机必须能够访问 PI 系统的以下端口源目的端口协议说明PI 连接器taosX/taosX-Agent 主机PI Data Archive Server5450/TCPPI AF SDK 专有协议必需读取 PI Point 数据PI 连接器taosX/taosX-Agent 主机PI AF Server5457/TCPPI AF SDK 专有协议使用 AF 模式时必需taosX-AgenttaosXtaosX 配置的端口gRPC使用 taosX-Agent 代理模式时必需如果网络环境存在防火墙或网络隔离务必确保上述端口放行。关于 taosX-Agent 代理模式的完整网络拓扑OT 网络中的 PI 系统 Windows 主机上的 taosX-Agent通过跨网 gRPC 与 IT 网络/云端的 taosX 通信参见 PI Connector 部署架构。如何验证端口连通性在 taosX / taosX-Agent 主机上可以使用以下命令快速验证# Windows PowerShell Test-NetConnection -ComputerName PI_SERVER_HOST -Port 5450 Test-NetConnection -ComputerName AF_SERVER_HOST -Port 5457# Linux仅用于验证 taosX ↔ taosX-Agent 的连通性 nc -zv HOST PORT注意由于 PI AF SDK 仅支持 WindowsLinux 下的nc命令只能用来验证 taosX 与 taosX-Agent 之间的 gRPC 通道不能代替 Windows 上对 PI 5450/5457 端口的验证。认证与服务账号要求PI 连接器taosx-pi.exe作为 taosX 或 taosX-Agent 的子进程运行通过 PI AF SDK 连接 PI 系统。认证由 Windows 操作系统处理Kerberos 或 NTLM 集成认证——不依赖 PI 系统内部的账号/密码体系。认证模式连接配置中的 Username / Password / Domain 字段均为可选控制认证模式字段取值认证模式说明全部留空推荐Windows 集成认证连接器使用 taosX-Agent 服务账号的 Windows 身份访问 PIKerberos 或 NTLM填写 Username Password± Domain显式凭据使用指定的 Windows 账号访问 PI覆盖服务账号身份默认情况下无需填写 Username、Password 或 Domain。留空即使用 Windows 集成认证连接器以 taosX-Agent 服务账号的 Windows 身份访问 PI这是生产环境的推荐做法。详细的字段级说明与认证机制解析见 连接配置与认证。taosX-Agent 的默认运行身份taosX-Agent 默认以 WindowsLocal System账号运行在域环境中对应机器账号例如DOMAIN\machinename$。在域环境下这个机器账号身份就是连接器呈递给 PI 系统的身份因此 PI 侧需要为该身份配置映射Mapping与权限。生产环境建议将 taosX-Agent 配置为在专用的域服务账号下运行这样更便于在 PI 侧进行权限管理。taosX-Agent 的运行身份可以在 Windows 服务管理器中查看和修改服务 →taosx-agent→ 属性 → 登录Log On。PI Data Archive 权限运行连接器的服务账号在 PI Data Archive 上需要以下权限读取 PI Point 数据的权限通过 PI Identity 或 PI Mapping读取 PI Point 属性的权限PI 管理员应使用 PI System Management ToolsSMT创建 Mapping将 Windows 账号的 SID 映射到具有读权限的PI IdentitySMT → Security → Mappings。PI AF Server 权限AF 模式使用 AF 模式时服务账号还需要目标 AF 数据库的读权限Read读取 AF Elements 及其 Attributes 的权限在 PI System ExplorerPSE中将 Windows 账号加入 AF 数据库的访问控制并授予 Read 和 Read Data 权限。服务账号推荐建议说明创建专用的域服务账号避免使用 Local System机器账号、个人账号或高权限管理员账号最小权限原则仅授予读取 PI 数据的权限无需写权限域账号当 PI 系统使用域认证时使用域账号以支持 Kerberos密码策略建议设置密码永不过期或与密码轮换策略协调软件依赖PI 连接器依赖 PI AF SDKPI AF Client该 SDK 必须安装在运行 taosX 或 taosX-Agent 的主机上依赖最低版本说明操作系统Windows Server 2016 / Windows 10PI AF SDK 仅支持 WindowsPI AF SDKPI AF Client2018从 OSIsoft / AVEVA 获取安装程序.NET Framework4.8PI AF SDK 的运行时依赖重要警告PI AF SDK仅支持 Windows。如果 taosX 部署在 Linux 环境中必须通过部署在 Windows 主机上的 taosX-Agent 作为代理连接 PI 系统。这正是 PI Connector 部署架构 中推荐的 Option BtaosX-Agent 代理模式的核心原因——它让 taosX 可以运行在 Linux 上同时满足 OT/IT 网络隔离的安全要求。任务类型与后续流程前置检查通过后即可在 taosExplorer 的 Data In 页面通过Add Data Source创建接入任务。PI 数据源任务分为两类任务类型taosExplorer 中的名称说明实时任务PI持续订阅 PI 系统的实时数据变更并写入 TDengine回填任务PI backfill抽取指定时间范围内的历史数据并写入 TDengine实时任务的重启补偿时间Restart Compensation Time与回填任务的开始/结束时间等参数配置、多列模型的高级选项同步新元素、同步静态属性变更、同步删除元素、同步删除/修改历史数据等详见 PI 数据接入总览回填性能调优与分片并行策略见 历史数据回填指南多 taosX / Xnode 实例下的任务调度与故障转移见 高可用与故障转移。上线前验证清单在创建 PI 数据接入任务之前请逐项确认以下内容网络与连通性已确认 PI Data Archive Server主机名建议使用主机名而非 IP使用 IP 可能影响 Kerberos 认证_______________已确认 PI AF Server 主机名使用 AF 模式时_______________已确认 AF 数据库名称使用 AF 模式时_______________taosX/taosX-Agent 主机可访问 PI Data Archive端口 5450taosX/taosX-Agent 主机可访问 PI AF Server端口 5457使用 AF 模式时已在 taosX-Agent 主机上使用 PI System Management ToolsSMT或 PI System ExplorerPSE手动验证 PI 连通性——在测试 taosX 之前先隔离环境问题使用 taosX-Agent 代理模式时taosX-Agent 服务运行中、taosX ↔ taosX-Agent 网络连通、taosExplorer 中 taosX-Agent 状态显示在线认证与权限已确认 taosX-Agent 的 Windows 运行身份默认Local System → 域机器账号DOMAIN\machinename$或自定义的域服务账号该 Windows 身份已在 PI Data Archive 中配置了指向相应PI Identity具有读权限的MappingAF 模式该身份在 AF Server Security 中具有 Read / Read Data 权限连接配置中的 Username / Password / Domain保持留空使用 Windows 集成认证软件环境taosX/taosX-Agent 主机操作系统为 Windows已安装 PI AF SDKPI AF Client已安装 .NET Framework 4.8TDengine 侧TDengine 集群已部署并正常运行目标数据库已创建或准备在 taosExplorer 中创建taosX 已安装并可通过 taosExplorer 访问任务配置PI Data Archive Server 名称使用主机名格式已点击Connectivity Check连通性检查按钮连接测试通过常见问题速查Q1连接配置里的 Username/Password/Domain 必须填写吗不需要。全部留空即使用 Windows 集成认证Kerberos 或 NTLM连接器以 taosX-Agent 服务账号的 Windows 身份访问 PI这是生产环境的推荐做法。显式凭据仅用于服务账号无法访问 PI、需要临时指定特定账号的场景且此时密码会以加密形式存储在 taosX 的任务配置中。Q2为什么 PI Server 地址建议用主机名而不是 IPKerberos 票据绑定在基于主机名注册的服务主体名称SPN上。使用 IP 地址连接时Windows 无法匹配 SPN会自动回退到 NTLM 认证而部分 PI 服务器的安全策略要求 Kerberos 并限制或禁用 NTLM。此外使用主机名时 PI 连接日志显示更清晰便于排障。Q3连接器如何在 PI 侧完成身份识别与授权PI 使用两层访问控制认证层Mapping决定你是谁——将 Windows 身份/SID 映射到 PI Identity授权层ACL/Security决定你能做什么——为 PI Identity 授予读权限。两层缺一不可。收紧权限时应修改 ACL而不是删除 Mapping删除 Mapping 会导致认证失败而非权限拒绝。Q4连接测试失败如何排查按顺序排查先用Test-NetConnection验证 5450/5457 端口连通性然后在 taosX-Agent 主机上用 SMT 或 PSE 直接连接 PI若手动连接也失败则说明是环境问题网络/权限/SDK而非 taosX 配置问题再确认 taosX-Agent 运行身份及其在 PI Data Archive 中的 Mapping最后确认 PI AF SDKPI AF Client 2018已安装。当前版本 PI 连接器在连接失败时可能只返回通用错误信息可将连接器日志级别设为debug获取更详细的信息。Q5taosX 部署在 Linux 上能用 PI 连接器吗可以但必须通过 Windows 主机上的 taosX-Agent 代理连接。因为 PI AF SDK 仅支持 Windows这是唯一的连接路径。推荐的生产部署方式是 taosX-Agent 代理模式部署架构中的 Option B。小结PI 数据接入 TDengine 的前置准备可以概括为三件事打通网络5450/5457 端口与 gRPC 通道、配好身份taosX-Agent 服务账号 PI 侧 Mapping 与读权限、装齐软件Windows PI AF SDK 2018 .NET Framework 4.8。逐项核对本文的验证清单后即可在 taosExplorer 中放心创建 PI 实时或回填任务并在创建页面通过Connectivity Check按钮做最终确认。更深入的认证细节可继续阅读 连接配置与认证部署方案选择见 PI Connector 部署架构。【免费下载链接】tdengineTDengine is an open source, high-performance, cloud native time-series database optimized for Internet of Things (IoT), Connected Cars, Industrial IoT and DevOps.项目地址: https://gitcode.com/taosdata/tdengine创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考