NetAlertX 插件故障排查完全指南:读懂 `app.log`、定位数据映射问题与源码级排错

原创2026-09-28 12:43:202,285 阅读
文章标签:网络后端插件系统运维告警前端可观测性

NetAlertX 插件故障排查完全指南:读懂 app.log、定位数据映射问题与源码级排错

本指南面向 NetAlertX 用户与插件开发者,围绕官方调试文档 docs/DEBUG_PLUGINS.md 的核心内容展开:当插件没有产生预期数据、设备未出现在列表、或通知异常时,如何通过开启调试日志、解读 app.log 中特定区段、核对插件事件计数,快速定位问题根因。读完本指南,你将掌握一套从「日志关键词搜索」到「源码级验证」的完整插件排错流程。

开始排错之前,请务必先在 Settings 中设置正确的调试级别与 LOG_LEVEL,具体见 docs/DEBUG_TIPS.md。这是后续所有排查步骤生效的前提。

一、前置条件:开启调试日志

插件的绝大部分问题都体现在日志中,而默认日志级别不足以暴露细节。按照 docs/DEBUG_TIPS.md 的建议,排查前先做两件事:

  1. 确认已按插件各自的安装说明完成配置(如 API Key、数据库路径、子网列表等),配置错误是插件无输出的最常见原因。
  2. 在 Settings → Core 中把 LOG_LEVEL 提升到 trace——这是最高日志级别,会输出本文后面要解读的所有关键调试行。排查完成后务必降回 debug 或更低,因为 trace 级别会产生非常大的日志文件。

DEBUG_TIPS 还提供了几个容器场景下的辅助手段:不使用 -d 参数在前台运行容器以直接看到崩溃报错、先验证 _dev 开发镜像是否已修复问题(操作前请备份数据库与配置)、在 compose 文件中将 restart 策略设为 no 避免自动重启掩盖错误,以及用非持久化挂载临时目录排除宿主机权限问题。

二、插件数据流概览:插件如何把数据交给主应用

理解日志之前,先明确插件向 NetAlertX 主应用交付数据的两种方式(原文定义):

  • 方式一:SQL 查询——插件通过 app-db-query 或 sqlite-db-query 两种数据源直接查询数据库(后者会把外部 SQLite 文件以 ATTACH DATABASE ... AS EXTERNAL_<PREFIX> 方式挂载后查询,见 server/plugin.py 中 execute_plugin 的实现)。
  • 方式二:脚本执行——插件运行 CMD 命令(如 python3 /app/server/plugins/xxx/script.py),脚本将结果写入插件日志目录下的 last_result.<PREFIX>.log 文件(插件日志目录为 app/log/plugins/,容器内实际路径以 logPath + "/plugins" 计算)。

脚本输出的每一行必须符合数据契约:以 | 分隔,9 列(必需)或 13 列(含 4 个可选帮助列),列顺序为 objectPrimaryId|objectSecondaryId|DateTime|watchedValue1|watchedValue2|watchedValue3|watchedValue4|Extra|ForeignKey。plugin_helper.Plugin_Object.write()(见 server/plugins/plugin_helper.py)正是按这个格式生成结果行。主程序读取结果文件时,会过滤掉不含 | 的行,并严格校验列数必须是 9 或 13,否则打印 Wrong number of input values, must be 9 or 13 并跳过该行(server/plugin.py)。列数错误是插件「静默无输出」的典型原因之一。

插件系统的整体架构与配置细节可参考 docs/PLUGINS_DEV.md。

三、潜在问题类型:排错时的思维框架

原文档将插件问题归纳为三类,排查时按此顺序逐项排除:

  1. 代码 Bug——插件脚本自身的逻辑错误;
  2. 意外输入——例如设备名称、厂商字符串中的特殊字符导致映射异常(见下文「输入数据被净化」小节);
  3. 外部依赖变化——插件所依赖的命令行工具(如 fping、nmap)或上游 API 改变了输出格式,导致解析失败。

四、第一步定位:在 app.log 中搜索 [Scheduler] run for PLUGINNAME: YES

插件是否被调度器实际执行,是排查的第一道分水岭。在 app.log 中搜索形如 [Scheduler] run for PLUGINNAME: YES 的日志行——例如 ICMP 插件就搜索 [Scheduler] run for ICMP: YES。

这行日志由调度器源码直接产生:server/scheduler.py 的 runScheduleCheck() 中,当当前时间已超过上次记录的下次调度时间时输出 [Scheduler] run for {self.service}: YES,否则输出 NO。因此:

  • 若搜索不到 YES,说明插件根本没有被触发——应检查该插件的 RUN 设置(disabled / once / schedule 等)与 RUN_SCHD 定时表达式;
  • 若出现 YES 但后续没有数据落库,则问题在插件执行或数据解析阶段,继续往下看。

原文档特别强调:如果你的问题与插件相关,却不在 issue 中附带包含这类日志的片段,维护者无法协助定位。请务必随问题附上对应插件的日志区段。

ICMP 日志示例解读

以下为 ICMP 插件(基于 fping,实现见 server/plugins/icmp_scan/icmp.py)的典型调试输出:

20:39:04 [Scheduler] run for ICMP: YES
20:39:04 [ICMP] fping skipping 192.168.1.124 : [2], timed out (NaN avg, 100% loss)
20:39:04 [ICMP] adding 192.168.1.123 from 192.168.1.123 : [2], 64 bytes, 20.1 ms (8.22 avg, 0% loss)
20:39:04 [ICMP] fping skipping 192.168.1.157 : [1], timed out (NaN avg, 100% loss)
20:39:04 [ICMP] adding 192.168.1.79 from 192.168.1.79  : [2], 64 bytes, 48.3 ms (60.9 avg, 0% loss)
20:39:04 [ICMP] fping skipping 192.168.1.128 : [2], timed out (NaN avg, 100% loss)
20:39:04 [ICMP] fping skipping 192.168.1.129 : [2], timed out (NaN avg, 100% loss)

解读要点:

  • adding <ip> 表示该 IP 响应了 ping,进入结果列表([2] 为 fping 的返回状态码,20.1 ms 为本次往返时延,8.22 avg 为平均值,0% loss 为丢包率);
  • fping skipping <ip> 表示超时(timed out、NaN avg、100% loss),该 IP 被跳过;
  • 若大量 IP 全部 skipping,优先怀疑:子网/接口配置(如 192.168.1.0/24 --interface=eth1 这种带 --interface 的条目是否正确,解析逻辑见 plugin_helper.parse_scan_subnets())、防火墙放行、或 fping 二进制是否缺失。

五、第二步深读:PIHOLE 插件完整调试日志逐段拆解

SQL 查询型插件(如 PiHole 设备同步)的日志更为完整,下面这段是官方文档给出的 PIHOLE 示例,其中 🔻 与 🔺 之间的区段是排错的关键(箭头仅用于本文高亮,实际日志中并不存在):

17:31:05 [Scheduler] run for PIHOLE: YES
17:31:05 [Plugin utils] ---------------------------------------------
17:31:05 [Plugin utils] display_name: PiHole (Device sync)
17:31:05 [Plugins] CMD: SELECT n.hwaddr AS objectPrimaryId, {s-quote}null{s-quote} AS objectSecondaryId, datetime() AS DateTime, na.ip  AS watchedValue1, n.lastQuery AS watchedValue2, na.name AS watchedValue3, n.macVendor AS watchedValue4, {s-quote}null{s-quote} AS Extra, n.hwaddr AS ForeignKey FROM EXTERNAL_PIHOLE.Network AS n LEFT JOIN EXTERNAL_PIHOLE.Network_Addresses AS na ON na.network_id = n.id WHERE n.hwaddr NOT LIKE {s-quote}ip-%{s-quote} AND n.hwaddr is not {s-quote}00:00:00:00:00:00{s-quote}  AND na.ip is not null
17:31:05 [Plugins] setTyp: subnets
17:31:05 [Plugin utils] Flattening the below array
17:31:05 ['192.168.1.0/24 --interface=eth1']
17:31:05 [Plugin utils] isinstance(arr, list) : False | isinstance(arr, str) : True
17:31:05 [Plugins] Resolved value: 192.168.1.0/24 --interface=eth1
17:31:05 [Plugins] Convert to Base64: True
17:31:05 [Plugins] base64 value: b'MTkyLjE2OC4xLjAvMjQgLS1pbnRlcmZhY2U9ZXRoMQ=='
17:31:05 [Plugins] Timeout: 10
17:31:05 [Plugins] Executing: SELECT n.hwaddr AS objectPrimaryId, 'null' AS objectSecondaryId, datetime() AS DateTime, na.ip  AS watchedValue1, n.lastQuery AS watchedValue2, na.name AS watchedValue3, n.macVendor AS watchedValue4, 'null' AS Extra, n.hwaddr AS ForeignKey FROM EXTERNAL_PIHOLE.Network AS n LEFT JOIN EXTERNAL_PIHOLE.Network_Addresses AS na ON na.network_id = n.id WHERE n.hwaddr NOT LIKE 'ip-%' AND n.hwaddr is not '00:00:00:00:00:00'  AND na.ip is not null
🔻
17:31:05 [Plugins] SUCCESS, received 2 entries
17:31:05 [Plugins] sqlParam entries: [(0, 'PIHOLE', '01:01:01:01:01:01', 'null', 'null', '2023-12-25 06:31:05', '172.30.0.1', 0, 'aaaa', 'vvvvvvvvv', 'not-processed', 'null', 'null', '01:01:01:01:01:01'), (0, 'PIHOLE', '02:42:ac:1e:00:02', 'null', 'null', '2023-12-25 06:31:05', '172.30.0.2', 0, 'dddd', 'vvvvv2222', 'not-processed', 'null', 'null', '02:42:ac:1e:00:02')]
17:31:05 [Plugins] Processing        : PIHOLE
17:31:05 [Plugins] Existing objects from Plugins_Objects: 4
17:31:05 [Plugins] Logged events from the plugin run    : 2
17:31:05 [Plugins] pluginEvents      count: 2
17:31:05 [Plugins] pluginObjects     count: 4
17:31:05 [Plugins] events_to_insert  count: 0
17:31:05 [Plugins] history_to_insert count: 4
17:31:05 [Plugins] objects_to_insert count: 0
17:31:05 [Plugins] objects_to_update count: 4
17:31:05 [Plugin utils] In pluginEvents there are 2 events with the status "watched-not-changed"
17:31:05 [Plugin utils] In pluginObjects there are 2 events with the status "missing-in-last-scan"
17:31:05 [Plugin utils] In pluginObjects there are 2 events with the status "watched-not-changed"
17:31:05 [Plugins] Mapping objects to database table: CurrentScan
17:31:05 [Plugins] SQL query for mapping: INSERT into CurrentScan ( "scanMac", "scanLastIP", "scanLastQuery", "scanName", "scanVendor", "scanSourcePlugin") VALUES ( ?, ?, ?, ?, ?, ?)
17:31:05 [Plugins] SQL sqlParams for mapping: [('01:01:01:01:01:01', '172.30.0.1', 0, 'aaaa', 'vvvvvvvvv', 'PIHOLE'), ('02:42:ac:1e:00:02', '172.30.0.2', 0, 'dddd', 'vvvvv2222', 'PIHOLE')]
🔺
17:31:05 [API] Update API starting
17:31:06 [API] Updating table_plugins_history.json file in /api

逐段含义如下(对应源码逻辑见 server/plugin.py 的 plugin_param、execute_plugin、process_plugin_events):

  1. CMD 与 Executing:显示插件最终要执行的 SQL 或命令。注意 {s-quote} 是单引号占位符,执行前会被替换为 '(源码中 q = set_CMD.replace("{s-quote}", "'"))。这里要仔细核对:查询是否连接到了正确的表(EXTERNAL_PIHOLE)、过滤条件是否符合预期。若出现 DB_PATH setting ... Did you mount it correctly? 或 ATTACH DATABASE failed 错误,说明外部数据库未正确挂载。
  2. setTyp / Resolved value / Convert to Base64 / base64 value:SQL 查询的返回结果会被拼装为命令参数;setTyp: subnets 表示该参数来自 SUBNETS 设置(类型为 array)。Convert to Base64: True 说明该参数经过 Base64 编码传递(plugin_param 中 base64 标记触发),日志中的 b'MTky...' 是编码后的值,解码即 192.168.1.0/24 --interface=eth1。Timeout: 10 是本次执行的 RUN_TIMEOUT。
  3. SUCCESS, received 2 entries:SQL 查询成功返回 2 行数据;随后 sqlParam entries 打印出即将写入 Plugins_Objects / Plugins_Events 的原始参数元组——这是核对「字段顺序是否错位」的最佳位置,例如确认 watchedValue1 拿到的是 IP、watchedValue2 是查询时间等。
  4. Processing : PIHOLE 之后的计数区段:见下一节详细解读。
  5. Mapping objects to database table: CurrentScan:插件配置了 mapped_to_table: "CurrentScan",因此数据会被映射插入扫描结果表。日志会打印实际的 INSERT into CurrentScan (...) 语句与 sqlParams for mapping 参数——当设备没有出现在 Devices 列表时,重点检查这里:映射的列是否齐全、scanSourcePlugin 是否被正确填入(映射机制见 docs/PLUGINS_DEV.md 的数据库映射章节)。
  6. 末尾的 [API] Update API starting 表示数据已成功落库并触发 API 端点更新,是整条链路走通的标志。

事件计数日志的含义

在 🔻 与 🔺 之间有一段「插件产生多少事件」的统计,这是排错时信息量最大的部分:

17:31:05 [Plugins] Existing objects from Plugins_Objects: 4
17:31:05 [Plugins] Logged events from the plugin run    : 2
17:31:05 [Plugins] pluginEvents      count: 2
17:31:05 [Plugins] pluginObjects     count: 4
17:31:05 [Plugins] events_to_insert  count: 0
17:31:05 [Plugins] history_to_insert count: 4
17:31:05 [Plugins] objects_to_insert count: 0
17:31:05 [Plugins] objects_to_update count: 4

对应源码(server/plugin.py process_plugin_events)的含义:

日志字段 含义 排查提示
Existing objects from Plugins_Objects 数据库中该插件已有的对象数(SELECT * FROM Plugins_Objects WHERE plugin = '<PREFIX>') 若为 0 而预期有数据,说明此前从未成功落库
Logged events from the plugin run 本次运行解析出的行数(即 SUCCESS, received N entries 的 N) 若为 0,说明查询/脚本无有效输出
pluginEvents count 本次事件对象总数 与上一行应一致
pluginObjects count 合并后对象总数 约等于已有对象 + 新增
events_to_insert count 触发通知的事件数 取决于 <PREFIX>_REPORT_ON 设置
history_to_insert count 本次状态真正发生变化、写入历史表的对象数 全部无变化时为 0
objects_to_insert count 新发现、需插入的对象数 长期为 0 说明无新设备
objects_to_update count 已存在、需更新的对象数 与已有对象数接近属正常

紧随其后的 In pluginEvents/pluginObjects there are N events with the status "..." 说明了状态分布(new、watched-not-changed、missing-in-last-scan 等)。例如示例中 2 个对象 missing-in-last-scan,意味着 PiHole 侧不再能看到它们——可能是上游数据消失,而非 NetAlertX 的问题。

这些计数若格式正确,会同步呈现在 UI 的 Plugins 表格中(下表展示了插件对象列表,与日志中的统计一一对应):

NetAlertX Plugins 表格中 PIHOLE 插件对象统计

六、分享应用状态:导出 Devices 与 CurrentScan 表内容用于求助

某些问题只靠插件自身的日志片段无法判断,需要连同主应用的设备表与扫描表状态一起分析。原文档给出的标准流程(与 docs/DEBUG_TIPS.md 一致):

  1. 在 Settings 中把 LOG_LEVEL 设为 trace(信息到手后立即关闭,避免日志文件暴涨);
  2. 等待问题复现;
  3. 在日志中搜索分隔行 ================ DEVICES table content ================;
  4. 在日志中搜索分隔行 ================ CurrentScan table content ================;
  5. 将(脱敏后的)输出粘贴到新 issue 的描述中;若含敏感数据,可发送至 support@netalertx.com 邮箱;
  6. 排查结束后将 LOG_LEVEL 恢复为 debug 或更低。

这两张表分别反映设备主数据与最近一次扫描的原始结果,能有效区分「插件确实产出了数据但主应用未吸收」与「数据从未进入扫描流程」两种场景。

七、来自源码的额外排查要点

结合本仓库实现,再补充几个原文之外、实战中高频踩坑的点:

  • RUN_TIMEOUT 是子进程的硬性 kill 超时,而非单次请求预算:run_plugin() 使用 subprocess.check_output(..., timeout=set_RUN_TIMEOUT)(server/plugin.py),超时后插件会被强制终止且结果文件尚未写出,表现为「整个运行被静默丢弃」。脚本内有多个串行网络调用时,应对配置声明的已知长度列表使用 config.json 的 "timeoutMultiplier": true 参数(参见 server/plugins/arp_scan/config.json 的 subnets 示例),或对运行时变长列表使用 plugin_helper.per_item_timeout()(server/plugins/plugin_helper.py)均分预算。
  • 输入数据会被默认净化:plugin_object_class.__init__ 会对所有插件来源字段执行 sanitize_plugin_text(),剥离 HTML 标签定界符(<、>)与控制字符(server/plugins/plugin_helper.py)。若设备名含特殊字符导致显示/匹配异常,先确认是否被净化,日志中会出现 sanitized (HTML/control chars stripped) 提示;确需保留原始文本的列才在 config.json 中声明 "allow_raw_text": true,且仅限 textarea_readonly 这类不会被当作 HTML 渲染的类型(规范见 docs/PLUGINS_DEV.md)。
  • 无效状态值会直接抛异常:plugin_object_class 只接受 exists、watched-changed、watched-not-changed、new、not-processed、missing-in-last-scan 六种状态,其余值会触发 ValueError,可通过日志中的 Invalid status value for plugin object 定位。
  • RUN 设置决定了触发方式:disabled / once / schedule 之外,还有 always_after_scan、before_name_updates、on_new_device 等触发时机(见 docs/PLUGINS_DEV.md 保留设置表)。排查「该跑没跑」时,先确认 RUN 值与期望的触发场景一致。

八、排错速查清单

  1. LOG_LEVEL 是否已设为 trace?
  2. 插件专属安装步骤(API Key、DB_PATH、子网)是否完成?
  3. app.log 中是否存在 [Scheduler] run for <PREFIX>: YES?没有则查 RUN / RUN_SCHD。
  4. 是否存在 Wrong number of input values, must be 9 or 13?有则修脚本/查询的列数。
  5. SUCCESS, received N entries 的 N 是否符合预期?不符则查上游数据源与过滤条件。
  6. objects_to_insert / objects_to_update 是否符合预期?不符则对照 Plugins_Objects 已有记录分析状态分布。
  7. Mapping objects to database table 段的 INSERT 语句与参数是否完整?scanSourcePlugin 是否缺失?
  8. 仍无法定位时,用 trace 级别导出 DEVICES table content 与 CurrentScan table content,随问题附上(注意脱敏)。

上述所有日志关键词均可在 server/scheduler.py、server/plugin.py 与 server/plugins/plugin_helper.py 中直接检索验证,排查过程完全可复现。

登录后查看全文
NetAlertX