Unstract Connector 开发运维指南:新增、删除与修改数据库 / 文件系统 / 队列连接器的完整生命周期

原创2026-09-15 10:39:591,866 阅读
文章标签:人工智能AI 应用大模型后端前端数据工程ETLNLP

Unstract Connector 开发运维指南:新增、删除与修改数据库 / 文件系统 / 队列连接器的完整生命周期

Unstract 通过一套统一的连接器(Connector)体系,让平台能够对接数据库、文件存储和消息队列三类外部数据源,从而支撑 API 部署与 ETL 流水线场景下的非结构化数据抽取。本文基于仓库中的 .claude/skills/connector-ops/SKILL.md 技能规范展开,系统梳理连接器的架构分层、目录结构与注册机制,并结合真实源码印证「新增(ADD)、删除(REMOVE)、修改(MODIFY)」三大运维操作的完整步骤,同时深入解析 fsspec 委托、Fork 安全、UUID 稳定性等关键模式与反模式,帮助你在 Unstract 中独立交付一个新的连接器。

一、连接器体系总览:三大类型与注册机制

Unstract 的连接器统一位于 连接器源码根目录 下,按用途划分为三类。理解这三类的基类、所在目录与运行模式,是后续所有操作的起点。

类型 基类 目录 运行模式(ConnectorMode)
数据库(Database) UnstractDB databases/ ConnectorMode.DATABASE
文件系统(Filesystem) UnstractFileSystem filesystems/ ConnectorMode.FILE_SYSTEM
队列(Queue) UnstractQueue queues/ ConnectorMode.MANUAL_REVIEW

从源码可以印证这套分层。三类连接器都继承自同一个抽象根类 UnstractConnector,它用 @abstractmethod 强制每个具体连接器实现一组「元数据 + 能力」接口:

  • 元数据接口:get_id()、get_name()、get_description()、get_icon()、get_json_schema();
  • 能力开关:can_read()、can_write()、requires_oauth()、get_connector_mode();
  • 校验入口:test_credentials()(返回凭证是否有效)。

运行模式的枚举定义在 enums.py 中,ConnectorMode 包含 FILE_SYSTEM = "FILESYSTEM"、DATABASE = "DATABASE"、MANUAL_REVIEW = "MANUAL_REVIEW" 等取值,与上表一一对应——队列连接器被映射到 MANUAL_REVIEW 模式,供平台将其用于人工审核环节。

三类基类的真实文件均已确认存在:

注册机制:目录即配置

连接器采用「自动发现(auto-discovery)」方式注册,无需在任何中心清单里手工登记。以数据库为例,databases/register.py 的逻辑是:

  1. 遍历 databases/ 下的每个子目录(跳过 __ 开头的特殊目录,如 __pycache__);
  2. 通过 import_module 动态导入该包,读取其 metadata 字典;
  3. 仅当 metadata.get("is_active", False) 为真时,才把该连接器纳入注册表,并以 connector_class.get_id() 作为唯一键;
  4. 若 ID 为空或重复,记录 Duplicate Id 告警;若某个子目录导入失败(ImportError),则记录错误日志并跳过,不会阻断其余连接器的加载。

文件系统侧同样有 filesystems/register.py 负责自动发现。三类发现结果最终在单例注册表中合并:connectorkit.py 中的 Connectorkit 用 @singleton 装饰,构造时执行 self._connectors = fs_connectors | db_connectors | q_connectors,把三类连接器字典做一次并集合并。

Connectorkit 还提供运行时查询能力,这也是「新增一个连接器后能被平台发现」的关键所在:

  • get_connectors_list(mode=None):遍历所有连接器,逐个调用 get_id()、get_name()、get_json_schema()、requires_oauth()、get_connector_mode() 等静态方法,组装出供前端渲染的配置表单列表;
  • get_connector_class_by_connector_id(connector_id):按 ID 反查连接器类,供执行侧实例化。

这一机制决定了新增连接器的验收标准:只要目录结构正确、metadata.is_active=True、get_id() 返回稳定的唯一 ID,连接器就会被自动发现并出现在列表中。

二、每个连接器的标准目录结构

一个连接器是一个独立的 Python 包,遵循固定的文件布局:

connector_name/
├── __init__.py          # 元数据字典,含 is_active 标志
├── connector_name.py    # 连接器主类
├── constants.py         # 可选常量
└── static/
    ├── json_schema.json # 配置表单的 JSON Schema
    └── settings.yaml    # 可选配置

其中 __init__.py 承担「自描述」职责。参考模板 init.py.template 给出的标准形态是:

from .{connector_name} import {ClassName}

metadata = {
    "name": {ClassName}.__name__,
    "version": "1.0.0",
    "connector": {ClassName},
    "description": "{description of the connector}",
    "is_active": True,
}

这里 metadata 的 is_active 字段正是前述自动发现的「开关」:设为 False 即可让一个连接器被注册器跳过而无需删除代码。get_json_schema() 的实现则统一约定为读取同目录 static/json_schema.json 的原始文本并返回,保证前端能拿到完整的表单 Schema。

三、操作一:新增(ADD)连接器

新增一个连接器是一条 10 步流水线。下面逐步给出规范步骤,并补充源码级的判断依据。

Step 1:明确需求

向需求方确认三件事:连接器名称(如 Redis、MongoDB、Wasabi)、连接器类型(database / filesystem / queue)、用途简述。这三项决定后续目录、基类与 Schema 的选择。

Step 2:调研目标服务

在动手前先做技术调研,重点确认:

  1. 该服务的官方 Python 库;
  2. 是否已存在成熟的 fsspec 兼容提供方——例如 S3 对应 s3fs、Azure 对应 adlfs、GCS 对应 gcsfs、Box 对应 boxfs。规范明确要求优先封装现成 provider,而非自研;
  3. 该服务支持的所有认证方式(API Key、OAuth、连接串、证书等);
  4. 每种认证方式所需的连接参数;
  5. 官方 Logo/图标来源。

仓库当前的 pyproject.toml 已经印证了「优先复用 fsspec provider」这一策略——文件系统连接器几乎全部建立在成熟 provider 之上:s3fs[boto3]==2024.10.0(Minio)、gcsfs==2024.10.0(GoogleCloudStorage)、adlfs~=2024.7.0(AzureCloudStorage)、boxfs==0.2.1(Box)、fsspec[sftp]~=2024.10.0(SFTP)。若调研发现没有现成 provider,则需在 Step 5b 走自定义 AbstractFileSystem 路线。

Step 3:生成连接器 ID

连接器 ID 采用 短名|UUID 的固定模式,用 uuid4() 生成:

f"{short_name}|{uuid4()}"
# 示例:"redis|a1b2c3d4-e5f6-7890-abcd-ef1234567890"

这个 ID 会被写入连接器的 get_id() 静态方法,并作为 Connectorkit 注册表的主键。一旦分配,永远不要改动(详见第六节「UUID 一致性」)。

Step 4:创建目录结构

按类型创建带 static/ 子目录的包:

# 数据库连接器
mkdir -p unstract/connectors/src/unstract/connectors/databases/{connector_name}/static

# 文件系统连接器
mkdir -p unstract/connectors/src/unstract/connectors/filesystems/{connector_name}/static

# 队列连接器
mkdir -p unstract/connectors/src/unstract/connectors/queues/{connector_name}/static

Step 5:编写连接器文件

5a. 编写 __init__.py

按 init.py.template 的形态落地 metadata 字典,is_active 置为 True。

5b. 编写主连接器类

主类从 .claude/skills/connector-ops/assets/templates/ 下选取对应模板,再针对具体服务做适配:

各类型需要实现的关键方法:

数据库连接器(基于 database.py.template):

  • get_engine() → 返回数据库连接对象;
  • sql_to_db_mapping() → 把 Python 类型映射为数据库列类型(如 bool→BOOLEAN、int→INTEGER、dict/list→JSON、bytes→BYTEA、其余→TEXT);
  • execute() → 执行查询(继承自基类,可选择覆写)。

文件系统连接器有两条路线,取决于是否存在 fsspec provider:

路线 A:封装现有 fsspec provider(首选)。 连接器只继承 UnstractFileSystem,核心实现:

  • get_fsspec_fs() → 返回 provider 的文件系统实例(如 S3FileSystem(...));
  • test_credentials() → 校验连接可用性;
  • extract_metadata_file_hash() → 从元数据中提取文件哈希(S3/Minio 用 ETag、Azure 用 content_md5、GCS 用 md5Hash);
  • is_dir_by_metadata() → 根据元数据判断路径是否为目录;
  • extract_modified_date() → 提取最后修改时间;
  • 不要实现 ls、walk、info 等方法——文件操作全部交由 provider 处理。

仓库中的 minio.py 正是路线 A 的范例:它 from s3fs.core import S3FileSystem 导入,并进一步定义 _AccessFilteredS3FileSystem(S3FileSystem) 来过滤当前凭证可访问的 bucket(并发探测、按 S3 Error.Code 决定保留或丢弃),文件读写能力完全复用 s3fs。

路线 B:自定义 AbstractFileSystem(仅当不存在 provider 时)。 只实现以下核心方法:

  • ls(path, detail=True) —— 列目录内容(必需);
  • info(path) —— 取单项元数据(可选优化);
  • _open(path, mode) —— 打开文件用于读取;
  • cat_file(path) —— 读取文件内容;
  • pipe_file(path, value) —— 写字节(注意是 pipe_file,不是 write_bytes,后者是前者的别名);
  • rm(path) —— 删除文件;
  • mkdir(path) —— 创建目录。

仓库中的 sharepoint.py 是路线 B 的参考实现,其 SharePointFileSystem(AbstractFileSystem) 恰好只实现了 ls、info、mkdir、_open、cat_file、pipe_file、rm 这一组核心方法,而没有去覆写 walk() / stat() 等派生方法——这正是第六节「fsspec 委托」原则的落地证据。

walk() 的例外情况:只有当文件系统的路径规范化逻辑与 _strip_protocol 不一致(例如 SharePoint 会把 "" 映射到 "root"),或者服务会抛出不是 FileNotFoundError/OSError 的异常(基类只捕获这两类)时,才允许覆写 walk()。一旦覆写,必须支持 detail 关键字参数(detail=True 返回字典、False 返回列表)以及 on_error 回调。

队列连接器(基于 queue.py.template):

  • get_engine() → 返回队列连接;
  • enqueue() → 入队消息;
  • dequeue() → 出队消息(支持超时);
  • peek() → 查看下一条消息但不移除。

5c. 编写 JSON Schema

static/json_schema.json 依据调研到的认证方式来生成,整体骨架为「allOf + oneOf」——allOf 第一段固定要求 connectorName,第二段用 oneOf 为每种认证方式各列一个分支:

{
  "title": "{Connector Display Name}",
  "type": "object",
  "allOf": [
    {
      "required": ["connectorName"],
      "properties": {
        "connectorName": {
          "type": "string",
          "title": "Name of the connector"
        }
      }
    },
    {
      "oneOf": [
        "// 为每种认证方式添加一个独立分支"
      ]
    }
  ]
}

敏感字段(密码、连接串)一律使用 "format": "password"。数据库场景下常见的「连接串 vs 独立参数」双分支写法,可直接参考模板 json_schema_template.json:一个 oneOf 分支只要求 connection_url,另一个分支要求 host/port/database/user/password 并附带 sslEnabled 布尔开关。更完整的各认证类型示例见 json_schema_examples.md。

Step 6:获取 Logo

运行 logo 抓取脚本:

python .claude/skills/connector-ops/scripts/fetch_logo.py "{service_name}" "{output_path}"

fetch_logo.py 会按顺序尝试多个来源:WorldVectorLogo、SimpleIcons、Devicon、Logo.dev API、Clearbit,均未命中则跳过并打印告警。命中的图标以 SVG 落盘。最终图标需放置于 frontend/public/icons/connector-icons/{ConnectorName}.png(该目录已存在 Bigquery.png、Box.png、Dropbox.png、Google Drive.png 等真实图标)。

Step 7:添加依赖

在 unstract/connectors/pyproject.toml 的 [project.dependencies] 段追加所需包,并遵循既有的版本钉选风格(如 ==、~=、>=)。现有依赖对同一 provider 使用了统一的钉选写法,例如 s3fs[boto3]==2024.10.0、gcsfs==2024.10.0、adlfs~=2024.7.0,新增时应对齐这种模式以保证可复现性。

Step 8:编写测试

在 unstract/connectors/tests/ 下同时产出 mock 测试与集成测试两套,模板见 test_mock.py.template 与 test_integration.py.template。

Mock 测试(必须可离线运行,永不依赖外部服务): 核心是用 @patch 把连接器模块内的连接库替换成 Mock,覆盖静态方法(get_id/get_name/get_json_schema 等)、初始化、get_engine() 成功/失败、test_credentials() 成功/失败、以及数据库特有的 execute() 与 sql_to_db_mapping()。模板里的 ID 格式断言值得保留——它校验 get_id() 返回形如 name|uuid 的字符串,且 name 部分等于连接器短名。

集成测试(依赖真实服务,默认跳过): 用 @unittest.skipUnless(os.getenv("{CONNECTOR}_HOST"), ...) 装饰,未设置对应环境变量时自动跳过;启用时从环境变量({CONNECTOR}_HOST、{CONNECTOR}_USER、{CONNECTOR}_PASSWORD 等)拼装配置并调用 test_credentials()。模板中还预留了数据库的建表/插入/查询/清理用例、文件系统的读写用例与队列的入出队用例,按需取消注释。

Step 9:验证

按以下顺序执行验证:

# 1. 语法/类型检查
cd unstract/connectors && python -m py_compile src/unstract/connectors/{type}/{name}/{name}.py

# 2. 运行 mock 测试
cd unstract/connectors && python -m pytest tests/{type}/test_{name}.py -v

# 3. 运行完整连接器测试套件(跳过集成测试)
cd unstract/connectors && python -m pytest tests/ -v --ignore=tests/{type}/test_{name}_integration.py

Step 10:向用户汇报

按规范给出的模板输出「新增连接器」小结,列出:创建的文件(__init__.py、主类、json_schema.json、两组测试、前端图标)、新增依赖、验证结果(语法检查 / mock 测试 / 测试套件),以及启用集成测试所需的 export {CONNECTOR}_* 环境变量与运行命令。

四、操作二:删除(REMOVE)连接器

删除操作强调「先排查依赖、再动手删除、最后回归验证」,避免留下悬空引用。

Step 1:定位连接器

# 按名称搜索连接器
grep -r "class {Name}" unstract/connectors/src/

Step 2:检查跨代码库依赖

grep -r "{connector_id}" --include="*.py" .
grep -r "from.*{connector_name}" --include="*.py" .

若连接器在其他地方被引用,需先警告用户。

Step 3:删除文件

# 删除连接器目录
rm -rf unstract/connectors/src/unstract/connectors/{type}/{name}/

# 删除测试
rm -f unstract/connectors/tests/{type}/test_{name}*.py

# 删除图标
rm -f frontend/public/icons/connector-icons/{Name}.png

说明:仓库为只读环境,以上命令用于描述该操作的语义与影响范围,实际变更应由具备写权限的开发者在其本地工作副本中执行。

Step 4:清理依赖(可选)

若被删除的连接器是某个依赖的唯一使用者,可提议从 pyproject.toml 中移除该依赖。

Step 5:验证

# 确认无导入错误
cd unstract/connectors && python -c "from unstract.connectors.connectorkit import Connectorkit; Connectorkit()"

# 运行测试套件
cd unstract/connectors && python -m pytest tests/ -v

第一行直接实例化 Connectorkit(),能触发三类的自动发现与字典合并——若删除引入导入错误,这里会立即暴露。

Step 6:向用户汇报

按模板输出「删除连接器」小结,列出被删除的文件与导入检查 / 测试套件两项验证结果。

五、操作三:修改(MODIFY)连接器

修改操作按变更类型分而治之,核心是「改一处、补一测、跑全量」。

Step 1:明确变更类型

向需求方确认属于以下哪一类:新增配置字段?新增认证方式?修 bug?升级依赖版本?还是改变行为?

Step 2:定位文件

find unstract/connectors -name "*{connector_name}*" -type f

Step 3:实施变更

  • 新增配置字段:依次更新 static/json_schema.json → 更新连接器类 __init__ 读取新字段 → 在连接器方法中使用该字段 → 更新测试覆盖新字段。
  • 新增认证方式:调研新认证方式参数 → 在 JSON Schema 中新增一个 oneOf 分支 → 更新连接器类处理新认证 → 为新认证方式补测试。对于同时支持 OAuth 与 Client Credentials 的连接器(如 SharePoint/OneDrive),应使用 connector_patterns.md 中记录的双认证(Dual Authentication)模式:通过 auth_type 字段配合 JSON Schema 的 dependencies,按所选认证方式条件性地显示/隐藏凭证字段。
  • 修 bug:定位根因 → 实施修复 → 补回归测试。
  • 升级依赖:更新 pyproject.toml 中的版本 → 检查破坏性变更 → 按需调整连接器代码 → 跑测试验证。

Step 4:更新测试

确保测试覆盖本次变更:为新功能补用例、因行为变化而调整既有测试,最后运行全量套件。

Step 5:验证

# 类型检查被改文件
cd unstract/connectors && python -m py_compile src/unstract/connectors/{type}/{name}/{name}.py

# 运行连接器测试
cd unstract/connectors && python -m pytest tests/{type}/test_{name}*.py -v

# 运行全量套件
cd unstract/connectors && python -m pytest tests/ -v

Step 6:向用户汇报

按模板输出「修改连接器」小结,包含:变更点描述、被修改文件列表、测试统计(新增/修改数量)、验证结果(语法检查 / 连接器测试 / 全量套件)。

六、关键模式与反模式(源码级印证)

SKILL 文档在「Important Notes」中沉淀了几条贯穿始终的工程约束,它们直接关系到连接器在 Celery worker 环境下的稳定性与长期可维护性。

1. Fork 安全:懒加载防止 SIGSEGV

问题:使用 gRPC 的连接器(Google APIs 等)若在 fork 之前初始化客户端,Celery fork 子进程时可能触发 SIGSEGV。 解法:在 __init__ 中只保存配置、不初始化客户端,改用「带线程锁的懒加载」在真正使用时(fork 之后)再导入并重客户端。filesystem.py.template 的 get_fsspec_fs() 正是这一模式:__init__ 里只置 self._fs = None 与 self._fs_lock = threading.Lock(),首次调用时再做 double-check 导入与实例化,模板注释明确写着「DO NOT initialize clients in __init__(prevents gRPC issues with Celery fork)」。更完整的懒加载范例见 connector_patterns.md 中的 Fork-Safe Initialization 小节。

2. UUID 一致性:ID 一经分配不可更改

connector_id 是 Connectorkit 注册表的主键,也是已有安装环境持久化引用的键。若随意变更,现有配置将无法再解析到对应连接器。因此「UUID 一致性」被列为硬约束。

3. Schema 向后兼容

修改 json_schema.json 时,必须保证既有配置依然合法——尤其是 oneOf 多分支场景下,删除某个分支可能让存量保存的连接串/参数配置直接失效。

4. 图标命名规范

图标文件使用 PascalCase 并将空格做 URL 编码,例如 Google%20Drive.png。这与 frontend/public/icons/connector-icons/ 下已存在的 Google Drive.png 等命名保持一致。

5. 测试隔离

Mock 测试绝不依赖外部服务;集成测试用 @unittest.skipUnless 守卫。这保证了 CI 的 mock 套件在任何环境下都能稳定通过。

6. fsspec 委托原则(最重要的反模式)

自定义 AbstractFileSystem 子类中,永远不要覆写 walk()、listdir()、stat()、exists()、isdir()、isfile()、delete()、read_bytes()、write_bytes() 这些方法——它们已由 fsspec 基类提供,并统一委托到 ls()/info()/pipe_file()。覆写它们只会徒增维护成本并引入隐蔽 bug(例如 walk() 未支持 detail=True 会破坏文件发现逻辑)。

配套的 pipe_file vs write_bytes 规则:实现写文件时应覆写 pipe_file(),因为基类的 write_bytes() 是它的别名,最终仍会委托给 pipe_file()。

sharepoint.py 可作为这一原则的正例:SharePointFileSystem 只实现了 ls(含 detail 参数)、info、mkdir、_open、cat_file、pipe_file、rm 等核心方法,把 stat/exists/isdir/read_bytes/write_bytes 等派生能力留给基类——既满足路线 B 的最小实现集,又严格遵守了「只写核心方法、不覆写派生方法」的约束。

七、参考材料与模板索引

本技能的完整资产集中在 connector-ops 技能目录 下,按职责分为三类:

参考文档(patterns)

资产模板(assets/templates)

辅助脚本(scripts)

八、小结

Unstract 的连接器体系以「统一抽象基类 + 目录自动发现 + 单例注册表」为骨架,把新增 / 删除 / 修改三类运维操作收敛成可复用的标准流程:新增沿「调研 → 生成 ID → 建目录 → 选模板 → 写 Schema → 取图标 → 加依赖 → 双套测试 → 三级验证 → 汇报」推进;删除坚持「先查依赖再删后验证」;修改按变更类型「改一补一跑全量」。真正决定质量的是几条硬约束——fsspec 委托(只写核心方法、不覆写派生方法、用 pipe_file 而非 write_bytes)、Fork 安全懒加载、UUID 永不变更、Schema 向后兼容、测试隔离。掌握这套骨架与约束,即可在 连接器源码根目录 下独立交付数据库、文件系统、队列三类新连接器。

登录后查看全文
unstract