SHM 使用攻略 ：不窥探用户隐私的数据收集工具

这玩意儿是干嘛的？

如果你开发了一个开源软件，让用户自己部署到他们自己的服务器上（就是那种 self-hosted 的应用），你肯定想知道：有多少人在用？他们用的什么版本？有没有出问题？

但问题来了——因为是用户自己部署的，你根本看不到任何数据。就像把孩子送出去了，生死未卜。

SHM 就是解决这个痛点的。它能帮你收集一些不涉及用户隐私的统计数据，比如：

• 有多少个实例在跑
• 每个实例用的什么版本
• 你定义的业务指标（比如创建了多少文档、处理了多少任务）
• 系统信息（CPU、内存、操作系统）

关键是，它不会偷窥用户的个人信息，所有数据都是加密签名的，而且用户可以随时关掉。

---

集成流程

假设你有个 Node.js 应用，想加上 SHM：

第 1 步：装 SDK

npm install @btouchard/shm-sdk

第 2 步：在代码里加几行

import { SHMClient } from '@btouchard/shm-sdk';

// 模拟业务数据
let usersActive = 5;
let documentsCreated = 100;
let jobsProcessed = 50;

// 初始化客户端
const client = new SHMClient({
    serverUrl: 'https://shm.lanmao168.heiyu.space',
    appName: 'TestApp',
    appVersion: '1.0.0',
    environment: 'development',
    enabled: true,
    dataDir: '.',
    reportIntervalMs: 60000, // 每分钟上报一次（最小间隔）
});

// 设置业务指标
client.setProvider(() => {
    // 模拟数据变化
    usersActive += Math.floor(Math.random() * 3) - 1;
    if (usersActive < 1) usersActive = 1;
    documentsCreated += Math.floor(Math.random() * 10);
    jobsProcessed += Math.floor(Math.random() * 5);

    const metrics = {
        users_active: usersActive,
        documents_created: documentsCreated,
        jobs_processed: jobsProcessed,
        api_requests: Math.floor(Math.random() * 1000) + 100,
        cache_hit_rate: (Math.floor(Math.random() * 30) + 70) / 100,
    };

    console.log(`📊 Metrics prepared: users=${usersActive}, docs=${documentsCreated}, jobs=${jobsProcessed}`);
    return metrics;
});

// 启动
client.start();

第 3 步：跑起来
运行上面的代码后，每隔一分钟，数据会自动发送到你的 SHM 服务器。
在微服上可以看到效果，数据已经收集到了

实战场景：我该怎么用它？

场景 1：你是开源项目作者

假设你做了个项目管理工具，发布后有人在用，但你不知道到底有多少人，也不知道哪些功能最受欢迎。

用 SHM 你可以：

• 看到全球有多少个活跃实例
• 知道每个实例创建了多少项目、多少任务
• 发现有人还在用老版本（该催更新了）
• 统计每天的活跃度变化

怎么做？

在你的应用代码里集成 SHM SDK（支持 Go 和 Node.js），定义你关心的指标就行了。比如：

telemetry.setProvider(() => ({
    projects_created: db.count('projects'),
    tasks_completed: db.count('tasks', { status: 'done' }),
    active_users: db.count('users', { last_login: 'recent' })
}));

这样每隔一段时间（默认一小时），你的应用就会把这些数字发给你的 SHM 服务器。

场景 2：追踪版本分布

你发布了新版本，但不确定有多少人升级了。

SHM 会自动收集版本信息，你能在 Dashboard 上看到：

• v1.0: 10 个实例
• v1.1: 5 个实例
• v2.0: 2 个实例（新版本，刚发布）

这样你就知道该不该继续维护老版本了。

---

Dashboard 实用操作

查看总览

打开 Dashboard（默认 http://localhost:8080），你会看到：

概览卡片 (顶部)

卡片	含义
OS Distribution: Darwin (1)	操作系统分布统计，显示有 1 个 macOS 实例
DOCUMENTS CREATED: 100	业务指标 - 创建的文档数量 (由 SDK setProvider 上报)
USERS ACTIVE: 10	业务指标 - 活跃用户数量 (由 SDK setProvider 上报)

这些卡片会自动适应您上报的任何指标，无需预先配置。

查看单个实例

点击某个实例，能看到：

• 最后活跃时间
• 系统信息（操作系统、CPU、内存）
• 历史数据曲线

时间序列图表 (中间)

功能	说明
documents created	选中的指标名称
Time series evolution	指标随时间变化的趋势
时间范围按钮	24h 7d 30d 3m 1y all - 选择查看的时间范围
X/Y 轴	X轴为时间，Y轴为指标数值

---

最后的建议

1. 从小开始：先定义 3-5 个核心指标，别贪多
2. 定期查看：每周看一次 Dashboard，了解项目健康度

SHM 的核心理念是：了解你的软件被如何使用，但不窥探用户隐私。用好它，你就能从"盲飞"变成"有数据支撑的决策"。

---

GitHub 地址：https://github.com/btouchard/shm