# turbo-job

**Repository Path**: warter-droplet/turbo-job

## Basic Information

- **Project Name**: turbo-job
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-30
- **Last Updated**: 2026-04-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Turbo-Job

高性能分布式任务调度系统，基于 Rust + Raft + Nacos 构建。

**项目地址:**
- 后端: https://gitee.com/warter-droplet/turbo-job.git
- 前端: https://gitee.com/warter-droplet/turbo-job-web.git

## 项目简介

Turbo-Job 是一个企业级分布式任务调度平台，提供可靠的定时任务调度、延迟任务执行和多次回调等功能。采用 Raft 共识协议保证强一致性，支持动态扩缩容，适用于微服务架构下的任务调度场景。

**项目组成:**
- **后端**: 本项目（Rust + Axum + Raft + PostgreSQL）
- **前端**: 独立前端项目（需单独部署）

**核心特点:**
- 🚀 高性能：基于 Rust 和 Tokio 异步运行时，性能卓越
- 🔒 强一致：Raft 共识协议保证集群数据一致性
- 🌐 分布式：支持多节点部署，自动故障转移
- 🔄 零配置：基于 Nacos 自动服务发现，无需手动配置节点
- 📊 多样化：支持 Cron、固定间隔、延迟、多次回调等多种调度类型
- 🔌 可扩展：支持 HTTP、NATS、Kafka、RabbitMQ 等多种执行方式

## 快速开始

### 前置准备

在开始之前,请确保已完成以下准备工作:

#### 1. 安装依赖环境

- **Rust 1.75+** - 用于编译项目
- **PostgreSQL 14+** - 数据库
- **Nacos 2.0+** - 配置中心和服务发现

#### 2. 初始化数据库

```bash
# 创建数据库
psql -U postgres -c "CREATE DATABASE turbo_job;"

# 执行初始化脚本
psql -U postgres -d turbo_job -f postgres_init.sql
```

#### 3. 配置 Nacos

在 Nacos 中创建配置，Data ID 为 `turbo-job`，格式为 YAML:

```yaml
# 服务发现配置
discovery:
  service_name: turbo-job-cluster
  group: DEFAULT_GROUP
  namespace: public
  username: ""
  password: ""

# 数据库配置
database_conf:
  url: postgresql://postgres:password@localhost/turbo_job
  max_connection: 10
  min_connection: 1
  connect_timeout: 30
  idle_timeout: 300
  max_lifetime: 1800
  schema: turbo_job
```

---

### 部署方式

Turbo-Job 支持多种部署方式,请根据需要选择:

- [源码部署](#源码部署) - 适合开发和测试
- [Docker 部署](#docker-部署) - 适合快速体验和单机部署
- [Kubernetes 部署](#kubernetes-部署) - 适合生产环境和集群部署

---

### 源码部署

#### 1. 配置环境变量

创建 `.env` 文件:

```bash
# Nacos 配置（必需）
NACOS_SERVER_ADDR=127.0.0.1:8848
NACOS_NAMESPACE=public
NACOS_GROUP=DEFAULT_GROUP
NACOS_DATA_ID=turbo-job
NACOS_USERNAME=nacos
NACOS_PASSWORD=nacos

# HTTP API 端口（可选，默认 3000）
TURBO_HTTP_API_PORT=3000

# Raft gRPC 端口（可选，默认为 HTTP 端口 + 200）
TURBO_GRPC_CLUSTER_PORT=3200
```

#### 2. 编译运行

```bash
# 编译并运行
cargo build --release
./target/release/turbojob
```

服务启动后访问: `http://localhost:3000/turbo-job/api/v1/`

**注意**: 这只是后端 API 服务。如需使用 Web 管理界面，请部署前端项目。

#### 3. 部署前端（可选）

前端项目提供 Web 管理界面，需要单独部署。

**前端项目地址**: https://gitee.com/warter-droplet/turbo-job-web.git

部署步骤请参考前端项目的 README 文档。

#### 4. 创建第一个任务（通过 API）

```bash
curl -X POST http://localhost:3000/turbo-job/api/v1/job \
  -H "Content-Type: application/json" \
  -d '{
    "app_name": "my-app",
    "namespace": "default",
    "description": "每分钟执行一次",
    "schedule_type": "CRON",
    "cron_value": "0 * * * * ?",
    "handle_name": "myHandler",
    "timeout_second": 30,
    "try_times": 3
  }'
```

---

### Docker 部署

> 🚧 待补充

使用 Docker 快速部署 Turbo-Job。

**前置准备:**
- Docker 20.10+
- Docker Compose 2.0+

**部署步骤:**

```bash
# 待补充 Docker 部署命令
```

---

### Kubernetes 部署

> 🚧 待补充

在 Kubernetes 集群中部署 Turbo-Job。

**前置准备:**
- Kubernetes 1.20+
- kubectl 已配置

**部署步骤:**

```bash
# 待补充 K8s 部署 YAML 和命令
```

## 核心特性

### 1. 多种调度类型

#### Cron 调度
支持标准 Cron 表达式，灵活配置周期性任务:
```json
{
  "schedule_type": "CRON",
  "cron_value": "0 0 2 * * ?"
}
```

#### 固定间隔调度
支持固定时间间隔执行，可配置首次延迟和锚点对齐:
```json
{
  "schedule_type": "INTERVAL",
  "interval_second": 3600,
  "first_delay_second": 60,
  "anchor_time": 1640000000
}
```

#### 延迟任务
一次性延迟执行，执行后自动删除:
```json
{
  "schedule_type": "DELAY",
  "delay_second": 300
}
```

#### 多次回调任务
支持配置多次回调，每次使用不同参数:
```json
{
  "schedule_type": "MULTI_CALLBACK",
  "callback_list": "[{\"interval_second\":3600},{\"interval_second\":7200}]",
  "callback_params": "[\"第一次\",\"第二次\",\"第三次\"]"
}
```

### 2. 高级调度功能

- **有效期控制**: 设置任务有效期，过期自动删除
- **每日时间段**: 配置多个每日执行时间段（如 9:00-21:00）
- **锚点对齐**: 固定间隔任务基于锚点时间对齐触发
- **首次延迟**: 固定间隔任务支持配置首次触发延迟

### 3. 分布式架构

- **Raft 共识**: 基于 Raft 实现强一致性，自动 Leader 选举
- **Nacos 发现**: 节点启动时自动从 Nacos 发现集群
- **槽位分片**: 基于一致性哈希的槽位分片（16384 个槽位）
- **动态扩缩容**: 支持节点动态加入和退出

### 4. 多种执行模式

- **HTTP 回调**: 通过 HTTP 接口触发任务执行
- **消息队列**: 支持 NATS、Kafka、RabbitMQ、Redis、Pulsar
- **路由策略**: 轮询、随机、一致性哈希、分片广播
- **阻塞策略**: 串行执行、丢弃后续、覆盖早期

### 5. 可靠性保障

- **失败重试**: 支持配置重试次数和重试间隔
- **超时控制**: 支持配置任务执行超时时间
- **过期策略**: 支持配置过期任务的处理策略
- **任务归档**: 自动归档历史任务记录

## 架构设计

### 系统架构

```
┌─────────────────────────────────────────────────────────────┐
│                        Turbo-Job 集群                         │
├─────────────────────────────────────────────────────────────┤
│                                                               │
│  ┌──────────┐      ┌──────────┐      ┌──────────┐          │
│  │  Node 1  │◄────►│  Node 2  │◄────►│  Node 3  │          │
│  │ (Leader) │      │(Follower)│      │(Follower)│          │
│  └────┬─────┘      └────┬─────┘      └────┬─────┘          │
│       │                 │                  │                 │
│       └─────────────────┴──────────────────┘                │
│                    Raft 共识层                               │
│       ┌─────────────────┬──────────────────┐                │
│       │                 │                  │                 │
│  ┌────▼─────┐      ┌────▼─────┐      ┌────▼─────┐          │
│  │ Schedule │      │ Schedule │      │ Schedule │          │
│  │ Manager  │      │ Manager  │      │ Manager  │          │
│  └────┬─────┘      └────┬─────┘      └────┬─────┘          │
│       │                 │                  │                 │
│  ┌────▼─────┐      ┌────▼─────┐      ┌────▼─────┐          │
│  │   Task   │      │   Task   │      │   Task   │          │
│  │ Manager  │      │ Manager  │      │ Manager  │          │
│  └──────────┘      └──────────┘      └──────────┘          │
│                                                               │
└───────────────────────┬───────────────────────────────────┘
                        │
        ┌───────────────┼───────────────┐
        │               │               │
   ┌────▼────┐    ┌────▼────┐    ┌────▼────┐
   │  Nacos  │    │Database │    │   MQ    │
   │(服务发现)│    │(持久化) │    │(任务下发)│
   └─────────┘    └─────────┘    └─────────┘
```

### 核心组件

**Raft 共识层**
- Leader 选举和故障转移
- 日志复制和状态同步
- 槽位分配和任务分片

**Schedule Manager（调度管理器）**
- 任务加载和触发时间计算
- 时间轮调度算法
- 有效期和时间段检查

**Task Manager（任务管理器）**
- 任务实例创建和下发
- 状态跟踪和失败重试
- 超时检测和回调处理

**Job Manager（任务配置管理器）**
- 任务 CRUD 操作
- 缓存管理和变更通知
- 延迟任务加载

**Nacos 集成**
- 服务注册和发现
- 配置管理
- 集群自动加入

## 多节点部署

启动多个节点，它们会自动从 Nacos 发现彼此并组成集群:

```bash
# 节点 1（使用默认配置）
TURBO_HTTP_API_PORT=3000 \
./target/release/turbojob

# 节点 2（指定不同端口）
TURBO_HTTP_API_PORT=3001 \
TURBO_GRPC_CLUSTER_PORT=3201 \
./target/release/turbojob

# 节点 3（指定不同端口）
TURBO_HTTP_API_PORT=3002 \
TURBO_GRPC_CLUSTER_PORT=3202 \
./target/release/turbojob
```

**说明:**
- 节点会自动生成唯一 ID（基于时间戳）
- 如果不指定 `TURBO_GRPC_CLUSTER_PORT`，默认为 HTTP 端口 + 200
- 第一个启动的节点会初始化 Raft 集群
- 后续节点会自动加入现有集群

## API 文档

### API 路径说明

**所有 API 路径前缀**: `/turbo-job`

**当前可用的 API 路径:**

- `/turbo-job/api/v1/` - 标准 API（推荐给执行器客户端使用）
- `/turbo-job/turbo/v1/` - 完整 API（推荐给执行器客户端使用）
- `/turbo-job/api/console/v1/` - 控制台 API（推荐给前端管理界面使用）

### 可用的 API 端点

#### Job 管理 API

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/turbo-job/api/v1/job/create` | 创建任务 |
| POST | `/turbo-job/api/console/v1/job/create` | 创建任务（控制台） |
| POST | `/turbo-job/api/v1/job/update` | 更新任务 |
| POST | `/turbo-job/api/console/v1/job/update` | 更新任务（控制台） |
| POST | `/turbo-job/api/console/v1/job/remove` | 删除任务（控制台） |
| GET | `/turbo-job/api/v1/job/info?id={job_id}` | 查询任务详情 |
| GET | `/turbo-job/api/console/v1/job/info?id={job_id}` | 查询任务详情（控制台） |
| GET | `/turbo-job/api/v1/job/list?namespace={ns}&app_name={app}` | 查询任务列表 |
| GET | `/turbo-job/api/console/v1/job/list?namespace={ns}&page=1&page_size=10` | 查询任务列表（控制台） |
| POST | `/turbo-job/turbo/v1/job/delay` | 创建延迟任务 |
| POST | `/turbo-job/api/console/v1/job/delay` | 创建延迟任务（控制台） |
| POST | `/turbo-job/turbo/v1/job/remove` | 删除任务 |

#### App 管理 API

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/turbo-job/api/v1/app/instance/addrs?namespace={ns}&app_name={app}` | 查询应用实例地址 |
| POST | `/turbo-job/api/console/v1/app/list` | 查询应用列表（控制台） |
| GET | `/turbo-job/api/console/v1/app/instance/addrs?namespace={ns}&app_name={app}` | 查询应用实例地址（控制台） |

#### 系统信息 API

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/turbo-job/api/v1/about` | 查询版本信息 |

### API 使用示例

#### 创建 Cron 任务

```bash
curl -X POST http://localhost:3000/turbo-job/api/v1/job \
  -H "Content-Type: application/json" \
  -d '{
    "app_name": "my-app",
    "namespace": "default",
    "description": "每天凌晨2点执行",
    "schedule_type": "CRON",
    "cron_value": "0 0 2 * * ?",
    "handle_name": "dailyTask",
    "timeout_second": 300,
    "try_times": 3
  }'
```

#### 创建延迟任务

```bash
curl -X POST http://localhost:3000/turbo-job/api/v1/job/delay \
  -H "Content-Type: application/json" \
  -d '{
    "app_name": "my-app",
    "namespace": "default",
    "description": "60秒后执行",
    "handle_name": "delayTask",
    "trigger_param": "{\"orderId\":\"12345\"}",
    "delay_second": 60,
    "timeout_second": 30,
    "try_times": 3
  }'
```

#### 创建多次回调任务

```bash
curl -X POST http://localhost:3000/turbo-job/api/v1/job \
  -H "Content-Type: application/json" \
  -d '{
    "app_name": "my-app",
    "namespace": "default",
    "description": "多次回调任务",
    "schedule_type": "MULTI_CALLBACK",
    "callback_list": "[{\"interval_second\":3600},{\"interval_second\":3600}]",
    "callback_params": "[\"第一次回调\",\"第二次回调\"]",
    "handle_name": "multiCallback",
    "timeout_second": 30
  }'
```

#### 查询任务列表

```bash
curl http://localhost:3000/turbo-job/api/v1/job/list?namespace=default&app_name=my-app
```

#### 更新任务

```bash
curl -X PUT http://localhost:3000/turbo-job/api/v1/job/{job_id} \
  -H "Content-Type: application/json" \
  -d '{
    "enable": true,
    "description": "更新后的描述"
  }'
```

#### 删除任务

```bash
curl -X DELETE http://localhost:3000/turbo-job/api/v1/job/{job_id}
```

## 配置说明

### 环境变量

**必需配置:**

```bash
# Nacos 配置
NACOS_SERVER_ADDR=127.0.0.1:8848       # Nacos 服务器地址
NACOS_NAMESPACE=public                 # Nacos 命名空间
NACOS_GROUP=DEFAULT_GROUP              # Nacos 分组
NACOS_DATA_ID=turbo-job                # Nacos 配置 Data ID
NACOS_USERNAME=nacos                   # Nacos 用户名
NACOS_PASSWORD=nacos                   # Nacos 密码
```

**可选配置:**

```bash
# HTTP API 端口（默认 3000）
TURBO_HTTP_API_PORT=3000

# Raft gRPC 端口（默认为 HTTP 端口 + 200）
TURBO_GRPC_CLUSTER_PORT=3200

# Raft 节点配置（可选，系统会自动生成）
TURBO_RAFT_NODE_ID=123456              # 节点唯一 ID，不配置则自动生成
TURBO_RAFT_GRPC_ADDR=0.0.0.0:9725      # Raft gRPC 地址，不配置则自动计算

# 时区配置（可选）
TURBO_GMT_OFFSET_HOURS=8               # GMT 时区偏移（小时）
```

### Nacos 配置

在 Nacos 中创建配置，Data ID 为 `turbo-job`，格式为 YAML:

```yaml
# 服务发现配置
discovery:
  service_name: turbo-job-cluster       # 服务名称
  group: DEFAULT_GROUP                  # 服务分组
  namespace: public                     # 命名空间
  username: ""                          # 用户名（可选）
  password: ""                          # 密码（可选）

# 数据库配置
database_conf:
  url: postgresql://user:password@localhost/turbo_job
  max_connection: 10                    # 最大连接数
  min_connection: 1                     # 最小连接数
  connect_timeout: 30                   # 连接超时（秒）
  idle_timeout: 300                     # 空闲超时（秒）
  max_lifetime: 1800                    # 连接最大生命周期（秒）
  schema: turbo_job                     # 数据库 Schema
```

## 开发指南

### 编译项目

```bash
# 开发模式编译
cargo build

# 生产模式编译（优化）
cargo build --release

# 检查编译错误（不生成二进制）
cargo check
```

### 交叉编译

使用 `cross` 工具进行交叉编译到不同平台:

```bash
# 安装 cross
cargo install cross

# 编译到 Linux x86_64
cross build --release --target x86_64-unknown-linux-gnu

# 编译到 Linux ARM64
cross build --release --target aarch64-unknown-linux-gnu

# 编译到 macOS x86_64
cross build --release --target x86_64-apple-darwin

# 编译到 macOS ARM64 (Apple Silicon)
cross build --release --target aarch64-apple-darwin

# 编译到 Windows x86_64
cross build --release --target x86_64-pc-windows-gnu
```

编译产物位置: `target/{target-triple}/release/turbojob`

**常用目标平台:**
- `x86_64-unknown-linux-gnu` - Linux x86_64
- `aarch64-unknown-linux-gnu` - Linux ARM64
- `x86_64-apple-darwin` - macOS Intel
- `aarch64-apple-darwin` - macOS Apple Silicon
- `x86_64-pc-windows-gnu` - Windows x86_64

### 运行测试

```bash
# 运行所有测试
cargo test

# 运行特定模块测试
cargo test --package turbojob-application
```

### 代码检查

```bash
# 代码格式化
cargo fmt

# 代码检查
cargo clippy
```

## 项目结构

```
turbo-job/
├── crates/                          # Workspace 子项目
│   ├── api/                         # API 层
│   │   └── src/
│   │       ├── openapi/             # OpenAPI 接口
│   │       │   └── v1/              # V1 版本（Job、App API）
│   │       ├── http/                # HTTP 服务
│   │       └── grpc/                # gRPC 服务（Raft 通信）
│   │
│   ├── application/                 # 应用层（业务逻辑）
│   │   └── src/
│   │       ├── job/                 # Job 管理
│   │       ├── task/                # Task 执行管理
│   │       │   ├── core.rs          # TaskManager 核心
│   │       │   ├── archive_manager.rs   # 任务归档
│   │       │   └── stats_manager.rs     # 统计管理
│   │       ├── schedule/            # 调度管理
│   │       │   ├── core.rs          # ScheduleManager 核心
│   │       │   └── batch_call.rs    # 批量调度
│   │       ├── app/                 # App 管理
│   │       ├── user/                # 用户管理
│   │       ├── services/            # 服务层
│   │       └── use_cases/           # 用例层
│   │
│   ├── domain/                      # 领域层
│   │   └── src/
│   │       ├── entities/            # 领域实体
│   │       ├── aggregates/          # 聚合根
│   │       ├── value_objects/       # 值对象
│   │       └── repositories/        # 仓储接口
│   │
│   ├── infrastructure/              # 基础设施层
│   │   └── src/
│   │       ├── storage/             # 数据存储
│   │       │   ├── entity/          # 数据库实体
│   │       │   ├── repository/      # 数据仓储实现
│   │       │   └── manager/         # 数据管理器
│   │       ├── raft/                # Raft 共识
│   │       │   ├── cluster_tokio.rs # Raft 集群管理
│   │       │   ├── state_machine.rs # Raft 状态机
│   │       │   └── network.rs       # Raft 网络通信
│   │       ├── cluster/             # 集群管理
│   │       │   ├── nacos_discovery.rs   # Nacos 服务发现
│   │       │   └── cluster_bootstrap.rs # 集群启动引导
│   │       ├── mq/                  # 消息队列
│   │       ├── executor/            # 任务执行器
│   │       └── config/              # 配置管理
│   │
│   └── common/                      # 公共模块
│       └── src/
│           ├── api_result.rs        # API 响应封装
│           ├── error.rs             # 错误定义
│           ├── cron_utils.rs        # Cron 工具
│           └── datetime_utils.rs    # 时间工具
│
├── src/                             # 主程序
│   ├── main.rs                      # 程序入口
│   └── web_config.rs                # Web 服务配置
│
├── postgres_init.sql                # 数据库初始化脚本
├── Cargo.toml                       # Workspace 配置
└── build.rs                         # 构建脚本
```

## 技术栈

- **语言**: Rust 1.75+
- **Web 框架**: Axum 0.7
- **共识协议**: OpenRaft
- **服务发现**: Nacos
- **数据库**: PostgreSQL (SQLx)
- **消息队列**: NATS / Kafka / RabbitMQ / Redis / Pulsar
- **异步运行时**: Tokio

## 许可证

MIT License