PI 实时数据同步指南
本页介绍如何使用 PI 实时任务将 PI 系统的实时数据持续同步到 TDengine，涵盖任务配置、高级功能、最佳实践和常见问题排查。
1. 概述
PI 实时任务用于持续订阅 PI 系统的数据变化，将新产生的数据实时写入 TDengine。典型使用场景包括：
- 实时监控：将 PI 实时数据同步到 TDengine，利用 TDengine 的高性能查询能力构建实时仪表板
- 双写过渡：在从 PI 向 TDengine 迁移过程中，两套系统并行运行
- 数据汇聚：将多个 PI 系统的实时数据汇聚到统一的 TDengine 集群
2. 创建 PI 实时任务
2.1 基本步骤
- 在 Explorer 的数据写入页面，点击 +新增数据源
- 在 类型 下拉列表中选择 PI
- 配置连接信息（详见 主文档）
- 配置数据模型（单列/多列，详见 模型配置参考）
- 配置重启补偿时间（见下节）
- 配置高级选项（见第 4 节）
- 提交任务
2.2 重启补偿时间
重启补偿时间 是 PI 实时任务的一个关键参数。当任务因故意外中断后重启时，taosX 会自动回填从中断时刻到当前时刻这段时间内的数据。
| 参数 | 说明 |
|---|---|
| 重启补偿时间 | 设置重启后自动回填的最大时间窗口 |
配置建议：
- 根据你能容忍的最大数据丢失时间来设置
- 例如，设置为 1 小时，则如果任务中断了 30 分钟后重启，taosX 会回填这 30 分钟的数据
- 如果中断时间超过了补偿时间的设置，超出部分的数据需要通过 PI backfill 任务手动补录
3. 数据同步行为
3.1 单列模型
- 订阅每个 PI Point 的值变化
- 当 PI Point 的值发生变化时，将新值写入对应的 TDengine 子表
- 每个 PI Point 对应一张子表
3.2 多列模型
- 订阅 AF 模板下所有元素的 PI Point 属性变化
- 当某个元素的某个 PI Point 属性值发生变化时，更新对应子表的对应列
- 每个 AF 元素对应一张子表
4. 多列模型高级功能
以下高级选项仅在使用多列模型的实时任务时可用。
4.1 同步新增元素
| 选项 | 默认值 | 说明 |
|---|---|---|
| 同步新增元素 | 开启 | 打开后，PI 连接器会监听模板下新增的元素，自动同步其数据 |
使用场景：当 PI 系统中持续有新设备/资产被添加到 AF 模板下时，无需手动重启任务或修改配置。
4.2 同步静态属性变化
| 选项 | 默认值 | 说明 |
|---|---|---|
| 同步静态属性变化 | 开启 | 打开后，所有非 PI Point 属性（静态属性）的值变化会同步到 TDengine TAG |
使用场景：当 AF 元素的描述信息、分类、位置等静态属性可能被修改时，保持 TDengine TAG 与 PI AF 一致。
4.3 同步删除元素
| 选项 | 默认值 | 说明 |
|---|---|---|
| 同步删除元素 | 开启 | 打开后，PI 连接器监听模板下删除元素的事件，同步删除 TDengine 对应子表 |
注意
开启此选项后，PI 中删除元素将导致 TDengine 中对应子表被删除，数据不可恢复。请谨慎使用。
4.4 同步删除历史数据
| 选项 | 默认值 | 说明 |
|---|---|---|
| 同步删除历史数据 | 开启 | 打开后，PI 中某个时间点的数据被删除时，TDengine 对应时间对应列的数据会被置空 |
4.5 同步修改历史数据
| 选项 | 默认值 | 说明 |
|---|---|---|
| 同步修改历史数据 | 开启 | 打开后，PI 中历史数据被修改时，TDengine 对应时间的数据也会更新 |
使用场景：PI 系统中可能存在数据修正的操作（如手动修改异常值），开启此选项可以保持 TDengine 与 PI 数据一致。
5. 最佳实践
5.1 高可用部署
- 建议使用 Agent 代理模式部署（参见 部署架构），将连接器与 taosX 分离
- 配置合理的重启补偿时间，确保任务重启后不会丢失数据
- 通过 Explorer 监控任务状态，及时发现异常
5.2 性能调优
| 调优项 | 建议 |
|---|---|
| 批次大小 | 根据数据密度调整，点位多且数据频率高时适当增大 |
| 单次读取最大延迟 | 根据实时性要求调整 |
| 日志级别 | 生产环境使用 info 或 warn，排查问题时临时切换到 debug |
5.3 任务监控
通过 Explorer 的数据源列表页面可以查看：
- 任务运行状态
- 数据写入速率
- 最近一次同步时间
- 错误日志
建议定期检查任务状态，确保实时同步正常运行。
6. 常见问题
实时任务数据丢失如何补偿？
如果实时任务中断时间超过了重启补偿时间的设置，可以通过以下步骤补偿：
- 记录任务中断的时间段
- 创建一个 PI backfill 任务，时间范围覆盖中断时段
- 运行回填任务补录数据
- 回填完成后，实时任务继续正常运行
实时同步延迟过大如何排查？
- 网络延迟：检查 taosX/agent 到 PI 系统的网络延迟
- PI 系统负载：检查 PI Data Archive 的负载情况
- TDengine 写入瓶颈：检查 TDengine 集群的写入性能
- 批次大小过大：适当减小批次大小，降低单次处理延迟
- 日志排查：将日志级别调整为
debug，查看详细的处理耗时
新增点位后需要重启任务吗？
- 多列模型：如果开启了 同步新增元素 选项，不需要重启
- 单列模型：需要更新模型配置文件（添加新点位的映射），然后重启任务
- 也可以在 PI 系统新增点位后，重新下载默认配置文件并上传
多列模型的 TAG 值不更新？
确认是否开启了 同步静态属性变化 选项。如果未开启，TAG 值只在子表创建时写入一次，后续不会更新。
