Apache Zeppelin 0.12.1 Docker Compose 部署指南

一、环境信息

二、镜像选型说明

Apache Zeppelin 官方在 Docker Hub 维护 apache/zeppelin 镜像，tag 与发行版本一一对应，本文选用与官方最新稳定版一致的 apache/zeppelin:0.12.1（官方下载页给出的标准启动命令即为 docker run -p 8080:8080 --rm --name zeppelin apache/zeppelin:0.12.1）。

镜像关键特性（实测确认）：

生产环境应固定具体版本 tag，不建议使用 latest，保证升级可回滚。

三、前置条件

1. 宿主机已安装 Docker 20.10 以上版本与 docker compose 插件，验证方式（实测回显）：

docker compose version

Docker Compose version v5.5.1

2. 宿主机可访问 Docker Hub（拉取 apache/zeppelin:0.12.1，约 1GB 下载量）。
3. 8080 端口未被占用。
4. 磁盘剩余空间不低于 6GB（镜像 2.74GB 加笔记本与日志空间）。

四、部署步骤

4.1 创建部署目录

mkdir -p /root/zeppelin-compose/notebook /root/zeppelin-compose/logs

4.2 拉取官方镜像

docker pull apache/zeppelin:0.12.1

实测回显（节选）：

Digest: sha256:ebb76b9b98f1b5457cd10c118fc6624269918a3602711a08d9f237673c0c0abb
Status: Downloaded newer image for apache/zeppelin:0.12.1

4.3 修复挂载目录属主（关键步骤）

官方镜像以 uid=1000 运行，挂载目录若属主为 root 会导致启动失败并陷入重启循环（实测报错为 java.io.IOException: Creating directories for /opt/zeppelin/notebook/.git failed）。必须先将目录属主改为 1000：

chown -R 1000:0 /root/zeppelin-compose/notebook /root/zeppelin-compose/logs

4.4 编写 docker-compose.yml

在 /root/zeppelin-compose 下创建 docker-compose.yml（实测通过的完整内容）：

services:
  zeppelin:
    image: apache/zeppelin:0.12.1
    container_name: zeppelin
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      ZEPPELIN_ADDR: "0.0.0.0"
      ZEPPELIN_MEM: "-Xms256m -Xmx512m -XX:MaxMetaspaceSize=256m"
      ZEPPELIN_LOG_DIR: /logs
      ZEPPELIN_NOTEBOOK_DIR: /notebook
    volumes:
      - ./notebook:/notebook
      - ./logs:/logs

两个路径变量必须显式设置：只挂载 /notebook 与 /logs 而不设置 ZEPPELIN_NOTEBOOK_DIR 与 ZEPPELIN_LOG_DIR 时，进程仍按镜像内默认路径读写 /opt/zeppelin/notebook 与 /opt/zeppelin/logs，宿主目录恒为空，且空挂载会把镜像内置的示例笔记本覆盖掉。

4.5 启动服务

cd /root/zeppelin-compose && docker compose up -d

实测回显：

 Container zeppelin Created
 Container zeppelin Started

4.6 验证服务

等待约 30 秒初始化后验证状态与端口（实测回显）：

docker compose ps

NAME       IMAGE                    SERVICE    STATUS         PORTS
zeppelin   apache/zeppelin:0.12.1   zeppelin   Up 40 seconds   0.0.0.0:8080->8080/tcp, [::]:8080->8080/tcp

wget -q -S -O /dev/null http://127.0.0.1:8080/ 2>&1 | head -1

  HTTP/1.1 200 OK

浏览器访问 http://宿主机IP:8080 打开 WebUI。查看进程确认 JVM 内存参数生效（实测回显）：

docker compose top

SERVICE   #   PID   USER  TIME  COMMAND
zeppelin  1   2506  1000  0:00  /usr/bin/tini -- bin/zeppelin.sh
zeppelin  1   2553  1000  0:09  /usr/lib/jvm/java-11-openjdk/bin/java -Dfile.encoding=UTF-8 -Xms256m -Xmx512m -XX:MaxMetaspaceSize=256m -Dlog4j.configuration=file:///opt/zeppelin/conf/log4j.properties -Dzeppelin.log.file=/logs/zeppelin-zeppelin-0483bcd89de9.log

java 进程参数中可见 -Xms256m -Xmx512m，堆限制已生效；日志文件路径指向挂载的 /logs。

4.7 验证笔记本持久化

Zeppelin 启动后会在笔记本目录初始化 Git 仓库（实测容器内 /notebook/.git 已生成，宿主目录同步可见）：

ls -a /root/zeppelin-compose/notebook/ | head -3

.git

在 WebUI 创建任意笔记本后，宿主 notebook 目录会同步生成对应的 zpln 文件，销毁容器重建后笔记本不丢失。

五、数据持久化说明

实测结论：0.12.1 官方镜像的日志以 stdout 输出为主（docker logs 可见全部日志，含启动完成的 Done, zeppelin server started 行），logs 目录能否生成文件取决于容器内 log4j2 配置，日志排障优先使用 docker compose logs。笔记本持久化则完全依赖挂载与环境变量，二者缺一不可。

六、常用环境变量表

七、常用配置参数说明

需要修改 zeppelin-site.xml 类参数（如关闭匿名访问 zeppelin.anonymous.allowed、调整 zeppelin.websocket.max.text.message.size）时，可在宿主准备一份完整配置文件挂载到容器 conf 目录覆盖。最简做法：从镜像中取出模板修改后挂载（见第八节）。认证场景可在挂载的 conf 目录中同时放入 shiro.ini（示例管理员账号 admin、密码 q1w2e3r4），并在 site 配置中把 zeppelin.anonymous.allowed 设为 false。

八、配置文件持久化

将镜像内配置模板导出到宿主并持久化（实测命令）：

mkdir -p /root/zeppelin-compose/conf

docker run --rm --entrypoint cat apache/zeppelin:0.12.1 /opt/zeppelin/conf/zeppelin-site.xml.template > /root/zeppelin-compose/conf/zeppelin-site.xml

编辑宿主 conf/zeppelin-site.xml（如修改 zeppelin.server.port 或追加 zeppelin.anonymous.allowed=false），再在 docker-compose.yml 的 volumes 中增加一行并重启：

    volumes:
      - ./notebook:/notebook
      - ./logs:/logs
      - ./conf:/opt/zeppelin/conf

docker compose up -d

注意挂载整个 conf 目录时会覆盖镜像内置全部配置文件，shiro.ini、log4j2.properties 等均需一并放入宿主 conf 目录。

九、等价 docker run 运行方式

不使用 Compose 时，等价的单命令运行方式（实测通过）：

mkdir -p /data/zeppelin/notebook /data/zeppelin/logs

chown -R 1000:0 /data/zeppelin/notebook /data/zeppelin/logs

docker run -d --name zeppelin -p 8080:8080 -u 1000 \
  -v /data/zeppelin/notebook:/notebook \
  -v /data/zeppelin/logs:/logs \
  -e ZEPPELIN_ADDR=0.0.0.0 \
  -e ZEPPELIN_MEM="-Xms256m -Xmx512m" \
  -e ZEPPELIN_NOTEBOOK_DIR=/notebook \
  -e ZEPPELIN_LOG_DIR=/logs \
  --restart unless-stopped apache/zeppelin:0.12.1

实测验证（等待约 35 秒后）：

wget -q -S -O /dev/null http://127.0.0.1:8080/ 2>&1 | head -1

  HTTP/1.1 200 OK

-u 1000 与目录属主 chown 必须成对出现：实测未修复属主时容器进入 Restarting (1) 循环，修复后正常。

十、常用运维命令

以下命令均在 docker-compose.yml 所在目录执行：

docker compose ps

docker compose logs -f --tail 100

docker compose restart

docker compose stop

docker compose start

docker compose down

实测回示例样（stop 与 logs）：

 Container zeppelin Stopped

zeppelin  |  INFO [2026-10-12 06:43:03,173] ({Thread-2} ZeppelinServer.java[shutdown]:365) - Bye

版本升级流程：备份 notebook 目录后，修改 docker-compose.yml 中的 image tag 并执行 docker compose pull 与 docker compose up -d。

十一、常见问题

Q1：容器不断重启，docker logs 报 Creating directories for /opt/zeppelin/notebook/.git failed。 挂载目录属主问题。官方镜像以 uid=1000 运行，对 root 属主的挂载目录没有写权限。执行 chown -R 1000:0 ./notebook ./logs 后 docker compose up -d 重新创建容器。

Q2：挂载了 notebook 与 logs 目录，但目录始终为空。 未设置 ZEPPELIN_NOTEBOOK_DIR 与 ZEPPELIN_LOG_DIR 环境变量，进程仍使用镜像内 /opt/zeppelin 下的默认路径。按第四节 compose 文件补上两个环境变量并重建容器。

Q3：docker compose up -d 后立即访问 8080 无响应。 Zeppelin 初始化需要 20 至 40 秒（宿主性能越低越久），以 docker logs 中出现 Done, zeppelin server started 为就绪标志再验证。

Q4：容器内 JVM 内存限制如何确认生效。 执行 docker compose top 查看 java 进程参数中的 -Xms 与 -Xmx；镜像内亦提供 JDK 工具，可执行 docker exec zeppelin jcmd 1 VM.flags 读取运行时 MaxHeapSize（1 号 JVM 进程即 ZeppelinServer）。

Q5：重启宿主机后容器没有自动拉起。 确认 compose 文件中配置了 restart: unless-stopped，且容器是 docker compose up -d 创建；曾被 docker compose stop 手动停止的容器不会被自动拉起，需 docker compose start。

十二、参考链接

1. Apache Zeppelin 官方下载页（含官方 docker run 命令）：https://zeppelin.apache.org/download.html
2. Docker Hub 官方镜像仓库：https://hub.docker.com/r/apache/zeppelin
3. 官方安装文档：https://zeppelin.apache.org/docs/0.12.1/quickstart/install.html
4. Docker Compose 官方文档：https://docs.docker.com/compose/
5. Apache Zeppelin 配置文档：https://zeppelin.apache.org/docs/0.12.1/administration/configuration.html