# 公开状态页

> 发布包含实时指标、事件公告、维护窗口和可用性历史的公开健康状态页。

URL: https://docs.serverbee.app/zh/docs/status-page

ServerBee 提供一个公开状态页，地址为 `https://your-server/status`。它无需认证即可访问，方便你向用户或相关方公示服务健康状态。

页面展示管理员选定的服务器和模块，数据来自公开端点 `GET /api/status/config` 和 `GET /api/status`。

## 页面展示内容 [#页面展示内容]

* 在线/总服务器数量。
* 每台选中服务器的在线/离线状态和分组标签。
* 在线服务器的实时指标：CPU、内存、Swap、磁盘、磁盘 I/O、网络速率/流量、负载、连接数、uptime。
* 每台服务器的 90 天可用性时间线。
* 已配置的公开备注。
* 可选模块：服务器详情、网络质量、IP 质量、事件公告、维护窗口。

IP 地址、主机名、网卡等敏感标识会在 API 层脱敏，不会出现在公开页面上。

## 配置状态页 [#配置状态页]

在 **Settings → Status Page** 中配置。状态页是单例：只有一个页面，原地编辑，而非按 slug 创建多个。

| 设置       | API 字段                    | 说明               |
| -------- | ------------------------- | ---------------- |
| 启用       | `enabled`                 | 禁用后公开页面不返回数据     |
| 标题       | `title`                   | 公开页面标题           |
| 描述       | `description`             | 可选介绍文本           |
| 服务器      | `server_ids`              | 页面展示的服务器         |
| 默认布局     | `default_layout`          | `list` 或 `grid`  |
| 显示服务器详情  | `show_server_detail`      | 允许下钻查看单台服务器详情    |
| 显示网络     | `show_network`            | 显示网络质量模块         |
| 显示 IP 质量 | `show_ip_quality`         | 显示 IP 质量模块       |
| 显示事件     | `show_incidents`          | 显示事件公告模块         |
| 显示维护     | `show_maintenance`        | 显示维护窗口模块         |
| 黄色可用性阈值  | `uptime_yellow_threshold` | 低于该百分比的日期显示为降级   |
| 红色可用性阈值  | `uptime_red_threshold`    | 低于该百分比的日期显示为严重故障 |

### 管理 API [#管理-api]

| 方法  | 路径                 | 说明      |
| --- | ------------------ | ------- |
| GET | `/api/status-page` | 读取状态页配置 |
| PUT | `/api/status-page` | 更新状态页配置 |

更新示例：

```json
{
  "title": "Production Status",
  "description": "Public health for production services",
  "server_ids": ["server-id-1", "server-id-2"],
  "default_layout": "grid",
  "show_server_detail": true,
  "show_network": true,
  "show_incidents": true,
  "show_maintenance": true,
  "enabled": true,
  "uptime_yellow_threshold": 99.9,
  "uptime_red_threshold": 95
}
```

## 公开 API [#公开-api]

以下端点无需认证，是公开页面的数据来源：

| 方法  | 路径                                      | 说明                |
| --- | --------------------------------------- | ----------------- |
| GET | `/api/status/config`                    | 页面元数据和显示选项        |
| GET | `/api/status`                           | 选中服务器的状态、实时指标和可用性 |
| GET | `/api/status/servers/{id}`              | 单台服务器详情           |
| GET | `/api/status/servers/{id}/metrics`      | 单台服务器的时序指标        |
| GET | `/api/status/servers/{id}/uptime-daily` | 单台服务器的 90 天每日可用性  |
| GET | `/api/status/network`                   | 网络质量概览            |
| GET | `/api/status/network/{id}`              | 单台服务器网络质量详情       |
| GET | `/api/status/ip-quality`                | IP 质量概览           |
| GET | `/api/status/incidents`                 | 活动和近期事件           |
| GET | `/api/status/maintenances`              | 活动和计划中的维护窗口       |

每个服务器条目包含 `id`、`name`、`group_name`、地区/国家、`os`、`online`、`in_maintenance`、`uptime_percent` 和 `uptime_daily`。

## 可用性时间线 [#可用性时间线]

每台服务器展示 90 天可用性时间线，每根条代表一天：

* **绿色** -- 健康可用性。
* **黄色** -- 低于黄色阈值。
* **红色** -- 低于红色阈值。
* **灰色** -- 无数据。

可用性数据来自 `uptime_daily` 表，由服务端后台聚合任务生成。缺失日期会自动补齐，保证时间线连续。

## 事件公告（Incidents） [#事件公告incidents]

事件公告用于公开说明故障或服务降级，可选关联到指定服务器。

### 字段 [#字段]

| 字段                | 说明                                                     |
| ----------------- | ------------------------------------------------------ |
| `title`           | 事件标题                                                   |
| `status`          | `investigating`、`identified`、`monitoring` 或 `resolved` |
| `severity`        | `minor`、`major` 或 `critical`                           |
| `server_ids_json` | 可选，受影响服务器                                              |
| `is_public`       | 是否在公开状态页展示                                             |

一个事件可以包含多条 update，每条 update 有自己的 `status` 和 `message`。添加 update 会记录消息，并把事件状态更新为该 update 的状态。状态变为 `resolved` 时会设置 `resolved_at`。

### API [#api]

| 方法     | 路径                            | 说明           |
| ------ | ----------------------------- | ------------ |
| GET    | `/api/incidents`              | 列出事件；支持按状态过滤 |
| POST   | `/api/incidents`              | 创建事件         |
| PUT    | `/api/incidents/{id}`         | 更新事件         |
| DELETE | `/api/incidents/{id}`         | 删除事件         |
| POST   | `/api/incidents/{id}/updates` | 添加事件更新       |

## 维护窗口 [#维护窗口]

维护窗口用于公告计划维护，并在活动期间抑制相关服务器的告警通知。

### 字段 [#字段-1]

| 字段                | 说明                       |
| ----------------- | ------------------------ |
| `title`           | 维护标题                     |
| `description`     | 可选详情                     |
| `start_at`        | UTC 开始时间                 |
| `end_at`          | UTC 结束时间，必须晚于 `start_at` |
| `server_ids_json` | 可选，受影响服务器                |
| `is_public`       | 是否在公开状态页展示               |
| `active`          | 是否启用该维护窗口                |

### API [#api-1]

| 方法     | 路径                       | 说明     |
| ------ | ------------------------ | ------ |
| GET    | `/api/maintenances`      | 列出维护窗口 |
| POST   | `/api/maintenances`      | 创建维护窗口 |
| PUT    | `/api/maintenances/{id}` | 更新维护窗口 |
| DELETE | `/api/maintenances/{id}` | 删除维护窗口 |

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

  <Card title="告警与通知" href="/zh/docs/alerts" />

  <Card title="API 参考" href="/zh/docs/api-reference" />
</Cards>