Apache Uniffle 0.10.0 配置参数详解
详解 Apache Uniffle 0.10.0 核心配置：coordinator.conf、server.conf、rss-env.sh 与 Spark 客户端参数的语义、默认值、同机端口冲突与准入检查实测结论。
Apache Uniffle 0.10.0 配置参数详解
一、参数体系与查看方法
1.1 配置文件布局
Uniffle 0.10.0 的配置集中在发行包 conf 目录（本文按部署目录 /opt/uniffle 展开）：
| 文件 | 生效对象 | 说明 |
|---|---|---|
| conf/coordinator.conf | coordinator 进程 | 键值对格式，每行一个参数 |
| conf/server.conf | shuffle-server 进程 | 键值对格式（0.10.0 起替代旧版 shuffle-server.conf） |
| conf/rss-env.sh | 全部进程启动脚本 | shell 变量：JAVA_HOME、HADOOP_HOME、JVM 堆大小 |
| conf/dashboard.conf | dashboard 进程 | Web 端口与 coordinator 地址 |
| conf/log4j2.xml | 全部进程 | 日志格式、级别、审计日志开关 |
1.2 参数加载机制
启动脚本按固定顺序加载：bin/uniffle-function.sh 与 bin/utils.sh 提供 shell 函数，conf/rss-env.sh 提供环境变量，随后各进程读取自己的 .conf 文件。两个要点：
- rss-env.sh 顶部有 set -o nounset 与 set -o errexit，文件中任何未定义变量引用都会直接中断启动脚本，HADOOP_HOME 必须显式定义。
- .conf 文件是 properties 风格键值对，不支持行内注释混写，注释行以 # 开头独立成行。
1.3 查看运行中生效参数
进程启动时会把完整 JVM 参数打印到控制台与日志头部，可用 jps -v 查看堆配置：
jps -v | grep -E 'CoordinatorServer|ShuffleServer'
实测回显（节选）：
5819 org.apache.uniffle.coordinator.CoordinatorServer -Xms512m -Xmx512m ...
6008 org.apache.uniffle.server.ShuffleServer -Xms512m -Xmx512m ...
coordinator 的部分运行时状态可通过 HTTP 接口查询（实测端口 19990）：
curl -s http://127.0.0.1:19990/api/coordinator/info
curl -s http://127.0.0.1:19990/api/server/nodes
二、coordinator.conf 核心参数
2.1 网络端口
| 参数 | 默认值 | 说明 |
|---|---|---|
| rss.rpc.server.port | 19999 | coordinator 的 gRPC 服务端口，供 shuffle-server 心跳注册与计算引擎查询 |
| rss.jetty.http.port | 19998 | coordinator 的 HTTP 端口，提供 REST API 与 /metrics |
同机同时运行 coordinator 与 shuffle-server 时必须错开两套端口（发行包默认值两边完全相同），本文实测采用：coordinator 19991/19990，shuffle-server 19997/19996。
2.2 集群与心跳
| 参数 | 默认值 | 说明 |
|---|---|---|
| rss.coordinator.server.heartbeat.timeout | 30000 | shuffle-server 心跳超时毫秒数，超时未收到心跳的节点从可用列表摘除并标记 LOST |
| rss.coordinator.app.expired | 600000 | 应用级元数据过期时间毫秒数，应用结束后 coordinator 保留该应用的统计信息时长 |
| rss.coordinator.exclude.nodes.file.path | file:///xxx | 排除节点列表文件路径，发行包默认值指向不存在的占位路径，直接启动会受影响，单机部署应删除该行 |
2.3 准入与分配（实测重点）
| 参数 | 默认值 | 说明 |
|---|---|---|
| rss.coordinator.shuffle.nodes.max | 13 | 双重语义：一是 coordinator 返回给计算引擎的候选 shuffle 节点数上限；二是客户端 access 准入检查的默认必需可用节点数。单机部署必须设为 1，否则 Spark 客户端被 AccessClusterLoadChecker 拒绝并静默回退到原生 shuffle |
| rss.coordinator.select.partition.strategy | CONTINUOUS | 分区到节点的分配策略，可选 CONTINUOUS（连续分配）与 ROUND_ROBIN（轮询） |
| rss.coordinator.access.loadChecker.memory.percentage | 15.0 | AccessClusterLoadChecker 判定节点可用的内存百分比阈值：节点剩余 buffer 容量占比达到该值的节点才计入可用节点数。注意键名结尾是 percentage，写成 percent 不会生效 |
| rss.coordinator.access.checkers | AccessClusterLoadChecker | 客户端准入检查器列表，逗号分隔；生产上至少保留负载检查器，小规模验证集群可结合 shuffle.nodes.max 一起调整 |
实测证据（反汇编 AccessClusterLoadChecker.check 的判定链）：可用节点数 = 状态为 ACTIVE 且可用内存百分比达标的节点数；availableServerNumThreshold 未配置（-1）时与 rss.coordinator.shuffle.nodes.max 对应的默认必需节点数比较，小于则拒绝并输出 total N nodes, N available nodes, memory percent threshold X。
2.4 实测单机参考模板
rss.rpc.server.port 19991
rss.jetty.http.port 19990
rss.coordinator.server.heartbeat.timeout 30000
rss.coordinator.app.expired 600000
rss.coordinator.shuffle.nodes.max 1
rss.coordinator.select.partition.strategy CONTINUOUS
三、server.conf 核心参数
3.1 网络与注册
| 参数 | 默认值 | 说明 |
|---|---|---|
| rss.rpc.server.port | 19999 | shuffle-server 的 gRPC 端口，接收计算引擎 shuffle 数据写入与读取请求 |
| rss.jetty.http.port | 19998 | shuffle-server 的 HTTP 端口，提供 /metrics 指标 |
| rss.coordinator.quorum | 无 | coordinator 地址列表，格式 host1:port1,host2:port2，端口填 coordinator 的 rpc 端口；多 coordinator 集群全部列出 |
3.2 存储类型与路径
| 参数 | 默认值 | 说明 |
|---|---|---|
| rss.storage.type | MEMORY_LOCALFILE_HDFS | 存储类型：MEMORY_LOCALFILE（内存加本地文件）、LOCALFILE（纯本地文件）、MEMORY_LOCALFILE_HDFS（内存加本地文件加 HDFS）、HDFS。0.10.0 强制 LOCALFILE 与 HDFS 只能在 test mode 使用 |
| rss.storage.basePath | /xxx | 本地 shuffle 数据根目录，建议独立数据盘，目录需提前创建 |
| rss.server.disk.capacity | 无默认 | 本地存储容量上限，如 10g；超过后节点被标记不可用 |
| rss.test.mode.enable | false | 测试模式开关，键名为 rss.test.mode.enable（非 test.mode）；LOCALFILE/HDFS 类型必须设 true |
3.3 内存与刷盘
| 参数 | 默认值 | 说明 |
|---|---|---|
| rss.server.buffer.capacity | 无默认 | shuffle 数据堆内 buffer 总容量（字节或 xg/xm 格式），写入先进 buffer，写满触发刷盘；该值加堆上其他开销应小于 JVM 堆上限 |
| rss.server.read.buffer.capacity | 无默认 | 读取数据的堆外 buffer 容量，影响并发读取吞吐 |
| rss.server.flush.thread.alive | 10 | 刷盘事件线程存活数 |
| rss.server.flush.localfile.threadPool.size | 10 | 本地文件刷盘线程池大小 |
| rss.server.flush.hadoop.threadPool.size | 60 | HDFS 刷盘线程池大小（仅 HDFS 类型生效） |
| rss.server.single.buffer.flush.enabled | true | 单 buffer 即刷开关，低负载下让数据更快落到本地文件 |
| rss.server.single.buffer.flush.threshold | 2mb | 单 buffer 触发刷盘的容量阈值 |
3.4 实测单机参考模板（512MB 堆）
rss.rpc.server.port 19997
rss.jetty.http.port 19996
rss.storage.basePath /data/uniffle/shuffle_data
rss.storage.type MEMORY_LOCALFILE
rss.coordinator.quorum 127.0.0.1:19991
rss.server.buffer.capacity 256m
rss.server.read.buffer.capacity 128m
rss.server.flush.thread.alive 5
rss.server.flush.localfile.threadPool.size 10
rss.server.disk.capacity 10g
rss.server.single.buffer.flush.enabled true
rss.server.single.buffer.flush.threshold 64m
该模板在 Ubuntu 22.04 与 CentOS 8 双平台实测通过，shuffle-server 成功注册并完成 Spark 作业 shuffle 写读。
四、rss-env.sh 与 JVM 内存参数
| 变量 | 默认值 | 说明 |
|---|---|---|
| JAVA_HOME | 无（注释占位） | JDK 路径，必须显式设置 |
| HADOOP_HOME | 无（注释占位） | Hadoop 安装路径，启动脚本与 uniffle 命令行工具都会执行 HADOOP_HOME/bin/hadoop classpath，必须显式设置（即使不使用 HDFS 存储） |
| XMX_SIZE | 8g | coordinator 进程堆上限（同时作为 dashboard 堆的回退值） |
| SHUFFLE_SERVER_XMX_SIZE | 80g | shuffle-server 进程堆上限 |
实测修改与验证：
grep -E '^(XMX_SIZE|SHUFFLE_SERVER_XMX_SIZE)' /opt/uniffle/conf/rss-env.sh
jps -v | grep ShuffleServer
实测回显（512MB 堆生效）：
XMX_SIZE="512m"
SHUFFLE_SERVER_XMX_SIZE="512m"
6008 org.apache.uniffle.server.ShuffleServer -Xms512m -Xmx512m ...
rss.server.buffer.capacity 与 SHUFFLE_SERVER_XMX_SIZE 需联动规划：buffer 在堆内分配，buffer.capacity 应明显小于堆上限，实测组合 512m 堆加 256m buffer 运行稳定。
五、dashboard.conf 参数
| 参数 | 默认值 | 说明 |
|---|---|---|
| rss.dashboard.http.port | 19997 | dashboard Web 端口；与 shuffle-server 常用 RPC 端口 19997 冲突，同机部署建议改为 19995 |
| coordinator.web.address | 无 | coordinator 的 HTTP 地址，如 http://127.0.0.1:19990/，dashboard 通过它查询集群状态 |
实测：修改端口为 19995 并配置 coordinator 地址后，./start-dashboard.sh 启动成功，curl http://127.0.0.1:19995/ 返回 200。
六、Spark 客户端关键参数
写入 Spark 的 spark-defaults.conf 或 spark-submit --conf：
| 参数 | 建议值 | 说明 |
|---|---|---|
| spark.shuffle.manager | org.apache.spark.shuffle.DelegationRssShuffleManager | 0.10.0 推荐用 Delegation 委托管理器：检测到 rss 参数可用时启用 Uniffle shuffle，准入失败时自动回退原生 shuffle（回退仅 WARN 日志，需留意） |
| spark.shuffle.enabled | true | 允许 shuffle 管理器替换 |
| spark.shuffle.service.enabled | false | 关闭 Spark 外部 shuffle 服务，Uniffle 模式下不需要 |
| spark.rss.coordinator.quorum | 127.0.0.1:19991 | coordinator 地址列表（rpc 端口），与 server.conf 的 quorum 指向同一组地址 |
| spark.rss.storage.type | MEMORY_LOCALFILE | 与 server.conf 的存储类型对应；选 LOCALFILE 时必须同时设置 spark.rss.test.mode.enable true |
| spark.rss.test.mode.enable | false | 客户端侧测试模式开关，纯 LOCALFILE/HDFS 类型需要设 true |
| spark.serializer | org.apache.spark.serializer.KryoSerializer | Uniffle 序列化 shuffle 模式必须 Kryo，否则报 does not support object relocation |
| spark.sql.shuffle.partitions | 按规模设置 | 每 Spark 应用在 Uniffle 侧的 partition 数，影响 shuffle 节点选择与文件数 |
七、生产配置模板
4 节点集群（1 coordinator 加 3 shuffle-server，每台 64GB 内存，HDFS 存储）参考：
coordinator.conf：
rss.rpc.server.port 19991
rss.jetty.http.port 19990
rss.coordinator.server.heartbeat.timeout 30000
rss.coordinator.app.expired 600000
rss.coordinator.shuffle.nodes.max 3
rss.coordinator.select.partition.strategy CONTINUOUS
rss.coordinator.access.loadChecker.memory.percentage 30.0
shuffle-server.conf（server.conf，每台相同）：
rss.rpc.server.port 19997
rss.jetty.http.port 19996
rss.storage.basePath /data1/uniffle/shuffle_data
rss.storage.type MEMORY_LOCALFILE_HDFS
rss.coordinator.quorum coord1:19991,coord2:19991
rss.server.buffer.capacity 16g
rss.server.read.buffer.capacity 8g
rss.server.flush.thread.alive 10
rss.server.flush.localfile.threadPool.size 20
rss.server.flush.hadoop.threadPool.size 60
rss.server.disk.capacity 3t
rss.server.single.buffer.flush.enabled true
rss.server.single.buffer.flush.threshold 64m
rss-env.sh（coordinator 与 server 可分主机分别设置）：
JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64
HADOOP_HOME=/opt/hadoop
XMX_SIZE="4g"
SHUFFLE_SERVER_XMX_SIZE="32g"
规划原则：buffer.capacity 约为堆上限的一半，HDFS 类型需额外确认 HADOOP_HOME/bin/hadoop classpath 能访问到 hdfs-site.xml（HADOOP_CONF_DIR 在 PATH 内），准入门檻 shuffle.nodes.max 设为集群实际节点数。
八、常见问题
Q1：为什么 coordinator.conf 与 server.conf 都写着 rss.rpc.server.port 19999？ 发行包两份默认配置各自独立且值相同，官方假设 coordinator 与 shuffle-server 分机部署。同机部署时必须手工错开，本文采用 coordinator 19991/19990 与 shuffle-server 19997/19996 的组合。
Q2：设置了 rss.coordinator.access.loadChecker.memory.percent 95.0 但不生效。 键名拼写错误，0.10.0 实际读取的键是 rss.coordinator.access.loadChecker.memory.percentage（percentage 结尾）。可通过反汇编 CoordinatorConf 确认 COORDINATOR_ACCESS_LOADCHECKER_MEMORY_PERCENTAGE 对应的键名。
Q3：shuffle-server 配置文件应该叫 shuffle-server.conf 还是 server.conf？ 0.10.0 为 conf/server.conf。启动脚本 start-shuffle-server.sh 固定读取 server.conf，旧文件名不会被加载。
Q4：如何验证 JVM 堆参数真的生效？ 用 jps -v（或 ps -ef | grep '[j]ava'）查看进程参数，输出中应出现 rss-env.sh 设置的 -Xms 与 -Xmx 值，例如 512MB 配置对应 -Xms512m -Xmx512m。
Q5：LOCALFILE 存储类型启动报 should be used in test mode 是 bug 吗？ 不是 bug，是 0.10.0 的明确限制：LOCALFILE 与 HDFS 两种直写类型性能不达标，仅允许测试模式使用。验证环境在 server.conf 设 rss.test.mode.enable true，并在 Spark 客户端设 spark.rss.test.mode.enable true；生产使用 MEMORY_LOCALFILE 或 MEMORY_LOCALFILE_HDFS。
九、参考链接
- Apache Uniffle 官方文档（配置）：https://uniffle.apache.org/docs
- 官方源码 CoordinatorConf/ShuffleServerConf 定义：https://github.com/apache/uniffle/tree/main/common/src/main/java/org/apache/uniffle/common/config
- 项目源码仓库：https://github.com/apache/uniffle