Keystone 遥测(Telemetry)完全指南:采集内容、触发时机与退出方式
Keystone 遥测(Telemetry)完全指南:采集内容、触发时机与退出方式
Keystone 6 在开发者运行 keystone dev 时会向官方服务器发送匿名遥测数据,用于帮助 Thinkmill Labs 了解社区的开发模式与项目复杂度,从而决定后续功能与维护的优先级。本文以仓库中的官方遥测文档 docs/content/docs/reference/telemetry.md 为主体,结合 packages/core/src/lib/telemetry.ts 等源码实现,完整讲解 Keystone 遥测的采集目的、触发时机、上报数据结构、存储位置,以及用户级、项目级、环境变量级和网络级四层退出(opt-out)方案,帮助你做出知情决策。
遥测的目的:Keystone 为什么收集匿名数据
Keystone 的遥测由 Thinkmill Labs Pty Ltd 主导,其设计与收集行为遵循澳大利亚隐私原则(Australian Privacy Principles)。按照官方文档的说明,遥测主要帮助官方回答以下四个问题:
- 正在使用 Keystone 的活跃开发者数量,与社区活跃成员数量的对比;
- 使用 Keystone 的项目复杂度如何;
- 开发者实际使用了哪些字段类型以及
@keystone-6/或社区提名的包; - 社区正在使用哪些操作系统与 Node.js 版本。
这些信息只服务于软件的持续开发与维护优先级决策,不包含任何个人身份信息,也不会被用于商业销售。
需要特别说明的是:Keystone 依赖的 Next.js 与 Prisma 各自拥有独立的遥测机制和隐私政策。本文只讨论 Keystone 自身的遥测,二者相互独立。
什么时候会触发遥测
根据官方文档,Keystone 仅在开发者显式运行 keystone dev(或通过 @keystone-6/core/scripts/cli 导出的 cli 函数并传入 argv 值为 dev)时才收集遥测。build、start、postinstall 等命令均不会触发遥测上报。
从源码看,上报入口位于 packages/core/src/scripts/dev.ts:dev 命令在系统初始化完成后调用 runTelemetry(cwd, system.lists, system.config.db.provider),并且仅在 system.config.telemetry !== false 时执行——这正是文档中"项目级 telemetry: false 配置可以禁用遥测"的底层实现。
四种不采集遥测的场景
运行 keystone dev 时,以下四种场景下不会发送任何遥测数据:
- 首次运行
keystone dev、正在展示遥测知情声明(inform notice)时; - 环境变量
CI被设置为任意值; - 环境变量
NODE_ENV为"production"; - 用户已显式退出遥测。
在 packages/core/src/lib/telemetry.ts 的 runTelemetry 实现中,这四种场景依次对应 ci.isCI 检测、process.env.NODE_ENV === 'production' 检测、telemetry === false(用户退出)与 informedAt === null(首次未告知)。此外源码还额外支持 KEYSTONE_TELEMETRY_DISABLED 与 DO_NOT_TRACK 两个环境变量(详见下文"退出遥测"章节)。所有分支命中时都会打印明确的禁用提示(例如 Keystone Telemetry is disabled (running in CI))。
值得注意的实现细节:首次运行仅展示知情声明,不会同时发送数据。runTelemetry 会在检查到 informedAt 为空时调用 inform() 打印声明并记录告知时间,随后直接返回——这一设计保证了开发者至少有"看到声明 → 主动退出"的窗口期,符合知情同意原则。
上报内容:两类独立的数据报告
Keystone 将遥测分为**设备遥测(Device Telemetry)与项目遥测(Project Telemetry)**两类,分别上报到 telemetry.keystonejs.com 的不同端点,以最小化两类数据在时间与分组上的关联性(官方明确表示两类数据"无关联必要")。服务器端会额外记录每条报告被接收的时间戳。
需要提醒:遥测信息的确切结构与内容可能随版本更新而调整;任何实质性增加都会在下次运行 keystone dev 时重新向开发者展示通知,并同步更新本文档。
设备遥测(Device Telemetry)
设备遥测描述"运行 keystone dev 的这台设备",当前包含:
- 最后一次使用
keystone dev的日期; - Node.js 主版本号;
- 操作系统名称。
对应的 JSON 格式示例(见官方文档):
{
"lastSentDate": "2024-11-23",
"os": "darwin",
"node": "20"
}
设备遥测上报端点:https://telemetry.keystonejs.com/3/device。在 packages/core/src/lib/telemetry.ts 的 sendDeviceTelemetryEvent 实现中,os 来自 node:os 的 platform(),node 取 process.versions.node 的主版本段;发送成功后会把当天日期写回本地的 lastSentDate,从而保证同一设备每天最多上报一次。
项目遥测(Project Telemetry)
项目遥测描述"当前这个 Keystone 项目",当前包含:
- 该项目最后一次运行
keystone dev的日期; - 项目已解析安装的
@keystone-6/(或社区提名)包及其版本号; - 项目使用的数据库类型;
- 项目定义的 list 数量;
- 项目使用的字段类型名称与对应数量。
对应的 JSON 格式示例(见官方文档):
{
"lastSentDate": "2025-07-28",
"packages": {
"@keystone-6/auth": "8.0.1",
"@keystone-6/core": "6.1.0",
"@keystone-6/document-renderer": "1.1.2",
"@keystone-6/fields-document": "5.0.2"
},
"database": "postgresql",
"lists": 3,
"fields": {
"unknown": 1,
"@keystone-6/text": 5,
"@keystone-6/timestamp": 2,
"@keystone-6/checkbox": 1
}
}
项目遥测上报端点:https://telemetry.keystonejs.com/3/project。
源码视角:包版本与字段统计如何生成
包版本列表的收集逻辑见 packages/core/src/lib/telemetry.ts 的 collectPackageVersions:它通过 createRequire 从项目目录解析 @keystone-6/core、@keystone-6/auth、@keystone-6/fields-document、@keystone-6/cloudinary、@keystone-6/session-store-redis 以及社区包 @opensaas/keystone-nextjs-auth 的 package.json,读取 version 字段;未安装的包会被静默跳过,并预置 @keystone-6/core 为 0.0.0 表示"未知"。
字段统计逻辑见 collectFieldCount(packages/core/src/lib/telemetry.ts):它遍历所有 list 的字段,读取每个字段对象上的 __ksTelemetryFieldTypeName 属性作为字段类型标识,如 @keystone-6/text、@keystone-6/checkbox 等。该标识由各字段类型在注册时写入,例如 checkbox 字段类型、integer 字段类型 等均定义了自己的 __ksTelemetryFieldTypeName;没有该标识的字段(id 字段除外)会被归入 unknown 计数。因此 fields 对象中出现的键名集合,实质上反映了项目里使用过的字段类型全景。
上报频率与失败处理
sendProjectTelemetryEvent(packages/core/src/lib/telemetry.ts)与设备遥测一样,通过比较本地记录的 lastSentDate 与当天日期,实现每个项目每天最多上报一次。实际发送由 sendEvent(同文件 L205-L229)执行:它使用 node:https 向 ${endpoint}${eventType} 发起 POST 请求,请求头仅含 Content-Type: application/json,且不携带任何 Cookie、鉴权头或用户标识;即使请求失败也会静默 resolve,绝不阻塞 keystone dev 的正常启动。
数据的使用、共享与保留
使用与共享:遥测数据由 Thinkmill Labs 分析以回答前述问题,过程中可能使用第三方服务;官方承诺尽可能以聚合形式与 Keystone 开源社区共享统计结果,并尽力剔除即使聚合后仍可能识别出特定设备或项目的离群数据。
不销售数据:官方文档明确声明"我们不销售这些数据,也没有此打算"。
保留期限:遥测报告及其时间戳仅保留 1 年。超过该期限后,单条遥测报告会被删除,只保留分析后的聚合形式数据。
如何退出遥测(Opt-out)
官方提供了四种不同粒度的退出方式,从个人用户到网络层面逐层递进。
方式一:用户级退出(CLI 命令)
$ keystone telemetry disable
该命令针对当前系统用户写入退出配置(存储位置见下文表格)。如果你的设备上有多个用户配置文件,切换用户后需要重新执行此命令。CLI 相关实现位于 packages/core/src/scripts/telemetry.ts,命令路由注册在 packages/core/src/scripts/cli.ts(telemetry 开头的输入均分发到该命令处理)。
除 disable 外,该子命令还支持:
| 子命令 | 作用 |
|---|---|
keystone telemetry enable |
为当前系统用户重新开启遥测 |
keystone telemetry reset |
重置当前用户的遥测配置(相当于恢复未初始化状态) |
keystone telemetry status |
查看当前设备/项目的遥测配置状态 |
keystone telemetry inform |
手动展示遥测知情声明 |
keystone telemetry --help |
展示全部用法说明 |
这些操作的底层分别是 lib/telemetry.ts 中的 disableTelemetry()(将配置置为 false)、enableTelemetry()(恢复默认配置)、resetTelemetry()(删除配置项)与 statusTelemetry()。
方式二:项目级退出(配置文件)
在项目的 keystone.ts 配置中显式设置 telemetry: false,即可让整个项目退出遥测,且该配置适合纳入版本控制、随项目分发给团队所有成员:
export default config({
db: {
// ...
},
lists,
// 为该项目禁用设备遥测与项目遥测
telemetry: false
})
该配置项在 packages/core/src/types/config/index.ts 中被定义为 telemetry?: boolean(注释为"用于禁用该项目遥测的布尔值"),并在初始化后的完整配置类型(同文件 L193)中成为必填的 telemetry: boolean 字段;dev.ts 正是依据该值决定是否调用 runTelemetry(见 packages/core/src/scripts/dev.ts)。
方式三:环境变量级退出
设置环境变量 KEYSTONE_TELEMETRY_DISABLED='1' 可退出所有遥测:
$ KEYSTONE_TELEMETRY_DISABLED=1 keystone dev
源码中该变量的判断在 runTelemetry 内(packages/core/src/lib/telemetry.ts)。此外,仓库实现还额外识别标准的 DO_NOT_TRACK=1 环境变量(同文件 L300-L303),这虽未写入官方遥测文档,但从源码结构看属于当前版本支持的另一条退出路径。
方式四:网络级退出(防火墙)
如果你在网络层面配置防火墙,只需不解析 telemetry.keystonejs.com 域名即可从根源上阻止所有遥测请求到达服务器。上报端点可在源码中确认:defaultTelemetryEndpoint = 'https://telemetry.keystonejs.com/3/'(packages/core/src/lib/telemetry.ts),且可通过 KEYSTONE_TELEMETRY_ENDPOINT 环境变量覆盖(该变量属于实现细节,日常无需使用)。
查看当前配置状态
不确定自己的设备/项目当前处于何种遥测状态?运行:
$ keystone telemetry status
输出会明确显示遥测处于 enabled、disabled 还是 uninitialized(未初始化),并打印设备遥测与各项目遥测的最近发送日期。从 packages/core/src/scripts/telemetry.ts 的实现看,该命令还支持彩色终端输出(绿色=enabled、红色=disabled、黄色=uninitialized),便于一眼识别。
遥测配置存储位置
Keystone 使用开源库 env-paths 决定遥测偏好配置的存放路径,当前各操作系统的位置如下:
| 操作系统 | 存储位置 |
|---|---|
| macOS | ~/Library/Preferences/keystonejs |
| Linux | ~/.config/keystonejs(或 $XDG_CONFIG_HOME/keystonejs) |
| Windows | %APPDATA%\keystonejs\Config(例如 C:\Users\YOUR_USERNAME\AppData\Roaming\keystonejs\Config) |
从源码看,配置读写基于 Conf 库(packages/core/src/lib/telemetry.ts),并内置了从 v1 到 v2 的配置迁移逻辑:v1 配置迁移后会保留各项目的 lastSentDate,同时将 informedAt 重置为 null,以保证升级后用户会重新收到一次遥测声明。
常见问题与反馈渠道
- 遥测会减慢
keystone dev启动吗? 不会。发送过程为异步非阻塞,且请求失败会被静默吞掉(仅当设置KEYSTONE_TELEMETRY_DEBUG=1时打印调试日志),不会影响开发服务器启动与响应。 - 如果对信息收集有疑问或投诉? 可以到 Keystone 的 GitHub 仓库提交 Issue,或联系其隐私官(邮箱
privacy@keystonejs.com,邮寄地址为悉尼 Clarence 街 191 号 10 层)。关于安全策略的更多说明见仓库根目录的 SECURITY.md。
小结
Keystone 的遥测设计遵循"匿名、最小必要、可知情退出"的原则:仅在 keystone dev 时触发,将设备信息与项目信息拆分为两路独立上报且每日限一次,数据仅保留一年并以聚合形式分享。开发者既可以按用户(keystone telemetry disable)、按项目(telemetry: false)、按环境(KEYSTONE_TELEMETRY_DISABLED=1)逐层退出,也可以通过 keystone telemetry status 随时核查当前状态。理解这些机制后,你可以在享受 Keystone 开发体验的同时,自主决定是否参与其社区数据共建。