ejhayes/nodejs-bull-monitor

bull-monitor

!https://api.codeclimate.com/v1/badges/9ca0eb7b9c6191ab30e9/maintainability !https://api.codeclimate.com/v1/badges/9ca0eb7b9c6191ab30e9/test_coverage !https://img.shields.io/docker/pulls/ejhayes/nodejs-bull-monitor.svg

镜像概述

bull-monitor是一款一站式Bull队列监控与报告工具，以Docker容器形式运行，适用于本地开发或生产环境部署。其核心目标是无需编写自定义代码，即可实现Bull队列的实时集成与监控，提供可视化界面、性能指标收集及错误报告等功能。

核心功能与特性

• 自动队列发现：只需指向Redis实例，即可自动发现Bull队列
• Prometheus指标集成：自动为每个发现的队列配置Prometheus指标
• 多UI支持：可配置的可视化界面（支持arena、bull-board、bull-master）
• Sentry错误报告：通过SENTRY_DSN环境变量启用
• Elastic ECS日志：当NODE_ENV设为production时自动启用
• OAuth2代理：可选集成oauth2_proxy限制访问（默认禁用）

使用场景

• 开发环境中实时监控Bull队列状态与任务执行情况
• 生产环境中收集队列性能指标，结合Prometheus和Grafana进行可视化分析
• 需要集中管理多个Bull队列的应用系统
• 需对队列访问进行权限控制的场景

使用方法

Docker快速启动

sh
docker run -d --rm \
  --name bull-monitor \
  -e "NODE_ENV=development" \
  -e "REDIS_HOST=host.docker.internal"  # Docker特殊主机名，用于访问宿主机服务
  -e "REDIS_PORT=6001" \
  -e "PORT=3000" \
  -e "BULL_WATCH_QUEUE_PREFIXES=bull" \
  -e "UI=bull-master" \
  -p 3000:3000 \
  ejhayes/nodejs-bull-monitor:latest

Docker Compose配置

在docker-compose.yml中添加以下配置：

yml
bull-monitor:
  image: docker.xuanyuan.run/ejhayes/nodejs-bull-monitor:latest
  ports:
    - 3000:3000
  environment:
    REDIS_HOST: <你的Redis主机>
    REDIS_PORT: <你的Redis端口>
    BULL_WATCH_QUEUE_PREFIXES: bull
    PORT: 3000
    UI: bull-master

启动服务：

sh
docker-compose up bull-monitor

可用访问路径

服务启动后，可通过以下路径访问相应功能：

配置说明

环境变量参数

Prometheus指标

指标通过/metrics端点暴露，为每个队列自动跟踪以下指标：

指标标签

注意事项

• 队列指标为全局指标，非特定于工作器
• Gauge类型指标（*_total）每60秒刷新一次，可通过BULL_COLLECT_QUEUE_METRICS_INTERVAL_MS调整间隔

Grafana支持

可在Grafana中可视化队列指标，需同时运行：

• bull-monitor（确保/metrics端点可访问）
• Prometheus（配置为抓取bull-monitor指标）
• Grafana（配置为从Prometheus获取数据）

本地测试环境

sh
# 启动服务
npm run services:start
npm run start:dev

# 生成测试数据
npm run generate

访问Grafana（http://localhost:3001%EF%BC%89%EF%BC%8C%E5%AF%BC%E5%85%A5%E4%BB%A5%E4%B8%8B%E4%BB%AA%E8%A1%A8%E7%9B%98%EF%BC%9A

可用UI界面

bull-board（默认）

来源：https://github.com/felixmosh/bull-board#readme
通过设置UI=bull-board显式启用。

bull-master

来源：https://github.com/hans-lizihan/bull-master
通过设置UI=bull-master启用。

arena

来源：https://github.com/bee-queue/arena
通过设置UI=arena启用。

OAuth2代理配置

通过内置OAuth2代理限制访问，需至少设置以下环境变量：

• USE_OAUTH2_PROXY=1（启用代理）
• OAUTH2_PROXY_REDIRECT_URL（OAuth提供商重定向URL）
• OAUTH2_PROXY_CLIENT_ID（客户端ID）
• OAUTH2_PROXY_SECRET_ID（密钥）

更多配置选项见https://oauth2-proxy.github.io/oauth2-proxy/docs/configuration/overview/#environment-variables%E3%80%82

安全注意事项

• 此工具设计为后台监控解决方案，不应公开暴露
• 目前仅支持单进程运行，不建议水平扩展（未来可能支持）

本地开发

启动完整本地开发环境：

sh
# 启动依赖服务
npm run services:start
# 启动开发模式
npm run start:dev

可用服务及访问地址：

• Grafana UI: http://localhost:3001
• Prometheus: http://localhost:3002
• SMTP (Mailhog): http://localhost:3003%EF%BC%88%E7%94%A8%E6%88%B7%E5%90%8D%EF%BC%9A%60test%60%EF%BC%8C%E5%AF%86%E7%A0%81%EF%BC%9A%60test%60%EF%BC%89
• Redis: localhost:6001
• SMTP服务器（Grafana告警用）: localhost:6002（无需认证，无加密）

清理环境：

sh
# 停止并移除所有服务
npm run services:remove

# 仅停止服务（保留数据）
npm run services:stop

路线图

查看https://github.com/ejhayes/bull-monitor/projects/1%E4%BA%86%E8%A7%A3%E6%9C%AA%E6%9D%A5%E6%94%B9%E8%BF%9B%E8%AE%A1%E5%88%92%E3%80%82

贡献者

感谢以下贡献者（emoji key）：

本项目遵循https://github.com/all-contributors/all-contributors%E8%A7%84%E8%8C%83%EF%BC%8C%E6%AC%A2%E8%BF%8E%E4%BB%BB%E4%BD%95%E5%BD%A2%E5%BC%8F%E7%9A%84%E8%B4%A1%E7%8C%AE%EF%BC%81