NATLAN Docs

外观

flap 观测与处置 ​

本文是互联抖动（BGP flap）的一线操作手册：怎么看榜、怎么定位根因、怎么处置、怎么撤销。检测算法与打分原理见 ../internals/flap-detection.md。

设计原则：检测层只告警、不自动抑制。所有处置动作由操作员显式触发、声明式下发（走 DesiredState 闭环）、可撤销，且挂在 /admin 前缀下全程进审计日志。

示例基址省略 https://api.natlan.io/api/v1；/ui/* 与 /admin/* 均需 admin 凭据。各端点的参数细节见 ../reference/api.md。

观测：从榜单到根因 ​

看什么端点说明
会话级抖动榜GET /ui/fleet/bgp-flapsP0：从快照推导的 BGP 会话翻动衰减分；单节点视图 GET /ui/nodes/{id}/bgp-flaps
前缀级抖动榜GET /ui/fleet/prefix-flapsP1：flapfeed 喂送的前缀 churn 衰减分；?group=prefix 切前缀优先形状；榜行内嵌根因定位结果
对端烈度榜GET /ui/fleet/flap-peers按对端 AS 聚合的烈度排行；单对端详情（rate / duration 时序）GET /ui/fleet/flap-peers/{asn}
时序仪表GET /ui/fleet/flap-statsfleet 级抖动率时序 + gauge（P90 截尾）
告警事件流GET /ui/fleet/flap-alertsP2：边沿触发的历史层（cron 每分钟评估），游标分页
根因定位GET /ui/fleet/prefix-flaps/localizeV2 根因区判别，按 confidence 降序

Web UI 的 flap 页面即以上端点的可视化（见 web-ui.md）。

告警线与榜单线分层：前缀衰减分 ≥ 20 上榜标黄（观察线），≥ 100 触发告警开单（处置线）。阈值可调，见 ../reference/configuration.md 的 [flap] 段 / FLAP_* vars。

根因区怎么读 ​

定位器把每条持续抖动的前缀判入四个根因区之一：

根因区含义可处置性
origin抖动源于前缀起源 AS（AS_PATH 末跳）高可信时间稳定，适合 prefix-block
path抖动源于路径中段某条链路（AS-path prepend 已折叠，避免误点名）通常不在本网处置范围；可联系对应网络或接受
near信号指向本节点与直接对端之间（P0 会话级信号门控）先查本端：underlay、MTU 黑洞、对端会话状态——near 是诚实的低置信过渡区，随证据积累会向 origin/path 收敛
moas前缀多起源（MOAS），归因不唯一逐起源分析

处置决策以 confidence 高的 origin/path 判定为依据；near 低置信时不要急于对外处置。

处置动作 ​

当前生效的处置汇总（各节点拒收前缀 + 全部禁用会话）：

bash
curl -s $BASE/admin/fleet/mitigations

拒收前缀（prefix-block / prefix-unblock） ​

把前缀写进目标节点 base_template.bird.blocked_prefixes（字段级合并），materialize 透传进 DesiredState，agent 渲染进 eBGP 导入过滤器精确匹配 reject。幂等——已拒收的节点跳过。

bash
# 缺省 fleet 级（全部未退役节点）；金丝雀可先只下发单节点
curl -s -X POST $BASE/admin/fleet/mitigations/prefix-block \
  -H 'Content-Type: application/json' \
  -d '{"prefix": "172.20.x.0/24"}'                       # 或 {"prefix": "...", "nodes": ["tpe1"]}

# 撤销（缺省清全部节点）
curl -s -X POST $BASE/admin/fleet/mitigations/prefix-unblock \
  -H 'Content-Type: application/json' -d '{"prefix": "172.20.x.0/24"}'

非法前缀 422（零压缩 / 掩码折叠后校验）；指定了未知节点 404、退役节点 409。

断开 / 恢复对端（peer-disable / peer-enable） ​

按对端 AS 把全部 eBGP 会话置 enabled=false：BIRD 摘除协议，WireGuard 隧道保留，恢复即秒级重建会话。幂等；该 AS 无会话时 404。

bash
curl -s -X POST $BASE/admin/fleet/mitigations/peer-disable \
  -H 'Content-Type: application/json' -d '{"asn": 4242423999}'

curl -s -X POST $BASE/admin/fleet/mitigations/peer-enable \
  -H 'Content-Type: application/json' -d '{"asn": 4242423999}'

两类动作的写路径纪律与其它 admin 写一致：变更与 materialize 同事务、提交后广播门铃，agent 定向收敛（birdc configure 热重载，无关会话零扰动）。

处置后的验证 ​

  1. GET /admin/fleet/mitigations 确认声明已生效（前缀在各节点的持有列表 / 会话 enabled=false）。
  2. 榜单观察衰减分回落（半衰期内自然衰减，见 ../internals/flap-detection.md）。
  3. 数据面核对用节点上的 birdc（控制面榜单是采集快照，有滞后；实时状态以 BIRD 为准，见 monitoring-and-troubleshooting.md）。

常见判例 ​

  • 对端周期性 180s 翻动 + 路由导入恒 0：大概率不是对端问题，是本端到对端的 MTU 黑洞（大 UPDATE 报文被丢，hold 超时循环）——降接口 MTU 到实测 PMTU，不要 peer-disable。用 DF 大包 ping 找阈值。
  • 某前缀在全 fleet 榜上高分且 origin 高可信：prefix-block 该前缀（可先金丝雀单节点），观察告警回落后评估是否长期保留。
  • near 判定 + 本端会话同时在会话级榜上：查本节点与该对端的隧道质量（丢包、重协商）与对端会话配置，处置动作放最后。