treg Idempotent-Key 多租户隔离原理你的请求为何不会拿到别人的结果【免费下载链接】tregOpenRouter for agent tools. Join community here: https://discord.gg/6mQYYfFMAn项目地址: https://gitcode.com/GitHub_Trending/treg/tregtreg 是一个面向 Agent 的工具版 OpenRouter——它把成百上千家第三方数据 API 统一成一个调用入口按团队租户计费。Agent 天然爱重试而 treg 的 Idempotency-Key 幂等键机制保证重试免费、结果不变、且绝不会把 A 团队的数据回放给 B 团队。本文讲清楚这套多租户隔离是怎么做到的。为什么 Agent 场景特别需要幂等键先说清楚问题Agent 的重试远比人类频繁而其中一种重试最贵——treg 调用上游供应商供应商成功且已扣费响应在回传途中丢失网络抖动、客户端超时Agent 发起重试treg 又调用了一次供应商又扣了一次费。从账本上看这是两笔各自成功的调用。更棘手的是仅仅记住这个 key 已扣费、跳过第二次收费是不够的——第二次上游调用照样发生钱照样付给供应商只是把成本从用户转嫁到了平台。所以真正的幂等必须做到第二次请求根本不出去直接回放第一次的应答。这套设计在 docs/IDEMPOTENT-CALLS-PLAN.md 中有完整推演。只存成功且已计费的响应窗口 24 小时实现规则非常克制源码见 idempotency.py只有带 key 才生效不传Idempotency-Key的请求行为与从前逐字节一致服务端绝不替你想 key只存已计费的成功响应失败本来就是免费的没必要保护存储因此有界24 小时窗口重试发生在秒级一天足够宽裕过期行直接消失。核心隔离key 按调用者作用域而不是全局唯一这是整篇文章的重点也是你的请求不会拿到别人的结果的根本保证。IdempotentCall表上的唯一约束是(membership_id, key)复合键而不是 key 单独唯一定义在 models.pyuq_idem_caller_key → UNIQUE (membership_id, key)这里的membership是 treg 的统一调用者身份一个人类成员的 token、一个 Agent token、一个 OAuth 授权最终都解析为同一个 Membership。于是只有一条规则覆盖所有情形这个 key 归发它的人所有。为什么这个设计如此重要key 是客户端自己起的。两个团队迟早都会起出retry-1这样的名字。如果只按 key 隔离先到的那个团队的响应体就会被回放给后到的团队——这是该功能里唯一会造成数据泄露而不只是多扣钱的失败模式为什么不是按团队隔离因为同一个团队里两个写得懒的 Agent 都会抢着用retry-1。按团队隔离会让第二个 Agent 收到莫名其妙的拒绝按调用者隔离它们压根碰不到彼此。作用域越小越安全Stripe 也是按 API key 划分的同理。再进一步转售场景的标签分区还有一个更隐蔽的跨租户漏洞一个转售型开发者会把所有用户都挂在自己的一个 token 下调用 treg。此时两个不同用户的请求都带着同一个调用者身份如果都用retry-1作 key第二个用户就会拿到第一个用户的缓存结果——跨租户泄露在下一层重新出现。解法在 _scoped_idempotency_key把调用者声明的主标签primary tag折叠进存储的 key 里相当于给每个终端用户切出一个独立命名空间且不需要任何数据库迁移如果调用还带强制的 pinpin 也会并入命名空间改 pin 绝不可能暴露旧缓存。多租户边界细节可参见 docs/context/architecture/multi-tenancy.md。三道防线拿错结果会被大声拒绝即便有了隔离还有两种误用会被当场拦下而不是静默返回错误数据情况行为说明同一个 key 用于不同的请求返回422请求指纹方法路径querybody 的哈希不匹配时拒绝避免把旧答案塞给新问题同一个 key 的请求还在飞返回409第一次调用尚未完成告知稍后再试阻止第二次重复扣费并发重试同时到达数据库裁决先写入pending占位行输者靠唯一约束插入失败而等待赢家绝不发起第二次上游调用占位行即锁两个重试同时到达、同时查不到缓存时谁先插入(membership_id, key)谁赢另一个只能等——读后写的竞态窗口由数据库唯一约束关闭这与账本ledger.reserve的条件更新是同一套思路。回放响应如何被识别回放不是静默的。命中的重试会带上明确的响应头详见 docs/context/interface/api.mdX-Treg-Idempotent-Replay: true—— 告诉调用者这是回放的X-Treg-Cost-Micro: 0—— 回放不再产生新费用客户端的本地计费合计保持真实X-Treg-Original-Cost-Micro: 原费用—— 原始调用花了多少一并给出。通过 MCP 协议调用时同样是可选的idempotency_key参数回放结果带replayed: true。小结treg 的幂等机制可以浓缩为四句话只存付费成功的答案24 小时过期——重试免费但绝不变成通用缓存唯一约束落在 (调用者, key) 上——key 撞车是常态跨租户回放才是事故转售场景再按标签分区一层——共享 token 下每个终端用户各有独立命名空间指纹不符报 422、在途冲突报 409、并发靠占位行唯一约束——错误大声暴露数据永不串户。对普通用户来说这意味着放心让 Agent 重试账单不会重复结果不会串门。【免费下载链接】tregOpenRouter for agent tools. Join community here: https://discord.gg/6mQYYfFMAn项目地址: https://gitcode.com/GitHub_Trending/treg/treg创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考