黑白名单

名单配置在 [filter] 块，按设备 MAC 过滤，每条可再限定端口。

两种模式

`list_mode`	含义
`whitelist`（默认，可写 `white`）	命中的设备不检测，其余照常检测；名单为空即检测全部
`blacklist`（可写 `black`）	只检测命中的设备，其余即使达阈值也不告警

白名单为空时等于不过滤，因此不需要单独的「不启用」开关。

写法

[filter]
list_mode = "blacklist"

# 该设备全部端口
[[filter.blacklist]]
mac = "aa:bb:cc:dd:ee:ff"

# 只检测指定端口（范围不足可能漏检）
[[filter.blacklist]]
mac = "11:22:33:44:55:66"
ports = [40000, 40001]

# 端口表达式：范围与斜杠列表可混用
[[filter.whitelist]]
mac = "22:33:44:55:66:77"
ports = ["40000-40010", "80/443"]

# 临时停用（不删除条目）
[[filter.whitelist]]
mac = "33:44:55:66:77:88"
enabled = false

# 为该设备启用全 UDP 端口封禁（需 [full_ban] mode = "device"）
[[filter.blacklist]]
mac = "60:21:01:1b:0a:23"
full_ban = true

# 为该设备启用 UPnP 拦截（需 [upnp] mode = "device"）
[[filter.blacklist]]
mac = "70:31:02:2c:1b:34"
upnp = true

字段	默认	说明
`mac`	—	必填，大小写不敏感
`ports`	空 = 全部端口	元素可为整数或端口表达式字符串
`enabled`	`true`	设为 `false` 可临时停用该条
`full_ban`	`false`	为该设备启用全 UDP 端口封禁，仅 `[full_ban] mode = "device"` 时生效
`upnp`	`false`	为该设备启用 UPnP 拦截，仅 `[upnp] mode = "device"` 时生效

端口表达式的陷阱

黑名单里配了 ports 却漏掉设备实际使用的端口，会导致漏检（缺少拦截）。启动时会就此告警：

警告：黑名单中 N 个条目配置了端口……

不确定时先不写 ports，让该设备全部端口都参与检测。

热重载行为

修改名单、条目 enabled / full_ban / upnp 标记或 list_mode 后，SIGHUP / POST /api/v1/reload 会：

同步名单，清除新排除设备 / 端口在 IPv4 与 IPv6 上的已有检测状态，并撤销对应端口封禁 ——无需等告警自然结束；
同步关联的全端口封禁与 UPnP 策略；
重启继承时也不会恢复这些已排除端口的告警与封禁。

启动日志

名单摘要会打在启动日志里，便于确认生效：

名单：黑名单（只检测名单内的 2 个设备）
名单：黑名单（只检测名单内的 2 个设备，其中 1 个仅限指定端口）
名单：白名单（名单内 2 个 MAC 不检测，其中 1 个仅限指定端口）

名单只能在配置文件中设置，没有对应的命令行参数。

与其他功能的关系

功能	依赖的名单方向
检测范围	黑名单 = 只检测名单内；白名单 = 名单内跳过
全 UDP 端口封禁（`device` 模式）	只对名单中 `full_ban = true` 的设备生效
UPnP 拦截	黑名单 = 只拦截名单内；白名单 = 拦截全部、仅放行名单内