jonbaldie/queue

队列服务器

概述

这是一个快速且易于使用的FIFO（先进先出）队列服务器，可在任何平台运行，通过HTTP端点即可简单操作。支持创建多个独立队列以分离不同类型的负载，适用于作为简单快速的工作队列（用于异步处理耗时任务）或轻量级消息代理。

核心功能与特性

• FIFO队列机制：严格保证先进先出，最早入队的负载最先被处理
• 负载唯一性：每个负载通过出队接口仅被读取一次，确保任务不重复执行
• 多队列支持：可创建任意数量的独立队列，实现不同类型任务的分离管理
• HTTP接口：通过简单的HTTP请求完成入队、出队和队列长度查询操作
• 可选持久性：支持通过配置将队列状态持久化到二进制日志文件，防止数据丢失

使用场景

• 异步任务调度：将耗时操作（如数据处理、文件转换、邮件发送）放入队列，由工作进程异步处理
• 消息传递：作为轻量级消息代理，在应用组件间传递消息，解耦系统模块
• 工作队列：分发任务到多个工作节点，实现任务负载均衡和并行处理

使用方法

启动服务器

使用Docker镜像启动，通过环境变量配置监听地址和端口：

bash
docker run -d -e HOST=127.0.0.1 -e PORT=1991 jonbaldie/queue

服务器将监听 http://127.0.0.1:1991。支持的环境变量：

• HOST：监听地址，默认值为 127.0.0.1
• PORT：监听端口，默认值为 1991

基本操作

入队（Enqueue）

向指定队列添加负载，队列不存在时会自动创建。发送POST请求到 /enqueue/:queue，负载放在请求的JSON体中：

bash
curl -X POST -H "Content-Type: application/json" -d '{"payload": "需要处理的数据"}' http://127.0.0.1:1991/enqueue/任务队列1

出队（Dequeue）

从指定队列获取并移除最早的负载。发送GET请求到 /dequeue/:queue：

bash
curl -X GET http://127.0.0.1:1991/dequeue/任务队列1

返回结果为队列中最早入队的负载，并将其从队列中永久移除。

查询队列长度

获取指定队列的待处理负载数量。发送GET请求到 /length/:queue：

bash
curl -X GET http://127.0.0.1:1991/length/任务队列1

持久性配置

默认情况下，服务器不持久化队列数据，重启后所有队列状态将丢失。启用持久化需添加 --persist 选项，并通过 PERSIST 环境变量指定日志文件存储路径：

bash
docker run -d -e PORT=1991 -e HOST=0.0.0.0 -e PERSIST=/data/ jonbaldie/queue /usr/bin/queue --persist

• 服务器会将队列变更记录到 persist.dat 文件（位于 PERSIST 指定的路径下）
• 启动时若检测到 persist.dat 文件存在，会先恢复历史数据再清空该文件
• 使用Docker时，建议将 persist.dat 所在目录挂载为持久卷，确保数据不丢失

注意：请勿手动编辑 persist.dat 文件，可能导致数据损坏或异常行为。

维护者：Jonathan Baldie <***>