# GeneralCrawler

**Repository Path**: zkq_java/general-crawler

## Basic Information

- **Project Name**: GeneralCrawler
- **Description**: 通用网站数据爬虫
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-30
- **Last Updated**: 2026-03-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# GeneralCrawler - 通用网站数据爬虫系统

一款企业级的通用网站数据采集平台，提供可视化配置、多级爬取、定时任务、数据分析和监控告警等一站式解决方案。

## ✨ 特性

- 🎯 **可视化配置** - 无需编码，通过 Web 界面配置爬虫规则
- 🔗 **多级爬取** - 支持 2-5 级 cascading 数据采集，3 种数据合并策略
- 🌐 **双模式支持** - HTML 页面解析 + API 接口调用
- ⏰ **定时任务** - Cron 表达式调度，自动化数据采集
- 📊 **数据分析** - ECharts 可视化仪表盘，实时数据洞察
- 🔐 **用户权限** - JWT 认证，角色权限管理
- 🚀 **高性能** - FastAPI 异步框架，Celery 分布式任务队列
- 📦 **容器化** - Docker Compose 一键部署（10 个服务）
- 🎨 **动态渲染** - Playwright 集成，支持 JavaScript 动态页面、截图、自动滚动
- 🔍 **代理管理** - 批量检测、响应时间测量、匿名度识别、智能选择
- 💾 **导入导出** - JSON/CSV/Excel 三格式双向导入导出
- 📡 **实时推送** - WebSocket 日志推送，毫秒级延迟
- 🌺 **监控完善** - Flower + Grafana + Prometheus 全方位监控

## 🛠️ 技术栈

### 后端

- **框架**: Python FastAPI + Uvicorn
- **爬虫**: Scrapy + Playwright
- **数据库**: MySQL 8.0 + MongoDB 6.0 + Redis 7.0
- **任务队列**: Celery 5.x + Redis

### 前端

- **框架**: React 18 + Ant Design Pro 5 + TypeScript
- **可视化**: ECharts 5

### 运维

- **容器化**: Docker + Docker Compose
- **监控**: Prometheus + Grafana

## 🚀 快速开始

### 环境要求

- Docker 20.10+
- Docker Compose 2.0+
- Node.js 18+ (本地开发前端)
- Python 3.10+ (本地开发后端)

### 方式一：Docker 一键启动（推荐）

#### Windows 用户

直接双击运行 `start-docker.bat` 脚本。

#### Linux/Mac 用户

```bash
# 赋予执行权限
chmod +x start-docker.sh

# 一键启动（自动创建 .env 文件）
./start-docker.sh

# 或手动配置
cp .env.example .env
# 编辑 .env 文件，修改密码等配置
docker-compose up -d
```

**相关脚本**:

- `start-docker.sh` - Docker 一键启动
- `stop-docker.sh` - 停止 Docker 服务
- 详见 [SCRIPTS_GUIDE.md](./SCRIPTS_GUIDE.md)

### 方式二：本地开发模式

#### Linux/Mac 用户（推荐）

```bash
# 使用脚本一键启动开发环境
chmod +x start-dev.sh stop-dev.sh logs.sh
./start-dev.sh
```

脚本会自动：

- ✅ 检查 Docker、Python、Node.js 环境
- ✅ 可选启动数据库基础设施
- ✅ 后台启动 FastAPI 和 React
- ✅ 可选启动 Celery Worker
- ✅ 自动记录日志到文件

**相关脚本**:

- `start-dev.sh` - 启动开发环境
- `stop-dev.sh` - 停止开发服务
- `logs.sh` - 查看服务日志
- 详见 [SCRIPTS_GUIDE.md](./SCRIPTS_GUIDE.md)

#### Windows 用户

#### 1. 启动基础服务

```bash
docker-compose up -d mysql mongodb redis
```

#### 2. 启动后端

```bash
cd backend
pip install -r requirements.txt
uvicorn app.main:app --reload
```

#### 3. 启动前端

```bash
cd frontend
npm install
npm start
```

### 访问系统

- **前端界面**: http://localhost:3000
- **后端 API / Swagger 文档**: http://localhost:8000/docs
- **Flower 监控**: http://localhost:5555 (账号：flower_admin / 密码见.env)
- **Grafana 监控**: http://localhost:3001 (账号：admin / 密码见.env)
- **Prometheus**: http://localhost:9090
- **默认管理员账号**: `admin` / `admin123`（首次使用请注册）

## 📁 项目结构

```
GeneralCrawler/
├── backend/              # Python 后端 (FastAPI + Scrapy)
│   ├── app/
│   │   ├── api/         # API 路由 (v1 版本)
│   │   ├── models/      # SQLAlchemy 数据模型
│   │   ├── schemas/     # Pydantic 数据验证
│   │   ├── services/    # 业务逻辑层
│   │   ├── spiders/     # Scrapy 爬虫模块
│   │   └── main.py      # FastAPI 应用入口
│   └── requirements.txt # Python 依赖
├── frontend/             # React 前端 (Ant Design Pro)
│   └── src/
│       ├── pages/       # 页面组件
│       ├── components/  # 通用组件
│       ├── services/    # API 调用
│       └── utils/       # 工具函数
├── docker/               # Docker 配置
│   └── mysql/init.sql   # MySQL 初始化脚本
├── docker-compose.yml    # Docker Compose 编排 (10 个服务)
├── docs/                 # 📚 文档中心 (20+ 文档)
│   ├── README.md        # 文档索引
│   ├── 01-quick-start/  # 快速开始 (3 个文档)
│   ├── 02-feature-demo/ # 功能说明 (2 个文档)
│   ├── 03-project-summary/ # 项目总结 (10 个文档)
│   ├── 04-technical-docs/  # 技术文档 (2 个文档)
│   └── 05-specifications/  # 项目规范 (3 个文档)
└── .env.example          # 环境变量模板
```

## 📋 核心功能

### 1. 爬虫管理

- 创建 HTML 或 API 类型爬虫
- 可视化 XPath 配置
- 爬虫启动/暂停/删除
- 实时状态监控
- **动态页面渲染**（Playwright 集成，支持截图、自动滚动）⭐

### 2. 多级爬取

- 列表页→详情页级联采集
- 三种数据合并策略（合并/关联/嵌套）
- 可配置并发控制和延迟
- **支持 2-5 级 cascading 爬取** ⭐

### 3. 数据管理

- 数据分页查询
- **数据导入导出**（JSON/CSV/Excel 三格式双向支持）⭐
- 数据清洗规则配置
- **BloomFilter 去重** ⭐

### 4. 定时任务

- Cron 表达式调度
- 任务依赖关系配置
- 自动执行历史记录
- **Celery Beat 定时调度器** ⭐

### 5. 监控告警

- 系统资源监控（Prometheus + Grafana）
- 爬虫运行状态监控
- **Flower 实时监控界面** ⭐
- **WebSocket 日志实时推送** ⭐
- 异常自动告警通知

### 6. 代理管理 ⭐

- **批量 HTTP 检测**（响应时间、匿名度）
- 智能选择策略（轮询/随机/优先级）
- 自动清理失效代理

### 7. 分布式支持 ⭐

- Celery 多 Worker 部署
- 任务路由（crawler/monitor 队列）
- 跨机器水平扩展

### 8. 企业级特性 🏢

- **告警通知** - 邮件/钉钉/企业微信多渠道告警 ⭐
- **RBAC 权限** - 5 种角色 +30 项细粒度权限控制 ⭐
- **模板市场** - 6 种预定义爬虫模板快速启动 ⭐
- **K8s 部署** - Helm Chart + 自动扩缩容 + 监控 ⭐

## 🔧 开发指南

### 后端开发

```bash
cd backend
pip install -r requirements.txt
uvicorn app.main:app --reload
```

### 前端开发

```bash
cd frontend
npm install
npm start
```

### 运行测试

```bash
cd backend
pytest
```

## 📖 文档

### 📚 完整文档索引

**所有文档已整理到 [docs/](./docs/) 目录，按类别组织，包含 24+ 份文档**：

👉 **[docs/README.md](./docs/README.md)** - 文档中心索引（快速开始、功能说明、项目总结、技术文档、项目规范、脚本工具）

### 🎯 快速导航

#### 🚀 快速开始（3 个文档）

- **[docs/01-quick-start/QUICK_START.md](./docs/01-quick-start/QUICK_START.md)** ⭐⭐⭐ - **5 分钟快速启动** - Docker 一键部署
- **[docs/01-quick-start/QUICKSTART.md](./docs/01-quick-start/QUICKSTART.md)** ⭐⭐ - **简化版入门指南** - 快速上手
- **[docs/01-quick-start/DEPLOYMENT_GUIDE.md](./docs/01-quick-start/DEPLOYMENT_GUIDE.md)** ⭐⭐⭐ - **详细部署指南** - 开发/测试/生产环境

#### 🎯 功能说明（2 个文档）

- **[docs/02-feature-demo/FEATURE_DEMO.md](./docs/02-feature-demo/FEATURE_DEMO.md)** ⭐⭐ - **功能演示手册** - API 示例 + 前端界面导览
- **[docs/02-feature-demo/ENHANCEMENTS_SUMMARY.md](./docs/02-feature-demo/ENHANCEMENTS_SUMMARY.md)** ⭐⭐ - **企业增强功能** - 告警/RBAC/模板市场/K8s

#### 📊 项目总结（10 个文档）

- **[docs/03-project-summary/PROJECT_COMPLETION_SUMMARY.md](./docs/03-project-summary/PROJECT_COMPLETION_SUMMARY.md)** ⭐⭐⭐ - **项目完成总结** - 技术架构 + API 总览 + 交付清单
- **[docs/03-project-summary/FINAL_UPDATE_REPORT.md](./docs/03-project-summary/FINAL_UPDATE_REPORT.md)** ⭐ - **最终更新报告** - v2.0.0 版本交付
- **[docs/03-project-summary/FEATURE_COMPLETION_REPORT.md](./docs/03-project-summary/FEATURE_COMPLETION_REPORT.md)** ⭐ - **功能完成度报告** - 各模块完成度详解
- **[docs/03-project-summary/PROJECT_FINAL_UPDATE.md](./docs/03-project-summary/PROJECT_FINAL_UPDATE.md)** ⭐ - **项目最终更新** - 工具函数/验证器/去重服务

#### ⚡ 技术文档（2 个文档）

- **[docs/04-technical-docs/PERFORMANCE_OPTIMIZATION.md](./docs/04-technical-docs/PERFORMANCE_OPTIMIZATION.md)** ⭐⭐ - **性能优化指南** - 数据库/应用/前端全方位优化
- **[docs/04-technical-docs/KUBERNETES_DEPLOYMENT.md](./docs/04-technical-docs/KUBERNETES_DEPLOYMENT.md)** ⭐⭐ - **K8s 部署指南** - Helm Chart + 自动扩缩容

#### 📋 项目规范（3 个文档）

- **[docs/05-specifications/SPEC.md](./docs/05-specifications/SPEC.md)** ⭐⭐⭐ - **需求规格说明书** - 完整功能需求 + 技术架构 + API 设计
- **[docs/05-specifications/SPEC_MULTI_LEVEL_ADDENDUM.md](./docs/05-specifications/SPEC_MULTI_LEVEL_ADDENDUM.md)** ⭐⭐ - **多级爬虫补充说明** - 层级化爬虫系统详细设计
- **[docs/05-specifications/SPEC_UPDATE_SUMMARY.md](./docs/05-specifications/SPEC_UPDATE_SUMMARY.md)** ⭐ - **需求更新摘要** - 版本变更记录和功能演进

#### 🛠️ 脚本工具（4 个文档）

- **[docs/06-scripts-tools/SCRIPTS_GUIDE.md](./docs/06-scripts-tools/SCRIPTS_GUIDE.md)** ⭐⭐⭐ - **脚本使用详解** - Linux/Mac 所有 Shell 脚本的完整说明
- **[docs/06-scripts-tools/INSTALL_LINUX.md](./docs/06-scripts-tools/INSTALL_LINUX.md)** ⭐⭐⭐ - **Linux/Mac安装配置** - 系统要求/依赖安装/故障排查
- **[docs/06-scripts-tools/LINUX_SCRIPTS_SUMMARY.md](./docs/06-scripts-tools/LINUX_SCRIPTS_SUMMARY.md)** ⭐⭐ - **脚本功能报告** - 创建总结/功能对比/代码统计
- **[docs/06-scripts-tools/SECRET_KEY_GUIDE.md](./docs/06-scripts-tools/SECRET_KEY_GUIDE.md)** ⭐⭐ - **密钥配置指南** - SECRET_KEY 生成/配置/故障排查

### 📖 推荐阅读路径

**新用户**: docs/README.md → 01-quick-start/QUICK_START.md → 02-feature-demo/FEATURE_DEMO.md

**开发人员**: docs/README.md → 03-project-summary/PROJECT_COMPLETION_SUMMARY.md → 04-technical-docs/PERFORMANCE_OPTIMIZATION.md

**运维人员**: docs/README.md → 01-quick-start/DEPLOYMENT_GUIDE.md → 04-technical-docs/KUBERNETES_DEPLOYMENT.md

**项目管理者**: docs/README.md → 02-feature-demo/ENHANCEMENTS_SUMMARY.md → 03-project-summary/FINAL_UPDATE_REPORT.md

### 🔗 API 文档

- **[Swagger/OpenAPI](http://localhost:8000/docs)** - 交互式 API 文档（在线测试）
- **[Redoc](http://localhost:8000/redoc)** - 美观的 API 文档（只读）

### 🔥 常用链接速查

| 用途               | 链接                               | 说明               |
| ------------------ | ---------------------------------- | ------------------ |
| 🌐 **前端界面**    | http://localhost:3000              | Web 管理控制台     |
| 📡 **API 文档**    | http://localhost:8000/docs         | Swagger 交互式文档 |
| 🌺 **Flower 监控** | http://localhost:5555              | Celery 任务监控    |
| 📊 **Grafana**     | http://localhost:3001              | 系统监控仪表盘     |
| 📈 **Prometheus**  | http://localhost:9090              | 指标采集           |
| 📚 **完整文档**    | [docs/README.md](./docs/README.md) | 20+ 技术文档       |

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

### 如何贡献

1. Fork 本项目
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

### 开发环境搭建

详见 [docs/01-quick-start/DEPLOYMENT_GUIDE.md](./docs/01-quick-start/DEPLOYMENT_GUIDE.md)

## 📊 项目统计

| 指标                | 数值        |
| ------------------- | ----------- |
| 📄 **文档数量**     | 20+ 份      |
| 📝 **代码行数**     | ~15,000+    |
| 🔌 **API 端点**     | 60+ 个      |
| 🖼️ **前端页面**     | 9 个        |
| 🐳 **Docker 服务**  | 10 个       |
| 💾 **数据库表**     | 10+ (MySQL) |
| 📦 **MongoDB 集合** | 7 个        |
| ⚙️ **预定义模板**   | 6 个        |
| 👥 **预定义角色**   | 5 个        |
| 🔐 **权限项**       | 30 个       |

## 📄 许可证

Apache-2.0 License

## 📞 联系方式

- 项目 Issues: GitHub Issues
- 讨论区：GitHub Discussions

---

_Built with ❤️ using FastAPI + React_