kami_spider/README.md

Kami Spider

项目简介

Kami Spider 是一个基于 FastAPI 的分布式爬虫 Web 框架，支持日志系统、链路追踪、优雅关闭、分布式部署等特性，便于后续扩展代理池、Redis、MySQL 等模块。

主要特性

• 完善的日志系统（本地、控制台、可选 OTel 导出）
• Pydantic 数据校验与配置管理
• 支持 MySQL 和 Redis (可选启用)
• 爬虫管理与任务调度系统
• 基于 DDD 设计的爬虫架构，爬虫间彼此独立
• 异步并发爬取，支持大规模分布式爬虫
• Gunicorn 作为 Web 服务器，支持初步分布式
• 支持 Docker、Docker Compose、K8s、Helm 部署
• 健康检查和资源限制
• 优雅关闭与链路追踪
• 项目结构清晰，易于扩展

快速开始

1. 配置环境变量

从 .env.example 创建 .env 文件，并根据需要修改配置。

2. 安装依赖

pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

3. 本地运行

uvicorn app.main:app --reload

4. 使用 Gunicorn 启动

gunicorn app.main:app -k uvicorn.workers.UvicornWorker --workers 4

5. Docker 部署

docker build -t kami-spider .
docker run -p 8000:8000 kami-spider

6. Docker Compose 部署

docker-compose up -d

7. K8s/Helm 部署

详见 deploy/ 目录。

爬虫开发指南

爬虫架构

Kami Spider 采用基于 DDD (领域驱动设计) 的爬虫架构，主要组件包括：

1. Spider 基类：定义爬虫的基本接口和行为
2. HttpSpider：基于 HTTP 协议的爬虫实现
3. Spider Manager：爬虫管理器，负责爬虫的注册、创建、启动和管理
4. API 接口：提供 RESTful API 接口，用于管理爬虫任务

创建自定义爬虫

可以通过继承 HttpSpider 基类来创建自定义爬虫，例如：

from app.spiders.base.http import HttpSpider, HttpSpiderRequest, HttpSpiderResponse
from typing import List, Dict, Any, Optional, Union

class MySpider(HttpSpider[Dict[str, Any]]):
    def __init__(self, name: str = "MySpider", **kwargs):
        super().__init__(name, **kwargs)
        self.start_urls = ["https://example.com"]
        
    async def parse(self, response: HttpSpiderResponse) -> Union[List[HttpSpiderRequest], List[Dict[str, Any]], None]:
        # 解析响应并返回数据项或新的请求
        pass
        
    async def process_item(self, item: Dict[str, Any]) -> Optional[Dict[str, Any]]:
        # 处理数据项
        return item

启动爬虫任务

可以通过 API 接口启动爬虫任务：

curl -X POST "http://localhost:8000/spider/task" \
     -H "Content-Type: application/json" \
     -d '{"spider_name": "SimpleSpider", "params": {"max_depth": 3}}'

配置管理

项目使用 Pydantic Settings 和环境变量进行配置管理。主要配置模块:

1. 日志配置: 控制台输出、文件输出、OTel 导出
2. OTel 配置: 控制是否启用链路追踪及其配置
3. 数据库配置: MySQL 连接配置
4. Redis 配置: Redis 连接配置，支持 Sentinel 高可用
5. 分布式配置: 支持外部配置中心(可扩展)

健康检查

系统提供 /health 接口，用于检查服务状态：

• Docker 配置了 HEALTHCHECK
• K8s 和 Helm 配置了 livenessProbe 和 readinessProbe

目录结构

• app/ # 主应用代码
• app/api/ # 路由与接口
• app/core/ # 核心功能（日志、配置、追踪等）
• app/db/ # 数据库连接（MySQL、Redis）
• app/models/ # Pydantic 数据模型
• app/spiders/ # 爬虫实现
  • base/ # 爬虫基类和接口
  • examples/ # 爬虫示例
  • manager.py # 爬虫管理器
• app/utils/ # 工具函数
• tests/ # 测试用例
• deploy/ # 部署相关（Dockerfile、K8s、Helm）

代码规范

• 遵循 PEP8
• 注释齐全

未来规划

• 代理池模块
• 更多分布式能力