RESTServer 起不来,日志只有一行:headerCacheSize 65536 exceeds maximum value of 65534
关键词:HBase 2.3.4、RESTServer、Stargate、Jetty、HttpConfiguration、headerCacheSize、Character.MAX_VALUE、javap 反汇编、Kerberos、SPNEGO、hbase.rest.http.header.cache.size、Thrift2
说明:文中主机名、IP、Principal、keytab 路径均为脱敏示例值,请替换成你自己的环境。
目录
- 一、先说结论
- 二、现场:进程起不来,日志只有一句
- 三、第一次误判:翻遍配置找不到开关
- 四、转折:javap 看到的是字面量
- 五、65534 这个数字从哪来
- 六、三种修法
- 七、编译、验包、替换、验证
- 八、服务起来之后:REST + Kerberos 对接
- 九、真正对接时才踩的两个坑:Base64 和 Scanner
- 十、顺带说说同集群的 Thrift2
- 十一、排错速查
- 十二、复盘
一、先说结论
某运营商的行业大数据平台(下文简称 大数据Hadoop集群)需要把 HBase 明细数据以 HTTP 接口开放给 Python / Go 业务系统。集群是 Kerberos 安全模式、HBase 2.3.4,同机还有一套 Thrift2 在跑。
Thrift2 起得挺好,RESTServer 一启动就挂:
java.lang.IllegalArgumentException: headerCacheSize 65536 exceeds maximum value of 65534
结论先摆出来:
| 项 | 结论 |
|---|---|
| 现象 | 启动即抛 IllegalArgumentException,Jetty Server 根本没起来 |
| 直接原因 | HBase 2.3.4 在 RESTServer.createServer() 里把 headerCacheSize 硬编码成 64 * 1024 |
| 根本原因 | Jetty 这个参数的上限是 Character.MAX_VALUE - 1 = 65534,多 2 字节就炸 |
能不能通过 hbase-site.xml 改 | 不能,2.3.4 没有这个配置项,字节码里直接是字面量 |
| 我们怎么修的 | 改一行常量,重编 hbase-rest 模块,换 jar |
| 更彻底的写法 | 拆成 hbase.rest.http.header.cache.size(后来官方就是这么改的) |
| 耗时 | 定位约 2 小时,编译替换约 1.5 小时,REST 对接半天 |
三条可复用的经验,写在最前面:
- 异常栈第一行决定排查方向。
IllegalArgumentException出现在HttpConfiguration里,说明是 HTTP 传输层建不起来,跟 Kerberos、跟表、跟 RegionServer 都没关系,可以一次排除掉一半猜测。 - 配置找不到,就去字节码里找。
javap -p -constants十秒就能证明"这个值是硬编码的",比翻文档、翻 issue 快得多。 - 补丁要能自己验证。编完先
javap验 jar,再上机替换,最后看日志和端口——不然滚动重启时你都不知道挂的是新包还是旧包。
二、现场:进程起不来,日志只有一句
hbase-daemon.sh start rest
jps -l | grep -i rest # 什么都没有
日志($HBASE_LOG_DIR/hbase-root-rest-<host>.out):
ERROR [main] rest.RESTServer: Failed to start the REST server
java.lang.IllegalArgumentException: headerCacheSize 65536 exceeds maximum value of 65534
at org.eclipse.jetty.http.HttpConfiguration.setHeaderCacheSize(HttpConfiguration.java)
at org.apache.hadoop.hbase.rest.RESTServer.createServer(RESTServer.java)
at org.apache.hadoop.hbase.rest.RESTServer.run(RESTServer.java)
at org.apache.hadoop.hbase.rest.RESTServer.doMain(RESTServer.java)
at org.apache.hadoop.hbase.rest.RESTServer.main(RESTServer.java)
行号随发行版和补丁不同会有差异,类名、方法名是固定的。
现场很"干净":不是 401,不是端口被占,不是 NoSuchTableException。就是参数校验不过,构造 HTTP 连接器时直接抛异常,main 线程退出,进程秒退。
第一印象是"是不是哪个配置写得太大",于是进入了第一次误判。
三、第一次误判:翻遍配置找不到开关
翻 hbase-site.xml、hbase-default.xml,按 header、max.header、rest.http、buffer 一通搜,REST 相关的配置只有这些:
hbase.rest.port
hbase.rest.host
hbase.rest.readonly
hbase.rest.info.port
hbase.rest.threads.max / min
hbase.rest.task.queue.size
hbase.rest.ssl.*
hbase.rest.keytab.file
hbase.rest.kerberos.principal
hbase.rest.authentication.type
hbase.rest.csrf.*
没有一个跟 HTTP header 尺寸有关。
再看命令行参数,hbase rest start 只支持三个:
-p / --port 绑定端口
-ro / --readonly 只允许 GET
-i / --infoport Info Server 端口
折腾了半个多小时,确认结论:2.3.4 这一版里,这个值写死在代码里,运行时改不动。
那它到底写死成多少、被谁用掉了?到这里就不该继续查文档了,直接看字节码。
四、转折:javap 看到的是字面量
发行包里现成的 jar 就能反汇编,不需要源码,也不需要反编译工具:
# 1) 看常量:static final int 带 ConstantValue 属性,javap -constants 能直接读出来
javap -p -constants \
-classpath $HBASE_HOME/lib/hbase-rest-2.3.4.jar \
org.apache.hadoop.hbase.rest.RESTServer | grep -i header
# 输出(未打补丁的官方 2.3.4):
# static final int DEFAULT_HTTP_MAX_HEADER_SIZE = 65536;
# 2) 看它被谁用了:-c 反汇编方法体
javap -p -c \
-classpath $HBASE_HOME/lib/hbase-rest-2.3.4.jar \
org.apache.hadoop.hbase.rest.RESTServer | grep -A2 -B2 setHeaderCacheSize
createServer(...) 里对应的字节码大致长这样:
289: ldc #151 // int 65536
291: invokevirtual #152 // Method .../HttpConfiguration.setHeaderCacheSize:(I)V
296: ldc #151 // int 65536
298: invokevirtual #153 // Method .../HttpConfiguration.setRequestHeaderSize:(I)V
303: ldc #151 // int 65536
305: invokevirtual #154 // Method .../HttpConfiguration.setResponseHeaderSize:(I)V
这两段输出把问题钉死了,看两个细节:
- 三处调用的实参是同一条
ldc #151,也就是同一个常量DEFAULT_HTTP_MAX_HEADER_SIZE = 64 * 1024; - 调用外面没有任何
conf.getInt(...)——如果是从配置读的,字节码里一定会先出现invokevirtual Configuration.getInt。没有,就是写死的。
对应的源码逻辑(HBase 2.3.4):
HttpConfiguration httpConfig = new HttpConfiguration();
httpConfig.setSecureScheme("https");
httpConfig.setSecurePort(port);
httpConfig.setHeaderCacheSize(DEFAULT_HTTP_MAX_HEADER_SIZE); // 65536 → 越界
httpConfig.setRequestHeaderSize(DEFAULT_HTTP_MAX_HEADER_SIZE);
httpConfig.setResponseHeaderSize(DEFAULT_HTTP_MAX_HEADER_SIZE);
httpConfig.setSendServerVersion(false);
httpConfig.setSendDateHeader(false);
顺便说一句,这个手法在排查任何"配置改了不生效"的问题时都好用:先确认这个值是不是从配置读的,再决定继续查配置还是查代码。
五、65534 这个数字从哪来
65534 = 0xFFFE = Character.MAX_VALUE - 1。
Jetty 的 HttpConfiguration#setHeaderCacheSize(int) 对 header 字段缓存做了上限校验,上限就是 Character.MAX_VALUE - 1,超过直接抛我们看到的那个异常。至于为什么是 65534 而不是 65535,一般理解为 Jetty 内部用 16 位长度表示字段缓存,0xFFFF 保留作哨兵,可用上限只剩 0xFFFE = 65534。
一个很硬的旁证:后来 HBase 官方修这个问题时,新增的默认值直接写成了这个表达式——
static final String HTTP_HEADER_CACHE_SIZE = "hbase.rest.http.header.cache.size";
static final int DEFAULT_HTTP_HEADER_CACHE_SIZE = Character.MAX_VALUE - 1; // 65534
这里还有一个容易误判的细节:setRequestHeaderSize(65536)、setResponseHeaderSize(65536) 这两句并不会抛异常,Jetty 对 request/response 缓冲的上限放得更宽。所以:
- 官方后来的修法是"只把 cache size 拆成可配置",request/response 仍然是 64KB;
- 我们线上图省事,把三处统一改成 65534。
两种做法功能等价,65534 只比 65536 少 2 字节,对真实业务请求头毫无影响,可以放心用。
六、三种修法
方案 A:改常量重编译(我们采用的,改动最小)
目标文件:hbase-rest/src/main/java/org/apache/hadoop/hbase/rest/RESTServer.java
- static final int DEFAULT_HTTP_MAX_HEADER_SIZE = 64 * 1024; // 64k
+ static final int DEFAULT_HTTP_MAX_HEADER_SIZE = Character.MAX_VALUE - 1; // 65534, Jetty 上限
一行改动,重新编译 hbase-rest 模块。
方案 B:拆成可配置项(推荐,贴合上游)
如果不想以后再为同类问题动源码,按官方思路改造:
static final int DEFAULT_HTTP_MAX_HEADER_SIZE = 64 * 1024; // 64k
static final String HTTP_HEADER_CACHE_SIZE = "hbase.rest.http.header.cache.size";
static final int DEFAULT_HTTP_HEADER_CACHE_SIZE = Character.MAX_VALUE - 1; // 65534
// createServer(...) 中:
int headerCacheSize =
conf.getInt(HTTP_HEADER_CACHE_SIZE, DEFAULT_HTTP_HEADER_CACHE_SIZE);
httpConfig.setHeaderCacheSize(headerCacheSize);
httpConfig.setRequestHeaderSize(DEFAULT_HTTP_MAX_HEADER_SIZE);
httpConfig.setResponseHeaderSize(DEFAULT_HTTP_MAX_HEADER_SIZE);
hbase-site.xml 里就可以调了(不配则用默认 65534):
<property>
<name>hbase.rest.http.header.cache.size</name>
<value>32768</value>
</property>
方案 C:升级版本
较新的 HBase 分支已经把这一处改成可配置(hbase.rest.http.header.cache.size,默认 Character.MAX_VALUE - 1)。
但生产上不建议为了这一行直接升级:2.3.x 到 2.4.x 之间有 client API、Netty、Jersey、Jetty 版本的一串变化,要回归 RegionServer、Master 和所有 Java 客户端。务实做法是:先按 A / B 打补丁把业务跑起来,版本升级单独排窗口。
七、编译、验包、替换、验证
7.1 编译
只需要 hbase-rest 模块,-am 带上依赖模块,跳过测试与静态检查:
cd /data/build/hbase-2.3.4
mvn -T 4C -DskipTests -Dcheckstyle.skip -Dspotbugs.skip \
clean package -pl hbase-rest -am
ls -lh hbase-rest/target/hbase-rest-2.3.4.jar
编译 JDK 要和运行环境一致(2.3.x 建议 JDK 8);如果构建环境对 Hadoop 版本有要求,按官方
BUILDING.txt追加-Dhadoop.profile=3.0之类,否则可能编出依赖不匹配的包。
7.2 验包(不上机就能验)
javap -p -constants \
-classpath hbase-rest/target/hbase-rest-2.3.4.jar \
org.apache.hadoop.hbase.rest.RESTServer | grep DEFAULT_HTTP_MAX_HEADER_SIZE
# 期望:static final int DEFAULT_HTTP_MAX_HEADER_SIZE = 65534;
先验包、后上机,能避免把没编进去的包滚到生产——这个坑我们踩过一次。
7.3 替换
HBASE_HOME=/opt/hbase
cd $HBASE_HOME/lib
# 备份
cp -a hbase-rest-2.3.4.jar hbase-rest-2.3.4.jar.bak.$(date +%Y%m%d)
# 替换并修权限
cp /data/build/hbase-2.3.4/hbase-rest/target/hbase-rest-2.3.4.jar ./
chown hbase:hbase hbase-rest-2.3.4.jar
chmod 644 hbase-rest-2.3.4.jar
md5sum hbase-rest-2.3.4.jar
REST 如果做多实例挂在 LB 后面,每台都要换。
hbase-daemon.sh只管本机,漏一台就会在滚动重启时被流量打到旧包节点上,继续宕。
7.4 重启与验证
hbase-daemon.sh stop rest
hbase-daemon.sh start rest
jps -l | grep -i rest # 进程
netstat -anp | grep 8080 # 端口
tail -n 100 $HBASE_LOG_DIR/hbase-root-rest-*.out # 不再有 IllegalArgumentException
看到 8080 处于 LISTEN,第一段就算过了。
八、服务起来之后:REST + Kerberos 对接
8.1 服务端配置
<property>
<name>hbase.rest.port</name>
<value>8080</value>
</property>
<property>
<name>hbase.rest.host</name>
<value>0.0.0.0</value>
</property>
<!-- SPNEGO 认证 -->
<property>
<name>hbase.rest.authentication.type</name>
<value>kerberos</value>
</property>
<property>
<name>hbase.rest.kerberos.principal</name>
<value>hbase/_HOST@EXAMPLE.COM</value>
</property>
<property>
<name>hbase.rest.keytab.file</name>
<value>/opt/keytab/hbase.keytab</value>
</property>
_HOST会自动替换成当前机器 FQDN。如果客户端用 IP 访问、而 Principal 里是域名,SPNEGO 协商会失败(Server not found in Kerberos database/GSS initiate failed),要么访问时用域名,要么把 IP 写进/etc/hosts。
8.2 客户端拿票据
kinit -kt /opt/keytab/hbase.keytab hbase/_HOST@EXAMPLE.COM
klist # 确认票据未过期
curl -V | grep -i spnego # 确认 curl 编进了 GSS-Negotiate
8.3 三个接口跑通
(1)列出所有表
curl -sS --negotiate -u : \
-H "Accept: application/json" \
"http://10.0.0.11:8080/" | python3 -m json.tool
{"table": [
{"name": "hbase:meta"},
{"name": "test:test_table"}
]}
(2)查表 Schema
curl -sS --negotiate -u : \
-H "Accept: application/json" \
"http://10.0.0.11:8080/test:test_table/schema" | python3 -m json.tool
返回列族 cf 的全套属性(VERSIONS、TTL、BLOCKCACHE…),拿来校验建表是否符合预期很顺手。
(3)按行键取一行
HOST=10.0.0.11; PORT=8080
TABLE=test:test_table; ROWKEY=1
curl -sS --negotiate -u : -v -X GET \
-H "Accept: text/xml" \
"http://${HOST}:${PORT}/${TABLE}/${ROWKEY}"
200 OK,响应体:
<?xml version="1.0" encoding="UTF-8"?>
<CellSet>
<Row key="MQ=="> <!-- "MQ==" 是行键 "1" 的 Base64 -->
<Cell column="Y2Y6" timestamp="1700000000000">aaaaaa</Cell>
<!-- column="Y2Y6" 是 "cf:" 的 Base64 -->
</Row>
</CellSet>
和 hbase shell 里 get 'test:test_table','1' 的结果一一对应,只是行列值都做了 Base64。
九、真正对接时才踩的两个坑:Base64 和 Scanner
9.1 Base64:业务方看第一眼就懵
REST 返回的行键、列名、Cell 值默认全部 Base64。给业务方一个能直接看懂输出的包装脚本,比发一份文档管用:
#!/usr/bin/env bash
# rest_get.sh <table> <rowkey>
set -euo pipefail
HOST="${HBASE_REST_HOST:-10.0.0.11}"
PORT="${HBASE_REST_PORT:-8080}"
TABLE="$1"; ROWKEY="$2"
curl -sS --negotiate -u : --connect-timeout 5 \
-H "Accept: application/json" \
"http://${HOST}:${PORT}/${TABLE}/${ROWKEY}" \
| python3 -c '
import base64, json, sys
def b64(s):
if s is None:
return None
return base64.b64decode(s + "=" * (-len(s) % 4)).decode("utf-8", "replace")
obj = json.load(sys.stdin)
for row in obj.get("Row", []):
print("rowkey:", b64(row.get("key")))
for c in row.get("Cell", []):
print(" %-16s ts=%-14s %s" % (b64(c.get("column")), c.get("timestamp"), b64(c.get("$"))))
'
rowkey: 1
cf: ts=1700000000000 aaaaaa
Python / Java 侧同理,别忘了补 = 填充(-len(s) % 4),否则会抛 Incorrect padding。
9.2 Scanner:id 在响应头里,用完必须删
点查用 GET /{table}/{rowkey},批量扫要走 Scanner 两段式。这里有两个坑:
HOST=10.0.0.11; PORT=8080; TABLE=test:test_table
# 1) 创建 scanner:scanner id 在响应头 Location 里,body 是空的
SCAN_URL=$(curl -sS -D - -o /dev/null --negotiate -u : -X POST \
-H "Content-Type: text/xml" \
--data '<Scanner batch="100"/>' \
"http://${HOST}:${PORT}/${TABLE}/scanner" \
| awk 'tolower($1)=="location:"{sub(/\r$/,"",$2); print $2}')
# 2) 反复取,直到 204 No Content
curl -sS --negotiate -u : -H "Accept: application/json" "$SCAN_URL"
# 3) 用完必须释放
curl -sS --negotiate -u : -X DELETE "$SCAN_URL"
坑一:id 在 Location 响应头里,不在 body 里,照着"返回 JSON"的思路去解析会拿到空字符串。 坑二:不 DELETE 会一直占着 RS 的 scanner lease(默认 60s),并发一高就是 Too many scanners + RegionServer 卡顿。用完即删,写进规范。
十、顺带说说同集群的 Thrift2
REST 和 Thrift2 在同一个集群并存很常见:REST 面向联调和轻量集成,Thrift2 面向高吞吐批量接口。
10.1 起没起来,三条命令
jps -l | grep -i thrift
# 4493 org.apache.hadoop.hbase.thrift2.ThriftServer
ps -ef | grep 4493 | grep -v grep
netstat -anp | grep 4493
10.0.0.12:9090 (LISTEN) # Thrift 主服务端口
10.0.0.12:10103 (LISTEN) # JMX(-Dcom.sun.management.jmxremote.port=10103)
启动命令里能看到 org.apache.hadoop.hbase.thrift2.ThriftServer start,JMX 端口是启动参数指定的。端口 9095 / 39635 之类是内部通信和临时端口,不用管。
10.2 Kerberos 下的关键配置
<!-- 明确关闭 HTTP 代理模式:Thrift 只走二进制协议 -->
<property>
<name>hbase.regionserver.thrift.http</name>
<value>false</value>
</property>
<property>
<name>hbase.thrift.support.proxyuser</name>
<value>false</value>
</property>
<!-- 服务端自身的 Kerberos 身份 -->
<property>
<name>hbase.thrift.keytab.file</name>
<value>/opt/keytab/hbase.keytab</value>
</property>
<property>
<name>hbase.thrift.kerberos.principal</name>
<value>hbase/_HOST@EXAMPLE.COM</value>
</property>
<!-- 关键:注释掉 qop,客户端到 Thrift 之间不再强制 SASL 认证 -->
<!--
<property>
<name>hbase.thrift.security.qop</name>
<value>authentication</value>
</property>
-->
注释掉 hbase.thrift.security.qop 之后,链路变成:
业务客户端 ──(明文 Thrift)──> Thrift2 Server ──(自身 keytab 认证)──> HBase
Thrift2 用自己配置的 keytab 跟后端 HBase 认证,业务侧只要连通 9090 就行,不必持有票据——这也是很多项目最终选择 Thrift2 的原因。
⚠️ 但这等于把 9090 变成一个免认证入口:任何能连上该端口的人,都以
hbase用户身份读写全表。生产上必须三件事一起做:① 防火墙/安全组白名单,只放业务网段;② 尽量恢复qop=authentication,让客户端走 SASL;③hbase.thrift.support.proxyuser=false明确禁用代理身份。REST 侧同理,别为了"联调方便"长期关掉 SPNEGO。
10.3 为什么浏览器打开 9090 什么都没有
因为 Thrift Server 压根没有 Web UI——它是 Thrift IDL 定义的 RPC 服务,本例里 hbase.regionserver.thrift.http 还是 false,端口上跑的是二进制协议,用浏览器访问只会得到连接重置。
想看 Web 界面的话:
| 用途 | 地址 |
|---|---|
| HBase Master UI | http://<hmaster>:16010(2.x) |
| RegionServer UI | http://<rs>:16030 |
| REST Info Server | http://<rest>:8085(hbase.rest.info.port) |
| 数据面 HTTP 访问 | 部署 RESTServer(8080) |
十一、排错速查
| 现象 | 大概率原因 | 处理 |
|---|---|---|
IllegalArgumentException: headerCacheSize ... | 2.3.4 硬编码 64KB,Jetty 上限 65534 | 改常量重编译 / 升级 |
401 Unauthorized | 没 kinit、票据过期、curl 无 SPNEGO | kinit + klist + curl -V |
GSS initiate failed | Principal 与访问域名不匹配 | 用 FQDN 访问或改 hosts |
403 Forbidden | hbase.rest.readonly=true 却发了写请求 | 改配置或只读调用 |
404 Not Found | 表名漏了 namespace(应为 ns:table) | 补 namespace |
返回空 200 | 行键被二次 Base64 | 只编码一次 |
Too many scanners | Scanner 没 DELETE | 用完即删,控制并发 |
| 浏览器打不开 9090 | Thrift 无 Web UI | 看 16010 / 16030 |
十二、复盘
这次问题的价值不在那"一行常量",而在三条方法论:
第一,先分层再猜。 异常来自 Jetty 而不是 HBase 的认证或存储层,直接排掉了一大半方向。很多人一看到 Kerberos 集群启动失败就往 kinit、keytab、qop 上扑,实际上报错连 HBase 的业务代码都没走到。
第二,配置找不到就去看字节码。 javap -p -constants 证明常量值,javap -p -c 证明"没有 conf.getInt 包裹",两条证据加起来,"此版本不可配置"就是板上钉钉,不用再翻文档猜。这个方法对任何"配置改了不生效"的问题都成立。
第三,补丁要闭环。 编译 → javap 验包 → 逐台替换 → 重启 → 看日志和端口,五步走完再宣布修好。省掉验包这一步,就等着在滚动重启时发现"怎么还是旧的"。
最后一句还是安全:Kerberos 集群里,为了联调方便而注释 qop、关 SPNEGO、长期保留匿名入口,本质是把风险从配置层挪到了网络层。能用 keytab + SPNEGO 走通,就别用"先关掉认证"这条路——真出问题时,日志里连是谁干的都查不出来。
参考
- HBase RESTServer 源码:
hbase-rest/src/main/java/org/apache/hadoop/hbase/rest/RESTServer.java - Jetty
HttpConfiguration#setHeaderCacheSize - HBase REST 官方文档:hbase.apache.org/book.html#_…