# scpun-crawl

**Repository Path**: foolcn/scpun-crawl

## Basic Information

- **Project Name**: scpun-crawl
- **Description**: 通用爬虫管理平台，基于 Spring Boot + Vue 3，支持可视化管道编排、插件扩展、定时调度和数据管理。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 4
- **Created**: 2026-04-08
- **Last Updated**: 2026-04-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 黑蜘蛛（scpun-crawl）

> **黑蜘蛛** — 通用爬虫管理平台，基于 Spring Boot + Vue 3，支持可视化管道编排、插件扩展、定时调度和数据管理。
<center>

[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
[![Java](https://img.shields.io/badge/Java-17-orange.svg)](https://openjdk.org/projects/jdk/17/)
[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.5-green.svg)](https://spring.io/projects/spring-boot)
[![Vue](https://img.shields.io/badge/Vue-3.5-brightgreen.svg)](https://gitee.com/snove/scpun-crawl-web)

</center>
---

## 仓库

本项目分为前后端两个独立仓库：

| 仓库 | 地址 | 说明 |
|------|------|------|
| 后端 | [gitee.com/snove/scpun-crawl](https://gitee.com/snove/scpun-crawl) | Spring Boot 多模块，爬虫引擎 + API |
| 前端 | [gitee.com/snove/scpun-crawl-web](https://gitee.com/snove/scpun-crawl-web) | Vue 3 + Naive UI，可视化管理界面 |

[![后端仓库](https://gitee.com/snove/scpun-crawl/widgets/widget_card.svg?colors=4183c4,ffffff,ffffff,e3e9ed,666666,9b9b9b)](https://gitee.com/snove/scpun-crawl)

[![前端仓库](https://gitee.com/snove/scpun-crawl-web/widgets/widget_card.svg?colors=4183c4,ffffff,ffffff,e3e9ed,666666,9b9b9b)](https://gitee.com/snove/scpun-crawl-web)

## 界面预览

<table>
  <tr>
    <td align="center"><img src="images/login.png" alt="登录页" /><br/><sub>登录页</sub></td>
    <td align="center"><img src="images/dashboard.png" alt="仪表盘" /><br/><sub>仪表盘</sub></td>
    <td align="center"><img src="images/sites.png" alt="站点管理" /><br/><sub>站点管理</sub></td>
  </tr>
  <tr>
    <td align="center"><img src="images/pipelineEditor.png" alt="管道编排" /><br/><sub>管道编排</sub></td>
    <td align="center"><img src="images/pipelineTemplate.png" alt="管道模板" /><br/><sub>管道模板</sub></td>
    <td align="center"><img src="images/task.png" alt="爬虫任务" /><br/><sub>爬虫任务</sub></td>
  </tr>
  <tr>
    <td align="center"><img src="images/schedule.png" alt="定时调度" /><br/><sub>定时调度</sub></td>
    <td align="center"><img src="images/dataSchema.png" alt="数据模式" /><br/><sub>数据模式</sub></td>
    <td align="center"><img src="images/script.png" alt="脚本节点" /><br/><sub>脚本节点</sub></td>
  </tr>
  <tr>
    <td align="center"><img src="images/plugin.png" alt="插件管理" /><br/><sub>插件管理</sub></td>
    <td align="center"><img src="images/proxy.png" alt="代理池" /><br/><sub>代理池</sub></td>
    <td align="center"><img src="images/rolePermission.png" alt="角色权限" /><br/><sub>角色权限</sub></td>
  </tr>
  <tr>
    <td align="center"><img src="images/systemParams.png" alt="系统参数" /><br/><sub>系统参数</sub></td>
    <td></td>
    <td></td>
  </tr>
</table>

---

## 功能特性

- **可视化管道编排** — 拖拽式节点配置，支持 HTML / JSON API / 动态渲染 / 两步提取四种爬虫类型
- **插件系统** — 上传 JAR 包即可扩展节点，热加载无需重启
- **脚本节点** — 内置 Groovy / Aviator 脚本引擎，无需打包插件即可自定义逻辑
- **定时调度** — 基于 Quartz 的 CRON 调度，支持暂停 / 恢复 / 手动触发，完整执行日志
- **数据管理** — 动态字段定义（DataSchema），支持 CSV / Excel / JSON 导出
- **代理池** — 代理健康检查、智能调度、批量导入
- **RBAC 权限** — 用户 / 角色 / 权限三层模型，数据范围隔离，RSA 加密登录
- **管道模板** — 可复用的管道配置模板市场

---

## 快速开始

### 方式一：Docker Compose（推荐）

```bash
# 1. 克隆后端（含 docker-compose.yml）
git clone https://gitee.com/snove/scpun-crawl.git
cd scpun-crawl

# 2. 配置环境变量
cp .env.example .env
# 编辑 .env，修改数据库密码和 JWT 密钥

# 3. 构建后端镜像
mvn package -DskipTests
docker build -t scpun-crawl-backend:1.0.0 .

# 4. 克隆前端并构建镜像
git clone https://gitee.com/snove/scpun-crawl-web.git
cd scpun-crawl-web && pnpm install && pnpm build
docker build -t scpun-crawl-frontend:1.0.0 .
cd ..

# 5. 启动所有服务
docker-compose up -d
```

访问地址：
- 前端：http://localhost
- Swagger UI：http://localhost:8080/swagger-ui.html
- 默认账号：`admin` / `Admin@123456`

### 方式二：本地开发

**环境要求：** Java 17+ · Maven 3.8+ · Node.js 18+ / pnpm · MySQL 8.0+ · Redis 7+

```bash
# 后端
git clone https://gitee.com/snove/scpun-crawl.git
cd scpun-crawl
cp scpun-crawl-app/src/main/resources/application-dev.yml \
   scpun-crawl-app/src/main/resources/application-local.yml
# 编辑 application-local.yml，填入数据库连接信息
mvn spring-boot:run -pl scpun-crawl-app -Dspring-boot.run.profiles=local

# 前端（新终端）
git clone https://gitee.com/snove/scpun-crawl-web.git
cd scpun-crawl-web && pnpm install && pnpm dev
# 访问 http://localhost:5173
```

---

## 项目结构

```
scpun-crawl/                    # 后端（本仓库）
├── scpun-crawl-plugin-api/     # 插件开发 SDK
├── scpun-crawl-common/         # 公共实体、Repository
├── scpun-crawl-core/           # 爬虫引擎、管道执行器、内置节点
└── scpun-crawl-app/            # 应用入口、Controller、Service

scpun-crawl-web/                # 前端（独立仓库）
├── src/api/                    # API 请求层
├── src/views/                  # 页面视图（17 个页面）
├── src/components/pipeline/    # 可视化管道编排器
└── src/stores/                 # Pinia 状态管理
```

---

## 内置节点

| 类型 | 节点 ID | 说明 |
|------|---------|------|
| 下载 | `http-downloader` | HTTP/HTTPS，支持代理、重试、自定义 Header |
| 下载 | `selenium-downloader` | Selenium 浏览器，支持 JS 渲染 |
| 提取 | `css-extractor` | CSS/XPath 选择器，配置驱动，支持翻页 |
| 提取 | `json-extractor` | JSONPath 提取，支持 JSON API 翻页 |
| 提取 | `two-step-extractor` | 列表页 → 详情页两步提取 |
| 提取 | `script-extractor` | Groovy 脚本自定义提取 |
| 转换 | `field-cleaner` | 去空格 / HTML 标签 / 日期格式化 |
| 转换 | `field-mapper` | 字段重命名映射 |
| 过滤 | `url-dedup-filter` | URL 去重 |
| 过滤 | `field-validator` | 必填字段校验 |
| 过滤 | `expr-filter` | Aviator 表达式过滤 |
| 输出 | `db-output` | 写入数据库 |
| 输出 | `script-output` | Groovy 脚本自定义输出 |
| 事件 | `email-notify` | 邮件通知 |
| 事件 | `alert-notify` | 告警推送 |

---

## 开发插件

引入 SDK，实现 `PipelineNode` 接口，打包 JAR 后在管理界面上传安装：

```xml
<dependency>
    <groupId>com.scpun.crawl</groupId>
    <artifactId>scpun-crawl-plugin-api</artifactId>
    <version>1.0.0</version>
</dependency>
```

```java
public class MyExtractorNode implements ExtractorNode {
    @Override
    public String getNodeId() { return "my-extractor"; }

    @Override
    public void extract(PipelineContext ctx) {
        CrawlRecord record = new CrawlRecord();
        record.setField("title", "提取的标题");
        ctx.addRecord(record);
    }
}
```

---

## 关键配置

生产环境必须通过环境变量设置：

| 变量 | 说明 |
|------|------|
| `DB_URL` | 数据库连接 URL |
| `DB_USERNAME` / `DB_PASSWORD` | 数据库账号 |
| `REDIS_HOST` / `REDIS_PASSWORD` | Redis 连接 |
| `JWT_SECRET` | JWT 签名密钥（≥ 32 位随机字符串） |
| `PLUGIN_DIR` | 插件存储目录（默认 `/opt/scpun-crawl/plugins`） |

---

## 运行测试

```bash
# 后端（H2 内存数据库，无需外部依赖，64 个测试用例）
mvn test -pl scpun-crawl-app -Dspring.profiles.active=test
```

---

## 技术栈

**后端：** Spring Boot 3.5 · Spring Security · Spring Data JPA · Quartz · WebMagic · Groovy · Aviator · MySQL · Redis

**前端：** Vue 3 · TypeScript · Naive UI · Pinia · Vue Router · Axios · ECharts · Vue Flow

---

## License

[Apache License 2.0](LICENSE) © 2026 scpun-crawl contributors

---

## 免责声明

本项目仅供学习、研究和合法的数据采集场景使用。使用本项目前，请确保：

1. **遵守目标网站的服务条款**（Terms of Service）和 `robots.txt` 协议
2. **不得用于**爬取涉及个人隐私、商业机密、受版权保护的内容
3. **不得用于**对目标网站发起高频请求，造成服务器负载异常（DDoS）
4. **不得用于**任何违反《中华人民共和国网络安全法》《数据安全法》《个人信息保护法》及其他适用法律法规的行为
5. 爬取的数据仅限合法授权范围内使用，**不得二次销售或用于商业牟利**

**使用本项目产生的一切法律责任由使用者自行承担，项目作者不承担任何连带责任。**

> 如果你不确定某个爬取行为是否合法，请在行动前咨询法律专业人士。