OpenAnalytics查询网关如何工作:Ed25519签名信封验证每一个查询
OpenAnalytics查询网关如何工作:Ed25519签名信封验证每一个查询
OpenAnalytics 是一款开源、隐私优先且无 Cookie 的 Web 分析平台,支持收入归因与 MCP Server。本文将完整解析它的查询网关如何用短时效 Ed25519 签名信封逐一验证每一次分析数据查询——从 8 个字段的规范签名串,到一次性 nonce 防重放,再到 7 类可诊断的拒绝原因。
查询网关解决什么问题
在 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 的中间件顺序是「承重的」(顺序错了就可能绕过认证):
- boundedBody —— 先给 body 上硬上限并一次性读下字节,超大载荷在哈希和解析之前就被廉价拒绝(413);
- signedRequestAuth —— 未认证请求不允许占用任何查询槽位(auth.ts);
- rateLimit —— 按已确认的 key id 限流(仅在配置了配额时启用);
- concurrencyLimit —— 限制并发查询数,超载时「在门口丢弃」而不是排队,返回可重试的 503(limits.ts);
- 路由处理 —— 解析参数、查缓存、在 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):如果有人在网关上误配置了私钥,服务直接启动失败。
也就是说,即使网关整体被攻陷,攻击者也无法伪造出能通过验证的查询请求。这是「验证者永远弱于签发者」的最小权限设计。
签名之外的第二道防线:操作白名单
签名验证的是「你是谁」,而 operations.ts 操作注册表验证的是「你能问什么」:
- 网关只接受操作 ID + 类型化参数,从不接受 SQL、表名或自由过滤器;
- 每条 SQL 是模块加载时就固定的常量字符串,所有值都通过
{name:Type}占位符绑定,「看不到参数的构造器无法拼接参数」; - 未注册的操作 ID 在任何连接建立之前就被拒绝;
- 每个分析操作都必须绑定
site_id,跨站点读取在结构上不可能发生。
通过验证后,查询还会命中有界的 QueryCache(缓存键含操作 ID 与全部参数,永不混站),未命中才在超时与 ClickHouse 端成本护栏下真正执行。
篡改/重放矩阵如何被测试覆盖
整个验证边界被契约测试逐一打穿(query-gateway-signed-auth.test.ts):无签名、缺头、伪造私钥签名、过期签名、超长有效期、错误受众、签名后篡改 body、有效期内重放、路径被改写——11 个场景全部断言「ClickHouse 从未被触碰」。还有一个安全默认:若未配置验证公钥,网关干脆不挂载查询路由(返回 404),不存在任何配置错误把它变成开放读取面的可能。
总结
OpenAnalytics 查询网关用一套简洁的「签名信封」把服务间认证做成了教科书级的实现:
- 8 字段规范串 + Ed25519:方案标识、受众、方法、路径、时间窗、nonce、body 哈希逐一绑定,一个都改不了;
- 验证方只有公钥:网关能验证不能签发,被攻破也伪造不出请求;
- 一次性 nonce + 原子写入:重放攻击在有效期内也无法二次生效;
- 7 类拒绝原因 + 失败顺序设计:每次 401 都能定位到具体攻击面或配置问题;
- 操作白名单兜底:签名之外,「能查什么」同样被结构上锁死。
对自托管 OpenAnalytics 或想借鉴服务间认证模式的团队,这套 apps/query-gateway/ 与 packages/auth/ 下的实现,是一份可以直接精读的安全参考。


