agentic_huge_data_base / wiki
页面 Onyx · 3 数据源与连接器·DeepWiki 中文全文译文
DeepWiki 中文译文 / Onyx / 3

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

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

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

数据源与连接器

相关源文件

以下文件为本维基页面的生成提供了上下文：

  • 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
  • backend/onyx/connectors/interfaces.py
  • backend/onyx/connectors/mock_connector/connector.py
  • backend/onyx/connectors/zendesk/connector.py
  • backend/tests/daily/connectors/google_drive/test_resolver.py
  • backend/tests/daily/connectors/zendesk/test_zendesk_connector.py
  • backend/tests/daily/connectors/zendesk/test_zendesk_data.json
  • backend/tests/unit/ee/onyx/external_permissions/confluence/test_space_access.py
  • backend/tests/unit/onyx/connectors/confluence/test_confluence_checkpointing.py
  • backend/tests/unit/onyx/connectors/confluence/test_onyx_confluence.py
  • backend/tests/unit/onyx/connectors/utils.py
  • backend/tests/unit/onyx/connectors/zendesk/test_zendesk_checkpointing.py
  • backend/tests/unit/onyx/connectors/zendesk/test_zendesk_rate_limit.py
  • backend/tests/unit/onyx/server/test_upload_files.py
  • [web/src/app/admin/connectors/[connector]/AddConnectorPage.tsx](web/src/app/admin/connectors/[connector]/AddConnectorPage.tsx)
  • [web/src/app/admin/connectors/[connector]/pages/Advanced.tsx](web/src/app/admin/connectors/[connector]/pages/Advanced.tsx)
  • [web/src/app/admin/connectors/[connector]/pages/ConnectorInput/FileInput.tsx](web/src/app/admin/connectors/[connector]/pages/ConnectorInput/FileInput.tsx)
  • [web/src/app/admin/connectors/[connector]/pages/DynamicConnectorCreationForm.tsx](web/src/app/admin/connectors/[connector]/pages/DynamicConnectorCreationForm.tsx)
  • [web/src/app/admin/connectors/[connector]/pages/utils/google_site.ts](web/src/app/admin/connectors/[connector]/pages/utils/google_site.ts)
  • 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
  • web/src/lib/types.ts

目的与范围

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

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

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

系统概述

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

  1. 连接器：定义数据源类型（例如 Slack、GitHub）和配置参数（例如要索引的仓库）web/src/lib/types.ts:219。
  2. 凭证：存储访问数据源所需的认证信息（例如 API 令牌、OAuth 令牌）web/src/lib/connectors/credentials.ts:40-46。
  3. 连接器-凭证对（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

连接器架构

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

Onyx · 连接器架构 · 图 1
Onyx · 连接器架构 · 图 1

连接器架构图

此图展示了连接器定义如何从前端枚举通过后端工厂流向具体的实现，例如 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。

标题：连接器初始化逻辑

Onyx · 工厂模式实现 · 图 2
Onyx · 工厂模式实现 · 图 2

连接器实例化流程

来源： 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_stateLoadConnector一次性加载所有文档（例如 web、airtable、file）web/src/lib/connectors/connectors.tsx:7-15。
pollPollConnector通过 API 调用定期轮询更新 backend/onyx/connectors/interfaces.py:125-131。
eventEventConnector通过监听器/Webhook 进行事件驱动更新。
slim_retrievalSlimConnector针对大规模 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：

  1. 公开：对组织内所有人可见。
  2. 私有：仅限于特定用户或用户组。
  3. 同步：权限从数据源同步（例如 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