treg数据模型深度解析：Org、Secret、Tool、Bundle核心表设计完全指南

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

treg（"OpenRouter for agent tools"）的数据模型是理解这套多租户 API 代理平台的关键。本文带你从新手视角读懂它的核心表设计：Org（团队/租户）、Secret（加密凭证）、Tool（可调用工具）、Bundle（技能打包），以及余额账本、调用审计等配套表。全部列定义以 src/treg/models.py 为权威来源，架构背景见 docs/context/architecture/data-model.md。

数据模型总览：一张图看懂表关系

treg 的所有租户资源都挂在org_id外键上，形成清晰的"团队 → 成员 → 凭证/工具"层级。核心关系如下：

一个容易混淆的点：一个"token"= 一个 (User, Org) 组合。同一个人加入 N 个团队，就有 N 条Membership、N 个 token，但User表里只有一条记录（见 src/treg/models.py）。

Org 表：多租户的根基

Org是多租户的锚点，字段设计很有代表性（src/treg/models.py）：

• balance_micro—— 以微美元（1e-6 USD）为单位的预付费余额。做成物化列而不是查询，是因为它是热路径上的花费闸门：一次条件 UPDATE 就能阻止并发调用把余额刷成负数；
• spent_today_micro/spent_today_day—— 当日累计花费计数器，供 fail-closed 的每日限额在每次计费调用中做单次主键查询，避免扫描整天的账本；
• previous_slug—— 团队改名后旧 slug 仍可作为别名解析，避免所有已分发的密钥瞬间失效；
• Stripe 自动充值字段（autotopup_*系列）—— 阈值、金额、月度上限与合规时间戳，自动充值默认关闭。

Secret 表：凭证永不离开服务器

Secret存储的是凭证本体，核心设计有三点（src/treg/models.py）：

1. value字段 Fernet 加密落盘，永远不会返回给客户端；
2. kind字段选择注入器：env（环境变量）、secret_file（密钥文件）、oauth、cli_auth或param（非机密参数，如项目 ID）；
3. 健康与过期是两条独立轴：health_status（unknown/ok/invalid）回答"现在能不能用"，expires_at回答"还能用多久"——一个不可刷新的 token 会一直保持 healthy 直到悄悄失效，所以必须单独展示。

此外，注册表 OAuth 连接还会记录provider、granted_scopes、resource_ref等元数据，标注这条连接"代哪个站点/账号行事"。

Tool 表：多凭证绑定（bindings）

Tool注册一个可调用能力 = 上游base_url+一个凭证绑定列表（src/treg/models.py）。每个绑定形如{secret_id, injector, location, name, format, secret_field}，表示一次凭证注入；一次请求会应用该工具全部的绑定——例如 google-ads 同时需要 OAuth Bearer 头和developer-token头。

其他实用字段：host（base_url 的域名，建索引以支持 URL 直通解析）、examples（展示在仪表盘的调用示例）、health_check（凭证健康探针）、cli（本地运行treg run --local的配置文件）。代理只中转（relay）、不建模上游，且凭证在服务器端注入，调用方永远不接触密钥。

Bundle 表：把整个技能文件夹打包

Bundle就是"技能"，纯打包概念（src/treg/models.py）：

• recipe—— SKILL.md 的文本，可分享的"怎么做"说明；
• files—— JSON 字典{relpath: content}，承载文件夹里其余文件（参考文档、脚本、子目录），于是skill install一次就能重建整个技能目录；
• 其下的 Secret 与 Tool 通过bundle_id反向引用，实现"注册一个技能"即成组创建。

运行配置（treg run的两种模式）统一放在Tool.cli上，而不是 Bundle 侧，这是后期"工具侧统一"重构的结果。

钱与审计：CreditBlock、LedgerEntry 与 CallRecord

余额不是单标量，而是"资金块"（CreditBlock）：促销赠送与购买充值分成不同的块，因为购买额度是可退的递延收入、促销额度不可退；消费顺序是"先促销、后最早的购买"，退款池因此最小化（src/treg/models.py）。

LedgerEntry 是只追加的钱账：每次余额/块变动写一行，与变动同事务提交，从不修改或删除——更正靠补偿性新条目。金额从团队视角带符号（充值为正、扣款为负），call_id关联"预留 → 结算/释放"对。

CallRecord 是"平台吞吐量的索引所在"：谁、何时、调了哪个工具、什么结果，异步写入不阻塞代理路径。它记录cost_estimated_micro（预留额）、cost_observed_micro（供应商实际报价）、refused_by（区分"平台拒绝"与"上游失败"）等。官方文档特别强调：(org_id, created_at)这类复合索引就是平台吞吐的一部分，索引缺失会让全库查询排队直至 API 池耗尽。

迁移与延伸阅读

• 所有生产 schema 变更由 Alembic 管理，迁移脚本在 src/treg/alembic/versions/（0001 基线 + 50 余个演进版本）；
• 余额、预留、结算的业务逻辑集中在 src/treg/domain/money/；
• 多租户隔离与角色门控见 docs/context/architecture/multi-tenancy.md；
• 完整表清单（含 OAuth 四表、归档、容量策略等）见 docs/context/architecture/data-model.md。

小结：新手记住三句话

1. 一切资源挂org_id——多租户隔离靠外键 + 会员 token，而非独立数据库；
2. 凭证加密落盘、服务器端注入——Secret 永不回传，调用方零接触密钥；
3. 钱走同步账本、日志走异步审计——LedgerEntry 绝不丢行，CallRecord 允许丢弃，两条纪律严格分开。

掌握这三点，treg 数据模型的地基就立住了。🧩

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