收割者 - 通用数据采集框架

📖 中文文档 | 英文 | 🔗 更多工具

一个通用、自适应的数据采集框架，旨在从多个来源全面获取信息，包括 GitHub、网络测绘平台（FOFA、Shodan）以及任意 Web 端点。尽管当前实现以 AI 服务提供商密钥发现作为实际示例，但该框架的架构设计具有高度可扩展性，能够支持多样化的数据采集场景。

---

⭐⭐⭐ 如果这个项目对您有帮助，请给它点个赞！ 您的支持将激励我们不断改进并添加新功能。

---

目录

• 关键特性
• 快速入门
• 架构
• 目录结构
• 故障排除
• 贡献

项目目标

该系统旨在构建一个通用数据采集框架，主要针对以下目标：

• GitHub：代码仓库、问题、提交记录及 API 端点
• 网络测绘平台：
  • FOFA - 网络空间测绘与资产发现
  • Shodan - 互联网设备搜索引擎
• 任意 Web 端点：自定义 API、Web 服务及其他数据源
• 可扩展架构：基于插件的系统，便于集成新的数据源

当前数据源支持情况

数据源	状态	描述
GitHub API	✅ 已实现	完整的 API 集成，并支持限流
GitHub Web	✅ 已实现	带智能解析的网页爬取
FOFA	🚧 计划中	网络空间资产发现集成
Shodan	🚧 计划中	物联网及网络设备枚举
自定义 APIs	🚧 计划中	通用 REST/GraphQL API 适配器

架构

分层架构

graph TB
    %% 入口层
    subgraph Entry["入口层"]
        CLI["CLI 界面<br/>(main.py)"]
        App["应用核心<br/>(main.py)"]
    end

    %% 管理层
    subgraph Management["管理层"]
        TaskMgr["任务管理器<br/>(manager/task.py)"]
        Pipeline["流水线管理器<br/>(manager/pipeline.py)"]
        WorkerMgr["工作者管理器<br/>(manager/worker.py)"]
        QueueMgr["队列管理器<br/>(manager/queue.py)"]
        StatusMgr["状态管理器<br/>(manager/status.py)"]
        Shutdown["关机协调器<br/>(manager/shutdown.py)"]
    end

    %% 处理层
    subgraph Processing["处理层"]
        StageBase["阶段框架<br/>(stage/base.py)"]
        StageImpl["阶段实现<br/>(stage/definition.py)"]
        StageReg["阶段注册表<br/>(stage/registry.py)"]
        StageFactory["阶段工厂<br/>(stage/factory.py)"]
        StageResolver["依赖解析器<br/>(stage/resolver.py)"]
    end

    %% 服务层
    subgraph Service["服务层"]
        SearchSvc["搜索服务<br/>(search/client.py)"]
        SearchProviders["搜索提供者<br/>(search/provider/)"]
        RefineSvc["查询优化<br/>(refine/)"]
        RefineEngine["优化引擎<br/>(refine/engine.py)"]
        RefineOptimizer["查询优化器<br/>(refine/optimizer.py)"]
    end

    %% 核心领域层
    subgraph Core["核心领域层"]
        Models["领域模型与任务<br/>(core/models.py)"]
        Types["类型系统<br/>(core/types.py)"]
        Enums["枚举类型<br/>(core/enums.py)"]
        Metrics["指标<br/>(core/metrics.py)"]
        Auth["认证模块<br/>(core/auth.py)"]
    end

    %% 基础设施层
    subgraph Infrastructure["基础设施层"]
        Config["配置<br/>(config/)"]
        Tools["工具与实用程序<br/>(tools/)"]
        Constants["常量<br/>(constant/)"]
        Storage["存储与持久化<br/>(storage/)"]
    end

    %% 状态管理层
    subgraph StateLayer["状态管理层"]
        StateCollector["状态收集器<br/>(state/collector.py)"]
        StateDisplay["显示引擎<br/>(state/display.py)"]
        StateBuilder["状态构建器<br/>(state/builder.py)"]
        StateModels["状态模型<br/>(state/models.py)"]
        StateMonitor["状态监控器<br/>(state/monitor.py)"]
        StateEnums["状态枚举<br/>(state/enums.py)"]
        StateTypes["状态类型<br/>(state/types.py)"]
    end

    %% 外部系统
    subgraph External["外部系统"]
        GitHub["GitHub<br/>(API + Web)"]
        AIServices["AI 服务提供商"]
        FileSystem["文件系统<br/>(本地存储)"]
    end

    %% 依赖关系（自上而下）
    Entry --> Management
    Management --> Processing
    Processing --> Service
    Service --> Core

    %% 基础设施依赖
    Entry -.-> Infrastructure
    Management -.-> Infrastructure
    Processing -.-> Infrastructure
    Service -.-> Infrastructure
    Core -.-> Infrastructure

    %% 状态管理依赖
    Entry -.-> StateLayer
    Management -.-> StateLayer

    %% 外部依赖
    Service --> External
    Infrastructure --> External

系统架构概览

graph TB
    %% 用户界面层
    subgraph UserLayer["用户界面层"]
        User[用户]
        CLI[命令行界面]
        ConfigMgmt[配置管理]
    end

    %% 应用管理层
    subgraph AppLayer["应用管理层"]
        MainApp[主应用]
        TaskManager[任务管理器]
        StatusManager[状态管理器]
        ResourceManager[资源管理器]
        ShutdownManager[关闭管理器]
    end

    %% 核心管道引擎
    subgraph PipelineCore["管道引擎"]
        %% 阶段管理系统
        subgraph StageSystem["阶段管理系统"]
            StageRegistry[阶段注册表]
            DependencyResolver[依赖解析器]
            StageFactory[阶段工厂]
        end

        %% 队列管理系统
        subgraph QueueSystem["队列管理系统"]
            QueueManager[队列管理器]
            WorkerManager[工作线程管理器]
            MonitoringSystem[系统监控]
        end

        %% 处理阶段
        subgraph ProcessingStages["处理阶段"]
            SearchStage[搜索阶段]
            GatherStage[收集阶段]
            CheckStage[检查阶段]
            InspectStage[检查阶段]
        end
    end

    %% 搜索提供商生态系统
    subgraph ProviderEcosystem["搜索提供商生态系统"]
        ProviderRegistry[提供商注册表]
        BaseProvider[基础提供商]
        OpenAIProvider[类似OpenAI的提供商]
        CustomProviders[自定义提供商]
    end

    %% 高级处理引擎
    subgraph ProcessingEngines["处理引擎"]
        SearchClient[搜索客户端]

        %% 查询优化引擎
        subgraph QueryOptimizer["查询优化引擎"]
            RefineEngine[细化引擎]
            RegexParser[正则表达式解析器]
            SplittabilityAnalyzer[可拆分性分析器]
            EnumerationOptimizer[枚举优化器]
            QueryGenerator[查询生成器]
            OptimizationStrategies[优化策略]

            %% 内部流程
            RefineEngine --> RegexParser
            RegexParser --> SplittabilityAnalyzer
            SplittabilityAnalyzer --> EnumerationOptimizer
            EnumerationOptimizer --> OptimizationStrategies
            OptimizationStrategies --> QueryGenerator
        end

        ValidationEngine[API密钥验证]
        RecoveryEngine[任务恢复]
    end

    %% 状态与数据管理
    subgraph StateManagement["状态与数据管理"]
        StateCollector[状态收集器]
        DisplayEngine[显示引擎]
        StatusBuilder[状态构建器]
        StateMonitor[状态监视器]
        PersistenceLayer[持久化层]
        SnapshotManager[快照管理器]
        ResultManager[结果管理器]
    end

    %% 基础设施服务
    subgraph Infrastructure["基础设施服务"]
        RateLimiting[速率限制]
        CredentialMgmt[凭证管理]
        AgentRotation[用户代理轮换]
        LoggingSystem[日志系统]
        RetryFramework[重试框架]
        ResourcePool[资源池]
    end

    %% 外部系统
    subgraph External["外部系统"]
        GitHubAPI[GitHub API]
        GitHubWeb[GitHub Web界面]
        AIServiceAPIs[AI服务APIs]
        FileSystem[本地文件系统]
    end

    %% 用户交互
    User --> CLI
    User --> ConfigMgmt
    CLI --> MainApp
    ConfigMgmt --> MainApp

    %% 应用流程
    MainApp --> TaskManager
    MainApp --> StatusManager
    MainApp --> ResourceManager
    MainApp --> ShutdownManager
    TaskManager --> StageRegistry
    TaskManager --> QueueManager

    %% 阶段管理流程
    StageRegistry --> DependencyResolver
    StageRegistry --> StageFactory
    DependencyResolver --> ProcessingStages
    StageFactory --> ProcessingStages

    %% 队列管理流程
    QueueManager --> WorkerManager
    QueueManager --> MonitoringSystem
    WorkerManager --> ProcessingStages

    %% 阶段依赖关系（管道）
    SearchStage --> GatherStage
    GatherStage --> CheckStage
    CheckStage --> InspectStage

    %% 处理引擎集成
    SearchStage --> SearchClient
    SearchStage --> QueryOptimizer
    CheckStage --> ValidationEngine
    ProcessingStages --> RecoveryEngine

    %% 提供商集成
    SearchClient --> ProviderRegistry
    ProviderRegistry --> BaseProvider
    BaseProvider --> OpenAIProvider
    BaseProvider --> CustomProviders

    %% 状态管理集成
    ProcessingStages --> StateCollector
    QueueManager --> StateCollector
    StateCollector --> DisplayEngine
    StateCollector --> StatusBuilder
    StateMonitor --> DisplayEngine
    ProcessingStages --> PersistenceLayer
    PersistenceLayer --> SnapshotManager
    PersistenceLayer --> ResultManager

    %% 基础设施集成
    SearchClient -.-> RateLimiting
    ResourceManager -.-> CredentialMgmt
    ResourceManager -.-> AgentRotation
    MainApp -.-> LoggingSystem
    ProcessingStages -.-> RetryFramework
    Infrastructure -.-> ResourcePool

    %% 外部连接
    SearchClient --> GitHubAPI
    SearchClient --> GitHubWeb
    ValidationEngine --> AIServiceAPIs
    PersistenceLayer --> FileSystem

    %% 样式
    classDef userClass fill:#e3f2fd,stroke:#1976d2,stroke-width:2px
    classDef appClass fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
    classDef coreClass fill:#e8f5e8,stroke:#388e3c,stroke-width:3px
    classDef providerClass fill:#fff3e0,stroke:#f57c00,stroke-width:2px
    classDef engineClass fill:#fce4ec,stroke:#c2185b,stroke-width:2px
    classDef stateClass fill:#f1f8e9,stroke:#689f38,stroke-width:2px
    classDef infraClass fill:#f5f5f5,stroke:#616161,stroke-width:2px
    classDef externalClass fill:#ffebee,stroke:#d32f2f,stroke-width:2px

    class User,CLI,ConfigMgmt userClass
    class MainApp,TaskManager,StatusManager,ResourceManager,ShutdownManager appClass
    class StageRegistry,DependencyResolver,StageFactory,QueueManager,WorkerManager,MonitoringSystem,SearchStage,GatherStage,CheckStage,InspectStage coreClass
    class ProviderRegistry,BaseProvider,OpenAIProvider,CustomProviders providerClass
    class SearchClient,QueryOptimizer,ValidationEngine,RecoveryEngine engineClass
    class StateCollector,StateMonitor,DisplayEngine,StatusBuilder,PersistenceLayer,SnapshotManager,ResultManager stateClass
    class RateLimiting,CredentialMgmt,AgentRotation,LoggingSystem,RetryFramework,ResourcePool infraClass
    class GitHubAPI,GitHubWeb,AIServiceAPIs,FileSystem externalClass

该项目采用分层架构，核心组件如下：

多阶段处理流程

sequenceDiagram
    participant CLI as CLI
    participant App as Application
    participant TM as TaskManager
    participant Pipeline as Pipeline
    participant Search as SearchStage
    participant Gather as GatherStage
    participant Check as CheckStage
    participant Inspect as InspectStage
    participant Storage as Storage
    participant Monitor as StatusManager

    %% 初始化阶段
    CLI->>App: 1. 启动应用
    App->>App: 2. 加载配置
    App->>TM: 3. 创建任务管理器
    TM->>TM: 4. 初始化服务提供者
    TM->>Pipeline: 5. 创建流水线
    Pipeline->>Search: 6. 注册搜索阶段
    Pipeline->>Gather: 7. 注册收集阶段
    Pipeline->>Check: 8. 注册检查阶段
    Pipeline->>Inspect: 9. 注册检查阶段
    App->>Monitor: 10. 启动状态管理器

    %% 处理阶段
    loop 多阶段处理
        TM->>Search: 11. 提交搜索任务
        Search->>Search: 12. 带优化的 GitHub 查询
        Search->>Gather: 13. 转发搜索结果

        Gather->>Gather: 14. 获取详细信息
        Gather->>Check: 15. 转发提取的密钥

        Check->>Check: 16. 验证 API 密钥
        Check->>Inspect: 17. 转发有效密钥

        Inspect->>Inspect: 18. 检查 API 功能
        Inspect->>Storage: 19. 保存结果

        Pipeline->>Monitor: 20. 更新状态
        Monitor->>App: 21. 显示进度
    end

    %% 恢复与持久化
    loop 后台操作
        Storage->>Storage: 自动保存结果
        Storage->>Storage: 创建快照
        Pipeline->>Pipeline: 任务恢复
        Monitor->>Monitor: 收集指标
    end

    %% 完成阶段
    Pipeline->>Pipeline: 22. 检查是否完成
    Pipeline->>Storage: 23. 最终持久化
    Pipeline->>Monitor: 24. 最终状态报告
    App->>TM: 25. 优雅关闭
    TM->>Storage: 26. 保存状态

架构层次

1. 表现层

• CLI 界面 (main.py)：命令行入口，包含参数解析和应用生命周期管理
• 配置系统 (config/)：基于 YAML 的配置管理，支持验证和模式定义

2. 应用层

• 应用核心 (main.py)：主应用生命周期及编排逻辑
• 任务管理 (manager/task.py)：服务提供者协调与任务分发
• 资源协调 (tools/coordinator.py)：全局资源管理和协调
• 关闭管理 (manager/shutdown.py)：优雅关闭协调
• 状态管理 (manager/status.py)：应用状态管理和协调
• 工作线程管理 (manager/worker.py)：工作线程管理和扩展
• 队列管理 (manager/queue.py)：多队列协调与管理

3. 业务服务层

• 流水线引擎 (manager/pipeline.py)：基于 DAG 执行的多阶段处理编排
• 阶段系统 (stage/)：可插拔的处理阶段，支持依赖解析和工厂模式
• 搜索服务 (search/)：GitHub 代码搜索，提供抽象层和优化功能
• 查询优化 (refine/)：基于策略模式和数学基础的智能查询优化

4. 领域层

• 核心模型与任务 (core/models.py)：业务领域对象、数据结构和任务定义
• 类型系统 (core/types.py)：接口定义和契约
• 业务枚举 (core/enums.py)：领域枚举和常量
• 度量与分析 (core/metrics.py)：性能测量和 KPI 跟踪
• 认证 (core/auth.py)：认证和授权逻辑
• 自定义异常 (core/exceptions.py)：领域特定的异常处理
• 自定义异常 (core/exceptions.py)：领域特定的异常处理

5. 基础设施层

• 存储与持久化 (storage/)：结果存储、恢复和快照管理
  • 原子操作 (storage/atomic.py)：带 fsync 的原子文件操作
  • 结果管理 (storage/persistence.py)：多格式结果持久化
  • 任务恢复 (storage/recovery.py)：任务恢复机制
  • 分片管理 (storage/shard.py)：带轮转的 NDJSON 分片管理
  • 快照管理 (storage/snapshot.py)：备份和恢复功能
• 工具与实用程序 (tools/)：基础设施工具和实用程序
  • 日志系统 (tools/logger.py)：带 API 密钥脱敏的结构化日志
  • 限流 (tools/ratelimit.py)：基于令牌桶算法的自适应速率控制
  • 负载均衡 (tools/balancer.py)：资源分配策略
  • 凭证管理 (tools/credential.py)：安全的凭证轮换和管理
  • 代理管理 (tools/agent.py)：用于网页抓取的用户代理轮换
  • 模式匹配 (tools/patterns.py)：模式匹配工具和辅助函数
  • 重试框架 (tools/retry.py)：统一的重试机制，支持退避策略
  • 资源池 (tools/resources.py)：资源池管理和优化

6. 状态管理层

• 状态采集 (state/collector.py)：系统指标收集和聚合
• 显示引擎 (state/display.py)：用户友好的进度可视化和格式化
• 状态构建器 (state/builder.py)：状态数据的构建和转换
• 状态模型 (state/models.py)：监控数据结构和指标
• 状态监控 (state/monitor.py)：实时状态监控和跟踪
• 状态枚举 (state/enums.py)：状态相关枚举和常量
• 状态类型 (state/types.py)：状态类型定义和接口

处理阶段

系统实现了4阶段流水线，用于全面的数据采集与验证：

1. 搜索阶段（stage/definition.py:SearchStage）：

   • 带有高级查询优化的智能GitHub代码搜索
   • 多提供商搜索支持（API + Web）
   • 使用数学优化算法进行查询精炼
   • 具有自适应限流功能的速率限制搜索执行

2. 收集阶段（stage/definition.py:GatherStage）：

   • 从搜索结果中获取详细信息
   • 内容提取与解析
   • 模式匹配以识别关键信息
   • 结构化数据的收集与归一化

3. 检查阶段（stage/definition.py:CheckStage）：

   • 根据实际服务端点验证API密钥
   • 身份验证与能力测试
   • 服务可用性及响应验证
   • 错误处理与重试机制

4. 检查阶段（stage/definition.py:InspectStage）：

   • 针对已验证密钥的API能力检查
   • 模型枚举与功能检测
   • 服务限制与配额分析
   • 全面的能力画像生成

高级查询优化引擎

系统配备了一个基于数学原理的复杂查询优化引擎：

核心组件

1. 正则表达式解析器：

   • 支持复杂语法的高级正则模式解析
   • 处理转义字符、字符类和量词
   • 将模式转换为可分析的段结构

2. 可拆分性分析器：

   • 对模式可分割性的数学分析
   • 递归深度限制以确保安全
   • 值阈分析以判断优化可行性
   • 资源成本估算以控制性能

3. 枚举优化器：

   • 智能选择枚举策略
   • 多维度优化（深度、广度、值）
   • 组合分析以选择最优段
   • 拓扑排序以解决依赖关系

4. 查询生成器：

   • 根据枚举策略生成优化后的查询变体
   • 支持可配置的枚举深度
   • 产生数学上最优的查询分布
   • 保持查询语义等价性

优化算法

• 数学建模：利用数学原理分析正则模式
• 枚举策略：智能选择最优的枚举深度和组合
• 资源管理：通过智能限制造避免资源耗尽
• 性能优化：单例模式确保最佳内存使用

支持的数据来源与用例

🔍 当前实现（AI服务发现）

• OpenAI及其兼容接口
• Anthropic Claude
• Azure OpenAI
• Google Gemini
• AWS Bedrock
• GooeyAI
• Stability AI
• 百度文心一言
• 智谱AI
• 自定义提供商

🌐 计划中的数据来源

• FOFA：网络空间资产发现与网络映射
• Shodan：互联网连接设备枚举
• 自定义REST API：通用API集成框架
• GraphQL端点：灵活的基于查询的数据获取
• 网页爬取：JavaScript渲染内容及动态站点
• 数据库连接器：直接查询数据库的能力

📊 潜在用例

• 数据挖掘：大规模信息提取与分析

关键特性

🌐 通用数据采集

• 多源支持：GitHub、FOFA、Shodan及自定义端点
• 自适应查询引擎：针对不同数据源的智能优化
• 协议无关：支持REST、GraphQL、WebSocket及网页爬取
• 速率限制：按来源的智能速率控制与配额管理

🏗️ 先进架构

• 动态阶段系统：可配置的处理流水线，采用DAG执行
• 插件架构：可扩展的框架，支持自定义数据源和处理器
• 依赖关系解析：自动阶段排序与依赖管理
• 处理器注册：可插拔处理器，实现灵活的数据转换

⚡ 高性能

• 异步处理：多线程任务执行，配合智能队列
• 自适应负载均衡：根据工作负载动态分配资源
• 查询优化：通过数学建模实现最优搜索策略
• 资源监控：实时性能跟踪与瓶颈检测

🛡️ 企业级就绪

• 容错性：全面的错误处理、重试机制及恢复能力
• 状态持久化：队列状态恢复与优雅关机能力
• 安全性：凭据管理、API密钥脱敏及安全存储
• 监控：实时分析、告警及性能可视化

系统要求

依赖项

• Python：3.10及以上
• 库：PyYAML
• 可选：uvloop（Linux/macOS性能提升）
• 开发：pytest、black、mypy（供贡献者使用）

快速入门

📚 如需全面的文档、教程和高级使用指南，请访问 DeepWiki

1. 安装

   git clone https://github.com/wzdnzd/harvester.git
   cd harvester
   pip install -r requirements.txt
   

2. 配置

请选择以下任一方法来创建您的配置文件

方法一：生成默认配置

python main.py --create-config

方法二：从示例复制

# 对于基础配置
cp examples/config-simple.yaml config.yaml

# 对于包含所有选项的完整配置
cp examples/config-full.yaml config.yaml

编辑配置文件：

• 设置您的 GitHub 会话令牌或 API 密钥
• 配置提供商搜索模式
• 调整速率限制和线程数

配置指南

系统提供了两种配置模板：

1. 基础配置 - 适合快速入门：

   # 全局应用设置
   global:
     workspace: "./data"  # 工作目录
     github_credentials:
       sessions:
         - "your_github_session_here"  # GitHub 会话令牌
       strategy: "round_robin"  # 负载均衡策略
   
   # 流水线阶段配置
   pipeline:
     threads:
       search: 1    # 搜索线程（保持较低）
       gather: 4   # 获取线程
       check: 2     # 验证线程
       inspect: 1    # API 能力检测线程
   
   # 系统监控设置
   monitoring:
     update_interval: 2.0    # 监控更新间隔
     error_threshold: 0.1    # 错误率阈值
   
   # 数据持久化配置
   persistence:
     auto_restore: true      # 启动时自动恢复状态
     shutdown_timeout: 30    # 关机超时时间（秒）
   
   # 全局速率限制配置
   ratelimits:
     github_web:
       base_rate: 0.5       # 基础速率（每秒请求数）
       burst_limit: 2       # 最大突发数量
       adaptive: true       # 启用自适应速率限制
   
   # 提供商任务配置
   tasks:
     - name: "openai"         # 提供商名称
       enabled: true          # 是否启用该提供商
       provider_type: "openai"
       use_api: false         # 是否使用 GitHub API 进行搜索
   
       # 流水线阶段设置
       stages:
         search: true         # 启用搜索阶段
         gather: true         # 启用获取阶段
         check: true          # 启用验证阶段
         inspect: true        # 启用 API 能力检测
   
       # 模式匹配配置
       patterns:
         key_pattern: "sk(?:-proj)?-[a-zA-Z0-9]{20}T3BlbkFJ[a-zA-Z0-9]{20}"
   
       # 搜索条件
       conditions:
         - query: '"T3BlbkFJ"'
   

2. 完整配置 - 包含所有高级选项：

   • display: 显示与监控设置
   • global: 全局系统配置
   • pipeline: 流水线阶段配置
   • monitoring: 系统监控参数
   • persistence: 数据持久化设置
   • worker: 工作线程池配置
   • ratelimits: 速率限制设置
   • tasks: 提供商任务配置

高级任务配置

📋 如需完整的配置示例，请参考：

• examples/config-full.yaml - 包含所有可用选项的综合配置
• examples/config-simple.yaml - 适用于快速入门的基础配置

tasks 部分是配置的核心，定义了要搜索哪些提供商以及如何处理它们。有关完整的任务配置，请参阅上述基础配置示例。

主要配置选项

• name: 任务的唯一标识符
• provider_type: 决定验证方式（openai、openai_like、anthropic、gemini 等）
• api: 用于密钥验证的 API 端点配置
• patterns.key_pattern: 用于识别有效 API 密钥的正则表达式模式
• conditions: 用于查找潜在密钥的搜索查询
• stages: 启用或禁用特定的处理阶段
• extras.directory: 自定义结果输出目录

3. 运行

   python main.py                  # 使用默认配置
   python main.py -c custom.yaml   # 使用自定义配置
   python main.py --validate       # 验证配置
   python main.py --log-level DEBUG # 开启调试日志
   

目录结构

harvester/
├── config/           # 配置管理
│   ├── accessor.py   # 配置访问工具
│   ├── defaults.py   # 默认配置值
│   ├── loader.py     # 配置加载
│   ├── schemas.py    # 配置模式
│   ├── validator.py  # 配置验证
│   └── __init__.py   # 包初始化
├── constant/         # 系统常量
│   ├── monitoring.py # 监控常量
│   ├── runtime.py    # 运行时常量
│   ├── search.py     # 搜索常量
│   ├── system.py     # 系统常量
│   └── __init__.py   # 包初始化
├── core/             # 核心领域模型
│   ├── auth.py       # 认证
│   ├── enums.py      # 系统枚举
│   ├── exceptions.py # 自定义异常
│   ├── metrics.py    # 性能指标
│   ├── models.py     # 核心数据模型及任务定义
│   ├── types.py      # 核心类型定义
│   └── __init__.py   # 包初始化
├── examples/         # 配置示例
│   ├── config-full.yaml    # 完整配置模板
│   └── config-simple.yaml  # 基本配置模板
├── manager/          # 任务与资源管理
│   ├── base.py       # 基础管理类
│   ├── pipeline.py   # 管道管理
│   ├── queue.py      # 队列管理
│   ├── shutdown.py   # 关机协调
│   ├── status.py     # 状态管理
│   ├── task.py       # 任务管理
│   ├── worker.py     # 工作线程管理
│   └── __init__.py   # 包初始化
├── refine/           # 查询优化
│   ├── config.py     # Refine 配置
│   ├── engine.py     # 优化引擎
│   ├── generator.py  # 查询生成
│   ├── optimizer.py  # 查询优化
│   ├── parser.py     # 查询解析
│   ├── segment.py    # 模式分割
│   ├── splittability.py # 可拆分性分析
│   ├── strategies.py # 优化策略
│   ├── types.py      # Refine 类型定义
│   └── __init__.py   # 包初始化
├── search/           # 搜索引擎
│   ├── client.py     # 搜索客户端
│   ├── provider/     # 提供商实现
│   │   ├── anthropic.py    # Anthropic 提供商
│   │   ├── azure.py        # Azure OpenAI 提供商
│   │   ├── base.py         # 基础提供商类
│   │   ├── bedrock.py      # AWS Bedrock 提供商
│   │   ├── doubao.py       # ByteDance Doubao 提供商
│   │   ├── gemini.py       # Google Gemini 提供商
│   │   ├── gooeyai.py      # GooeyAI 提供商
│   │   ├── openai.py       # OpenAI 提供商
│   │   ├── openai_like.py  # 兼容 OpenAI 的提供商
│   │   ├── qianfan.py      # Baidu Qianfan 提供商
│   │   ├── registry.py     # 提供商注册表
│   │   ├── stabilityai.py  # Stability AI 提供商
│   │   ├── vertex.py       # Google Vertex AI 提供商
│   │   └── __init__.py     # 包初始化
│   └── __init__.py   # 包初始化
├── stage/            # 管道阶段
│   ├── base.py       # 基础阶段类
│   ├── definition.py # 阶段实现
│   ├── factory.py    # 阶段工厂
│   ├── registry.py   # 阶段注册表
│   ├── resolver.py   # 依赖项解析器
│   └── __init__.py   # 包初始化
├── state/            # 状态管理
│   ├── builder.py    # 状态构建器
│   ├── collector.py  # 状态收集
│   ├── display.py    # 显示引擎
│   ├── enums.py      # 状态枚举
│   ├── models.py     # 状态数据模型
│   ├── monitor.py    # 状态监控
│   ├── types.py      # 状态类型定义
│   └── __init__.py   # 包初始化
├── storage/          # 存储与持久化
│   ├── atomic.py     # 原子文件操作
│   ├── persistence.py # 结果持久化
│   ├── recovery.py   # 任务恢复
│   ├── shard.py      # NDJSON 分片管理
│   ├── snapshot.py   # 快照管理
│   └── __init__.py   # 包初始化
├── tools/            # 工具与实用程序
│   ├── agent.py      # 用户代理管理
│   ├── balancer.py   # 负载均衡
│   ├── coordinator.py # 资源协调
│   ├── credential.py # 凭证管理
│   ├── logger.py     # 日志系统
│   ├── patterns.py   # 模式匹配工具
│   ├── ratelimit.py  # 速率限制
│   ├── resources.py  # 资源池
│   ├── retry.py      # 重试框架
│   ├── utils.py      # 通用工具
│   └── __init__.py   # 包初始化
├── .dockerignore     # Docker 忽略规则
├── .gitignore        # Git 忽略规则
├── Dockerfile        # Docker 容器配置
├── entrypoint.sh     # Docker 入口脚本
├── LICENSE           # 许可证文件
├── main.py           # 入口点及应用核心
├── README.md         # 英文文档
├── README.zh-CN.md   # 中文文档
├── requirements.txt  # Python 依赖项
└── __init__.py       # 根包初始化

高级功能

1. 实时监控

   • 任务状态跟踪
   • 性能指标收集
   • 资源使用情况监控
   • 警报系统

2. 配置灵活性

   • 多提供商配置
   • 自定义搜索模式
   • 可调整的性能参数
   • 动态资源分配

3. 可扩展性

   • 插件式提供商
   • 自定义管道阶段
   • 可配置的监控系统
   • 灵活的恢复策略

故障排除

常见问题

1. 安装问题

# 问题：pip install 失败
# 解决方案：升级 pip 并使用虚拟环境
python -m pip install --upgrade pip
python -m venv venv

# Linux/macOS
source venv/bin/activate

# Windows
venv\Scripts\activate

pip install -r requirements.txt

2. 配置错误

# 问题：配置验证失败
# 解决方案：验证配置文件
python main.py --validate

# 问题：缺少配置文件
# 解决方案：从示例创建
cp examples/config-simple.yaml config.yaml

3. 速率限制问题

# 问题：API 请求过多
# 解决方案：在配置中调整速率限制
rate_limits:
  github_api:
    base_rate: 0.1  # 降低速率
    adaptive: true  # 启用自适应限制

4. 内存问题

# 问题：内存占用过高
# 解决方案：减少批处理大小和线程数
pipeline:
  threads:
    search: 1
    gather: 2  # 从默认值减少
persistence:
  batch_size: 25  # 从默认值 50 减少

5. 网络连接

# 问题：连接超时
# 解决方案：增加超时时间
api:
  timeout: 60  # 从默认值 30 增加
  retries: 5   # 增加重试次数

调试模式

# 启用调试日志记录
python main.py --log-level DEBUG

# 将调试输出保存到文件
python main.py --log-level DEBUG > debug.log 2>&1

安全考虑

凭证管理

• 切勿将凭证提交到版本控制系统
• 使用环境变量存储敏感配置
• 定期轮换凭证以降低暴露风险
• 为 API 密钥实施最小权限原则

数据保护

# 示例：安全的凭证配置
global:
  github_credentials:
    sessions:
      - "${GITHUB_SESSION_1}"  # 使用环境变量
      - "${GITHUB_SESSION_2}"
    tokens:
      - "${GITHUB_TOKEN_1}"

隐私考量

• 尊重 robots.txt 文件及网站的服务条款
• 实施速率限制以避免对目标服务造成过大压力
• 日志脱敏可自动从日志中移除敏感数据
• 数据保留策略应符合相关法律法规

合规指南

• 在生产环境中使用前审查法律要求
• 获取数据收集所需的必要许可
• 在必要时实施数据匿名化
• 记录数据处理活动以确保合规性

重要提示

1. 局限性

   • 遵守 GitHub API 的使用限制
   • 合理配置速率限制
   • 注意内存使用情况
   • 小心处理敏感数据

2. 最佳实践

   • 使用合适的线程数
   • 定期备份结果
   • 监控错误率
   • 及时处理告警

待办事项与路线图

🏗️ 核心架构改进

数据源抽象

• 抽象数据源接口：为所有数据源创建统一接口
  • 定义包含标准方法（search、gather、validate）的 DataSourceProvider 基类
  • 实现针对不同 API 格式（REST、GraphQL、WebSocket）的适配器模式
  • 添加用于数据源注册的配置模式
  • 支持动态加载和热插拔数据源

阶段系统增强

• 灵活的阶段定义：突破当前 4 阶段的限制
  • 创建 StageDefinition 配置格式（YAML/JSON）
  • 实现从配置文件中动态加载阶段
  • 增加阶段组合与条件执行功能
  • 支持用户自定义阶段工作流及 DAG 定制

处理器注册系统

• 可插拔的处理架构：用可配置处理器取代固定函数调用
  • 实施适用于各阶段的 HandlerRegistry
  • 创建具有标准化输入输出契约的 ProcessorInterface
  • 添加处理器发现机制（基于注解或配置驱动）
  • 支持请求/响应处理的中间件链

🌐 数据源集成

网络测绘平台

• FOFA 集成

  • 实现带有认证的 FOFA API 客户端
  • 添加针对 FOFA 的查询优化功能

• Shodan 集成

  • 支持从 Shodan 查询和提取数据

通用网络来源

• 通用网页爬虫
  • 构建可配置的网页抓取引擎
  • 增加对 JavaScript 渲染内容的支持（Selenium/Playwright）
  • 实现反机器人检测绕过机制
  • 创建内容提取规则引擎

🔧 框架增强

配置与扩展性

• 插件系统
  • 设计具备生命周期管理的插件架构
  • 创建插件市场及发现机制
  • 增加插件沙箱隔离与安全验证
  • 实现插件依赖关系解析

性能与可扩展性

• 分布式处理
  • 增加对分布式任务执行的支持（Celery/RQ）
  • 实现负载均衡的水平扩展
  • 创建集群管理和节点发现功能
  • 增加分布式状态同步机制

安全性

• 增强的安全特性
  • 实现凭证加密与安全存储
  • 为每个数据源制定速率限制策略

📊 监控与分析

高级监控

• 实时分析仪表盘
  • 构建基于 Web 的监控界面
  • 增加实时指标可视化功能
  • 实现告警与通知系统
  • 创建性能剖析与瓶颈分析功能

🚀 高级功能

API 与集成

• RESTful API 服务器
  • 构建全面的 REST API 以供外部集成
  • 实现支持实时通知的 Webhook 功能
  • 创建适用于主流编程语言的 SDK 库

贡献说明

欢迎贡献！在提交拉取请求之前，请确保：

1. 更新测试用例
2. 代码符合编码规范
3. 在必要时添加文档
4. 所有测试通过

贡献者优先领域

• 🔥 高优先级：数据源抽象及 FOFA/Shodan 集成
• 🔥 高优先级：阶段系统灵活性与处理器注册
• 🔥 高优先级：插件架构与扩展性框架
• 🔥 中优先级：性能优化与分布式处理
• 🔥 中优先级：基于 Web 的监控仪表盘

许可证

本项目采用知识共享署名-非商业性使用 4.0 国际许可协议（CC BY-NC 4.0）。详细信息请参阅 LICENSE 文件。

免责声明

⚠️ 重要提示

本项目仅用于教育和技术研究目的。用户在使用该软件时应谨慎并承担相应责任。

关键点：

• 本软件仅供学习、研究和教育用途
• 用户必须遵守其所在司法管辖区的所有适用法律和法规
• 用户有责任确保其使用行为符合任何第三方平台或 API 的服务条款
• 项目作者不建议、鼓励或认可使用本软件非法获取他人的 API 密钥或凭证
• 项目作者对因使用本软件而产生的任何争议、法律问题或损害概不负责
• 未经明确书面许可，严禁商业使用
• 用户应尊重他人的知识产权和隐私权

使用本软件即表示您已阅读、理解并同意上述条款。请自行承担使用风险。

联系方式

如在使用过程中有任何疑问或其他咨询，请通过 GitHub Issues 联系项目维护人员。

Harvester 快速上手指南

Harvester 是一个通用且自适应的数据采集框架，专为从 GitHub、网络空间测绘平台（如 FOFA、Shodan）及任意 Web 端点获取综合信息而设计。虽然当前实现以发现 AI 服务提供商密钥为例，但其架构具有高度可扩展性，支持多样化的数据采集场景。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux、macOS 或 Windows (推荐 WSL2)
• Python 版本：Python 3.8 或更高版本
• 依赖管理：pip 或 poetry
• 网络环境：能够访问 GitHub API 及目标数据源（若在国内使用，建议配置代理或使用加速镜像）

安装步骤

1. 克隆项目

从 GitHub 克隆仓库到本地：

git clone https://github.com/wzdnzd/ai-collector.git
cd ai-collector/harvester

提示：如果直接克隆速度较慢，可使用国内镜像加速：

git clone https://gitee.com/mirror/github-wzdnzd/ai-collector.git
cd ai-collector/harvester

2. 创建虚拟环境（推荐）

为了避免依赖冲突，建议创建独立的 Python 虚拟环境：

python -m venv venv
source venv/bin/activate  # Linux/macOS
# 或在 Windows 上执行: venv\Scripts\activate

3. 安装依赖

安装项目所需的 Python 包。如果在国内遇到下载慢的问题，推荐使用清华或阿里镜像源：

# 使用默认源
pip install -r requirements.txt

# 推荐使用清华镜像源（国内加速）
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

Harvester 主要通过命令行界面 (CLI) 进行操作。以下是最简单的使用示例，演示如何启动数据采集任务。

配置凭证（可选但推荐）

对于需要认证的数据源（如 GitHub API），建议先配置凭证。您可以编辑 config/ 目录下的配置文件，或通过环境变量设置：

export GITHUB_TOKEN="your_github_token_here"
# export FOFA_KEY="your_fofa_key_here"  # 未来支持

运行采集任务

使用 main.py 启动框架。以下命令将启动默认的采集流程（当前主要针对 GitHub 上的 AI 服务密钥发现）：

python main.py --target github --mode search

参数说明：

• --target: 指定数据源类型（当前支持 github，未来支持 fofa, shodan 等）。
• --mode: 指定运行模式（如 search 搜索, gather 收集, check 验证）。

查看结果

采集完成后，结果通常保存在 storage/ 或 results/ 目录下（具体路径取决于配置文件 config/ 中的设置）。您可以直接查看生成的日志文件或数据文件：

ls -l results/
cat results/latest_output.json

---

注：本工具仅供学习和研究使用，请严格遵守相关法律法规及各平台服务条款，切勿用于非法用途。