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 < 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），定义你关心的指标就行了。比如： ```javascript 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 个核心指标，别贪多 3. **定期查看**：每周看一次 Dashboard，了解项目健康度 SHM 的核心理念是：**了解你的软件被如何使用，但不窥探用户隐私**。用好它，你就能从"盲飞"变成"有数据支撑的决策"。 --- GitHub 地址：https://github.com/btouchard/shm