Queuebit 是面向 Node.js 的 Redis 持久化批处理 SDK。它把一轮长任务记录为 Run，按页保存进度，在失败后有限重试，并在成功后交付完成回调。适合批量生成收据、数据同步、受控补数等“有稳定业务快照、可按页推进、需要可查询状态”的工作。
运行环境要求 Node.js 22+、Redis 7.2+，Redis 主节点需要可观察到 noeviction。
npm install queuebit当前仓库仍保留 private: true，避免误发布。若公开 npm 包尚未匹配本文档 API，这是发布前置条件，不要求使用者改成本地打包安装。
使用 批量生成收据任务模块 连接你的业务快照 repository 和幂等 sink：
import { createBatchQueue } from 'queuebit';
import { defineReceiptTask } from './receipt-task.mjs';
import { receiptRepository, receiptSink } from './your-application-adapters.js';
const queue = createBatchQueue({
namespace: 'receipt-service',
redis: { mode: 'direct', host: '127.0.0.1', port: 6379 },
});
const task = defineReceiptTask(queue, receiptRepository, receiptSink);
await queue.ready();
const { runId } = await task.start({
query: { snapshotId: 'snapshot-2026-09' },
idempotencyKey: 'receipt-snapshot-2026-09',
});
console.log(runId);
// 消费者需要保持运行；应用关闭时调用 await queue.close()。复制示例任务模块到你的应用。your-application-adapters 需要提供固定成员和 payload 的业务快照、按稳定游标读取的页，以及持久的 putOnce 写入。快照应在 start 前已经存在。完整示例 描述这些合同；恢复示例 演示外部写成功但 Queuebit 进度尚未确认时，worker 重启后如何安全重放。
start 表示提交被接收，不表示已经完成。用 task.get(runId) 查询状态和回调进度。执行和回调交付都是至少一次；业务幂等要和业务写入一起保存。import、构造队列和 define 不会建立连接；ready 才启动选定的 producer/consumer 模式。取消和关闭是协作式的，handler 不退出仍会占用本地物理槽。
本地 Redis 可使用 direct host/port；云服务通常提供 redis:// 或 rediss:// URL；单主复制拓扑可用 Sentinel discovery。TLS 需要校验 CA 和主机名；Sentinel 发现凭据与 Redis 数据节点凭据分开。当前不支持 Redis Cluster。复制是异步的，故障切换可能丢失已确认写入。
operator 接口提供 Run 查看/列表/暂停/恢复/取消、死信查看/重放、健康、容量和本地指标。控制请求携带 expectedRevision、reason 和 commandId；响应不确定时先查询当前状态，再用同一命令身份重试，不要假设没有写入。
文档站正文唯一来源为 website/docs，当前为仅中文完整站点。旧双语目录和旧 URL 不再保留。
- 首页
- 快速开始：使用
npm install queuebit跑通第一轮收据任务。 - 任务定义与接口：定义任务、推进分页、提交、查询、取消及错误处理边界。
- 批量生成收据：从入门 Map 示例过渡到持久化恢复示例。
- 完整可执行入门应用：复制为独立应用的
app.mjs。
Queuebit 将固定业务快照按页执行，保存进度并持久投递回调。应用负责真实快照仓储与业务幂等写入；start 只表示接收，消费者需要持续运行。失败后按 Run 状态和控制命令标识恢复；不确定响应不代表零写入。
根包只导出 createBatchQueue、QueuebitError 和公开 TypeScript 类型。没有旧 API/旧数据迁移、CLI、框架适配器或内部子路径。包本身不提供 cron、DAG、优先级、全局限流、仪表盘、CDC 或无限流。你的服务负责托管、信号、业务 repository 和 sink。
npm ci
npm --prefix website ci
npm run docs:validate
npm run test:batch:docs
npm run test:batch:docs:recovery站点开发使用 Node.js 22.12+。docs:validate 检查中文站源码、类型、静态构建和本地链接，不需要 Redis。test:batch:docs 独立构建根包、安装候选包、编译 API 示例，并运行真实 Redis 下的入门示例及单进程重试教学。test:batch:docs:recovery 启动测试自有 worker 子进程，验证外部写成功但进度未确认后的跨进程恢复。测试会启动自有隔离 Redis 并清理。它们不是 npm 发布资格验证。
npm run docs:dev 启动热更新开发服务，docs:edit 是同一入口的别名。npm run docs:build 只生成 website/dist；之后 npm run docs:preview 只预览已有产物。服务绑定 127.0.0.1，实际端口以启动输出为准，站点根路径为 /，没有 /zh 或 /queuebit 前缀。结束预览后按 Ctrl+C 停止自己启动的服务。
SDK 完整验证入口仍是 npm test / test:batch:release，需要 Node.js 22/24、Redis 和 OpenSSL 等环境。当前文档工作不恢复已暂停的远端 CI 排查，也不声称满足 npm 发布要求。
当前仓库仍是历史版本号 0.0.5 且 private: true。选择新版本、打 tag、发布 npm 或修复正式发版门禁，需要单独 release 授权。
Apache-2.0