LibianCrawler Document

暗色模式

LibianCrawler 系统概述 ​

LibianCrawler 是一个集成了数据采集、处理、管理与可选用户界面的复合型系统。其设计目标是为复杂的、多来源的数据获取场景提供一套标准化、可扩展的解决方案。

功能概述 ​

系统的核心功能围绕着自动化数据工作流展开，具体包括以下几个方面：

  • 数据采集能力: 系统支持两种主要的数据采集模式：

    1. API 直连采集: 针对提供结构化数据接口（API）的目标源，系统能够直接发起网络请求以获取数据。
    2. 浏览器自动化采集: 针对需要动态渲染或用户交互的Web页面，系统利用 Playwright 库驱动 Camoufox 指纹浏览器，模拟用户行为进行数据抓取。

  • 分布式任务执行: 系统包含一个 worker 组件，用于任务的调度与执行。该设计允许将数据采集任务分发至不同的执行节点，从而支持并行处理，提高了大规模数据采集的吞吐量和系统伸缩性。

  • 声明式任务定义: 数据采集流程（步骤、目标、参数等）被抽象为外部的 JSON 配置文件。这种声明式的方法将任务逻辑与执行引擎分离，使得非开发人员也能通过修改配置来调整或新增采集任务，降低了系统的使用门槛。

  • 数据处理流水线: 系统包含一个独立的数据处理模块，该模块采用 Deno 作为 TypeScript 运行时环境。它负责对采集到的原始数据执行清洗、格式转换、结构化提取等操作。

  • 用户交互界面: 系统提供一个基于 Vue.js 的Web前端应用，作为 worker 系统的图形化管理终端。该界面用于监控任务状态、查看结果和管理节点。使用 pywebview 库封装为桌面应用程序，实现了Python后端与前端UI的本地集成。

技术架构

LibianCrawler 采用多语言、多模块的微服务架构，旨在结合不同技术栈的优势，实现功能解耦和独立部署。

  • 核心后端 (Python):

    • 语言与环境: 使用 Python 作为后端服务的主要开发语言。依赖管理和虚拟环境隔离通过 Poetry 工具实现。
    • 核心组件: libiancrawlers 包是系统的核心，包含了 worker 任务调度器 (core.py) 和执行节点 (node.py) 的实现。app_util 子模块则提供了配置加载、日志、网络请求封装等应用级支持功能。
    • 浏览器驱动: 通过 playwright_util.py 对 Playwright 库进行封装，为上层应用提供统一的浏览器操作接口。

  • 数据处理服务 (TypeScript/Deno):

    • 运行时: data_cleaner_ci 模块选用 Deno 作为其 TypeScript 代码的运行时环境，利用其内置的安全性、工具链和对Web标准API的支持。
    • 数据转换: 该服务大量使用 JSONata 查询和转换语言。预定义的 .jsonata 模板用于执行复杂嵌套数据结构的提取和重塑，实现了数据转换逻辑的可视化和集中管理。
    • 数据持久化: nocodbutil.ts 和 pg.ts 文件表明，数据处理结果可被写入 PostgreSQL 数据库，并可能通过 NocoDB 平台进行管理和访问。

  • 前端界面 (Vue.js):

    • 框架与构建: worker-ui 目录是一个标准化的 Vue.js 3 项目，使用 TypeScript 进行类型约束，并采用 Vite 作为开发服务器和构建工具，以实现快速开发和高效打包。
    • 组件化: 界面遵循组件化开发模式，auto-imports.d.ts 和 components.d.ts 表明项目使用了自动导入功能以简化开发。
    • 后端集成: pywebview.d.ts 类型定义文件是关键，它为前端代码提供了与 pywebview 注入的Python后端通信的接口类型，这是实现桌面应用功能的桥梁。
项目结构解析

项目的目录结构反映了其模块化的设计思想，各主要目录的职责划分如下：

  • libiancrawlers/: Python 核心后端代码库。

    • app_util/: 应用层工具，如 config.py (配置管理), playwright_util.py (浏览器自动化封装)。
    • crawlers/: 存放具体爬虫逻辑的实现，可能按目标网站或类型分子目录。
    • worker/: 分布式任务执行框架，包含 core.py (核心调度), node.py (工作节点), ui.py (与UI的接口)。

  • data_cleaner_ci/: TypeScript 数据处理服务代码库。

    • general_data_process/: 通用数据处理脚本。
    • jsonata_templates/: 存放 .jsonata 格式的数据转换模板。

  • worker-ui/: Vue.js 前端应用代码库。

  • steps/: 存放 .json 格式的预定义采集任务。每个文件（如baidu.json）描述了一个完整的数据采集流程。

  • docs/: 项目文档，使用 VitePress 静态站点生成器构建。

工作流与数据流 ​

一个典型的数据处理任务在 LibianCrawler 系统中的生命周期如下：

  1. 任务启动: 用户或外部系统通过 直接命令行启动 或 调用 worker 服务的接口，并可指定一个位于 steps/ 目录下的 JSON 任务配置文件来启动一个爬虫。

  2. 任务执行: libiancrawlers 接收到请求，解析 JSON 文件中 定义的步骤，并调度相应的爬虫模块（API或浏览器）开始执行数据采集。

  3. 原始数据缓存: 采集到的原始数据（如 HTML、JSON 响应）被存储于垃圾湖中，等待后续处理。

  4. 数据移交与清洗: libiancrawlers 将原始数据移交给 data_cleaner_ci 服务。该服务根据预设的规则（如 JSONata 模板）对数据进行解析、验证、清洗和结构化。

  5. 数据输出: 清洗后的结构化数据被写入目标存储，例如 PostgreSQL 数据库。

  6. 状态监控: 在整个过程中，用户可以通过 worker-ui 界面实时监控任务的执行状态、进度和结果。

开发与贡献 ​

  • 项目蓝图: docs/develop/roadmap.md 文件中可能包含了项目未来的发展方向和功能规划，为潜在的贡献者提供了参与的思路。