监控

ServerBee 通过统一的 Web 面板实时监控所有已接入的服务器。指标经 WebSocket 流式推送，无需轮询即可即时更新，同时支持历史数据查询和趋势分析。

仪表盘概览

登录管理面板后，仪表盘页面会一目了然地展示所有已注册服务器的实时状态：

• 顶部统计卡片 -- 在线 / 离线 / 总数、CPU 平均使用率、内存平均使用率、总带宽
• 在线/离线状态 -- 带颜色指示器
• 环形图表网格 -- 每张卡片包含四个环形图（CPU、内存、磁盘、月度流量配额使用率）。未配置配额时流量环退化为显示累计传输字节；若设置了计费周期，底部还会显示剩余天数提示
• 磁盘 I/O 吞吐 -- 按设备聚合后的读/写速率，与网络速率并列实时显示
• 网络吞吐 -- 上行 / 下行速率
• 负载趋势 -- load5 · load15 紧邻 load1，以及 uptime / swap / 进程数 / TCP / UDP 汇总行
• 地区和国旗 -- 启用 GeoIP 时显示

所有数据通过 WebSocket 驱动，无需手动刷新即可实时更新。服务器按分组组织并依据权重排序。你可以在此视图中筛选、搜索和批量操作服务器。

如需创建面向不同场景的运维视图，可以使用 仪表盘与组件 创建额外仪表盘布局，包含图表、地图、服务状态、Markdown 说明和可用性时间线等组件。

GeoIP 显示

地区/国家标签和 Server Map 组件需要 GeoIP 数据。你可以通过 geoip.mmdb_path 配置自定义 MaxMind 兼容 MMDB 文件，也可以在 Settings → GeoIP Database 下载 DB-IP Lite 数据库。状态查询端点为 GET /api/geoip/status，管理员可通过 POST /api/geoip/download 触发下载。

实时指标推送

浏览器端通过 /api/ws/servers 连接 WebSocket 后，会收到以下消息：

因此仪表盘会实时更新，无需刷新页面或设置轮询间隔。

指标类型

Agent 每 3 秒采集并上报以下指标。Server 在 Welcome 消息中下发这一固定的 report_interval：

系统资源

网络指标

系统负载

连接和进程

环境指标

磁盘 I/O 指标

Agent 在所有主要平台上采集磁盘读写吞吐量：

Linux：直接读取 /proc/diskstats。仅跟踪物理块设备（如 sda、nvme0n1），排除虚拟设备（loop*、dm-*、ram*、sr*）和分区。DiskIo.name 为块设备名。

macOS / Windows：使用 sysinfo Disk::usage() API，以挂载点路径（如 /、/home、C:\）作为 key。提供 per-mount-path 语义而非 per-physical-disk。已知限制：macOS APFS 下共享同一物理磁盘的多个卷可能报告重叠的 I/O 计数。

Agent 启动后的首次采样建立基线并上报空列表，后续采样基于增量计算速率。

磁盘 I/O 数据以 JSON 列（disk_io_json）存储在 records 和 records_hourly 表中。小时聚合器按设备计算平均读写速率。

GPU 指标（可选）

启用 GPU 监控（enable_gpu = true）后，每块 GPU 独立采集以下指标：

服务器信息

除了周期性指标外，每个 Agent 在首次连接时还会上报静态系统信息：

• CPU 名称、核心数和架构
• 操作系统和内核版本
• 内存、Swap 和磁盘总容量
• IPv4 和 IPv6 地址
• 虚拟化类型（KVM、Xen、Docker 等）
• Agent 版本

这些信息显示在服务器详情页并存储到数据库中。

历史数据和图表

ServerBee 以两种粒度存储指标记录：

分钟级原始记录

• 由 RecordWriter 后台任务每 60 秒写入一次
• 默认保留 7 天（可通过 retention.records_days 配置）
• 每条记录捕获某一时间点的全部指标值

小时级聚合记录

• 由 Aggregator 后台任务计算
• 取每小时内所有原始记录的平均值
• 默认保留 90 天（可通过 retention.records_hourly_days 配置）
• 用于长期趋势可视化

仪表盘图表会根据所选时间范围自动在原始记录和小时记录之间切换。

GPU 记录

GPU 指标按设备粒度单独存储在专用表中。每条记录包含设备索引、名称、显存、利用率和温度，默认保留 7 天（可通过 retention.gpu_records_days 配置）。

数据查询策略

历史指标通过 REST API 查询：

GET /api/servers/:id/records?from=2026-03-13T00:00:00Z&to=2026-03-14T00:00:00Z&interval=auto

interval 参数控制数据粒度：

数据存储层级

Agent 上报 (每 3 秒)
  --> 内存缓存: 仅保留每台服务器最新一份（实时推送用）
  --> 每 1 分钟: 写入 records 表（分钟级记录）
  --> 每 1 小时: 聚合写入 records_hourly 表（平均值）

服务器详情

每台服务器都有一个详情页，展示以下内容：

• 基本信息 -- 操作系统、CPU 型号、内存总量、IP 地址、地区、Agent 版本
• 实时流式图表（默认模式） -- 展示 WebSocket 推送的实时指标
• 历史趋势图表 -- 切换到 1h / 6h / 24h / 7d / 30d 查询数据库中的历史记录
• 磁盘 I/O 图表 -- 合并和分盘两种视图（全平台、历史模式）
• 90 天可用性时间线 -- 按天展示可用性状况的彩色条形图
• GPU 面板 -- 如果该服务器上报了 GPU 数据，显示各 GPU 的利用率和显存图表（仅历史模式）
• 流量统计 -- 网络累计流量的统计信息
• 服务器元数据 -- 分组、标签、备注、定价
• 操作 -- 终端访问、编辑、删除

实时图表模式

服务器详情页默认为实时模式，图表展示 WebSocket 推送的实时数据流：

• 数据来源：通过实时服务器目录订阅 BrowserMessage::Update 事件，自动累积数据点
• 更新频率：约 3 秒一次（与 Agent 上报间隔一致）
• 缓冲区大小：增长到 250 个数据点后，裁剪为最新的 200 个点
• 去重机制：基于服务端 last_active 时间戳过滤重复事件
• 可用图表：CPU、内存、磁盘、网络入/出、负载（1 分钟）
• 时间轴格式：第一个刻度显示 HH:mm:ss，后续刻度显示 mm:ss

实时模式目前不提供温度、GPU 和磁盘 I/O 图表。WebSocket 的 BrowserMessage::Update 消息已在 LiveMetrics 中携带磁盘读写汇总速率，但详情页实时图表模型尚未映射这些字段。切换到历史视图可查看温度、GPU 和分盘 I/O 数据。

磁盘 I/O 图表

当存在历史磁盘 I/O 数据时，服务器详情页会显示磁盘 I/O 图表，支持两种视图：

• 合并视图 (Merged) -- 所有物理磁盘的读写吞吐量汇总
• 分盘视图 (Per Disk) -- 每块物理磁盘的独立图表（如 sda、nvme0n1）

两种视图均以面积图展示读取速率（蓝色）和写入速率（绿色）。缺失的数据点会自动补零，保持时间轴连续。

可用性时间线

服务器详情页包含一个可用性卡片，展示 90 天的可用性时间线。每天显示为一根彩色条：

• 绿色 -- 100% 可用
• 黄色 -- 低于黄色阈值（可用性下降）
• 红色 -- 低于红色阈值（严重故障）
• 灰色 -- 无数据

可用性数据通过 GET /api/servers/{server_id}/uptime-daily?days=90 查询。端点返回每天一条 UptimeDailyEntry，包含 date、online_minutes、total_minutes 和 uptime_percent 字段。缺失日期会自动补零。

数据保留策略

ServerBee 自动清理过期数据，由后台任务每小时执行一次：

修改保留策略示例：

[retention]
records_days = 14          # 分钟级数据保留 14 天
records_hourly_days = 365  # 小时级数据保留 1 年

磁盘空间估算

数据库增长取决于服务器数量、启用的数据写入功能、采样间隔和保留设置。容量规划请以存储与容量规划为准，其中提供了 2026 年 4 月的实测数据、统一的 30 天基线、功能乘数和 WAL 预留建议。

服务器分组和管理

服务器分组

你可以将服务器按用途、地区或其他维度进行分组：

• 创建分组并设置排序权重
• 将服务器分配到不同分组
• 仪表盘按分组展示服务器列表
• 排序权重控制显示顺序（权重越小位置越靠前）
• 未分组的服务器显示在默认区域

分组可以表示环境（生产、预发）、地区（US-East、EU-West）、服务商（AWS、Hetzner）或任何适合你需求的组织结构。

服务器标签

除了分组外，还可以为服务器添加多个标签（Tag），用于更灵活的分类和筛选。标签是多对多关系，一台服务器可以有多个标签。

服务器管理操作

数据流

Agent                  Server                    浏览器
  |                      |                         |
  |-- Report (3s) ------>|                         |
  |                      |-- 缓存到 AgentManager   |
  |                      |                         |
  |                      |-- RecordWriter (60s) -->|
  |                      |   写入 SQLite           |
  |                      |                         |
  |                      |-- Update (广播) ------->|
  |                      |                     实时 UI
  |                      |                         |
  |                      |-- Aggregator (每小时) ->|
  |                      |   小时级平均值          |
  |                      |                         |
  |                      |-- Cleanup (每小时) ---->|
  |                      |   删除过期记录          |

Agent 每 3 秒上报一次。Server 将最新一份上报缓存在内存中，并立即广播给已连接的浏览器。每 60 秒，所有缓存的上报会批量写入 SQLite。两个独立的每小时任务分别将原始记录聚合为小时级汇总，并根据保留策略清理过期数据。

网络质量视图

/network 总览页和 /network/{server_id} 详情页会汇总每台服务器已配置的探测目标。

• 新分配的目标会立即显示，即使首条探测结果尚未写入
• 尚无探测数据的目标会显示为空状态，而不是从汇总中消失
• 总览页搜索框会跟随当前界面语言显示占位文案

时间范围选择器

时间范围栏提供以下选项：

从实时模式切换到历史视图时，系统自动启用 REST API 查询从数据库加载数据。切换回实时模式时，立即显示已累积的缓冲区数据（即使在查看历史数据期间，实时数据也会在后台持续累积）。

流量统计

ServerBee 以小时和天为粒度跟踪网络流量，支持按计费周期查询用量并提供周期末预测能力。

工作原理

流量统计集成在现有的指标记录管道中：

1. Agent 每 3 秒上报累计网络字节数（net_in_transfer、net_out_transfer）
2. RecordWriter 计算连续上报之间的增量，累积到小时级流量记录
3. Aggregator 将小时数据汇总为日级别（通过 scheduler.timezone 配置感知时区）
4. Cleanup 任务根据保留策略清理过期的流量记录

流量 API

通过 GET /api/servers/{id}/traffic 查询任意服务器的流量统计，返回内容包括：

• 周期总量 -- 当前计费周期的入站/出站总字节数
• 使用百分比 -- 已用流量占服务器流量限额的百分比（如已配置）
• 预测 -- 基于当前消耗速率估算的周期末总用量
• 日明细 -- 计费周期内每日流量总量
• 小时明细 -- 今日每小时流量明细

计费周期

流量按计费周期查询，周期由以下参数决定：

• billing_cycle -- 周期类型：monthly（默认）、quarterly 或 yearly
• billing_start_day -- 计费周期起始日（1-28，默认 1）

例如，billing_start_day = 15 且 billing_cycle = monthly 时，周期从每月 15 日开始到下月 14 日。

前端展示

服务器详情页显示可折叠的流量卡片，包含：

• 进度条 -- 可视化显示已用流量占限额的比例
• 日图表 -- 柱状图展示周期内每日入站/出站流量
• 小时图表 -- 柱状图展示今日每小时流量
• 预测 -- 预计周期末总用量

数据保留

调度时区

日级流量聚合遵循 scheduler.timezone 设置。将其设为你的计费时区（如 Asia/Shanghai），确保日统计与你的服务商日边界一致。

Docker 容器监控

ServerBee 支持实时 Docker 容器监控。当 Agent 能够访问 Docker daemon 时，此功能可用。需要 docker 能力（CAP_DOCKER），该能力默认关闭。能力由 Agent 拥有 —— 在 Agent 主机的 [capabilities] allow 列表中加入 docker（或 --allow-cap docker）并重启 Agent。见 功能开关。

概览

Docker 监控页面展示：

• 概览卡片 -- 运行中/已停止容器数量、总 CPU 使用率、总内存使用量、Docker 版本
• 容器列表 -- 可搜索、可过滤的表格，包含名称、镜像、状态、CPU%、内存、网络 I/O
• 事件时间线 -- 容器生命周期事件（start、stop、die、create、destroy），按时间倒序排列
• 网络弹窗 -- Docker 网络列表，包含驱动、作用域和容器数量
• 卷弹窗 -- Docker 卷列表，包含驱动、挂载点和创建时间

容器详情

点击任意容器行可查看：

• 容器信息 -- 镜像、状态、端口、创建时间、容器 ID
• 统计卡片 -- CPU 使用率、内存（含进度条）、网络 I/O、块 I/O
• 日志流 -- 实时日志输出：
  • stdout 白色文本，stderr 红色文本
  • Follow 开关控制自动滚动
  • Clear 按钮清空日志
  • 连接状态指示器（Connected/Disconnected）

工作原理

1. 浏览器导航到 Docker 页面时，通过 WebSocket 发送 DockerSubscribe 消息
2. Server 指示已连接的 Agent 启动 Docker 监控
3. Agent 使用 bollard Docker API 客户端轮询容器和统计数据
4. 更新实时广播到订阅的浏览器
5. 当所有浏览器离开 Docker 页面时，监控自动停止（基于 viewer 引用计数）

容器日志使用专用 WebSocket 端点（/api/ws/docker/logs/{server_id}），通过 subscribe/unsubscribe 协议实现按容器的日志流。

数据保留

容器统计数据和日志不持久化存储，仅实时流式传输。

网络质量监控

ServerBee 内置了网络质量监控系统，通过各 Agent 对网络目标发起探测，可视化延迟、丢包率和异常情况。

预设目标

96 个预设探测目标嵌入在服务端二进制中（不存储在数据库）：

• 中国电信 -- 31 个省级节点（TCP 探测，使用 Zstatic CDN）
• 中国联通 -- 31 个省级节点（TCP 探测，使用 Zstatic CDN）
• 中国移动 -- 31 个省级节点（TCP 探测，使用 Zstatic CDN）
• 国际节点 -- Cloudflare (1.1.1.1)、Google DNS (8.8.8.8)、AWS Tokyo（ICMP 探测）

中国节点使用域名（{省代码}-{运营商代码}-v4.ip.zstaticcdn.com:80），DNS 自动解析到最新的 CDN 节点 IP，无需手动维护 IP 列表。

预设目标为只读，不可编辑或删除。你也可以通过设置页创建自定义目标。

配置

前往 设置 > 网络探测 进行配置：

• 目标管理 -- 查看所有 96 个预设目标（带锁图标和运营商标签），管理自定义目标（创建/编辑/删除）
• 全局设置 -- 探测间隔（30-600 秒，默认 60）、每轮发包数（5-20，默认 10）、新服务器默认分配的探测目标
• 单服务器目标 -- 通过网络详情页的「管理目标」弹窗，为每台服务器分配最多 20 个探测目标

网络总览页

/network 页面为每台服务器展示一张卡片，包含：

• 目标数量和平均延迟
• 可用性百分比
• 异常数量及严重性指示

网络详情页

点击服务器卡片进入 /network/:serverId，包含：

• 时间范围选择 -- 实时、1h、6h、24h、7d、30d
• 目标卡片 -- 每个目标的延迟和丢包率，可切换显示/隐藏
• 多线延迟图表 -- 每个目标一条彩色线，带时间戳 Tooltip
• 异常摘要表 -- 高延迟、高丢包、不可达事件
• 统计栏 -- 综合平均延迟、可用性百分比、目标数量
• CSV 导出 -- 下载选定时间范围的探测数据

Traceroute

网络详情页可以从选中的 Agent 对目标主机或 IP 发起 Traceroute，用于排查路由变化和丢包问题。

• 需要 Agent 的 effective CAP_PING_ICMP 能力。
• 目标只允许字母、数字、点、连字符和冒号。
• Dialog 提供 ICMP / UDP / TCP 三种探测协议下拉选择。
• 默认跑 5 轮，每轮一次增量更新通过 WebSocket 推送到浏览器，表格实时填充： Hop / IP / 主机名 / ASN / 丢包率 / Best / Avg / Worst / Jitter / StdDev。
• ECMP 多路径时同一 TTL 会有多个 IP，第一行显示主 IP，悬停 +N chip 查看其他 IP。
• 已完成的 Traceroute 自动保存到本地 SQLite，可以在 dialog 历史区点击切换查看； 管理员可以删除单条或一键清空。
• 触发 trace 需要管理员权限；只读用户能浏览历史，但不能发起新 trace 或删除记录。

权限

ServerBee Agent 现在内嵌 trippy-core 直接发起 raw ICMP/UDP/TCP 包， 不再依赖系统的 traceroute / mtr 二进制。但 raw socket 仍需要操作系统级权限：

权限不足时 Traceroute 会立刻返回带平台对应安装提示的错误消息，不需要重启 Agent。

API 流程

POST   /api/servers/{id}/traceroute          { target, protocol? }   → { request_id }
GET    /api/servers/{id}/traceroute/{rid}    → 最新快照（含 protocol/started_at/round/total_rounds 等完整字段）
GET    /api/servers/{id}/traceroute          → 该服务器的历史记录摘要列表，按时间倒序
DELETE /api/servers/{id}/traceroute/{rid}    → 删除单条（admin）
DELETE /api/servers/{id}/traceroute          → 清空全部（admin）

WebSocket 推送 BrowserMessage::TracerouteUpdate 携带每轮增量结果。客户端在断开重连时可通过 GET 单条接口拉取最新累计快照。

数据保留

网络探测记录采用与系统指标相同的两级存储：

• 原始记录 -- 保留 7 天（可通过 retention.network_probe_days 配置）
• 小时聚合 -- 保留 90 天（可通过 retention.network_probe_hourly_days 配置）

告警集成

两种告警规则类型可用于网络质量：

• network_latency -- 当平均延迟超过阈值时触发
• network_packet_loss -- 当丢包率超过阈值时触发