voidrail 0.3.3

No project description provided

VoidRail

VoidRail 的名称来自于古老的修仙界，是虚空传送阵的意思。

VoidRail 基于 Celery 构建轻量级分布式任务处理框架，专为 CPU 密集型计算设计。它提供简单易用的接口，让您可以快速构建和部署分布式计算服务。

安装

使用 pip 安装：

pip install voidrail

依赖说明
VoidRail 默认使用 Redis 作为 Broker 和结果后端，因此在启动 Worker 或客户端前，需要先确保 Redis 服务已运行（默认端口为 6379）。可以使用以下方式启动 Redis：

# 本地启动（需先安装 Redis）
redis-server

# 或使用 Docker 启动
docker run -d --name voidrail-redis -p 6379:6379 redis

核心组件

VoidRail 采用两组件架构：

1. Worker：服务实现模块，继承 CeleryWorker 基类，定义处理逻辑
2. Client：客户端模块，使用 CeleryClient 类发送任务请求

基本使用

简单例子

# echo.py
import time
from voidrail import create_app

app = create_app('echo')

@app.task(name='echo.say_hello')
def say_hello(name):
    """简单的问候任务"""
    return f"Hello, {name}! Current time: {time.ctime()}"

@app.task(name='echo.say_hello_delay', bind=True)
def say_hello_delay(self, name, delay=3):
    """带延迟的问候任务，演示任务状态更新"""
    self.update_state(state='PROGRESS', meta={'progress': 0, 'message': '开始处理'})
    
    # 模拟处理过程
    for i in range(10):
        time.sleep(delay / 10)
        self.update_state(state='PROGRESS', meta={
            'progress': (i + 1) * 10, 
            'message': f'处理中 {(i + 1) * 10}%'
        })
    
    return f"Hello after {delay} seconds, {name}! Time: {time.ctime()}"

命令行工具

安装完成后，你可以通过命令行来启动服务或调用任务，无需额外代码：

# 启动 Worker（加载本地文件自定义模块 echo.py）
python -m voidrail --module echo

# 调用任务
python -m voidrail call echo.say_hello -a World

# 查看帮助信息
python -m voidrail --help

使用客户端

你也可以通过代码来访问已经启动的服务。

from voidrail.client import CeleryClient

# 创建客户端
client = CeleryClient(service_name="echo")

# 同步调用任务
result = client.call(
    task_name="say_hello",
    args=["World"]
)
print(result["result"])  # Hello, World!

# 异步调用任务
async_res = client.call(
    task_name="say_hello_delay",
    args=["Async World"],
    kwargs={"delay": 2},
    wait_result=False
)
task_id = async_res["task_id"]
print(f"任务已提交，ID: {task_id}")

# 查询任务状态
status = client.get_task_status(task_id)
print(f"任务状态: {status['status']}")

# 获取最终结果（可在状态为 completed 后调用）
if status["status"] == "completed":
    final_res = client.get_task_result(task_id)
    print(f"结果: {final_res}")

# 列出当前注册的任务
tasks = client.list_registered_tasks()
print("可用任务:", tasks)

水平扩展能力

VoidRail的一个主要优势是支持简单而强大的水平扩展。当您启动多个相同服务的Worker实例时：

1. 自动负载均衡：所有实例会自动协作处理队列中的任务
2. 无需额外配置：不需要任何特殊设置，只需启动更多相同的服务实例
3. 容错和高可用：如果某个实例崩溃，其他实例会继续处理任务

例如，您可以在多台服务器上启动相同的服务：

graph TB
    Client[客户端]
    Queue[(Redis消息队列)]
    
    subgraph "服务器A"
    Worker1[Worker实例1]
    end
    
    subgraph "服务器B"
    Worker2[Worker实例2]
    Worker3[Worker实例3]
    end
    
    subgraph "服务器C"
    Worker4[Worker实例4]
    end
    
    Client -->|发送任务| Queue -->|分发任务| Worker1 & Worker2 & Worker3 & Worker4

运行多个Worker实例

要充分利用多核CPU，可以启动多个Worker实例：

# 启动Worker进程
# 通过环境变量控制并发度
CELERY_CONCURRENCY=4 python hello_service.py

您可以在不同的服务器上多次启动相同的服务实例：

# 在服务器A上
python hello_service.py

# 在服务器B上
python hello_service.py

# 在服务器C上
python hello_service.py

每个实例都会自动加入相同的worker池，共同处理任务队列。Celery会为每个worker分配一个唯一ID， 确保任务只会被处理一次。这种设计使VoidRail非常适合需要动态扩展的场景 - 随着负载增加， 只需启动更多的worker实例即可线性提高处理能力。