NetAlertX New Devices 模板插件深度解析：新设备默认值配置与底层实现机制-平芜编程栈

后端
网络
运维
数据可视化

【免费下载链接】NetAlertX

Centralized network visibility and continuous asset discovery. Monitor devices, detect change, and stay aware across distributed networks.

项目地址：https://gitcode.com/gh_mirrors/ne/NetAlertX

点击查看免费下载

导读

NetAlertX 的newdev_template插件（New Devices）是一个"数据库条目型"核心模板插件：每当网络扫描发现一台此前从未出现过的新设备时，系统就会以该插件在Settings > New Devices中定义的默认值来初始化这条设备记录。本文将完整拆解该模板插件提供的全部配置项（忽略规则、名称清洗正则、设备字段默认值等），并深入 device_handling.py 与 name_resolution.py 的源码，说明这些设置如何在"新设备入库 → 名称解析 → 图标/类型推断 → 忽略过滤"的完整链路中被真正消费，帮助你在部署 NetAlertX 时精准控制新设备的接入行为。

插件定位与工作原理

newdev_template本身不执行任何扫描，也不产出设备对象，它是一个纯粹的"默认值模板"。其定位可以从 config.json 的头部声明中直接读出：

"template_type": "database-entry"：指明这是数据库条目模板类型；
"unique_prefix": "NEWDEV"：所有由它生成的设置项都以NEWDEV_为前缀写入Settings表；
"plugin_type": "core"：属于核心插件，随系统启用（"enabled": true）；
"data_source": "template"：数据源为模板，而非网络发现；
"show_ui": false：插件本身不在插件列表 UI 中展示（它只通过 Settings 页的 "New Devices" 分组呈现）。

从源码调用看，device_handling.py 中生成新设备记录的 SQL 会直接读取NEWDEV_*全局设置并注入到INSERT语句中（见 device_handling.py#L770-L786）；前端 deviceDetailsEdit.php 则在编辑设备时按setGroup == "NEWDEV"过滤、以NEWDEV_前缀映射到Devices表的字段（见 deviceDetailsEdit.php#L90-L93）。这就是"模板生成可编辑设置，再由 device.py 使用这些设置初始化新值"这一机制（README 的 Notes 所述）的完整实现闭环。

快速使用：进入设置页面

按 README 指引，只需进入Settings > New Devices（设置分组页）即可调整所有默认值。这里的每一项设置都对应NEWDEV_*键：

设置项（函数名）	默认值	说明
`ignored_MACs`	`[]`（空）	需要忽略的 MAC 列表，支持`%`通配符
`ignored_IPs`	`[]`（空）	需要忽略的 IP 列表，支持`%`/`_`通配符
`NAME_CLEANUP_REGEX`	12 条内置正则（base64 存储）	新设备名称清洗规则，按顺序执行
`IP_MATCH_NAME`	`true`	是否允许按 IP 猜测设备名
`replace_preset_icon`	`false`	是否用推断的厂商/设备图标覆盖预设图标
`devMac`/`devLastIP`	空	自动检测，不可编辑
`devName`	`(unknown)`	新设备默认名称；为`(unknown)`或`(name not found)`时尝试自动发现
`devIcon`	空	默认图标（含图标选择器与实时预览）
`devOwner`/`devType`/`devVendor`/`devGroup`/`devLocation`	空	所有者、类型、厂商、分组、位置的默认值（多为下拉选择）
`devComments`	空	默认备注（textarea）
`devFirstConnection`/`devLastConnection`/`devLastNotification`	空	自动检测，不可编辑（时间戳）
`devFavorite`	`0`	默认是否标记为收藏设备
`devStaticIP`	`0`	默认是否静态 IP
`devScan`	`1`	默认是否对该设备执行扫描
`devLogEvents`	`1`	默认是否记录设备事件
`devAlertEvents`	`1`	默认是否对设备事件告警（Down 与新设备通知默认总是发送，除非在`NTFPRCS_INCLUDED_SECTIONS`中取消勾选）
`devAlertDown`	`0`	默认是否在设备掉线时告警（受`NTFPRCS_alert_down_time`影响）
`devCanSleep`	`0`	默认是否允许设备在缺席小于`NTFPRCS_sleep_time`时显示为Sleeping
`devSkipRepeated`	`0`	重复通知抑制时长（小时）：`0`=全部通知，`1`=1h，`8`=8h，`24`=1天，`168`=1周
`devPresentLastScan`	`1`	默认上一次扫描是否在场
`devIsNew`	`1`	默认是否视为"新设备"（影响 New Devices 过滤器与列表展示，不影响通知）
`devIsArchived`	`0`	默认是否归档（归档且离线时从 My Devices 隐藏）
`devParentMAC`/`devParentRelType`/`devParentPort`	空 /`default`/`0`	网络拓扑父节点默认值（父 MAC、关系类型、端口）
`devSSID`/`devSite`/`devVlan`	空	无线 SSID、网络站点、VLAN 默认值
`devSyncHubNode`	空	Sync 节点名（启用 sync 插件后自动填充）
`devCustomProps`	内置"删除设备"动作	自定义属性的默认模板
`devFQDN`/`devPrimaryIPv4`/`devPrimaryIPv6`	空	自动检测，不可编辑（FQDN 可由`REFRESH_FQDN`自动刷新）
`devReqNicsOnline`	`0`	是否要求所有关联 NIC 在线才判定设备在线
`devForceStatus`	`dont_force`	强制状态：`online`/`offline`/`dont_force`（自动检测）

忽略规则：ignored_MACs 与 ignored_IPs

这是两个数组型设置，作用是从监控与告警中彻底剔除不需要的设备：被忽略的设备不会出现在任何 UI 列表和通知中。

通配符语义：描述文本明确指出%匹配任意字符序列（含空序列），_精确匹配单个字符。例如02:42:ac:%可过滤掉 Docker 容器（其 MAC 通常以02:42:ac开头）；192.168.3.%可过滤整个 IP 网段。
底层实现：过滤动作发生在扫描数据落库之前。exclude_ignored_devices 将NEWDEV_ignored_MACs、NEWDEV_ignored_IPs通过list_to_where("OR", ...)组装成LIKE条件，直接对CurrentScan表执行DELETE：

mac_condition = list_to_where("OR", "scanMac", "LIKE", get_setting_value("NEWDEV_ignored_MACs")) ip_condition = list_to_where("OR", "scanLastIP", "LIKE", get_setting_value("NEWDEV_ignored_IPs")) # DELETE FROM CurrentScan WHERE (scanMac LIKE ... OR scanLastIP LIKE ...)

注意：SQLite 的LIKE天然支持%与_通配符，与设置描述中的语义一致；若两列表均为空，则执行WHERE 1=1 AND 1=0的空条件保护，避免误删整表（见 device_handling.py#L84）。

名称清洗：NAME_CLEANUP_REGEX 与 IP_MATCH_NAME

新设备名称质量直接影响列表可读性与后续匹配，NetAlertX 通过两层机制处理：

1. 名称清洗正则（NAME_CLEANUP_REGEX）

数组中每条正则按顺序对设备名执行re.sub(rgx, "", name)替换为空串。内置 12 条默认正则（config.json 中以 base64 存储，解码后如下）：

\._airplay # 去除 mDNS 服务类型后缀 _airplay \._tcp # 去除 ._tcp \.localdomain # 去除 .localdomain \.local # 去除 .local \._esphomelib # 去除 ._esphomelib \._googlecast # 去除 ._googlecast \.lan # 去除 .lan \.home\.arpa # 去除 .home.arpa \.home # 去除 .home -[a-fA-F0-9]{32} # 去除 32 位十六进制后缀（如某些随机主机名） #.* # 去除 # 及之后内容 \.$ # 去除结尾点号

执行逻辑位于 NameResolver.clean_device_name：按序遍历正则列表执行替换，随后强制re.sub(r"\.$", "", name)收尾，并修复". (IP match)"间隔问题。这是列表型设置，可自由增删——例如可加入-iPhone$之类的正则来清理移动设备名。

2. 按 IP 匹配名称（IP_MATCH_NAME）

默认开启（true）。当按 MAC 在Plugins_Objects表中找不到名称时，若开启此项，则再按 IP（objectSecondaryId）尝试匹配（见 name_resolution.py#L36-L47）。该方案在 IP 基本静态的网络中有效；匹配成功时名称会附加(IP match)标记以示来源。若你的网络大量使用 DHCP 且地址频繁变动，可关闭此项以减少误匹配。

新设备入库流程：NEWDEV_* 默认值的消费位置

理解"模板默认值"如何落地，需要看新设备创建主流程。位于 update_and_insert_devices（源码约 device_handling.py#L744-L909）：

收集候选：从CurrentScan中选取scanCreatesDevice = 1且 MAC 非空的记录；
拼接默认值：将NEWDEV_devAlertEvents、NEWDEV_devAlertDown、NEWDEV_devPresentLastScan、NEWDEV_devIsArchived、NEWDEV_devIsNew、NEWDEV_devSkipRepeated、NEWDEV_devScan、NEWDEV_devOwner、NEWDEV_devFavorite、NEWDEV_devGroup、NEWDEV_devComments、NEWDEV_devLogEvents、NEWDEV_devLocation、NEWDEV_devCustomProps、NEWDEV_devParentRelType、NEWDEV_devReqNicsOnline等设置值经safe_int/sanitize_SQL_input处理后注入INSERT（见 device_handling.py#L770-L786）；
安静模式（quiet）：若某 MAC 的扫描行存在scanNotificationMode = 'quiet'，则改用newDevDefaults_quiet变体，将告警相关默认值硬编码为0，从而在新设备整个生命周期内静默抑制 Down/Disconnected 通知（见 device_handling.py#L788-L804）；
类型回退：扫描未提供类型时回退到NEWDEV_devType（见 device_handling.py#L887-L889）；
父节点守卫：NEWDEV_devParentMAC指向的 MAC 若已不存在（设备被删除），则视为未设置，避免向新设备注入悬空引用（见 device_handling.py#L834-L848）。

图标与类型推断：replace_preset_icon 的取舍

replace_preset_icon（Overwrite Preset Icon）默认关闭。其消费逻辑在 update_icons_and_types：

开启时：查询范围扩大为devIcon为空或等于默认图标NEWDEV_devIcon的设备，随后用guess_icon()依据厂商、MAC、IP、名称推断更贴合的图标并覆盖之；
关闭时：仅对图标为空（NULL 等价）的设备做推断，保留手动设置的预设图标NEWDEV_devIcon。

config.json 的描述给出了一条重要警告：若开启此项，请避免手动把该图标分配给设备，因为它可能被自动替换。同理，devType为空时由guess_type()按相同维度推断（见 device_handling.py#L456-L477）。注意devType描述提到：NETWORK_DEVICE_TYPES中自定义的网络设备类型不会自动加入下拉选项，需要在该设备上通过+按钮手动添加。

前端编辑联动：设备详情页如何使用这些设置

模板设置同时也是设备详情编辑页的字段来源：

编辑页通过filterColumn: "setGroup", filterValue: "NEWDEV"只加载 NEWDEV 分组设置（见 deviceDetailsEdit.php#L90-L93）；
保存时以NEWDEV_devName、NEWDEV_devOwner、NEWDEV_devType、NEWDEV_devVendor、NEWDEV_devIcon等 ID 读取输入并映射回Devices表字段（见 deviceDetailsEdit.php#L435-L439）；
NEWDEV_devScan与NEWDEV_devPresentLastScan属于隐藏字段（见 deviceDetailsEdit.php#L111）；
新增设备（mac == "new"）时禁用自动检测类字段（devLastNotification、devFirstConnection、devLastConnection、devFQDN、devPrimaryIPv4、devPrimaryIPv6、devSyncHubNode），而已有设备则额外禁用devMac、devLastIP的编辑（见 deviceDetailsEdit.php#L113）。

因此，修改模板默认值不仅影响未来发现的新设备，也会作为设备编辑表单的初始值出现。此外 app.css 中隐藏了设置页里NEWDEV插件的若干"添加选项/复制图标"按钮，避免在模板层面误操作。

结语与最佳实践

newdev_template是 NetAlertX "新设备策略"的总开关，配置建议归纳如下：

先配忽略规则：用02:42:ac:%类通配符过滤 Docker 容器、用192.168.3.%过滤测试网段，从源头减少噪声设备；
保留默认名称清洗正则：它们专门针对 mDNS/多播设备名后缀，若手动替换请务必保留\.local、\.lan等高频项；
按需开启图标覆盖：想让新设备自动获得厂商图标可开启replace_preset_icon，但需接受手动图标可能被覆盖；
审计通知默认值：devAlertDown（默认关）、devSkipRepeated（默认 0=全部通知）与NTFPRCS_alert_down_time、NTFPRCS_sleep_time、NTFPRCS_INCLUDED_SECTIONS联动，决定新设备上线后的告警行为；
静态 IP 环境可保留IP_MATCH_NAME，动态 DHCP 环境建议评估误匹配风险后关闭。