
做数据分析的人多半被笔记本丢过一次。容器重建、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/ 前缀下,容器重建不丢、多实例能共享。剩下的就是把演示镜像钉到稳定版、把权限收到单个桶,这套就能从跑通走到能用。