# 仪表盘与组件

> 使用可拖拽组件和可复用布局构建自定义监控仪表盘。

URL: https://docs.serverbee.app/zh/docs/dashboards

ServerBee 仪表盘由可配置组件组成。你可以保留默认总览仪表盘，也可以按地区、团队或用途创建多个仪表盘，并设置一个作为所有用户默认打开的仪表盘。

## 管理仪表盘 [#管理仪表盘]

在首页顶部的仪表盘切换器中可以：

* 切换不同仪表盘
* 创建新仪表盘
* 重命名仪表盘
* 删除不再需要的仪表盘
* 将某个仪表盘设为默认

如果系统中还没有仪表盘，ServerBee 会自动创建第一个默认仪表盘。已经是默认的仪表盘不能直接取消默认；请把另一个仪表盘设为默认。

## 编辑布局 [#编辑布局]

1. 打开一个仪表盘。
2. 点击 **Edit**。
3. 从组件选择器添加组件。
4. 拖拽组件调整位置。
5. 在组件的最小/最大尺寸约束内调整大小。
6. 配置组件数据源和标题。
7. 点击 **Save**。

布局以网格坐标保存：`grid_x`、`grid_y`、`grid_w`、`grid_h`，组件设置保存为 JSON。保存时会做差异更新：已有组件更新，新组件插入，从布局中移除的组件会被删除。

## 组件类型 [#组件类型]

| 组件                 | 分类 | 典型用途                                 |
| ------------------ | -- | ------------------------------------ |
| `stat-number`      | 实时 | 展示一个全局汇总指标（服务器数量、平均 CPU/内存、总带宽或健康状态） |
| `metric-card`      | 实时 | 以彩色卡片展示单台服务器的多个关键指标                  |
| `server-cards`     | 实时 | 展示选中服务器的紧凑卡片                         |
| `gauge`            | 实时 | 用仪表盘形式展示某台服务器的一个指标                   |
| `line-chart`       | 图表 | 展示单台服务器单一指标的历史曲线                     |
| `multi-line`       | 图表 | 对比多台服务器的同一指标                         |
| `top-n`            | 实时 | 按某个指标给服务器排行                          |
| `alert-list`       | 状态 | 展示活动或最近告警状态                          |
| `service-status`   | 状态 | 展示服务监控状态                             |
| `traffic-bar`      | 图表 | 展示单台服务器流量使用情况                        |
| `disk-io`          | 图表 | 展示磁盘读写吞吐历史                           |
| `server-map`       | 状态 | 安装 GeoIP 后在地图上展示服务器位置                |
| `markdown`         | 状态 | 用 Markdown 添加说明、Runbook 或链接          |
| `uptime-timeline`  | 状态 | 展示选中服务器的可用性条形时间线                     |
| `network-latency`  | 图表 | 展示网络延迟探测历史曲线                         |
| `network-quality`  | 实时 | 展示网络质量评分与实时指标                        |
| `network-overview` | 状态 | 跨服务器汇总网络质量概览                         |

## 常见组件配置 [#常见组件配置]

多数组件设置保存在 `config_json` 中。常见字段包括：

| 字段            | 使用场景           | 含义                            |
| ------------- | -------------- | ----------------------------- |
| `server_id`   | 单服务器组件         | 要查询的服务器 ID                    |
| `server_ids`  | 多服务器组件         | 要包含的服务器 ID 列表                 |
| `metric`      | 指标组件           | 指标键，例如 CPU、内存、磁盘、流量或负载        |
| `hours`       | 历史组件           | 图表回看时间窗口                      |
| `interval`    | 历史组件           | 数据粒度（`raw`、`hourly` 或 `auto`） |
| `monitor_ids` | Service Status | 要展示的服务监控 ID                   |
| `content`     | Markdown       | Markdown 内容                   |

## GeoIP 与服务器地图 [#geoip-与服务器地图]

Server Map 组件需要 GeoIP 数据。你可以：

* 通过 `geoip.mmdb_path` 配置自定义 MaxMind 兼容 MMDB 文件，或
* 在 **Settings → GeoIP Database** 中下载 DB-IP Lite 数据库。

缺少 GeoIP 数据时，组件会显示安装提示。

## 性能与组件容量 [#性能与组件容量]

仪表盘采用视口懒挂载（IntersectionObserver）：屏幕外的组件不会在初次渲染时挂载图表，所以冷启动开销几乎不随组件数量增长。但**滚动过程**中，进入视口的图表会同步测量容器与 SVG 文本尺寸，高密度涌入时会触发强制回流并造成滚动卡顿。

实测参考（桌面 Chrome，未开 CPU/网络限流，**后端在本地**，每个组件按 line-chart / gauge / multi-line / disk-io 混排）：

| 组件数     | 冷加载 LCP  | 滚动表现                  |
| ------- | -------- | --------------------- |
| ≤ 30    | \~360 ms | 流畅                    |
| 30 – 60 | \~360 ms | 可用，密集滚动时略有顿挫          |
| > 60    | \~360 ms | 滚动期间明显卡顿，主线程被图表布局测量占用 |

如果 Server 部署在公网远端，冷加载 LCP 会随**首屏内**图表数量增长——每个图表都要等自己的历史查询返回才能绘制，40 组件仪表盘经公网实测首屏为秒级，而非 \~360 ms。上表的滚动特征仍然适用。

**推荐范围**：

* **舒适区**：单仪表盘 ≤ **30 个组件**。
* **可接受**：30 – 60 个组件。如果业务必须超过，请优先放置静态/非图表组件（`markdown`、`alert-list`、`service-status`、`stat-number`），把成本较高的图表组件（`line-chart`、`multi-line`、`disk-io`、`traffic-bar`、`gauge`）控制在 30 个以内。
* **不推荐**：单仪表盘 > 60 个组件 —— 建议按团队 / 区域 / 场景拆成多个仪表盘。

如果你确实需要在一个仪表盘里展示几十个图表，把它们**分组放在同一区域**而不是均匀散布在长页面里，这样滚动时进入视口的图表批次更少，瞬时压力更低。

## API [#api]

| 方法     | 路径                        | 说明              |
| ------ | ------------------------- | --------------- |
| GET    | `/api/dashboards`         | 列出仪表盘           |
| GET    | `/api/dashboards/default` | 获取默认仪表盘，必要时自动创建 |
| GET    | `/api/dashboards/{id}`    | 获取仪表盘及其组件       |
| POST   | `/api/dashboards`         | 创建仪表盘           |
| PUT    | `/api/dashboards/{id}`    | 更新元数据和/或组件      |
| DELETE | `/api/dashboards/{id}`    | 删除仪表盘           |

更新请求示例：

```json
{
  "name": "Production",
  "is_default": true,
  "widgets": [
    {
      "widget_type": "stat-number",
      "title": "Web CPU",
      "config_json": {
        "server_id": "server-id",
        "metric": "cpu",
        "unit": "%"
      },
      "grid_x": 0,
      "grid_y": 0,
      "grid_w": 2,
      "grid_h": 1,
      "sort_order": 0
    }
  ]
}
```

<Cards>
  <Card title="监控功能" href="/zh/docs/monitoring" />

  <Card title="服务监控" href="/zh/docs/service-monitors" />

  <Card title="存储与容量规划" href="/zh/docs/storage-sizing" />
</Cards>