进阶 omnigent.ai 2026-10-14 06:47:13 · 22 阅读

第14章 Omnigent 数据库配置指南：Postgres、CockroachDB 与 SQLite

Database

Omnigent 服务器需要数据库来持久化会话历史、用户账户和工件。支持 Postgres、CockroachDB 和 SQLite。三者使用相同的 schema 和 migrations。

Postgres（推荐）

Postgres 是生产环境的首选。如果你运行多于一个服务器实例，则必须使用 Postgres。

Render 和 Railway 已预置。Render 会自动完成配置；在 Railway 上，你需要自行添加 Postgres 插件，并应用户服务上设置 DATABASE_URL 引用变量（${{Postgres.DATABASE_URL}}）。

其他平台请自带数据库。最快的选项是 Neon：创建一个数据库并设置 DATABASE_URL。

任何 postgres:// 或 postgresql:// URL 均可使用。Entrypoint 会自动标准化。

DATABASE_URL=postgresql://user:pass@host:5432/omnigent

Postgres 驱动

PostgreSQL 驱动（psycopg）作为可选扩展提供，不在基础安装中。当你将自安装的 Omnigent CLI 或服务器指向 Postgres 数据库时，请安装它：

pip install 'omnigent[postgres]'

如果使用 uv 工具安装，请添加驱动：

uv tool install omnigent --with 'psycopg[binary]'

如果数据库 URI 指向 Postgres 但驱动缺失，Omnigent 将启动失败并给出包含上述安装命令的可操作错误信息。

通过设置 OMNIGENT_DATABASE_URI（或传入 --database-uri）为 postgresql+psycopg:// URL，将 CLI 或本地服务器指向 Postgres：

OMNIGENT_DATABASE_URI=postgresql+psycopg://user:pass@host:5432/omnigent

裸 postgres:// 和 postgresql:// URL 会自动标准化为 psycopg 3 dialect；直接传入 URI 时，建议使用显式的 postgresql+psycopg:// scheme。旧的 psycopg2 dialect 未被安装——请切换 scheme 为 postgresql+psycopg://，或自行安装 psycopg2-binary 以保留 psycopg2。

CockroachDB

CockroachDB 通过其 SQLAlchemy dialect 获得支持。在将 Omnigent 指向 CockroachDB 连接前，请安装可选驱动：

pip install 'omnigent[cockroachdb]'

如果数据库 URI 指向 CockroachDB 但驱动缺失，Omnigent 将启动失败并给出包含此安装命令的可操作错误信息。

两种 URI 格式均可。Omnigent 会将短格式标准化为 psycopg 3：

cockroachdb://user:password@host:26257/database
cockroachdb+psycopg://user:password@host:26257/database

直接传入 URI 时，建议使用显式的 cockroachdb+psycopg:// scheme。

兼容性

Omnigent 要求 CockroachDB v23.2.28 或更高版本。

CockroachDB v23.2 提供 READ COMMITTED 作为可选预览功能。请在启动 Omnigent 前在集群上启用它：

SET CLUSTER SETTING sql.txn.read_committed_isolation.enabled = true;

Omnigent 在启动时检查实际隔离级别，并给出可操作错误而非静默地将 v23.2 事务运行在 SERIALIZABLE 下。引擎在 READ COMMITTED 下运行，保留显式行锁，并在发生序列化错误（SQLSTATE 40001）后重放仅限数据库的事务回调；它从不重试约束失败或外部副作用。

首次启动

针对空数据库启动 CockroachDB。首次启动时，Omnigent 直接创建当前 schema 并打上当前 Alembic revision 戳，而非运行历史的 PostgreSQL migration 链。由先前尝试遗留的部分 revision 数据库不受支持，必须替换为新的空数据库。由受支持的 Omnigent 版本创建的现有 CockroachDB 数据库，后续 migrations 将使用标准的 Alembic upgrade。

SQLite

SQLite 是演示和单实例部署的零依赖选项。

DATABASE_URL=sqlite:////data/artifacts/chat.db

.db 文件位于平台的持久化磁盘或卷上。

对比

特性	Postgres	CockroachDB	SQLite
多实例	是	是	否
托管备份	是（配合托管 Postgres）	是（配合托管 CockroachDB）	否
设置要求	数据库预置	空数据库预置	无
最适合	生产环境	分布式 / 多区域	演示、单用户