Huey 消费者(Consumer)完全指南:启动、配置、Worker 模型与生产部署

原创2026-10-09 15:58:431,344 阅读
文章标签:任务调度后端

Huey 消费者(Consumer)完全指南:启动、配置、Worker 模型与生产部署

Huey 是一个轻量级任务队列,而 consumer(消费者) 是真正从队列中取出并执行任务的常驻进程。本文以官方文档 docs/consumer.rst 为主体,结合 huey/consumer.py、huey/consumer_options.py 的源码实现与 examples/deploy 生产配置示例,系统讲解消费者的启动方式、全部命令行选项、三种 Worker 执行模型的取舍、优雅关闭/重启的信号机制、多消费者部署策略,以及消费者内部的消息流转原理。读完本文,你将能独立完成 Huey 生产环境的启动参数选型与进程编排。

启动消费者:定位你的 Huey 实例

消费者只是一个普通的 Python 进程,通过命令行入口 huey_consumer 启动。它的唯一必需参数是指向你的 Huey 实例的"导入路径"(import path)——也就是你在交互式解释器中导入该 Huey 对象时所用的点分路径:

huey_consumer blog.main.huey --logfile=../logs/huey.log

上面命令中的 blog.main.huey 对应下面的导入语句:

>>> from blog.main import huey

换句话说,huey_consumer 会执行 from blog.main import huey,拿到实例后再连接存储后端、创建调度器和 Worker。因此,"能不能启动消费者"本质上等价于"能不能在 Python 中导入这个对象"。

常见的导入失败与三种解决方式

如果 blog 模块不在你的 Python 路径上,导入就会失败。官方文档给出了三种绕过方式:

  1. 手动指定 PYTHONPATH:启动时直接注入搜索路径——

    PYTHONPATH=/some/dir/:$PYTHONPATH huey_consumer blog.main.huey
    
  2. 从配置模块所在目录启动消费者:直接 cd 到站点根目录再运行。作者本人使用 supervisord 管理 Huey 进程时,就是在 supervisord 配置里把 directory 指向站点根目录。

  3. 写一个包装脚本,手动 hack sys.path:在脚本里 sys.path.insert(...) 后再调用消费者主循环。

⚠️ supervisord 用户必读警告:如果打算用 supervisord 管理消费者进程,必须直接运行消费者命令,不要隔着一层 shell 脚本。中间层的 shell 脚本会干扰 supervisor 对消费者 Python 进程的终止与重启(这是 GitHub issue #88 讨论过的问题,后文部署章节会反复强调这一点)。

消费者命令行选项完全参考

消费者的全部选项在 huey/consumer_options.py 中定义,代码用 optparse 把它们组织成三个选项组:Logging、Workers、Scheduler。其默认值集中定义在 config_defaults 元组中(huey/consumer_options.py),这些默认值会原样传入 Consumer 构造函数,是理解每个选项行为的权威依据。

日志选项

选项 说明
-l, --logfile 日志输出到指定文件;不指定则输出到 stderr。日志文件会无限增长,建议配合 logrotate 之类的轮转工具。也可以自己在名为 huey 的 logger 上挂 handler。默认日志级别为 INFO
-v, --verbose 详细日志(loglevel=DEBUG)。注意:因为参数冲突,在 Django 环境下该选项改名为 -V, --huey-verbose
-q, --quiet 最小化日志(loglevel=WARNING)
-S, --simple 使用简单日志格式,只包含时间(H:M:S)和消息

日志级别与格式在源码中有精确映射:verbose 参数未指定时级别为 INFO,指定后为 DEBUG,-q 使其为 WARNING(见 huey/consumer_options.py)。-S 的格式为 '%(asctime)s %(message)s';默认格式则包含级别、模块名和"工作者标识"——process 类型显示进程号,其余类型显示线程名(huey/consumer_options.py)。这对排查"哪个 Worker 处理了哪个任务"很有用。

Worker 选项

选项 说明
-w, --workers Worker 线程/进程/greenlet 的数量。默认 1,但大多数应用建议至少 2,避免一个慢任务独占唯一的 Worker。CPU 密集型负载下,可向 CPU 核心数靠拢。使用 greenlet 类型时能跑上百个 Worker,但用 Redis 时要相应放大连接池
-k, --worker-type 选择执行模型:thread、process 或 greenlet,默认 thread。选择依据见"Worker 类型"一节
-M, --max-tasks Worker 执行完指定数量任务后自动重启,用于防止内存泄漏等问题。该选项要求健康检查开启,否则会抛出 ConfigurationError(源码在 huey/consumer.py 中显式校验:max_tasks requires check_worker_health be enabled)

-M 的底层机制值得注意:Worker 的 loop() 中每执行完一个任务就累加 task_count,一旦达到 max_tasks 便抛出 WorkerRecycle 异常,外层 _run 循环捕获后记录 "Process %s restarting (max tasks)" 并让该 Worker 正常退出(huey/consumer.py),随后由主循环的健康检查把它重新拉起。这是一种"定期回收 Worker 进程"的经典防泄漏手段。

队列轮询选项

这些参数控制"轮询型"存储后端(如非阻塞模式的 Redis)的空闲等待策略:

选项 说明
-d, --delay 轮询后端时的基础等待秒数,默认 0.1。如果队列里没找到任务,会把当前延迟乘以 backoff 参数;一旦收到任务,轮询间隔立即重置回该值
-m, --max-delay 使用加权退避时,两次轮询之间的最大等待秒数,默认 10。如果消费者很少收到任务,可以调大它来降低 CPU 占用
-b, --backoff 轮询退避倍数,必须不小于 1,默认 1.15。ConsumerConfig.validate() 中会校验 backoff < 1 直接抛 ValueError(huey/consumer_options.py)

退避逻辑的实现在 Worker 的 sleep() 方法里:等待 self.delay 秒后把 self.delay *= self.backoff,但先钳制到 max_delay(huey/consumer.py);而只要 dequeue() 拿到任务,self.delay 就会立即重置为 default_delay(huey/consumer.py)。也就是说:空闲越久,轮询越稀疏,最多不超过 max_delay;一来任务立刻回到快节奏。注意阻塞型存储(如 Redis 的 BRPOP 模式)不走这条路径,huey.storage.blocking 为真时 Worker 拿到空结果不会 sleep。

健康检查与锁选项

选项 说明
-c, --health-check-interval 消费者检查 Worker 状态、重启已死亡 Worker 的频率,默认 10 秒
-C, --disable-health-check 关闭 Worker 健康检查。开启健康检查成本很低,多数部署应保持默认
-f, --flush-locks 启动消费者时冲刷(flush)所有锁。如果消费者在执行加锁任务时被突然杀掉,遗留的锁可能永远卡住后续任务,此选项用于清理
-L, --extra-locks 额外的待冲刷锁名,逗号分隔。用于清理那些"在上下文管理器里创建、启动时无法被自动发现"的锁。隐含开启 --flush-locks

健康检查的源码实现在主循环中:每隔 health_check_interval 遍历一次 Worker 列表,任何死亡的 Worker 会被重建并重新 start(),连调度器死亡也会被检测并重启(huey/consumer.py)。冲刷锁则由 Consumer.__init__ 在启动前执行 self.flush_locks(*lock_names),发现陈旧锁时记录 warning(huey/consumer.py)。

生命周期选项

选项 说明
-t, --shutdown-timeout 优雅关闭时等待 Worker 完成当前任务的秒数。超时后剩余任务会被当作收到中断信号处理(即被打断)。默认无限期等待在途任务完成
-g, --graceful-signal 默认 INT 触发优雅关闭、TERM 立即中断;大多数进程管理器发送的是 TERM,因此生产环境应指定 -g TERM,让 TERM 走优雅路径、INT 立即中断
-s, --scheduler-interval 调度器运行频率,默认每秒一次,最大可调至 60 秒。该值必须能整除 60(即必须是 60 的因子)

scheduler_interval 的合法性在源码中被双重校验:Consumer.__init__ 要求它是 60 的因子(huey/consumer.py),ConsumerConfig.validate() 还要求其落在 1~60 之间(huey/consumer_options.py)。原因在调度器实现里写得很清楚:调度器按 interval 周期醒来读取任务调度表,同时每 60 秒检查一次周期任务(huey/consumer.py),只有整除 60 才能让两类检查对齐。

调度选项

选项 说明
-n, --no-periodic 让该消费者进程不入队周期任务。当多个消费者共享一个队列时,除一个之外的所有消费者都应加上此选项,确保周期任务只被入队一次,而不是每个消费者各入队一次

综合示例

官方文档给出了四个覆盖典型场景的完整命令:

# 8 个线程 + 错误日志文件 + 最小化日志
huey_consumer my.app.huey -l /var/log/app.huey.log -w 8 -q

# 多进程:4 个 Worker 进程
huey_consumer my.app.huey -w 4 -k process

# 单线程 + 禁用周期任务 + 详细日志输出到 stderr
huey_consumer my.app.huey -v -n

# 50 个 greenlet + 关闭健康检查 + 调度粒度 60 秒
huey_consumer my.app.huey -w 50 -k greenlet -C -s 60

Worker 类型:thread、process 与 greenlet

消费者由三个并发组件构成:主进程(main process)、调度器(scheduler)和一个或多个 Worker。Huey 为这三者的并发提供了三种执行环境,它们在 huey/consumer.py 中分别由 ThreadEnvironment、ProcessEnvironment、GreenletEnvironment 实现,Worker 类型常量定义在 huey/constants.py。

thread(默认):均衡之选

使用操作系统线程。由于 Python 全局解释器锁(GIL)的存在,同一时刻只有一个线程在运行,Python 运行时会在发生 I/O 或线程空闲时切换运行线程;如果 Worker 是 CPU 密集型的,运行时默认约 5ms 后抢占式切换。线程在性能与内存效率之间提供了良好平衡——你能享受抢占式多任务,又不必承担多进程的开销。拿不准时,thread 就是最安全的选择。

process:绕开 GIL 的 CPU 密集方案

调度器与 Worker 各自运行在独立进程中。相比线程的最大优势是没有 GIL,CPU 密集型 Worker 可以真正并行执行。代价是每个进程在内存中各持有一份代码副本,内存占用大概率高于线程与 greenlet。

⚠️ Windows 限制:多进程支持在 Windows 上不可用。Windows 唯一可用的进程启动方式是 spawn,它要求把 Huey 状态 pickle 序列化,而 Huey 使用(并创建)了大量无法 pickle 的对象。源码中 ProcessEnvironment 直接通过 multiprocessing.get_context('fork') 获取启动上下文,拿不到 fork 就抛出 ConfigurationError,明确说明 process 类型要求 fork 启动方式(huey/consumer.py)。

greenlet:IO 密集型的协作式方案

调度器与 Worker 运行在 greenlet 中,需要安装 gevent。当任务执行可能阻塞的操作(socket 读写)时,文件描述符被交给 gevent 管理的事件循环,调度器会切换任务。由于 gevent 是协作式多任务,一个 CPU 密集型任务不会把控制权交还给 gevent 调度器,并发度反而受限。因此 greenlet 适合大量 socket I/O 的任务(比如爬网站)。用 Redis 时务必把连接池放大到每个 greenlet 都能拿到独立连接。

使用 gevent 的正确姿势

gevent 通过 monkey-patch 各种 Python 模块(socket、ssl、time 等)工作。为了让应用能可靠切换任务,必须把 monkey-patch 放在代码最开头,早于任何其他模块加载:

# main.py
from gevent import monkey; monkey.patch_all()

from .app import wsgi_app   # 导入我们的 WSGI 应用
from .db import database    # 数据库连接
from .queue import huey     # 应用的 Huey 实例
from .tasks import *        # 导入所有任务,让它们可被发现

启动命令:

huey_consumer main.huey -k greenlet -w 16

源码对此还有一道运行时防线:Consumer.start() 在 greenlet 模式下会检查 monkey.is_module_patched('socket'),如果发现没有应用 monkey-patch,就记录一条 warning,提示可能导致错误或不可预测的行为(huey/consumer.py)。

消费者的启动与关闭:信号语义

优雅关闭与立即中断

消费者的信号行为在 docs/deployment.rst 中有精确的对照表:

信号 消费者行为
SIGINT 优雅关闭:Worker 完成当前任务后进程退出
SIGTERM 立即关闭:正在运行的任务被中断,每个被中断任务发出 SIGNAL_INTERRUPTED 信号
SIGHUP 优雅重启:Worker 完成当前任务后,消费者在原地重新执行自己(os.execl 原地换血,PID 不变)

出于历史原因,优雅关闭默认绑定 SIGINT,但大多数进程管理器用 SIGTERM 停进程。因此生产环境应运行 -g TERM(即 --graceful-signal=TERM)把两者对调:SIGTERM 走优雅路径,SIGINT 立即中断。下文的 systemd、supervisord、Docker 配置示例全都这样做。当然也可以反过来:让进程管理器用 SIGINT 停 Huey(systemd 写 KillSignal=SIGINT,supervisord 写 stopsignal=INT,Dockerfile 写 STOPSIGNAL SIGINT,Kubernetes 同样会遵从)。

源码中的信号处理非常清晰:默认 _signals = (SIGINT, SIGTERM),-g TERM 时对调为 (SIGTERM, SIGINT);_handle_graceful_signal、_handle_stop_signal、_handle_restart_signal 三个处理器只设置简单的标志位,由主循环统一消费(huey/consumer.py)。优雅关闭时 stop(graceful=True) 会先 _join_workers() 等待在途任务,超时(--shutdown-timeout)后调用 _interrupt_workers() 强制中断(huey/consumer.py)。

关闭超时与任务丢失的真相

Huey 不保证消息的至少一次投递,也不对已完成任务做确认(acknowledgement)。 这意味着如果你没有让消费者完成正在执行的任务就终止它,那些任务就永久丢失了。--shutdown-timeout 必须比进程管理器自己的 SIGKILL 期限短几秒,让 Huey 先优雅地中断掉队的任务(每个都会发 SIGNAL_INTERRUPTED),再轮到管理器发 SIGKILL。各管理器的默认期限如下:

管理器 默认期限 对应设置
systemd 90s TimeoutStopSec
supervisord 10s stopwaitsecs
Docker 10s docker stop -t、stop_grace_period
Kubernetes 30s terminationGracePeriodSeconds

如果你有长任务,要同步调大期限和超时。想在被中断时收到告警,可以使用 Huey 的 SIGNAL_INTERRUPTED 信号(见"消费者信号"一节)。

生产部署:supervisord、systemd、Docker 与 Kubernetes

完整的部署示例与生产检查清单在 docs/deployment.rst 与 examples/deploy 目录中。核心原则只有一条:消费者是一个普通的前台 Python 进程,不守护化、不写 pid 文件、不管理自身生命周期——这些是进程管理器的事。

systemd

参考 examples/deploy/huey.service:

[Unit]
Description=huey consumer for my_app
After=network.target redis.service

[Service]
Type=exec
User=appuser
Group=appuser
WorkingDirectory=/srv/my_app
# 直接运行消费者(不要套 shell 脚本),确保信号直达 Python 进程。
# -g TERM 让 systemd 的停止信号 SIGTERM 变成优雅关闭。
ExecStart=/srv/my_app/venv/bin/huey_consumer my_app.huey -w 4 -k thread -g TERM -t 55

# SIGKILL 期限。消费者的 -t 55 会在此之前打断仍在运行的任务,
# 发出 SIGNAL_INTERRUPTED,确保任务不会被 SIGKILL 白白丢掉。
TimeoutStopSec=60

# "systemctl reload huey" 映射到 Huey 的优雅重启(SIGHUP),
# 消费者原地 re-exec 自己,PID 不变。
ExecReload=/bin/kill -HUP $MAINPID

Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

安装并启动:

sudo cp huey.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now huey

要点:journald 会捕获 stdout/stderr,所以不要加 -l 日志文件选项,用 journalctl -u huey 看日志;systemctl reload huey 触发 SIGHUP 优雅重启且 PID 不变,务必避免 Type=forking(Type=exec 才正确,还能在启动时直接报告启动错误);Restart=on-failure 在崩溃后重启但在干净退出(如优雅 kill -TERM)后保持停止,想无条件拉回就用 Restart=always(两种设置下 systemctl stop 都不会触发自动重启)。

supervisord

参考 examples/deploy/supervisor.conf:

[program:huey]
directory=/srv/my_app
; 直接运行消费者(不要 shell 包装),确保信号直达 Python 进程。
; -g TERM 让 supervisor 的停止信号 TERM 变成优雅关闭。
command=/srv/my_app/venv/bin/huey_consumer my_app.huey -w 4 -k thread -g TERM -t 55
user=appuser
autostart=true
autorestart=true

; SIGKILL 期限(默认 10)。消费者的 -t 55 会在此之前打断仍在运行的任务,
; 发出 SIGNAL_INTERRUPTED,确保任务不会被 SIGKILL 丢掉。
stopwaitsecs=60

stdout_logfile=/var/log/huey/stdout.log
stderr_logfile=/var/log/huey/stderr.log
environment=PYTHONUNBUFFERED="1"

要点:如果你的应用模块不在 Python 路径上,可以加 environment=PYTHONPATH="/srv/my_app" 或把 directory 指向项目根目录(消费者从 directory 启动);supervisor 不做 shell 展开,所以这里不能写字面量 $PYTHONPATH。改完配置后执行 supervisorctl reread && supervisorctl update。

Docker 与 Docker Compose

参考 examples/deploy/Dockerfile 与 examples/deploy/compose.yaml:

  • 务必使用 CMD 的 exec 形式(JSON 数组、无 shell),让消费者成为 PID 1 并直接接收信号。
  • -g TERM 让 docker stop 请求优雅关闭;但默认宽限期只有 10 秒,所以要用 docker stop -t 60 <container>(或在 compose 里设 stop_grace_period)去匹配消费者的 -t 55。
  • process Worker 类型在容器里完全没问题;greenlet 记得在入口模块顶部应用 monkey-patch。
  • web 应用与 worker 共享同一镜像,因此两者导入的是同一份代码与同一个任务注册表。
  • 扩展 worker 服务时(docker compose up --scale worker=3)要注意:每个消费者都会独立入队周期任务。 正确做法是:单独跑一个专职的周期任务消费者(不带 -n),被横向扩展的 worker 全部加 -n / --no-periodic。
  • 多个容器只能通过网络可访问的存储后端(Redis、Postgres)共享队列;SqliteHuey 和 FileHuey 只有在所有容器挂载同一本地卷时才能跨容器工作,而 sqlite 跑在网络文件系统上是糟糕的主意。

Kubernetes 与 PaaS

一个最小 worker Deployment 片段:

spec:
  containers:
  - name: huey-worker
    image: my-app:latest
    command: ["huey_consumer", "my_app.huey", "-w", "4", "-n",
              "-g", "TERM", "-t", "55"]
  terminationGracePeriodSeconds: 60
  • kubelet 发送 SIGTERM,-g TERM 让它变成优雅关闭。
  • terminationGracePeriodSeconds 是 SIGKILL 期限,必须大于 --shutdown-timeout,让掉队任务先被干净打断。
  • replicas > 1 时周期任务只能由一个消费者入队:可横向扩展的 worker 加 -n,另起一个单副本的 "scheduler" Deployment 不带 -n。

PaaS(Heroku 风格)的 Procfile 形如:

web: gunicorn my_app.wsgi
worker: huey_consumer my_app.huey -w 4 -k thread -g TERM -t 25

这类平台发 SIGTERM 且宽限期短(通常约 30 秒)且无法自定义信号,所以必须 --graceful-signal=TERM、--shutdown-timeout 比宽限期短几秒,并注册 SIGNAL_INTERRUPTED 重新入队处理器。存储位置从环境变量读取:

import os
from huey import RedisHuey

huey = RedisHuey('my-app', url=os.environ['REDIS_URL'])

日志轮转与健康检查

  • 在 systemd、Docker、PaaS 下,让日志走 stderr(不加 -l 的默认行为),由平台统一采集。

  • 其他方式监管时用 -l /var/log/huey.log,但消费者长期持有该文件句柄且没有收到信号重新打开文件的机制,所以 logrotate 必须用 copytruncate:

    # /etc/logrotate.d/huey
    /var/log/huey.log {
        weekly
        rotate 8
        compress
        copytruncate
        missingok
    }
    
  • 健康检查方面,消费者自己会监控 Worker 并重启死亡的 Worker(-c 选项),外部存活探针主要确认进程在跑、存储后端可达即可。一个极简探针脚本:

    # huey_health.py - 存储后端不可达时以非零码退出。
    from my_app import huey
    huey.pending_count()
    

生产检查清单(速查)

来自 docs/deployment.rst 的核对项:

  • 消费者以 -g TERM 运行,或 supervisor 用 SIGINT 停 Huey;
  • --shutdown-timeout 比进程管理器的 kill 超时短几秒;
  • 注册 SIGNAL_INTERRUPTED 处理器,把被打断的任务重新入队;
  • 恰好一个消费者入队周期任务,其余全部加 -n;
  • 消费者被直接运行,没有 shell 脚本包装;
  • 结果数据被读取(或过期),避免结果存储无限增长(读结果、返回 None,或用 RedisExpireHuey);
  • 使用 Huey.lock_task 的话,用 -f / --flush-locks 清理崩溃遗留的锁;
  • Worker 数量与类型匹配工作负载;
  • 生产环境关闭 immediate 模式(它是默认值,但 Django 用户要复查,因为 djhuey 在 DEBUG=True 时会开启它);
  • 存储后端共享或网络暴露时,用 SignedSerializer 给消息签名;
  • systemd/Docker/PaaS 下日志走 stderr,用 -l 时用 copytruncate 轮转。

部署新代码与多消费者

优雅滚动升级

部署新代码时,最佳策略是先优雅关闭旧消费者,让所有在跑任务完成,再启动加载新代码的新消费者。如果存在超长任务,另一个方案是让新代码使用独立的存储命名空间:在 Redis 上只需给 RedisHuey() 指定一个新的 name,然后启动新代码与新消费者,它们与旧消费者完全独立运作;等旧队列清空后,优雅关闭旧消费者即可。进程内缓存了任务代码意味着每次发布都必须重启(或 SIGHUP 原地重启)消费者。

多消费者:一队列多进程

Huey 通常跑在单台服务器上,靠增加 Worker 数量来应对负载;但也可以在多台服务器上运行多个消费者。此时至关重要的一点:只允许一个消费者入队周期任务。默认每个消费者都会在周期任务到期时入队,因此多消费者场景下,除一个外其余全部要加 -n / --no-periodic。例如:

  • 服务器 A(主):huey_consumer myapp.huey -w 8 -k process
  • 服务器 B:huey_consumer myapp.huey -w 8 -k process --no-periodic
  • 服务器 C:huey_consumer myapp.huey -w 8 -k process --no-periodic

由于每个消费者都必须能访问同一个队列与结果存储,必须使用 Redis 或其他网络可访问的存储后端。注意:这里讲的是多个消费者共享一个队列;如果要跑多个队列,需要采用 recipe 中 multiple-queues 的方案。

消费者内部原理:一条任务的生命周期

官方文档建议结合 huey/consumer.py 阅读本节。一条任务从产生到执行完毕大致经历四步:

  1. 入队:你的应用调用被 @huey.task() 装饰的函数,触发一条消息写入队列(例如一个 Redis list)。应用立即返回一个 Result 对象,不阻塞等待执行结果。
  2. 取出:消费者进程中的某个 Worker 正在监听新消息,收到消息后解析出"执行哪个任务、何时执行、带什么参数"。
  3. 判断:Worker 检查这条消息能否立即执行。若被调度到未来执行,加入调度表(schedule);若已被 revoke 或已过期,直接丢弃;否则进入执行。
  4. 执行:Worker 执行任务。成功则结果写入结果存储;失败则检查该任务是否可以重试——依据任务的 retry_delay,Huey 要么立刻把任务重新入队,要么告诉调度器在何时重新入队。

在 Worker 忙碌的同时,Scheduler 在查看自己的调度表,确认是否有任务到期可执行;到期任务被入队,等待下一个空闲 Worker 处理。如果使用了周期任务(cron)功能,那么每隔一分钟调度器会检查一遍周期任务,把到期的入队。

三个组件的源码级解读

  • Worker(huey/consumer.py):核心 loop() 反复调用 self.huey.dequeue();拿到任务就重置轮询延迟并 self.huey.execute(task, now);空队列且存储非阻塞时执行退避 sleep。initialize() 会执行 Huey 实例注册的启动钩子,shutdown() 执行关闭钩子(这解释了消费者内外的资源初始化方式)。
  • Scheduler(huey/consumer.py):loop() 按 interval 调用 huey.read_schedule(now) 并把到期任务 enqueue;若启用周期任务且到了 60 秒周期,则调用 read_periodic(now) 入队周期任务。它只负责入队,从不执行任务——执行始终由 Worker 完成。调度器还有防重放保护:若因挂起/恢复而错过多个周期,会跳过错过的检查而不是连续补跑,避免同一分钟内重复入队。
  • 主循环与健康检查(huey/consumer.py):run() 启动调度器与全部 Worker、注册信号处理器后进入主循环;每 health_check_interval 检查一次,任何死亡的 Worker 或调度器都会被重建重启。收到优雅信号后 stop(graceful=True) 等待在途任务(受 --shutdown-timeout 约束);收到 SIGHUP 则置 _restart=True,退出前用 os.execl 以相同参数原地重启自己。

一个值得注意的启动校验:Consumer.start() 和构造函数都会检查 huey.immediate。如果 Huey 实例开启了 immediate 模式,启动消费者会抛出 ConfigurationError(构造函数仅记录 warning)——因为 immediate 模式下任务在调用进程内同步执行,根本不需要也不允许消费者进程(huey/consumer.py)。

消费者信号

消费者在任务执行过程中会发出若干信号,回调以信号处理器形式注册。完整信号参考见 docs/signals.rst,核心信号包括:

信号 触发时机
SIGNAL_ENQUEUED 任务入队。在应用进程(你调用任务时)和消费者进程(重新入队重试/周期/调度任务时)都会发出
SIGNAL_EXECUTING 任务即将被 Worker 执行
SIGNAL_COMPLETE 任务成功完成且结果已存入结果存储
SIGNAL_ERROR 任务执行中抛出未处理异常(额外参数 exc:异常实例)
SIGNAL_CANCELED 任务被取消(pre_execute 钩子或任务自身抛出 CancelExecution)
SIGNAL_RETRYING 任务失败但将重试
SIGNAL_SCHEDULED 任务未到期,已加入调度表(有 eta 或 retry_delay)
SIGNAL_REVOKED 任务被撤销,不再执行
SIGNAL_EXPIRED 任务已过期,不再执行
SIGNAL_LOCKED 任务无法获取锁(Huey.lock_task),不会执行
SIGNAL_TIMEOUT 任务超过执行超时
SIGNAL_RATE_LIMITED 任务被 Huey.rate_limit 限流
SIGNAL_INTERRUPTED 消费者关闭时任务仍在执行(如收到 SIGTERM)

信号按确定顺序发出:成功执行是 ENQUEUED → EXECUTING → COMPLETE;失败重试是 ENQUEUED → EXECUTING → ERROR(exc) → RETRYING → (SCHEDULED 或 ENQUEUED);调度任务是 ENQUEUED → SCHEDULED →(到期后消费者内)ENQUEUED → EXECUTING → COMPLETE/ERROR;撤销是 ENQUEUED → REVOKED。

注册处理器用 @huey.signal(),不指定信号名则注册到内部 "any" 频道(即监听所有信号):

@huey.signal()
def all_signal_handler(signal, task, exc=None):
    print('%s - %s' % (signal, task.id))

@huey.signal(SIGNAL_ERROR, SIGNAL_LOCKED, SIGNAL_CANCELED, SIGNAL_REVOKED)
def task_not_executed_handler(signal, task, exc=None):
    print('[%s] %s - not executed' % (signal, task.id))

@huey.signal(SIGNAL_COMPLETE)
def task_success(signal, task):
    pass

用 huey.disconnect_signal(handler) 注销,可指定只注销某个信号。

用 SIGNAL_INTERRUPTED 挽回丢失的任务

用 SIGTERM(未配 -g TERM 时)关闭消费者会立即中断在跑任务,这些任务默认不会被重试。避免丢失的标准做法是注册中断处理器把它们重新入队:

@huey.signal(SIGNAL_INTERRUPTED)
def on_interrupted(signal, task, *args, **kwargs):
    huey.enqueue(task)

注意两个性能与健壮性要点(同样来自 docs/signals.rst):

  • 信号处理器由消费者同步执行(SIGNAL_ENQUEUED 除外,它还在你的应用进程里跑)。一个慢处理器(比如往一个宕机的 REST API 发数据)会阻塞整个消费者,导致无法处理下一个任务。处理器里还要注意共享资源(数据库连接、打开的文件句柄)的管理。
  • 处理器抛异常不会拖垮消费者:Huey 会记录异常但继续处理,一个坏处理器既不影响其他处理器,也不影响任务的执行与结果存储。
  • 信号在 immediate 模式下同样会发出,这让你可以不启动消费者就轻松测试处理器。

小结

Huey 的消费者是一个结构清晰、参数克制的常驻进程:huey_consumer 负责把它指向你的 Huey 实例,-w/-k 决定并发形态(线程/进程/greenlet),-d/-m/-b 控制轮询节奏,-c/-f/-M/-t/-g 覆盖健康检查、锁清理、进程回收与优雅关闭,-n/-s 管理调度行为。生产部署时记住几条铁律:直接运行消费者(不套 shell)、-g TERM + 略短于管理器期限的 -t、恰好一个消费者管周期任务、用 SIGNAL_INTERRUPTED 兜底中断任务。结合 huey/consumer.py 的源码和 examples/deploy 的现成配置,即可把一套可靠的任务消费集群投入生产。

登录后查看全文
huey