10.4 · 类型系统与数据模型（Type System and Data Models）

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

项目Onyx 章节10.4 状态全文译文模块认证、权限与安全、文档对象与元数据、检索、召回与索引、界面与交互

项目要点页2.5 参考项目项目章节目录Onyx DeepWiki 原始章节Type System and Data Models 上一章10.3 下一章11

源码线索

backend/onyx/connectors/factory.py
backend/tests/unit/onyx/server/test_upload_files.py
web/src/app/admin/indexing/status/CCPairIndexingStatusTable.tsx
web/src/app/admin/layout.tsx
web/src/components/admin/connectors/AccessTypeForm.tsx
web/src/components/admin/connectors/AccessTypeGroupSelector.tsx
web/src/components/icons/icons.tsx
web/src/lib/connectors/connectors.tsx
web/src/lib/connectors/credentials.ts
web/src/lib/sources.ts

模块标签

认证、权限与安全
文档对象与元数据
检索、召回与索引
界面与交互
模型调用与提供方适配

章节正文

类型系统与数据模型

原始 DeepWiki 页面https://deepwiki.com/onyx-dot-app/onyx/10.4-type-system-and-data-models

类型系统与数据模型

目的与范围

本文档为 Onyx 前端应用中使用的 TypeScript 类型系统和数据模型提供了全面的参考。它涵盖了表示用户、连接器、文档、聊天会话及其关系的核心类型定义。这些类型作为前端和后端系统之间的契约，确保了整个应用的类型安全性和一致性。

有关数据库模型和后端模式的信息，请参见 8.1 数据库模型与模式。有关连接器实现细节，请参见 3.1 连接器框架概述。有关认证和授权逻辑，请参见 9.1 认证方法。

核心类型定义位置

所有主要的前端类型都集中在 web/src/lib/types.ts 文件中。该文件作为 Next.js 应用中使用的 TypeScript 接口和枚举的单一事实来源。连接器和凭证的支持类型定义位于 web/src/lib/connectors/connectors.tsx 和 web/src/lib/connectors/credentials.ts 中。

来源： web/src/lib/types.ts:1-253, web/src/lib/connectors/connectors.tsx:1-143, web/src/lib/connectors/credentials.ts:1-282

用户与认证类型

用户接口

User 接口表示系统中经过认证的用户，包含全面的偏好设置和个性化数据：

用户模型架构

Onyx · 用户接口 · 图 1

来源： web/src/lib/types.ts:107-131, web/src/lib/types.ts:21-41, web/src/lib/types.ts:48-55, web/src/lib/types.ts:133-141

UserRole 枚举

UserRole 枚举定义了授权层级，包含决定系统访问权限的不同角色：

枚举值	标签	描述
`LIMITED`	受限	访问受限的用户
`BASIC`	基础	无管理能力的标准用户
`ADMIN`	管理员	完全的管理访问权限
`CURATOR`	管理员	可以管理特定群组
`GLOBAL_CURATOR`	全局管理员	可以管理其所属的所有群组
`EXT_PERM_USER`	外部权限用户	基于权限访问的外部用户
`SLACK_USER`	Slack 用户	仅通过 Slack 访问的用户

角色标签和验证消息定义在 USER_ROLE_LABELS 和 INVALID_ROLE_HOVER_TEXT 映射中。

来源： web/src/lib/types.ts:65-73, web/src/lib/types.ts:75-83, web/src/lib/types.ts:99-107

连接器与数据源类型

ValidSources 枚举

ValidSources 枚举列出了所有支持的数据源类型。前端使用此枚举通过 SOURCE_METADATA_MAP 驱动图标选择和元数据查找。

来源： web/src/lib/types.ts:252-253, web/src/lib/sources.ts:92-451

连接器类型层级

连接器实体关系

Onyx · 连接器类型层级 · 图 2

来源： web/src/lib/types.ts:204-216, web/src/lib/types.ts:15-19, web/src/lib/connectors/connectors.tsx:32-34

连接器配置类型

ConnectionConfiguration 接口定义了连接器设置表单的结构，允许 UI 根据源需求动态生成字段。

export interface ConnectionConfiguration {
  description: string;
  subtext?: string;
  initialConnectorName?: string;
  values: (BooleanOption | ListOption | TextOption | NumberOption |
           SelectOption | MultiSelectOption | FileOption | TabOption)[];
  advanced_values: (/* 相同选项类型 */)[];
  overrideDefaultFreq?: number;
  advancedValuesVisibleCondition?: (values: any, currentCredential: Credential<any> | null) => boolean;
}

来源： web/src/lib/connectors/connectors.tsx:114-143

凭证类型

通用凭证结构

凭证系统使用通用类型模式来处理多样化的认证载荷（令牌、密钥、证书），同时保持一致的元数据包装器。

凭证模型层级

Onyx · 通用凭证结构 · 图 3

来源： web/src/lib/connectors/credentials.ts:27-46, web/src/lib/connectors/credentials.ts:47-49, web/src/lib/connectors/credentials.ts:210-216

索引与生命周期类型

IndexAttemptSnapshot

表示单次索引尝试，包含全面的状态跟踪和指标：

字段	类型	描述
`id`	`number`	尝试的唯一标识符
`status`	`ValidStatuses \| null`	当前生命周期状态（例如 `success`、`failed`）
`from_beginning`	`boolean`	完全重新索引与增量更新
`new_docs_indexed`	`number`	此尝试期间添加的文档数
`docs_removed_from_index`	`number`	移除的文档数
`total_docs_indexed`	`number`	此 CCPair 索引中的总文档数
`error_msg`	`string \| null`	如果尝试失败，错误消息
`time_started`	`string \| null`	开始的 ISO 时间戳

来源： web/src/lib/types.ts:204-216

索引阶段

索引过程被分解为细粒度的阶段，由 INDEX_ATTEMPT_STAGES 常量跟踪。这包括 CONNECTOR_FETCH、CHUNKING、EMBEDDING 和 VECTOR_DB_WRITE。

来源： web/src/lib/types.ts:222-242

前端到后端类型映射

前端的 TypeScript 类型镜像了后端的 SQLAlchemy 模型和 Pydantic 模式。系统在 submitConnector 函数中使用标准的 fetch 模式与 FastAPI 端点通信。

自然语言到代码实体空间

Onyx · 前端到后端类型映射 · 图 4

来源： web/src/lib/types.ts:107-131, web/src/app/admin/connectors/[connector]/AddConnectorPage.tsx:75-127, backend/onyx/connectors/factory.py:105-138, web/src/lib/types.ts:204-216

源元数据系统

源元数据系统将 ValidSources 枚举桥接到 UI 显示属性，包括图标和文档链接。

interface PartialSourceMetadata {
  icon: React.FC<{ size?: number; className?: string }>;
  displayName: string;
  category: SourceCategory;
  isPopular?: boolean;
  docs?: string;
  oauthSupported?: boolean;
  federated?: boolean;
  alwaysConnected?: boolean;
}

SOURCE_METADATA_MAP 将每个 ValidSources 值映射到其元数据。例如，Slack 的元数据包括图标、显示名称和类别。

来源： web/src/lib/sources.ts:55-72, web/src/lib/sources.ts:78-90, web/src/lib/sources.ts:92-451

图标与视觉表示

图标通过 web/src/components/icons/icons.tsx 中的集中注册表进行管理。系统支持基于 SVG 的图标和基于图像的第三方集成徽标。

图标处理流程

Onyx · 图标与视觉表示 · 图 5

来源： web/src/components/icons/icons.tsx:41-55, web/src/components/icons/icons.tsx:76-131, web/src/lib/sources.ts:92-451