agentic_huge_data_base / wiki
页面 Onyx · 8.1 数据库模型与模式定义·DeepWiki 中文全文译文
DeepWiki 中文译文 / Onyx / 8.1

8.1 · 数据库模型与模式定义（Database Models and Schema）

企业连接器与统一搜索 · 聚焦本章的模块关系、源码依据与实现要点。

项目Onyx 章节8.1 状态全文译文 模块文档对象与元数据、认证、权限与安全、图谱与关系、测试、发布与运维
项目要点页2.5 参考项目 项目章节目录Onyx DeepWiki 原始章节Database Models and Schema 上一章8 下一章8.2
源码线索
  • backend/alembic.ini
  • backend/alembic/env.py
  • backend/alembic/versions/351faebd379d_add_curator_fields.py
  • backend/alembic/versions/57b53544726e_add_document_set_tables.py
  • backend/alembic/versions/6d387b3196c2_basic_auth.py
  • backend/alembic/versions/74379b447d4c_add_paste_as_tile_to_user.py
  • backend/alembic/versions/800f48024ae9_add_id_to_connectorcredentialpair.py
  • backend/alembic/versions/da4c21c69164_chosen_assistants_changed_to_jsonb.py
  • backend/alembic_tenants/README.md
  • backend/alembic_tenants/env.py
模块标签
  • 文档对象与元数据
  • 认证、权限与安全
  • 图谱与关系
  • 测试、发布与运维
  • 接口与服务契约

章节正文

数据库模型与模式定义

原始 DeepWiki 页面https://deepwiki.com/onyx-dot-app/onyx/8.1-database-models-and-schema

数据库模型与模式

相关源文件

本章引用的主要源码文件：

  • backend/alembic.ini
  • backend/alembic/env.py
  • backend/alembic/versions/351faebd379d_add_curator_fields.py
  • backend/alembic/versions/57b53544726e_add_document_set_tables.py
  • backend/alembic/versions/6d387b3196c2_basic_auth.py
  • backend/alembic/versions/74379b447d4c_add_paste_as_tile_to_user.py
  • backend/alembic/versions/800f48024ae9_add_id_to_connectorcredentialpair.py
  • backend/alembic/versions/da4c21c69164_chosen_assistants_changed_to_jsonb.py
  • backend/alembic_tenants/README.md
  • backend/alembic_tenants/env.py
  • backend/alembic_tenants/script.py.mako
  • backend/alembic_tenants/versions/14a83a331951_create_usertenantmapping_table.py
  • backend/onyx/auth/schemas.py
  • backend/onyx/auth/users.py
  • backend/onyx/db/enums.py
  • backend/onyx/db/models.py
  • backend/onyx/db/user_preferences.py
  • backend/onyx/server/manage/get_state.py
  • backend/onyx/server/manage/models.py
  • backend/onyx/server/manage/users.py
  • backend/tests/api/test_api.py
  • backend/tests/unit/onyx/auth/test_single_tenant_jwt_strategy.py
  • deployment/aws_ecs_fargate/cloudformation/services/onyx_nginx_service_template.yaml
  • deployment/aws_ecs_fargate/cloudformation/services/onyx_web_server_service_template.yaml
  • web/src/hooks/useTokenRefresh.test.tsx
  • web/src/hooks/useTokenRefresh.ts
  • web/src/providers/UserProvider.tsx

本文档描述了 Onyx 使用的 PostgreSQL 数据库模式以及 SQLAlchemy ORM 模型。这些模型定义在 backend/onyx/db/models.py 中。关于数据库操作和查询的信息，请参见第 8.2 节。关于使用 Redis 进行后台任务协调的信息，请参见第 7.2 节。

概述

Onyx 使用 PostgreSQL 作为关系型数据库，并采用 SQLAlchemy ORM 进行对象关系映射。数据库存储了用户、连接器、文档、聊天历史、索引状态以及知识图谱数据。在多租户部署中，每个租户拥有独立的 PostgreSQL 模式（例如 tenant_abc123），而共享的 public 模式则包含 UserTenantMapping 表 backend/onyx/auth/users.py:153-157。

来源： backend/onyx/db/models.py:1-100，backend/onyx/auth/users.py:149-157

数据库基础设施

基础声明式类

所有模型都继承自一个公共的 Base 类，该类扩展了 SQLAlchemy 的 DeclarativeBase backend/onyx/db/models.py:118-120：

class Base(DeclarativeBase):
    __abstract__ = True

这为所有 ORM 模型提供了基础，使用 SQLAlchemy 2.0 的声明式语法，配合 Mapped 类型注解和 mapped_column backend/onyx/db/models.py:38-39。

来源： backend/onyx/db/models.py:118-120，backend/onyx/db/models.py:38-39

自定义类型装饰器

Onyx 定义了自定义的 SQLAlchemy 类型装饰器，用于实现特殊的列行为，包括对敏感数据的静态加密 backend/onyx/db/models.py:122-127。

类型装饰器存储类型用途
EncryptedStringLargeBinary使用 encrypt_string_to_bytes / decrypt_bytes_to_string 对字符串值进行静态加密 backend/onyx/db/models.py:164-201
EncryptedJsonLargeBinary将 JSON 字典序列化为 JSON 字符串后进行加密，实现静态加密 backend/onyx/db/models.py:202-233
NullFilteredStringString过滤掉 PostgreSQL 文本字段中无效的 NUL 字符（\x00） backend/onyx/db/models.py:234-245

来源： backend/onyx/db/models.py:122-245

表分类

下图将自然语言概念与 PostgreSQL 模式中的具体代码实体进行了关联。

Onyx · 表分类 · 图 1
Onyx · 表分类 · 图 1

来源： backend/onyx/db/models.py:247-3000

认证与用户模型

用户模型

User 表扩展了 SQLAlchemyBaseUserTableUUID，同时处理认证和丰富的用户偏好设置 backend/onyx/db/models.py:247。

Onyx · 用户模型 · 图 2
Onyx · 用户模型 · 图 2

关键字段：

  • role：枚举类型，包括 BASIC、ADMIN、CURATOR、GLOBAL_CURATOR、LIMITED、SLACK_USER、EXT_PERM_USER backend/onyx/auth/schemas.py:11-32。
  • account_type：枚举类型，包括 STANDARD、BOT、EXT_PERM_USER、SERVICE_ACCOUNT、ANONYMOUS backend/onyx/db/enums.py:7-20。
  • personal_name / personal_role：用于系统提示中的个性化设置 backend/onyx/db/models.py:270-271。
  • paste_as_tile：偏好设置，用于控制粘贴内容在聊天中的渲染方式 backend/onyx/db/models.py:284。

来源： backend/onyx/db/models.py:247-300，backend/onyx/auth/schemas.py:11-32，backend/onyx/db/enums.py:7-20

连接器与凭证模型

连接器模型

Connector 表定义了数据源配置 backend/onyx/db/models.py:1600。

字段类型描述
idInteger主键
sourceDocumentSource枚举类型，如 GOOGLE_DRIVE、SLACK、CONFLUENCE backend/onyx/configs/constants.py:50
input_typeInputTypeLOAD_STATE（有状态）或 POLL（无状态） backend/onyx/connectors/models.py:58
connector_specific_configJSONB特定于源的配置（API 端点、过滤器等）
refresh_freqInteger重新索引之间的秒数
prune_freqInteger清理已删除文档之间的秒数

来源： backend/onyx/db/models.py:1600-1650

连接器凭证对模型

ConnectorCredentialPair（CCPair）是索引的原子单元，表示一个连接器与特定凭证的关联 backend/onyx/db/models.py:445。

Onyx · 连接器凭证对模型 · 图 3
Onyx · 连接器凭证对模型 · 图 3

关键字段：

  • status：控制索引生命周期（ACTIVE、PAUSED、DELETING 等） backend/onyx/db/enums.py:180-187。
  • access_type：PUBLIC、PRIVATE（由用户组控制）或 SYNC（外部权限） backend/onyx/db/enums.py:207-211。
  • last_successful_index_time：用于计算增量轮询范围 backend/onyx/db/models.py:488。

来源： backend/onyx/db/models.py:445-545，backend/onyx/db/enums.py:180-211

文档与文件模型

文档模型

Document 表存储已索引文档的元数据 backend/onyx/db/models.py:547。请注意，实际的文本片段存储在向量提供程序（Vespa/OpenSearch）中。

字段类型描述
idString唯一 ID（通常是源前缀的 URL/路径）
semantic_idString人类可读的标题或 ID
linkString指向源文档的直接链接
doc_updated_atDateTime源系统中的最后修改时间
boostInteger排名提升因子（默认值为 0）
is_publicBoolean全局可见性标志

来源： backend/onyx/db/models.py:547-641

用户文件与项目模型

这些模型处理用于聊天上下文和"项目"功能的直接文件上传。

  • UserFile：表示一个已上传的文件，包含其存储路径（file_id）和索引状态（PROCESSING、COMPLETED、FAILED） backend/onyx/db/models.py:2800-2850。
  • UserProject：用于对 UserFile 对象进行分组的容器 backend/onyx/db/models.py:2900-2950。
  • Project__UserFile：将文件与项目关联的关联表 backend/onyx/db/models.py:2955-2965。

来源： backend/onyx/db/models.py:2800-3000，backend/onyx/db/enums.py:221-229

聊天与会话模型

ChatSession 和 ChatMessage

聊天会话维护对话上下文。消息通过 parent_message 组织成树状结构，以支持分支 backend/onyx/db/models.py:2145。

Onyx · ChatSession 和 ChatMessage · 图 4
Onyx · ChatSession 和 ChatMessage · 图 4

关键逻辑：

  • parent_message：链接到前一条消息。如果为 NULL，则表示会话根节点 backend/onyx/db/models.py:2145。
  • latest_child_message：跟踪用于重新生成/编辑的活动分支 backend/onyx/db/models.py:2149。
  • citations：引用索引到文档标识符的映射 backend/onyx/db/models.py:2163。

来源： backend/onyx/db/models.py:2000-2300，backend/onyx/db/enums.py:175-178

关联表

Onyx 使用多个关联表来管理多对多关系，用于访问控制和配置。

关联表用途
Persona__DocumentSet将助手与知识集关联 backend/onyx/db/models.py:302-311
Persona__User显式授予用户对私有助手的访问权限 backend/onyx/db/models.py:314-323
User__UserGroup权限组中的成员关系 backend/onyx/db/models.py:392-401
DocumentSet__CCPair填充文档集的连接器 backend/onyx/db/models.py:339-353
ChatMessage__SearchDoc特定聊天轮次的检索结果 backend/onyx/db/models.py:2385-2394

来源： backend/onyx/db/models.py:300-450

知识图谱模型

知识图谱（KG）系统存储提取的实体及其关系。

  • KGEntityType：实体类型的模式（例如"人员"、"项目"） backend/onyx/db/models.py:643-708。
  • KGEntity：具体的提取实例 backend/onyx/db/models.py:853-939。
  • KGRelationshipType：实体之间关系的模式（例如"工作于"） backend/onyx/db/models.py:710-779。
  • KGRelationship：包含 confidence_score 和 grounding_content 的关系实例 backend/onyx/db/models.py:1031-1150。

来源： backend/onyx/db/models.py:643-1150

页面来源：

  • backend/onyx/db/models.py:1-3000
  • backend/onyx/db/enums.py:1-260
  • backend/onyx/auth/schemas.py:1-80
  • backend/onyx/auth/users.py:1-160
  • backend/onyx/db/user_preferences.py:1-225
  • backend/onyx/server/manage/models.py:1-200