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

## 这玩意儿是干嘛的？

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

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

SHM 就是解决这个痛点的。它能帮你收集一些**不涉及用户隐私**的统计数据，比如：
- 有多少个实例在跑
- 每个实例用的什么版本
- 你定义的业务指标（比如创建了多少文档、处理了多少任务）
- 系统信息（CPU、内存、操作系统）

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


https://appstore.lazycat.cloud/#/shop/detail/cloud.lazycat.app.shm


---

### 集成流程

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

**第 1 步：装 SDK**
```bash
npm install @btouchard/shm-sdk
```

**第 2 步：在代码里加几行**
```javascript
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  ({
    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 上报) |

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

![image.png](https://dl.playground.lazycat.cloud/guidelines/496/5b4fe855-3c0a-4399-93c4-248c6e5cd77a.png "image.png")

### 查看单个实例

点击某个实例，能看到：
- 最后活跃时间
- 系统信息（操作系统、CPU、内存）
- 历史数据曲线

![image.png](https://dl.playground.lazycat.cloud/guidelines/496/dc616930-894a-47fb-be87-92cce02173df.png "image.png")
#### 时间序列图表 (中间)

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

---
  

## 最后的建议

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

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

---

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