Zeppelin 笔记本重启就丢:三个环境变量把 .zpln 存进 RustFS 桶

做数据分析的人多半被笔记本丢过一次。容器重建、Pod 漂移、实例扩容,Apache Zeppelin 的默认笔记本仓库落在本地盘上,机器一换,写了一半的分析就没了。RustFS 官方集成目录里有一篇对应的指南,用它的 S3 笔记本仓库把每个笔记本写成一个 .zpln 对象存进桶,重启、换实例都还在。这篇对着官方那篇指南把最小链路走一遍,再讲清楚它给的是本地演示,你上生产还差哪几步。

官方给的接法和它没替你做的部分

官方那篇 Zeppelin 指南用 apache/zeppelin:0.12.0 配 rustfs/rustfs-x86-musl:v2.3.1 验证过:起一个容器、设几个 ZEPPELIN_* 变量、建一个笔记本、用 rc ls 看桶里多了个 .zpln 文件,重启容器再看笔记本还在。整条链路是通的,照着敲就能复现。它解决的是"笔记本能不能落到对象存储"这一个问题。

它没解决的是生产里另外三件事。凭证,指南里用的是占位符,真实环境得给 Zeppelin 单独开一把访问密钥;寻址,自定义端点必须走路径风格,否则 Zeppelin 会把桶名拼成主机名去解析;隔离,官方明确写了这套是本地集成测试、不适用于生产,单实例、没做租户隔离。下面的主体就是把官方那段接进你已有的桶和凭证体系,再把这三个缺口补上。

笔记本是怎么变成桶里一个对象的

Zeppelin 的笔记本仓库是可插拔的。默认的本地文件系统仓库换成 S3NotebookRepo(org.apache.zeppelin.notebook.repo.S3NotebookRepo)之后,每个笔记本都按"名字+ID"序列化成一个 .zpln 的 JSON 文件,写进桶的 user/notebook/ 前缀下面。这个前缀不用事先建,S3 仓库在启动时按需创建。

因为笔记本的真相来源在桶里,容器就没必要保存状态。Zeppelin 重启会重新从桶里加载笔记本列表,多个实例指同一个桶就能共享同一批笔记本。把状态外置最直接的收益就在这里:笔记本不再跟某一台机器的磁盘绑死。

Zeppelin 有个省事的设计,ZEPPELIN_* 开头的环境变量会被当成配置属性读进去,所以不用改 zeppelin-site.xml。把下面这几个变量塞进 docker run 就够了:

bash 复制代码
docker run -d --name zeppelin --network oo-rustfs_default \
  -p 8080:8080 \
  -e AWS_ACCESS_KEY_ID \
  -e AWS_SECRET_ACCESS_KEY \
  -e ZEPPELIN_NOTEBOOK_STORAGE=org.apache.zeppelin.notebook.repo.S3NotebookRepo \
  -e ZEPPELIN_NOTEBOOK_S3_BUCKET=my-bucket \
  -e ZEPPELIN_NOTEBOOK_S3_ENDPOINT=http://rustfs:9000 \
  -e ZEPPELIN_NOTEBOOK_S3_PATH_STYLE_ACCESS=true \
  apache/zeppelin:0.12.0

凭证走 AWS_ACCESS_KEY_ID 和 AWS_SECRET_ACCESS_KEY 两个标准变量,端点用裸的 host:port,路径风格那个开关保持 true。

路径风格值得多说一句。S3 请求有两种寻址方式:虚拟主机样式把桶名写进主机名(bucket.s3.example.com),路径样式把桶名放进 URL 第一段(example.com/bucket)。RustFS 默认按路径样式工作,不需要配通配 DNS。Zeppelin 这类工具如果照 AWS 的默认行为走虚拟主机样式,就会去解析 my-bucket.rustfs 这种根本不存在的域名。这就是后面那个报错的由来。ZEPPELIN_NOTEBOOK_S3_PATH_STYLE_ACCESS=true 的作用,就是把工具强制拉回路径样式。

把建、存、重启走一遍

先准备凭证文件,把两个占位符换成真值:

bash 复制代码
cat > .env <<'EOF'
AWS_ACCESS_KEY_ID=<your-access-key>
AWS_SECRET_ACCESS_KEY=<your-secret-key>
EOF

桶用现成的 my-bucket。容器起来后,等 8080 端口的界面就绪,可以在 UI 里手动建笔记本,也可以走 REST API:

bash 复制代码
NOTE=$(curl -s -X POST "http://localhost:8080/api/notebook" \
  -H "Content-Type: application/json" \
  -d '{"name": "rustfs-demo"}' | python3 -c "import json,sys; print(json.load(sys.stdin)['body'])")
echo "note id: $NOTE"

回一个 ID 就说明笔记本建好了。这时候数一下桶里有没有东西:

bash 复制代码
rc ls rustfs/my-bucket/user/notebook/ -r

会看到类似 user/notebook/rustfs-demo_2N4PY7UY5.zpln 的文件,文件名就是"笔记本名+ID"。再重启容器验证一次:

bash 复制代码
docker restart zeppelin
curl -s "http://localhost:8080/api/notebook" | head -c 200

刚才那个 ID 又出现在列表里,说明笔记本确实是从桶里读回来的,不是残留在容器盘上。要清掉演示数据就把整个前缀删了:

bash 复制代码
rc rm rustfs/my-bucket/user/notebook/ --recursive --force

这里有个边界要讲清楚:删的是桶里的对象前缀,和 Zeppelin 界面里"删除笔记本"不是一回事。走了 REST 或界面的删除,Zeppelin 会在桶里删掉对应的 .zpln;直接 rc rm 前缀则是绕过 Zeppelin 把对象清掉,正在运行的实例如果还缓存着旧列表,可能短暂看到已经不在桶里的笔记本,重启后才会一致。所以清理演示数据可以随手 rc rm,生产里删笔记本还是走 Zeppelin 自己的接口,让元数据和数据一起动。

两个高频报错

桶里始终没有笔记本,先查三个 ZEPPELIN_NOTEBOOK_S3_* 变量是不是都设了,再查凭证有没有真的进容器。有个容易忽略的点:S3 笔记本仓库是在启动时初始化的,改完变量必须重建容器,光 restart 不会重新读配置。

另一个是 UnknownHostException: my-bucket.rustfs。这是路径风格没生效,Zeppelin 把桶当成主机名去解析了。把 ZEPPELIN_NOTEBOOK_S3_PATH_STYLE_ACCESS=true 原样留着,别改成 false。自定义端点走路径风格时不需要额外的虚拟主机配置,桶名落在请求路径的第一段。

上生产前补的三件事

凭证排第一。别把根密钥塞进 .env 给 Zeppelin 用,去控制台给这个服务单独开一把访问密钥,只授权它读写笔记本那一个桶,过期时间也设上,官方的访问密钥管理页写了创建和撤销步骤。

镜像版本排第二。官方指南里 RustFS 用的是 rustfs-x86-musl:v2.3.1,那是验证时的版本;当前稳定版是 RustFS 1.0.6(2026-11-15 发布),生产把镜像钉到对应 tag,Zeppelin 镜像也固定到你要的版本,别用 latest。

寻址排第三。Zeppelin 只用到分桶列举、对象读写这些基础 S3 操作,落在兼容面的常用部分。但自定义端点加路径风格这套配置对版本敏感,换 RustFS 版本时用官方的 S3 兼容性说明对一遍实际调用的那几个操作。打算按用户分笔记本前缀,可以照 Apache Zeppelin 的存储文档把 user/notebook/ 拆成按用户隔离的路径,再把每个用户的桶权限收窄到各自前缀。

回头看这套接法:把 ZEPPELIN_NOTEBOOK_STORAGE 切到 S3NotebookRepo,端点指到 RustFS、路径风格打开、凭证单独建一把,笔记本就落在 user/notebook/ 前缀下,容器重建不丢、多实例能共享。剩下的就是把演示镜像钉到稳定版、把权限收到单个桶,这套就能从跑通走到能用。

相关推荐
guuguo44 分钟前
【做个开源软件】Mac 上 node 进程莫名吃掉 6G 内存?给 AI / MCP 做了个深度归因和安全回收工具
人工智能·开源·github
好用斋1 小时前
内网测速 LibreSpeed:网页版 Docker 测速服务
运维·docker·容器
江华森2 小时前
从零开始:智能运维概念与Linux环境准备完全指南
linux·运维
一切皆有可能!!2 小时前
【SoduWork测评】本机跑源码,找到并修了7个Bug
windows·开源·bug·ai编程·soduwork
阿里云云原生3 小时前
AgentScope Durable:让企业 Agent 持续、可靠地运行
云原生
橙橙子2303 小时前
Linux----libevent
linux·运维·服务器
如夏倾城5 小时前
五大远程桌面协议:RDP、SSH、VNC/RFB、Citrix ICA/HDX 与 VMware Blast Extreme
运维·windows·网络协议·安全·自动化·ssh·远程工作
无足鸟ICT5 小时前
【RHCA+】numactl命令(管理numa)
linux·运维·服务器
Eyfcom5 小时前
〖物流云原生实战 05〗Service Mesh 在快递系统微服务治理中的应用:从“代码侵入”到“基础设施下沉”
微服务·云原生·service_mesh·快递系统·物流云原生实战