Apache Zeppelin 0.12.1 配置参数详解

一、环境信息

二、前置条件

1. 已按安装指南完成 Zeppelin 0.12.1 部署，安装目录为 /opt/zeppelin。
2. 掌握基本的文件编辑操作，本文修改配置后均需重启服务生效：

cd /opt/zeppelin && bin/zeppelin-daemon.sh restart

3. 验证 JVM 参数需要 JDK 自带的 jps 与 jcmd 工具（java-11-openjdk-devel 或 openjdk-11-jdk 包均已包含）。

三、参数查看与修改方式

3.1 两类配置文件

Zeppelin 的参数分布在 conf 目录下两类文件中：

两个文件均由模板复制而来，conf 目录初始状态只有 zeppelin-env.sh.template 与 zeppelin-site.xml.template：

ls /opt/zeppelin/conf/

configuration.xsl  interpreter-list  log4j.properties  log4j.properties2  log4j2.properties
log4j_yarn_cluster.properties  shiro.ini.template  zeppelin-env.cmd.template  zeppelin-env.sh.template
zeppelin-site.xml.template

3.2 查看当前生效参数

官方 REST 接口可查看运行中服务读取到的全部配置（实测命令）：

curl -s http://127.0.0.1:8080/api/configurations/all | head -c 300

{"status":"OK","message":"","body":{"zeppelin.notebook.dir":"notebook","zeppelin.server.port":"8080","zeppelin.server.addr":"0.0.0.0",

3.3 修改与生效规则

1. zeppelin-env.sh 中的同名 export 变量重复出现时，后一行覆盖前一行，编辑前先 grep 确认无重复。
2. 环境变量与 zeppelin-site.xml 同名参数（如 ZEPPELIN_PORT 对应 zeppelin.server.port）实测以环境变量优先：实测将 ZEPPELIN_PORT 改为 8081 后重启，8081 返回 HTTP 200 且 8080 不再监听。
3. 所有修改必须重启 Zeppelin 进程后生效，jcmd 读取的运行时参数是最终判定依据。

四、参数总览

4.1 zeppelin-env.sh 常用环境变量

4.2 zeppelin-site.xml 核心参数

conf/zeppelin-site.xml.template 共 118 个 property，核心参数如下：

五、核心参数分类详解

5.1 服务地址与端口参数

监听地址与端口由 ZEPPELIN_ADDR 与 ZEPPELIN_PORT 控制，或由 zeppelin-site.xml 中 zeppelin.server.addr 与 zeppelin.server.port 控制。对外提供服务必须把地址改为 0.0.0.0（默认 127.0.0.1 仅本机可访问）。

实测：将 zeppelin-env.sh 中 ZEPPELIN_PORT 改为 8081 并重启：

cd /opt/zeppelin && bin/zeppelin-daemon.sh restart

Zeppelin stop                                              [  OK  ]
Zeppelin start                                             [  OK  ]

curl -s -o /dev/null -w '8081 HTTP %{http_code}\n' http://127.0.0.1:8081/

8081 HTTP 200

同时启动日志可见新端口已监听（节选自 logs/zeppelin-运行用户-主机名.log）：

INFO [2026-10-12 06:26:02,960] ({main} AbstractConnector.java[doStart]:376) - Started ServerConnector@6771beb3{HTTP/1.1, (http/1.1)}{0.0.0.0:8081}
INFO [2026-10-12 06:26:02,966] ({main} ZeppelinServer.java[startZeppelin]:274) - Done, zeppelin server started

修改端口后需同步放行防火墙（Ubuntu 用 ufw allow 8081/tcp，CentOS 用 firewall-cmd --permanent --add-port=8081/tcp 后 firewall-cmd --reload）。

5.2 JVM 内存参数（堆限定 256-512MB）

限定主进程堆内存必须使用 ZEPPELIN_MEM。实测发现一个关键覆盖关系：启动脚本 bin/common.sh 第 150 行拼接 JVM 参数时，顺序依次为 ZEPPELIN_JAVA_OPTS 的内容、文件编码参数、ZEPPELIN_MEM 的内容，三者以空格连接成一个 JAVA_OPTS 字符串。若 ZEPPELIN_MEM 未设置，common.sh 第 142 至 143 行会将其赋为默认值 -Xmx1024m，恰好位于拼接末尾。由于 JVM 对重复出现的 -Xmx 取最后一次的值，把 -Xmx 写进 ZEPPELIN_JAVA_OPTS 会被末尾默认值覆盖，实测 jps -v 会同时看到 -Xmx512m 与 -Xmx1024m，且 jcmd 读取的运行时堆为 1024MB。

正确写法（conf/zeppelin-env.sh）：

export ZEPPELIN_MEM="-Xms256m -Xmx512m -XX:MaxMetaspaceSize=256m"
export ZEPPELIN_JAVA_OPTS="-Dfile.encoding=UTF-8"

重启后两级验证（实测回显，日志文件名中的主机名因环境而异）：

jps -v | grep ZeppelinServer

4937 ZeppelinServer -Dfile.encoding=UTF-8 -Xms256m -Xmx512m -XX:MaxMetaspaceSize=256m -Dlog4j.configuration=file:///opt/zeppelin/conf/log4j.properties -Dzeppelin.log.file=/opt/zeppelin/logs/zeppelin-root-zeppelin-node01.log

jcmd $(jps | awk '/ZeppelinServer/{print $1}') VM.flags | tr ' ' '\n' | grep -E 'HeapSize'

-XX:InitialHeapSize=268435456
-XX:MaxHeapSize=536870912

InitialHeapSize 268435456 字节即 256MB，MaxHeapSize 536870912 字节即 512MB，说明 ZEPPELIN_MEM 配置已实际生效。解释器进程内存单独由 ZEPPELIN_INTP_MEM 控制，轻量场景同样建议限制。

5.3 目录与笔记本存储参数

日志、进程号与笔记本目录分别对应 ZEPPELIN_LOG_DIR、ZEPPELIN_PID_DIR、ZEPPELIN_NOTEBOOK_DIR（或 site.xml 中 zeppelin.notebook.dir 等）。将笔记本目录迁移到独立数据盘是常见需求。

实测：把笔记本目录改到 /data/zeppelin-notebook 并迁移数据。

第一步，修改 conf/zeppelin-env.sh（确认全文只有一行该变量）：

export ZEPPELIN_NOTEBOOK_DIR="/data/zeppelin-notebook"

第二步，停止服务后迁移已有笔记本（默认 Git 存储实现会在笔记本目录维护 .git 仓库，需整体拷贝）：

bin/zeppelin-daemon.sh stop

Zeppelin stop                                              [  OK  ]

mkdir -p /data/zeppelin-notebook

cp -a /opt/zeppelin/notebook/. /data/zeppelin-notebook/

第三步，启动并验证（实测回显）：

bin/zeppelin-daemon.sh start

Zeppelin start                                             [  OK  ]

curl -s http://127.0.0.1:8080/api/notebook | grep -o '2N7GTCPK6' | head -1

2N7GTCPK6

迁移前的笔记本 ID 出现在列表中，说明新目录读取正常。若不迁移数据仅改目录，笔记本列表将只剩新目录内容，表现为所有笔记本消失。

5.4 认证与安全参数

Zeppelin 0.12.1 默认匿名放行。开启认证需要三步，全部实测通过。

第一步，conf/zeppelin-site.xml 中将内置参数 zeppelin.anonymous.allowed 设为 false。该参数不在 site.xml.template 中，需在 configuration 标签末尾手动追加 property：

<property>
  <name>zeppelin.anonymous.allowed</name>
  <value>false</value>
</property>

第二步，从模板创建 conf/shiro.ini 并配置管理员账号（示例 admin、密码 q1w2e3r4）：

cp /opt/zeppelin/conf/shiro.ini.template /opt/zeppelin/conf/shiro.ini

shiro.ini 有效内容如下（模板其余样例段可删除）：

[users]
admin = q1w2e3r4, admin

[main]
sessionManager = org.apache.shiro.web.session.mgt.DefaultWebSessionManager
cookie = org.apache.shiro.web.servlet.SimpleCookie
cookie.name = JSESSIONID
cookie.httpOnly = true
cookie.sameSite = LAX
sessionManager.sessionIdCookie = $cookie
securityManager.sessionManager = $sessionManager
securityManager.sessionManager.globalSessionTimeout = 86400000
shiro.loginUrl = /api/login

[roles]
admin = *

[urls]
/api/version = anon
/** = authc

第三步，重启服务并实测三种访问（实测回显）：

bin/zeppelin-daemon.sh restart

未登录访问受保护接口，返回 302 重定向到登录页：

curl -s -o /dev/null -w 'HTTP %{http_code}\n' http://127.0.0.1:8080/api/notebook

HTTP 302

登录获取会话（注意 0.12.1 的 /api/login 只接受表单编码，JSON 提交会报 Internal server error）：

curl -s -c /tmp/zp_cookie.txt -X POST http://127.0.0.1:8080/api/login -d 'userName=admin&password=q1w2e3r4'

{"status":"OK","message":"","body":{"principal":"admin","ticket":"2fc8372f-68f6-4629-9852-df347d486bb7","roles":"[\"admin\"]"}}

带会话访问，返回 200：

curl -s -b /tmp/zp_cookie.txt -o /dev/null -w 'HTTP %{http_code}\n' http://127.0.0.1:8080/api/notebook

HTTP 200

错误密码登录返回 403：

curl -s -o /dev/null -w 'HTTP %{http_code}\n' -X POST http://127.0.0.1:8080/api/login -d 'userName=admin&password=wrongpass'

HTTP 403

[urls] 段中 anon 表示匿名放行，authc 表示必须登录；模板还提供 roles[admin] 级别的接口保护（如 /api/interpreter/** 与 /api/credential/**），URL 规则按出现顺序匹配且第一条命中即生效。

5.5 日志参数

日志目录由 ZEPPELIN_LOG_DIR 控制（默认相对路径 logs，即 /opt/zeppelin/logs）。日志格式由 conf/log4j2.properties 定义，默认输出文件名规律为 zeppelin-运行用户-主机名.log。实测查看最近错误：

grep -iE 'ERROR' /opt/zeppelin/logs/zeppelin-root-zeppelin-node01.log | tail -3

ERROR [2026-10-12 06:21:56,306] ({qtp1850777594-31} WebApplicationExceptionMapper.java[toResponse]:42) - Error response

排障时重点关注 zeppelin-root 主日志与 logs/zeppelin-interpreter-sh-shared_process-运行用户-主机名.log 解释器日志两类文件。

六、生产配置模板

以下为轻量场景（2 核 4GB 内存、40GB 数据盘、单机部署、数十名以内分析用户）实测可用的配置模板。内存约束：主进程堆 256MB 至 512MB；磁盘约束：系统盘加数据盘不低于 40GB，笔记本按日均增长 10MB 预估。

conf/zeppelin-env.sh 推荐内容：

# 主进程 JVM：堆 256MB 起步、上限 512MB
export ZEPPELIN_MEM="-Xms256m -Xmx512m -XX:MaxMetaspaceSize=256m"
# 解释器进程内存同步限制
export ZEPPELIN_INTP_MEM="-Xms256m -Xmx512m"
export ZEPPELIN_JAVA_OPTS="-Dfile.encoding=UTF-8"
# 监听全部网卡，端口按需调整
export ZEPPELIN_ADDR="0.0.0.0"
export ZEPPELIN_PORT=8080
# 目录规划：日志与笔记本落在数据盘
export ZEPPELIN_LOG_DIR="/data/zeppelin/logs"
export ZEPPELIN_PID_DIR="/data/zeppelin/run"
export ZEPPELIN_NOTEBOOK_DIR="/data/zeppelin/notebook"

conf/zeppelin-site.xml 建议修改的 property：

<property>
  <name>zeppelin.anonymous.allowed</name>
  <value>false</value>
</property>
<property>
  <name>zeppelin.websocket.max.text.message.size</name>
  <value>10240000</value>
</property>

配套动作清单：创建 /data/zeppelin 三个子目录并赋权；创建 conf/shiro.ini 配置 admin 管理员账号（示例密码 q1w2e3r4）；防火墙放行 8080；通过 bin/zeppelin-systemd-service.sh enable 注册开机自启。

七、常见问题

Q1：修改端口或地址后访问仍是旧行为。 先确认修改的是 conf 下真实生效的文件（不是 template 模板），再检查 zeppelin-env.sh 中同名 export 是否出现多行（后一行覆盖前一行，实测曾出现两行 ZEPPELIN_NOTEBOOK_DIR 导致目录配置不生效），最后重启服务并用 jps 确认进程号已更换。

Q2：ZEPPELIN_JAVA_OPTS 里写了 -Xmx512m，实际堆还是 1024MB。 bin/common.sh 拼接参数时默认的 ZEPPELIN_MEM 等于 -Xmx1024m 位于末尾，JVM 取最后一个 -Xmx。把堆参数移到 ZEPPELIN_MEM 并重启，用 jcmd 进程号 VM.flags 验证 MaxHeapSize 等于 536870912。

Q3：/api/login 用 JSON 提交报 Internal server error。 0.12.1 的登录接口要求 application/x-www-form-urlencoded 表单格式，应使用 -d 'userName=admin&password=q1w2e3r4' 提交；JSON 请求会在日志中留下 The @FormParam is utilized when the content type of the request entity is not application/x-www-form-urlencoded 异常。

Q4：开启认证后访问接口返回 302 而不是 401。 Shiro 的 authc 过滤器对未登录请求执行重定向到登录页，302 属预期行为；登录失败（密码错误）返回 403。判断认证是否生效应以带会话 cookie 请求是否返回 200 为准。

Q5：改了笔记本目录后 WebUI 里笔记本全部消失。 新目录为空，需要停服后把原目录内容整体拷贝到新目录（含隐藏的 .git），再启动服务。参见 5.3 节实测步骤。

八、参考链接

1. 官方配置文档（Administration、Configuration）：https://zeppelin.apache.org/docs/0.12.1/administration/configuration.html
2. Shiro 认证官方文档：https://zeppelin.apache.org/docs/0.12.1/security/shiroauthentication.html
3. 笔记本存储官方文档：https://zeppelin.apache.org/docs/0.12.1/storage/storage.html
4. REST API 官方文档：https://zeppelin.apache.org/docs/0.12.1/usage/rest_api/zeppelin_api.html
5. Apache Zeppelin 官方下载页：https://zeppelin.apache.org/download.html