跳到主要内容

现场案例集

不是「请这样做」，而是「发生了这样的事，这样解决了」的记录。 只收录了2026年2月至9月在实际现场遇到并解决的内容。

本文档阅读方法

一般流程和基本使用方法不在本文中。那些内容请以故障排除 和技术故障排除为准。

这里是症状 → 原因 → 处理三行记录。请在其中查找与当前症状相似的内容， 作为原因候选。保留的数字仅是协议标准或库默认值这类知识本身， IP、主机名、客户公司名均已删除。

1. 现场安装 · 网络​

PLC ping 不通，无法收发数据​

  • 症状 现场安装后与PLC无法通信。ping无响应。
  • 原因 未区分PLC IP与应分配给Edge PC的IP。
  • 处理 将Edge PC的IP设置为与PLC同网段·不同主机·相同掩码。出差前在表格中填写两个IP，确认它们互不相同后再出发。
  • 确认 若双方通信同时中断，首先怀疑IP冲突。按ping → 端口 → read 的顺序逐步缩小范围。

不知道三菱端口，工程师只能干等​

  • 症状 不知道MC协议端口，工作停滞。
  • 原因 三菱没有官方固定端口。 这是在GX Works的「打开设置」中指定的值。
  • 处理 只需请工程师明确指定四项 — ① 打开设置画面 ② 协议·打开方式·本机端口 ③ 是否为MC协议专用设置 ④ 允许连接的IP限制。不要用「通信设置怎么做」这种方式打开询问。
  • 参考 常见惯例值为内置以太网1025·模块2001，5001·5002为保留端口。5007是库的默认值，不是三菱的默认值。

ping、端口都通，但数值读不出来​

  • 症状 连接正常，但内存数值无法读入。
  • 原因 PLC DB块内存地址值问题。
  • 处理 请PLC工程师确认DB块地址值。只要地址正确且连接选项无问题，现场数据已证明Edge侧的扫描没有问题。此后属于PLC侧的处理范畴。

关闭配电柜门后通信变得不稳定​

  • 症状 关闭配电柜门后网络极不稳定，打开门则正常。
  • 原因 在厚重配电柜内部同时放入了Edge PC、LTE路由器，甚至包括天线。
  • 处理 将天线安装在配电柜外部。开孔位置由电气室负责人指定。外部安装时接缝处必须做硅胶密封处理——防止固定不良。

现场勘察漏掉确认项，导致现场施工受阻​

  • 症状 以为已经准备好了，但现场仍不断出现变量。
  • 处理 固定6项勘察清单 — 配电柜结构·机箱种类 / PLC型号·状态 / 网络通信方式 / AP区域ping状态 / Edge PC安装位置 / 天线位置。机箱由Edge迷你PC + LTE路由器 + 二孔接线板组成，必须考虑电源适配器的位置。

无法确定Edge PC的安装数量​

  • 症状 完成勘察后仍无法确定设备数量。
  • 原因 未能确保采集标签数量。 需要标签数与采集周期才能计算每台设备的负载并确定数量，但当时没有清单，且安装位置有限，难以追加安装。原本假设1:1映射，但客户要求1:N。
  • 处理 勘察前先获取 ① 各业务场所PLC标签清单及数量 ② 安装信息表单（PLC/SCADA · IP/PORT · 协议） ③ 新增区段网络构成方案。

PLC没有以太网口，或被要求经由SCADA PC采集​

  • 症状 以太网TCP直连的前提不成立。遇到「从连接PLC的PC上取不就行了吗」的要求，或多台PLC仅记录在SCADA PC的DB中的结构。
  • 处理 勘察时必须确认PLC是否有以太网口 / 是否经由SCADA / SCADA DB种类及记录方式，提前确定采集方式。

接入测试工具后采集中断​

  • 症状 验证工具接入后，原有采集被拒绝或受到干扰。
  • 原因 在MELSEC这类单连接插槽设备上开启了第二个TCP连接。
  • 处理 禁止以下三项。
    1. 禁止对正在采集的PLC开启第二个连接 — 先停止对应的OPC。
    2. 禁止write — 工具的一个参数就会触发write。
    3. 禁止探测超时设为1秒 — 设备accept延迟实测约为2.6秒，应设为3~5秒。

2. 启动 · 开机​

启动后所有endpoint无响应 + ping重试日志刷屏​

  • 症状 请求全部超时(code=000)。
  • 原因 dev.mode=EDGE，外部Platform的网页端口已失效，导致启动被阻塞。
  • 处理 改为dev.mode=STANDALONE后重启，待外部恢复后再还原。同时检查server.host。

网页画面每3~4分钟就无响应​

  • 症状 网页周期性宕机后又恢复。
  • 原因 未与Platform连接。 无法连接时，网页上下文会每3~4分钟陷入重载循环。一旦连接成功就会停止。不是网页本身的问题。
  • 处理 恢复与Platform的连接是根本解决方法。

更换认证密钥后NPE无限爆发​

  • 症状 日志中dm is null NPE持续堆积，DB相关功能全部失效。
  • 原因 密钥错误时，API client初始化会以403硬性失败，导致DatalakeManager无法初始化，使DB层崩溃。密钥正常时会通过回退机制启动。
  • 处理 恢复原密钥后重启。通过启动日志中的**DataSource initialized — ready**行进行确认。

3. Platform上行（传输）中断​

Edge网页和采集均正常，但数据未上传至Platform​

这是最常遇到的情形。

  • 症状 现场采集和网页均正常，但仅上行中断。网页端口TIME-WAIT堆积超过100个。

  • 原因 线路瞬断后，MQTT重连的CONNECT中缺失认证信息，Platform拒绝连接并陷入无限重连。由于认证信息只存在于最初启动路径中，一旦断开，应用无法自行恢复。

  • 处理 重启Web应用可恢复会话。防止复发请参见下方watchdog。

  • 确认 其特征是「Platform网页端口已打开，但MQTT会话不存在」。

    nc -z -w2 <플랫폼IP> <웹포트> && echo ROUTE_OK
    ss -tan | grep -c "ESTAB.*<플랫폼IP>:<MQTT포트>"   # 1 정상 / 0 끊김

瞬断仅几秒，却导致数日上行中断​

  • 症状 瞬断7秒后中断3小时，一次瞬断导致中断11天。
  • 原因 与上述相同。由于网页、PLC采集、线路全部正常，无人察觉异常。
  • 处理 部署自动恢复(watchdog)。瞬断时长与中断时长无关，应优先处理无监控的设备。

数据未存入Platform，却一直在排查Edge​

  • 症状 上行正常，但Platform中未留存数据。
  • 原因 问题不在Edge，而在Platform存储路径。 在broker之前抓取topic确认Edge发布正常，真正的阻塞点是Platform存储初始化因DB查询超时而永久未初始化。
  • 处理 重启Platform服务器。最终恢复是同时解决了多个原因——broker认证文件缺失 + 标签description为null + Platform存储缓冲区停止。
  • 确认 存储成功的判定标准不是SSTable的生成，而是目标标签的实际存在。曾有仅看生成就误判为通过的先例。

watchdog自动恢复的配置​

  • 症状 上行中断必须由人工发现才能恢复。
  • 处理 将watchdog三种分别部署为独立服务——线路（仅记录日志）·设备网络（仅记录日志）·Platform会话（重启Web应用）。因为一个失效时其余必须存活，不合并为一个服务。
  • 判定 以30秒间隔连续4次（约2分钟）确认特征→重启→15分钟内禁止再次触发。
  • 结果 6台部署中误报0次。实际恢复案例为瞬断05:27 → 触发05:39 → 恢复05:40。

安装了watchdog却未自动恢复​

  • 症状 中断11天，watchdog毫无动作。
  • 原因 处于**仅观察（DRY_RUN=1）**状态。would restart仅记录了1,013次。判定准确，唯一的失败点就在于此。
  • 处理 观察部署 → 在1台设备上验证实际重启 → 在正常状态下切换至执行模式。若在中断状态下切换，会立即触发重启。

手动重启命令杀死了自身的shell​

  • 症状 执行重启命令后shell立即死亡，Web应用宕机3分34秒。
  • 原因 pkill -9 -ef tomcat的命令行中含有「tomcat」，匹配到了自身。后面拼接的startup未能执行。
  • 处理 将kill与startup分离为独立执行。状态确认时使用类似pgrep -f 'catalina[.]startup'的方括号写法避免自我匹配。
  • 注意 restart.sh末尾带有日志tail，在自动化中调用会导致卡住。

PLC正常，但watchdog报告服务DOWN​

  • 症状 会话存活，却出现1,422次误报。
  • 原因 ① 判定模式遗漏了IPv6-mapped表示法（[::ffff:<PLC_IP>]:<PLC포트>）。② 作为回退使用的nc在单会话设备上被拒绝。
  • 处理 ① 修改模式以同时支持有无方括号两种形式。② 将判定顺序改为优先使用ss ESTAB被动方式，不存在时才用nc。

重启watchdog后采集中断2分钟​

  • 症状 修改watchdog设置时Web应用同时被终止。
  • 原因 watchdog启动的Web应用被纳入watchdog服务的cgroup，因而一同被终止。
  • 处理 90秒后会重新检测并自动重启实现自愈，但仍会产生2分钟中断。变更watchdog设置请在不影响生产作业的时间段进行。

诊断通道401反复记录​

  • 症状 诊断端口长期处于SYN-SENT状态，日志每2~3秒出现一次诊断认证401。
  • 原因 这是Platform侧的问题，由于诊断发送器因版本差异未携带密钥，即使在正常运行组合下也会同样出现401。
  • 处理 由于Edge重启无法解决，应将其排除在watchdog触发条件之外。联动是否正常以60秒内是否有实际标签数据进入作为判定标准。

4. PLC采集稳定性​

通信稍有波动，采集就反复停止·重启​

  • 症状 轻微通信波动导致采集反复停止后又重新连接。

  • 原因 ping仅失败1次就立即停止采集器。

  • 处理 把缓冲机制放在了停止和恢复一侧。NOT_COLLECT 判定本身没有缓冲。

    项目值
    ping 周期 · ICMP 超时5秒 · 800ms
    ping连续失败多少次才停止采集器（成功则重置）3次
    最近读取成功且新鲜时跳过 ping 的窗口15秒或采集周期 ×3，取较长者
    降为NOT_COLLECT的条件无缓冲——一个周期内只要有1件错误，或一个值都没收到，就在该周期立即降级
    NOT_COLLECT 持续多久才请求恢复（重新连接）超过60秒
    这些无法通过配置更改

    包括 ping 3次 · 恢复60秒在内，上述各值都是固化在代码中的常量。app.properties中不存在 对应的键——如需更改，需要进行产品层面的变更。以往有些资料误写为可配置项，实际并非如此。

    同时取消了按标签的重试机制。 一旦连接断开，所有标签会同时失败，重试只会拖延扫描。 为此改为设置按标签的读取超时，避免单个标签的延迟拖累整个扫描。

    连接失败时会启用按连接的重连退避（2026-10-01）。从1秒开始每次加倍，最长等待60秒后再重连。 一旦连接成功或更改了IP·端口，就不再等待而立即重试。

  • 结果 短暂的波动可能会在画面上短暂显示为NOT_COLLECT。但不会因此停止采集器或引发重连—— ping 连续失败3次之前不会停止，只有 NOT_COLLECT 持续超过60秒时才会请求恢复。

监控层ICMP误报导致正常采集被停止​

  • 症状 采集正常进行中，监控却停止了采集器。
  • 原因 监控层仅依据ping结果进行判断。
  • 处理 将监控标准改为**「有流量即存活证据」**。若最近的read成功且数据新鲜，则跳过探测。

套接字泄漏导致PLC全面拒绝连接50分钟​

  • 症状 采集、探测、恢复所有连接均被拒绝。
  • 原因 废弃驱动时未调用close就丢弃，导致套接字泄漏，且由于是单插槽设备，该套接字永久占用了该插槽。connected=false只是一个逻辑标志，与TCP套接字是独立的。
  • 处理 在移除·替换驱动的代码中必须伴随调用close。

因探测超时，恢复永远无法开启​

  • 症状 插槽已空闲，但仍无法恢复。
  • 原因 设备accept延迟约为2.6秒，而探测超时为1秒，被判定为永久失败。
  • 处理 将超时提升至4秒。接入新设备时应通过日志实测连接耗时并验证余量。
不要相信一次验证通过

上面三个案例症状相同但原因有三层。每修复一个就判断为「已解决」， 但实际上仍有后续原因未被发现。

事故大多出现在启动后1分钟内。应集中观察前3分钟， 只有同时满足启动判定区间 + 15分钟无中断 + 日志0条才可判定通过。

无法确认通信不稳定的原因是否出在线路上​

  • 症状 无法定位间歇性采集失败的原因区间。
  • 观测 实际案例中**连接延迟飙升至平均值的6倍（6,125ms）**后，链路在接下来数天内断开， 在未做任何处理的情况下自动恢复，采集重新开始。延迟骤增是前兆信号。
  • 处理 设置常态化质量监控。将1秒间隔的ping以10分钟为单位汇总（丢包率·RTT最小·平均·最大值）， 若丢包率达到5%以上，则同时快照记录接口错误计数器和路由信息。判定标准为正常 / 注意5% / 危险10%，日志保留15天。

无法复现丢包状况​

  • 症状 现场症状无法在内部重现，验证受阻。

  • 处理 使用tc/netem对特定PLC IP的通信人为注入丢包。不影响SSH或其他通信。

    tc qdisc del dev <NIC> root 2>/dev/null            # 항상 먼저 제거
    tc qdisc add dev <NIC> root handle 1: htb default 30
    tc class add dev <NIC> parent 1: classid 1:1 htb rate 100mbit
    tc class add dev <NIC> parent 1:1 classid 1:10 htb rate 100mbit
    tc qdisc add dev <NIC> parent 1:10 handle 10: netem loss 5%
    tc filter add dev <NIC> protocol ip parent 1:0 prio 1 u32 match ip dst <PLC_IP> flowid 1:10
    tc qdisc del dev <NIC> root                        # 종료

watchdog日志解读​

只有状态发生变化时才会留下事件区块。使用grep "EVENT"只查看事件。

类别信号含义
LTECABLE_DISCONNECTED物理链路
LTEROUTER_DOWN路由器ping失败
LTELTE_NO_RETURN_TRAFFIC有发送但接收为0——上行断开
LTELTE_SIGNAL_LOST外部ping失败
PLCLINK_DOWN · ARP_L2_ISSUE链路·L2
PLCPHYSICAL_LAYER_ISSUECRC增加——线缆·端口物理问题
PLCPLC_NO_RESPONSE · PLC_SERVICE_DOWN无响应 · 端口关闭

⚠ 部分NIC不支持rx_crc_errors。CRC:+0为回退值，请勿用于物理层判定。

5. 数值缺失或异常​

HMI画面数值与Edge采集数值不一致​

  • 原因 HMI数值可能是已应用逻辑运算后的值。
  • 处理 分三段缩小范围——PLC内存原始值 → HMI面板（已应用逻辑） → Edge（数据类型·采集周期·计算公式）。 先与PLC原始值比较，再确认Edge的类型·周期·计算公式，最后进行最终比对。

计数器间歇性混入异常中间值​

  • 原因 在PLC扫描周期中，计数器更新时机与读取时间点重叠时，高低位字的一致性会被破坏，从而读到中间值。这不是故障，而是时序特性。

填入标签地址后持续返回空值​

  • 原因 在JSON类地址中遗漏了PATH模式写法（$.），导致退化为KEY模式。KEY模式不会沿路径查找， 而是按最顶层键名原样查找。受此影响的有Kafka · MQTT · WebSocket，HTTP不受影响。

  • 处理 确认以下三点。

    • 数组索引使用点号加数字（.0.），不支持方括号写法。
    • 字段名需精确到大小写（agvid失败 / agvId成功）。
    • 不支持通配符及数组整体展开。
    TOPIC:$.body.list.0.battery     ✅
    TOPIC:body.list[0].battery      ❌

仅特定标签持续返回空值​

  • 原因 发送端载荷中的字段名存在拼写错误（status → stutaus）。即使按正确拼写注册，也只会得到空值而无报错。
  • 处理 注册前应亲眼确认实际载荷中字段名的原文。
  • 附带注意事项 空字符串根本不会被存储（无报警时段会出现数据空白）。JSON null会以字符串"null"形式存储， 若以数字类型注册则会解析失败。

采集数量远少于发布数量​

  • 原因 这是设计上的正常现象。 驱动会以最后一个值覆盖消息，读取并非消费队列， 而是对最后一个值的轮询采样。只要broker的LAG为0，就说明已全部接收到。
  • 处理 如需全量采集，需要进行基于队列的重新设计，属于合同变更事项。

刚注册后旧数据大量涌入，或反而未能导入​

  • 原因 涉及Kafka的auto-offset方向（默认latest）。latest需要在创建消费者组之后发布才能捕获， 而**earliest**会一次性消费注册瞬间已堆积的现有消息。除这两个值以外都会悄无声息地降为latest。
  • 注意 这仅限于Kafka。MQTT没有offset概念——与之类似的位置是clean-session。
  • 处理 验证应以实时发布进行。

数据提取为0件但无任何错误日志​

  • 原因 jar冲突——重新打包的JSON库与标准库冲突，导致缺少必需的构造函数。
  • 处理 替换为标准jar，将冲突jar备份转移后清理缓存并重启。
  • 确认 正常状态是安静的成功。只要轮询线程存活、LAG为0且VALUE_NULL日志停止输出即为正常， 不会输出成功日志。

出现类型异常​

  • 症状 NumberFormatException或Invalid tag data type。
  • 原因 注册时将类型统一设为Integer。
  • 处理 按值的性质重新区分——Double用于电流·温度·电压·重量·速度·坐标，String用于报警·状态·区域·方向·颜色， Integer用于电池·错误代码。Edge标签类型与Platform类型必须一致。 即使数值以字符串形式传入， 只要声明类型正确就能被准确解析。

更改了元数据但未生效​

  • 原因 未执行缓存reload。
  • 处理 需同时重新读取三处——Platform服务器、OPC-UA插件、Edge。只要漏掉一处，一致性就会被破坏。 若重新注册OPC导致标签ID被重新发放，需清除Platform中残留的标签并停止再启动OPC以重新同步。

通过REST注册后驱动连broker都连不上​

  • 症状 看起来像「PLC连接timeout」，但TCP正常，连consumer group都没有创建。
  • 原因 OPC创建请求体中缺失必填字段，内部抛出异常导致地址映射扫描失败。 若通过界面注册，界面会自动补全，所以仅在REST路径下才会出问题。
  • 处理 填齐八个必填字段——opc_id · opc_name · opc_type · site_id · opc_agent_ip · opc_agent_port · timecycle · async。 同时确认地址表示法和offset方向。
  • 变更点 以前PUT会将未指定的字段清空，所以「删除后重新创建」是安全的。2026-07-20通过部分合并修复 —— 现在只有发送的字段会被更改。但也因此无法用null来清空字段。

ping通但采集为0​

  • 原因 ping正常、ARP也正常，但TCP端口是关闭的。 读取错误计数达480万，成功次数为0。
  • 处理 **属于PLC侧通信端口·模块处理范畴，**watchdog无法解决，应转交设备负责人处理。

查询最新值却返回旧数据​

  • 原因 SELECT * ... LIMIT 5是分区顺序，因此旧数据会先返回。实时存储本身是正常的。
  • 处理 使用WHERE tag_id=... ORDER BY timestamp DESC进行确认。

6. 资源耗尽 · 日志​

每30天就会同时爆发各种错误​

  • 症状 运行30天后，全方位错误爆发。

  • 原因 监控定时器每10秒尝试一次docker ping，若docker不存在，失败路径中有2个文件描述符不会被回收。 由于异常未被记录到日志中，因而悄无声息地累积。数字正好吻合——30.3天除以10秒为261,700次， 乘以2为523,400，而实测为523,690。

  • 处理 安装与正常对照设备相同版本的docker并固定下来。若仅重启，30天后仍会复发。

  • 确认

    P=$(pgrep -f catalina.startup.Bootstrap | head -1)
    ls /proc/$P/fd | wc -l      # 정상 ~600, 누수 시 50만+
    wc -l < /proc/net/unix      # 정상 ~200, 누수 시 50만+
    ls /var/run/docker.sock     # 없으면 누수 진행 확정
请勿将继发症状误诊为独立bug

/proc/stat失败、Mount point not found、JMX NPE、「打开的文件过多」、队列WAL异常 （采集数据丢失区间）、日志暴增，全部都是文件描述符耗尽所派生出的问题。 耗尽之前的日志中ERROR为0条。

线程·FD持续增加并发生OOM​

  • 原因 对已失效目标的无限重连。 目标处于ping正常但协议端口已失效的状态， 数十种OPC以1秒周期重连，每次尝试都会创建新客户端。实测每秒净增2.25个， 常驻线程中有76%由此产生。另一台设备上驱动线程增长至40,900个导致OOM， 采集停止了3天却连终止日志都没有，因而未被察觉。
  • 处理 未使用的OPC必须停止。 若PLC宕机也会重现相同的泄漏，长期运行的设备尤需注意。

同一日志堆积数万条​

  • 原因 轮询周期硬编码，没有关闭的设置项。
  • 处理 不要修改类代码，而是在日志配置中为对应package添加WARN级别logger进行抑制。

7. 部署 · 初始化​

不能在客户公司设备上留下安装痕迹​

  • 处理 不上传文件，而是通过标准输入投放脚本。

    ssh <호스트> 'bash -s' < install.sh

    服务器上完全不会生成安装文件本身。

  • 确认 临时目录中无残留，未生成备份文件，24小时内新生成的文件只有预期产出物。 备份原件保存在本地报告中。

一行安装命令返回404​

  • 原因 部署路径已改版，域名顶层不同。
  • 同时暴露的问题
    • 软链接会返回404——指针改用硬链接。
    • 以curl | bash方式执行时，脚本中的read会遇到EOF导致整体中断。通过连接终端解决。
    • 一个环节失败会导致后续防火墙、调优、SSL、服务注册全部被跳过，于是将该环节改为非必需。

将服务器重置为仅保留OS​

  • 处理顺序 先删除容器，再卸载引擎。 将是否存在重新配置源作为第0道安全保障， 若没有则中止。
绝对不要动防火墙

在远程连接中重置防火墙会导致SSH断开，没有控制台无法恢复。 重新配置脚本只会重新开放所需端口，不会关闭端口。

  • 故意不改动的内容 主机名·语言环境·时区·附属软件包。重新配置时会重新设置这些内容。

修改了server.host但数据方向未改变​

  • 原因 该设备采用的是pull方式。Platform会直接读取Edge的标签值API。即使更改Edge的push目标，方向也不会改变。
  • 处理 若要改由其他Platform接收，需在对方侧用Edge地址和密钥配置pull。

Edge与Platform版本不一致导致无法联动​

  • 症状 API server is not responding无限循环。端口全部开放，网络本身没有问题。
  • 原因 新版Platform只开放新API，而旧版Edge硬编码调用旧路径。必须先完成握手才能开始发布。
  • 处理 将Edge升级至与Platform相同的发行版本。 无法通过配置解决——握手逻辑已编译在代码中。
  • 令牌陷阱 保存与部署是两回事（需在界面上点击「部署」）。需要指定允许的IP， 公开ping返回200并不代表认证已通过。