OpenAnalytics查询网关如何工作:Ed25519签名信封验证每一个查询

原创2026-11-09 19:53:371,953 阅读

OpenAnalytics查询网关如何工作:Ed25519签名信封验证每一个查询

OpenAnalytics 是一款开源、隐私优先且无 Cookie 的 Web 分析平台,支持收入归因与 MCP Server。本文将完整解析它的查询网关如何用短时效 Ed25519 签名信封逐一验证每一次分析数据查询——从 8 个字段的规范签名串,到一次性 nonce 防重放,再到 7 类可诊断的拒绝原因。

OpenAnalytics查询网关驱动的分析仪表盘总览

查询网关解决什么问题

在 OpenAnalytics 的架构里,前端仪表盘的所有数字(访客、页面浏览、来源、地域……)都要从 ClickHouse 读出来。一个朴素的做法是让 API 服务直连 ClickHouse,但这样做有两个隐患:

  • 密钥扩散:API 服务一旦持有数据库凭据,被攻破就等于数据全泄露;
  • 自由查询:API 层如果拼接 SQL,注入风险和成本失控风险都会放大。

所以 OpenAnalytics 在中间加了一层 query-gateway 查询网关:它是外部调用者通往私有 ClickHouse 的唯一通道。API 服务(gateway-client.ts)被明确禁止持有 ClickHouse 凭据,它只做一件事——带着签名向网关提交一个「操作 ID + 类型化参数」,永远不提交 SQL。

这条边界的钥匙,就是 Ed25519 签名信封。

签名信封:构成规范串签名的 8 个字段

签名逻辑集中在 service-signature.ts,方案名为 OA1-ED25519。API 每发起一次查询,就用私钥对如下一组字段拼成的「规范签名串」(canonical signing string)签名:

顺序 字段 作用
1 OA1-ED25519 方案标识,放在第一行,防止旧验证器误认新方案
2 key id 密钥版本,支持轮换
3 audience 受众,防止签名被拿到另一环境重放
4 METHOD(大写) 绑定 HTTP 方法
5 path(含查询串) 只签路径不签查询参数会留下篡改空间
6 issued-at 签发时间(RFC 3339 UTC 毫秒)
7 expires-at 过期时间
8 nonce 一次性随机数,防重放
9 body SHA-256 请求体哈希,而非原文

每个字段同时以 x-oa-* 请求头的形式随请求发送(如 x-oa-scheme、x-oa-nonce、x-oa-body-sha256、x-oa-signature),验证方从线上实际值重建签名串,而不是依赖任何假设。两个巧妙的设计值得一说:

  • 路径带查询串一起签:只签 pathname 的话,攻击者可以悄悄改写 query 参数而签名仍然通过;
  • 请求体只签哈希:验证不依赖「解析后的 body 重新序列化后逐字节一致」,避免序列化差异造成误判。

验证顺序:请求路径上的中间件管线

在 app.ts 中,/v1/query 的中间件顺序是「承重的」(顺序错了就可能绕过认证):

  1. boundedBody —— 先给 body 上硬上限并一次性读下字节,超大载荷在哈希和解析之前就被廉价拒绝(413);
  2. signedRequestAuth —— 未认证请求不允许占用任何查询槽位(auth.ts);
  3. rateLimit —— 按已确认的 key id 限流(仅在配置了配额时启用);
  4. concurrencyLimit —— 限制并发查询数,超载时「在门口丢弃」而不是排队,返回可重试的 503(limits.ts);
  5. 路由处理 —— 解析参数、查缓存、在 ClickHouse 端成本护栏下执行查询。

验证内部还讲究检查次序:先查受众 → 再查时间窗 → 再对 body 哈希 → 最后才验签,nonce 消费放在最末。nonce 最后消费是因为:若先消费,未认证的攻击者就能灌满 nonce 存储,或「烧掉」合法请求者的 nonce。

7 种拒绝原因:让每次失败都可诊断

所有拒绝都统一返回 401,但携带机器可读的 reason,运维无需读错误文本就能区分是时钟漂移、重放还是伪造(auth.ts):

reason 触发场景
MISSING_SIGNATURE 完全没有签名,通常是调用方配置错误
MALFORMED_SIGNATURE 签名头不全、时间格式不合规、有效期超过上限
BAD_SIGNATURE 签名验不过——伪造或路径/方法被改写
EXPIRED 签名已过期,或签发于「未来」(时钟超前)
WRONG_AUDIENCE 签名是为 staging 签的,被拿到生产使用
REPLAYED nonce 已被使用过
BODY_MISMATCH 签名后请求体被篡改

其中有效期上限由验证方强制:即使调用方自己声称签了一小时的有效期,验证方也会按配置上限截断(硬顶 5 分钟,见 service-signature.ts),「短时效凭证」不是信任,而是校验。

防重放:一次性 nonce 与 Valkey 共享存储

即便签名绑定了方法、路径、body 和受众,它在有效期内仍可被原样重放。因此每个请求都携带一次性 nonce:

  • 单实例:内存 nonce 存储(nonce-store.ts)足够,条目只在签名有效期内保留;
  • 多实例:必须换成 Valkey 共享存储。这不是理论推演——注释里记录了实测:两台实例的部署中,10 次重放有 7 次被接受,因为重放落在了没见过该 nonce 的机器上。

Valkey 实现的核心是原子的 SET key NX PX:两个并发重放不可能都观察到「未见过」,只有一个能写入成功(nonce-store.ts)。nonce 的存活时间与签名有效期对齐,过期自动消失,无需清理任务。

为什么用 Ed25519 非对称签名,而不是共享 HMAC 密钥?

这是整个设计里最值得新手体会的一点:

  • HMAC 共享密钥下,网关既能验证也能签发——一旦被攻破,攻击者就能伪造任意合法请求;
  • Ed25519 下,私钥只存在于 API 侧(QUERY_SIGNING_PRIVATE_KEY),网关只有公钥(QUERY_SIGNING_PUBLIC_KEY),网关能验证但不能签发;
  • 更进一步,QUERY_SIGNING_PRIVATE_KEY 被列入了网关环境的 FORBIDDEN_KEYS(env.ts):如果有人在网关上误配置了私钥,服务直接启动失败。

也就是说,即使网关整体被攻陷,攻击者也无法伪造出能通过验证的查询请求。这是「验证者永远弱于签发者」的最小权限设计。

OpenAnalytics访客旅程视图由查询网关的类型化操作驱动

签名之外的第二道防线:操作白名单

签名验证的是「你是谁」,而 operations.ts 操作注册表验证的是「你能问什么」:

  • 网关只接受操作 ID + 类型化参数,从不接受 SQL、表名或自由过滤器;
  • 每条 SQL 是模块加载时就固定的常量字符串,所有值都通过 {name:Type} 占位符绑定,「看不到参数的构造器无法拼接参数」;
  • 未注册的操作 ID 在任何连接建立之前就被拒绝;
  • 每个分析操作都必须绑定 site_id,跨站点读取在结构上不可能发生。

通过验证后,查询还会命中有界的 QueryCache(缓存键含操作 ID 与全部参数,永不混站),未命中才在超时与 ClickHouse 端成本护栏下真正执行。

OpenAnalytics查询网关支持的地域分布实时数据可视化

篡改/重放矩阵如何被测试覆盖

整个验证边界被契约测试逐一打穿(query-gateway-signed-auth.test.ts):无签名、缺头、伪造私钥签名、过期签名、超长有效期、错误受众、签名后篡改 body、有效期内重放、路径被改写——11 个场景全部断言「ClickHouse 从未被触碰」。还有一个安全默认:若未配置验证公钥,网关干脆不挂载查询路由(返回 404),不存在任何配置错误把它变成开放读取面的可能。

总结

OpenAnalytics 查询网关用一套简洁的「签名信封」把服务间认证做成了教科书级的实现:

  • 8 字段规范串 + Ed25519:方案标识、受众、方法、路径、时间窗、nonce、body 哈希逐一绑定,一个都改不了;
  • 验证方只有公钥:网关能验证不能签发,被攻破也伪造不出请求;
  • 一次性 nonce + 原子写入:重放攻击在有效期内也无法二次生效;
  • 7 类拒绝原因 + 失败顺序设计:每次 401 都能定位到具体攻击面或配置问题;
  • 操作白名单兜底:签名之外,「能查什么」同样被结构上锁死。

对自托管 OpenAnalytics 或想借鉴服务间认证模式的团队,这套 apps/query-gateway/ 与 packages/auth/ 下的实现,是一份可以直接精读的安全参考。

登录后查看全文
openanalytics