NATLAN Docs

外观

Web 管理界面 ​

面向用浏览器操作控制面的运维人员。Web UI（NATLAN 控制台）是独立的静态 SvelteKit SPA，源码维护在独立仓库 dn42-control-webui，部署为 Cloudflare Git 关联 Worker（静态资产），生产地址 https://console.natlan.io（备用入口 https://webui.ngworks.org）。它不含服务端逻辑——凭据存浏览器 localStorage，经 CORS + Authorization: Bearer 直连控制面（默认 https://api.natlan.io）。

接口字段只在 ../reference/api.md 维护；本文只讲"界面上怎么点"。构建 / 部署 / 前端开发说明见 Web UI 仓库自身的 README。

本地开发运行 ​

bash
git clone https://github.com/chidakiko/dn42-control-webui
cd dn42-control-webui
npm install        # 首次
npm run dev        # 开发模式，默认 http://127.0.0.1:5173

控制面需开启 CORS 允许该来源（DN42_CONTROL_CORS_ORIGINS，见 ../reference/configuration.md）。

登录与账号 ​

登录

登录页是 Cloudflare 式布局，提供两种登录方式（记住上次成功的方式）：

  • 管理员账号（默认）——用户名 + 密码 + Cloudflare Turnstile 人机验证，调 POST /api/v1/auth/login 换取会话令牌（密码服务端只存 argon2id 散列；会话令牌 24 小时有效）。账号方式固定连默认控制面（不暴露地址覆盖）。密码错 401、账号锁定 403、同用户名或同 IP 连续失败 5 次进入 15 分钟限速窗口（429）；对不支持账号体系的旧后端（404/405）给出降级提示，引导改走 token 方式。契约见 ../reference/api.md。
  • API Token——机器凭据，直接粘贴 admin token（无 Turnstile），并开放「控制服务器地址」输入框，可指向任意控制面实例（空 = 默认）。一份静态构建因此可操作任意 fleet。

登录后顶栏右侧是 GitHub 式身份下拉：显示当前凭据归属（账号显示用户名，token 显示「API Token」），菜单含「账号设置」（/account，账号会话可修改密码；改密成功即吊销全部会话、回登录页）与「退出登录」。401 即凭据失效，自动登出。

身份下拉菜单

界面外壳 ​

  • 顶栏：汉堡菜单（手机抽屉）、NATLAN 标志、面包屑（带父级分组，页面描述收进 info 图标 tooltip）；右侧依次是自动刷新开关（全局 35s 轮询，可暂停）、语言（英 / 简中 / 繁中 / 日 四语）、主题（跟随系统 / 亮 / 暗）、文档入口（book 图标，新窗打开 docs.natlan.io）、身份下拉。

    顶栏

  • 侧栏：Cloudflare 式分组层级，可折叠成图标轨、hover 悬浮展开；手机端变为从顶栏下方滑出的抽屉。底部显示当前控制面地址（指向 legacy 面时带「Legacy」徽章）。

    侧栏分组层级

侧栏导航结构：

分组页面
总览概述 / · 流量 /traffic · 路由 /routing · 抖动 /flaps
节点节点列表 /nodes（详情页 /nodes/<id> 由列表下钻）
接入注册审批 /registrations · 注册令牌 /enrollment-tokens · 导入下发 /provision
DNSDNS 组 /dns-groups
运维Agent 版本 /agent-releases · 审计日志 /audit

列表筛选、页签、翻页位置等状态都会写进 URL query——任意界面状态可复制链接分享。

总览（概述页） ​

机群拓扑

页首 hero 是机群拓扑世界地图（可平移缩放）：节点按物理站点落在等距投影世界地图上，真实内部 WG 链路（OSPF 邻接）画大圆弧相连；按缩放层级自动把节点聚合成区 / 国家 / 城市簇，hover 高亮邻接与链路明细。顶部有健康筛选 chip 与链路图例，右侧节点列表支持区筛选与翻页，行内含能力图标（DNS / RPKI / BIRD / WG）、世代、漂移、agent 版本、最近心跳与一键请求快照。健康判定见 monitoring-and-troubleshooting.md。

机群拓扑 Widget

Widget 头部是机群 KPI：在线 / 总数、Agent 目标版本（落后数链接到 Agent 版本页）、peering 状态、开放 flap 告警数（链接到抖动页）。

下方的 Peering issues 表只在有未建立的 BGP 会话时出现，worst-first 排序（flapping → down → connecting），行点击直达对应节点的 BGP 会话页签；全部正常时整表消失。

对等连接异常表

流量页 ​

流量

页顶 range 分段控件（24h / 7d / 30d）驱动全页。三个板块：

  • 相对变化 hero：逐桶「本期 vs 上期」收 / 发变化率曲线，配流量构成半环（内部 / 外部、收 / 发）与 Top-5 对端榜；
  • 绝对趋势图：收 / 发字节实线 + 上期虚线对比；
  • 按对端 AS 流量：全量对端 AS 流量榜（AS 名由控制面按 registry 权威解析）。

流量相对变化 hero

路由页 ​

全机群路由分析板：路由总量与 IPv4/IPv6、RPKI 有效率统计条 + 半环仪表；收敛 / RPKI-invalid 告警；分家族路由表规模趋势；起源 AS 榜（分页）。单节点级的路由分析在节点详情的「路由」组（见下）。

机群路由

抖动页（flap 检测与处置） ​

抖动

/flaps 把 BGP flap 检测三层（会话 P0 / 前缀 P1 / 告警 P2，算法见 ../internals/flap-detection.md）与人工处置收进一页，自上而下：

  1. 活动 hero——fleet 级 flap 速率仪表（1h–30d range 分段，可切 fleet / per-node 刻度）+ 路由变更量与活跃前缀数两张时序图。

    抖动活动 hero

  2. 处置清单（in effect）——当前生效的拒收前缀与被禁用对端（按 AS 折叠），就地可撤销；空时自隐。处置模型见 ../internals/flap-detection.md，操作手册见 flap-response.md。

  3. 前缀 flap 榜——一行一前缀（含 origin 起源 AS 归因，多源 MOAS 标红），内嵌根因定位：近端 / 起源 / 路径 / 多源四个根因区徽章 + 置信度 + 嫌疑点，区筛选 tile 可按根因过滤；展开抽屉看 AS 路径条（按根因区点亮嫌疑段）与 per-peer 明细；行内「⋯」菜单可直接拒收前缀或（近端根因且会话在抖时）断开对端。榜单硬上限 500 行，页顶有 feed 管道健康条。

    前缀 flap 榜与根因定位（展开抽屉：机群根因构成条 + 区筛选 tile + AS 路径条）

  4. 对端烈度榜——每行一个对端 AS，severity 折叠会话层 + 前缀层烈度，区分 linkChurn（本端会话在抖）/ pathChurn（其后路径在抖）；支持 ASN 查找，行点击进单对端详情。

    对端烈度榜

  5. 告警事件流——边沿触发的告警历史（前缀计分上穿阈值开单、滞回关单；告警线 20 标黄 / 100 开单），active / resolved 筛选 + 游标加载更早。

    抖动告警事件流

单对端详情 /flaps/peers/<asn>：复述该 AS 的烈度概况 + 本端相关 eBGP 会话（携 flap score）+ 该对端的前缀榜与告警历史 + 一键禁用；无近期抖动则显示正向空态。

节点列表 ​

节点列表

顶部页签分列表与可观测性两视图。列表支持卡片 / 表格双形态、客户端搜索、活性筛选 chip（在线 / stale / 离线 / 需要关注）：

  • 卡片含活性点、健康徽章、当前吞吐大数、异常芯片（peer down / 漂移 / 版本落后）与 6h 流量 sparkline，按严重度排序；
  • 表格可按各列排序，行「⋯」菜单深链到详情页各页签。

页面也提供新建节点入口（JSON base_template 编辑器）。

节点详情 ​

顶部是节点头（地点 · AS · 世代 + 活性 / 版本 / 健康 / 生命周期徽章）与工具栏：⚡ 一键互联（见下）、通知更新 / 请求快照（手动给 agent 推事件，节点掉线时禁用）、编辑（节点身份与 base_template，含 bird.internal_topology，见 ../internals/internal-routing.md）。节点失联时页顶出断连告警条。

两级页签（5 个顶层分组，?tab=<id> 深链直达）：

  • 概览——漂移问题表（严重度排序，期望 → 观测 diff 芯片）、趋势与 agent 自观测指标、身份信息（含 WireGuard 公钥、前缀、labels）、危险操作（退役 / 恢复 / 删除，删除需输入节点名确认）。

    节点当前异常（漂移问题表）

    节点运行指标（状态 + agent 自观测）

  • 互联：Peering（对等关系元信息）· 接口（结构化表单 / raw JSON 双模编辑 + 链路流量）· BGP 会话（spec 编辑 + 会话 flap 状态转移证据日志）· 内部互联（iBGP / OSPF 合成视图与邻接 liveness）· 拨测（在 debug-shell 容器内流式跑 ping / mtr / traceroute）。

  • 路由：路由表（统计 / 构成仪表 / 前缀长度与 AS-path 分布 / 规模与 churn 趋势 / 起源与对端榜 + 可按族 / 范围 / RPKI / 途经 ASN / 关键字筛选的前缀表，multipath 按前缀分组展开）· 路由过滤（import-table 过滤前视图：per-peer 统计、RPKI-invalid 与拒收原因明细）· 路由调优（community / local_pref 三件套策略表单）。

  • DNS——分配 / 取消 DNS 组：分配即在本节点启用 CoreDNS，多节点订阅同组即 anycast（见 dns-and-anycast.md）。

  • 运维：版本历史（generation 列表 / diff / 回滚）· 状态事件（游标翻页）· 期望状态（当前 DesiredState 只读）· 令牌（agent token 签发 / 轮换 / 吊销）。

节点概览

接口

内部互联

路由表

节点 DNS

一键互联向导（添加 peer） ​

节点详情工具栏点 ⚡ 一键互联，四步把建立对等连接所需配置填好——无需手写 JSON，是新增对等连接的唯一入口。提交时 peering + WireGuard 接口 + 首条 BGP 会话走 provision 端点同事务建立，其余会话随后用返回的 peering_id 补建。

① 基本 —— peer 名、对端 ASN、是否内部、标签/备注。

向导-基本

② WireGuard —— 接口名、监听端口、MTU、本端地址、私钥引用、对端公钥、endpoint、allowed_ips、keepalive、peer_routes。

向导-WireGuard

③ BGP —— 加 0..N 条会话；预设 + IPv4 / + IPv6 链路本地 / + MP-BGP 各带默认。纯传输 peer 可不加。

向导-BGP

④ 确认 —— 摘要 + 只读预览，点「创建对等连接」。

向导-确认

完整 peering 概念见 peering.md。

注册审批 ​

注册审批

新节点 agent 用 enrollment token 注册后落到「待审批」，在此批准/拒绝（可附备注；per-node 准入闸门，见 ../internals/security.md），并可查看节点上报的 inventory。

注册令牌（enrollment token） ​

注册令牌

签发 / 吊销 enrollment token（可绑定节点、设过期），token 明文只在创建时显示一次；列表按 used / expired / valid 派生状态展示。

导入下发（provision） ​

导入下发

贴一份完整 DesiredState JSON 一次性建/覆盖整节点（幂等），也可从现有节点克隆当前期望状态作为起点。字段见 ../reference/desired-state.md。

DNS 组（共享 / anycast） ​

DNS 组

集中维护共享 DNS 配置：一个组带 bind 地址（任播服务地址）+ 缓存 TTL + 转发，组下声明权威 zone（可覆盖 SOA，留空自动派生），zone 下是扁平记录（name / type / content / TTL / 注释，含 PTR 反向助手）。把组分配给节点即在该节点起 CoreDNS；多个节点订阅同一组就是 anycast。组 → zone → 记录三级选择写进 URL，可深链分享。概念与任播地址派生见 dns-and-anycast.md。

Agent 版本（agent-releases） ​

上传 agent wheel 包（version + 多 .whl）、设置全局目标版本；逐节点表显示当前版本 / 合规状态 / 已应用世代 / apply 状态 / 活性分档（online / stale / offline）与最近心跳。心跳版本低于目标时控制面会向 agent 推送更新事件，滚动升级机制见 upgrades-and-migrations.md。

审计日志 ​

审计

admin 写操作的审计流水（谁、何时、改了什么、响应码），游标分页 + 服务端搜索（匹配操作者 / 方法 / 路径），自动刷新只前插新行、不打断已翻的历史。

近期新增页面（索引） ​

近期迭代新增的能力在上文相应小节已有展开，此处汇总索引：

  • 抖动页（/flaps）——flap 榜单、根因定位与处置（见抖动页；处置操作手册见 flap-response.md）。
  • 主动拨测——节点详情「互联」组的拨测子页：在节点 debug-shell 容器内流式跑 ping / mtr / traceroute，SSE 实时输出（接口与原理见 monitoring-and-troubleshooting.md）。
  • registry 名称富化——DN42 registry 镜像数据以 AS 名称 / 链接形式融入流量榜、起源榜、flap 榜与 peering 行（非独立查询页）。

页面级细节（路由、组件、交互）以独立仓库 dn42-control-webui 为准。

关于本页截图 ​

本页配图（docs/images/wui-*.png）摄于 2026-07 的生产实例（中文界面，console.natlan.io × api.natlan.io），与现状代际一致；仅「一键互联向导」四步图为较早代际（结构未变）。截图工具链在 dn42-control-webui 仓库的 scripts/screenshots.mjs（Playwright + 系统 Chrome，注入 localStorage 凭据批量出图）；界面迭代后在该仓库重跑并把 shots/backend-images/ 覆盖到本仓库 docs/images/。