3.5 · 连接器 Administration UI（Connector Administration UI）

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

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

项目要点页2.5 参考项目项目章节目录Onyx DeepWiki 原始章节Connector Administration UI 上一章3.4 下一章4

源码线索

backend/onyx/connectors/factory.py
backend/tests/unit/onyx/server/test_upload_files.py
web/src/app/admin/bots/page.tsx
web/src/app/admin/discord-bot/page.tsx
web/src/app/admin/documents/sets/hooks.tsx
web/src/app/admin/documents/sets/new/page.tsx
web/src/app/admin/documents/sets/page.tsx
web/src/app/admin/indexing/status/CCPairIndexingStatusTable.tsx
web/src/app/admin/layout.tsx
web/src/app/admin/token-rate-limits/page.tsx

模块标签

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

中文译文

连接器 Administration UI（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/onyx-dot-app/onyx/3.5-connector-administration-ui

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

翻译模型：deepseek-chat

原文字符数：12676

项目：Onyx (onyx)

---

连接器管理界面

目的与范围

本文档描述了用于在 Onyx 中创建、配置和管理数据源连接器的管理用户界面。内容涵盖动态表单生成系统（该系统会适配每种连接器类型）、凭证关联机制，以及连接器-凭证对（CCPair）的监控界面。有关后端连接器实现的详细信息，请参阅连接器框架概述。有关凭证存储的详细信息，请参阅凭证管理。

---

界面架构总览

连接器管理界面构建在一个动态配置系统之上，该系统根据声明式模式生成表单。整个系统由三个主要层级组成：源元数据（图标、类别、文档）、配置模式（表单字段）和凭证模板（认证要求）。

标题：连接器管理界面架构

graph TB
    subgraph "源注册表"
        SMM["SOURCE_METADATA_MAP<br/>（sources.ts）"]
        CC["connectorConfigs<br/>（connectors.ts）"]
        CT["credentialTemplates<br/>（credentials.ts）"]
    end

    subgraph "界面组件"
        AC["AddConnectorPage.tsx"]
        CF["DynamicConnectorCreationForm.tsx"]
        CRED["CreateCredential.tsx"]
        STATUS["CCPairIndexingStatusTable.tsx"]
    end

    subgraph "数据钩子"
        UCS["useConnectorIndexingStatusWithPagination"]
        UGC["useGmailCredentials"]
    end

    subgraph "后端 API"
        API["/api/manage/admin/connector"]
        CAPI["/api/manage/admin/credential"]
        ISTATUS["/api/manage/admin/connector/indexing-status"]
    end

    SMM --> AC
    CC --> CF
    CT --> CRED

    AC --> UCS
    CF --> API
    CRED --> CAPI
    UCS --> ISTATUS

来源： [web/src/app/admin/connectors/[connector]/AddConnectorPage.tsx:129-182]()，web/src/lib/connectors/connectors.tsx:145-148，web/src/lib/connectors/credentials.ts:284-285

---

源元数据系统

每个数据源都注册了驱动界面展示的元数据，包括显示名称、图标以及是否支持 OAuth。

关键函数与元数据

函数	用途	文件引用
`SOURCE_METADATA_MAP`	图标、显示名称和 OAuth 支持状态的注册表	`web/src/lib/sources.ts:92-460`
`getSourceDisplayName`	返回 `ValidSources` 枚举对应的人类可读名称	`web/src/lib/sources.ts:506-508`
`getSourceMetadata`	检索特定源类型的元数据	`web/src/lib/sources.ts:464-476`

来源： web/src/lib/sources.ts:92-508

---

动态表单生成

连接器配置界面是根据 ConnectionConfiguration 模式动态生成的。每种连接器类型都指定了其必需的配置字段、高级选项和校验规则。

ConnectionConfiguration 模式

ConnectionConfiguration 对象定义了 DynamicConnectorCreationForm 如何渲染输入控件。

标题：连接配置数据流

graph LR
    subgraph "代码实体：ConnectionConfiguration"
        VAL["values: FieldOption[]"]
        ADV["advanced_values: FieldOption[]"]
        DESC["description: string"]
    end

    subgraph "界面组件：DynamicConnectorCreationForm"
        FORM["Formik 表单"]
        INPUTS["文本/选择/布尔输入"]
    end

    VAL --> FORM
    ADV --> FORM
    FORM --> INPUTS
    INPUTS -- "onSubmit" --> SUBMIT["submitConnector()"]

来源： web/src/lib/connectors/connectors.tsx:114-143，[web/src/app/admin/connectors/[connector]/AddConnectorPage.tsx:75-127]()

字段选项属性

配置中的字段可以是文本、数字、布尔值或复杂标签页。

visibleCondition：一个函数，根据当前表单值或所选凭证决定是否显示某个字段 web/src/lib/connectors/connectors.tsx:41-44。
label：可以是静态字符串，也可以是适配凭证类型的函数 web/src/lib/connectors/connectors.tsx:33-34。
type：决定输入组件类型（例如 select、multiselect、list、checkbox、file）web/src/lib/connectors/connectors.tsx:17-24。

来源： web/src/lib/connectors/connectors.tsx:32-112

---

凭证管理与关联

凭证是独立创建和管理的，但必须关联到连接器才能形成 CCPair。

凭证创建流程

CreateCredential 组件使用 credentialTemplates 来渲染特定源所需的字段。

标题：凭证关联逻辑

graph TD
    subgraph "前端：CreateCredential.tsx"
        TEMP["credentialTemplates[source]"]
        SUB["submitCredential()"]
    end

    subgraph "后端 API"
        CC["/api/manage/credential"]
        LINK["/api/manage/admin/connector"]
    end

    TEMP --> SUB
    SUB -- "POST" --> CC
    CC -- "credential_id" --> LINK

来源： [web/src/app/admin/connectors/[connector]/AddConnectorPage.tsx:12-18]()，[web/src/app/admin/connectors/[connector]/AddConnectorPage.tsx:75-127]()

多认证方式支持

某些源（如 SharePoint）支持多种认证方式。CredentialTemplateWithAuth 接口允许界面根据所选 authentication_method 切换字段 web/src/lib/connectors/credentials.ts:22-25。

来源： web/src/lib/connectors/credentials.ts:22-25

---

连接器状态与监控

管理界面提供了所有活跃 CCPair 的全面视图，包括其索引状态和文档数量。

索引状态仪表盘

状态表使用 ConnectorIndexingStatusLite 来获取所有连接器的摘要信息。

组件	角色	文件引用
`CCPairIndexingStatusTable`	渲染按源分组的主连接器表	`web/src/app/admin/indexing/status/CCPairIndexingStatusTable.tsx:1-218`
`CCPairStatus`	显示状态徽章（活跃、已暂停、初始索引中、错误）	`web/src/app/admin/indexing/status/CCPairIndexingStatusTable.tsx:175-186`
`SummaryRow`	按源显示汇总统计信息（总文档数、活跃连接器数）	`web/src/app/admin/indexing/status/CCPairIndexingStatusTable.tsx:66-137`

来源： web/src/app/admin/indexing/status/CCPairIndexingStatusTable.tsx:66-218

CCPair 详情视图

ConnectorRow 组件链接到特定 CC Pair 的管理页面 web/src/app/admin/indexing/status/CCPairIndexingStatusTable.tsx:151-155。该视图包含：

最后成功时间：连接器上次成功完成索引的时间 web/src/app/admin/indexing/status/CCPairIndexingStatusTable.tsx:172。
访问类型：指示连接器是公共、私有还是继承（同步）web/src/app/admin/indexing/status/CCPairIndexingStatusTable.tsx:189-205。
文档数量：该特定对已索引的文档总数 web/src/app/admin/indexing/status/CCPairIndexingStatusTable.tsx:208。

来源： web/src/app/admin/indexing/status/CCPairIndexingStatusTable.tsx:139-218

---

CCPair 校验与创建

当用户点击新连接器的"创建"按钮时，系统会执行校验。在后端，validate_ccpair_for_user 会实例化连接器并运行设置/权限校验。

标题：CCPair 创建序列

sequenceDiagram
    participant UI as AddConnectorPage.tsx
    participant API as /api/manage/admin/connector
    participant Backend as validate_ccpair_for_user

    UI->>API: POST /api/manage/admin/connector
    API->>Backend: 调用 validate_ccpair_for_user()
    Backend->>Backend: instantiate_connector()
    Backend->>Backend: validate_connector_settings()
    Backend-->>API: 校验结果
    API-->>UI: 200 OK（连接器）

来源： [web/src/app/admin/connectors/[connector]/AddConnectorPage.tsx:75-127]()，backend/onyx/connectors/factory.py:141-189

访问控制

连接器的访问类型通过 AccessTypeForm 和 AccessTypeGroupSelector 进行管理，允许管理员将连接器设置为"公共"、"私有"或"同步"（从源继承权限）[web/src/app/admin/connectors/[connector]/pages/DynamicConnectorCreationForm.tsx:72-76]()。

来源： [web/src/app/admin/connectors/[connector]/pages/DynamicConnectorCreationForm.tsx:72-76]()

---

关键实体总结

代码实体	位置	用途
`IndexAttemptSnapshot`	`web/src/lib/types.ts:204-216`	索引进度和最后状态指标的接口
`ConnectionConfiguration`	`web/src/lib/connectors/connectors.tsx:114-143`	定义动态表单字段的接口
`submitConnector`	[web/src/app/admin/connectors/[connector]/AddConnectorPage.tsx:75-127]()	用于 POST/PATCH 连接器配置的前端函数
`instantiate_connector`	`backend/onyx/connectors/factory.py:105-138`	用于创建连接器实例进行校验的后端工厂
`ConnectorIndexingStatusLite`	`web/src/app/admin/indexing/status/CCPairIndexingStatusTable.tsx:144`	用于仪表盘渲染的轻量级状态类型

来源： web/src/lib/types.ts:204-216，web/src/lib/connectors/connectors.tsx:114-143，[web/src/app/admin/connectors/[connector]/AddConnectorPage.tsx:75-127]()，backend/onyx/connectors/factory.py:105-138