企业官网建设流程全解析

密钥永不出服务器：treg服务端凭据注入的安全设计原理

【免费下载链接】tregOpenRouter for agent tools. Join community here: https://discord.gg/6mQYYfFMAn项目地址: https://gitcode.com/GitHub_Trending/treg/treg

treg 是一个面向 AI Agent 的工具网关（"OpenRouter for agent tools"），把 60 多个第三方数据源统一成一个地址、一个令牌。它的最大安全亮点是：你的 API 密钥永不出服务器——所有凭据都在 treg 服务端加密保存，调用时由代理在服务端即时注入到出站请求中，调用方和 Agent 自始至终只持有一个访问 treg 的令牌。这篇文章带你用 5 分钟看懂这套凭据注入安全设计的原理。

为什么密钥管理是 Agent 工具调用的最大隐患

当你的 Agent 需要调用 SEO、社媒、公司数据等外部 API 时，传统做法是把各家密钥塞进本地.env或 Agent 的上下文里。这带来三个真实风险：

treg 的思路是把"调用工具"这件事改造成经代理转发：Agent 只对 treg 说话，真实密钥从不离开服务器边界。

核心原则：代理只忠实转发，密钥只在服务端注入

treg 的代理遵守一条铁律（见 README.md 中的 "The one rule"）：

代理只做两件事——忠实转发上游请求 + 在服务端注入认证凭据；除此之外，方法、路径、查询参数、请求体字节一律原样透传。

转发时 treg 只改动三样东西：逐跳传输头、treg 自己的控制头（会被剥掉，绝不泄漏给上游）、以及注入的凭据。你可以在 src/treg/infra/upstream/relay.py 中查看这份"忠实转发契约"的完整实现。

实际效果如下图所示：在控制台点 "Try It" 发起请求，响应状态栏直接提示key injected by registry——密钥由注册表注入，客户端全程无感知。

凭据注入器（Injector）：让代理核心保持"无知"

不同供应商的密钥放的位置千差万别：有的在Authorization头，有的在 query 参数，有的在 JSON 请求体里。treg 用一组注入器（injector）解决这种差异，源码位于 src/treg/infra/upstream/injectors.py：

# 一个 binding 就是一个普通字典，描述"把哪个密钥放到哪里" { "secret_id": "xxx", "injector": "env", # 或 oauth / cli_auth / secret_file "location": "header", # header | query | json "name": "Authorization", "format": "Bearer {secret}", }

设计上有两个巧妙之处：

1. 注册表模式：代理按binding["injector"]查注册表分发，永远不知道自己在转发哪个供应商——新增一种认证形态只需加一个注入函数，代理核心代码一行不改；
2. 注入即覆盖：若调用方在同一位置传了伪造的凭据，注入值会强制覆盖，确保"注入的密钥获胜"，杜绝客户端劫持上游账户。

在控制台创建工具时，Binding 区域正是这套机制的可视化：一个工具可以绑定多个密钥（例如 OAuth Bearer +developer-token双凭据），每个绑定独立声明注入位置。

密钥落盘：Fernet 加密 + 只存哈希

密钥进了服务器之后怎么存？treg 的答案是任何密钥都以密文形式落盘，实现见 src/treg/crypto.py：

• 供应商密钥用Fernet 对称加密存储，加密主密钥来自环境变量TREG_SECRET_KEY；若未设置，系统会退化为进程内临时密钥——重启后所有密钥不可解，这被故意设计成"响亮的提醒"，逼你配置主密钥；
• 调用 treg 的 API 令牌（treg_开头）只存SHA-256 哈希+ 安全前缀，明文仅在创建时返回一次；
• 任何返回完整凭据的接口都带上Cache-Control: no-store，防止浏览器与中间缓存留存。

控制台 Secrets 面板的提示栏写得很直白："VALUES ARE NEVER SHOWN"——上传的密钥在界面上永远是掩码。

OAuth 令牌保鲜：自动刷新，绝不惊扰用户

OAuth 令牌会过期，treg 把"保鲜"做成了透明的后台动作（详见 docs/context/architecture/auth-secrets.md）：

• 到期前自动刷新：每次调用前检查expires_at（预留 60 秒余量），过期即静默换取新令牌并重加密落盘；
• 单一飞行（single-flight）：同一个密钥的并发刷新被锁串行化，写回还带上"旧密文条件更新"，多 worker 环境下第二次刷新不会冲掉第一次轮换出的 refresh_token；
• 可刷新凭证对用户永远显示"新鲜"：只有不可续期的令牌（如某些 LinkedIn 场景）才会在 7 天后收到"即将过期"警告。

唯一例外：local-run 授权如何被收窄到最小

treg 有一条受审计的例外路径——本地运行授权（local-run grant），它允许把凭据交给本地 CLI 使用。但这个例外被层层收窄：仅限成员身份、需工具属主逐工具开启、全程审计，且对 OAuth 凭据只放出短命的 access token，refresh_token与client_secret永不出服务器。在 Linux 上凭证还运行在专用treg-run用户下，成员自己的账户也读不到。这是一个"刻意的、窄缝般的例外"。

纵深防线：健康检查、所有权边界与 SSRF 防护

凭据注入只是第一道闸，treg 还配了完整的纵深防御：

给自部署者的 3 条落地建议

1. 务必设置TREG_SECRET_KEY——不设置意味着重启后密钥全部不可解，这是安全底线也是部署检查的第一项；
2. 区分两种密钥：调用 treg 的 API 令牌（存哈希、可吊销轮换）与供应商密钥（Fernet 加密、永不出服务器）是两个独立存储，备份时只备数据库与主密钥即可；
3. 启用健康检查：对 OAuth 凭证挂一个定时任务触发POST /health/run，令牌"悄悄过期"会在下一轮探测中第一时间暴露。

小结

treg 的凭据安全模型可以浓缩为一句话：密钥只存在于服务端，调用只携带令牌。Fernet 加密落盘保证"拖库不等于拖走密钥"，注入器注册表保证"代理永远不需要知道密钥长什么样"，自动刷新保证"用户永远不用管令牌过期"，而所有权边界与 SSRF 双重解析则封死了凭据被窃取或滥用的路径。对于想安全地给 Agent 接入外部工具的团队，这套"密钥永不出服务器"的设计范式本身就值得抄作业。

【免费下载链接】tregOpenRouter for agent tools. Join community here: https://discord.gg/6mQYYfFMAn项目地址: https://gitcode.com/GitHub_Trending/treg/treg