最近，我开发了一款插件——在线显示

https://www.halo.run/store/apps/app-ion2qhko

实时连接的力量：Halo 统计插件 Online 现已上线

在运营个人博客时，我们往往会关注后台的访问量。但传统的统计（如百度统计、Google Analytics）通常有延迟，且无法让读者直观感受到“此时此刻”还有谁在陪着我。

为了让 Halo 博客更具生命力和互动感，我开发了 Online 监控插件。它不仅能让你实时掌握站点的脉搏，更能让你的读者感受到社区的活跃。

🚀 为什么选择 Online 插件？

1. 毫秒级感知的“生命力”

通过 WebSocket 技术，插件可以实现误差不超过 15 秒的实时在线人数统计。当有人进入你的博客，后台和前端都能瞬间感知。

2. 强大的监控看板

插件在后台提供了一个直观的监控中心，无需跳转外部网站，即可查看：

  • 全站总人数：当前在线的真实访客。

  • 24 小时峰值：记录过去一天中最热闹的时刻。

  • 活跃页面排行：哪篇文章正在被热读？一眼便知。

3. 高度自定义与开放

无论你是想低调地在后台分析数据，还是想高调地展示在首页，插件提供的 数据公开性设置 和 标准 API 接口 都能满足你。

🛠️ 用户使用手册

安装与配置

  1. 安装：在 Halo 应用市场搜索 Online 或访问插件地址下载安装。

  2. 前置条件：确保你的主题模板中包含 <halo:footer /> 标签（通常在 layout.html 的 </body> 前），这是脚本注入的关键。

  3. 核心设置：

    • 清理频率：建议设置为 30-60 秒，自动踢掉非活跃连接。

    • 白名单：如果你使用了 FRP 或 Cloudflare 代理，请确保将相关域名 /IP 加入白名单，防止 WebSocket 连接失败。

👨‍💻 开发与进阶文档

如果你是主题开发者，或者想通过代码自定义展示样式，Online 插件提供了极简的接入方式。

1. 快速获取在线人数

你可以直接通过 Fetch API 调用插件暴露的接口：

fetch('/apis/online-user.zyx2012.cn/v1alpha1/stats/summary')
  .then(res => res.json())
  .then(data => {
    console.log('当前在线：', data.total);
    console.log('活跃页面：', data.activePages);
  });

2. 监听前端事件（进阶）

为了避免页面加载瞬间数据显示为 0，建议监听插件派发的自定义事件：

window.addEventListener("online-monitor:registered", function () {
  // 当 WebSocket 注册成功后，再触发数据拉取逻辑
  refreshOnlineCounter();
});

🔍 技术实现要点（简写）

插件的核心架构非常精简：

  • 前端注入：利用 TemplateFooterProcessor 无感注入客户端脚本 client.js。

  • 长连接维护：基于 WebSocket 建立双向通信，通过 pathname 实时同步用户的浏览路径。

  • 后端处理：PageOnlineHandler 负责在内存中维护会话映射表，动态计算各 URI 的热度值。

注意：由于性能考虑，目前的“24 小时峰值”暂存于内存中，插件重启后会重置。

🎯 计划中的改进

  • 增加更丰富的历史数据统计图表。

  • 支持主题模板变量直接注入，免去手动 Fetch 的麻烦。

  • 自动识别文章页面 URL 并添加标题显示

希望这款插件能为你的 Halo 博客带来更多生机。如果你在使用中遇到问题，欢迎在 GitHub 或评论区向我反馈！