企业官网建设流程全解析

OneUptime 状态页资源与分组完全指南：从单条监控到多级分组与 Grid 矩阵布局

【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime

本篇指南聚焦 OneUptime 开源可观测平台中状态页（Status Page）的**资源（Resources）与分组（Groups）**模块：资源是状态页上的一条可见行（一个监控器或监控器组），分组则是把这些行组织成 "API"、"Web 应用"、"数据管道" 等章节的容器。读完本文，你将掌握资源屏幕的完整布局、单条/批量添加监控的两种流程、五项展示选项（工具提示、当前状态、可用性百分比、历史图表、精度）的配置逻辑、多级嵌套分组的创建与管理，以及从 CSV 批量导入整棵分组树的方法，并能对照仓库源码理解每个字段在数据模型层的真实定义与默认值。

本文依据 法文原版文档（另有 英文版）编写，涉及的字段名、默认值与导入规则均可在仓库源码中交叉验证。

核心概念：什么是资源与分组

**资源（Resource）**就是状态页上的一行——一个带名称、当前状态，以及（可选的）可用性百分比和历史图表的监控器（或监控器组）。访问者看到这一行，就能判断"是我这边的问题还是他们那边的问题"。

**分组（Group）**则是容纳资源的章节容器。当一个状态页有四十个监控器时，分组能把它组织成 "API"、"Web 应用"、"数据管道" 这样的可读结构，而不是一张无穷无尽的清单。

两者都在同一个屏幕上配置：打开一个状态页，在侧边菜单中选择Ressources（资源）——在未启用监控器组（Monitor Groups）的项目中，该入口名称为Moniteurs（监控器）。分组原本有独立页面，现在已合并到此屏幕，旧 URL/groups会直接重定向到这里。

命名建议是本文反复强调的第一原则：资源名应像客户谈论你的产品那样命名——Checkout API，而不是prod-checkout-lb-healthcheck-us-east-1。这是访问者在故障期间回答"问题出在我这还是你们那"的关键一行。

资源屏幕（Ressources Screen）布局

资源屏幕一分为二：

• 左侧：分组浏览器（Group Browser）——分组的树状列表。顶部有Search groups...搜索框，下方有计数器（形如3 groups · 12 resources）。当分组数量超过可视区域时，Show N more of M按钮会揭示剩余部分。
• Top of page（页面顶部）——浏览器中的第一行，存放不属于任何分组的资源。它的提示文案准确说明了用途：访问者最先看到这些资源，它们永远排在所有分组之上。如果页面完全没有分组，右侧面板会显示为All resources。
• 右侧：资源面板（Resources Pane）——显示所选分组的内容。面板头部包含Edit Group（编辑分组）、主按钮Ajouter un moniteur（添加监控器），以及More actions（更多操作）溢出菜单。

卡片头部还有两个按钮：New Group（新建分组）和一个三点菜单，内含Import groups from CSV（从 CSV 导入分组）和Actualiser（刷新）。

空状态（Empty States）会明确指引下一步操作：

• 空分组显示No monitors here yet，附Ajouter un moniteur、Add Multiple按钮，且仅在状态页完全没有分组时显示Create a Group。
• 搜索无结果显示No resources match your search。
• 浏览器为空时说明：分组用于把过长的状态页切分成章节，且支持嵌套。

添加监控器（Add a Monitor）

选择资源要落入的分组（或选择Top of page作为无分组行），点击Ajouter un moniteur。弹出的窗口标题为Add a monitor to {group}，包含两个步骤：Détails du moniteur（监控器详情）和Avancé（高级）。

监控器详情（Détails du moniteur）步骤包含：

如果项目启用了监控器组（Monitor Groups），下拉列表下方会出现Add a Monitor Group instead.链接——点击后Moniteur下拉框会替换为Moniteur Groupe（监控器组）下拉框（占位文案 "Sélectionner le groupe de moniteurs"），链接则切换为Add a Monitor instead.用于切回。当你想让状态页的一行代表多个检查的聚合结果时，就应使用监控器组。

批量添加（Add Multiple）

Add Multiple（在More actions菜单中显示为Add multiple monitors）打开Add Multiple Monitors窗口。两个步骤与单条添加相同，但第一步提供多选的Moniteurs列表而非单个下拉框，且Avancé步骤中选择的展示选项会应用到所有选中的监控器。这是快速搭建一个新页面最高效的方式。

资源的展示选项（Display Options）

Avancé（高级）步骤在单条添加表单与批量添加窗口中完全一致。这里的所有选项按资源生效——同一分组的两个行可以配置成不同的展示方式：

第一步骤的Nom d'affichage（显示名称）（displayName）与Description（描述）（displayDescription）同样属于纯展示范畴——它们永远不会修改监控器本身。

这些字段在数据模型层的定义可以直接在 StatusPageResource 模型 中验证。例如showCurrentStatus的数据库列定义带default: true与isDefaultValueColumn: true（StatusPageResource.ts#L747-L758），showUptimePercent默认false（StatusPageResource.ts#L788-L799），showStatusHistoryChart默认true（StatusPageResource.ts#L870-L881），与文档描述的默认行为完全一致。displayTooltip在模型中是LongText列（StatusPageResource.ts#L706-L717），displayDescription则是 Markdown 列（StatusPageResource.ts#L664-L676），这与"描述支持 Markdown"的界面说明互为印证。

可用性百分比与历史图表（Uptime Percent & History Charts）

Afficher le % de disponibilité和Afficher le graphique de l'historique des états都依赖一个位于别处的页面级设置。该设置位于Pages de statut → votre page → Avancé → Paramètres avancés（状态页 → 你的页面 → 高级 → 高级设置）中的Paramètres de l'historique de disponibilité（可用性历史设置）卡片，字段名为Afficher l'historique de disponibilité (en jours)（显示可用性历史（天数））。它接受 1 到 90 天，默认值 90。

因此操作顺序是：先逐资源开启开关，再为整页一次性设置时间窗口。

精度是一个编辑决策（Precision is an editorial choice）。Sélectionner la précision de disponibilité下拉框提供四个选项，其枚举定义见 UptimePrecision.ts：

小数位越多，看起来越精确——也就越容易为第三位小数争吵。如果发布的是三个九的 SLA，就对齐到三位精度，不要再往上加。

分组拥有自己独立的这些开关副本（见下文），因此一个分组可以显示聚合百分比而其中包含的监控器保持低调，反之亦然。

历史图表柱状条的颜色，以及哪些监控器状态被视为"故障（down）"，都在品牌定制屏幕Page de vue d'ensemble（概览页）中配置，详见 状态页品牌定制与域名。

分组（Groups）

点击New Group打开Create New Status Page Group表单，包含三个步骤：Détails du groupe（分组详情）、Mise en page（布局）和Avancé（高级）。

分组详情（Détails du groupe）：

Avancé（高级）复用了资源的开关，但作用范围是分组级别：

• Afficher l'état actuel du groupe（显示分组当前状态）（showCurrentStatus）——默认开启，在分组标题旁显示一个状态。
• Afficher le % de disponibilité（显示可用性百分比）（showUptimePercent）——默认关闭，开启后会出现Sélectionner la précision de disponibilité（选择精度）。

编辑方式同样统一：面板头部的Edit Group，或浏览器行菜单中的Edit group，都会打开Edit Status Page Group窗口并带Enregistrer les modifications（保存修改）按钮。

面板头部会用小徽章（pills）标示当前生效的设置——Grid、Collapsed by default、Uptime %——无需打开表单即可一览分组配置。

分组模型的字段定义可在 StatusPageGroup.ts 中核对：name是必填ShortText且在同一状态页内唯一（@UniqueColumnBy("statusPageId")，StatusPageGroup.ts#L377-L391），isExpandedByDefault默认true（StatusPageGroup.ts#L612-L623），showCurrentStatus默认true（StatusPageGroup.ts#L700-L711），showUptimePercent默认false（StatusPageGroup.ts#L741-L752），与界面说明完全一致。此外模型还通过@SlugifyColumn("name", "slug")从名称自动生成 slug（StatusPageGroup.ts#L82），并暴露为CrudApiEndpoint(new Route("/status-page-group"))（StatusPageGroup.ts#L81），说明分组管理同样走标准 CRUD API。

管理一个分组（Manage a Group）

浏览器中每行的菜单包含Edit group、Move up、Move down、Afficher l'ID（显示 ID）和Delete group。面板的More actions菜单提供对应的长文本版本——Edit this group、Add a sub group（添加子分组）、Move group up、Move group down、Show group ID、Actualiser（刷新）和Delete this group。

一个未填名称就保存的分组会显示为Untitled group——这通常是个提示，说明你本来想输入点什么。

嵌套分组（Nesting Groups）

分组是可嵌套的：在子分组的Parent Group字段中指定父分组，或使用浏览器中的Add a sub group inside this group动作。表单的帮助文本描述了这种设计的适用形态——例如Entities › Region › Market（实体 › 区域 › 市场）——并说明每个层级都会显示其下方所有内容的聚合状态与可用性。

当一个分组有子分组时，资源面板会显示一行Sub groups（子分组）徽章，直接跳转到每个子分组——无需重新经过浏览器即可遍历整个层级。

嵌套在大页面上尤其有意义：托管服务商的产品之下套区域，分销商的业务单元之下套市场。而对于只有十二个监控器的页面，单一扁平层级反而更友好。

从数据模型看，嵌套通过自引用实现：StatusPageGroup通过parentStatusPageGroupId关联到自己（StatusPageGroup.ts#L282-L347），字段注释明确说明"空值表示顶级分组"。仓库中还包含专门的服务端测试 StatusPageGroupNesting.test.ts 来校验嵌套行为。

列表或网格布局（List or Grid Layout）

Mise en page（布局）步骤定义分组的Mode d'affichage（viewMode），它会改变公开渲染效果。枚举定义见 StatusPageGroupViewMode.ts：

选择Grid后会额外出现四个字段：

• Libellé de l'axe des lignes（行轴标签）——行的维度名称，占位文案Service。
• Valeurs de l'axe des lignes（行轴值）——行本身，通过Add Row逐个添加（占位文案e.g. Auth）。
• Étiquette de l'axe des colonnes（列轴标签）——列的维度，占位文案Region。
• Valeurs de l'axe des colonnes（列轴值）——通过Add Column添加（占位文案e.g. US-East）。

网格分组中的每个监控器随后被放置进一个单元格；因此批量添加窗口在选监控器的同时会要求指定行和列，并复用你自己的轴标签。

先搭好轴再添加监控器。没有行和列的网格分组会显示一个橙色警告，说明在轴存在之前没有地方放置监控器，并附Set up the grid按钮——同时Ajouter un moniteur按钮在轴搭好前会消失。

网格字段在模型中的存储方式也值得注意：rowAxisLabel/columnAxisLabel是短文本列（StatusPageGroup.ts#L866-L920），而rowAxisValues/columnAxisValues是"逗号分隔的标签列表"长文本列，字段注释（StatusPageGroup.ts#L950-L1000）明确指出其决定网格布局中的行列顺序——这就是界面上 Add Row / Add Column 逐个添加的底层存储形式。

排列访问者看到的内容（Ordering）

顺序是显式指定的，而非字母序，可以在三个位置调整：

• 分组内部的资源——直接拖拽行。面板会提示：Drag a row to change the order visitors see（拖拽行以改变访问者看到的顺序）。
• 分组之间的相对顺序——浏览器行菜单中的Move up / Move down，或面板溢出菜单中的Move group up / Move group down。
• 无分组的资源——它们位于Top of page，永远显示在所有分组之上；因此把每个人都会来查看的那个服务放在这里。

两种禁用拖拽的情况。使用Search in {group}...过滤面板会禁用重排——面板显示N of M shown · drag to reorder is off while filtering，此时应清空搜索。网格分组从不支持拖拽排序，因为位置由行/列轴决定。

数据层同样支持显式排序：StatusPageResource和StatusPageGroup模型都定义了order数值列（StatusPageResource.ts#L989-L998、StatusPageGroup.ts#L572-L582），注释为 "Order / Priority of this resource"，即拖拽与 Move up/down 最终写入的就是这个字段。

把用户最常提及的服务放在顶部。故障期间到访的访问者通常读完第一屏就停止滚动。

从 CSV 导入分组（Import Groups from CSV）

手工搭建深层层级十分繁琐。卡片头部的三点菜单提供Import groups from CSV，打开Import Groups from CSV窗口。

完整流程：点击Download CSV Template下载status-page-groups-template.csv，填写后Choose CSV File选择文件，再点Preview Import预览将要创建的内容（此时尚未写入任何数据）。随后Import results（导入结果）表格把每一行标记为Created（已创建）、Failed（失败）或Skipped（跳过），并附原因——坏行不会无声消失。

仅name是必填列。支持的列如下（与导入解析器 StatusPageGroupCsv.ts 中STATUS_PAGE_GROUP_CSV_COLUMNS常量定义一致，StatusPageGroupCsv.ts#L69-L82）：

导入只创建分组，不创建资源——之后再用Ajouter un moniteur或Add Multiple添加监控器。

源码层面的导入逻辑比界面提示更严格，值得展开：

• 布尔列宽容解析：parseBoolean接受true/false、yes/no、1/0等多种写法（StatusPageGroupCsv.ts#L280-L306），其他任何值都视为错误而非静默转为false，避免"off 悄悄变成展开"这类意外。
• 枚举列模糊匹配：parseEnumCell通过normalizeEnumCell去掉非字母数字字符后匹配（StatusPageGroupCsv.ts#L313-L355），因此One Decimal、one-decimal、ONE_DECIMAL均等效；viewMode同理。
• 精度自动填充：当showUptimePercent为 true 而未指定uptimePercentPrecision时，解析器默认填入ONE_DECIMAL，与表单行为一致（StatusPageGroupCsv.ts#L531-L539）。
• 嵌套深度上限 10：MAX_GROUP_NESTING_DEPTH = 10（StatusPageGroupCsv.ts#L34），超过该深度的行会在预览阶段被标记跳过，而不是在写入中途失败。
• 父依赖排序：planStatusPageGroupImport按依赖顺序分批创建——先创建顶级分组，再创建引用它们的子分组，循环引用或父分组缺失的行会被跳过并附明确原因（StatusPageGroupCsv.ts#L590-L699）。
• 网格列误用即报错：在viewMode非Grid的行中填写网格轴列，会被判定为矛盾并报错，而不是悄悄丢弃（StatusPageGroupCsv.ts#L488-L502）。

仓库为这套导入逻辑提供了完整的测试保障：StatusPageGroupCsv.test.ts 钉住解析器行为，StatusPageGroupImportRunner.test.ts 与 StatusPageGroupImportPageInvariants.test.ts 验证运行与页面约束。

延伸阅读

• 状态页概述——什么是状态页，各部件如何组合。
• 状态页品牌定制与域名——logo、favicon、图表颜色，以及把页面挂到自有域名。
• 订阅者与公告——这些资源状态变化时谁会收到通知。
• 公共 API——以编程方式读取状态页数据。
• 事件的状态与严重级别——什么让事件出现在页面上，又怎样消失。

【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime