806 数据异常链路排查与定位

版本: v2.1 修改日期: 2026-05-29 适用场景: 数据采集中断、消息流转异常、数据未入库、调度告警未触发等链路异常的生产环境只读排查

ℹ️ 本手册适用于 viSCADA v1.9.0 之前版本，所有排查操作通过 kubectl 命令行完成。v1.9.0 及以上版本可结合 「数据对接服务」 → 「运行日志」 页面辅助排查。

本手册覆盖从设备采集到数据库落库、调度触发的完整数据链路，按”数据流向 + 集群侧辅助”分层排查。所有命令均为只读，不包含任何变更、写入、删除类操作。

1 整体排查流程

排查沿数据流向逐层推进：先确认集群整体状态，再按 「数据对接容器」→ Kafka → millidata → 数据库 主线验证，最后覆盖调度与集群辅助。采集侧发现下发或配置异常时，回查设备服务（device）。

图 1 viSCADA 数据链路分层排查流程

步骤	排查目标	对应章节
`1`	确认集群 Pod 状态，排除 `CrashLoopBackOff`、节点 `NotReady` 等基础设施异常	3 前置监控快速定位
`2`	确认「数据对接容器」运行正常，设备数据已进入采集链路	4.1 数据对接容器（采集入口）
`3`	采集侧报错时回查设备「配置下发」与任务状态	4.2 设备下发 / 配置错误
`4`	验证 Kafka 目标主题已有消息写入	4.3 Kafka 主题消息流转
`5`	确认 `millidata` 正常消费 Kafka 消息并写入 `base_ods` 与 `base_dwd`	4.4 下游数据处理服务（millidata）
`6`	核验 `history` 与 `latest` 表数据已落库	4.5 数据库核验（history / latest）
`7`	涉及调度或告警时排查 DolphinScheduler 工作流与日志	5 调度侧排查（DolphinScheduler）
`8`	仍未定位时通过 Pod / Service / 节点辅助确认	6 集群侧辅助排查

1.1 按故障现象快速选择入口

故障现象	优先排查入口
设备数据完全无上报	4.1 → 4.2 → 4.3
平台采集正常，数据库无历史/最新数据	4.3 → 4.4 → 4.5
数据上报延迟较大	4.3 → 4.4 → 4.5
数据值异常、频繁抖动	4.1 → 设备寄存器/点位配置核对
指令下发失败	4.2 → 4.1 → 设备在线状态
调度未触发、告警异常	5 → 4.4 → 4.5

2 前置条件与安全红线

2.1 生产环境安全红线

⚠️ 本手册仅用于生产环境只读排查。执行任何写入、修改、删除类操作可能导致数据丢失、业务中断或配置污染，严禁在排查过程中混入。

绝对禁止的操作包括但不限于：

删除 Kafka 主题、删除消息
执行数据库 UPDATE / DELETE / DROP / TRUNCATE
修改 「Service」 / 「Deployment」 / 「ConfigMap」
重启 Pod、驱逐节点

操作要求：

优先在业务低峰期排查
涉及敏感资源时建议双人复核
优先小范围过滤日志，避免在集群内做大范围全文搜索

⚠️ kafka-console-consumer.sh --from-beginning 在大主题下可能引发高 IO、长时间阻塞或 broker 资源占用，必须先确认主题规模并加关键词过滤后谨慎使用。

📌 本手册中所有涉及真实环境的 Pod 名、IP、主题名均为示例，实际使用时替换为当前环境的真实值。占位符统一见附录 B：占位符说明。

3 前置监控快速定位

进入具体章节前，先完成以下快速确认，避免在 Pod 已崩溃的前提下反复排查上层业务：


# 查看 prod 命名空间业务 Pod 状态
kubectl get pods -n prod
#       |    |     └── 命名空间（namespace）
#       |    └── 列出 Pod
#       └── kubectl 命令
 
# 查看 kafka 命名空间 Pod 状态
kubectl get pods -n kafka
#       |        └── 命名空间
#       └── 列出 Pod
 
# 查看 dolphinscheduler 相关 Pod（-A = 所有命名空间）
kubectl get pods -A | grep dolphinscheduler
#                 └── 列出所有命名空间的 Pod
 
# 查看近期事件（按时间倒序，取最后 50 条）
kubectl get events -A --sort-by=.lastTimestamp | tail -50
#                        └── 按最后时间戳排序

重点关注：

观测项	判定标准
Pod 状态	是否全部 `Running`
异常状态	是否存在 `CrashLoopBackOff` / `OOMKilled` / `ImagePullBackOff`
节点 / 存储 / 网络事件	近期是否出现资源异常、驱逐、节点 `NotReady`
重启次数	是否存在大规模反复重启

💡 若发现 Pod 层级异常，优先处理基础设施问题，再回到业务链路排查。

4 数据流侧排查

数据流按”采集 → Kafka → 下游处理 → 数据库”顺序层层验证，每层独立闭环，读者可直接跳到任一层完成该层判定。

4.1 数据对接容器（采集入口）

4.1.1 目的

确认 「数据对接容器」（connector，承载 Telegraf 采集任务）运行是否正常，以及设备数据是否已进入采集链路。

4.1.2 日志埋点示例

采集侧通常在 Telegraf 配置中加入 starlark 处理器打印原始指标，便于定位数据是否流入：


[[processors.starlark]]
    namepass = ["${TEMPLATE_NAME}"]
    alias = "${TEMPLATE_NAME}@starting"
    order = ${order@55}
    source = '''
load("logging.star", "log")
load("json.star", "json")
def apply(metric):
    log.info("metricStart:"+json.encode(metric))
    return metric
'''

4.1.3 操作步骤


# 1. 列出 prod 命名空间下 connector 相关 Pod
kubectl get pods -n prod | grep -i connect
#       |        |               └── 忽略大小写过滤
#       |        └── 命名空间
#       └── 列出 Pod
 
# 2. 查看 Pod 状态、所在节点、IP
kubectl get pods -n prod -o wide | grep -E 'connect'
#       |        |        |               └── 扩展正则过滤
#       |        |        └── 宽输出（含 IP、节点、状态）
#       |        └── 命名空间
#       └── 列出 Pod
 
# 3. 跟随指定 Pod 日志（-f = follow，持续输出新日志，Ctrl+C 退出）
kubectl -n prod logs -f <connect-pod-name>
#       |        |    └── 跟随模式，持续输出
#       |        └── 查看日志
#       └── 命名空间
 
# 4. 示例：过滤包含设备 ID 的日志（-v = 排除匹配行）
kubectl -n prod logs -f connector-24043-79b89ffc5f-mcz6p | grep -v '10000' | grep 'JuIzTd8MQ0'
 
# 5. 如 Pod 有多个容器，指定容器查看（-c = 容器名）
kubectl -n prod logs -f <connect-pod-name> -c <container-name>
 
# 6. 限制日志范围，减少噪音
kubectl -n prod logs --tail=200 --since=1h <connect-pod-name>
#                     |            └── 仅最近 1 小时的日志
#                     └── 仅最后 200 行
 
# 7. 无日志或日志异常时，查看 Pod 详情与事件
kubectl -n prod describe pod <connect-pod-name>
#                        └── 查看 Pod 详情（状态、事件、容器信息）
kubectl -n prod get events --sort-by=.lastTimestamp | grep <connect-pod-name>
#                              └── 按最后时间戳排序

4.1.4 常见异常与排查方向

异常现象	典型日志关键字	排查方向
无任何日志输出	—（无输出）	Pod 名称错误 / 容器错误 / 采集任务未触发 / 设备无数据
连接超时	`connection timeout`、`device connect failed`	设备网络不通 / IP 或端口错误 / 从站地址错误 / 设备离线
配置或点位错误	`register address invalid`、`parse failed`、`unsupported field`	寄存器地址错误 / 采集模板字段映射错误 / 协议参数不一致

4.1.5 协议专项检查要点

Modbus 常见检查项：

寄存器地址是否正确
波特率、校验位、停止位是否匹配
从站 ID 是否正确
数据类型是否匹配
采集周期是否合理

S7 常见检查项：

IP 是否正确
机架号、槽号是否正确
DB 块地址是否正确
点位解析方式是否正确

💡 协议类问题优先核查”配置是否与现场设备一致”，不要直接假设程序异常。

4.1.6 判定与下一步

采集日志有有效数据 → 进入 4.3 Kafka 主题消息流转
日志报设备连接、配置、指令错误 → 进入 4.2 设备下发 / 配置错误
Pod 异常重启 → 先处理资源、配置或镜像问题，再回到本节

4.2 设备下发 / 配置错误

4.2.1 目的

定位设备指令下发失败、采集配置错误、任务异常等问题。

4.2.2 操作步骤


# 1. 列出 device 相关 Pod（^device- = 以 device- 开头）
kubectl get pods -n prod | grep '^device-'
#       |        |               └── 过滤以 device- 开头的行
#       |        └── 命名空间
#       └── 列出 Pod
 
# 2. 跟随目标 Pod 日志
kubectl -n prod logs -f <device-pod-name>
#       |        |    └── 跟随模式，持续输出
#       |        └── 查看日志
#       └── 命名空间
 
# 3. 按任务 ID 或设备 ID 过滤
kubectl -n prod logs -f device-service-8f7885b79-2fr9v | grep 'task-123456'
 
# 4. 查看 Pod 详情与事件
kubectl -n prod describe pod <device-pod-name>
#       |               └── 查看 Pod 详情（状态、事件、容器）
#       └── 命名空间
kubectl -n prod get events --sort-by=.lastTimestamp | grep <device-pod-name>
#       |        |                               └── 过滤目标 Pod 事件
#       |        └── 列出事件，按时间戳倒序
#       └── 命名空间
 
# 5. 查看关键字上下文（-A N = 匹配行及后 N 行，-B N = 前 N 行，-C N = 前后各 N 行）
kubectl -n prod logs -f device-service-8f7885b79-2fr9v | grep -A 5 'task-123456'
kubectl -n prod logs -f device-service-8f7885b79-2fr9v | grep -B 5 'task-123456'
kubectl -n prod logs -f device-service-8f7885b79-2fr9v | grep -C 5 'task-123456'

💡 grep -A N 显示匹配行及后 N 行，grep -B N 显示匹配行及前 N 行，grep -C N 显示前后各 N 行。

💡 kubectl 不支持直接把 device-* 当作 Pod 名通配符执行日志命令，必须先查出真实 Pod 名。

4.2.3 正常结果示例


taskId=task-123456 dispatch success
deviceId=JuIzTd8MQ0 config applied successfully

4.2.4 常见异常与排查方向

异常现象	典型日志关键字	排查方向
配置下发失败	`config push failed`、`device not online`	设备在线状态异常 / 下发目标错误 / 网络不通 / 服务鉴权失败
任务不存在	`task not found`	任务 ID 错误 / 配置未同步 / 环境查错

4.2.5 判定与下一步

设备配置异常 → 先修复配置，再回到 4.1 数据对接容器（采集入口）重新验证
设备日志正常 → 继续 4.3 Kafka 主题消息流转

4.3 Kafka 主题消息流转

4.3.1 目的

验证采集数据是否已写入 Kafka 主题（例如 ods.<PROJECT_ID>.data）。

4.3.2 操作步骤


# 1. 查看 kafka 命名空间 Pod
kubectl get pods -n kafka
#       |        └── 命名空间
#       └── 列出 Pod
 
# 2. 进入 Kafka Pod（exec = 在容器内执行命令，-it = 交互式终端，-- = kubectl 参数结束）
kubectl exec -n kafka -it kafka-0 -- bash
#       |    |        |   |       |    └── 要执行的命令
#       |    |        |   |       └── 分隔符
#       |    |        |   └── Pod 名称
#       |    |        └── 交互式终端
#       |    └── 命名空间
#       └── 在容器内执行命令
 
# 若 bash 不可用，改用 sh
kubectl exec -n kafka -it kafka-0 -- sh

Pod 内执行：


# 3. 查看所有主题
sh /opt/bitnami/kafka/bin/kafka-topics.sh --bootstrap-server 127.0.0.1:9092 --list
#                                            |                            └── 列出所有主题
#                                            └── Kafka broker 地址
 
# 4. 查看目标主题详情（分区数、副本分布、leader）
sh /opt/bitnami/kafka/bin/kafka-topics.sh --bootstrap-server 127.0.0.1:9092 --describe --topic ods.1.data
#                                                                          └── 查看详情       └── 目标主题
 
# 5. 消费新消息并过滤关键字
sh /opt/bitnami/kafka/bin/kafka-console-consumer.sh --bootstrap-server 127.0.0.1:9092 --topic ods.1.data | grep '48985'
 
# 6. 使用 Service 地址消费（推荐）（--group = 指定消费者组，避免影响现有消费进度）
sh /opt/bitnami/kafka/bin/kafka-console-consumer.sh --bootstrap-server kafka:9092 --topic ods.1.data --group debug-ops | grep '48985'
 
# 7. 历史消息排查（谨慎！--from-beginning = 从最早消息开始消费）
sh /opt/bitnami/kafka/bin/kafka-console-consumer.sh --bootstrap-server 127.0.0.1:9092 --topic ods.1.data --from-beginning | grep '48985'

ℹ️ 127.0.0.1:9092 仅在 Pod 内与 broker 同网络环境时适用。优先使用集群 Service 地址，如 kafka:9092。

⚠️ --from-beginning 可能触发全量历史消费，在大主题下极易引发高 IO 与内存占用，仅用于小范围、带过滤的历史定位，使用前核实主题规模。

4.3.3 常见异常与排查方向

异常现象	典型日志关键字	排查方向
主题不存在	`Topic 'ods.1.data' does not exist`	项目 ID 错误 / 主题名拼写错误 / 环境错误
无任何输出	—（无输出）	主题无消息 / `grep` 关键字错误 / broker 地址错误 / 权限不足 / 网络不通
权限拒绝	`Topic authorization failed`	Kafka ACL 权限不足 / 当前用户或容器权限受限

4.3.4 判定与下一步

Kafka 有目标消息 → 进入 4.4 下游数据处理服务（millidata）
Kafka 无消息 → 回查 4.1 与 4.2
Kafka 主题异常 → 先核查主题、broker、网络与权限

4.4 下游数据处理服务（millidata）

4.4.1 目的

确认 Kafka 消息是否被 millidata 等下游服务正常消费、解析、标准化并写入数据库。

ℹ️ millidata 是 Kafka 消息的下游消费服务，负责字段解析、「标准化名称」 映射与数据库写入，区别于采集侧的 「数据对接容器」（connector）。

4.4.2 操作步骤


# 1. 查看 millidata 相关日志
kubectl -n prod logs -f millidata-54db4cc449-47rfx
#       |        |    └── 跟随模式，持续输出
#       |        └── 查看日志
#       └── 命名空间
 
# 2. 指定容器并限制日志量（-c = 容器名，--tail=20 = 仅最后 20 行）
kubectl -n prod logs -f --tail=20 millidata-54db4cc449-47rfx -c broker-dock
 
# 3. 按设备 ID 过滤
kubectl -n prod logs -f millidata-54db4cc449-47rfx -c broker-dock | grep '<device-id>'
 
# 4. 若不清楚容器名，先查询（jsonpath = 提取 JSON 字段值）
kubectl -n prod get pod <pod-name> -o jsonpath='{range .spec.containers[*]}{.name}{"\n"}{end}'
#                                                             └── 遍历所有容器，逐行输出容器名

4.4.3 正常结果示例


consume success, deviceId=JuIzTd8MQ0, pid=535675
standard name mapping success
write db success

4.4.4 常见异常与排查方向

异常现象	典型日志关键字	排查方向
标准化名称冲突	`duplicate standard name`、`name conflict`	同一系统中存在带 `m_` 前缀与不带 `m_` 前缀的重复属性名 / 标准化命名不规范
PID 冲突	`pid duplicated`	不同类别设备共用相同 `PID` / 多项目配置串用
字段解析失败	`field parse failed`、`schema mismatch`	Kafka 消息格式与服务解析逻辑不一致 / 字段缺失 / 表结构不匹配

4.4.5 命名与 PID 冲突规则

⚠️ 不同类别设备不得使用相同 PID，否则下游服务无法区分数据归属，会导致写库冲突或数据覆盖。

⚠️ 同一个 viSCADA 系统中，严禁同时存在带 m_ 前缀和不带 m_ 前缀的相同 「属性」 名称。例如 m_001t 与 001t 在 millidata 中会被视为同一 「标准化名称」，引发写库冲突。

4.4.6 判定与下一步

处理正常 → 进入 4.5 数据库核验（history / latest）
存在命名冲突、PID 冲突、字段解析失败 → 先修正规则与配置后再重试

4.5 数据库核验（history / latest）

4.5.1 目的

确认目标数据是否已成功入库，核验历史表与最新表状态。

4.5.2 数据流向说明

图 2 Kafka 到数据库的落库路径

原始采集 → Kafka 主题 → 下游处理 → 历史表
历史表同步或聚合 → 最新表

4.5.3 查询 SQL 示例


-- 历史表：按 pid 查看最近 10 条（xxxxx 替换为模型前缀）
SELECT *
FROM base_dwd.xxxxx_m_source_history
--     └── 历史表（全量拉链数据）
WHERE pid = 535675
--    └── 设备 PID（替换为实际值）
ORDER BY aligntime DESC
--         └── 按时间降序，最新在前
LIMIT 10;
--    └── 仅取 10 条


-- 最新表：按 pid 查看最近数据（xxxxx 替换为模型前缀）
SELECT *
FROM base_dwd.xxxxx_m_latest
--     └── 最新表（每个设备仅保留最新一条）
WHERE pid = 535675
ORDER BY aligntime DESC
LIMIT 10;

💡 建议加时间过滤，避免全表扫描：


SELECT *
FROM base_dwd.xxxxx_m_source_history
WHERE pid = 535675
  AND aligntime >= '2026-01-06 00:00:00'
--    |              └── 起始时间（替换为排查时间点）
--    └── 时间过滤列
ORDER BY aligntime DESC
LIMIT 10;

4.5.4 正常结果判定

能查询到与 Kafka 消息对应的 PID
时间戳接近当前时间
值字段正常
latest 与 history 数据逻辑一致

4.5.5 常见异常与排查方向

异常现象	排查方向
`history` 无数据	下游服务未消费 / 写库失败 / `PID` 错误 / 库表错误 / 时间范围不正确
`history` 有数据，`latest` 无数据	`latest` 更新链路异常 / 聚合逻辑异常 / 表同步任务异常
查询慢或超时	未走索引 / 时间范围过大 / 表数据量过大 / 数据库性能瓶颈

ℹ️ 排查数据库时务必核对时区、库名、表名、PID、时间范围是否正确。

4.5.6 判定与下一步

history / latest 均正常 → 链路基本闭环
数据库无数据 → 回查 4.4 下游数据处理服务（millidata）
数据库有数据但页面无展示 → 继续检查上层展示逻辑或缓存机制

5 调度侧排查（DolphinScheduler）

5.1 目的

定位任务调度、工作流触发、告警通知等异常。

5.2 操作步骤


# 1. 查看 dolphinscheduler 相关 Pod（-A = 所有命名空间）
kubectl get pods -A | grep dolphinscheduler
 
# 2. 查看告警组件日志
kubectl -n dolphinscheduler logs -f dolphinscheduler-alert-dd58ddcdd-jv9vt
#       |                     |    └── 跟随模式，持续输出
#       |                     └── 查看日志
#       └── 命名空间
 
# 3. 查看 Service 与端口（svc = Service 资源）
kubectl get svc -A | grep dolphinscheduler
#       |    └── 所有命名空间
#       └── 列出 Service

5.3 访问方式示例

DolphinScheduler 前端访问示例：


http://10.10.10.111:31270/dolphinscheduler/

Service 类型	访问方式
`NodePort`	任一节点 `IP` + `nodePort`
`LoadBalancer`	外部负载均衡地址
`ClusterIP`	仅集群内部访问

5.4 常见异常与排查方向

异常现象	排查方向
页面不可达	Service 类型不正确 / `NodePort` 未开放 / 防火墙限制 / Pod 未就绪
任务未触发	`scheduler` 异常 / `worker` 异常 / 上游依赖未满足 / 数据条件未达成

⚠️ 生产环境禁止执行 kubectl edit svc 等变更操作。排查阶段仅允许查看，如需调整 Service 类型，走变更审批流程。

6 集群侧辅助排查

当数据流侧排查无法定位时，通过 Pod、Service、节点三个维度辅助确认。

6.1 查询 Pod 所在节点与 IP


# 查询 Pod（-o wide = 宽输出，含 IP、节点）
kubectl get pods -n prod | grep <keyword>
kubectl get pods -n prod -o wide | grep <keyword>

输出重点字段：

NODE：Pod 所在节点
IP：Pod 集群内 IP

6.2 查询 Service 端口


# 列出 Service（svc = Service 资源）
kubectl get svc -n prod | grep <keyword>
#       |               └── 过滤关键字
#       └── 列出 Service
 
# 查看 Service 详情（含端口、选择器、端点）
kubectl describe svc <svc-name> -n prod

6.3 常用场景示例

采集容器（connector）：


# Pod 列表（-i = 忽略大小写）
kubectl get pods -n prod | grep -i connect
# Pod 宽输出（-o wide = 含 IP、节点；-E = 扩展正则）
kubectl get pods -n prod -o wide | grep -E 'connect'
# Service 列表
kubectl get svc -n prod | grep connect

设备服务（device）：


# Pod 列表（^device- = 以 device- 开头）
kubectl get pods -n prod | grep '^device-'
# Pod 宽输出
kubectl get pods -n prod -o wide | grep '^device-'
# Service 列表
kubectl get svc -n prod | grep device

下游处理服务（millidata）：


# Pod 列表
kubectl get pods -n prod | grep millidata
# Pod 宽输出
kubectl get pods -n prod -o wide | grep millidata
# Service 列表
kubectl get svc -n prod | grep millidata

Kafka：


# Pod 列表
kubectl get pods -n kafka
# Pod 宽输出（-o wide = 含 IP、节点）
kubectl get pods -n kafka -o wide
# Service 列表
kubectl get svc -n kafka | grep kafka

DolphinScheduler：


# Pod 列表（-A = 所有命名空间）
kubectl get pods -A | grep dolphinscheduler
# Pod 宽输出
kubectl get pods -n dolphinscheduler -o wide | grep dolphinscheduler
# Service 列表
kubectl get svc -A | grep dolphinscheduler

节点信息：


# 查看所有节点状态与资源
kubectl get nodes -o wide
# 查看 Pod 详细事件（含调度信息、挂载状态）
kubectl describe pod <pod-name> -n <namespace>

6.4 注意事项

ℹ️ 127.0.0.1 仅表示当前容器 / Pod 内部网络环境；集群外部访问需通过 Service。端口问题通常需结合 Pod、Service、节点三者一起看。

7 常见报错分析

现象	可能原因	处理建议
`kafka-console-consumer` 执行后无输出	主题名错误 / broker 地址错误 / `grep` 关键字错误	先 `--list` 核对主题；改用 `kafka:9092`；去掉 `grep` 查看原始输出
`kubectl logs` 无输出	Pod 名错误 / 多容器未指定 / Pod 未运行	`kubectl get pods` 核对 Pod 名；用 `jsonpath` 查容器名；`describe pod` 查状态
Kafka 有消息，数据库无数据	`millidata` 未消费 / 字段解析失败 / 命名冲突 / PID 冲突 / 写库失败	按 Kafka → `millidata` 日志 → 字段映射 → 命名规则 → 库表结构 → 性能顺序排查
页面无数据，数据库有数据	上层接口缓存未刷新 / `latest` 与 `history` 不一致 / 前端筛选条件错误 / 时区错误	清缓存 / 核对筛选条件 / 核对时区
设备数据频繁抖动或值错误	寄存器地址错误 / 数据类型解析错误 / 采样周期过短 / 设备原始值异常 / 比例系数换算错误	核对采集配置与现场设备一致性
Pod 处于 `CrashLoopBackOff`	配置错误 / 镜像拉取失败 / 资源不足 / 依赖服务不通	`describe pod` 看事件 + `logs --previous` 看上次崩溃日志
连接超时 `connection timeout`	设备离线 / 网络不通 / IP 或端口错误 / 从站地址错误	现场核对网络与设备配置
标准化名称冲突 `duplicate standard name`	带 `m_` 前缀与不带前缀的属性名并存	统一命名规范，移除重复定义
PID 冲突 `pid duplicated`	不同设备类共用 PID / 多项目串用	按项目与设备类重新分配 PID

8 回报格式

📌 排查结束后，无论是否定位到根因，均按以下格式回报，便于二线复核与知识沉淀。

回报材料清单：

基本信息： 项目编号 <PROJECT_ID>、设备标识 <device-id>、故障发生时间、发现时间
故障现象描述： 对应 1.1 按故障现象快速选择入口中的一类或多类
定位路径： 本次排查涉及的章节编号与次序（如 4.1 → 4.3 → 4.4）
关键截图 / 日志片段： Pod 日志片段、Kafka 消费输出、数据库查询结果、告警信息
命令与输出： 本次排查使用的关键 kubectl / Kafka / SQL 命令及脱敏后的输出
根因与处置建议： 初步判定的根因；建议的后续变更动作（若涉及变更，转变更审批流程，不在本次排查中执行）
未定位项： 本次未能定位的环节，附已排除的可能性

附录 A：命令速查

A.1 采集排查


kubectl get pods -n prod | grep -i connect
kubectl get pods -n prod -o wide | grep connect
kubectl -n prod logs -f <connect-pod-name>
kubectl -n prod logs --tail=200 --since=1h <connect-pod-name>
kubectl -n prod describe pod <connect-pod-name>

A.2 设备服务排查


kubectl get pods -n prod | grep '^device-'
kubectl -n prod logs -f <device-pod-name>
kubectl -n prod describe pod <device-pod-name>

A.3 Kafka 排查


kubectl get pods -n kafka
kubectl exec -n kafka -it <pod-name> -- bash
sh /opt/bitnami/kafka/bin/kafka-topics.sh --bootstrap-server <broker:port> --list
sh /opt/bitnami/kafka/bin/kafka-topics.sh --bootstrap-server <broker:port> --describe --topic <topic>
sh /opt/bitnami/kafka/bin/kafka-console-consumer.sh --bootstrap-server <broker:port> --topic <topic>

A.4 下游处理服务排查


kubectl -n prod logs -f <pod-name>
kubectl -n prod logs -f <pod-name> -c <container-name>
kubectl -n prod get pod <pod-name> -o jsonpath='{range .spec.containers[*]}{.name}{"\n"}{end}'

A.5 数据库查询


SELECT * FROM <table> WHERE pid = <pid> ORDER BY aligntime DESC LIMIT 10;

A.6 调度服务排查


kubectl get pods -A | grep dolphinscheduler
kubectl -n dolphinscheduler logs -f <pod-name>
kubectl get svc -A | grep dolphinscheduler

A.7 集群通用查询


kubectl get pods -n <namespace>
kubectl get pods -n <namespace> -o wide
kubectl describe pod <pod-name> -n <namespace>
kubectl get svc -n <namespace>
kubectl describe svc <svc-name> -n <namespace>
kubectl get nodes -o wide

附录 B：占位符说明

占位符	说明	取值来源
`<namespace>`	Kubernetes 命名空间	集群资源规划
`<connect-pod-name>`	数据对接容器 Pod 名称	`kubectl get pods -n prod`
`<device-pod-name>`	设备服务 Pod 名称	`kubectl get pods -n prod \| grep '^device-'`
`<pod-name>`	通用 Pod 名称	Kubernetes 查询结果
`<container-name>`	Pod 内容器名称	`kubectl get pod -o jsonpath`
`<svc-name>`	Service 名称	`kubectl get svc`
`<broker:port>`	Kafka broker 地址	例如 `kafka:9092`
`<topic>`	Kafka 主题名称	例如 `ods.<PROJECT_ID>.data`
`<PROJECT_ID>`	项目唯一编号	viSCADA 平台项目详情页
`<pid>`	设备或站点唯一 PID	viSCADA 平台设备详情页 / 数据库
`<device-id>`	设备唯一标识	采集配置 / 设备编码
`<task-id>`	采集任务唯一 ID	设备服务日志 / 配置中心
`<keyword>`	检索关键字	设备 ID、任务 ID、`traceId` 等
`<TEMPLATE_NAME>`	Telegraf 采集模板名	采集容器配置
`<ORDER>`	Telegraf 处理器顺序	采集容器配置

附录 C：参考文档

以下 mrdoc 链接作为外部补充参考，实际排查以本手册主流程为准。若链接失效，按归口联系文档维护人。

参考内容	链接
数据对接的数据链路说明	mrdoc 共享文档
物联与一网平台标准对接排查手册	mrdoc
数据采集与下发控制全流程说明	mrdoc
Modbus 协议排查文档	mrdoc
S7 协议排查文档	mrdoc