后端API网关MCP 服务dsh-plugin【免费下载链接】tregOpenRouter for agent tools. Join community here: https://discord.gg/6mQYYfFMAn项目地址https://gitcode.com/GitHub_Trending/treg/treg点击查看免费下载导读本文是 tregOpenRouter for agent tools一个面向 Agent 工具调用场景的注册表与代理平台的数据模型技术指南。全文以 docs/context/architecture/data-model.md 为骨架结合 src/treg/models.py模型权威定义、src/treg/infra/db.py异步数据库引擎、src/treg/audit.py审计写入器等源码展开。读完你将掌握treg 的三大异步连接池如何做 bulkhead 隔离、每一张注册表核心表的字段语义与所有权边界、Alembic 迁移的只增不改纪律与采纳门槛、以及审计/产品分析写入器为何采用尽力而为、可丢行的设计哲学。一、数据模型总览最小化的多租户注册表treg 的数据模型刻意精简charter 原则不发明多余的抽象名词。整个模型围绕一个核心形状展开Org组织/租户是拥有资源的租户边界User用户只是全局身份邮箱唯一不携带任何令牌或角色Membership成员关系把用户挂到组织上携带角色和令牌——一个令牌 一个(user, org)对一个用户在 N 个组织里就有 N 个 membership所有资源表Secret、Tool、Bundle、CallRecord 等都带org_id因此任何列表、调用、变更都以调用者的组织为作用域。src/treg/models.py是列、索引和默认值的权威定义而>POOL_SPECS: dict[str, dict[str, int]] { api: {pool_size: 5, max_overflow: 10}, admin: {pool_size: 3, max_overflow: 0}, background: {pool_size: sum(BACKGROUND_CONSUMERS.values()), max_overflow: 0}, read: {pool_size: 2, max_overflow: 0}, # optional replica }关键设计点大小刻意不均衡API 是产品其余两个不是。两个次要池溢出为 0——溢出是 bulkhead 绝不能有的逃生舱。池而非信号量信号量只约束记得取它的模块池约束路由到它的每个模块。background由BACKGROUND_CONSUMERS清单求和而来不是随手挑的数audit._flush(1)、archive._store/_touch(2)、adsconv.worker(1)、archive.prune_worker(1)、archive.refresh_worker(1)、catalog observation refresh(1)、admin evidence sweep(1)、api_keys last used(1)。清单是事实来源测试走它——一个漏掉的消费者就是在负载下静默丢行。池大小是每进程的web 服务跑两个 uvicorn worker、滚动部署短暂跑两个实例所以per_process × 2 × 2必须低于数据库计划的 103 连接上限connection_budget()计算 per_process/per_instance/deploy_peak 并打日志。pool_timeout5s非 SQLAlchemy 默认 30拿不到槽位的请求是 treg 饱和调用者应快速听到类型化的503 treg_saturatedbootstrap_handlers把 TimeoutError 映射为带 Retry-After 的 503而非等 30 秒换匿名 500。槽位只约束毫秒级的并发 DB 阶段——/call/在上游往返期间不持连接call_tool在relay()前提交。TREG_DB_POOL_OVERRIDES如admin.pool_size4,background.pool_size12支持事故中免部署调池未知/畸形/越界条目记日志并跳过但必须说出来——被静默忽略的覆盖让操作员以为改了。_OVERRIDE_FLOORS强制pool_size1、max_overflow0——SQLAlchemy 把 0 或负溢出读作无限2026-08-15 事故正是经防事故的旋钮进入的。/call/的 relay 后记账步骤用session_maker请求会话在 relay 前提交因此它们永不等它见 proxy-model § Connection discipline。dispose_engine()在显式维护事件循环退出前关闭池化连接防止后续服务器循环继承绑定到已关闭循环的连接。verify_db()是只读生命周期与 worker 守卫保留缺 Fernet 密钥的拒绝真实 DB 无TREG_SECRET_KEY拒绝启动——临时密钥会在重启时丢失所有已存 secret、要求头部戳记、拒绝已知较旧修订、对未知更新修订警告但继续服务仅增时代可回滚。reset_db()仅测试用dispose 每个循环绑定池、重建 SQLite 模式或截断 Postgres 应用表、同事务写 Alembic 头戳。避开逐测试 Alembic 运行与 Postgres DDL 保持套件快速同时不削弱 autogenerate drift 守卫。可选只读副本TREG_READ_DATABASE_URL增加独立 SQLite/Postgres 引擎与read_session_maker。Postgres 默认把事务设为只读default_transaction_read_only: onSQLite 在专用读连接上开PRAGMA query_only。空 URL 别名现有主会话写入行为不变配置的数据源故障向上传播、无主库回退。尚无业务调用者使用此数据源——启用前必须处理供给/复制、副本延迟与每个调用者的写边界仅一个 URL 不会同步数据库。七、Alembic 执行与采纳门槛Alembic 通过maintenance._upgrade_schema拥有所有生产模式执行空或已戳记的库运行alembic upgrade head非空未戳记库不经检查或写入即被拒绝必须经过采纳发布 0.14.x显式升级也拒绝未知较新修订不能安全跨回滚地板迁移。迁移脚本在src/treg/alembic/随打包 wheel 分发。仓库根 alembic.ini 供开发者 CLI 使用script_location %(here)s/src/treg/alembicmaintenance._alembic_config解析已安装包资源并提供配置的数据库 URL。Alembic 命令经asyncio.to_thread运行env 拥有自己的asyncio.run。在 Postgres 上env.py 在迁移前设lock_timeout 5sstatement_timeout 120s锁竞争干净失败transaction_per_migrationTrue让每个修订各自提交maintenance的有界重试从超时处恢复。权威 drift 守卫升级到 head、对SQLModel.metadata跑 Alembic autogenerate、要求空 diff。测试经reset_db()保持快速create_allfixtures同事务戳头drift 守卫在完整套件里跑 SQLite、在test-postgresCI 跑 Postgres。test_alembic_expand_safety.pytests/test_alembic_expand_safety.py只解析每个修订的upgrade()体允许一封闭集合的仅增 Alembic 操作ADDITIVE_OPERATIONS frozenset({ add_column, bulk_insert, create_check_constraint, create_foreign_key, create_index, create_table, create_unique_constraint, f, })任何 ALTER、DROP、raw 执行或未知操作必须设模块级contract True并在模块 docstring 命名回滚地板。修订 0003、0004、0008 声明了它们各加一个 NOT NULL 列并去掉服务端默认——旧代码无法再插行。0021 也设contract Truepro forma——CREATE INDEX CONCURRENTLY被计数为非仅增但操作只是一个仅增索引0021 展示了并发构建纪律autocommit 块 提高的lock_timeout/statement_timeout 构建前检查 INVALID 碎片。0036 的 Activity 索引在列事务提交后的独立修订中于 Postgres 用CREATE INDEX CONCURRENTLYSQLite 正常创建。八、审计写入器audit.py尽力而为、可丢、可恢复src/treg/audit.py 的record_call/record_run经background_session_maker调度尽力而为写入永不延迟或失败一个代理响应_pending保留任务循环绑定信号量限制并发写入_MAX_CONCURRENT_WRITES 1——每进程一个批写者_MAX_PENDING 5000超界丢行绝不 OOM 或卡死服务器。_BATCH 200行/INSERT 往返失败批次逐行重试一行被拒只花那一行不连累周围 199 行——突发中的失败证据正是突发不能带走的东西。_known_fields对照模型字段过滤遥测并在未知键上告警——一个未知键必须只损失一列、绝不整行遥测字段先于迁移落地会静默删除它触及的每一行。drain()循环到队列为空含关闭期间新加的任务。_writer_done回调处理写入者最后一次空队列检查后入队的窗口。丢数据是 ERROR 而非 WARNING_write_batch失败、_enqueue背压丢行都记 ERROR——因为FaultCaptureHandler从 ERROR 开始低于它损失只到容器 stdout无法告警。不花钱的降级归档查找回退实时调用、重试通过留在 WARNING——分界线是数据是否真的丢了。审计是丢数据的分析与诊断。资金操作必须用同步 ledger。九、产品分析写入器analytics.pyPostHog 批量、永不 raise与audit.py同样的丢数据纪律但汇是 PostHog 的/batch/端点而非 DBcapture(distinct_id, event, properties, groups)同步且永不 raise调用点在 Stripe webhook 内异常会 500 并触发对已入账支付的重复处理排队到_MAX_PENDING超界丢最新一个 flusher 任务微批_BATCH_MAX/POST最多每_FLUSH_INTERVAL_S经每 flush 的 httpx 客户端——无信号量发往 PostHog 的 HTTP 不碰 DB 池。空posthog_key 模块关闭自托管者与测试套件什么都不发。$groups: {team: org_slug}镜像浏览器的posthog.group(team, slug)。每个事件携带buildTREG_BUILD否则主机导出的 commit 变量否则已装包版本与archive_config12 位十六进制摘要概括改变调用行为的归档设置。它们让分析能限定到一个代码版本或一个缓存配置而非记住的部署时间。归因产品事件用调用者邮箱与团队组与 SPA 识别的同一个人/组预身份call_intake_failed用固定treg-server身份且无团队认证拿不到 DB 连接。发射器call_tool的_audit漏斗tool_called目录provider作厂商或自有工具的上游 host、bootstrap_handlers._pool_saturatedcall_intake_failed、billing_topuptopup_started、billing._credittopup_completed按fresh门控。drain()在生命周期finally最后执行——在audit.drain()与archive.drain()之后它是那两个上报损失的汇。故障捕获capture_fault发 PostHog$exception事件固定treg-server身份只带异常类、最多 500 字符字符串、未处理机制、组件/日志标签异常值中的 URL 查询串在截断前替换为?[redacted]。FaultCaptureHandler镜像 ERROR 记录、忽略treg.analytics日志树、线程本地重入守卫 永不 raise 的emit生命周期在根与uvicorn.error上安装、关闭 drain 后移除。重复上卷不限速_note_fault每(fault type, logger/site)开一个_FaultWindow_FAULT_WINDOW_S首个立即上报其余计数_emit_fault_summaries在 flusher 定时器及drain()中释放计数永不在下次出现时——风暴已停或事故中重启时计数不再随之消失。每事件带fault_occurrences它代表的次数sum(fault_occurrences)是真实总数。窗口载荷构造时固定PostHog 按异常类型值指纹——带后续消息的摘要会落入不同 issue 并拆散总和。成本按键基数_FAULT_MAX_KEYSLRU 驱逐有界而非按量。仅在共享队列真正积压时丢故障_FAULT_QUEUE_SHAREof_MAX_PENDING。十、Arena 与归档相关表Arenarevision 0027 加ArenaRun与ArenaEvaluationEnrich Arena。Run 冻结加密输入、适配器请求、结果与收据evaluation 记录不可变偏好 暴露候选集与反馈上下文版本 2 起归因。两者 creator/team 作用域、30 天后过期。Run 用条件更新 claim唯一 run-id evaluation 约束与 run 行锁序列化并发反馈查看结果不提交投票。这些表无余额写入职责。0028 加ArenaObservation匿名分类审计事实30 天窗口与ArenaInsightState收集游标 聚合 JSON仅application.arena_insights写无审计外键审计保留独立都不存原始请求/响应/凭据。0029 加ArenaVerificationSnapshot仅application.arena_verification_insights.publish_snapshot写不可变 run ID、内容摘要、发布时间与聚合 JSON 让验证试点独立于滚动观测不含联系人/原始证据。归档保留保留统计计数带可恢复 body 的逻辑快照含 R2 与去重版本。剪枝 DB 字节把both变r2而不减计数剪掉最后一份 DB 副本清除body_storage并递减。失败的 R2-only 上传仍追加仅哈希快照null 位置。退役的volatile_paths列保留兼容、不再出现在 admin 响应中。归档语义详见 archiveresult admission、body storage 与 R2 双写、own-key answers、sharing、pricing a hit。托管密钥迁移顺序0034 加密钥控制、事件、可空 Activity 快照与仅哈希回填0035 加 Default-key generation。0034 是安全回滚地板旧服务器代码无法强制禁用或吊销密钥。两者都不在持有列 DDL 锁时在大型 Activity 表上建索引。0036 的(org_id, api_key_id, id)部分索引api_key_id IS NOT NULL支撑list_calls/list_runs的 team/key 过滤与最新优先分页历史未指派行留在索引外。十一、租户作用域与最终提醒每个租户资源携带org_idmembership 令牌在一个组织内标识一个用户。owner记录创建者并参与角色检查。隔离与清理详见 multi-tenancy。贯穿全文的三条纪律值得带走索引就是吞吐量——CallRecord/LedgerEntry的时间窗口索引故事0020/0021/0022/0023/0024是把计数移到热列、让聚合走出请求路径的完整演进直接服务于503 treg_saturated的消除数据库是最后的仲裁者——幂等AdConversion唯一(org_id, action)、CreditBlock.stripe_payment_intent、Referral双唯一、IdempotentCall唯一约束、ledger.reserve条件 UPDATE与防竞态OAuthCode兑换即删、OAuthRefresh家族吊销全部落在约束上而非 SELECT-then-INSERT 的应用代码上写入分层按可丢性分级——资金同步 ledger、append-only 持久 outboxAdConversion 尽力而为audit/analytics可丢、丢即 ERROR。这是 treg 数据模型把分析与会计分开的根源也是任何在此基础上做二次开发的团队最需要理解的分界线。赞分享后端API网关MCP 服务dsh-plugin【免费下载链接】tregOpenRouter for agent tools. Join community here: https://discord.gg/6mQYYfFMAn项目地址https://gitcode.com/GitHub_Trending/treg/treg点击查看免费下载相关推荐如何用AI求职自动化工具career-ops轻松找到理想工作如何用AI求职自动化工具career ops轻松找到理想工作 还在为海量职位筛选而烦恼吗还在手动填写无数申请表吗career ops是一款开源的AI求职自动人工智能AI 应用AI 技能LobeChat数据库设计完整表结构关系模型解析LobeChat数据库设计完整表结构关系模型解析 LobeChat作为一款强大的AI协作平台其高效运行离不开精心设计的数据库架构。本文将深入解析LobeCh人工智能AI 应用大模型AI Agent多智能体工具调用前端后端Android 内存优化实战十分钟搭好 Perfetto 内存采集链路从诊断到修复Android 内存优化实战十分钟搭好 Perfetto 内存采集链路从诊断到修复 一个节假日里某视频 App 的长视频场景集中告警用户连看一小时后进可观测性后端开发工具前端数据可视化上一篇终极Bend语言代码混淆与保护指南商业应用安全策略全解析下一篇LAVIS 实战教程基于 BLIP Large 在 COCO-Captioning 上进行微调训练创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
