第 7 章 Quilt 与批量小文件

学习目标

• 用 store-quilt 批量上传小文件。
• 用 read-quilt 按 identifier、tag、QuiltPatchId 读取。
• 理解 Quilt 与普通 Blob 生命周期管理的差异。

前置条件

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

准备小文件集合

cd ~/walrus-book-lab
mkdir -p quilt-src/docs quilt-downloads

printf '# Walrus Notes\n' > quilt-src/docs/notes.md
printf '{"kind":"profile","name":"alice"}\n' > quilt-src/profile.json
printf 'id,value\n1,42\n' > quilt-src/data.csv

按路径上传 Quilt

递归上传目录和文件：

walrus store-quilt \
  --epochs 2 \
  --paths quilt-src \
  --context testnet

输出里保存 Quilt ID 和 Sui object ID：

export QUILT_ID='<QUILT_ID>'
export QUILT_OBJECT_ID='<QUILT_OBJECT_ID>'

Quilt 内每个文件用 identifier 检索。通过 --paths 上传时，文件名会作为默认 identifier；同一个 Quilt 内 identifier 必须唯一，否则上传失败。

用 JSON 指定 identifier 和 tags

需要自定义 identifier 或 tag 时，用 --blobs：

walrus store-quilt \
  --blobs '{"path":"quilt-src/docs/notes.md","identifier":"notes","tags":{"type":"markdown","chapter":"7"}}' \
          '{"path":"quilt-src/profile.json","identifier":"profile","tags":{"type":"json","chapter":"7"}}' \
          '{"path":"quilt-src/data.csv","identifier":"dataset","tags":{"type":"csv","chapter":"7"}}' \
  --epochs 2 \
  --context testnet

JSON 建议外层用单引号，内部字段用双引号，避免 shell 转义混乱。

列出 Quilt Patch

walrus list-patches-in-quilt "$QUILT_ID" --context testnet

输出会列出每个 patch 的 identifier 和 QuiltPatchId。保存需要精确读取的 patch：

export QUILT_PATCH_ID='<QUILT_PATCH_ID>'

按 identifier 读取

walrus read-quilt \
  --quilt-id "$QUILT_ID" \
  --identifiers notes profile \
  --out quilt-downloads \
  --context testnet

检查：

find quilt-downloads -maxdepth 1 -type f -print

按 tag 读取

读取 tag 为 type=json 的 patch：

walrus read-quilt \
  --quilt-id "$QUILT_ID" \
  --tag type json \
  --out quilt-downloads \
  --context testnet

读取 tag 为 chapter=7 的 patch：

walrus read-quilt \
  --quilt-id "$QUILT_ID" \
  --tag chapter 7 \
  --out quilt-downloads \
  --context testnet

按 QuiltPatchId 读取

walrus read-quilt \
  --quilt-patch-ids "$QUILT_PATCH_ID" \
  --out quilt-downloads \
  --context testnet

多个 patch ID 可以连续传入：

walrus read-quilt \
  --quilt-patch-ids <PATCH_ID_1> <PATCH_ID_2> \
  --out quilt-downloads \
  --context testnet

管理 Quilt 生命周期

Quilt 是一个整体存储单元。普通 Blob 的 delete、extend、share 不能作用到 Quilt 内的单个小文件；要对整个 Quilt 对象操作。

延长整个 Quilt：

walrus extend \
  --blob-obj-id "$QUILT_OBJECT_ID" \
  --epochs-extended 3 \
  --context testnet

删除整个 deletable Quilt：

walrus delete --object-id "$QUILT_OBJECT_ID" --context testnet

输出解读

• QUILT_ID 用来 list-patches-in-quilt 和 read-quilt --quilt-id。
• QuiltPatchId 用来只读 Quilt 中一个或多个小文件。
• QUILT_OBJECT_ID 是链上对象 ID，用于 extend、delete、share、attributes 等管理操作。

常见坑

• identifier 重复：--paths 默认用文件名，两个目录下都有 index.html 时会冲突；用 --blobs 自定义 identifier。
• 把 QuiltPatchId 当 Blob ID：Quilt 内文件用 read-quilt，不是 walrus read。
• 想单独删除 Quilt 内一个文件：不能对单个 patch 做普通 Blob 生命周期操作，需要重新打 Quilt。
• 大文件批量不一定适合 Quilt：Quilt 主要优化大量小文件的开销和索引。

下一步

你已经掌握 CLI 主线。后续可以进入 Walrus Sites，把静态站点文件作为 Quilt 上传并由 Sui 链上索引发布。