Ubuntu 22.04 安装 Apache Zeppelin 0.12.1 指南
本文实测 Ubuntu 22.04 部署 Apache Zeppelin 0.12.1 全流程，涵盖 OpenJDK 安装、下载校验、解压配置、堆内存限定、启动验证、Notebook 运行、systemd 注册与卸载，回显均来自真实环境。
Ubuntu 22.04 安装 Apache Zeppelin 0.12.1 指南
一、环境信息
| 项目 | 实测环境 |
|---|---|
| 操作系统 | Ubuntu 22.04.5 LTS（64 位） |
| 内核版本 | 5.15.x 系列 |
| 主机名 | zeppelin-node01（示例，实际以部署机为准） |
| 服务器地址 | 192.168.10.11（示例内网地址） |
| Apache Zeppelin 版本 | 0.12.1（bin-netinst 包，2026 年 6 月 12 日发布） |
| JDK 版本 | OpenJDK 11.0.32（apt 源安装） |
| 安装目录 | /opt/zeppelin |
| 服务端口 | 8080 |
| 磁盘占用 | 安装包 516MB，解压后约 574MB |
二、前置条件
- 服务器可访问公网（需下载官方安装包与 apt 依赖），或已配置可访问 Apache 镜像站的代理。
- 磁盘剩余空间不低于 2GB（安装包 516MB 加解压后 574MB，另需日志与笔记本空间）。
- 内存不低于 2GB。本文按轻量场景将 Zeppelin 主进程堆内存限定为 256MB 至 512MB。
- 具备 root 权限或可使用 sudo 的账号。
- 8080 端口未被占用，可用以下命令确认：
ss -lntp | grep 8080
无输出即表示端口空闲。
三、版本选型说明
截至本文实测日期，Apache Zeppelin 官方最新稳定版为 0.12.1（2026 年 6 月 12 日发布）。官方提供两种二进制包：
| 包名 | 体积 | 说明 |
|---|---|---|
| zeppelin-0.12.1-bin-all.tgz | 约 706MB | 全量包，内置全部解释器 |
| zeppelin-0.12.1-bin-netinst.tgz | 约 515MB | 精简包，内置 markdown、shell、python、spark、flink 等常用解释器，其余解释器可用 install-interpreter.sh 按需补装 |
实测下载速度下，netinst 包下载体积更小且已覆盖 md、sh、python 等常用解释器，本文以 netinst 包为例。两个包均可在 downloads.apache.org 获取，历史版本在 archive.apache.org 查询。
四、部署步骤
4.1 安装 JDK
Zeppelin 0.12.1 官方要求 Java 8 或 Java 11，实测使用 apt 源安装 OpenJDK 11：
apt-get update
DEBIAN_FRONTEND=noninteractive apt-get install -y openjdk-11-jdk wget curl
安装完成后确认 Java 版本（实测回显）：
java -version
openjdk version "11.0.32.1" 2026-08-18
OpenJDK Runtime Environment (build 11.0.32.1+1-post-1ubuntu1-22.04-Ubuntu)
OpenJDK 64-Bit Server VM (build 11.0.32.1+1-post-1ubuntu1-22.04-Ubuntu, mixed mode, sharing)
同时确认 javac 已随包安装：
javac -version
javac 11.0.32.1
4.2 下载安装包并校验
创建下载目录并获取安装包（实测包体积 516MB，下载耗时随带宽而定）：
mkdir -p /tmp/zpdl && cd /tmp/zpdl
wget https://downloads.apache.org/zeppelin/zeppelin-0.12.1/zeppelin-0.12.1-bin-netinst.tgz
下载官方 sha512 校验文件并验证完整性（实测回显）：
wget https://downloads.apache.org/zeppelin/zeppelin-0.12.1/zeppelin-0.12.1-bin-netinst.tgz.sha512
sha512sum -c zeppelin-0.12.1-bin-netinst.tgz.sha512
zeppelin-0.12.1-bin-netinst.tgz: OK
回显 OK 表示安装包完整。若报 FAILED，需重新下载。
4.3 解压到安装目录
tar -xzf zeppelin-0.12.1-bin-netinst.tgz -C /opt/
mv /opt/zeppelin-0.12.1-bin-netinst /opt/zeppelin
确认目录内容与占用（实测回显）：
ls /opt/zeppelin/
LICENSE NOTICE README.md bin conf interpreter k8s lib licenses notebook plugins scripts
zeppelin-web-0.12.1.war zeppelin-web-angular-0.12.1.war
du -sh /opt/zeppelin
574M /opt/zeppelin
4.4 编写配置文件 conf/zeppelin-env.sh
从模板复制并编辑环境变量文件：
cp /opt/zeppelin/conf/zeppelin-env.sh.template /opt/zeppelin/conf/zeppelin-env.sh
在文件末尾追加以下内容（关键点：限定堆内存必须使用 ZEPPELIN_MEM 变量，原因见注意事项 6.2）：
cat >> /opt/zeppelin/conf/zeppelin-env.sh <<'ENVEOF'
# JVM 堆内存：256MB 至 512MB
export ZEPPELIN_MEM="-Xms256m -Xmx512m -XX:MaxMetaspaceSize=256m"
export ZEPPELIN_JAVA_OPTS="-Dfile.encoding=UTF-8"
# Web 服务监听地址与端口
export ZEPPELIN_ADDR="0.0.0.0"
export ZEPPELIN_PORT=8080
# 日志、进程号与笔记本目录
export ZEPPELIN_LOG_DIR="/opt/zeppelin/logs"
export ZEPPELIN_PID_DIR="/opt/zeppelin/run"
export ZEPPELIN_NOTEBOOK_DIR="/opt/zeppelin/notebook"
ENVEOF
创建日志与进程号目录：
mkdir -p /opt/zeppelin/logs /opt/zeppelin/run
4.5 启动服务
使用官方守护脚本后台启动（实测回显）：
cd /opt/zeppelin && bin/zeppelin-daemon.sh start
Please specify HADOOP_CONF_DIR if USE_HADOOP is true
Zeppelin start [ OK ]
第一行提示仅表示未接入 Hadoop 集群配置，未对接 Hadoop 时可忽略。启动后 Jetty 初始化需要 10 至 30 秒，随后才可正常访问。
4.6 验证服务
确认守护进程状态（实测回显）：
bin/zeppelin-daemon.sh status
Zeppelin is running [ OK ]
确认 WebUI 返回 HTTP 200（实测回显）：
curl -s -o /dev/null -w 'HTTP %{http_code}\n' http://127.0.0.1:8080/
HTTP 200
确认 JVM 进程堆参数生效（实测回显，日志文件名中的主机名因环境而异）：
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 读取运行时堆上限做二次验证（实测回显）：
jcmd $(jps | awk '/ZeppelinServer/{print $1}') VM.flags | tr ' ' '\n' | grep MaxHeapSize
-XX:MaxHeapSize=536870912
536870912 字节即 512MB，说明堆上限配置已实际生效。
浏览器访问 http://192.168.10.11:8080 即可打开 Zeppelin WebUI 首页。若系统启用了 ufw 防火墙，需先放行端口：
ufw allow 8080/tcp
4.7 创建 Notebook 运行代码验证
通过 REST API 创建一个使用 sh 解释器的笔记本（实测命令）：
curl -s -X POST http://127.0.0.1:8080/api/notebook \
-H "Content-Type: application/json" \
-d '{"name":"install-check","paragraphs":[{"title":"check","text":"%sh\necho \"Zeppelin on $(hostname) is OK\"\nuname -r\ndate"}]}'
实测回显（body 中的字符串即新笔记本 ID）：
{"status":"OK","message":"","body":"2N7GTCPK6"}
执行刚创建的段落（实测命令，段落 ID 通过 GET /api/notebook/2N7GTCPK6 查询 paragraphs 数组获得）：
curl -s -X POST http://127.0.0.1:8080/api/notebook/run/2N7GTCPK6/paragraph_1791786283783_1276185374 \
-H "Content-Type: application/json" -d '{}'
实测回显：
{"status":"OK","body":{"code":"SUCCESS","msg":[{"type":"TEXT","data":"Zeppelin on zeppelin-node01 is OK\n5.15.0-91-generic\n2026年 10月 12日 星期一 14:30:02 CST\n"}]}}
code 为 SUCCESS 且 data 中能看到命令输出，说明解释器调度与段落执行链路正常。也可以直接在 WebUI 中新建笔记本，输入 %sh 段落后点击运行按钮验证。
五、配置说明
5.1 环境变量一览
本指南在 conf/zeppelin-env.sh 中设置的变量含义如下：
| 变量 | 实测值 | 说明 |
|---|---|---|
| ZEPPELIN_MEM | -Xms256m -Xmx512m -XX:MaxMetaspaceSize=256m | 主进程 JVM 内存，限堆必须用它 |
| ZEPPELIN_JAVA_OPTS | -Dfile.encoding=UTF-8 | 追加的 JVM 参数，不要在其中写 -Xmx |
| ZEPPELIN_ADDR | 0.0.0.0 | 监听地址，默认 127.0.0.1 仅本机可访问 |
| ZEPPELIN_PORT | 8080 | Web 服务端口 |
| ZEPPELIN_LOG_DIR | /opt/zeppelin/logs | 服务日志目录 |
| ZEPPELIN_PID_DIR | /opt/zeppelin/run | 进程号文件目录 |
| ZEPPELIN_NOTEBOOK_DIR | /opt/zeppelin/notebook | 笔记本存储目录 |
5.2 站点配置文件
conf/zeppelin-site.xml.template 是全量站点参数模板，共 118 个配置项。将模板复制为 zeppelin-site.xml 后修改才生效：
cp /opt/zeppelin/conf/zeppelin-site.xml.template /opt/zeppelin/conf/zeppelin-site.xml
安装场景常用两处：zeppelin.server.addr（默认 127.0.0.1，外部访问需改 0.0.0.0）与 zeppelin.server.port（默认 8080）。详细参数见本专栏配置参数详解篇。
5.3 注册 systemd 服务（可选）
官方自带脚本可生成 systemd 服务文件：
/opt/zeppelin/bin/zeppelin-systemd-service.sh enable
实测生成 /etc/systemd/system/zeppelin.service，关键内容如下：
[Service]
Type=oneshot
ExecStart=/opt/zeppelin/bin/zeppelin-daemon.sh start
ExecStop=/opt/zeppelin/bin/zeppelin-daemon.sh stop
RemainAfterExit=yes
随后启用并启动：
systemctl enable zeppelin
systemctl start zeppelin
systemctl status zeppelin
实测回显：
● zeppelin.service - Apache Zeppelin daemon
Loaded: loaded (/etc/systemd/system/zeppelin.service; enabled; vendor preset: enabled)
Active: active (exited) since Mon 2026-10-12 06:22:58 UTC; 32s ago
Process: 5601 ExecStart=/opt/zeppelin/bin/zeppelin-daemon.sh start (code=exited, status=0/SUCCESS)
Main PID: 5601 (code=exited, status=0/SUCCESS)
该服务为 oneshot 类型，start 命令返回时 Zeppelin 仍在后台初始化，需等待 15 至 30 秒后 curl 才返回 200。
六、注意事项
- 安装包与校验文件务必成对下载，sha512sum -c 回显 FAILED 时必须重新下载，不可强行解压。
- 限定堆内存必须写在 ZEPPELIN_MEM 中。启动脚本 bin/common.sh 第 150 行按 ZEPPELIN_JAVA_OPTS、编码参数、ZEPPELIN_MEM 的顺序拼接 JVM 参数，而 ZEPPELIN_MEM 默认值为 -Xmx1024m，且位于拼接末尾。JVM 对重复出现的 -Xmx 取最后一次的值，因此把 -Xmx512m 写进 ZEPPELIN_JAVA_OPTS 会被默认值覆盖，实测 jps -v 中会出现两个 -Xmx 且运行时堆为 1024MB。
- 启动时输出 Please specify HADOOP_CONF_DIR if USE_HADOOP is true 属正常提示，仅当对接 Hadoop 时才需要设置该变量。
- ZEPPELIN_ADDR 默认 127.0.0.1，只能本机访问；对外提供服务需改为 0.0.0.0 或具体网卡地址，并同步放行防火墙端口。
- 0.12.1 默认允许匿名访问。生产环境建议参考配置篇启用 Shiro 认证（创建 conf/shiro.ini 并将 zeppelin.anonymous.allowed 设为 false），示例管理员账号 admin、密码 q1w2e3r4。
- zeppelin-env.sh 中同名变量重复赋值时后一行生效，编辑前先检查文件中是否已存在同名 export，避免出现 ZEPPELIN_NOTEBOOK_DIR 两行导致目录配置不生效的情况。
- 升级版本时只需备份 conf 与 notebook 目录，新版本解压后恢复这两个目录即可。
七、常见问题
Q1：启动回显 OK，但浏览器无法访问 8080 端口。 Jetty 初始化需要 10 至 30 秒，稍候重试；再检查 ZEPPELIN_ADDR 是否为 0.0.0.0、防火墙是否放行（ufw allow 8080/tcp），并在服务器本机执行 curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:8080/ 区分是服务未就绪还是网络不通。
Q2：jps -v 显示 -Xms256m -Xmx512m 之后又出现 -Xmx1024m，内存限制不生效。 这正是注意事项 2 描述的覆盖问题。检查 conf/zeppelin-env.sh，把堆参数从 ZEPPELIN_JAVA_OPTS 移到 ZEPPELIN_MEM，重启后用 jcmd 进程号 VM.flags 确认 MaxHeapSize 为 536870912（512MB）。
Q3：执行 bin/zeppelin-daemon.sh stop 后 status 显示 Zeppelin is not running [FAILED]。 这是停止后的正常回显，status 命令对已停止状态返回 FAILED 退出码，仅表示当前没有运行中的 Zeppelin 进程，不代表故障。
Q4：启动日志报 Failed to init NotebookRepo 或目录创建失败。 检查 ZEPPELIN_NOTEBOOK_DIR 指向目录的属主与读写权限，保证运行 Zeppelin 的用户（本文为 root）对其可写；同时确认磁盘未写满。
八、卸载方式
依次执行以下命令即可完整卸载（每条单独执行）：
cd /opt/zeppelin && bin/zeppelin-daemon.sh stop
若注册过 systemd 服务，先禁用再删除服务文件：
systemctl disable zeppelin
/opt/zeppelin/bin/zeppelin-systemd-service.sh disable
rm -f /etc/systemd/system/zeppelin.service
systemctl daemon-reload
删除安装目录与下载缓存：
rm -rf /opt/zeppelin
rm -rf /tmp/zpdl
如不再需要 JDK，可执行 apt-get remove --purge -y openjdk-11-jdk 并 apt-get autoremove 清理依赖。卸载前如需保留分析成果，先备份 /opt/zeppelin/notebook 目录。
九、参考链接
- Apache Zeppelin 官方下载页：https://zeppelin.apache.org/download.html
- 官方安装文档（Quickstart Install）：https://zeppelin.apache.org/docs/0.12.1/quickstart/install.html
- 官方发行说明 0.12.1：https://zeppelin.apache.org/releases/zeppelin-release-0.12.1.html
- Shiro 认证官方文档：https://zeppelin.apache.org/docs/0.12.1/security/shiroauthentication.html
- REST API 官方文档：https://zeppelin.apache.org/docs/0.12.1/usage/rest_api/zeppelin_api.html