RESTServer 起不来,日志只有一行:headerCacheSize 65536 exceeds maximum value of 65534

0 阅读9分钟

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 路径均为脱敏示例值,请替换成你自己的环境。

目录


一、先说结论

某运营商的行业大数据平台(下文简称 大数据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 对接半天

三条可复用的经验,写在最前面:

  1. 异常栈第一行决定排查方向。IllegalArgumentException 出现在 HttpConfiguration 里,说明是 HTTP 传输层建不起来,跟 Kerberos、跟表、跟 RegionServer 都没关系,可以一次排除掉一半猜测。
  2. 配置找不到,就去字节码里找。javap -p -constants 十秒就能证明"这个值是硬编码的",比翻文档、翻 issue 快得多。
  3. 补丁要能自己验证。编完先 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

这两段输出把问题钉死了,看两个细节:

  1. 三处调用的实参是同一条 ldc #151,也就是同一个常量 DEFAULT_HTTP_MAX_HEADER_SIZE = 64 * 1024;
  2. 调用外面没有任何 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 UIhttp://<hmaster>:16010(2.x)
RegionServer UIhttp://<rs>:16030
REST Info Serverhttp://<rest>:8085(hbase.rest.info.port)
数据面 HTTP 访问部署 RESTServer(8080)

十一、排错速查

现象大概率原因处理
IllegalArgumentException: headerCacheSize ...2.3.4 硬编码 64KB,Jetty 上限 65534改常量重编译 / 升级
401 Unauthorized没 kinit、票据过期、curl 无 SPNEGOkinit + klist + curl -V
GSS initiate failedPrincipal 与访问域名不匹配用 FQDN 访问或改 hosts
403 Forbiddenhbase.rest.readonly=true 却发了写请求改配置或只读调用
404 Not Found表名漏了 namespace(应为 ns:table)补 namespace
返回空 200行键被二次 Base64只编码一次
Too many scannersScanner 没 DELETE用完即删,控制并发
浏览器打不开 9090Thrift 无 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#_…