一次常规发布之后,运维发现队列在十分钟内堆到了三万条,用户收不到短信,订单状态也不更新。查下来是发布脚本先重启了机器,Supervisor 把 worker 停了,新代码起来后没有人手动启动 worker,任务只进不出。积压本身不是代码 bug,是发布顺序漏了一步。

另一次更隐蔽。一个发邮件的任务在处理到一半时被 kill,队列里那条记录还在,几秒后另一个 worker 又把它取出来重跑。用户收到两封一样的邮件,财务系统里也多了一条重复流水。开发的第一反应是「队列不可靠」,实际原因是任务本身不幂等,而队列的语义本来就是「至少执行一次」。

队列把「必须当场做完的」和「可以晚点做的」分开,代价是引入了一整套新的失败模式:任务会重复、会丢、会堆积、会耗尽内存。这篇讲清楚这套机制怎么运转,以及每个失败模式该在哪里设防。

队列里的一个任务经历了什么

队列(queue)是一个「待办清单」,应用把任务写进去,另一组常驻进程按顺序取出来执行。在 Laravel 里,投递方调用 dispatch,消费方是 queue:work 命令启动的 worker 进程。

一个队列任务的生命周期
dispatch 投递
写入队列存储
worker 取出并保留
执行 handle
删除或失败重试

关键在第三步「取出并保留」。worker 取到任务后不会立刻删除,而是标记为已保留(reserved),执行成功才删除;执行中进程挂了,保留超时后任务重新可见,会被再次取出。这个机制保证了「任务不会因为 worker 崩溃而消失」,也直接导致了「同一个任务可能被执行多次」。

所以队列的语义是「至少一次」(at least once),不是「恰好一次」。任何依赖队列的任务都必须假设自己会被执行两遍,这就是后面要讲幂等的原因。想要「恰好一次」,只能在业务层用唯一键、状态位或数据库约束去重,队列本身给不了。

database 还是 Redis

Laravel 支持多种队列驱动:sync 是同步执行,用来本地调试;database 把任务存进数据库表;redis 存进 Redis;另外还有 SQS、Beanstalkd 等。sync 会让 dispatch 当场执行完,线上误用会直接把请求拖死,所以生产环境的 QUEUE_CONNECTION 绝不能是 sync。

database 驱动

任务存在 jobs 表,不需要额外组件,运维看得见、能直接查、能手工重跑。代价是 worker 轮询数据库,量大时会产生明显的查询压力和锁竞争,延迟也偏高。

Redis 驱动

内存结构,取出和投递都快,延迟低,适合任务量大或对时效敏感的场景。代价是多一个必须高可用的组件,且要配置持久化,否则 Redis 重启会丢任务。

取舍的实用标准:日任务量在几千到几万、延迟要求是分钟级,database 完全够用,而且排查方便;任务量到几十万、或者需要秒级触发,再上 Redis。不要在项目初期就为了「先进」上 Redis,多一个组件的运维成本和故障面是真实的。

驱动之外还有一个维度是队列名。任务可以投递到不同的队列,worker 用 --queue=high,default 按顺序消费,高优先级的队列先取。邮件、短信这类用户可感知的任务放 high,报表生成、数据同步放 low,一个慢任务就不会堵住所有通知。队列名是逻辑划分,不需要为每个名字单独起 worker,除非你确实想给高优先级分配更多进程。

任务还有延迟投递的能力,->delay(now()->addMinutes(10)) 让任务十分钟后才可见。database 驱动用 available_at 字段实现,Redis 驱动用有序集合实现,语义一致。延迟任务不要用来做「精确到秒」的定时,worker 的空闲轮询间隔会带来误差,真正的定时用调度器。

如果选 Redis,必须确认持久化配置。appendonly yes 打开 AOF,并设置合理的 appendfsync;同时给 Redis 设置 maxmemory-policy noeviction,不要用 allkeys-lru,否则内存吃紧时队列键会被当成缓存淘汰掉,任务凭空消失。这两项和缓存用法是冲突的,很多团队会把队列和缓存拆到两个 Redis 实例。

表结构与失败记录

用 database 驱动需要两张表:jobs 存待执行任务,failed_jobs 存最终失败的任务。生成迁移并执行:

php artisan queue:table
php artisan queue:failed-table
php artisan migrate

jobs 表的每一行是一条序列化后的任务,包含队列名、payload、尝试次数、保留时间等字段。payload 里是任务类名和构造参数,所以任务类的构造参数必须是可序列化的简单值。传整个模型时框架会只序列化主键,执行时再按主键重新查询;这也意味着执行那一刻查到的数据可能已经变了,任务里要自己判断当前状态是否还满足执行条件。

failed_jobs 表记录异常信息、堆栈和失败时间。这张表不是垃圾桶,是排查入口:php artisan queue:failed 列出失败任务,queue:retry {id} 重试单条,queue:retry all 全部重试,queue:flush 清空。清空之前一定先看失败原因,直接 flush 等于把现场证据删了。

表会持续增长。生产环境要定期归档失败记录,或者在确认无用后按时间清理;jobs 表在任务正常消费后行会被删除,不需要额外清理,但如果长期积压,表会膨胀到影响查询,这本身就是需要处理的故障信号。

worker 参数与进程守护

worker 是常驻进程,靠命令行参数控制它的行为。几个参数直接影响可靠性,必须一起看:

参数作用设错的后果
--tries最多尝试次数设成 1,临时故障直接进失败表
--timeout单条任务最长执行秒数设得太短,长任务被误杀
--max-timeworker 运行多久后优雅退出不设则长期不重启,内存缓慢上涨
--memory进程内存上限,超过即退出不设则可能被系统 OOM 杀掉
--sleep没任务时轮询间隔设太小空转,数据库压力上升
--backoff失败后延迟重试的秒数不设则立即重试,打爆下游

--timeout 和配置文件里的 retry_after 有一个硬关系:retry_after 必须大于 timeout。否则任务还在执行,保留时间就到了,另一个 worker 会把它当成超时任务再取走,于是同一条任务被两个进程同时跑。这是「同一任务跑两遍」最常见的原因,改参数时两个值要一起改。timeout 设为 60,retry_after 至少设 90。

worker 不能靠手工 nohup 启动,要用进程守护工具。Supervisor 是最常见的选择,配置大致如下:

[program:cms-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /srv/cms/current/artisan queue:work --tries=3 --timeout=60 --max-time=3600 --memory=512 --sleep=3
autostart=true
autorestart=true
numprocs=4
user=www-data
redirect_stderr=true
stdout_logfile=/srv/cms/shared/storage/logs/worker.log
stopwaitsecs=90

stopwaitsecs 要大于单条任务的最长耗时,这样重启时 Supervisor 会等当前任务执行完再杀进程,而不是半路掐断。numprocs 不是越大越好,每个 worker 都占一条数据库连接,前面算连接数时要把它算进去。

本地开发常看到另一个命令 queue:listen,它每次处理任务都会重新启动一次框架,改代码立刻生效,代价是慢。线上要用 queue:work,进程常驻、框架只启动一次,但改代码必须重启或 queue:restart。这两个命令混用会造成「本地改了有效、线上改了无效」的错觉。

发布时还要执行一次 php artisan queue:restart。它不会立刻杀进程,而是给所有 worker 发一个「干完当前任务就退出」的信号,Supervisor 再把它们拉起来,新进程加载新代码。漏了这一步,worker 会一直跑旧代码,表现出来就是「代码改了、任务行为没变」。

幂等、去重与并发限制

既然任务可能执行多次,第一道防线是幂等(idempotency):同一个任务执行两遍,结果和执行一遍一样。实现方式通常是一个业务唯一键或状态位,执行前检查、执行后落标记:

public function handle(): void
{
    $order = Order::find($this->orderId);

    if ($order === null || $order->invoice_sent_at !== null) {
        return;
    }

    Mail::to($order->email)->send(new InvoiceMail($order));

    $order->forceFill(['invoice_sent_at' => now()])->save();
}

这段代码在并发下仍有窗口:两个 worker 同时读到 invoice_sent_at 为空,都往下走。更稳的做法是用数据库唯一约束或原子更新来抢占,比如 update ... where invoice_sent_at is null,只有影响行数为 1 的那个进程继续发邮件。涉及钱的逻辑不能只靠「先查再写」。

Laravel 还提供几个声明式的去重工具。ShouldBeUnique 让同一个唯一键的任务在队列里只存在一个,重复投递会被丢弃;WithoutOverlapping 中间件保证同一个键同一时间只有一个实例在跑,后到的可以选择释放回队列;RateLimited 限制单位时间内的执行次数,适合调用有配额的第三方接口。

public function middleware(): array
{
    return [
        (new WithoutOverlapping($this->orderId))
            ->releaseAfter(10)
            ->expireAfter(300),
    ];
}

这三个工具都依赖锁,锁存在缓存里,所以多机部署时缓存必须共享(Redis 或数据库),不能用文件缓存。锁还有过期时间,expireAfter 要大于任务最长执行时间,否则任务没跑完锁先没了,另一个进程就能进来。

定时任务:cron 只跑一行

定时任务(scheduler)解决「每隔一段时间做一件事」。Laravel 11 起没有 app/Console/Kernel.php,调度写在 routes/console.php:

use Illuminate\Support\Facades\Schedule;

Schedule::command('orders:sync')->everyFiveMinutes()->withoutOverlapping();
Schedule::job(new PruneExpiredTokens)->dailyAt('02:30');
Schedule::command('reports:daily')->dailyAt('06:00')->onOneServer();

服务器上的 cron 只需要一行,每分钟调用一次调度器,由它判断这一分钟该跑哪些任务:

* * * * * cd /srv/cms/current && php artisan schedule:run >> /dev/null 2>&1

不要为每个任务单独写一条 cron。那种写法把时间规则分散到系统配置里,代码和配置对不上,换机器就漏;统一走 schedule:run,规则只存在代码里,可测试、可版本管理。

多机部署时,定时任务会在每台机器上同时触发。加 onOneServer() 可以让同一时刻只有一个实例执行,它依赖共享缓存锁;加 withoutOverlapping() 可以防止上一次还没跑完下一次又开始。两者含义不同,前者是「多机只跑一个」,后者是「同一任务不并发」,需要时两个都要加。

本地开发不要等 cron,直接跑 php artisan schedule:work,它会每分钟执行一次调度,并在前台输出每次触发了什么。上线前用 php artisan schedule:list 核对所有任务的下次执行时间和时区,时区不一致会导致「凌晨两点的任务在下午两点跑」。

失败任务与 Horizon

任务失败后的处理分三层。第一层是自动重试,由 --tries 和 --backoff 控制;第二层是任务自己的 failed() 方法,可以在最终失败时写一条告警或补偿记录;第三层是人工介入,通过 queue:failed 查看、queue:retry 重跑。

失败不等于异常。任务里抛异常会被记为失败并重试;如果任务自己捕获了异常却什么也不做,队列会认为它成功了,这条任务就静默丢失。要主动放弃时调用 $this->fail(),让失败表留下记录,而不是 return 一个空。

Horizon 是官方提供的 Redis 队列管理面板,能看吞吐、等待时间、失败率和每个队列的 worker 数,也能在界面上重试任务。它只支持 Redis 驱动,database 驱动用不了。安装用 composer require laravel/horizon 加 php artisan horizon:install,上线前必须在 AppServiceProvider 里配置访问授权,否则面板对公网开放等于把队列数据送出去。

任务量不大时不必上 Horizon。它自己也是一个常驻进程,要单独守护、单独重启,面板还要配权限,收益只在「队列多、需要看曲线」时才明显。只有一两个队列的项目,用 queue:failed 加日志和告警就够了。

Horizon 的进程模型和 Supervisor 不同:它自己管理一组 worker,发布时执行 php artisan horizon:terminate 让它优雅重启,而不是 queue:restart。两者别混用,混用的结果是进程被反复拉起又退出。

完整链路:下单后异步发邮件

依赖方面,Laravel 12 自带队列组件,不需要额外安装包;邮件用框架自带的 Mail 组件,本地可以用 log 驱动,不真的发出去。先确认 .env 里 QUEUE_CONNECTION=database,再建表:

php artisan queue:table
php artisan queue:failed-table
php artisan migrate
php artisan make:job SendInvoice

任务类实现 ShouldQueue,构造时只传订单 ID,handle 里重新查询并做幂等判断。触发接口只投递,不等待结果,返回 202 表示「已接受」:

Route::post('/v1/orders/{order}/invoice', function (Order $order) {
    SendInvoice::dispatch($order->id);

    return response()->json(['queued' => true], 202);
});

服务用等价的 php -S 起好后,先调用接口把任务放进队列,再用 --once 手动消费一条,观察输出:

curl -i -X POST http://127.0.0.1:8030/api/v1/orders/1/invoice \
  -H "Accept: application/json"

php artisan queue:work --once

本机实测两次调用都返回 202 和 {"queued":true},jobs 表里排进 2 条任务;两次 queue:work --once 跑完后 jobs 表为 0,日志按顺序出现 [2026-11-07 03:45:14] local.INFO: invoice sent {"order_id":1} 和 [2026-11-07 03:45:15] local.INFO: invoice skipped {"order_id":1},订单的 invoice_sent_at 被写入。重复调用确实只发一封,第二封被幂等判断挡住。

现象、原因与第一步

现象真实原因第一步查什么
任务只进不出worker 没启动,或发布时被停掉没拉起ps aux | grep queue:work;看 Supervisor 状态
同一任务执行两遍retry_after 小于 timeout,任务被重复领取对比 config/queue.php 与 worker 参数
任务跑一半就消失worker 被 kill,任务还在保留期,尚未重新可见看任务是否出现 jobs 表的 reserved_at
改了代码行为不变没有执行 queue:restart,worker 还在跑旧代码看 worker 启动时间与发布记录
任务全部进失败表下游服务不可用,或构造参数无法反序列化php artisan queue:failed 看异常原文
定时任务没触发cron 没配,或 schedule:run 路径指向旧目录看系统 crontab 与 schedule:list
多机重复跑定时任务没有加 onOneServer,缓存也未共享检查调度写法与 CACHE_STORE
worker 内存持续上涨长驻进程累积状态,未设 --max-time看进程内存;配置定时优雅重启

边界与代价

队列不是「免费的性能」。它把同步操作变成异步,用户看到的是「已受理」,真正的结果要靠轮询、推送或另一个接口查。产品上必须设计「处理中」和「失败」两种状态,否则用户永远不知道那条任务到底成没成。

至少一次语义决定了所有任务都要考虑重复。任务越复杂、涉及的副作用越多,幂等的成本越高。发邮件、发短信、扣库存、调支付,每一项都要单独设计去重键。这部分工作量经常被低估,最后变成线上重复扣款。

worker 的数量受数据库连接数和下游承载能力限制。加 worker 能提高吞吐,但下游接口有配额、数据库有连接上限,盲目扩容只是把压力转移到更脆弱的地方。真正的容量规划要看队列的等待时间曲线,而不是 worker 数量。

队列的等待时间要能被观测到。database 驱动可以按 created_at 算最老任务等了多久,Redis 可以读队列长度;更直接的做法是给「最老任务年龄」设一条告警线,超过五分钟就通知。没有这条曲线时,积压往往要靠用户投诉才发现,那时候已经晚了半小时。

换队列中间件的代价也不小。从 database 换到 Redis,任务代码基本不动,但运维要多一套高可用配置;从 Redis 换到 Kafka 这类消息平台,投递语义、消费组、分区都要重新设计,Laravel 的队列抽象也不再适用。选型要在任务量还小的时候定,别等积压成灾再迁。

当天能自己验证的练习

  1. 把 QUEUE_CONNECTION 设成 database,执行 queue:table 和 migrate,投递一个任务后用 select * from jobs 看 payload 与尝试次数。
  2. 用 php artisan queue:work --once 消费一条任务,观察 jobs 表行数变化,以及 failed_jobs 是否为空。
  3. 故意在任务里抛异常,把 --tries 设为 1,确认任务进入 failed_jobs,再用 queue:retry 重跑。
  4. 把 timeout 设为 5、retry_after 设为 6,运行一个 sleep 8 秒的任务,观察它是否被第二个 worker 重复领取。
  5. 在 routes/console.php 加一条每分钟执行的调度,用 schedule:list 确认下次执行时间,再用 schedule:work 观察实际触发。

小结

三句话:队列是至少一次语义,任务必须幂等;timeout 和 retry_after 要成对配置,worker 用 Supervisor 守护并在发布时 queue:restart;调度只写在 routes/console.php,cron 只跑 schedule:run。

下一篇讲上线。队列、路由、数据库在本地都能跑通之后,真正的分界线是发布:配置怎么缓存、迁移按什么顺序执行、队列什么时候重启、日志写到哪里、健康检查查什么、出问题怎么回滚。下一篇从一个「本地正常、上线 500」的配置缓存事故开始,把整组内容收到发布流程上。