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

企业连接器与统一搜索 · 本章是 Onyx DeepWiki 中文译文的独立章节页，保留原始链接、源码锚点、模块标签和章节层级。

项目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

翻译时间：2026-05-27T08:44:51.123Z

翻译模型：deepseek-chat

原文字符数：13013

项目：Onyx (onyx)

---

类型系统与数据模型

目的与范围

本文档为 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 接口表示系统中经过认证的用户，包含全面的偏好设置和个性化数据：

用户模型架构

classDiagram
    class User {
        +string id
        +string email
        +boolean is_active
        +boolean is_superuser
        +boolean is_verified
        +UserRole role
        +UserPreferences preferences
        +Date current_token_created_at
        +number current_token_expiry_length
        +Date oidc_expiry
        +boolean is_cloud_superuser
        +string|null team_name
        +boolean is_anonymous_user
        +boolean password_configured
        +TenantInfo|null tenant_info
        +UserPersonalization personalization
    }

    class UserPreferences {
        +number[]|null chosen_assistants
        +number[] visible_assistants
        +number[] hidden_assistants
        +number[] pinned_assistants
        +string|null default_model
        +number[] recent_assistants
        +boolean auto_scroll
        +boolean shortcut_enabled
        +boolean temperature_override_enabled
        +ThemePreference|null theme_preference
        +string|null chat_background
        +string default_app_mode
    }

    class UserPersonalization {
        +string name
        +string role
        +MemoryItem[] memories
        +boolean use_memories
        +boolean enable_memory_tool
        +string user_preferences
    }

    class TenantInfo {
        +NewTenantInfo|null new_tenant
        +NewTenantInfo|null invitation
    }

    User --> UserPreferences
    User --> UserPersonalization
    User --> TenantInfo

来源： 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

连接器类型层级

连接器实体关系

graph TB
    Connector["Connector&lt;T&gt;"]
    Credential["Credential&lt;T&gt;"]
    ConnectorIndexingStatus["ConnectorIndexingStatusLite"]
    IndexAttemptSnapshot["IndexAttemptSnapshot"]

    ConnectorIndexingStatus --> Connector
    ConnectorIndexingStatus --> Credential
    IndexAttemptSnapshot --> ConnectorIndexingStatus

来源： 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

---

凭证类型

通用凭证结构

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

凭证模型层级

classDiagram
    class CredentialBase~T~ {
        +T credential_json
        +boolean admin_public
        +ValidSources source
        +string name
        +boolean curator_public
        +number[] groups
    }

    class Credential~T~ {
        +number id
        +string|null user_id
        +string|null user_email
        +string time_created
        +string time_updated
    }

    class GithubCredentialJson {
        +string github_access_token
    }

    class SharepointCredentialJson {
        +string sp_client_id
        +string sp_client_secret
        +string sp_directory_id
        +string sp_certificate_password
        +TypedFile sp_private_key
    }

    CredentialBase~T~ <|-- Credential~T~
    Credential~GithubCredentialJson~ ..> GithubCredentialJson
    Credential~SharepointCredentialJson~ ..> SharepointCredentialJson

来源： 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 端点通信。

自然语言到代码实体空间

graph LR
    subgraph "自然语言概念"
        UserConcept["用户身份"]
        ConnectorConcept["数据集成"]
        CredentialConcept["认证密钥"]
        StatusConcept["索引健康状态"]
    end

    subgraph "代码实体空间（后端/前端）"
        FE_User["User (web/src/lib/types.ts)"]
        BE_Me["/api/me (FastAPI 路由)"]
        FE_Connector["Connector (web/src/lib/connectors/connectors.tsx)"]
        BE_ConnectorURL["/api/manage/admin/connector (backend/onyx/server/manage/connector.py)"]
        FE_Credential["Credential (web/src/lib/connectors/credentials.ts)"]
        BE_CredURL["/api/manage/credential (backend/onyx/server/manage/credential.py)"]
        FE_Status["IndexAttemptSnapshot (web/src/lib/types.ts)"]
        BE_Instantiate["instantiate_connector (backend/onyx/connectors/factory.py)"]
    end

    UserConcept --> FE_User
    UserConcept --> BE_Me
    ConnectorConcept --> FE_Connector
    ConnectorConcept --> BE_ConnectorURL
    CredentialConcept --> FE_Credential
    CredentialConcept --> BE_CredURL
    StatusConcept --> FE_Status
    BE_Instantiate --> BE_ConnectorURL

来源： 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 的图标和基于图像的第三方集成徽标。

图标处理流程

graph TD
    Source["SOURCE_METADATA_MAP (web/src/lib/sources.ts)"] --> Metadata["PartialSourceMetadata.icon"]
    Metadata --> SourceIconComp["SourceIcon 组件 (web/src/components/SourceIcon.tsx)"]

    subgraph "图标生成器"
        CreateIcon["createIcon() (web/src/components/icons/icons.tsx)"]
        CreateLogoIcon["createLogoIcon() (web/src/components/icons/icons.tsx)"]
    end

    CreateIcon --> Metadata
    CreateLogoIcon --> Metadata

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