"dsh-crew 派发不出去？五类报错照着查"——说实话，我第一次在生产环境看到任务全部堆在队列里、一个 worker 都没有响应的时候，第一反应是重启大法。结果没解决问题，反而把已经跑着的任务也弄丢了。后来才发现，这类"派发不出去"的故障，绝大多数都能归到几类固定报错上，排查路径也相当规律。
我这边内部叫 dsh-crew 的派发组件，简单说就是一套任务分发与执行机制：调度端负责从队列取任务，按照 worker 的能力和负载状态分派下去，worker 执行完再把结果写回。听起来不复杂，但真正跑起来，涉及注册、心跳、路由、状态存储、消息确认这么多环节，任何一个地方掉链子，任务就卡住了。这篇文章我就拿实际踩过的坑来说，把"派发不出去"最常见的五类报错，报错长什么样、为什么会出现、怎么一步步查，全部摊开讲清楚。无论你是刚接手这类系统，还是已经被折磨了好几轮，照着查基本能省下半天排查时间。
1. 先看派发链路的五个关键位点
排查"派发不出去"之前，我心里始终有一张链路图。dsh-crew 这类派发系统的数据流大概是这样：任务进入队列，调度器把队列里的任务捞出来，根据 worker 上报的能力和标签做路由匹配，然后下发执行指令，worker 启动任务进程，结束后回报状态，状态再写回存储。
这里面有五个位点是最容易出问题的：
| 位点 | 角色 | 出问题时的典型表现 |
|---|---|---|
| 接入端/生产者 | 提交任务进队列 | 任务根本没进队列，显示已提交但后续无状态 |
| 队列与消息通道 | 暂存和传递任务 | 任务堆积、重复消费、消息丢失 |
| 调度器/路由匹配 | 根据规则选择 worker | 日志报 no route、任务一直 pending |
| worker 注册与心跳 | 上报存活与能力 | worker offline、heartbeat timeout |
| 状态存储 | 记录任务和 worker 状态 | 状态不一致、锁过期、数据错乱 |
我习惯把这条链路想象成一个快递站：任务就是包裹，队列是传送带，调度器是分拣员，worker 是快递员，状态存储是站点的登记本。包裹派不出去，可能是传送带卡了（队列问题），可能是分拣员不知道哪个快递员能送这个件（路由问题），也可能是快递员根本没上班签到（心跳问题），还可能是登记本上写错了（状态存储问题）。
所以我不建议一上来就盯着调度器日志看。先问自己一个问题：任务到底卡在哪一步？是没进队列，进了队列没被消费，还是消费了但 worker 没收到？把位点定住，再去看对应环节的日志和指标，比大海捞针快得多。
2. 第一类报错：worker 掉线、心跳超时，调度端认为它不存在
这类报错是我遇到频率最高的一种。典型日志长这样：
[dispatcher] worker node-23 heartbeat timeout after 30s, mark as offline [dispatcher] task t-1024 cannot be dispatched: no alive worker target matched, retry in 5s第一次看到"no alive worker"的时候，我以为是 worker 崩了，但登录到机器上一看，执行进程还活着，CPU 也是正常的。这就是这类问题最迷惑人的地方：业务进程活着，但调度端已经认为你死了。
2.1 优先检查心跳链路本身的稳定性
心跳是 worker 和调度端之间维持"我还在"的约定。心跳发不出去，进程再健康也是白搭。常见的几个因素：
- 网络抖动和防火墙策略。心跳通常是短连接或者长连接上的定时消息，如果中间有防火墙对空闲连接做了回收，或者 worker 与调度端之间走的是跨网段链路并且有丢包，心跳就时断时续。
- 心跳线程被阻塞。不少 worker 的心跳和业务执行是在同一个进程里共用线程池的，如果某个任务执行时占住了线程池，心跳消息排队发不出去，调度端就会判定超时。我见过一次很典型的例子：某 worker 上跑了一个批量计算任务，把所有线程占满，心跳协程饿死，30 秒后调度端直接标记 offline。
- 本地时钟偏差。如果 worker 所在机器的时间比调度端快或者慢太多，心跳报文里带的时间戳就会让调度端觉得报文是过期数据，直接丢弃。时间同步这件事在分布式系统里真的不是小问题。
排查的时候，我习惯先看调度端日志里标记 offline 前，有没有收到 worker 最后一次心跳。把心跳的发送时间、接收时间、判定超时时间三个时间点列出来，就能大概判断是链路抖动、线程阻塞还是时钟问题。
2.2 用三个参数重新校准心跳策略
大多数心跳机制都有三个可调参数：心跳间隔、超时判定时间、失联后的重试次数。默认值往往偏保守。
| 参数 | 默认值 | 建议 | 说明 |
|---|---|---|---|
| heartbeat_interval | 5s | 10s | 间隔太短徒增压力，10 秒足够感知大多数故障 |
| heartbeat_timeout | 15s~30s | 60s | 给 GC 停顿和网络抖动留缓冲 |
| offline_retry | 3 | 5 | 避免一次抖动就立刻标记离线 |
我调过一版把超时时间从 15 秒拉到 60 秒，再配合指数退避重试，某开发环境的误判离线率直接从每周十几次降到接近零。当然，超时时间也不能无限拉长，否则 worker 真的挂了，调度端还要傻等一分钟才把任务重新派给别人，整体恢复速度会变慢。这个值要根据业务容忍度来选。
2.3 别忘了 worker 启动时的注册信息
还有一类隐蔽情况是注册信息冲突。worker 启动时会拿节点 ID、IP、端口去注册，如果同一个节点 ID 被两台机器同时使用（比如镜像克隆后没有重新生成 ID），新的注册会顶掉旧的，导致旧节点上的任务还没执行完，调度端就认为它已经不存在了，接着就把任务又派出去一次。
这种问题从日志表面看就是"worker 随机 offline"，但本质上不是心跳问题，而是身份冲突。排查时可以在调度端看一眼 worker 注册表的更新时间，如果某个节点 ID 的注册时间频繁变化，多半是有重复身份。
3. 第二类报错：队列消息重复消费、消费延迟，任务被卡在 pending
心跳没问题、worker 都活着，但任务就是派不出去，这时候我一般转头看队列。dsh-crew 的任务流入和结果回传往往都依赖消息通道，消息通道出的问题，从任务状态上看就是"pending 转不出来"。
3.1 先看队列积压和消费 lag
大多数消息系统都有现成的指标看。比如队列深度（当前排队消息数）和消费 lag（消费端落后了多久/多少条）。我遇到过的两种典型情况：
- 队列深度正常，但 lag 持续增长。说明消费端在处理消息上卡住了，任务进了队列但没人取。
- 队列深度为零，任务却还显示 pending。说明消费端可能把消息取走了，但处理后状态没有正确回写，或者是消息被消费了但执行结果一直没有上报。
第一种情况去查 worker 侧的消费线程，第二种情况去查任务状态回写链路。很多人一看到任务堆积就以为是队列容量不够，其实多数时候是消费端处理能力下降或者状态回写出问题。
3.2 重复消费：处理逻辑必须是幂等的
消息系统的"至少一次"投递语义是老大难。dsh-crew 的默认配置里，任务消息被消费后需要显式确认（ack）。如果 worker 执行完任务后还没来得及 ack，网络断开或者进程重启，消息就会重新投递，任务就会被再次执行。
这带来两个后果：一是同一个任务被派发了两次，二是调度端看到的任务状态可能被后续的重复执行覆盖。这个问题不是完全靠消息系统配置能解决的，任务处理逻辑本身要设计成幂等。比如：
- 任务消息里带上全局唯一的 task_id，worker 执行前先去状态存储查一下这个 task_id 是否已经执行完成，完成则直接跳过。
- 状态回写时使用条件更新（只有 pending 状态才允许改成 running），避免旧消息覆盖新状态。
我在一个模拟项目里就吃过这个亏。当时为了省事，没有做幂等检查，结果某次消息重试导致同一批数据处理了两遍，下游统计全乱了。从那以后，我对所有任务处理函数的第一条要求就是：相同的 task_id 重复执行多少次，结果必须一样。
3.3 消费线程阻塞和死信处理
还有一种容易被忽略的情况：消费者从队列里捞出一条消息后，处理逻辑里遇到了异常，但没有捕获，导致消费线程一直卡在重试循环里，后面的消息全部排队。日志里通常能看到同一个消息 ID 反复出现，每次都在超时边缘。
处理办法一般是给每条消息设置最大重试次数，超过次数进入死信队列。dsh-crew 里可以给死信队列单独配一个消费者，把异常消息的内容、报错、入队时间落下来，方便后续定位。没有死信机制的话，坏消息会一直堵在队首，把后面所有正常任务全部拖死。
4. 第三类报错：路由匹配为空，调度器找不到能干活的人
如果说心跳问题像"快递员没上班"，那路由匹配问题就像"分拣员不知道这个包裹该给谁"。日志里常见：
[router] task t-2048 requires capability [gpu:A100, region:cn-north], but no worker matched [dispatcher] no available worker for task, abandon after max retries这种报错最直接的理解就是：有任务要派发，但调度器按照规则扫描了一圈所有 worker，发现没有一个满足条件的。有时候不是 worker 不够，而是 worker 上报的标签和能力跟路由规则对不上。
4.1 标签规格不一致：最常见的低级错误
dsh-crew 的 worker 启动时会声明自己的标签，比如：
worker: id: node-31 labels: region: cn-north gpu: A100 pool: high-performance resources: cpu: 16 mem: 64Gi调度端路由规则可能是这样的：
route: match: region: cn-north gpu: a100注意看，worker 标签写的是A100（大写），路由规则写的是a100（小写）。如果匹配逻辑是精确字符串比较，那这个 worker 永远不会被选中。这种问题排查起来特别费时间，因为从两边看都"没错"。
我现在的习惯是：不管是标签还是路由规则，全部统一定义成枚举级别的小写字符串，并在调度端提供一个"标签预览"命令，能看到当前所有 worker 的标签集合。派发不出去时，第一件事就是拿任务的匹配条件和 worker 标签集合做一次直观对比，人眼扫一遍的效果比看日志强多了。
4.2 资源约束把符合条件的 worker 全都排除了
有些路由匹配会同时校验资源和约束条件。比如任务声明需要 32GB 内存，而整个集群里所有 worker 空余内存都不足 32GB，这时候即使有 worker 挂着"内存充足"的标签，路由结果也是空。
这类问题的特点是：标签匹配可能全部通过，但调度端给你返回的报错是"资源不足"。排查时不能只看标签，要把任务的资源需求和当前集群的空余资源拉出来对比。我常用一个办法：直接查所有 worker 的allocated和total资源，算出每个 worker 的剩余资源，然后手动模拟一遍路由匹配逻辑，很快就知道是哪个条件卡住了。
4.3 路由规则版本和 worker 声明版本不一致
我吃过一次亏：调度端更新了路由规则，要求所有任务必须选择带pool=high-performance标签的 worker，但集群里还有一大半 worker 是旧版本启动的，根本没有这个标签。结果就是新任务全部派发不出去，旧任务还在正常运行。
这种"灰度更新导致匹配规则超前于实际 worker 能力"的问题，在动态扩缩容的集群里尤其容易出现。排查要点是：路由规则的生效范围得和 worker 的能力声明保持同步。要么先让所有 worker 升级并注册新标签，再切换路由规则；要么在路由规则里做兼容处理。上线策略上多花点心思，比事后排查省太多事。
5. 第四类报错：状态存储的键过期、锁失效，任务状态和实际不符
这类问题最隐蔽。现象往往是：任务实际已经执行完了，但在控制台上看还是 running；或者 worker 已经不存在了，但任务还挂在它名下，调度端一直没有重新派发。
dsh-crew 里状态存储一般用键值型存储（缓存或数据库），并借助分布式锁做并发控制。状态和锁出的问题，绝大多数都跟过期时间设置不合理有关。
5.1 任务状态键过期，导致状态回跳或丢失
任务状态通常用一个带过期时间的键来保存，目的是防止异常任务永远占着存储。但过期时间如果设得太短，长任务还没跑完，状态键就被自动清理了。等 worker 执行完想回写状态时，发现写不进去（因为原始的 pending 状态已经没了），或者在调度端看来任务已经"蒸发"了。
排查时先看任务的 TTL 和任务实际执行时长。有个规律：任务执行时长接近 TTL 的，状态类故障发生率会明显上升。我一般会把任务状态键的 TTL 设置成任务最大预估时长的三到五倍，并额外在任务消息里附带一个创建时间戳，状态回写时做兜底校验。
5.2 分布式锁过期导致重复派发
调度端给 worker 派发任务时，通常会先抢一个锁，防止同一个任务被多个 worker 同时执行。如果锁的租约时间太短，任务执行特别是耗时较长的任务还没结束，锁先过期了，另一个调度器实例就把任务又抢过来派发了。
这种问题在日志里的表现是：同一个 task_id 出现在两个 worker 的执行日志里，两边都在跑。排查方向比较明确：
- 锁的租约时间和任务最长执行时间对比；
- 锁续租机制是否正常（有些实现是自动续租的，有些不是）；
- 网络分区后，旧锁持有者是否能正确感知锁已失效。
我认为最稳妥的方案是给任务执行本身增加"执行前写开始标志、执行后条件更新"的双保险，即使锁过期导致重复派发，第二次执行时看到任务已经不是 pending 状态就会自动退出。靠锁本身防御网络分区是不可靠的，应用层幂等才是兜底。
5.3 worker 假死和状态存储中的脏数据
有一种常见组合：worker 因为心跳超时被标记 offline，但过一会儿心跳恢复，worker 又变成 online。如果这个过程中它刚好在跑一个任务，那么任务状态可能还挂在它名下，但调度端已经认为它"不在线"，自然不会基于这个任务做重新派发。
这会造成一个很尴尬的局面：任务既没有被继续执行，也没有被重新派发，永远卡在 running。处理思路是：worker 重新注册上线后，主动向调度端报告自己当前正在运行的任务列表，调度端根据 worker 的上线登记做状态对账。没有这个对账机制，就得人工手动恢复状态，一次两次可以，集群大了根本扛不住。
6. 第五类报错：令牌、权限、配置校验失败
这类报错表面上看跟任务派发没有直接关系，但 worker 连接调度端时的认证握手一旦失败，后面的流程根本走不下去。日志里常见：
[agent] auth failed: token expired, re-register required [dispatcher] incoming request from node-44 rejected: credential mismatch6.1 token 过期和续期逻辑没闭环
很多 dsh-crew 部署里，worker 启动时拿一个长期有效的 token 或者短期的 session token。如果 worker 进程长期不重启，而 token 有效期只有 24 小时，到期后 worker 并不会自动重新认证，连接就会在某一刻静默断开。
这个问题的可怕之处在于：它不是一个瞬间的报错，而是"慢慢地失去连接"，日志里可能只有一次 auth failed，然后 worker 就被标记 offline，但 worker 侧的日志一切正常。排查此类问题，我建议在 worker 侧实现自动续期逻辑，并在 token 过期前提前刷新；同时在监控上增加"认证剩余有效期"的指标，低于某个阈值就发出告警。
6.2 权限范围不匹配
有些环境会在调度端配置 worker 的权限范围，比如这个 worker 只能接收某个项目组下的任务。如果任务提交方的身份信息和 worker 的权限不匹配，任务就会被调度端拒绝派发。
典型例子：任务提交时带了scope: project-a，而目标 worker 被配置成只允许执行scope: project-b的任务，路由匹配即使通过了，在权限校验那一层也会被拦下来。我之前遇到过排查了很久才发现的坑：worker 侧配置没问题，调度端路由配置也没问题，但权限配置文件里两个项目组的命名差了一个下划线，导致所有任务都匹配不上。
这类问题没有太多技巧，核心就是把 worker、任务、权限三者的标识符统一管理，最好做成配置中心下发，而不是散落在各机器上。
6.3 配置版本不一致：worker 用旧配置跑新任务
还有一种比较隐蔽的情况：调度端发布新任务时携带了配置版本号，worker 执行前要校验自己的本地配置版本是否匹配。如果 worker 没有及时拉取最新配置，校验失败，任务会被拒绝执行。
从外部看，任务显示的是"已派发"，但 worker 一直不启动执行，状态不上报。很多人会误以为是 worker 负载过高排队，实际上 worker 只是默默地拒绝了。排查时可以对比调度端下发的配置版本号和 worker 当前的配置版本号，如果存在跨度，就是配置同步的问题。解决方式也简单：让 worker 在空闲时定期拉取配置，执行任务前再校验一次，不匹配就强制退出并重新初始化。
7. 排查工具箱：日志关键词、队列指标、自检清单
讲完五类报错，我再把我平时排查"派发不出去"问题时的工具箱完整列出来。这个工具箱不依赖什么复杂平台，就是一组纯手动的排查手段，足够覆盖绝大多数场景。
7.1 日志关键词灰名单
我从来不看满屏的 INFO 日志，而是直接按故障特征搜关键词。不同报错对应不同日志片段：
| 问题类别 | 关键日志片段 | 我优先去看的位置 |
|---|---|---|
| worker 离线 | heartbeat timeout / mark as offline | 调度端 worker 管理日志 |
| 路由匹配为空 | no available worker / route not matched | 调度端路由日志 |
| 队列积压 | consume lag / queue depth | 消息系统监控面板 |
| 状态回写失败 | state update conflict / ttl expired | 状态存储写入日志 |
| 权限校验失败 | auth failed / credential mismatch | worker 注册认证日志 |
灰名单不是固定不变的，每次排查完我都会把新的可疑日志加进去，慢慢就形成了团队自己的"查错手册"。
7.2 三个命令定位当前派发瓶颈
有些系统自带调试命令，有些没有。如果没有，我一般用这三个命令组合来定位：
# 1. 查看调度端感知到的 worker 列表和状态（示例） dshctl worker list --show-labels # 2. 查看任务当前的路由匹配结果（示例） dshctl task explain t-2048 --match-detail # 3. 查看队列需求和消费 lag（示例） dshctl queue stats --top 10第一个命令解决"有没有人"，第二个命令解决"为什么不选他"，第三个命令解决"任务到底卡在哪个环节"。绝大多数情况下，这三个问题问完，故障点已经八九不离十了。
7.3 恢复性自检清单
最后分享一份我每次处理完"派发不出去"之后都会过一遍的自检清单。它不能帮你找到新问题，但能确保你不会因为修一个 bug 引出另外三个 bug：
- 心跳超时时间调整后，是否有监控覆盖"误判离线"的频率？
- 任务处理逻辑是否做到了同一 task_id 重复执行幂等？
- 路由标签是否统一成小写枚举，并在 worker 侧有校验？
- 状态键 TTL 是否覆盖了任务最长执行时长？
- 分布式锁租约是否支持自动续期？
- worker 认证 token 是否有过期前自动刷新机制？
- worker 配置版本和调度端是否用同一个配置中心？
这些条目既是排查思路的总结，也是日常运维的体检项。我不建议一次性全部改完，而是每次故障后补一条，慢慢完善，对照清单做一次检查，往往比写一大堆临时脚本更有效。
8. 最后分享一个实战小技巧
写了这么多，最想强调的还是开头那句话：派发不出去，先定位任务卡在哪个环节，再去看具体报错。五类报错看着多，实际排查时是能按"位点"快速收敛的。我自己吃了不少亏，也总结出一个习惯——每次处理完这类问题，都会把当次的报错日志、临时改动、最终修复方案记成一条简短的笔记。下一次再遇到类似的"派发不出去"，翻笔记比从头查快得多。
一个小技巧送给你们：如果你发现自己频繁在排查"任务状态和 worker 实际状态不一致"的问题，别再把精力放在修改状态字段上，而应该去检查任务状态键的 TTL 和锁的租约时间，这两个值一旦设置合理，很多看似诡异的现象会自己消失。状态一致性靠的是设计，不是靠人肉纠正。
