跳转至

告警增强离线自测（alert-enrich-test.py）

位置：deploy/nfos/tools/alert-enrich-test.py ｜ 语言：python3 ｜ 是否需要 root：否

工具性质：离线自测（不联网、不写盘、不需要 root —— 源码 docstring 自述） 运行前提：仓库检出必须在场 —— 加载 deploy/nfos/monitoring/alert-enrich.py。可从任意位置运行（工具自动向上找到含 deploy/nfos 的祖先目录） 部署状态：随仓库检出运行，不部署到 /opt/Cy/services/system.d/nfos/

用途

对 deploy/nfos/monitoring/alert-enrich.py 做离线自测，覆盖地址口径与文本抽取的边界。

源码 docstring 的用法与覆盖点（逐字引用）：

    python3 .scratch/alert-enrich-test.py

覆盖：
  1. 公网/私网判定边界（含 RFC1918 内外、回环、链路本地、ULA、文档段、组播、mapped）
  2. 次数统计（同 rule / 同 IP；含“拉取失败 → None”）
  3. 缺失/异常输入不抛异常（None/空串/非 dict/坏 JSON/超长文本）
  4. 真实告警样例（WA-002 / EG-001 / RS-001 / AU-001）的地址与文本块

被测函数（按 ok(...) 断言逐项覆盖）：

函数 覆盖内容
classify_ip / is_public_ip / ip_mark / label_ip 26 组边界 IP（10/8、172.16-31、172.32、192.168、127、169.254、fc00::/fd00::、fe80::、::1、::、组播、::ffff: mapped、[...]、%eth0）与 9 组非法输入
count_same_rule / count_same_ip 同 rule / 同 IP（跨 rule、subject 内 IP）计数；None 入参 → None
parse_alerts 信封 {code, data}、裸数组、{data:{items}}、缺 data、字符串 → None
ip_from_dedup :ip: 段、兜底取 IP、无 IP → 空、IPv6
site_from_log_path / request_from_evidence 日志路径 → 域名、waf-blocked.log 标注、请求行提取
enrich_hit / enrich_plan 7+8 组畸形输入不抛异常；addr_block/extra 类型稳定；真实样例（WA-002 / EG-001 / RS-001 / AU-001 / 无 IP 命中）的地址与标记
enrich_plan 输出 逐条增强、保留 recover/active、enrich.alerts_available / alerts_count

末尾固定打印 检查项 <N>，失败 <M>，全通过时再打印 ALL_PASS。

典型场景

  • 改动 alert-enrich.py（地址判定、dedup_key 解析、addr_block 文案）之后的提交前回归；
  • 线上告警“内网/公网”标记反了、或 addr_block 里 IP 取错时，用它在本地复现并定位边界；
  • 前端同口径自测（ispublicip-test.js）的后端对照：两者覆盖同一份边界清单，便于确认前后端判定一致。

用法与参数

源码 docstring 给出的用法（逐字引用，.scratch/ 为升级前旧路径，本页按新位置书写）：

    python3 .scratch/alert-enrich-test.py

本工具不接受任何命令行参数：

参数 类型 默认值 说明
（无） — — 无 argparse、不读 sys.argv、不读环境变量；全部输入为源码内置用例

无参数时的默认行为：跑完第 1–4 组全部用例并打印结论。注意源码会先做一次 sys.stdout.reconfigure(encoding="utf-8", errors="replace")，以兼容 Windows 默认 GBK 控制台（否则打印 🌐/🏠 会 UnicodeEncodeError）。

示例

从仓库根目录执行：

python deploy/nfos/tools/alert-enrich-test.py

期望输出（实测：检查项 99、失败 0，末行 ALL_PASS）：

检查项 99，失败 0
ALL_PASS

中间会打印各分组（== 1. 公网/私网判定边界 == … == 4. 真实形态样例 ==）、逐项 ok ...，以及 WA-002 / EG-001 的 addr_block 文本块。

情形 期望退出码
全部通过（打印 检查项 N，失败 0 + ALL_PASS） 0
存在失败项（打印 检查项 N，失败 M 后逐条列出 FAIL） 1
被加载模块缺失 / 模块级代码抛异常 1（importlib 异常，Python traceback，非自检语义）

依赖与权限

  • 语言/版本：Python 3（#!/usr/bin/env python3）。
  • 第三方依赖：无，标准库 importlib.util / io / json / os / sys。
  • 仓库依赖：必需 —— 加载 <repo>/deploy/nfos/monitoring/alert-enrich.py；_nf_repo_root() 向上找第一个含 deploy/nfos 的祖先目录。
  • 权限：不需要 root、不需要写权限、不需要网络（纯离线）。

风险与注意事项

  • 纯离线只读：不联网、不写盘、不起服务；被测模块以 importlib 加载后只调用其纯函数。
  • 会执行被测模块的模块级代码：若 alert-enrich.py 将来在模块级加入写盘/联网/读环境变量的副作用，本自测会一并触发这些副作用（当前版本为纯函数定义 + 常量，无副作用）。
  • 断言是行为锁定：例如 classify_ip("203.0.113.77") == "public"（文档地址段按公网处理）、ip_mark 的空格与 emoji 文案（🌐公网 / 🏠内网）。有意修改这些口径时必须同步改本自测，否则会连续 FAIL。
  • 通过 importlib 直接按文件路径加载，不依赖包名/sys.path，因此重命名或移动 alert-enrich.py 会让本自测立即报错（这也是它的价值）。

回滚

本工具不部署到线上、不改线上系统，且不产出任何文件：

  • 无输出文件、无临时目录、无状态文件、无缓存目录；
  • 不改动 alert-enrich.py 或任何其它文件；
  • 无需清理。若只是运行过本自测，工作区比对结果应为空。