SD-WAN WebUI 设计路线图

Status: Current implementation baseline

Last reviewed: 2026-06-23

结论

当前 SD-WAN WebUI 已形成可验证的运维控制台基线。

已有代码提供了可用雏形：

• nexus-frontend/src/components/layout/sidebar.tsx 已有 SD-WAN 导航组。
• nexus-frontend/src/app/(dashboard)/gateway/sdwan/*/page.tsx 已有 Overview、 Route Policies、NNSR Paths、Underlay Sessions、Egress Targets、Topology、Route Simulator 路由。
• nexus-frontend/src/components/gateway/sdwan-console.tsx 已有主要页面实现。
• nexus-frontend/src/lib/sdwan.ts 已经把 path hop 和 forward entry 连接到 underlaySessionId。
• 2026-06-22 本轮已把 SD-WAN console 主要页面文案接入 en / zh-CN i18n，并把 Underlay 页面 UI 文案统一为 Underlay Sessions / 承载会话。
• 2026-06-22 Egress Targets 已改为按类型显示固定字段；raw config 仅作为只读预览。
• 2026-06-22 Route Policies 的 pinned path 已从 UUID textarea 改为节点选择器和有序跳点列表。
• 2026-06-22 Route Simulator 已展示匹配策略、选中路径、承载会话、转发表项、出口动作、 fallback reason 和 warnings。
• 2026-06-23 侧边栏已把 SD-WAN 子页面统一为 Overview、Route Policies、NNSR Paths、 Underlay Sessions、Egress Targets、Topology、Route Simulator；底层传输链路已移出 SD-WAN 顶级导航。
• 2026-06-23 Transport Links 已从 Network 顶级侧边栏移除，改由 SD-WAN Underlay Sessions 页提供高级来源入口；Transport Links 页面本身明确标注为 underlay source plumbing。
• 2026-06-23 Route Policies 表单已增加默认路由和宽匹配风险确认；保存前会阻止未确认 的高风险策略、缺出口目标和空 pinned path。
• 2026-06-23 NNSR Path 详情已默认展示 hop chain、underlay session health、MTU budget、 forward-entry install drift 和节点级安装详情；安装详情来自 agent apply report 的 route_version_nodes.message。
• 2026-06-23 Underlay Sessions 主列表已改为 session-first：会话状态、节点对、 transport、endpoint、runtime 和操作优先展示。
• 2026-06-23 Underlay Sessions 不再兼容 L3 projection；REST、PCE 和 runtime 只消费 显式 SD-WAN underlay profiles，QUIC REALITY 与 BoringTun WireGuard 都在新会话窗口内配置。
• 2026-06-23 Topology 已改为拓扑快照 + node/link inspector：节点、链路可选中， link health、latency、loss、jitter、bandwidth、last update 可排障，drain/exclude 有确认。
• 2026-06-23 Topology API 已返回当前 route version 的 path details 和 recent events； WebUI 不再把 /sdwan/paths 列表误当成 path detail 使用。
• 2026-06-23 Topology 已增加 affected paths 队列和 topology timeline，可从风险路径直接选中 inspector 或打开完整 NNSR path 详情。
• 2026-06-23 Route Simulator 已增加结果动作：可打开模拟出的 NNSR path 详情弹窗， 并跳转到 Route Policies、Underlay Sessions、Egress Targets。
• 2026-06-23 Overview 已增加 Operational Health 摘要、Agent Drift Queue，并增强 Degraded Paths 的 fallback reason、egress、MTU、loss 展示。
• 2026-06-23 SD-WAN console 已把 route/path/install/event 等状态枚举封装为 en / zh-CN 文案；未知后端枚举仍回退为可读原值。
• 2026-06-23 Overview 已接入 degraded underlay sessions；数据来自当前 route version 实际使用 hop 对应的 node_links latency/loss/jitter/bandwidth 遥测。
• 2026-06-23 Overview 和 Topology timeline 已对已知 SD-WAN 事件动态消息做 en / zh-CN 本地化，未知消息仍回退原文。
• 2026-06-23 Agent heartbeat、Backend API 和 WebUI 已接入 per-underlay-session runtime health：rx/tx/error/last report。
• 2026-06-23 Overview 的 Degraded Underlay Sessions 已合并 link telemetry 与 agent runtime error。
• 2026-06-23 Playwright 响应式检查覆盖 Overview、Topology、Policies、Underlay Sessions 的 1440/768/390px 视口；修复了 Topology node card 内嵌 tooltip button 导致的 nested button hydration error。
• 2026-06-23 repo scan 已确认废弃传输路径和已停止维护的语言口径不再出现在运行时入口。

剩余工作属于未来增强，不再阻塞当前 WebUI 基线：per-forward-entry 独立失败原因、持久 override/clear override 状态模型、更多自动 fallback 原因分类。

产品边界

SD-WAN WebUI 只暴露以下对象：

对象	用户心智	UI 权限边界
Route Policy	哪些流量进入 SD-WAN，走什么出口和意图	可创建、编辑、模拟、部署
NNSR Path	PCE 计算出的路径和标签转发表	默认只读，可查看详情和安装状态
Underlay Session	节点之间可用的承载 session	可查看健康、成本、MTU、来源；创建动作走 L3/port/credential 规则
Egress Target	流量从哪里离开 SD-WAN	可按类型表单化配置
Route Version	一次 PCE 计算和下发结果	可 recompute、deploy、rollback、查看 drift
Node Action	排水、排除、偏好区域等运维动作	必须有确认、状态反馈和审计结果

UI 不应该暴露 “SD-WAN port”。底层 socket、REALITY profile、WireGuard key、MTU 预算和地址来源属于 underlay session diagnostics 或高级 transport 详情，不是 SD-WAN role 属性。

信息架构

目标导航：

Network
  SD-WAN
    Overview
    Route Policies
    NNSR Paths
    Underlay Sessions
    Egress Targets
    Topology
    Route Simulator
    Advanced transport source links

约束：

• SD-WAN 是策略和路径控制台。
• 底层传输链路不能作为顶级 SD-WAN 策略入口。
• L3 建出的可用链路投影为 SD-WAN underlay session。
• SD-WAN 页面默认消费 underlay session，不直接编辑底层 listener/port。
• 底层传输入口只从 Underlay Sessions 的高级来源动作进入。

Transport Links 已从顶级导航降级到 SD-WAN Underlay Sessions 的高级传输来源入口， 避免用户把底层链路当作 SD-WAN 路径策略。

视觉与交互基线

这不是 landing page。界面应是安静、数据密集、可钻取的运维控制台。

设计要求：

• 页面首屏优先显示状态、风险和下一步动作，不做宣传式 hero。
• 表格支持横向滚动或响应式列裁剪，移动端不能撑破视口。
• 状态色只表达状态：成功、告警、失败、待部署、已过期。不要用大面积装饰色。
• 卡片只用于 metric、重复项、详情面板和弹窗，不做嵌套卡片。
• 所有操作按钮使用 lucide 图标加短文本；危险操作必须确认。
• 拓扑视图要可选中节点、link、session、path，并在右侧或下方显示详情。
• 表单按任务分段，不让用户一次面对所有底层字段。
• 文案短、具体、运维化。示例：“版本状态”“路径已降级”“发起排水”“模拟路径”。

i18n 路线

现状：

• nexus-frontend/src/i18n/context.tsx 只支持 en 和 zh-CN。
• nexus-frontend/src/components/layout/header.tsx 和登录页语言菜单也只有两种语言。
• sdwan-console.tsx 已接入 useT()；核心标题、按钮、表头、弹窗、toast、空态和 主要表单文案使用 sdwan namespace。
• 现有 en.json 和 zh-CN.json 结构通过脚本同步检查，缺键会在 npm run test:i18n 失败。
• SD-WAN console 已使用 tx() 包装 fallback，避免 t("key") || fallback 掩盖缺键。
• Overview 和 Topology timeline 已通过 sdwan.event_messages 本地化已知事件消息。

目标：

src/i18n/
  context.tsx
  en.json
  zh-CN.json

新增顶层 namespace：

sdwan
  common
  overview
  policies
  paths
  underlay
  egress
  topology
  simulator
  route_versions
  status
  actions

必须补齐：

• nav.network
• nav.sdwan
• nav.sdwan_overview
• nav.sdwan_policies
• nav.sdwan_paths
• nav.sdwan_underlay
• nav.egress_targets
• nav.sdwan_topology
• nav.sdwan_simulator
• common.previous
• common.next

术语表：

English	zh-CN
Route Policy	路由策略
Path Intent	选路意图
NNSR Path	NNSR 路径
Underlay Session	公网承载会话
Egress Target	出口目标
Route Version	路由版本
Forward Entry	转发表项
Install State	安装状态
Fallback Path	备用路径

验收门槛：

• 语言菜单包含 English、简体中文。
• SD-WAN 页面无未封装的核心用户可见英文字符串，协议名、ID 和后端动态消息除外。
• t() 缺键不能被 || fallback 掩盖。
• 字典 key 同步检查覆盖 en、zh-CN。
• 中文文案不使用长解释句，不写“如何使用本页面”的显性说明。

页面路线

1. Overview

目标：让运维人员 30 秒内知道当前 SD-WAN 是否健康。

首屏指标：

• Active policies
• Installed paths
• Degraded sessions
• Current route version
• Agents in sync
• Active fallbacks

必备面板：

• Route version state: candidate、computed、deployed、stale、failed。
• Agent install drift: 哪些 agent 未安装当前版本。
• Top degraded sessions: session、节点对、loss、latency、MTU、最后上报时间。
• Recent events: recompute、deploy、rollback、fallback、drain、exclude。

操作：

• Refresh
• Recompute
• Deploy current candidate
• Rollback selected version

2. Route Policies

目标：策略创建流程必须围绕流量、出口、选路意图和预览，不围绕底层链路。

表格列：

• Status
• Priority
• Match
• Path intent
• Active path
• Egress
• Version
• Actions

创建流程：

Match traffic
  -> Egress target
  -> Path intent
  -> Preview / simulate
  -> Save
  -> Deploy

要求：

• pinned path 不能要求用户手填节点 UUID；必须使用节点/session selector。
• policy conflict 要在保存前或模拟结果中明确展示。
• 默认路由、全端口、全协议这类高风险匹配必须确认。
• 保存和部署分开，避免编辑表单自动改变运行态。

3. NNSR Paths

目标：让用户理解 PCE 算出了什么，以及每跳怎样通过 underlay session 发包。

列表列：

• Path ID
• Policy
• Route version
• Mode
• Hops
• Latency
• Loss
• Health
• Install state

详情结构：

Path summary
  route version / policy / egress / health / explanation
Hop chain
  node -> underlay session -> node
NNSR labels
  local label / next label / action
Forward entries
  node / action / next node / underlay session / install state
MTU budget
  ingress MTU / per-hop underlay MTU / final payload budget

默认展示路径和健康原因。NNSR label 位宽、TTL 等技术细节放在高级区。

4. Underlay Sessions

目标：把底层 L3 能力投影成 SD-WAN 可用 session。

列表列：

• State
• Local node
• Peer node
• Source
• Session mode
• Endpoint
• MTU
• Latency
• Loss
• Priority
• Cost
• Last report

创建/编辑边界：

• SD-WAN 可创建 desired underlay intent，但实际端口、listener、REALITY profile、 credential 必须走 L3/port/credential 规则。
• 来自 L3 的 session 默认只读显示底层来源。
• 底层 endpoint 可以诊断展示，但不能叫 SD-WAN endpoint。
• REALITY 端口只显示为 transport endpoint reservation，不允许在 SD-WAN 表单随机填写。

第一版保留现有 REST 路径名，但 UI 文案已统一成 Underlay Sessions。

5. Topology

目标：从当前卡片网格升级成可排障拓扑。

视图：

Toolbar
  route version / health filter / region filter / refresh
Canvas or SVG topology
  node status / link health / active path highlight
Inspector
  selected node / link / session / path
Timeline
  recent fallback / drain / exclude / deploy events

操作：

• Drain node
• Exclude node
• Prefer region
• Clear temporary override（需要后端持久 override 状态模型）
• Open affected paths

验收：

• 1024px 以上显示拓扑和 inspector 双栏。
• 768px 以下拓扑和详情纵向堆叠。
• 320px 不能横向溢出。

6. Route Simulator

目标：模拟一个包进入 SD-WAN 后会匹配哪条策略、哪条路径、哪个出口。

输入：

• Ingress node
• Source IP
• Destination IP
• Protocol
• Port
• Source group
• User group
• Traffic tag

输出：

• Matched policy
• Selected path
• Egress target
• Underlay sessions per hop
• Fallback reason
• Warnings
• Links to policy/path/session detail

文案必须运维化，例如“模拟流量路径”，不要写演示口吻。

7. Egress Targets

目标：移除默认 JSON 配置体验，改为按类型表单。

类型：

• NAT node
• Public IP pool
• Service upstream
• Remote TUN
• Drop

每种类型提供固定字段和校验。高级 JSON 只能作为只读 raw view 或调试抽屉，不作为 默认编辑方式。

数据与 API 缺口

前端当前已消费或需要后端稳定提供：

• Underlay sessions: explicit SD-WAN underlay profiles only。
• Session runtime: rx/tx/error counters、last report、last error。
• Metrics: latency、packet loss、jitter、bandwidth、last report。
• MTU budget: underlay MTU、NNSR overhead、payload MTU。
• Route install drift: per agent installed route version and node-level error message。
• Forward-entry install detail: current UI derives node-level install message from sdwan_route_version_nodes.message; true per-entry failure reason still needs backend schema if agent reports individual entry failures later.
• Fallback reason: health, policy constraint, node unavailable, session unavailable。
• Topology action result: affected policies, affected paths, audit id。

当前 WebUI 的运维闭环已覆盖 route version、agent drift、degraded paths、degraded underlay sessions、runtime counters 和主要操作反馈；更细粒度的 per-entry failure reason 与持久 override 状态仍是后端增强项。

协作模型

WebUI 采用“设计合同 -> 切片实现 -> 截图审查 -> i18n 审查 -> 合并”的循环。

角色：

角色	责任
User	决定产品心智、术语、优先级和不能出现的旧模型。
Codex implementation owner	读代码、改前端、补 i18n、跑检查、维护 roadmap。
Product/IA expert	审查导航、任务流、页面切片和运维闭环。
i18n expert	审查 key 结构、en / zh-CN 覆盖、术语和中文表达。
Backend/domain expert	审查 API 字段是否匹配 NNSR/underlay session 边界。
Visual QA expert	用 Playwright 截图查桌面/移动布局、溢出、对比度和交互状态。

每个 UI 切片需要产出：

• 页面或组件变更。
• en、zh-CN 文案。
• 空态、加载态、错误态。
• 关键表单校验。
• Playwright 桌面和移动截图。
• 至少一次 build/lint。

实施阶段

Phase 0: 设计冻结

• [x] 确认本路线图术语表。
• [x] 确认不保留独立底层传输链路顶级入口。
• [x] 确认 UI 文案统一为 Underlay Sessions。
• [x] 确认 en/zh-CN 术语和文案风格。

Phase 1: i18n 底座

• [x] 保持 Lang 为 en | zh-CN。
• [x] 统一语言菜单。
• [x] 新增 sdwan namespace。
• [x] 消除 SD-WAN 页面硬编码文案。
• [x] 增加字典同步检查脚本。

Progress:

• SD-WAN console 已审计 JSX 文本、placeholder、dialog title 和 toast；用户可见文案已走 sdwan.* 或既有 common.* 字典，剩余直接文本是协议枚举、技术示例值或 tx() fallback。

Phase 2: IA 和导航

• [x] 补齐 SD-WAN nav 字典。
• [x] 调整底层传输链路文案，明确其为底层连接管理。
• [x] SD-WAN 子页面命名统一为 Overview、Route Policies、NNSR Paths、 Underlay Sessions、Egress Targets、Topology、Route Simulator。
• [x] 删除或隐藏会让用户误解为旧 SD-WAN 路径的入口和文案。

Progress:

• Transport Links 不再作为 Network 顶级侧边栏项出现。
• Underlay Sessions 页提供 QUIC/WireGuard transport 高级入口，并说明 SD-WAN 消费 underlay session，Transport Links 只是来源配置。
• Transport Links 页面增加边界提示：策略、NNSR 选路和出口决策留在 SD-WAN 控制台。

Phase 3: Policies / Simulator

• [x] 重构 policy 表单为分段流程。
• [x] pinned path 改为 selector。
• [x] default route 和 broad match 增加确认。
• [x] simulator 输出 policy/path/session/egress 全链路。
• [x] 模拟结果可跳转详情。

Progress:

• Policy 创建/编辑已改为 Match、Path、Egress、Review 四步流程；字段错误会停在当前步骤， 最终保存错误会跳回第一个问题步骤。
• Simulation Output 已增加 Result Actions。
• 模拟出的 NNSR path 可直接打开 path detail 弹窗，复用 NNSR Paths 页详情组件。
• Policy、underlay sessions、egress targets 可从模拟结果跳转到对应页面。

Phase 4: Underlay Sessions / Paths

• [x] Underlay 页面改为 session-first。
• [x] 移除 L3 projection 兼容，Underlay Sessions 只展示显式会话。
• [x] NNSR path 详情默认展示 hop chain 和 underlay session health。
• [x] MTU budget 可视化。
• [x] Forward entries 增加 install drift 和错误详情。

Progress:

• NNSR path detail 和 Route Simulator 的 underlay hop 表已按 session-first 展示。
• Underlay Sessions 列表已以 session state、node pair、transport、endpoint 和 runtime 为主视图；创建/编辑表单按 identity/security/budget 分段并保留 QUIC REALITY 与 BoringTun WireGuard 两种新会话模式。
• /sdwan/underlay-profiles 列表只返回显式 SD-WAN profiles；旧 L3 projection route version 会被标记 stale，后续 recompute 只使用显式承载会话。
• Forward entries 已拆分 next label 与 underlay session，并对非 installed/active 状态标记 install drift。
• Forward entries 已显示节点级安装详情；数据来自同一路由版本、同一节点的 agent apply message。
• 真实 runtime session health 通过 sdwan_underlay_session_runtime 返回到 WebUI。
• Overview 的 Degraded Underlay Sessions 使用当前 route version 的 sdwan_path_hops 关联 node_links，展示 session、path、节点对、latency、loss、jitter、bandwidth 和原因。
• Route/path/install/event 等 UI 状态枚举已通过 sdwan.status、sdwan.path_modes、 sdwan.forward_actions 和 sdwan.event_actions 本地化。
• Per-entry failure reason 仍不是独立字段；如果 agent 后续按 entry 上报失败原因，需要新增 后端 schema。

Phase 5: Topology / Observability

• [x] 拓扑视图替代纯卡片网格。
• [x] 支持 node/link/session/path inspector。
• [x] drain、exclude、prefer region 有确认和结果反馈。
• [x] Overview 接入 fallback reason、agent drift。
• [x] Overview 接入 degraded session 真实 metrics。

Progress:

• Topology 已从纯节点卡片 + link 表改为 topology snapshot、active links 和 inspector。
• Node inspector 展示状态、区域、SID、underlay endpoint、关联链路数。
• Link inspector 展示健康、latency、loss、jitter、bandwidth、last update。
• Session inspector 基于 sdwan_underlay_profiles 投影展示节点对、传输、endpoint、MTU 和状态。
• Path inspector 基于 /sdwan/topology 返回的 path details 展示 path health、hop chain， 并可打开完整 path detail。
• 选中 path 后，拓扑节点卡、active link 列表和 link detail 表会高亮该 path 经过的节点与链路。
• Drain、exclude 和 prefer region 当前是事件记录/重算请求，已增加确认和 toast 结果；后端 还没有持久 override 状态模型，不能提供真实 clear override。
• Affected paths 队列展示低健康度、fallback、安装漂移路径，并可直接选中 inspector 或打开详情。
• Topology timeline 展示最近 deploy、recompute、drain、exclude 等事件及短 metadata 摘要。
• Topology node card 已移除 nested button 结构，节点状态用非交互 pill 展示，避免 TooltipTrigger 嵌套在可点击卡片内。
• Overview 已接入 Operational Health、Agent Drift Queue、fallback/degraded path reason。
• Degraded session 已合并 link telemetry 与 agent runtime error，Overview 可直接显示 runtime error reason、last error 和 last report。
• Active path highlight 使用 /sdwan/topology 返回的 path hops 计算，只读关联当前 route version。

Phase 6: Egress Targets

• [x] 按出口类型拆表单。
• [x] 移除默认 JSON 编辑体验。
• [x] 增加类型级校验和预览。
• [x] 把 service upstream 与已有 L4 upstream selector 打通。

完成定义

SD-WAN WebUI 只有同时满足以下条件才算做好：

• 用户不需要理解底层隧道实现，也能完成策略、路径、出口和排障。
• NNSR path 页面只通过 underlay session 描述下一跳承载。
• SD-WAN 页面不出现旧路径心智或独立旧 underlay 选择。
• REALITY、WireGuard、端口、credential 只作为底层 session 详情或高级配置出现。
• en / zh-CN 完整，SD-WAN 页面无硬编码用户文案。
• 所有危险动作有确认和审计结果。
• Overview 能回答“现在是否健康、哪里坏了、下一步做什么”。
• Simulator 能回答“这条流量会怎么走、为什么这样走、失败时原因是什么”。
• 桌面、平板和手机布局无文本溢出、无横向破版。
• npm run lint、npm run build 和文档构建通过。