如何在 Cloudflare Workers 上部署 KeyStats 同步后端:D1 + R2、7 个迁移、零明文存储全指南
如何在 Cloudflare Workers 上部署 KeyStats 同步后端:D1 + R2、7 个迁移、零明文存储全指南
KeyStats 是一款 macOS/Windows 键盘与鼠标统计菜单栏应用,支持端到端加密(E2EE)的多设备同步。它的同步后端是一个独立可部署的 Cloudflare Workers 项目,位于 services/sync-worker/,只依赖 D1 数据库和 R2 对象存储,服务端全程拿不到任何明文的按键次数、按键名或密钥。本文将带你完成一次完整的部署:本地验证 → 创建 D1/R2 → 执行 7 个数据库迁移 → 配置 pepper 密钥 → 上线 staging 与 production,并逐层解释"零明文存储"是如何实现的。
部署前 3 分钟:看懂 Worker + D1 + R2 架构
在敲第一条命令之前,先花 3 分钟理清三个角色的分工,后面每一步都会用到:
| 组件 | 绑定名 | 存什么 |
|---|---|---|
| Cloudflare Worker | — | 路由、鉴权、限流逻辑,入口见 src/index.ts 与 src/routes.ts |
| D1 数据库 | DB |
凭据的 HMAC 哈希、加密设备档案、当前加密记录、历史游标、限流状态、删除回执 |
| R2 存储桶 | HISTORY |
每个历史修订版本一个不可变加密对象,被取代后保留 7 天 |
关键配置都在 wrangler.jsonc 里:
- 定义了
local/staging/production三套环境,staging 与 production 使用相互独立的 D1 与 R2; - 每日定时任务
17 3 * * *(UTC 凌晨 3:17)触发清理逻辑,见 src/cleanup.ts; - 变量
SYNC_ENABLED是全局"急停开关",设为false后拒绝一切同步/配对/恢复操作,但保留删除接口。
准备工作:克隆仓库并本地验证
先拿到源码并在本地跑通全部检查,确保环境没有问题再上云:
git clone https://gitcode.com/gh_mirrors/key/keyStats
cd keyStats/services/sync-worker
npm ci
npm run check
npx wrangler d1 migrations apply DB --local
其中 npm run check 一步做了四件事(定义在 package.json):
- 校验 contracts/sync/v1/ 下的 JSON Schema 与黄金加密向量;
- 重新生成并检查 Wrangler 类型绑定;
tsc --noEmit类型检查;- 用 vitest + Miniflare 在内存版 D1/R2 上跑完整个 Worker 测试(测试专用的 pepper 直接注入 Miniflare,不需要
.env文件)。
最后一条命令则把 7 个迁移应用到本地 D1,等价于在本地提前预演一遍生产迁移。
一次性 Cloudflare 设置:创建 D1 与 R2
按照 wrangler.jsonc 中写明的名称,为 staging 和 production 各创建一套资源:
npx wrangler d1 create keystats-sync-staging
npx wrangler r2 bucket create keystats-sync-staging
npx wrangler d1 create keystats-sync-production
npx wrangler r2 bucket create keystats-sync-production
⚠️ 注意:仓库里检入的
database_id是00000000-...占位符,不能直接部署。部署流程会用仓库自带的 scripts/write-deploy-config.mjs 生成一份权限受限的临时配置,把真实 D1 UUID 填进去,全程不往仓库写任何密钥文件。
逐个看懂 7 个数据库迁移
迁移文件都在 services/sync-worker/migrations/,按序号依次执行。理解它们能帮你建立对整个数据模型的心智模型:
| 迁移 | 文件 | 做了什么 |
|---|---|---|
| 0001 | 0001_initial.sql | 建 5 张核心表:vaults(库)、devices(设备)、history_changes(历史游标)、pairing_sessions(配对会话)、rate_limits(限流) |
| 0002 | 0002_active_device_limit.sql | 插入触发器:单个 vault 最多 5 台活跃设备,写点直接拦截 |
| 0003 | 0003_history_revision_monotonic.sql | 触发器保证同一 record_id 的 revision 严格单调递增,防止旧数据回灌 |
| 0004 | 0004_exempt_sync_page_limit.sql | 新增 exempt_sync_page_count 列并加 CHECK ≤ 256,防止未完成的全量引导变成无限写入路径 |
| 0005 | 0005_maintenance_state.sql | 通用 maintenance_state 键值表,供每日 Cron 持久化断点(如孤儿对象扫描游标) |
| 0006 | 0006_recovery_and_pairing_replay.sql | 增加"恢复重激活"触发器(同样拦截 5 设备上限竞态),并为配对增加 replaces_existing_device 列 |
| 0007 | 0007_vault_deletion_receipts.sql | 独立删除回执表:只存 token 哈希、无 vault 外键,物理删除后仍可让 DELETE /v1/vault 的精确重试返回 204 |
迁移的哲学很统一:产品级不变量(设备上限、版本单调、页数封顶)全部下推到 SQL 触发器/CHECK 约束,并发请求无法"竞态绕过"。
配置 TOKEN_HASH_KEY:它是 pepper,不是普通部署密钥
这是整个部署中最容易出事故的一步,请务必读懂:
TOKEN_HASH_KEY是持久化的认证胡椒盐(pepper),服务端所有 token 都用它做 HMAC 后再入库;- 长度必须 ≥ 32 字节且随机生成。Worker 启动时会校验,不满足直接抛错(见 src/index.ts);
- 轮换或丢失它,会作废该环境下所有已存的设备凭据和恢复凭据。除非你打算重置整个 vault,否则请把它长期保存在 CI/Environment Secrets 中;
- staging 与 production 必须使用不同的随机密钥;
- 通过
wrangler secret put写入,仓库中永远不出现明文。
部署到 staging 与 production
推荐走仓库文档(services/sync-worker/README.md)描述的部署流程:主分支自动部署 staging;production 需要环境审批 + 显式确认。手动部署时大致等价于:
# 1. 用仓库脚本生成临时部署配置(填入真实 D1 UUID)
CLOUDFLARE_D1_DATABASE_ID=<你的 D1 UUID> \
node scripts/write-deploy-config.mjs staging /tmp/wrangler-staging.json
# 2. 应用 7 个迁移
npx wrangler d1 migrations apply DB --config /tmp/wrangler-staging.json
# 3. 写入 pepper 并部署
npx wrangler secret put TOKEN_HASH_KEY
npx wrangler deploy --env staging --config /tmp/wrangler-staging.json
部署完成后,两个必做动作:
- 健康检查:访问
GET /healthz(实现见 src/routes.ts),应返回{"ok":true,"syncEnabled":true,"serverTime":...}; - 回填客户端端点:production 部署后,把仓库变量
KEYSTATS_SYNC_PRODUCTION_URL设为最终的workers.dev地址——发布构建会把它注入 macOS 的Info.plist与 Windows 程序集元数据;端点缺失时客户端 UI 仍可见,但同步功能保持关闭,这是刻意的安全设计。
零明文存储:服务端到底能看到什么
这正是 KeyStats 同步后端的设计核心。Worker 永远收不到:恢复种子、恢复码、明文设备档案、本地日期、按键名、统计计数(见 services/sync-worker/README.md 开篇声明)。它实际看到的只有:
- 不透明标识符:设备/vault 是随机 UUID,
recordId是由 HMAC 派生的索引,不泄露本地日期; - AES-256-GCM 密文信封:nonce + ciphertext + tag,AAD 绑定
1\nvaultId\ndeviceId\nrecordId\nrevision,格式定义见 contracts/sync/v1/encrypted-record.schema.json; - 凭据哈希:
TOKEN_HASH_KEY参与加钥哈希后落库,连 token 本身都不存; - 限流与游标元数据:纯数值,无业务语义。
完整的线上协议(含 OpenAPI 定义)以 contracts/sync/v1/openapi.yaml 为准,客户端与 Worker 共享同一份契约,npm run check 会持续校验一致性。设计动机可延伸阅读 2026-07-13-e2ee-sync-design.md。
上线后的运维清单:限流、Cron 与监控
服务自带一整套保护参数(部分见 src/env.ts 与 src/cleanup.ts):
| 项目 | 默认值 | 说明 |
|---|---|---|
| 请求体上限 | 2 MiB | 超限返回 413 |
| 单次同步归档数 | 16 条 | 全量引导用 bootstrapComplete 分页 |
| 每 vault 活跃设备 | 5 台 | 由 D1 触发器强制 |
| 同步频率 | 1 次/小时、8 次/UTC 日 | MIN_SYNC_INTERVAL_SECONDS、DAILY_SYNC_LIMIT |
| 被取代历史保留 | 7 天 | R2 独立对象,可单独清理 |
| 每日 Cron | 17 3 * * * |
800 次操作预算,孤儿扫描断点持久化 |
| 急停开关 | SYNC_ENABLED=false |
拒绝同步/配对/恢复,保留删除 |
监控建议直接摘自官方 README:以近 7 天峰值为容量信号,达到免费额度 60% 告警、75% 时迁移到 Workers Paid;413 或归档超限错误率上升通常意味着客户端引导批处理有问题。日志层面刻意禁用了持久化 Workers Logs(调用元数据可能含请求头),应用也不向日志输出任何凭据、标识、密文、按键名或计数,只依赖平台内置指标。
常见问题(FAQ)
Q:部署后客户端一直提示"同步未启用"?
先查 KEYSTATS_SYNC_PRODUCTION_URL 是否已注入发布构建;再查 Worker 的 SYNC_ENABLED 是否被误设为 false。
Q:TOKEN_HASH_KEY 丢了怎么办?
没有"找回"一说——它失效意味着该环境全部凭据作废,只能整体重置 vault。这也是它必须存进 CI Secrets 且永不轮换的原因。
Q:staging 为什么要关闭限流?
wrangler.jsonc 中 staging 的 HOURLY_RATE_LIMITS_ENABLED=false、DAILY_SYNC_LIMIT=0,是为了让联调可以高频压测,而 production 保持完整限速。
总结:部署 KeyStats 同步后端的核心就四步——本地 npm run check 全绿、按名创建 D1/R2、用脚本注入真实 D1 ID 后执行 7 个迁移并部署、把 ≥32 字节的 TOKEN_HASH_KEY 作为长期 pepper 写入 Secret。整个服务端只是加密数据的"保险柜管理员":没有账户系统、没有明文统计、没有可读的按键名,这正是"零明文存储"承诺落地的样子。