3.2 · 连接器类型与生命周期（Connector Types and Lifecycle）

连接器类型与生命周期

连接器类型与生命周期

相关源文件

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

• backend/alembic/versions/14162713706c_add_index_attempt_stage_metric_table.py
• backend/alembic/versions/1c36b3dc2f4e_add_full_exception_trace_to_permission_.py
• backend/ee/onyx/background/celery/tasks/doc_permission_syncing/tasks.py
• backend/ee/onyx/background/celery/tasks/external_group_syncing/tasks.py
• backend/onyx/background/celery/tasks/connector_deletion/tasks.py
• backend/onyx/background/celery/tasks/docprocessing/tasks.py
• backend/onyx/background/celery/tasks/pruning/tasks.py
• backend/onyx/background/indexing/run_docfetching.py
• backend/onyx/db/connector_credential_pair.py
• backend/onyx/db/file_record.py
• backend/onyx/db/index_attempt.py
• backend/onyx/db/index_attempt_metrics.py
• backend/onyx/db/index_attempt_metrics_models.py
• backend/onyx/db/indexing_coordination.py
• backend/onyx/db/permission_sync_attempt.py
• backend/onyx/file_store/staging.py
• backend/onyx/server/documents/cc_pair.py
• backend/onyx/server/documents/connector.py
• backend/onyx/server/documents/models.py
• backend/onyx/utils/postgres_sanitization.py
• backend/tests/external_dependency_unit/celery/test_docprocessing_priority.py
• backend/tests/external_dependency_unit/db/test_index_attempt_stage_metrics.py
• backend/tests/external_dependency_unit/db/test_targeted_reindex_filter.py
• backend/tests/external_dependency_unit/file_store/test_staging_concurrent_attempt_skip.py
• backend/tests/external_dependency_unit/indexing/__init__.py
• backend/tests/external_dependency_unit/indexing/test_docfetching_orphan_cleanup.py
• backend/tests/external_dependency_unit/indexing/test_document_deletion_file_cleanup.py
• backend/tests/external_dependency_unit/indexing/test_index_doc_batch_prepare.py
• backend/tests/external_dependency_unit/indexing_helpers.py
• backend/tests/external_dependency_unit/permission_sync/test_doc_permission_sync_attempt.py
• backend/tests/external_dependency_unit/permission_sync/test_external_group_permission_sync_attempt.py
• backend/tests/external_dependency_unit/search_settings/test_index_swap_workflow.py
• backend/tests/unit/onyx/db/test_tools.py
• [web/src/app/admin/connector/[ccPairId]/ConfigDisplay.tsx](web/src/app/admin/connector/[ccPairId]/ConfigDisplay.tsx)
• [web/src/app/admin/connector/[ccPairId]/DocPermissionSyncAttemptsTable.tsx](web/src/app/admin/connector/[ccPairId]/DocPermissionSyncAttemptsTable.tsx)
• [web/src/app/admin/connector/[ccPairId]/ExternalGroupSyncAttemptsTable.tsx](web/src/app/admin/connector/[ccPairId]/ExternalGroupSyncAttemptsTable.tsx)
• [web/src/app/admin/connector/[ccPairId]/page.tsx](web/src/app/admin/connector/[ccPairId]/page.tsx)
• [web/src/app/admin/connector/[ccPairId]/types.ts](web/src/app/admin/connector/[ccPairId]/types.ts)
• web/src/app/admin/indexing/status/page.tsx
• web/src/components/modals/EditPropertyModal.tsx

目的与范围

本文档介绍了 Onyx 中通过 ValidSources 枚举对数据源进行的分类、连接器-凭证对（CCPair）的生命周期，以及管理其入库、修剪和权限同步的专用后台任务。同时，本文还详细说明了联邦连接器（精简检索）与已入库连接器之间的区别。

有关连接器框架的结构化实现，请参阅连接器框架总览。有关认证的详细信息，请参阅凭证管理。

数据源枚举

Onyx 使用集中式枚举来标识和分类外部数据源。该枚举驱动着 UI 图标、连接器工厂逻辑以及数据库过滤。

ValidSources 枚举

ValidSources 类型（以及后端中对应的 DocumentSource）定义了所有受支持的集成。

代码定义： ValidSources 位于 web/src/lib/types.ts:36-121，DocumentSource 位于 backend/onyx/configs/constants.py:42-108。

常见数据源：

• 生产力工具： GoogleDrive、Gmail、MicrosoftTeams、Sharepoint、Confluence、Notion。
• 通讯工具： Slack、Discord、Zulip。
• 开发工具： GitHub、GitLab、Jira、AzureDevOps。
• 存储/数据： S3、GoogleCloudStorage、Airtable、Salesforce。

联邦连接器与已入库连接器

Onyx 区分了两种数据源：一种是入库到本地向量存储中的数据源，另一种是实时查询的数据源。

1. 已入库连接器： 这是标准模式。文档会被获取、切分、生成嵌入向量并存储到 Vespa 中。这种方式可以对所有已连接的知识库进行高性能的混合搜索。
2. 联邦连接器（精简检索）： 文档不会存储在本地。相反，Onyx 会在搜索时将用户的查询转发到外部数据源的 API。

• 示例： FederatedSlack 用于实时消息检索，无需对整个工作空间建立索引 web/src/app/admin/indexing/status/CCPairIndexingStatusTable.tsx:57-61。
• UI 表示： 联邦连接器会显示一个"联邦"徽章，并链接到专门的管理页面 web/src/app/admin/documents/sets/page.tsx:46-68。

来源： web/src/lib/types.ts:36-121 backend/onyx/configs/constants.py:42-108 web/src/app/admin/indexing/status/CCPairIndexingStatusTable.tsx:57-61 web/src/app/admin/documents/sets/page.tsx:46-68

连接器-凭证对（CCPair）生命周期

CCPair 是 Onyx 中数据入库的基本单元。它将一个特定的 Connector 配置（例如，一个特定的 SharePoint 站点）与一个 Credential（例如，一个 OAuth 令牌或服务账号）绑定在一起。

生命周期状态机

CCPair 的状态通过 ConnectorCredentialPairStatus 枚举进行跟踪 backend/onyx/db/enums.py:23-26。

关键状态：

• ACTIVE（活跃）： 该配对有资格进行后台入库、修剪和权限同步。
• PAUSED（已暂停）： 该配对的后台任务被挂起 backend/onyx/db/enums.py:23-26。
• DELETING（删除中）： 系统正在从 Vespa 和 Postgres 中主动移除文档。该配对无法恢复 backend/onyx/db/enums.py:23-26。

来源： backend/onyx/db/enums.py:23-26 backend/onyx/db/models.py:116-121 backend/onyx/db/connector_credential_pair.py:23-26

后台任务编排

生命周期由一系列 Celery 任务管理，这些任务通过 Redis "栅栏"进行协调，以防止对同一个 CCPair 执行重叠的操作。

入库生命周期

入库是使 Onyx 知识库与外部数据源保持同步的过程。

任务流程图

实现细节：

• 入库尝试： 每次入库运行都会创建一个 IndexAttempt 记录，用于跟踪成功、失败和文档数量 backend/onyx/db/index_attempt.py:140-157。
• 运行器逻辑： _get_connector_runner 通过 instantiate_connector 实例化连接器类，并在获取文档前校验设置 backend/onyx/background/indexing/run_docfetching.py:95-130。
• 状态监控： UI 使用 CCPairStatus 显示状态，该状态将数据库状态映射为 INITIAL_INDEXING 或 SCHEDULED 等视觉指示器 web/src/app/admin/indexing/status/CCPairIndexingStatusTable.tsx:175-185。

来源： backend/onyx/background/celery/tasks/docprocessing/tasks.py:103-115 backend/onyx/background/indexing/run_docfetching.py:95-157 backend/onyx/db/index_attempt.py:140-157 web/src/app/admin/indexing/status/CCPairIndexingStatusTable.tsx:175-185

修剪生命周期

修剪用于识别 Onyx 中已从外部数据源删除的文档。

• 触发条件： 根据上次成功修剪或入库的时间差计算得出 backend/onyx/background/celery/tasks/pruning/tasks.py:164-170。
• 机制： connector_pruning_generator_task 任务调用连接器的逻辑，将当前数据源 ID 与数据库中的 ID 进行比较 backend/onyx/background/celery/tasks/pruning/tasks.py:1-85。
• 安全性： 修剪使用 Redis 栅栏（OnyxRedisLocks.PRUNING_LOCK）来确保在活跃入库期间不会运行 backend/onyx/background/celery/tasks/pruning/tasks.py:30-38。

来源： backend/onyx/background/celery/tasks/pruning/tasks.py:1-170 backend/onyx/configs/constants.py:30-32

权限同步生命周期

对于支持外部权限的连接器（例如 Google Drive、SharePoint、Slack），Onyx 会定期同步访问控制列表（ACL）。

• 逻辑： 如果同步周期已过，则由 check_for_doc_permissions_sync 触发 backend/ee/onyx/background/celery/tasks/doc_permission_syncing/tasks.py:139-164。
• 组同步： 一个单独的任务 check_for_external_group_sync 负责将外部用户组同步到本地的 ExternalUserGroup 模型 backend/ee/onyx/background/celery/tasks/external_group_syncing/tasks.py:111-155。
• API： 同步尝试可以通过 /manage/admin/cc-pair/{cc_pair_id}/sync-attempts 查看，该端点返回 CCPairSyncAttemptsResponse backend/onyx/server/documents/cc_pair.py:119-153。

来源： backend/ee/onyx/background/celery/tasks/doc_permission_syncing/tasks.py:139-164 backend/ee/onyx/background/celery/tasks/external_group_syncing/tasks.py:111-155 backend/onyx/server/documents/cc_pair.py:119-153

删除与清理

当删除一个 CCPair 时，系统会先进入"软删除"状态，然后通过 check_for_connector_deletion_task 进行永久移除。

1. 状态变更： 状态被设置为 DELETING backend/onyx/db/enums.py:23-26。
2. 任务撤销： 使用 revoke_tasks_blocking_deletion 撤销该配对正在进行的入库、修剪或权限同步任务 backend/onyx/background/celery/tasks/connector_deletion/tasks.py:79-130。
3. 擦除过程：

• 通过 delete_all_documents_by_connector_credential_pair__no_commit 从 Postgres 和 Vespa 中移除文档 backend/onyx/background/celery/tasks/connector_deletion/tasks.py:34-36。
• 清理孤立的标签和层级节点 backend/onyx/background/celery/tasks/connector_deletion/tasks.py:53-56。

1. 最终移除： 通过 delete_connector_credential_pair__no_commit 从数据库中删除 ConnectorCredentialPair 行 backend/onyx/background/celery/tasks/connector_deletion/tasks.py:29-31。

来源：

• backend/onyx/background/celery/tasks/connector_deletion/tasks.py:29-130
• backend/onyx/db/enums.py:23-26
• backend/onyx/server/documents/connector.py:58-60