treg安全架构深度剖析Fernet加密、write-only密钥与审计日志的三层防线【免费下载链接】tregOpenRouter for agent tools. Join community here: https://discord.gg/6mQYYfFMAn项目地址: https://gitcode.com/GitHub_Trending/treg/tregtreg 是一个面向 Agent 的工具调用代理平台可理解为Agent 工具版 OpenRouter代理 3000 工具端点并按次计费。正因为所有凭证都汇聚到一台服务器treg 的安全设计尤为关键Fernet 静态加密保证密钥落盘即密文、write-only 密钥保证 API Key 只显示一次、fire-and-forget 审计日志保证每笔调用可追溯。本文带你完整看懂这套三层防线。一、Fernet 静态加密密钥落盘即密文1. 核心原则永远不存明文treg 的第一条安全决策写在代码注释里secrets are never stored plaintext密钥绝不明文落盘。所有上传的 API Key、OAuth Token 在写入数据库前都会经过 Fernet 对称加密。核心实现集中在 src/treg/crypto.py整个模块只有几十个行却定义了完整的加密契约encrypt()/decrypt()使用环境变量TREG_SECRET_KEY派生的 Fernet 密钥加解密new_key()生成一把全新的 urlsafe 密钥供部署时配置new_token()/hash_token()生成高熵随机 token 并计算其 SHA-256 哈希。2. 一个巧妙的开发环境警报器在开发环境如果忘记配置TREG_SECRET_KEYtreg 会临时生成一把只在内存中存活一把一次性密钥。后果是重启进程后所有密钥都无法解密——这是一种大声的失败逼着运维人员意识到你该配置密钥了而不是默默用明文运行。3. 解密只发生在调用瞬间解密动作只在一个位置发生代理转发请求前的内存中。密钥被解出、注入请求头、发往上游然后立即丢弃。明文密钥永远不会返回给任何客户端任何 API 响应的密钥视图都是脱敏的元数据名称、所有者、健康状态而非密钥值本身。二、write-only 密钥API Key 只显示一次1. 数据库里根本没有你的 Key这是 treg 密钥管理最值得学习的设计。当你创建一个 API Key形如treg_abc123...时mint_secret()生成明文同时计算前 12 位安全前缀和SHA-256 哈希明文在响应中恰好返回一次此后永远不再出现数据库只保存哈希和短前缀——哈希用于登录时查找匹配前缀用于在控制台辨认这是哪把 Key。这意味着即使整库被拖走攻击者拿到的也只有不可逆的 SHA-256 摘要。由于 token 本身就是高熵随机串非密码treg 选择快速的 SHA-256 而非慢速密码哈希——因为攻击者无法暴力枚举高熵空间只能做哈希碰撞而这在计算上不可行。密钥模型定义见 src/treg/models.pyApiKey表key_hash唯一索引、safe_prefix、state状态机active | disabled | revoked生命周期规则在 src/treg/domain/identity/api_keys.py。2. 原子轮换一次只能换一把轮换rotate是最容易出并发事故的运维操作。treg 用一条条件 UPDATE 语句作为跨进程锁UPDATE api_keys SET staterevoked WHERE id? AND state IN (active,disabled) AND replacement_key_id IS NULL先赢得这条更新的一方rowcount1才有资格插入新 Key并发请求拿到 rowcount0直接收到409 Conflict而不是创建出两把替换密钥或泄露数据库错误。旧 Key 被标记revoked且永久失效但审计行、事件与 Activity 快照全部保留——撤销是永久的只是隐藏不是删除。另外两个贴心细节响应头防缓存任何返回完整凭证的响应都带Cache-Control: no-store密钥不会落进浏览器或代理缓存last_used_at不阻塞认证最后使用时间只是展示元数据认证事务提交后才在 5 分钟窗口内异步更新高并发下请求不会挤在一行写锁上。三、审计日志fire-and-forget 也要有纪律1. 设计目标审计绝不能拖慢业务审计模块 src/treg/audit.py 的模块注释开宗明义never block the proxied response——写审计行入队后立即返回响应流不等待落盘。但随手一丢是有纪律的关键参数一目了然常量值作用_MAX_CONCURRENT_WRITES1每进程单写者省连接池_BATCH200每 200 行一次 INSERT 往返_MAX_PENDING5000队列超限即丢审计行绝不无限膨胀极端突发流量下宁可丢几行审计并记录已丢弃计数也不允许审计把内存吃爆、把真实业务卡死——审计是尽力而为业务才是第一优先级。2. 每笔调用都留下身份指纹record_call()写入的CallRecord不只有 URL 和状态码还包括调用者身份三元组api_key_idKey 的数据库 ID、api_key_name人类可读名称、api_key_prefix短前缀。注意——审计表里依然没有完整密钥只有足以定位谁的指纹。3. 密钥管理事件只增不改的账本ApiKeyEvent是一张append-only只追加的审计表谁、什么时间、对哪把 Key、做了什么rotated、revoked、disabled……。模型注释强调It never contains complete secret material——审计表永远不包含完整密钥材料审计本身也不能成为泄密渠道。团队控制台对密钥的禁用、轮换、撤销入口见 src/treg/web/ 下的管理页面危险操作撤销、移除成员有独立的确认界面。四、边界防御密钥的所有权围栏三层防线之外treg 还有一道横向的所有权边界成员只能绑定自己上传的密钥domain/tools/bindings.py的validate_bindings强制检查防止把队友的 Key 洗进自己控制的工具再经代理base_url外传base_url双重 SSRF 防护注册时校验 调用时重新解析主机屏蔽回环、内网、链路本地与云元数据地址含 DNS 重绑定且禁止把工具指向 treg 自身本地运行的密钥特许local-run grant是全系统唯一允许取回密钥值的路径且仅限会员 工具所有者开启 全程审计OAuth 场景下只放出短命的 access tokenrefresh_token与client_secret永远不出服务器。五、部署自检清单把 treg 的安全设计提炼为可执行的 5 条检查项配置TREG_SECRET_KEY——用new_key()生成未配置时密钥重启即失效是刻意的告警机制创建 Key 后立刻保存明文——write-only 意味着界面里再也找不到它轮换遇到 409 不要重试轰炸——说明另一请求已赢得轮换检查 Key 列表即可关注审计丢弃计数——队列超过 5000 会丢行持续丢弃说明写入端连接池/数据库需要扩容Webhook 告警地址走公网——健康检查的凭证失效通知会拒绝回环/内网/CGNAT 地址防止被当作 SSRF 跳板。结语treg 的安全架构没有花哨的组件却处处是失败要响亮、泄露要不可能的取舍Fernet 让密文成为唯一落盘形态write-only 让数据库拖库等于拖走一堆哈希审计日志用单写者 批量 背压保证记录一切与绝不拖垮业务可以共存。这三层防线的设计思路对任何要托管用户凭证的代理类项目都是很好的范本。延伸阅读docs/context/architecture/auth-secrets.md认证与密钥完整设计、tests/test_audit.py审计纪律的回归测试、tests/test_api_keys.py密钥生命周期测试。【免费下载链接】tregOpenRouter for agent tools. Join community here: https://discord.gg/6mQYYfFMAn项目地址: https://gitcode.com/GitHub_Trending/treg/treg创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考