企业官网建设流程全解析

• 后端
• 消息队列
• 任务调度

本文基于 docs/gitbook/bullmq-pro/install.md 编写。BullMQ Pro 是开源 BullMQ 的商业支持版本，通过独立的 npm 私有仓库（taskforce.sh 维护的 Registry）分发。读完本文，你将掌握如何获取 NPM Token、配置.npmrc、安装@taskforcesh/bullmq-pro包、在代码与 Docker 环境中正确使用QueuePro/WorkerPro等 Pro 类，并了解安装完成后可继续探索的 Pro 特色能力。

一、理解 BullMQ Pro：商业版本与安装前提

BullMQ 是一个基于 Redis 或 PostgreSQL 的消息队列与批量处理库，支持 NodeJS、Python、.NET、Elixir、Rust 与 PHP 等多种语言。本仓库即开源版bullmq的源码（当前 package.json 中版本为 6.3.8，MIT 许可），包含Queue、Worker、JobScheduler、FlowProducer等核心类以及 src/commands 下整套 Lua 脚本实现。

BullMQ Pro 是同一团队（Taskforce.sh）推出的商业支持版本。根据 docs/gitbook/bullmq-pro/introduction.md 的说明，它可以作为标准 BullMQ 的drop-in replacement（直接替换）：安装后只需把开源类的导入换成 Pro 版本的类，即可使用 Pro 新增的高级功能，并享有来自库作者团队的商业支持。

安装 BullMQ Pro 需要满足以下前提：

1. Node.js / npm 环境：@taskforcesh/bullmq-pro是 npm 包，通过 npm、yarn 或 pnpm 安装。
2. 有效的 NPM Token：BullMQ Pro 不在公共 npm Registry 分发，必须先从taskforce.sh获取 NPM Token（该网站同时提供免费试用 Token，用于评估后再决定是否订阅，许可证采用按组织授权、项目内不限使用的模式，详见 introduction.md）。

注意：本仓库只包含开源 BullMQ 的实现，BullMQ Pro 是独立分发的商业包，安装过程通过其私有 Registry 完成。

二、获取 NPM Token 并配置.npmrc

拿到 Token 之后，第一步是在应用仓库中创建或更新.npmrc文件，将@taskforceshscope 的包定向到私有 Registry，并注入认证信息。完整配置如下：

@taskforcesh:registry=https://npm.taskforce.sh/ //npm.taskforce.sh/:_authToken=${NPM_TASKFORCESH_TOKEN} always-auth=true

逐行解读：

其中NPM_TASKFORCESH_TOKEN需要先在环境中定义，例如本地开发：

export NPM_TASKFORCESH_TOKEN=你的_token值

在 CI/CD 流水线中，则应将该值配置为流水线的 Secret 环境变量，不要把 Token 明文写进.npmrc或提交到仓库。除了直接编辑.npmrc，也可以使用 npm 命令行写入等价配置：

npm config set @taskforcesh:registry https://npm.taskforce.sh/ npm config set //npm.taskforce.sh/:_authToken ${NPM_TASKFORCESH_TOKEN} npm config set always-auth true

三、安装@taskforcesh/bullmq-pro

配置好.npmrc后，就可以像安装普通包一样安装 Pro 包，支持 npm、yarn、pnpm 三种包管理器：

# npm npm install @taskforcesh/bullmq-pro # yarn（官方文档示例） yarn add @taskforcesh/bullmq-pro # pnpm pnpm add @taskforcesh/bullmq-pro

安装完成后，可以用如下命令验证版本与依赖树是否正常（此时应能看到@taskforcesh/bullmq-pro及其依赖的开源bullmq底座）：

npm ls @taskforcesh/bullmq-pro

从源码证据看，BullMQ Pro 始终紧跟开源 BullMQ 的演进：其 changelog.md 中记录了每次发版对bullmq的版本升级，例如 7.48.0 版本将底层 bullmq 升级至 v5.81.4。这意味着你在开源版中积累的 API 使用经验，在 Pro 版本中依然适用。

四、引入 Pro 类并使用

BullMQ Pro 的核心使用方式与开源版完全一致，只需从@taskforcesh/bullmq-pro导入Pro 版本的类。按照 install.md 的说明，这些类是开源 BullMQ 库对应类的子类，在继承全部现有功能的基础上新增了 Pro 能力：

import { QueuePro, WorkerPro } from '@taskforcesh/bullmq-pro'; const queue = new QueuePro('myQueue'); const worker = new WorkerPro('myQueue', async job => { // Process job });

代码结构上与开源版几乎无异：QueuePro用于投递任务，WorkerPro用于消费处理，连接配置、任务选项等 API 保持一致。这样设计的好处是迁移成本极低——把Queue换成QueuePro、Worker换成WorkerPro、Job换成JobPro即可逐步启用 Pro 功能。

结合仓库内 docs/gitbook/bullmq-pro 目录下的文档，可以看到 Pro 系列类还包括：

• JobPro：Pro 版任务对象，在批处理（Batches）中通过job.getBatch()获取整批任务、用setAsFailed(err)单独标记失败任务，见 batches.md；
• QueueEventsPro：Pro 版事件监听器，配合全局事件监听单个任务的 completed/failed 事件，同样见 batches.md；
• QueuePro/WorkerPro的group选项：在queue.add()的任务选项中通过group: { id }为任务分组，实现组间 round-robin 公平调度，见 groups/README.md；
• WorkerPro的batch选项：{ size, minSize, timeout, groupAffinity }控制批量处理，见 batches.md；
• WorkerPro支持返回Observable：实现任务取消、TTL 超时自动取消、基于最后返回值断点续跑等高级场景，见 observables/README.md；
• QueuePro/WorkerPro的telemetry选项：可传入BullMQOtel实例接入 OpenTelemetry 可观测性，见 telemetry.md。

五、在 Docker 中安装 BullMQ Pro

使用 Docker 部署时，需要在镜像构建阶段就把.npmrc一并放入镜像，否则构建过程中 npm/yarn 无法解析私有 Registry 的认证。官方文档给出的 Dockerfile 片段如下：

WORKDIR /app ADD .npmrc /app/.npmrc

关键点：

• .npmrc必须在执行npm install/yarn install之前复制到工作目录，通常与构建命令放在同一个构建阶段；
• 建议通过构建参数（Build Arg）或 CI Secret 注入NPM_TASKFORCESH_TOKEN，保持.npmrc内继续使用${NPM_TASKFORCESH_TOKEN}占位，避免把明文 Token 打进镜像层；
• 如果最终运行镜像不需要安装依赖，可以在多阶段构建的最终阶段丢弃包含 Token 的.npmrc，减少敏感信息暴露面。

六、安装后的下一步：探索 Pro 特色能力

安装并跑通基础示例后，可以按需深入以下 Pro 特有主题（均在仓库文档中有完整配置示例）：

七、常见问题与注意事项

1. Token 失效或 401 错误：检查NPM_TASKFORCESH_TOKEN环境变量是否已正确设置、Token 是否过期（试用 Token 通常有有效期），以及.npmrc是否位于执行安装命令的目录（npm 会逐级向上查找）。
2. 不要把 Token 提交进仓库：.npmrc应只保留${NPM_TASKFORCESH_TOKEN}占位符，Token 本身放本地环境变量或 CI Secret；同时建议把.npmrc加入.gitignore前的安全审查清单（若仓库需要共享该文件，务必确保不含明文 Token）。
3. always-auth不要随意删除：删除后 npm 在部分场景（如仅读取公开元数据）可能不发送认证头，导致安装失败或行为不稳定。
4. 版本演进：Pro 包随开源 bullmq 版本迭代，升级 Pro 版本前可查阅 changelog.md 了解底层 bullmq 版本与功能变更，新版本公告渠道详见 new-releases.md。
5. 免费试用：若尚未决定是否订阅，可先在 taskforce.sh 申请免费试用 Token 完成安装与评估，再决定是否转为正式订阅（许可证按组织授权、不限项目数，详见 introduction.md）。

至此，你已经完成了 BullMQ Pro 的安装闭环：从获取 Token、配置.npmrc、安装@taskforcesh/bullmq-pro，到代码与 Docker 环境中的 Pro 类接入。后续即可基于 Groups、Batches、Observables 等 Pro 特性，在保持开源 BullMQ API 使用习惯的前提下，构建更公平、更高吞吐、更可观测的生产级任务队列。

• 后端
• 消息队列
• 任务调度