数据库配置

Open Connector 使用 Drizzle ORM（基于 node-postgres）和 Postgres 作为持久化存储层。drizzle-kit 负责 schema push 和迁移命令；当前表清单以生成的 schema 文档为准。

支持的 Postgres 版本

Postgres v15 或更高版本
兼容所有主流托管 Postgres 服务：
- Supabase
- Neon（仓库当前生产部署使用；请使用带连接池的 URL，并选择靠近应用主机的区域）
- Amazon RDS for PostgreSQL
- Google Cloud SQL for PostgreSQL
- 自托管 Postgres

连接配置

通过 DATABASE_URL 环境变量配置数据库连接：

# 标准格式
DATABASE_URL=postgres://username:password@hostname:5432/database_name

# 示例（本地开发）
DATABASE_URL=postgres://postgres:postgres@localhost:5432/open_connector

# 示例（带 SSL 的生产环境）
DATABASE_URL=postgres://user:[email protected]:5432/open_connector?sslmode=require

建议在生产环境中使用 ?sslmode=require，以确保客户端与数据库之间的连接经过加密。大多数托管 Postgres 服务默认要求 SSL。

数据库迁移

Open Connector 使用 Drizzle 迁移管理 Schema 变更。迁移从仓库根目录运行，并设置好 DATABASE_URL（项目没有预构建镜像，迁移工具随源码提供）。

首次部署

首次部署后运行迁移以创建数据库表：

# 从仓库根目录运行，DATABASE_URL 指向目标数据库
DATABASE_URL='postgresql://…-pooler.…neon.tech/…?sslmode=require' pnpm db:migrate

连接器目录行会在服务器启动时自动写入（seedProviders），无需手动初始化连接器。

升级时执行迁移

每次升级 Open Connector 到新版本后，如果该版本包含 Schema 变更，需要执行迁移。建议在重启服务器之前或同时执行迁移，以避免出现使用旧 Schema 运行的情况。

# 拉取最新代码后，从仓库根目录执行迁移
git pull
DATABASE_URL='postgresql://…-pooler.…neon.tech/…?sslmode=require' pnpm db:migrate

本地开发使用 Schema Push

在本地开发环境中，可以使用 db:push 命令将 Schema 直接推送到数据库，无需生成迁移文件：

# 从源码仓库根目录运行
pnpm db:push

# 生成迁移文件（不直接应用）
pnpm db:generate

# 应用已生成的迁移
pnpm db:migrate

数据库结构

Open Connector 的数据库包含以下主要表：

表名	用途
`user`	控制台用户账号（Better Auth 管理）
`session`	用户登录会话
`account`	第三方登录账号关联
`organization`	多租户组织
`member`	组织成员关系
`project`	组织内的项目
`apikey`	Agent API Key（哈希存储，带 scope 元数据）
`auth_config`	OAuth 应用注册（加密存储 Client Secret）
`connection`	用户连接（加密存储 Token）
`tool_execution_log`	工具/凭证调用记录

防篡改审计轨迹（SHA-256 哈希链）以结构化 evlog 宽事件形式输出，并非存储在某张专用数据库表中。

完整的 Schema 定义参见代码仓库中的 packages/db/src/schema/ 目录，以及自动生成的文档 docs/generated/db-schema.md。

本地启动 Postgres（仅用于开发）

如果您在本地开发，可以使用仓库提供的 Docker Compose 配置只启动 Postgres：

# 从源码仓库根目录运行
pnpm db:start     # 启动 Postgres（端口 5432）
pnpm db:stop      # 停止 Postgres（保留数据）
pnpm db:down      # 停止并删除数据卷
pnpm db:watch     # 查看 Postgres 日志
pnpm db:studio    # 打开 Drizzle Studio（数据库可视化界面）

备份建议

对于生产环境，请配置定期自动备份：

Neon / Supabase：请按所选套餐在控制台配置并验证 Point-in-Time Recovery（PITR）和保留期
自托管：使用 pg_dump 配合 cron 定期执行，并将备份文件上传到对象存储（S3、R2 等）

# 手动备份示例
pg_dump \
  --no-password \
  --format=custom \
  --file=open_connector_$(date +%Y%m%d_%H%M%S).dump \
  "postgres://user:password@hostname:5432/open_connector"

数据库备份包含加密的凭证数据。CONNECTOR_ENCRYPTION_KEY 需要与备份一起安全保存才能进行恢复。仅有数据库备份而没有加密密钥，则无法恢复用户的 Token。

On this page