Hadoop YARN容量调度器默认配置详解与生产调优实战

1. 从一次集群告警说起：为什么默认配置值得单独拎出来讲

刚接手一个跑了几十个离线任务的集群那会儿，我遇到过一个特别典型的现象：白天任务提交上去，队列里排得满满当当，但集群整体资源利用率却只有三成左右。当时第一反应是资源不够，差点就去申请扩容了。后来把capacity-scheduler.xml翻出来逐行看了一遍，才发现问题根本不在机器数量上，而是默认配置里几个关键参数把资源卡死了。

capacity-scheduler.xml是 Hadoop YARN 里 Capacity Scheduler（容量调度器）的核心配置文件。YARN 作为资源调度层，决定了集群里 CPU、内存这些资源怎么分给不同的队列、不同的应用。而 Capacity Scheduler 是 Apache Hadoop 默认启用的调度器，它的默认配置直接决定了一个刚装好的集群"出厂状态"下能跑成什么样。很多人装完集群能跑通 WordCount 就以为万事大吉，实际上默认配置是为"能跑起来"设计的，不是为"跑得好"设计的。

这篇内容适合三类人看：一是刚接触 YARN、想搞明白调度器到底在管什么的新手；二是集群跑着跑着发现资源利用率上不去、任务排队异常、想排查配置问题的运维或开发；三是准备做多队列资源隔离、需要从默认配置出发做定制的人。我会把默认配置里每个关键参数拆开讲清楚它默认是什么、为什么这么设、实际生产里应该怎么调，再配上我踩过的坑和排查思路。整篇围绕capacity-scheduler.xml这一份文件展开，但会把背后的调度逻辑讲透，让你看完能直接对着自己的集群动手改。

2. 默认配置全貌与设计逻辑拆解

2.1 默认文件到底长什么样

Hadoop 发行版里自带的capacity-scheduler.xml，如果你不去动它，核心内容其实非常"素"。它主要包含这么几类配置：根队列的资源分配、默认队列的定义、资源计算器、以及一堆带默认值的开关。我把最关键的几项列出来，这也是后面所有讨论的基础。

配置项	默认值	作用
yarn.scheduler.capacity.root.queues	default	根队列下只有一个 default 子队列
yarn.scheduler.capacity.root.default.capacity	100	default 队列占根队列 100% 容量
yarn.scheduler.capacity.root.default.maximum-capacity	100	default 队列最大可弹性到 100%
yarn.scheduler.capacity.root.default.state	RUNNING	队列处于运行状态
yarn.scheduler.capacity.root.default.user-limit-factor	1	单用户最多用队列 1 倍容量
yarn.scheduler.capacity.resource-calculator	DefaultResourceCalculator	只按内存调度，忽略 CPU
yarn.scheduler.capacity.maximum-am-resource-percent	0.1	AM 最多占队列 10% 资源
yarn.scheduler.capacity.node-locality-delay	40	本地化等待的调度机会数

这张表里每一项都值得单独说，但先记住一个整体印象：默认配置是"单队列、全内存、保守分配"的思路。它假设你只有一个队列，所有应用挤在一起，调度器只关心内存够不够，CPU 基本不管。

2.2 为什么默认只给一个 default 队列

很多人第一次看到root.queues=default会疑惑：YARN 不是号称支持多队列资源隔离吗，怎么默认就一个队列？这其实是刻意的设计取舍。Capacity Scheduler 的定位是"多租户共享大集群"，但一个刚装好的集群往往还没确定租户划分方案，这时候给你一个 default 队列，保证任何应用提交上来都有地方跑，不会因为队列没配好直接失败。

从调度器实现角度看，根队列root是必须存在的顶层容器，它下面挂的子队列才是真正分配资源的地方。默认只挂一个 default，等于把 100% 资源都给了它。这种设计的好处是零配置可用，坏处是所有应用不分优先级、不分用户地抢同一池子资源，一个跑飞的大任务能把整个集群拖垮。所以生产环境第一件事往往就是拆队列，而拆队列的起点就是理解这个默认结构。

提示：改root.queues增加子队列时，新增队列的 capacity 之和不能超过 100，否则 ResourceManager 启动会直接报配置错误。这是新手最容易踩的第一个坑。

2.3 DefaultResourceCalculator 带来的隐性限制

默认资源计算器是DefaultResourceCalculator，它只按内存做调度决策，CPU 资源在调度层面被完全忽略。这个默认值在早期 Hadoop 里很常见，因为那时候大部分集群是内存瓶颈型，CPU 相对富裕。但现在情况变了，很多任务（比如机器学习训练、视频转码）是 CPU 密集型，如果调度器不看 CPU，就会出现"内存分出去了但 CPU 被抢爆"的情况，任务实际执行效率极低。

要改成同时考虑内存和 CPU，需要把计算器换成DominantResourceCalculator。这个计算器会取内存和 CPU 中占比更高的那个作为主导资源（Dominant Resource），按主导资源做公平分配。改这一项的影响面很大，它会改变整个集群的调度行为，所以不建议在集群跑着大量任务时贸然切换，最好在业务低峰期做，并且提前压测。

2.4 user-limit-factor 与 AM 资源上限的保守哲学

user-limit-factor=1意味着单个用户最多只能用掉队列 100% 的容量，听起来好像没限制，但结合多用户场景就有意义了：如果队列容量是 100，两个用户同时提交任务，默认情况下每个用户最多用 100，但实际调度会尽量让两人平分。这个参数设成大于 1 的值（比如 2），允许单用户在队列空闲时超用资源，适合"平时人少、偶尔爆发"的场景。

maximum-am-resource-percent=0.1限制 ApplicationMaster 最多占用队列 10% 的资源。AM 是每个应用的管理进程，本身不干重活，但它要占一个 container。如果这个比例设太高，大量小应用的 AM 会把资源吃光，真正干活的 task 反而没资源；设太低，并发应用数就上不去。默认 0.1 是个折中值，小集群够用，大集群跑大量并发应用时经常需要往上调。

3. 核心参数逐个拆解与实操调优

3.1 队列容量三兄弟：capacity、maximum-capacity、user-limit-factor

这三个参数是 Capacity Scheduler 的灵魂，必须一起理解。capacity是队列的"保底份额"，比如两个队列各 50，那不管对方多闲，你至少能拿到 50% 的资源。maximum-capacity是"弹性上限"，对方闲着的时候你可以临时超用，但最多不超过这个值。user-limit-factor则是在队列内部，限制单个用户能占队列容量的倍数。

举个具体例子。假设根队列下有两个子队列 A 和 B，配置如下：

<property> <name>yarn.scheduler.capacity.root.queues</name> <value>a,b</value> </property> <property> <name>yarn.scheduler.capacity.root.a.capacity</name> <value>60</value> </property> <property> <name>yarn.scheduler.capacity.root.a.maximum-capacity</name> <value>80</value> </property> <property> <name>yarn.scheduler.capacity.root.b.capacity</name> <value>40</value> </property> <property> <name>yarn.scheduler.capacity.root.b.maximum-capacity</name> <value>100</value> </property>

这个配置的含义是：A 保底 60%，最多能涨到 80%；B 保底 40%，最多能涨到 100%。当 A 空闲时，B 可以吃掉 A 释放的资源，一直涨到 100%。注意 A 和 B 的 capacity 之和是 100，这是硬性要求；而 maximum-capacity 各自可以到 100，互不冲突，因为它表达的是"上限"而非"份额"。

实操中我建议 capacity 按业务重要性分配，maximum-capacity 留出弹性空间。比如核心业务队列 capacity 给 50、maximum 给 70，离线分析队列 capacity 给 30、maximum 给 100，这样核心业务有保底，离线任务能在空闲时吃满剩余资源，整体利用率能明显提升。

3.2 资源计算器切换的完整操作与验证

把DefaultResourceCalculator换成DominantResourceCalculator只需要改一行配置：

<property> <name>yarn.scheduler.capacity.resource-calculator</name> <value>org.apache.hadoop.yarn.util.resource.DominantResourceCalculator</value> </property>

但改完之后必须验证，否则你可能以为生效了其实没有。验证方法有两个：一是看 ResourceManager 日志里调度器初始化时打印的计算器类名；二是提交一个 CPU 密集任务，观察yarn.scheduler相关的指标里 CPU 是否参与了分配决策。我一般用第二种，更直观。

这里有个容易忽略的点：切换计算器后，之前按内存算出来的队列使用率会全部重算，可能出现某个队列"突然"超了 maximum-capacity 的情况，导致新任务被卡住。所以切换前要先用yarn queue -status看一遍各队列当前的内存和 CPU 使用情况，确认切换后不会触发上限。

注意：DominantResourceCalculator需要 NodeManager 正确上报 CPU 核数（yarn.nodemanager.resource.cpu-vcores），如果这个值配得不对，主导资源计算会失真。默认它等于机器物理核数，但很多虚拟化环境需要手动指定。

3.3 AM 资源上限与并发应用数的关系

maximum-am-resource-percent直接决定了集群能同时跑多少个应用。假设队列总资源是 100GB 内存，AM 默认占 1GB，那 10% 就是 10GB，最多同时跑 10 个应用的 AM。如果你要跑 50 个并发小应用，这个默认值就不够了，需要往上调，比如调到 0.3 甚至 0.5。

但调高有代价：AM 占的资源多了，留给实际 task 的就少了。所以这是个平衡。我的经验是，先估算平均每个应用需要多少 AM 内存和多少 task 内存，再反推合理的比例。比如每个应用 AM 1GB、task 平均 4GB、平均每个应用 5 个 task，那单个应用总需求约 21GB，其中 AM 占 1GB 约 5%，这时候 0.1 的默认值其实够用。但如果应用普遍很小、task 很少，AM 占比就会升高，默认值就不够了。

另外还有个相关参数yarn.scheduler.capacity.maximum-am-resource-percent是队列级别的，可以在子队列上单独覆盖。给跑大量小应用的队列单独调高，给跑大任务的队列保持默认，这样更精细。

3.4 本地化等待：node-locality-delay 的取舍

node-locality-delay=40表示调度器在放弃本地化、退而求其次选择非本地节点之前，会等待 40 次调度机会。本地化（Locality）指的是把 task 分配到数据所在的节点，避免跨网络拉数据。等待越久，本地化命中率越高，但任务启动延迟也越大。

默认 40 是个偏保守的值，适合数据量大、网络带宽紧张的场景。如果你的集群网络很好（比如万兆内网），或者任务对启动延迟敏感（比如交互式查询），可以把这个值调小，比如 10 到 20，让任务更快跑起来。反过来，如果任务是重 IO 的批处理，调大一点能减少跨节点数据传输。

这个参数没有绝对最优值，得结合你的网络和任务特性试。我一般先在默认值下跑一批任务，看 ResourceManager 日志里本地化命中的比例，如果命中率已经很高（比如 90% 以上），说明 40 够用甚至偏大；如果命中率低，可能是数据分布本身就不均匀，调参数也救不了，得从数据布局入手。

4. 完整实操：从默认配置到多队列生产配置

4.1 改造前的现状盘点

动手改之前，先摸清现状。我习惯跑这么几条命令：用yarn queue -status default看默认队列的资源和使用率；用yarn application -list看当前跑着哪些应用、各占多少资源；再看 ResourceManager 的 Web UI 里各队列的 pending 和 running container 数。这一步的目的是搞清楚"现在的瓶颈到底在哪"，避免盲目改配置。

假设盘下来发现：所有应用挤在 default 队列，内存利用率 60%，但 CPU 利用率只有 20%，而且经常有任务因为抢不到 AM 资源而卡在 ACCEPTED 状态。这就说明两个问题：一是需要拆队列做隔离，二是 AM 资源上限偏低，三是 CPU 没被调度器利用起来。

4.2 设计队列结构

基于上面的现状，我设计一个三队列结构：prod（核心生产）、offline（离线批处理）、adhoc（临时查询）。prod 保底 40%、上限 60%；offline 保底 40%、上限 100%；adhoc 保底 20%、上限 50%。这样核心业务有保底，离线任务能弹性吃满空闲资源，临时查询有独立空间不干扰别人。

对应的配置片段：

<property> <name>yarn.scheduler.capacity.root.queues</name> <value>prod,offline,adhoc</value> </property> <property> <name>yarn.scheduler.capacity.root.prod.capacity</name> <value>40</value> </property> <property> <name>yarn.scheduler.capacity.root.prod.maximum-capacity</name> <value>60</value> </property> <property> <name>yarn.scheduler.capacity.root.offline.capacity</name> <value>40</value> </property> <property> <name>yarn.scheduler.capacity.root.offline.maximum-capacity</name> <value>100</value> </property> <property> <name>yarn.scheduler.capacity.root.adhoc.capacity</name> <value>20</value> </property> <property> <name>yarn.scheduler.capacity.root.adhoc.maximum-capacity</name> <value>50</value> </property>

注意 capacity 之和 40+40+20=100，符合要求。每个队列还要设state=RUNNING，否则队列不工作。

4.3 应用如何指定队列

队列建好了，应用得知道往哪提交。有几种方式：提交时用-D mapreduce.job.queuename=offline指定；或者在mapred-site.xml里配默认队列；再或者在代码里通过Job.setQueueName()设置。我一般推荐在提交脚本里显式指定，这样最清晰，也方便不同任务走不同队列。

有个细节：如果应用指定的队列不存在，或者队列处于 STOPPED 状态，任务会直接失败。所以改完队列配置后，一定要先重启 ResourceManager（或者用yarn rmadmin -refreshQueues热加载），再用一个测试任务验证每个队列都能正常提交。

4.4 热加载与重启的取舍

yarn rmadmin -refreshQueues可以在不重启 ResourceManager 的情况下重新加载队列配置，这对生产集群非常友好。但它有个限制：只能改队列的容量、上限、状态这些属性，不能新增或删除队列。也就是说，如果你要加一个新队列，还是得重启 ResourceManager。

我的做法是：日常调容量用 refreshQueues，涉及队列增删的改动安排在维护窗口重启。重启前先yarn application -list确认没有关键任务在跑，或者用-Dmapreduce.job.queuename把任务临时导到其他队列。

提示：refreshQueues 之后，正在运行的应用不会重新分配资源，新配置只对新提交的应用生效。所以调完容量别指望立刻看到变化，得等新任务上来。

5. 常见问题与排查技巧实录

5.1 队列容量之和不等于 100 会怎样

这是最高频的配置错误。如果子队列 capacity 之和小于 100，ResourceManager 启动时会警告，剩余容量会被"浪费"（没有队列认领）；如果大于 100，直接启动失败，报IllegalArgumentException。我见过有人把三个队列配成 50、50、50，结果 RM 起不来，排查半天才发现是加法问题。

解决办法很简单：确保同一层级下所有子队列的 capacity 之和恰好等于 100。如果确实想留余量，可以加一个"保留队列"占住剩余份额，而不是让和小于 100。

5.2 任务一直卡在 ACCEPTED 状态

任务提交后长时间处于 ACCEPTED，说明调度器分配不出资源。常见原因有三个：一是队列资源被占满且达到 maximum-capacity；二是 AM 资源上限到了，新应用的 AM 起不来；三是队列 state 是 STOPPED。

排查顺序：先yarn queue -status <队列名>看使用率和上限；再看maximum-am-resource-percent是否卡住了 AM；最后确认队列状态。我遇到最多的是第二种，尤其是跑大量小应用时，默认 0.1 的 AM 上限很快就被占满，表现就是任务全卡在 ACCEPTED，但集群内存明明还有富余。

5.3 改了配置不生效

配置改了但行为没变，通常是这几个原因：忘了 refreshQueues 或重启；改错了文件（集群里可能有多个 capacity-scheduler.xml，比如 Hadoop 目录一份、各节点一份）；配置项名字拼错（比如把maximum-capacity写成max-capacity）。

我的排查习惯是：改完先grep确认文件里配置项名字正确，再 refreshQueues，然后看 ResourceManager 日志里有没有加载新配置的记录。如果日志里没动静，八成是文件路径不对或者 RM 没读到。

5.4 常见问题速查表

现象	可能原因	排查动作
RM 启动失败	capacity 之和大于 100	检查各子队列 capacity 相加
任务卡 ACCEPTED	队列满 / AM 上限到 / 队列 STOPPED	查队列状态和 AM 使用率
配置不生效	未 refresh / 文件错 / 名字错	grep 配置项 + 看 RM 日志
CPU 利用率低	用了 DefaultResourceCalculator	切换为 DominantResourceCalculator
本地化命中率低	node-locality-delay 偏小或数据不均	调大 delay 或检查数据分布

5.5 几个我踩过的坑

第一个坑是user-limit-factor设太大。有次为了让人少的时候能多用资源，把它设成了 5，结果单个用户提交大量任务时把整个队列吃满，其他用户全被饿死。后来改回 1 到 2 之间，配合队列隔离才稳定。

第二个坑是忽略yarn.scheduler.capacity.node-locality-delay的单位。它不是"秒"也不是"毫秒"，而是"调度机会数"，跟集群规模和任务提交频率有关。我一开始按时间理解，调来调去没效果，后来才搞明白它的真实含义。

第三个坑是热加载后没验证。有次 refreshQueues 后以为生效了，结果新队列根本没加上（因为新增队列不支持热加载），任务提交上去全失败。从那以后我养成了改完必测的习惯，用一个最小任务跑一遍每个队列。

6. 默认配置的边界与后续扩展方向

把capacity-scheduler.xml的默认配置吃透，本质上是在理解 YARN 资源调度的"最小可用模型"。默认值不是错的，它是为通用场景设计的保守起点。真正要让它适配你的业务，得从队列结构、资源计算器、AM 上限、本地化策略这几个维度去调，而每个维度的调整都要有明确的业务理由，不能为了调而调。

这套配置后续还能往几个方向扩展：一是结合Fair Scheduler做对比选型，看哪种调度器更适合你的负载特征；二是引入队列的 ACL 控制，限制哪些用户能往哪些队列提交；三是配合 Node Labels 做更细粒度的资源分区，比如把 GPU 节点单独划给特定队列。这些都是在默认配置基础上长出来的能力，前提是你先把默认这层搞扎实。

我个人在实际操作中的体会是，YARN 调优最忌讳一上来就抄网上的"最佳配置"。别人的队列结构和你的业务负载可能完全不同，照搬往往适得其反。更靠谱的做法是先用默认配置跑一段时间，收集真实的资源使用数据，再基于数据做针对性调整。配置改完一定要验证，验证完一定要观察一段时间，确认没有副作用再固化下来。这套流程走下来，比任何现成的配置模板都管用。