一次常规发布之后,运维发现队列在十分钟内堆到了三万条,用户收不到短信,订单状态也不更新。查下来是发布脚本先重启了机器,Supervisor 把 worker 停了,新代码起来后没有人手动启动 worker,任务只进不出。积压本身不是代码 bug,是发布顺序漏了一步。
另一次更隐蔽。一个发邮件的任务在处理到一半时被 kill,队列里那条记录还在,几秒后另一个 worker 又把它取出来重跑。用户收到两封一样的邮件,财务系统里也多了一条重复流水。开发的第一反应是「队列不可靠」,实际原因是任务本身不幂等,而队列的语义本来就是「至少执行一次」。
队列把「必须当场做完的」和「可以晚点做的」分开,代价是引入了一整套新的失败模式:任务会重复、会丢、会堆积、会耗尽内存。这篇讲清楚这套机制怎么运转,以及每个失败模式该在哪里设防。
队列里的一个任务经历了什么
队列(queue)是一个「待办清单」,应用把任务写进去,另一组常驻进程按顺序取出来执行。在 Laravel 里,投递方调用 dispatch,消费方是 queue:work 命令启动的 worker 进程。
关键在第三步「取出并保留」。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-time | worker 运行多久后优雅退出 | 不设则长期不重启,内存缓慢上涨 |
--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 的队列抽象也不再适用。选型要在任务量还小的时候定,别等积压成灾再迁。
当天能自己验证的练习
- 把
QUEUE_CONNECTION设成database,执行queue:table和migrate,投递一个任务后用select * from jobs看 payload 与尝试次数。 - 用
php artisan queue:work --once消费一条任务,观察jobs表行数变化,以及failed_jobs是否为空。 - 故意在任务里抛异常,把
--tries设为 1,确认任务进入failed_jobs,再用queue:retry重跑。 - 把
timeout设为 5、retry_after设为 6,运行一个 sleep 8 秒的任务,观察它是否被第二个 worker 重复领取。 - 在
routes/console.php加一条每分钟执行的调度,用schedule:list确认下次执行时间,再用schedule:work观察实际触发。
小结
三句话:队列是至少一次语义,任务必须幂等;timeout 和 retry_after 要成对配置,worker 用 Supervisor 守护并在发布时 queue:restart;调度只写在 routes/console.php,cron 只跑 schedule:run。
下一篇讲上线。队列、路由、数据库在本地都能跑通之后,真正的分界线是发布:配置怎么缓存、迁移按什么顺序执行、队列什么时候重启、日志写到哪里、健康检查查什么、出问题怎么回滚。下一篇从一个「本地正常、上线 500」的配置缓存事故开始,把整组内容收到发布流程上。