NetAlertX 插件故障排查完全指南:读懂 `app.log`、定位数据映射问题与源码级排错
NetAlertX 插件故障排查完全指南:读懂 app.log、定位数据映射问题与源码级排错
本指南面向 NetAlertX 用户与插件开发者,围绕官方调试文档 docs/DEBUG_PLUGINS.md 的核心内容展开:当插件没有产生预期数据、设备未出现在列表、或通知异常时,如何通过开启调试日志、解读 app.log 中特定区段、核对插件事件计数,快速定位问题根因。读完本指南,你将掌握一套从「日志关键词搜索」到「源码级验证」的完整插件排错流程。
开始排错之前,请务必先在 Settings 中设置正确的调试级别与
LOG_LEVEL,具体见 docs/DEBUG_TIPS.md。这是后续所有排查步骤生效的前提。
一、前置条件:开启调试日志
插件的绝大部分问题都体现在日志中,而默认日志级别不足以暴露细节。按照 docs/DEBUG_TIPS.md 的建议,排查前先做两件事:
- 确认已按插件各自的安装说明完成配置(如 API Key、数据库路径、子网列表等),配置错误是插件无输出的最常见原因。
- 在 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。
三、潜在问题类型:排错时的思维框架
原文档将插件问题归纳为三类,排查时按此顺序逐项排除:
- 代码 Bug——插件脚本自身的逻辑错误;
- 意外输入——例如设备名称、厂商字符串中的特殊字符导致映射异常(见下文「输入数据被净化」小节);
- 外部依赖变化——插件所依赖的命令行工具(如
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):
CMD与Executing:显示插件最终要执行的 SQL 或命令。注意{s-quote}是单引号占位符,执行前会被替换为'(源码中q = set_CMD.replace("{s-quote}", "'"))。这里要仔细核对:查询是否连接到了正确的表(EXTERNAL_PIHOLE)、过滤条件是否符合预期。若出现DB_PATH setting ... Did you mount it correctly?或ATTACH DATABASE failed错误,说明外部数据库未正确挂载。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。SUCCESS, received 2 entries:SQL 查询成功返回 2 行数据;随后sqlParam entries打印出即将写入Plugins_Objects/Plugins_Events的原始参数元组——这是核对「字段顺序是否错位」的最佳位置,例如确认watchedValue1拿到的是 IP、watchedValue2是查询时间等。Processing : PIHOLE之后的计数区段:见下一节详细解读。Mapping objects to database table: CurrentScan:插件配置了mapped_to_table: "CurrentScan",因此数据会被映射插入扫描结果表。日志会打印实际的INSERT into CurrentScan (...)语句与sqlParams for mapping参数——当设备没有出现在 Devices 列表时,重点检查这里:映射的列是否齐全、scanSourcePlugin是否被正确填入(映射机制见 docs/PLUGINS_DEV.md 的数据库映射章节)。- 末尾的
[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 表格中(下表展示了插件对象列表,与日志中的统计一一对应):
六、分享应用状态:导出 Devices 与 CurrentScan 表内容用于求助
某些问题只靠插件自身的日志片段无法判断,需要连同主应用的设备表与扫描表状态一起分析。原文档给出的标准流程(与 docs/DEBUG_TIPS.md 一致):
- 在 Settings 中把
LOG_LEVEL设为trace(信息到手后立即关闭,避免日志文件暴涨); - 等待问题复现;
- 在日志中搜索分隔行
================ DEVICES table content ================; - 在日志中搜索分隔行
================ CurrentScan table content ================; - 将(脱敏后的)输出粘贴到新 issue 的描述中;若含敏感数据,可发送至
support@netalertx.com邮箱; - 排查结束后将
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值与期望的触发场景一致。
八、排错速查清单
LOG_LEVEL是否已设为trace?- 插件专属安装步骤(API Key、DB_PATH、子网)是否完成?
app.log中是否存在[Scheduler] run for <PREFIX>: YES?没有则查RUN/RUN_SCHD。- 是否存在
Wrong number of input values, must be 9 or 13?有则修脚本/查询的列数。 SUCCESS, received N entries的 N 是否符合预期?不符则查上游数据源与过滤条件。objects_to_insert/objects_to_update是否符合预期?不符则对照Plugins_Objects已有记录分析状态分布。Mapping objects to database table段的 INSERT 语句与参数是否完整?scanSourcePlugin是否缺失?- 仍无法定位时,用
trace级别导出DEVICES table content与CurrentScan table content,随问题附上(注意脱敏)。
上述所有日志关键词均可在 server/scheduler.py、server/plugin.py 与 server/plugins/plugin_helper.py 中直接检索验证,排查过程完全可复现。
