遥测(打开统计)
MatrixMedia 在应用启动时会向一个公开 GitHub Gist 追加一条匿名事件,用于统计"谁打开了 Electron"。本页说明数据字段、上报流程与关闭方式。
采集字段
每次启动(GUI 或 CLI)追加一条 JSON 事件到 Gist 的 events.json:
| 字段 | 说明 | 示例 |
|---|---|---|
ts | 启动时间(ISO 8601,UTC) | 2026-08-04T03:12:45.000Z |
version | 应用版本 | 0.10.4 |
platform | 操作系统 | win32 / darwin / linux |
arch | CPU 架构 | x64 / arm64 |
locale | 界面语言 | zh-CN |
mode | 启动方式 | gui / cli |
不采集:用户 ID、设备指纹、账号、IP、地理位置、文件路径、任何业务数据。
上报流程
- 应用启动后在后台(不阻塞主流程)读取 Gist 当前内容(一次 GET 取整个 gist)。
- 向
events.json追加本次事件;若条数超过 5000,只保留最近 5000 条(滚动窗口)。 - 向
meta.json({ "total": 累计总数, "updated": 更新时间 })的total加一;文件缺失或损坏时以当前事件条数兜底初始化。 - 一次 PATCH 同时写回
events.json与meta.json。
官网"累计打开次数"读 meta.json 的 total(只增不减);"近 N 天"与平台/版本分布读 events.json 的滚动窗口。
整个过程是 best-effort:失败静默,绝不影响应用启动或使用。
关闭上报
任选其一:
- 设置环境变量
MATRIXMEDIA_DISABLE_TELEMETRY=1 - 在用户主目录创建文件
~/.matrixmedia/no-telemetry(内容任意) - 在应用「项目详情 → 隐私设置」中关闭匿名启动统计。界面使用同一个
no-telemetry文件,GUI 与 CLI 共用,下次启动生效;环境变量禁用时,界面不能重新启用。
自建后端(维护者)
- 创建一个公开 Gist,包含两个文件:
events.json(初始内容[])与meta.json(初始内容{ "total": 0, "updated": "" },也可以不建,首次上报会自动初始化)。 - 记下 Gist id。
- 创建一个有
gist权限的 GitHub Token。 - Electron 端配置(二选一):
- 环境变量
MATRIXMEDIA_GIST_ID/MATRIXMEDIA_GIST_TOKEN - token 放到
~/.matrixmedia/gist-token文件
- 环境变量
- 官网侧编辑
website/.vitepress/theme/utils/gistStats.js,把GIST_ID填为同一 gist id,GIST_OWNER填为 gist 所属 GitHub 用户名(官网通过gist.githubusercontent.com/<owner>/<id>/raw/<file>读取数据,避免未认证 REST API 的 60 次/小时/IP 限额)。
