第 4 章 上传第一个 Blob

学习目标

• 使用 walrus store 上传单文件和多文件。
• 理解 --epochs、--deletable、--permanent、--force。
• 把上传输出保存为后续命令可复用的变量。

前置条件

• 已完成 Testnet 配置。
• 当前目录为 ~/walrus-book-lab。
• 余额中有测试 SUI 和测试 WAL。

创建样例文件

cd ~/walrus-book-lab
mkdir -p files downloads

printf 'hello walrus\n' > files/hello.txt
printf '{"chapter":4,"topic":"store"}\n' > files/chapter-04.json

上传单个 Blob

walrus store files/hello.txt --epochs 2 --context testnet

典型输出：

Blob ID: <BLOB_ID>
Sui object ID: <BLOB_OBJECT_ID>

把两个值写入 shell 变量，后面替换为你的真实输出：

export BLOB_ID='<BLOB_ID>'
export BLOB_OBJECT_ID='<BLOB_OBJECT_ID>'

上传多个文件

walrus store files/hello.txt files/chapter-04.json --epochs 2 --context testnet

也可以用 shell glob：

walrus store files/*.json --epochs 2 --context testnet

glob 由 shell 展开。目录里没有匹配文件时，不同 shell 的行为不同，生产脚本应先 find 检查文件列表。

生命周期参数

最常用的是相对 Epoch：

walrus store files/hello.txt --epochs 2 --context testnet

存到最大可选 Epoch：

walrus store files/hello.txt --epochs max --context testnet

指定最早过期时间：

walrus store files/hello.txt \
  --earliest-expiry-time '2026-06-01T00:00:00Z' \
  --context testnet

指定结束 Epoch：

walrus store files/hello.txt --end-epoch <END_EPOCH> --context testnet

Blob 在 end epoch 开始时过期；如果在 Epoch 切换前用 --epochs 1，可能很快就过期。

Deletable 与 Permanent

默认新 Blob 是 deletable。你可以显式写出：

walrus store files/hello.txt --epochs 2 --deletable --context testnet

永久到期前不可由上传者提前删除：

walrus store files/hello.txt --epochs 2 --permanent --context testnet

如果你后续要练习 delete，用 --deletable。如果你后续要练习 share，共享 Blob 只能基于 permanent Blob，上传时用 --permanent 或在 store 时直接 --share。

强制创建新对象

同内容重复上传时，Walrus 可能复用已有认证结果。需要新 Sui 对象时使用：

walrus store files/hello.txt --epochs 2 --force --context testnet

这会创建新的 Sui object ID，仍然可能得到相同 Blob ID。

输出解读

• Blob ID：内容地址，用于 read 和 blob-status --blob-id。
• Sui object ID：链上管理对象，用于 extend、share、attributes、burn-blobs。
• 如果输出提示已经存在或复用存储资源，说明客户端做了自动优化，不一定重新上传全部 sliver。

常见坑

• 忘记 --epochs：当前 CLI 要求明确生命周期。
• 上传敏感文件：Walrus Blob 公开可发现，敏感数据必须先加密。
• 只保存 Blob ID：后续无法方便地 extend 或设置属性。
• 以为 --permanent 是永久保存：它表示到期前不可提前删除，不表示无限期保存。

下一步

下一章读取 Blob、下载到文件，并查询 Blob 可用状态。