Unstract Connector 开发运维指南:新增、删除与修改数据库 / 文件系统 / 队列连接器的完整生命周期
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 模式,供平台将其用于人工审核环节。
三类基类的真实文件均已确认存在:
- 数据库基类 UnstractDB
- 文件系统基类 UnstractFileSystem
- 队列基类 UnstractQueue
注册机制:目录即配置
连接器采用「自动发现(auto-discovery)」方式注册,无需在任何中心清单里手工登记。以数据库为例,databases/register.py 的逻辑是:
- 遍历
databases/下的每个子目录(跳过__开头的特殊目录,如__pycache__); - 通过
import_module动态导入该包,读取其metadata字典; - 仅当
metadata.get("is_active", False)为真时,才把该连接器纳入注册表,并以connector_class.get_id()作为唯一键; - 若 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:调研目标服务
在动手前先做技术调研,重点确认:
- 该服务的官方 Python 库;
- 是否已存在成熟的 fsspec 兼容提供方——例如 S3 对应
s3fs、Azure 对应adlfs、GCS 对应gcsfs、Box 对应boxfs。规范明确要求优先封装现成 provider,而非自研; - 该服务支持的所有认证方式(API Key、OAuth、连接串、证书等);
- 每种认证方式所需的连接参数;
- 官方 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)
- connector_patterns.md:常见模式与反模式(Fork 安全、连接串 vs 参数、SSL/TLS 分级、凭证测试、类型映射、fsspec 委托等);
- json_schema_examples.md:各认证类型的 JSON Schema 示例;
- test_patterns.md:测试模式与 fixture。
资产模板(assets/templates)
- 连接器类模板:database.py.template、filesystem.py.template、queue.py.template、init.py.template;
- Schema 模板:json_schema_template.json;
- 测试模板:test_mock.py.template、test_integration.py.template。
辅助脚本(scripts)
- fetch_logo.py:多来源抓取连接器图标;
- verify_connector.py:连接器校验脚本。
八、小结
Unstract 的连接器体系以「统一抽象基类 + 目录自动发现 + 单例注册表」为骨架,把新增 / 删除 / 修改三类运维操作收敛成可复用的标准流程:新增沿「调研 → 生成 ID → 建目录 → 选模板 → 写 Schema → 取图标 → 加依赖 → 双套测试 → 三级验证 → 汇报」推进;删除坚持「先查依赖再删后验证」;修改按变更类型「改一补一跑全量」。真正决定质量的是几条硬约束——fsspec 委托(只写核心方法、不覆写派生方法、用 pipe_file 而非 write_bytes)、Fork 安全懒加载、UUID 永不变更、Schema 向后兼容、测试隔离。掌握这套骨架与约束,即可在 连接器源码根目录 下独立交付数据库、文件系统、队列三类新连接器。