treg OAuth自动刷新机制深度解析：single-flight refresh如何保持令牌新鲜

treg OAuth自动刷新机制深度解析single-flight refresh如何保持令牌新鲜【免费下载链接】tregOpenRouter for agent tools. Join community here: https://discord.gg/6mQYYfFMAn项目地址: https://gitcode.com/GitHub_Trending/treg/treg在 treg面向 AI Agent 的 API 工具网关可理解为Agent 工具界的 OpenRouter中OAuth 自动刷新是保证上游 API 调用永不 401 的核心机制。当凭据临近过期时treg 会在单次调用内悄然换取新令牌借助single-flight单飞刷新哪怕同一时刻涌来上百个请求也只触发一次 token 端点请求。本文带你从零读懂这套机制的设计与实现。它解决了什么问题别再手动重新上传令牌用过 OAuth APIGoogle、X、Meta 等的人都熟悉这个痛点access_token 通常只有几十分钟到一小时的寿命过期后所有请求开始返回 401你得重新走一遍授权流程。treg 的做法是把凭据加密落库在每次调用转发给上游之前原地刷新。令牌过期对用户完全透明——上游看到的永远是一个活着的 token。两种凭据模式Auto 与 Manualtreg 用三把钥匙判断一个凭据能否自动续命逻辑在 domain/connections/refresh.py 的is_refreshable()中字段作用refresh_token用来换取新 access_tokenclient_id/client_secret客户端身份凭证三者齐全即进入Auto 模式treg 负责保鲜。缺任何一个字段则是Manual 模式用户自己上传裸 tokentreg 原样注入、绝不越俎代庖。在 Secrets 面板中你可以看到每个凭据的刷新状态、最近一次刷新时间和健康状态过期判断提前 60 秒动手什么时候算过期由is_stale()决定核心常量是 refresh.py 中的_SKEW 60.0距真实过期时间还剩 60 秒以内 → 视为 stale触发刷新拿不到过期时间 → 宁可刷新。这是保守策略未知比已知更危险反向同理HTTP 适配器在刷新成功后总会盖一个expires_at缺省按 1 小时兜底避免某家上游不返回expires_in导致每次调用都刷新的恶性循环。单飞刷新一次风暴一次刷新这是整套机制的精华。假设令牌刚刚过期而你的 Agent 在同一秒内发出了 50 个请求——如果每个请求都各自去 token 端点刷新就会造成刷新风暴50 次外部请求、可能 49 个过期的 refresh_token 互相覆盖。treg 的解法分三层全部在 refresh.py 的ensure_fresh()中第一层进程内锁按凭据 ID 隔离_locks: dict[int, asyncio.Lock] defaultdict(asyncio.Lock)每个凭据 ID 一把asyncio.Lock。第一个请求拿到锁去刷新其余 49 个在锁外排队。锁数量还会自我约束超过 512 把时自动清理空闲锁防止长驻进程无限增长。第二层锁内复查避免重复劳动拿到锁后先执行db.refresh(secret)——重新从数据库读一次。因为在你排队期间先行者可能已经刷新完毕。如果新读到的 blob 已经不再 stale直接返回一次 HTTP 都不用发。第三层跨进程条件写多 Worker 互不踩踏进程内锁只能管住自己这个 Worker。生产环境多个 Worker 并发时treg 用乐观锁式的条件更新兜底UPDATE secrets SET value 新密文 WHERE id ? AND value 刷新前的旧密文写回以旧密文为前置条件。若另一个 Worker 已经把 refresh_token 轮转掉了你的WHERE value old_value匹配不到任何行写入自动落空随后db.refresh()重新加载获胜者的 blob 用于本次注入。刷新过的 refresh_token 永远不会被旧值覆盖。刷新请求本身方言、认证与轮转真正与上游 token 端点对话的是 infra/oauth_refresh.py 中的HTTPXOAuthRefreshPort.exchange()它处理了三类各家供应商的方言参数名差异TikTok 读的是client_key而非client_id。这些方言在首次授权时就快照进凭据 blob几个月后刷新仍说正确的方言认证方式差异X 和 Pinterest 要求把 client_secret 放进 HTTP Basic 头放请求体会被 401 拒绝。认证方式同样记录在 blob 里老凭据缺这个字段时会先用请求体方式试一次4xx 后自动重试 Basic并把生效的方式回写下次一步到位——存量坏连接会在下一次调用时自我修复无需迁移refresh_token 轮转上游若返回新的 refresh_token 则采纳否则沿用旧的。另外两个工程细节值得一提刷新前先提交数据库事务让网络等待期间不占用任何数据库连接池槽位——否则慢速的上游会把池子堵死application/call/service.py 中的注释记录了这次死锁的完整复盘刷新失败会写入last_error凭据页面上能直接看到为什么续不上而不是一连串无解释的 401。刷新在哪些路径上生效同一个ensure_fresh()被所有需要令牌的入口复用做到一处刷新处处新鲜调用主链路每次 API 调用注入凭据之前见 call/service.py刷新失败会向上抛出明确的502 oauth refresh failed而不是注入一个死令牌健康巡检health.py 的巡检 Runner 走同一条刷新路径先保鲜再探测资源发现与本地运行resource discovery 与 local-run 也复用同一实现不另起炉灶。配套地docs/context/architecture/auth-secrets.md 对这套新鲜度规则有完整描述其中expiry_state()把可自动续期的凭据永远标记为fresh用户无需被骚扰只对无法自续的凭据发出 7 天内过期的预警并给出唯一的行动指令字段needs_reconnect。测试如何证明只刷新一次tests/test_oauth_refresh.py 用行为级测试锁住了这套语义几个关键用例测试验证点test_stale_token_is_refreshed_before_call过期令牌在调用前被静默换掉上游看到Bearer REFRESHEDtest_valid_token_is_not_refreshed有效令牌原样透传不做无谓刷新test_manual_mode_token_without_refresh_fields_is_injected_as_isManual 模式凭据绝不触碰刷新逻辑test_concurrent_stale_calls_keep_one_refresh_winner两个并发过期请求同时到达token 端点只收到 1 次调用两者都拿到同一个新令牌test_token_endpoint_io_holds_no_database_connection刷新期间数据库连接池占用数为 0最后那条并发测试正是single-flight的直接证据测试故意把 token 端点挂起让两个请求同时进入刷新路径最终断言calls 1。总结treg 的 OAuth 自动刷新可以浓缩成一句话提前 60 秒、每把凭据一把锁、锁内复查一次、跨进程条件写一次——四层防线叠加让令牌在调用者完全无感的情况下始终保持新鲜。对新手来说使用上只需要记住两点通过 treg 的托管授权流程treg oauth connect接入的凭据天生处于 Auto 模式之后不用管它手动上传的裸 token 属于 Manual 模式treg 不会替你续期过期请重新上传。更多架构细节可参考 docs/context/architecture/ 下的 auth-secrets 与 proxy-model 两篇文档。【免费下载链接】tregOpenRouter for agent tools. Join community here: https://discord.gg/6mQYYfFMAn项目地址: https://gitcode.com/GitHub_Trending/treg/treg创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考