Open Agents 数据库设计：Drizzle + Postgres 的 15 张表完全指南

Open Agents 数据库设计：Drizzle + Postgres 的 15 张表完全指南

【免费下载链接】open-agentsAn open source template for building cloud agents.项目地址: https://gitcode.com/GitHub_Trending/op/open-agents

Open Agents 是一个构建云端编程 Agent 的开源模板，其后端基于Drizzle ORM + PostgreSQL构建。本文带你完整解析它的15 张数据表设计——从用户认证到会话、聊天、沙箱生命周期与用量统计，帮你快速理解这套 AI Agent 云平台的数据库架构，以及如何在自己的项目中复用这套设计思路。

为什么选择 Drizzle + Postgres？

Open Agents 的数据库层非常精简，核心只有三个部分：

相比传统 SQL 文件维护表结构，Drizzle 的优势在于：

• 类型安全：每张表通过$inferSelect/$inferInsert自动推导 TypeScript 类型，写查询时 IDE 直接提示字段
• 声明式迁移：改一次schema.ts，drizzle-kit自动生成带编号的 SQL 迁移文件，历史可追溯
• 配置极简：整个连接配置见 drizzle.config.ts，只需一个POSTGRES_URL环境变量

💡 数据库连接采用 Proxy 懒加载模式（client.ts），首次访问时才建立连接，避免服务启动时的冷启动开销。

15 张表全景图：四大模块分组

15 张表按业务职责可以分为四组，这也是阅读 schema.ts 源码的最佳顺序：

一、认证模块（4 张表）：Open Agents 用户登录体系

这张表是整库的"根"，其余表全部通过外键references(() => users.id)关联它，并统一使用onDelete: "cascade"级联删除——用户注销后，其所有会话、聊天、用量数据自动清理，无需写清理脚本。

二、平台集成模块（2 张表）：连接 GitHub 与 Vercel

这两个表体现了云端 Agent 的核心定位：它不只是一个聊天机器人，而是一个能直接操作你代码仓库和部署平台的系统。

• github_installations上有两个唯一索引（用户+安装 ID、用户+账户 login），保证同一账户不会重复记录
• vercel_project_links用(user_id, repo_owner, repo_name)复合主键，一个仓库对应一个项目，天然防重

三、核心业务模块（5 张表）：Session → Chat → Message 三级结构

这是 Open Agents 数据模型的心脏：

users (1) ──< sessions (1) ──< chats (1) ──< chat_messages │ │ │ ├──< chat_reads（已读状态） │ └──< shares（分享链接） └──< workflow_runs ──< workflow_run_steps

重点拆解：sessions 表的"沙箱生命周期"设计

sessions表（schema.ts#L126-L201）字段最多，是理解整个项目的关键。它同时承载了四类信息：

1. 仓库定位：repo_owner/repo_name/branch/clone_url，其中is_new_branch标记是否自动创建了新分支
2. 沙箱状态：sandbox_state（JSONB）+lifecycle_state枚举（provisioning / active / hibernating / hibernated / restoring / archived / failed），配合lifecycle_version做乐观锁，防止并发状态覆盖
3. 休眠调度：hibernate_after/sandbox_expires_at/last_activity_at三个时间戳，支撑"空闲自动休眠、唤醒自动恢复"的快照机制
4. 成果追踪：pr_number/pr_status（open/merged/closed）、lines_added/lines_removed，让会话列表直接展示产出统计

这种"生命周期状态机落库"的做法，配合 SANDBOX-LIFECYCLE.md 文档描述的编排流程，是 Agent 类应用保证任务可恢复性的关键——即使服务器重启，进程也能从数据库状态续跑。

重点拆解：消息为何用 JSONB 存储 parts？

chat_messages表刻意把消息内容整体存进partsJSONB 字段（schema.ts#L233-L244），而不拆成"文本表 + 工具调用表"。原因是 AI 消息结构多变（文本、推理、工具调用、审批按钮混杂），JSONB 提供了"灵活存储 + 可索引查询"的平衡点，避免了为每种消息类型加表。

四、运行与用量模块（4 张表）：Agent 执行的"黑匣子"

这组设计有两个亮点：

• Workflow 双层记录：workflow_runs+workflow_run_steps把一次 Agent 执行拆成"运行-步骤"两级，每步都记录耗时和结束原因。这正是 Open Agents"持久化工作流"架构的落地——Agent 不依赖单次 HTTP 请求生命周期，断了可以从最后一步恢复
• 用量表只增不改：usage_events按"每条助手回复一行"追加写入，按用户/模型/Agent 类型（主 Agent / 子 Agent）分维度记录 token。它是排行榜（usage-domain-leaderboard.ts）和用量洞察（usage-insights.ts）的数据底座，append-only 模式天然适合聚合分析

索引与外键：三个值得抄的设计细节

1. 高频查询路径都有索引

sessions按user_id、chats按session_id、workflow_runs按chat_id / session_id / user_id建索引——恰好对应"我的会话列表""会话内聊天""某次运行记录"三条最热查询路径。

2. 级联删除贯穿全库

几乎所有外键都是onDelete: "cascade"：删用户 → 删会话 → 删聊天 → 删消息/运行记录，数据一致性靠数据库而非应用代码保证。

3. 迁移自愈机制

启动时的迁移脚本（migrate.ts）不仅执行 SQL，还能检测"有表结构但没有迁移历史"的遗留数据库，跳过已存在的对象并补录迁移记录（migrate.ts#L109-L152），对 fork 后直接跑的场景非常友好。

快速上手：如何运行这套数据库

1. 准备 Postgres 连接串，填入POSTGRES_URL环境变量
2. 参考 [apps/web/.env.example] 补齐其他密钥（Neon 可自动提供 Postgres）
3. 部署时自动执行 migrate.ts 完成建表，无需手动跑 SQL

总结：这套设计的可复用经验

Open Agents 的 15 张表给出了一个 AI Agent 产品的完整数据模型参考：

如果你想在自己的项目中实践 Drizzle + Postgres，建议从 apps/web/lib/db/schema.ts 入手通读一遍表定义，再结合 migrations 目录 中 37 个迁移文件，观察这套 schema 是如何一步步演化而来的——这本身就是一份免费的数据库演进教科书。

【免费下载链接】open-agentsAn open source template for building cloud agents.项目地址: https://gitcode.com/GitHub_Trending/op/open-agents