zkr/ocups-kafka
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Revert "rabbitmq"

Browse Source 
This reverts commit 0976909cc8.
This commit is contained in:
李顺东
2026-01-15 22:08:12 +08:00
parent 0976909cc8
commit 1a5d14e0e7
14 changed files with 665 additions and 419 deletions
Download Patch File Download Diff File Expand all files Collapse all files

555
docs/技术方案.md
View File

@@ -3,13 +3,12 @@
## 1. 项目概述
### 1.1 需求背景
从八爪鱼API采集招聘数据，筛选近7天发布的数据，通过RabbitMQ消息队列提供数据消费接口，支持消息级别TTL自动过期。
从八爪鱼API采集招聘数据，筛选近7天发布的数据，通过内置Kafka服务提供消息队列，供外部系统消费。
### 1.2 核心功能
- 增量采集八爪鱼API招聘数据（从后往前采集，最新数据优先）
- 增量采集八爪鱼API招聘数据
- 日期过滤（发布日期 + 采集时间均在7天内）
- RabbitMQ消息队列（支持消息TTL，7天自动过期）
- 容器启动自动开始采集
- 内置Kafka服务
- 提供REST API消费接口
---
@@ -23,18 +22,16 @@
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │
│ │ 八爪鱼API │───▶│ 采集服务 │───▶│ 日期过滤器 │ │
│ │ (数据源) │ │ (从后往前) │ │ (7天内数据) │ │
│ │ (数据源) │ │ (增量采集) │ │ (7天内数据) │ │
│ └──────────────┘ └──────────────┘ └────────┬─────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ RabbitMQ 服务 │ │
│ │ ┌─────────────────────────────────────────────────────┐ │ │
│ │ │ Queue: job_data │ │ │
│ │ │ - 消息TTL: 7天 (604800000ms) │ │ │
│ │ │ - 过期消息自动删除 │ │ │
│ │ │ - 持久化存储 │ │ │
│ │ └─────────────────────────────────────────────────────┘ │ │
│ │ 内置 Kafka 服务 │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐ │ │
│ │ │ Zookeeper │ │ Broker │ │ Topic:job_data │ │ │
│ │ │ (Docker) │ │ (Docker) │ │ │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────────┘ │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
@@ -55,13 +52,14 @@
| 组件 | 技术方案 | 版本 | 说明 |
|------|---------|------|------|
| 运行环境 | Python | 3.11+ | 主开发语言 |
| 运行环境 | Python | 3.10+ | 主开发语言 |
| HTTP客户端 | httpx | 0.27+ | 异步HTTP请求 |
| 消息队列 | RabbitMQ | 3.12+ | 支持消息级别TTL |
| MQ客户端 | pika | 1.3+ | Python RabbitMQ SDK |
| 消息队列 | Kafka | 3.6+ | Docker部署 |
| Kafka客户端 | kafka-python | 2.0+ | Python Kafka SDK |
| API框架 | FastAPI | 0.109+ | REST接口 |
| 容器编排 | Docker Compose | 2.0+ | 服务部署 |
| 数据存储 | SQLite | 内置 | 存储采集进度 |
| 容器编排 | Docker Compose | 2.0+ | Kafka/Zookeeper部署 |
| 任务调度 | APScheduler | 3.10+ | 定时增量采集 |
| 数据存储 | SQLite | 内置 | 存储采集进度(offset) |
---
@@ -86,42 +84,36 @@ job_crawler/
│ │ ├── __init__.py
│ │ ├── api_client.py # 八爪鱼API客户端
│ │ ├── crawler.py # 采集核心逻辑
│ │ ├── rabbitmq_service.py # RabbitMQ服务
│ │ ├── kafka_service.py # Kafka服务
│ │ └── progress_store.py # 进度存储
│ ├── utils/ # 工具函数
│ │ ├── __init__.py
│ │ └── date_parser.py # 日期解析
│ ├── __init__.py
│ └── main.py # 应用入口
├── config/ # 配置文件
│ ├── config.yml # 运行配置
│ └── config.yml.docker # Docker配置模板
├── docker-compose.yml # 容器编排
├── docker-compose.yml # 容器编排（含Kafka+App）
├── Dockerfile # 应用镜像构建
├── deploy.sh # 部署脚本(Linux)
├── deploy.bat # 部署脚本(Windows)
├── requirements.txt # Python依赖
└── README.md # 使用说明
├── .env.example # 配置模板
├── .dockerignore # Docker忽略文件
└── README.md # 使用说明
```
---
## 5. 核心模块设计
### 5.1 增量采集模块
#### 采集策略（从后往前）
#### 采集策略
```python
# 增量采集流程
1. 获取数据总数 total
2. 读取上次采集的起始位置 last_start_offset
3. 计算本次采集范围:
- start_offset = total - batch_size (从最新数据开始)
- end_offset = last_start_offset (截止到上次位置)
4. 循环采集: offset 从 start_offset 递减到 end_offset
5. 每批数据过滤后立即发送到RabbitMQ
6. 采集完成后保存 last_start_offset = 本次起始位置
1. 读取上次采集的offset（首次为0）
2. 调用API: GET /data/all?taskId=xxx&offset={offset}&size=100
3. 解析返回数据，过滤近7天数据
4. 推送到Kafka
5. 更新offset = offset + size
6. 循环直到 offset >= total
```
#### 进度持久化
@@ -129,12 +121,9 @@ job_crawler/
```sql
CREATE TABLE crawl_progress (
task_id TEXT PRIMARY KEY,
last_start_offset INTEGER, -- 上次采集的起始位置
current_offset INTEGER,
total INTEGER,
last_update TIMESTAMP,
status TEXT,
filtered_count INTEGER,
produced_count INTEGER
last_update TIMESTAMP
);
```
@@ -150,58 +139,59 @@ CREATE TABLE crawl_progress (
#### 过滤逻辑
```python
def is_within_days(aae397: str, collect_time: str, days: int = 7) -> bool:
def is_within_7_days(aae397: str, collect_time: str) -> bool:
"""
判断数据是否在指定天数内
条件：发布日期 AND 采集时间 都在N天内
判断数据是否在近7天内
条件：发布日期 AND 采集时间 都在7天内
"""
today = datetime.now().date()
cutoff_date = today - timedelta(days=days)
seven_days_ago = today - timedelta(days=7)
publish_date = parse_aae397(aae397)
collect_date = parse_collect_time(collect_time)
publish_date = parse_aae397(aae397) # 解析发布日期
collect_date = parse_collect_time(collect_time) # 解析采集时间
return publish_date >= cutoff_date and collect_date >= cutoff_date
return publish_date >= seven_days_ago and collect_date >= seven_days_ago
```
### 5.3 RabbitMQ服务模块
### 5.3 Kafka服务模块
#### 消息TTL机制
```python
# 队列声明时设置消息TTL
channel.queue_declare(
queue='job_data',
durable=True,
arguments={
'x-message-ttl': 604800000 # 7天(毫秒)
}
)
#### Docker Compose配置
```yaml
version: '3.8'
services:
zookeeper:
image: confluentinc/cp-zookeeper:7.5.0
ports:
- "2181:2181"
environment:
ZOOKEEPER_CLIENT_PORT: 2181
# 发送消息时也设置TTL（双重保障）
channel.basic_publish(
exchange='',
routing_key='job_data',
body=message,
properties=pika.BasicProperties(
delivery_mode=2, # 持久化
expiration='604800000' # 7天
)
)
kafka:
image: confluentinc/cp-kafka:7.5.0
ports:
- "9092:9092"
environment:
KAFKA_BROKER_ID: 1
KAFKA_ZOOKEEPER_CONNECT: zookeeper:2181
KAFKA_ADVERTISED_LISTENERS: PLAINTEXT://localhost:9092
KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1
depends_on:
- zookeeper
```
#### 优势
- 消息级别TTL，精确控制每条消息的过期时间
- 过期消息自动删除，无需手动清理
- 队列中始终保持最近7天的有效数据
#### Topic设计
- Topic名称: `job_data`
- 分区数: 3
- 副本数: 1
- 消息格式: JSON
### 5.4 REST API接口
| 接口 | 方法 | 说明 |
|------|------|------|
| `/consume` | GET | 消费队列数据，支持batch_size参数 |
| `/queue/size` | GET | 获取队列消息数量 |
| `/consume` | GET | 消费Kafka数据，支持batch_size参数 |
| `/consume/stream` | GET | SSE流式消费 |
| `/status` | GET | 查看采集进度和状态 |
| `/tasks` | GET | 获取任务列表 |
| `/crawl/start` | POST | 手动触发采集任务 |
| `/crawl/stop` | POST | 停止采集任务 |
@@ -217,17 +207,13 @@ GET /consume?batch_size=10
"code": 0,
"data": [
{
"_id": "uuid",
"_task_id": "00f3b445-...",
"_crawl_time": "2026-01-15T10:30:00",
"Std_class": "机动车司机/驾驶",
"aca112": "保底1万+五险+港内A2驾驶员",
"AAB004": "青岛唐盛物流有限公司",
"acb241": "1-1.5万",
"aab302": "青岛黄岛区",
"aae397": "1月13日",
"Collect_time": "2026-01-15",
...
"job_title": "机动车司机/驾驶",
"company": "青岛唐盛物流有限公司",
"salary": "1-1.5万",
"location": "青岛黄岛区",
"publish_date": "2026-01-13",
"collect_time": "2026-01-15",
"url": "https://www.zhaopin.com/..."
}
],
"count": 10
@@ -239,20 +225,13 @@ GET /consume?batch_size=10
{
"code": 0,
"data": {
"tasks": [
{
"task_id": "00f3b445-...",
"task_name": "青岛招聘数据",
"total": 270000,
"last_start_offset": 269900,
"status": "completed",
"filtered_count": 15000,
"produced_count": 15000,
"is_running": false
}
],
"queue_size": 12345,
"running_count": 0
"task_id": "00f3b445-d8ec-44e8-88b2-4b971a228b1e",
"total": 257449,
"current_offset": 156700,
"progress": "60.87%",
"kafka_lag": 1234,
"status": "running",
"last_update": "2026-01-15T10:30:00"
}
}
```
@@ -261,47 +240,113 @@ GET /consume?batch_size=10
## 6. 数据模型
### 6.1 原始数据保留
数据采集后保留原始字段名，仅添加元数据：
### 6.1 原始数据字段映射
| 字段 | 说明 |
|------|------|
| _id | 唯一标识(UUID) |
| _task_id | 任务ID |
| _crawl_time | 入库时间 |
| 其他字段 | 保留原始API返回的所有字段 |
| 原始字段 | 含义 | 输出字段 |
|---------|------|---------|
| Std_class | 职位分类 | job_category |
| aca112 | 职位名称 | job_title |
| AAB004 | 公司名称 | company |
| acb241 | 薪资范围 | salary |
| aab302 | 工作地点 | location |
| aae397 | 发布日期 | publish_date |
| Collect_time | 采集时间 | collect_time |
| ACE760 | 职位链接 | url |
| acb22a | 职位描述 | description |
| Experience | 经验要求 | experience |
| aac011 | 学历要求 | education |
### 6.2 RabbitMQ消息格式
### 6.2 Kafka消息格式
```json
{
"_id": "uuid",
"_task_id": "00f3b445-d8ec-44e8-88b2-4b971a228b1e",
"_crawl_time": "2026-01-15T10:30:00",
"Std_class": "机动车司机/驾驶",
"aca112": "保底1万+五险+港内A2驾驶员",
"AAB004": "青岛唐盛物流有限公司",
"AAB019": "民营",
"acb241": "1-1.5万",
"aab302": "青岛黄岛区",
"AAE006": "青岛市黄岛区...",
"aae397": "1月13日",
"Collect_time": "2026-01-15",
"ACE760": "https://www.zhaopin.com/...",
"acb22a": "岗位职责...",
"Experience": "5-10年",
"aac011": "学历不限",
"acb240": "1人",
"AAB022": "交通/运输/物流",
"Num_employers": "20-99人",
"AAE004": "张先生/HR",
"AAB092": "公司简介..."
"id": "uuid",
"job_category": "机动车司机/驾驶",
"job_title": "保底1万+五险+港内A2驾驶员",
"company": "青岛唐盛物流有限公司",
"salary": "1-1.5万",
"location": "青岛黄岛区",
"publish_date": "2026-01-13",
"collect_time": "2026-01-15",
"url": "https://www.zhaopin.com/...",
"description": "...",
"experience": "5-10年",
"education": "学历不限",
"crawl_time": "2026-01-15T10:30:00"
}
```
---
## 7. 部署流程
### 7.1 Docker Compose 一键部署（推荐）
```bash
# 1. 配置环境变量
cd job_crawler
cp .env.example .env
# 编辑 .env 填入 API_USERNAME 和 API_PASSWORD
# 2. 启动所有服务（Zookeeper + Kafka + App）
docker-compose up -d
# 3. 查看日志
docker-compose logs -f app
# 4. 停止服务
docker-compose down
```
### 7.2 单独构建镜像
```bash
# 构建镜像
docker build -t job-crawler:latest .
# 推送到私有仓库（可选）
docker tag job-crawler:latest your-registry/job-crawler:latest
docker push your-registry/job-crawler:latest
```
### 7.3 Kubernetes 部署（可选）
```yaml
# 示例 Deployment
apiVersion: apps/v1
kind: Deployment
metadata:
name: job-crawler
spec:
replicas: 1
selector:
matchLabels:
app: job-crawler
template:
spec:
containers:
- name: job-crawler
image: job-crawler:latest
ports:
- containerPort: 8000
env:
- name: KAFKA_BOOTSTRAP_SERVERS
value: "kafka:9092"
envFrom:
- secretRef:
name: job-crawler-secrets
```
### 7.4 服务端口
| 服务 | 端口 | 说明 |
|------|------|------|
| FastAPI | 8000 | HTTP API |
| Kafka | 9092 | 外部访问 |
| Kafka | 29092 | 容器内部访问 |
| Zookeeper | 2181 | Kafka协调 |
---
## 7. 配置说明
## 8. 配置说明
### 配置文件 `config/config.yml`
@@ -315,124 +360,133 @@ app:
# 八爪鱼API配置
api:
base_url: https://openapi.bazhuayu.com
task_id: 00f3b445-d8ec-44e8-88b2-4b971a228b1e
username: "your_username"
password: "your_password"
batch_size: 100
# 多任务配置
tasks:
- id: "00f3b445-d8ec-44e8-88b2-4b971a228b1e"
name: "青岛招聘数据"
enabled: true
- id: "task-id-2"
name: "任务2"
enabled: false
# RabbitMQ配置
rabbitmq:
host: rabbitmq # Docker内部服务名
port: 5672
username: guest
password: guest
queue: job_data
message_ttl: 604800000 # 消息过期时间：7天(毫秒)
# Kafka配置
kafka:
bootstrap_servers: kafka:29092 # Docker内部网络
topic: job_data
consumer_group: job_consumer_group
# 采集配置
crawler:
filter_days: 7 # 数据有效期（天）
max_expired_batches: 3 # 连续过期批次阈值
max_workers: 5 # 最大并行任务数
auto_start: true # 容器启动时自动开始采集
interval: 300 # 采集间隔(秒)
filter_days: 7 # 过滤天数
# 数据库配置
database:
path: data/crawl_progress.db
path: /app/data/crawl_progress.db
```
### 配置加载优先级
1. 环境变量 `CONFIG_PATH` 指定配置文件路径
2. 默认路径 `config/config.yml`
### Docker挂载
```yaml
# docker-compose.yml
volumes:
- ./config:/app/config:ro # 配置文件（只读）
- app_data:/app/data # 数据持久化
```
---
## 8. 部署流程
### 8.1 Docker Compose 一键部署
```bash
# 1. 配置
cd job_crawler
cp config/config.yml.docker config/config.yml
# 编辑 config/config.yml 填入账号密码
# 2. 构建镜像
./deploy.sh build
# 3. 启动服务
./deploy.sh up
# 4. 查看日志
./deploy.sh logs
# 5. 查看状态
./deploy.sh status
```
### 8.2 部署脚本命令
| 命令 | 说明 |
|------|------|
| `./deploy.sh build` | 构建镜像 |
| `./deploy.sh up` | 启动服务 |
| `./deploy.sh down` | 停止服务 |
| `./deploy.sh restart` | 重启应用 |
| `./deploy.sh logs` | 查看应用日志 |
| `./deploy.sh status` | 查看服务状态 |
| `./deploy.sh reset` | 清理数据卷并重启 |
### 8.3 服务端口
| 服务 | 端口 | 说明 |
|------|------|------|
| FastAPI | 8000 | HTTP API |
| RabbitMQ | 5672 | AMQP协议 |
| RabbitMQ | 15672 | 管理界面 |
### 8.4 访问地址
- API文档: http://localhost:8000/docs
- RabbitMQ管理界面: http://localhost:15672 (guest/guest)
---
## 9. 数据流向
```
八爪鱼API → 采集服务(过滤7天内数据) → RabbitMQ(TTL=7天) → 第三方消费
↓
过期自动删除
```
---
## 10. Token自动刷新机制
系统实现了Token自动管理：
1. 首次请求时自动获取Token
2. Token缓存在内存中
3. 请求前检查Token有效期（提前5分钟刷新）
4. 遇到401错误自动重新获取Token
---
## 11. 异常处理
## 9. 异常处理
| 异常场景 | 处理策略 |
|---------|---------|
| API请求失败 | 重试3次，指数退避 |
| Token过期 | 自动刷新Token |
| RabbitMQ连接失败 | 自动重连 |
| Token过期 | 返回错误，需手动更新 |
| Kafka连接失败 | 重试连接，数据暂存本地 |
| 日期解析失败 | 记录日志，跳过该条数据 |
---
## 12. 快速启动
## 10. 监控指标
- 采集进度百分比
- Kafka消息堆积量(lag)
- 每分钟采集条数
- 过滤后有效数据比例
- API响应时间
---
## 11. 后续扩展
1. **多任务支持**: 支持配置多个taskId并行采集
2. **数据去重**: 基于职位URL去重
3. **告警通知**: 采集异常时发送通知
4. **Web管理界面**: 可视化监控采集状态
---
## 12. Docker 镜像构建
### Dockerfile 说明
```dockerfile
FROM python:3.11-slim
WORKDIR /app
# 安装系统依赖
RUN apt-get update && apt-get install -y --no-install-recommends gcc
# 安装Python依赖
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
# 复制应用代码
COPY app/ ./app/
# 创建数据目录
RUN mkdir -p /app/data
# 环境变量
ENV PYTHONPATH=/app
ENV PYTHONUNBUFFERED=1
EXPOSE 8000
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
```
### 构建命令
```bash
# 构建
docker build -t job-crawler:latest .
# 运行测试
docker run --rm -p 8000:8000 \
-e API_USERNAME=xxx \
-e API_PASSWORD=xxx \
-e KAFKA_BOOTSTRAP_SERVERS=host.docker.internal:9092 \
job-crawler:latest
```
---
## 13. 代码分层说明
| 层级 | 目录 | 职责 |
|------|------|------|
| API层 | `app/api/` | 路由定义、请求处理、响应格式化 |
| 服务层 | `app/services/` | 业务逻辑、外部服务调用 |
| 模型层 | `app/models/` | 数据结构定义、数据转换 |
| 工具层 | `app/utils/` | 通用工具函数 |
| 核心层 | `app/core/` | 配置、日志等基础设施 |
---
## 14. 快速启动
```bash
# 1. 配置
@@ -441,15 +495,46 @@ cp config/config.yml.docker config/config.yml
# 编辑 config/config.yml 填入账号密码
# 2. 一键启动
./deploy.sh build
./deploy.sh up
docker-compose up -d
# 3. 查看采集日志
./deploy.sh logs
# 3. 访问API文档
# http://localhost:8000/docs
# 4. 消费数据
# 4. 启动采集
curl -X POST http://localhost:8000/crawl/start
# 5. 查看进度
curl http://localhost:8000/status
# 6. 消费数据
curl http://localhost:8000/consume?batch_size=10
# 5. 查看队列大小
curl http://localhost:8000/queue/size
```
---
## 15. Token自动刷新机制
系统实现了Token自动管理：
1. 首次请求时自动获取Token
2. Token缓存在内存中
3. 请求前检查Token有效期（提前5分钟刷新）
4. 遇到401错误自动重新获取Token
```python
# app/services/api_client.py 核心逻辑
async def _get_token(self) -> str:
# 检查token是否有效（提前5分钟刷新）
if self._access_token and time.time() < self._token_expires_at - 300:
return self._access_token
# 调用 /token 接口获取新token
response = await client.post(f"{self.base_url}/token", json={
"username": self.username,
"password": self.password,
"grant_type": "password"
})
self._access_token = token_data.get("access_token")
self._token_expires_at = time.time() + expires_in
```