Apache Zeppelin 0.12.1 常用 CLI 命令与工具详解

一、环境信息

项目	实测环境
操作系统	Ubuntu 22.04.5 LTS 与 CentOS Linux 8 双环境实测
Apache Zeppelin 版本	0.12.1（bin-netinst 包）
JDK 版本	OpenJDK 11
安装目录	/opt/zeppelin
工具目录	/opt/zeppelin/bin
服务端口	8080
堆内存	主进程 256MB 至 512MB

二、工具概览

Zeppelin 自带的命令行工具集中在 bin 目录，先列出全部工具（实测回显）：

ls /opt/zeppelin/bin/

common.cmd  common.sh  functions.cmd  functions.sh  install-interpreter.sh  interpreter.cmd
interpreter.sh  stop-interpreter.sh  zeppelin-daemon.sh  zeppelin-systemd-service.sh
zeppelin.cmd  zeppelin.sh

工具	用途	日常使用频率
bin/zeppelin-daemon.sh	后台守护方式启动、停止、重启、查看状态	最高
bin/zeppelin.sh	前台方式启动（调试用）	中
bin/zeppelin-systemd-service.sh	注册或注销 systemd 开机自启服务	装机时使用
bin/install-interpreter.sh	补装 netinst 包未内置的解释器	按需
bin/interpreter.sh	以独立进程方式调试单个解释器	排障时使用
jps 与 jcmd（JDK 自带）	验证 JVM 进程与运行时内存参数	验证时使用

三、前置条件

已完成 Zeppelin 部署且 conf/zeppelin-env.sh 已按配置篇完成堆内存等基础配置。
执行 zeppelin-daemon.sh 时工作目录或脚本路径不影响使用，但配置目录默认按安装位置解析。
systemctl 相关命令需要 root 权限。
JDK 的 bin 目录需在 PATH 中（jps、jcmd 可直接调用），可用以下命令确认：

jps -V

实测回显：

jps 11.0.32.1

四、工具详解

4.1 zeppelin-daemon.sh：守护进程管理

这是使用频率最高的工具，支持 start、status、restart、stop 四个动作。

启动服务（实测回显）：

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

Please specify HADOOP_CONF_DIR if USE_HADOOP is true
Zeppelin start                                             [  OK  ]

第一行提示为未接入 Hadoop 时的固定警告，可忽略。启动后 Jetty 初始化需要 10 至 30 秒。

查看运行状态，运行中（实测回显）：

bin/zeppelin-daemon.sh status

Please specify HADOOP_CONF_DIR if USE_HADOOP is true
Zeppelin is running                                        [  OK  ]

已停止时（实测回显）：

Please specify HADOOP_CONF_DIR if USE_HADOOP is true
Zeppelin is not running                                    [FAILED]

重启服务（实测回显）：

bin/zeppelin-daemon.sh restart

Please specify HADOOP_CONF_DIR if USE_HADOOP is true
Zeppelin stop                                              [  OK  ]
Zeppelin start                                             [  OK  ]

停止服务（实测回显）：

bin/zeppelin-daemon.sh stop

Zeppelin stop                                              [  OK  ]

stop 之后必须用 status 或 curl 确认进程确实退出，再用 start 重启，避免旧进程残留导致端口占用。

4.2 zeppelin.sh：前台启动与调试

该脚本以前台方式运行 Zeppelin，日志直接输出到终端，Ctrl 加 C 即退出并结束服务，适合首次配置排障。查看用法（实测回显）：

bin/zeppelin.sh --help

Usage: bin/zeppelin.sh [--config <conf-dir>] [--run <noteId>]

参数说明：--config 可指定替代配置目录；--run 可在启动后直接打开指定笔记本 ID。生产环境应以 zeppelin-daemon.sh 或 systemd 方式常驻运行，前台模式仅用于临时调试。

4.3 zeppelin-systemd-service.sh：注册 systemd 服务

查看用法（实测回显）：

/opt/zeppelin/bin/zeppelin-systemd-service.sh

usage: zeppelin-systemd-service.sh {enable|disable}

  enable:    enable Zeppelin systemd service.
  disable:   disable Zeppelin systemd service.

注册服务（实测回显）：

/opt/zeppelin/bin/zeppelin-systemd-service.sh enable

To start Zeppelin using systemd, simply type:
# systemctl start zeppelin

To check the service health:
# systemctl status zeppelin

该命令生成 /etc/systemd/system/zeppelin.service，实测文件内容：

[Unit]
Description=Apache Zeppelin daemon
After=syslog.target network.target

[Service]
Type=oneshot
ExecStart=/opt/zeppelin/bin/zeppelin-daemon.sh start
ExecStop=/opt/zeppelin/bin/zeppelin-daemon.sh stop
RemainAfterExit=yes

[Install]
WantedBy=multi-user.target

启用开机自启（实测回显）：

systemctl enable zeppelin

Created symlink /etc/systemd/system/multi-user.target.wants/zeppelin.service → /etc/systemd/system/zeppelin.service.

启动服务并查看状态（实测回显）：

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)

注销服务使用 disable 动作：

/opt/zeppelin/bin/zeppelin-systemd-service.sh disable

4.4 install-interpreter.sh：补装解释器

netinst 安装包仅内置 markdown、shell、python、spark、flink 等常用解释器，其余解释器（如 jdbc、cassandra、elasticsearch 等）需要用该脚本在线补装。查看用法（实测回显）：

/opt/zeppelin/bin/install-interpreter.sh --help

Options
  -l, --list                   List available interpreters
  -a, --all                    Install all available interpreters
  -n, --name       [NAMES]     Install interpreters (comma separated list)e.g. md,shell,jdbc,python,angular
  -t, --artifact   [ARTIFACTS] (Optional with -n) custom artifact names. (comma separated list correspond to --name) e.g. customGroup:customArtifact:customVersion
  --proxy-url      [url]       (Optional) proxy url. http(s)://host:port
  --proxy-user      [user]      (Optional) proxy user
  --proxy-password [password]  (Optional) proxy password

列出可安装的解释器清单（实测回显）：

/opt/zeppelin/bin/install-interpreter.sh -l

alluxio                 Alluxio interpreter
angular                 HTML and AngularJS view rendering
bigquery                BigQuery interpreter
cassandra               Cassandra interpreter
elasticsearch           Elasticsearch interpreter
file                    HDFS file interpreter
flink                   Flink interpreter
groovy                  Groovy interpreter
hbase                   Hbase interpreter
java                    Java interpreter
jdbc                    Jdbc interpreter
livy                    Livy interpreter
md                      Markdown support
neo4j                   Neo4j interpreter
python                  Python interpreter
shell                   Shell command
sparql                  Sparql interpreter

安装指定解释器（示例安装 jdbc）：

/opt/zeppelin/bin/install-interpreter.sh -n jdbc

安装过程需要访问 Maven 仓库，受限网络环境可通过 --proxy-url 指定代理。安装完成后在 WebUI 的解释器页面刷新即可看到新解释器。

4.5 jps 与 jcmd：JVM 进程与内存验证

jps 列出 Zeppelin 相关 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 4937 VM.flags | tr ' ' '\n' | grep -E 'HeapSize'

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

268435456 字节即 256MB，536870912 字节即 512MB，与 conf/zeppelin-env.sh 中 ZEPPELIN_MEM 的设定一致。

五、注意事项

systemctl start zeppelin 返回成功时 Zeppelin 仍在后台初始化（服务为 oneshot 类型且 RemainAfterExit=yes），需等待 15 至 30 秒再验证 WebUI。
bin/zeppelin-daemon.sh status 对已停止服务回显 Zeppelin is not running 且退出码为 FAILED，这是正常的停止态回显，不是故障。
zeppelin.sh 前台模式退出即停止服务，不可作为生产运行方式；远程会话中断也会连带终止前台进程。
install-interpreter.sh -a 会安装全部解释器，下载体积大且多数用不上，建议按需用 -n 指定。
修改 conf/zeppelin-env.sh 后必须重启才能生效；每次重启后建议用 jps -v 确认新进程的 JVM 参数符合预期，避免配置覆盖类问题（堆参数必须写 ZEPPELIN_MEM，写 ZEPPELIN_JAVA_OPTS 会被默认 -Xmx1024m 覆盖）。
排查启动失败时优先看 /opt/zeppelin/logs/zeppelin-运行用户-主机名.log 与 logs/zeppelin-root-主机名.out 两个文件。

六、常见问题

Q1：zeppelin-daemon.sh start 回显 OK，但 curl 或浏览器仍打不开页面。 Jetty 初始化需要 10 至 30 秒；若持续失败，查看 logs 目录主日志中的 ERROR 行，常见原因是端口被占用或 ZEPPELIN_ADDR 配置的地址在本机不存在。

Q2：systemctl status zeppelin 显示 active (exited)，服务到底启动没有？ oneshot 类型服务的 status 只反映启动脚本是否执行成功。进一步执行 bin/zeppelin-daemon.sh status 确认 Zeppelin is running，并用 curl 验证 8080 端口返回 200。

Q3：执行 stop 后再 start，日志报端口被占用。 说明 stop 未彻底（可能有残留解释器进程）。用 jps 查看残留的 JVM 进程号，kill 对应进程后再 start；确属异常退出遗留时，检查 ZEPPELIN_PID_DIR 指向目录中的进程号文件是否过期。

Q4：install-interpreter.sh 下载解释器很慢或失败。 脚本支持 --proxy-url 参数走代理下载；也可以改用全量安装包 bin-all 重装，避免在线补装环节。

七、参考链接

官方安装文档（含启动脚本说明）：https://zeppelin.apache.org/docs/0.12.1/quickstart/install.html
解释器安装官方文档：https://zeppelin.apache.org/docs/0.12.1/usage/interpreter/installation.html
REST API 官方文档：https://zeppelin.apache.org/docs/0.12.1/usage/rest_api/zeppelin_api.html
Apache Zeppelin 官方下载页：https://zeppelin.apache.org/download.html