跳转到正文

ADR 0054: 用户体验改进计划默认加入,日报发往托管日志服务;发布方通知走签名发布通道

本文目录

日期:2026-10-22 · 状态:已接受;修订 0040 补充(2026-10-17)的开关取舍

背景

ADR 0040 的补充让自动检查更新在索引请求的查询参数里带上装机规模(节点数、GPU 型号、agent 版本), 发布方从对象存储的访问日志统计。它只回答「有多少、多大」,回答不了「用来做什么、跑了什么任务、在哪里失败」;查询参数和只读的静态源也装不下更多内容。 同时,发布方需要一条把安全公告、重要版本、社区活动送到管理员面前的途径。

决策

  1. 默认加入,一个开关。 server.yaml 的 usage_report(不写即加入)管每日报告,以及检查更新附带的节点数与 GPU 型号。 auto_check_updates 管是否自动检查;自动检查总会附带安装标识、server 与 agent 版本(2026-10-22 补充:退出改进计划的安装也要能计入装机数与版本分布),要完全不发送须关掉自动检查。私有化交付在首次启动前写 usage_report: false,不做专门的构建或安装包。
  2. 只有 server 报告,每天一次。 首次启动与重新加入时立刻发一份,之后报告覆盖上一个完整 UTC 日,次日按安装标识错开发送;只有带 server.yaml 的安装发送,GPUWORKS_USAGE_REPORT=off 强制关闭(CI、l2 测试);失败不重试,进程内计数并入下一天;不补发错过的日子。 能从数据库按时间窗口查到的事实就查(时间线事件走 created_at 索引),只在发生时存在的事实(API 错误码、路由调用、panic、登录、agent 连接问题) 用进程内计数器,不为报告新建表;唯一新增的持久化是最近报告日 usage_report_last_day。agent 不改动。
  3. 内容只有枚举值、计数和分段。 字段清单(docs/reference/usage-report.md)是对用户的承诺,测试保证它与 usagereport.Report 一字不差。 模型名只在确定公开时上报(内置模板,或该模型站点没有配置访问凭据),否则记为 custom;版本号只保留数字部分。
  4. 收集端用托管日志服务,不自建服务;发送前测速,发给快的。 两个收集端:阿里云 SLS 的 WebTracking 日志库(境内直达、免备案默认域名、自带 SQL 分析与仪表盘) 与 Cloudflare Worker(写入 R2,再导入同一日志库),地址都是二进制常量。发送前同时向两边各发一个不写数据的 GET,发给先应答的, SLS 优先(Cloudflare 要快出 50 ms 以上),失败再试另一个;测速结果写进报告。实测办公网与 gpu3 到 SLS 0.05–0.35 s、到 Cloudflare 0.7–3.3 s。 按写入量计费约 0.4 元/GB,万级安装每月十余元。
  5. 收集端记录来源公网 IP。 报告正文不含地址;收集端记录请求的来源公网 IP(server 的出口地址),用于按国家与省份统计、识别伪造报告, SLS 与报告同样保存 180 天,Cloudflare 记在对象元数据里。设置页、铃铛通知与字段清单如实说明。
  6. 通知走签名发布通道,不走收集端。 WebTracking 只回空的 200,不能借它下发内容。通知是发布源根目录的 notices.json, 与版本索引同一种 ed25519 签名信封,随检查更新拉取(同一节流,auto_check_updates 开启时另每 6 小时后台拉取)。 是否适用由 server 用本地事实判断(渠道、构建时间、加速卡厂商),不向发布方发送任何信息,也与是否加入改进计划无关。 控制台只用页头铃铛展示,不弹横幅;适用的安全通知另写一条 server 日志。

取舍

  • 默认加入换来有代表性的数据;代价是必须可逐字预览(GET /api/v1/usage-report/preview)、一键退出(「版本与更新」里的开关,悬停说明上传什么、不记录什么),并把私有化交付的关闭方式写进文档。
  • 匿名写入的日志库可能被写入伪造数据。报告只用于看趋势,统计时按 install_id 格式、schema 与每个安装每天一条过滤; 改用带签名的写入要么把密钥放进二进制(同样可被提取),要么需要自建签发服务,都与「不运维服务」冲突。
  • 把装机规模并入新开关意味着关掉 usage_report 的安装照常检查更新,只带安装标识与版本;这推翻了 0040 补充里「一个开关管检查和报告」的选择—— 如今报告远不止规模,客户需要能只关报告不关更新。代价是「退出改进计划」不等于「什么都不发」:想完全不发送的安装还要关掉自动检查。
  • 每天一份而不是实时上报:负担可忽略(一个请求、一次分组查询),代价是错误要隔天才看到,且 server 重启会丢掉当天的进程内计数。
  • 记录来源 IP换来地域分布与防刷依据,代价是收集端保存了一个通常被视为个人信息的出口地址;只保存在发布方的日志库里,不与报告内容以外的数据关联。 若日后需要,可改为原始数据进短期日志库、加工后只保留国家与省份。
  • 通知不能触发动作:哪怕是严重漏洞也只提示与写日志,不自动升级或改配置;签名私钥泄露的后果因此只限于错误的提示。

后果

  • 新包 internal/server/usagereport(叶子包:报告结构、裁剪、计数器、发送、调度时刻、检查更新附带的装机规模),distribution 只接收现成的查询参数,仍不依赖本仓库任何包。
  • 新接口 GET /api/v1/usage-report、PUT /api/v1/usage-report/enabled、GET /api/v1/usage-report/preview、GET /api/v1/notices、POST /api/v1/notices/read; 新表 notice_reads(迁移 166)。
  • 发布方用 scripts/publish_notices.sh 签发并上传 build/notices/notices.json;发布源的缓存规则需把 /notices.json 与 */index.json 一样设为不缓存。

这篇文档有帮助吗?