3 · 数据源与连接器（Data Sources and Connectors）

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

项目Onyx 章节3 状态全文译文模块界面与交互、文档对象与元数据、系统架构、认证、权限与安全

项目要点页2.5 参考项目项目章节目录Onyx DeepWiki 原始章节Data Sources and Connectors 上一章2.4 下一章3.1

源码线索

backend/ee/onyx/connectors/perm_sync_valid.py
backend/ee/onyx/external_permissions/confluence/constants.py
backend/ee/onyx/external_permissions/confluence/group_sync.py
backend/ee/onyx/external_permissions/confluence/space_access.py
backend/onyx/background/indexing/checkpointing_utils.py
backend/onyx/connectors/confluence/connector.py
backend/onyx/connectors/confluence/onyx_confluence.py
backend/onyx/connectors/confluence/utils.py
backend/onyx/connectors/connector_runner.py
backend/onyx/connectors/factory.py

模块标签

界面与交互
文档对象与元数据
系统架构
认证、权限与安全
测试、发布与运维

中文译文

数据源与连接器（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/onyx-dot-app/onyx/3-data-sources-and-connectors

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

翻译模型：deepseek-chat

原文字符数：14402

项目：Onyx (onyx)

---

数据源与连接器

目的与范围

本页面全面介绍 Onyx 的连接器系统，该系统支持与 60 多种外部数据源集成，包括 Slack、GitHub、Google Drive、Confluence、Jira 等。连接器是 Onyx 从外部平台检索、索引和同步文档的机制。

本页面涵盖高层架构、核心抽象和系统组件。如需了解以下详细信息，请参阅相关章节：

连接器框架内部原理和工厂模式，请参见连接器框架概述
连接器生命周期管理和索引状态，请参见连接器类型与生命周期
凭证存储和认证方法，请参见凭证管理
支持的完整数据源目录，请参见支持的数据源
连接器管理管理界面，请参见连接器管理界面

如需了解执行连接器任务的后台处理机制，请参见后台处理与协调。

系统概述

连接器系统通过三个核心实体的组合来运行：

连接器：定义数据源类型（例如 Slack、GitHub）和配置参数（例如要索引的仓库）web/src/lib/types.ts:219。
凭证：存储访问数据源所需的认证信息（例如 API 令牌、OAuth 令牌）web/src/lib/connectors/credentials.ts:40-46。
连接器-凭证对（CCPair）：将连接器与其凭证关联，形成一个索引单元 web/src/lib/types.ts:217。

连接器从外部源获取文档，这些文档随后会被解析、切分、生成嵌入向量并存储在 Vespa 中，以支持语义搜索。系统支持多种输入模式（加载状态、轮询、事件驱动）和访问控制模式（公开、私有、权限同步）web/src/lib/types.ts:168-183。

来源：

web/src/lib/types.ts:168-183
web/src/lib/connectors/credentials.ts:40-46
web/src/lib/types.ts:217-219

连接器架构

标题：连接器实体与实现映射

graph TB
    subgraph "前端注册表（代码实体空间）"
        ValidSources["ValidSources 枚举<br/>(web/src/lib/types.ts)"]
        SOURCE_METADATA_MAP["SOURCE_METADATA_MAP<br/>(web/src/lib/sources.ts)"]
        connectorConfigs["connectorConfigs<br/>(web/src/lib/connectors/connectors.tsx)"]
        credentialTemplates["credentialTemplates<br/>(web/src/lib/connectors/credentials.ts)"]
    end

    subgraph "后端工厂与注册表"
        identify_connector_class["identify_connector_class()<br/>(onyx/connectors/factory.py)"]
        instantiate_connector["instantiate_connector()<br/>(onyx/connectors/factory.py)"]
        ConfluenceConnector["ConfluenceConnector 类<br/>(onyx/connectors/confluence/connector.py)"]
    end

    subgraph "数据模型"
        Connector_Model["Connector (web/src/lib/types.ts)"]
        Credential_Model["Credential (web/src/lib/connectors/credentials.ts)"]
        CCPair["ConnectorIndexingStatus (web/src/lib/types.ts)"]
    end

    subgraph "核心接口 (onyx/connectors/interfaces.py)"
        LoadConnector["LoadConnector"]
        PollConnector["PollConnector"]
        SlimConnector["SlimConnector"]
        CheckpointedConnector["CheckpointedConnector"]
    end

    ValidSources --> SOURCE_METADATA_MAP
    ValidSources --> connectorConfigs
    ValidSources --> credentialTemplates

    identify_connector_class --> instantiate_connector
    instantiate_connector --> ConfluenceConnector

    ConfluenceConnector -- "实现" --> CheckpointedConnector
    ConfluenceConnector -- "实现" --> SlimConnectorWithPermSync

    Connector_Model --> CCPair
    Credential_Model --> CCPair

连接器架构图

此图展示了连接器定义如何从前端枚举通过后端工厂流向具体的实现，例如 ConfluenceConnector backend/onyx/connectors/confluence/connector.py:120-126。

来源：

web/src/lib/types.ts:466-526
web/src/lib/sources.ts:92-451
web/src/lib/connectors/connectors.tsx:145-148
backend/onyx/connectors/interfaces.py:43-157
backend/onyx/connectors/confluence/connector.py:120-126

连接器注册表与工厂模式

ValidSources 枚举

web/src/lib/types.ts 中的 ValidSources 枚举定义了所有支持的数据源。该枚举作为可用连接器的单一事实来源：

类别	数据源（示例）
维基/知识库	`confluence`、`notion`、`bookstack`、`outline`、`coda`、`slab`、`guru`、`document360`、`discourse`、`gitbook`、`google_sites`、`mediawiki`、`wikipedia`、`axero`
云存储	`google_drive`、`dropbox`、`s3`、`r2`、`google_cloud_storage`、`oci_storage`、`egnyte`
代码仓库	`github`、`gitlab`、`bitbucket`
消息	`slack`、`teams`、`gmail`、`discord`、`zulip`
工单/任务管理	`jira`、`zendesk`、`linear`、`asana`、`clickup`、`productboard`、`airtable`、`freshdesk`、`testrail`

来源：

web/src/lib/types.ts:466-526

工厂模式实现

后端使用 identify_connector_class 和 instantiate_connector 根据 DocumentSource 动态加载连接器。instantiate_connector 函数负责通过 load_credentials 加载凭证或设置凭证提供者 backend/onyx/connectors/interfaces.py:49-51。

标题：连接器初始化逻辑

sequenceDiagram
    participant UI as AddConnectorPage.tsx
    participant Factory as factory.py
    participant Conn as 基础连接器实现
    participant DB as SQLAlchemy 会话

    UI->>Factory: submitConnector(connector_base)
    Factory->>Factory: instantiate_connector(...)
    Factory->>Conn: load_credentials(credential_json)
    Note right of Conn: 连接器特定逻辑<br/>(例如 Confluence 认证)
    Conn-->>Factory: 更新后的凭证（可选）
    Factory->>DB: backend_update_credential_json (如果已更改)
    Factory->>Conn: validate_connector_settings()
    Factory-->>UI: 校验结果

连接器实例化流程

来源：

[web/src/app/admin/connectors/[connector]/AddConnectorPage.tsx:75-127]()
backend/onyx/connectors/interfaces.py:49-51
backend/onyx/connectors/interfaces.py:71-77

输入类型与连接器模式

连接器按照 ValidInputTypes web/src/lib/types.ts:168-172 和 InputType web/src/lib/connectors/connectors.tsx:17-24 定义的模式运行：

输入类型	接口	描述
`load_state`	`LoadConnector`	一次性加载所有文档（例如 `web`、`airtable`、`file`）`web/src/lib/connectors/connectors.tsx:7-15`。
`poll`	`PollConnector`	通过 API 调用定期轮询更新 `backend/onyx/connectors/interfaces.py:125-131`。
`event`	`EventConnector`	通过监听器/Webhook 进行事件驱动更新。
`slim_retrieval`	`SlimConnector`	针对大规模 ID 获取的优化检索 `backend/onyx/connectors/interfaces.py:134-142`。

来源：

backend/onyx/connectors/interfaces.py:118-157
web/src/lib/types.ts:168-172
web/src/lib/connectors/connectors.tsx:7-15

数据模型与关系

核心实体

连接器：表示数据源的配置（例如特定的 GitHub 仓库所有者）web/src/lib/types.ts:3。
凭证：存储认证数据（API 密钥、OAuth 令牌）web/src/lib/connectors/credentials.ts:40-46。
ConnectorIndexingStatus：CCPair 状态的快照，包含 cc_pair_id、last_status 和文档计数 web/src/lib/types.ts:195-202。
IndexAttemptSnapshot：跟踪单次索引运行，记录 new_docs_indexed 和 error_msg web/src/lib/types.ts:204-216。

来源：

web/src/lib/types.ts:195-216
web/src/lib/connectors/credentials.ts:40-46

前端配置系统

ConnectionConfiguration 模式

web/src/lib/connectors/connectors.tsx 中的 ConnectionConfiguration 接口定义了配置表单的动态生成方式。它支持多种字段类型，包括 text、select、checkbox 和 tab web/src/lib/connectors/connectors.tsx:114-143。例如，github 连接器配置使用 tab 在索引特定仓库或"全部"之间切换 web/src/lib/connectors/connectors.tsx:184-229。

源元数据映射

web/src/lib/sources.ts 中的 SOURCE_METADATA_MAP 提供 UI 元数据，包括图标和文档链接。

Slack：归类为 Messaging，支持 OAuth，并具有联邦模式 web/src/lib/sources.ts:78-90。
Confluence：热门数据源，归类为 Wiki，支持 OAuth web/src/lib/sources.ts:94-101。
Google Drive：归类为 Storage，支持 OAuth web/src/lib/sources.ts:189-196。

来源：

web/src/lib/connectors/connectors.tsx:114-248
web/src/lib/sources.ts:78-196

访问控制与特殊类型

访问类型

连接器支持三种访问模式 web/src/lib/types.ts:183：

公开：对组织内所有人可见。
私有：仅限于特定用户或用户组。
同步：权限从数据源同步（例如 SlimConnectorWithPermSync 实现）backend/onyx/connectors/interfaces.py:147-156。

联邦模式与索引模式

索引模式：文档被获取、生成嵌入向量并存储在 Vespa 中，以支持搜索。
联邦模式：结果从源 API 实时获取。此模式延迟较高且搜索质量较低，尤其对于 Slack 而言 web/src/lib/sources.ts:86-88。

来源：

web/src/lib/types.ts:183
backend/onyx/connectors/interfaces.py:147-156
web/src/lib/sources.ts:86-88