3.1 · 连接器框架总览（Connector Framework Overview）

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

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

项目要点页2.5 参考项目项目章节目录Onyx DeepWiki 原始章节Connector Framework Overview 上一章3 下一章3.2

源码线索

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.1-connector-framework-overview

连接器框架概述

InputType 和连接器接口

ValidInputTypes 类型定义了决定连接器如何获取和同步数据的入库模式。这些类型直接映射到连接器类必须实现的特定后端接口。

InputType 到代码实体的映射

Onyx · InputType 和连接器接口 · 图 1

来源： backend/onyx/connectors/interfaces.py:43-156, web/src/lib/types.ts:168-172

InputType 描述

InputType	用途	连接器接口	使用场景
`load_state`	一次性批量数据导入	`LoadConnector`	网页抓取、文件上传、静态数据导入 `backend/onyx/connectors/interfaces.py:118-122`
`poll`	增量同步	`PollConnector` 或 `CheckpointedConnector`	针对带有修改时间戳的数据源进行持续同步 `backend/onyx/connectors/interfaces.py:125-130`
`event`	事件驱动的实时更新	无（由工厂处理）	基于 Webhook 的连接器、实时数据流 `backend/onyx/connectors/factory.py:82-84`
`slim_retrieval`	联合搜索或仅 ID 同步	`SlimConnector`	查询时检索或仅元数据索引 `backend/onyx/connectors/interfaces.py:134-142`

前端通过 isLoadState 工具函数识别使用 load_state 模式的连接器：

export function isLoadState(connector_name: string): boolean {
  const loadStateConnectors = ["web", "xenforo", "file", "airtable"];
  if (loadStateConnectors.includes(connector_name)) {
    return true;
  }
  return false;
}

来源： web/src/lib/connectors/connectors.tsx:7-15

连接器工厂模式

连接器工厂根据 DocumentSource 和 InputType 动态加载并实例化连接器类。这使得系统可以扩展到数十个连接器，而不会导致核心应用程序启动时变得臃肿。

工厂执行流程

Onyx · 连接器工厂模式 · 图 2

来源： backend/onyx/connectors/factory.py:34-138

关键工厂函数

identify_connector_class(source, input_type)：获取某个数据源的类引用。它使用 _load_connector_class 来延迟导入模块，并将类缓存到 _connector_cache 中 backend/onyx/connectors/factory.py:92-102。
instantiate_connector(...)：主要入口点。它识别类、实例化该类，并处理凭证加载或提供者注入。它还会为文件持久化连接 raw_file_callback backend/onyx/connectors/factory.py:105-138。
_validate_connector_supports_input_type(...)：确保加载的类实现了 InputType 所需的接口（例如，当请求 POLL 时，检查连接器是否为 PollConnector）backend/onyx/connectors/factory.py:58-90。

ConnectionConfiguration 模式

前端使用声明式模式为每个连接器生成配置界面。这在 web/src/lib/connectors/connectors.tsx 中定义。

配置结构

ConnectionConfiguration 接口定义了连接器设置所需的字段，包括标准和高级设置：

export interface ConnectionConfiguration {
  description: string;
  subtext?: string;
  initialConnectorName?: string;
  values: (BooleanOption | ListOption | TextOption | NumberOption | SelectOption | MultiSelectOption | FileOption | TabOption)[];
  advanced_values: (BooleanOption | ListOption | TextOption | NumberOption | SelectOption | MultiSelectOption | FileOption | TabOption)[];
  overrideDefaultFreq?: number;
}

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

选项类型和数据流

选项类型	接口	用途
`text`	`TextOption`	用于 URL、ID 等的单行或文本区域输入 `web/src/lib/connectors/connectors.tsx:67-72`
`select`	`SelectOption`	带有预定义 `StringWithDescription` 值的下拉菜单 `web/src/lib/connectors/connectors.tsx:49-53`
`checkbox`	`BooleanOption`	布尔切换开关 `web/src/lib/connectors/connectors.tsx:79-82`
`tab`	`TabOption`	复杂的分组配置（例如 GitHub 的"特定仓库"与"全部"） `web/src/lib/connectors/connectors.tsx:94-112`

示例：GitHub 配置

GitHub 连接器配置使用 tab 选项在索引特定仓库或整个组织之间切换：

github: {
  description: "配置 GitHub 连接器",
  values: [
    { type: "text", label: "仓库所有者", name: "repo_owner", optional: false },
    {
      type: "tab",
      name: "github_mode",
      label: "我们应该从 GitHub 索引什么？",
      tabs: [
        { value: "repo", label: "特定仓库", fields: [...] },
        { value: "everything", label: "全部", fields: [...] }
      ]
    },
    // ...
  ]
}

来源： web/src/lib/connectors/connectors.tsx:184-248

凭证管理

凭证与连接器配置分离，以便在多个连接器实例之间重用。

凭证模板

credentialTemplates 对象定义了每个数据源所需凭证的 JSON 结构：

export const credentialTemplates: Record<ValidSources, any> = {
  github: { github_access_token: "" } as GithubCredentialJson,
  zendesk: {
    zendesk_subdomain: "",
    zendesk_email: "",
    zendesk_token: "",
  } as ZendeskCredentialJson,
  // ...
};

来源： web/src/lib/connectors/credentials.ts:284-315

多认证方式数据源

某些数据源（如 SharePoint 或 Google Drive）支持多种认证方式（例如，客户端密钥与证书，或 OAuth 与服务账号）。这通过模板中的 authMethods 来处理：

sharepoint: {
  sp_client_id: "",
  sp_directory_id: "",
  // ...
}

来源： web/src/lib/connectors/credentials.ts:210-216, web/src/lib/connectors/credentials.ts:325-354

数据源元数据

SOURCE_METADATA_MAP 为 UI 提供显示信息、图标和分类。

字段	用途
`icon`	数据源图标的 React 组件 `web/src/lib/sources.ts:56`
`displayName`	用户友好的名称 `web/src/lib/sources.ts:57`
`category`	分组（例如，Wiki、存储、消息） `web/src/lib/sources.ts:58`
`federated`	布尔值，指示数据源是否支持无需索引的实时搜索 `web/src/lib/sources.ts:62`

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

数据流：从 UI 到索引

UI 配置：管理员从 SOURCE_METADATA_MAP 中选择一个数据源 web/src/lib/sources.ts:92。
表单生成：AddConnector 根据 connectorConfigs 渲染字段，并管理凭证链接 web/src/app/admin/connectors/[connector]/AddConnectorPage.tsx:129-182。
持久化：submitConnector 将配置发送到 /api/manage/admin/connector web/src/app/admin/connectors/[connector]/AddConnectorPage.tsx:75-127。
实例化：后台工作进程调用 instantiate_connector() 来加载特定的类（例如 ConfluenceConnector）backend/onyx/connectors/factory.py:105-138。
校验：框架在开始工作前调用 validate_connector_settings()，并可选择性地调用 validate_perm_sync() backend/onyx/connectors/interfaces.py:71-90。
入库：调用连接器的 poll_source() 或 retrieve_all_slim_docs() 方法，生成 Document、SlimDocument 或 HierarchyNode 对象 backend/onyx/connectors/interfaces.py:25-26。

来源： backend/onyx/connectors/factory.py:105-138, backend/onyx/connectors/interfaces.py:71-90, web/src/app/admin/connectors/[connector]/AddConnectorPage.tsx:75-127