企业官网建设流程全解析

• 可观测性
• 后端
• 微服务
• 云原生

SkyWalking 官方 UI 是项目默认的可视化前端，为全链路应用观测提供开箱即用的仪表盘能力。本文围绕 docs/en/ui/README.md 展开，系统讲解侧边栏菜单与 Marketplace 机制、Layer/Entity 两个核心概念、自定义 Dashboard 的编辑与保存、Widget 的指标配置与图型映射、以及关联、静态链接与设置项等实战要点，帮助你快速掌握 SkyWalking UI 的查看与定制能力。

官方 UI 与默认仪表盘概览

SkyWalking 官方 UI 提供默认且强大的可视化能力，用于观测全栈应用（full-stack applications）。它是 SkyWalking 项目仓库中独立于 OAP 后端的前端工程，源码位于 skywalking-ui 目录；在正式发布包中，UI 与 OAP 后端一同分发，可通过 apm-dist 的 assembly 配置打包集成。

UI 左侧的导航栏列出了所有受支持的观测栈及其默认仪表盘：

• 使用Official Dashboards菜单，可以逐个探索用于监控不同技术栈的默认仪表盘；
• 仪表盘覆盖范围包括语言 Agent（Java、Go、Node.js、Python 等）、服务网格（Istio/Envoy）、Kubernetes、各类数据库与消息队列、基础设施（Linux/Windows）、云厂商服务（AWS）以及 SkyWalking 自身的可观测性（SO11Y）。

这些默认仪表盘不是写死在 UI 前端代码里的，而是由 OAP 后端在启动时从ui-initialized-templates目录加载的 JSON 模板。从 UITemplateInitializer.java 的源码可以看到，后端会按Layer名称逐一扫描ui-initialized-templates/<layer>子目录下的模板文件（如general、mesh、mysql、kafka、so11y_oap等），解析后通过UITemplateManagementService.addIfNotExist写入存储，形成默认仪表盘集合。

侧边栏菜单与 Marketplace

菜单的按需出现机制

自 9.6.0 起，所有可用的功能菜单项只登记在 marketplace 中，只有存在被各类观测探针（语言 Agent、服务网格平台、OTEL 集成等）观测到的对应服务时，菜单项才会出现在侧边栏上。也就是说：菜单是动态的、按需浮现的——没有采集到对应数据前，左侧导航保持精简；一旦某个服务被观测到，其所属菜单会在短时间内自动弹出。

驱动这一机制的配置文件是ui-initialized-templates/menu.yaml，它是所有默认支持集成的通用 marketplace。从 UIMenuInitializer.java 的实现可以看出，OAP 启动时用 SnakeYAML 读取该文件，解析为MenuData后调用UIMenuManagementService.saveMenu保存菜单定义；如果文件不存在则跳过加载（仅打印 debug 日志）。仓库中的真实菜单文件位于 menu.yaml。

菜单定义支持一级和二级菜单项，叶子菜单项必须带有用于导航的layer字段。典型结构如下：

menus: - name: GeneralService icon: general_service menus: - name: Services layer: GENERAL - name: VisualDatabase layer: VIRTUAL_DATABASE - name: VisualCache layer: VIRTUAL_CACHE - name: VisualMQ layer: VIRTUAL_MQ - name: SelfObservability icon: self_observability menus: - name: SkyWalkingServer layer: SO11Y_OAP - name: Satellite layer: SO11Y_SATELLITE

仓库中的实际模板在字段命名上略有演进（如顶层使用title/i18nKey/description），但核心结构一致：二级菜单的layer是菜单与观测数据之间的关联键。例如General Service下的Virtual MQ对应VIRTUAL_MQ层——当语言 Agent 通过插件观测到虚拟消息队列时，该菜单才会出现。

菜单刷新间隔配置

菜单出现存在一个轮询刷新周期。控制该周期的是后端配置项uiMenuRefreshInterval：

• 默认值为20（秒），定义见 CoreModuleConfig.java；
• 配置词汇表（configuration-vocabulary.md）中的说明为："The period (in seconds) of refreshing the status of all UI menu items."。

也就是说，当至少一个服务被观测到后，UI 会以该周期（默认 20 秒）刷新各菜单项对应的状态，从而让相关菜单"自动弹出"在左侧导航栏。

自定义 Dashboard 的核心概念

除官方仪表盘外，Dashboards为最终用户提供定制能力：可以新增标签页/页面/小组件（tab/page/widget），也可以按个人偏好重新配置仪表盘。

Layer 与 Entity Type：定制前必须理解的两个属性

每个仪表盘都有两个关键属性：

1. Layer（层）：决定仪表盘属于哪类观测对象（如GENERAL、MESH、MYSQL、KAFKA、SO11Y_OAP、VIRTUAL_DATABASE等）。后端在加载模板时正是以 Layer 目录为单位扫描的，参见 UITemplateInitializer.java 中的UI_TEMPLATE_FOLDER列表，其中除各类技术栈 Layer 外还包含custom目录。
2. Entity Type（实体类型）：决定仪表盘作用在哪个粒度上，例如 Service、Instance、Endpoint、Cluster、Node 等。

此外，追踪（trace）、指标（metrics）与日志（log）分析分别由 SkyWalking 内核中的 OAL、MAL、LAL 引擎驱动：

• OAL：指标聚合语言，参见 mal.md 概念文档；
• MAL：指标表达式语言，参见 mal.md；
• LAL：日志分析语言，参见 lal.md。

建议先理解这三个引擎，再进行自定义仪表盘工作。

Root 仪表盘与入口语义

Service和All实体类型的仪表盘可以设置为 root（"set this to root"），被设为 root 的仪表盘将作为其 Layer 的默认入口。注意：

• 如果一个 Layer 下有多个 root 仪表盘，UI 会随机选择其中一个作为入口，官方不推荐这样做；
• 因此应保证每个 Layer 至多保留一个 root 仪表盘。

编辑权限与保存机制（重要注意事项）

发布版本默认关闭仪表盘编辑功能，需要设置系统环境变量来激活：

SW_ENABLE_UPDATE_UI_TEMPLATE=true

该环境变量在后端配置中映射为enableUpdateUITemplate，默认值为false，定义见 server-starter 的 application.yml。从 UIConfigurationManagement.java 源码可以看出，创建、更新、禁用仪表盘的 GraphQL 接口都会在未开启该开关时返回"dashboard creation/update/disable has been disabled. Check SW_ENABLE_UPDATE_UI_TEMPLATE..."的提示。

保存机制上的两个关键点：

1. 在保存编辑结果之前，修改只存在内存中；
2. 关闭标签页会永久丢失所有未保存的更改——编辑完成后务必立即保存。

新增与编辑仪表盘

• 新增仪表盘：通过Dashboards菜单中的New Dashboard创建。
• 编辑已有仪表盘有两种方式：
  1. 在Dashboards菜单的Dashboard List中，对已有仪表盘执行编辑（edit）/删除（delete）/设为 root（set-as-root）操作；
  2. 在任意仪表盘页面右上角点击V切换，转为E（代表Edit）模式后直接编辑。

模板加载的底层机制

自定义仪表盘与官方仪表盘在底层使用同一套模板体系。OAP 启动时，UITemplateInitializer.java 会：

• 读取ui-initialized-templates/<layer>目录下的所有 JSON 文件；
• 每个文件必须且只能包含一个dashboard 配置对象，否则抛出异常；
• 校验同一 Layer + Entity + Name 组合下的命名冲突（verifyNameConflict），冲突时拒绝加载；
• 通过addIfNotExist写入，实现幂等初始化。

以通用层根仪表盘为例，general-root.json 展示了真实模板结构：顶层children为 Tab/Widget 的布局树（x/y/w/h 定位），Widget 内通过graph.type（如ServiceList、Topology）声明图型，metricConfig声明指标标签与单位，expressions/subExpressions声明 MQE 表达式（如avg(service_cpm)、avg(service_sla)/100）。理解这份 JSON 有助于深入理解 UI 仪表盘的渲染原理。

Widget：仪表盘的基本组成单元

仪表盘由各种 widget 组成。在Edit模式下，可以根据 Layer 对 widget 进行新增、移动、删除、编辑——每个 widget 都会声明自己适用的 Layer。

Widget 的核心作用是可视化由 OAL、MAL 或 LAL 脚本生成的指标数据。

指标（Metrics）配置要素

要在图中展示一个或多个指标，需要配置以下信息：

1. Name（名称）：指标的名称；
2. Data Type（数据类型）：按不同指标类型决定读取数据的方式；
3. Visualization（可视化）：用于可视化指标的图型选项，每种数据类型都有与之匹配的图型（对应关系见下文"常见图型"）；
4. Unit（单位）：指标数据的单位；
5. Calculation（计算）：指标的计算公式（可用公式见下文"计算方式"）。

常见图型与数据类型的匹配

实际图型能力对应着 UI 渲染层，例如模板中出现的ServiceList、Topology等图型类型即由graph.type字段驱动（参见 general-root.json）。

计算方式（Calculations）

这些计算对应着原始存储值与展示值之间的换算：例如 OAL 中 Apdex 类指标通常以万分比存储，展示时除以 10000 还原为 0~1 的 Apdex 分；service_apdex/10000正是 general-root.json 中根仪表盘的 MQE 表达式写法。时间类的转换基于 dayjs 库，用于把 Unix 时间戳渲染为可读时间。

图型样式（Graph styles）

除指标配置外，图型还提供高级样式选项（advanced style options），用于调整展示效果，如坐标轴显隐、字号、是否显示分组等。以模板中的ServiceList图型为例，其样式字段包括fontSize、showXAxis、showYAxis、showGroup等（见 general-root.json）。

Widget 选项（Widget options）

Widget 本身可以定义以下属性：

1. Name（名称）：widget 的名称，用于在仪表盘中与其他 widget 进行关联；
2. Title（标题）：widget 的标题名；
3. Tooltip Content（提示内容）：widget 的附加说明文字。

Widget 关联（Association Options）

Widget 提供与其他 widget 关联的能力：关联后，鼠标悬停时会在同一时间点上显示轴指针（axis pointer）与提示信息，帮助用户理解多个指标之间的连通性/联动关系。

Widget 静态链接（Widget Static Link）

仪表盘上每个 widget 的右上角都有Generate Link选项，可生成代表该 widget 的静态链接。通过该链接可以：

• 将 widget 分享给他人；
• 将 widget 以 iFrame 形式集成到任何第三方系统中，轻松构建大屏网络运维中心（NOC, Network Operations Center）仪表盘。

关于该链接有两个可自定义选项：

1. Lock Query Duration（锁定查询时长）：手动设置查询时长，默认关闭（OFF）；
2. Auto Fresh（自动刷新）：默认开启（ON），查询周期为 6 秒、时间范围为最近 30 分钟；查询周期与时间范围均可自定义。

Settings 设置

UI 的Settings提供以下选项：

• 语言（language）；
• 服务器时区（server time zone）；
• 自动刷新（auto-fresh）选项。

这些设置存储在**浏览器本地存储（local storage）**中，除非手动清除，否则不会改变。

FAQ：登录与认证

SkyWalking 多年来一直不提供常规意义上的登录与认证功能。如果有认证需求，业界已有大量成熟的网关（Gateway）解决方案可以与之配合，例如 Nginx 生态下的各类认证模块。也就是说，SkyWalking UI 默认假设运行在受信任的内网或由上层网关统一管控的网络环境中，认证能力应由部署架构中的网关层补齐。

延伸阅读

• backend settings 配置词汇表：查阅uiMenuRefreshInterval、enableUpdateUITemplate等与 UI 相关的完整配置项说明；
• OAL/MAL 概念文档 与 LAL 文档：理解指标与日志数据的生成引擎；
• 官方仪表盘模板目录：仓库内 115 个 JSON 模板，覆盖全部默认技术栈，是学习仪表盘 JSON 结构与自定义的最佳参考；
• menu.yaml：完整侧边栏菜单 marketplace 定义；
• UITemplateInitializer.java 与 UIMenuInitializer.java：仪表盘模板与菜单的加载源码；
• UITemplateCheckerTest.java：模板合法性的测试用例，可用于验证模板格式。

• 可观测性
• 后端
• 微服务
• 云原生