ServerPulse：给 Halo 站点加一个实时服务器监控页

ServerPulse 是我给 Halo 写的第一个插件，前两天刚上架官方应用商店。启用之后站点会多出一个 /pulse 页面，打开就能看到这台机器的 CPU、内存、磁盘、运行时间、最近两分钟的趋势曲线和硬件详情；Halo 控制台首页也能挂一个同款数据的仪表盘部件。它跑在 Halo 进程里，不用装 Agent、不用另起服务、不用数据库。

一、为什么还要再做一个监控插件

Halo 部署好之后，我大概每周会有一两次想知道「这台机器现在到底忙不忙」——内存是不是快满了、磁盘是不是该清了、站点卡是因为 CPU 还是因为别的。

以往的做法只有两种，都不太顺手：

• SSH 上去敲 top / htop。 数据是准的，但每次开终端、登服务器只为了看三个数字，太麻烦，手机上更没法看。
• 上 Prometheus + Node Exporter + Grafana。 功能强大，可为了看三个百分比要额外跑三四个容器、占几百 MB 内存，对一台只放博客的小机器来说纯属杀鸡用牛刀。

所以 ServerPulse 只做一件事：把这台机器现在的状态，用一个页面干净地摆出来。指标直接在 Halo 进程内读取（底层用 OSHI），不引入任何新组件，也不往外发一个字节的数据。

二、它长什么样

启用插件后访问 https://你的站点/pulse，就是下面这个页面：

页面右上角可以在亮色、暗色、跟随系统之间切换，访客的选择会自己记住。同一台机器切成暗色是这样：

布局从上到下是三层：顶部三项环形指标（处理器、内存、磁盘），中间是最近约 2 分钟的实时趋势曲线，最下面是硬件与系统的明细。整个页面是响应式的，手机上会自然收成一列。

三、能看到哪些指标

其中磁盘使用率优先取系统盘（Windows 的 SystemDrive）或根分区 /；物理磁盘总量会单独展示，避免把多个挂载点重复累加成一个虚高的数字。

四、三步装上

环境要求只有两条：Halo >= 2.21.0、Java 21（这也是 Halo 2.21+ 本身的运行时要求）。

1. 在 Halo 控制台的「插件」页面，从应用商店搜索 ServerPulse 安装，或直接上传插件 JAR。
2. 启用插件。
3. 打开 https://你的站点/pulse。

想让读者能从站点导航直接点进去，在后台「菜单」里加一个指向 /pulse 的自定义链接就行。

五、控制台仪表盘部件

除了独立页面，插件还往 Halo 控制台首页塞了一个部件。添加方式：

/console/dashboard → 右上角「设置」→「添加部件」→「小部件中心」→「服务器」分组 → 保存

部件最花心思的地方是会按卡片的宽高自动换布局——仪表盘可以随意拖拽缩放，塞进去之后不会出现挤成一团或者大片留白：

宽而扁的时候，指标卡横排，趋势图放在右侧：

窄而高的时候，指标改成纵向堆叠，趋势图铺满底部：

中等尺寸用环形仪表卡：

高度很矮的时侯退化成紧凑条形，优先保住数字：

部件右上角的齿轮可以单独配置标题、是否显示运行时间和硬件信息。预览状态下用的是示例数据、不会发请求；真正加到仪表盘之后才按插件设置里的刷新间隔轮询，页面切到后台时会自动暂停。

六、设置项

插件详情页有六项设置，默认值基本可以直接用：

七、访问控制与隐私

监控页默认是仅登录用户可见——毕竟 CPU 型号、操作系统版本、磁盘容量这些信息，等于把服务器家底摆在公网上。三种模式的区别：

• 仅登录用户（默认）：匿名访客打开 /pulse 只看到登录引导，监控接口返回 401。
• 公开访问：任何人都能看到数据。开启前请确认你接受这些硬件信息被公开。
• 指定用户访问：只有被选中的 Halo 用户能看；匿名访客 401，未授权的登录用户 403。

权限层面，插件只申请了 api.serverpulse.halo.run 下 metrics 这一个资源的只读权限，没有写操作、没有数据库、没有外部服务。前端资源全部随 JAR 分发，不加载 CDN、外部字体和统计脚本。页面和部件读的都是同一个接口：

GET /apis/api.serverpulse.halo.run/v1alpha1/metrics

八、几个需要提前知道的限制

• Docker 部署的数值可能失真。 指标从 Halo 所在进程/主机读取，容器里看到的 CPU、内存、进程数取决于 cgroup 配置，可能是宿主机的值。
• 历史曲线只存在内存里。 页面刷新都还在，但 Halo 重启或插件重载之后会清空，最多保留最近约两分钟——它不是时序数据库，也不打算做成长周期监控。
• OSHI 跑不起来时会降级。 某些受限环境里 OSHI/JNA 拿不到硬件信息，页面会提示「部分硬件信息不可用」，同时退回 JVM 基础指标，不影响 Halo 启动。
• 它只读。 看得到状态，但重启服务、清理磁盘这些操作都不在范围内。

九、关于主题

/pulse 默认用插件内置的独立模板 templates/pulse.html。如果你想让监控页跟自己主题的视觉更贴合，可以在主题里放一个同名 pulse.html 覆盖它，插件会优先使用主题模板——需要保留 pulseTheme、apiBase、pluginName、pluginVersion 这几个字段的语义。

✅ 总结：ServerPulse 解决的是一个很小但很具体的问题——不登服务器也能一眼看清这台机器现在怎么样。一个页面、一个控制台部件、零额外依赖、只读权限、数据不出站。如果你也在用 Halo 并且懒得为三个百分比再架一套监控栈，装上试试就好。

应用商店：https://www.halo.run/store/apps/app-2abwvlzx　｜　开源仓库：litxiaoxi/halo-plugin-server-pulse（MIT）

用下来有任何问题或者想要的功能，欢迎在仓库提 issue。