前言
Walrus 是构建在 Sui 之上的去中心化 Blob 存储网络。它适合保存需要可验证、可编程、长期可用的数据，例如前端站点资源、链下大文件、AI 数据集、审计日志、Agent 记忆和链上应用的外部内容。
本书按开发者的真实学习路径组织：先用 CLI 完成上传和下载，再发布 Walrus Sites，然后进入 HTTP API、TypeScript SDK、Move 集成和系统原理。每一章都优先给出可以运行的命令或代码，再解释这些命令背后的对象模型、费用、安全边界和生产注意事项。
版本策略
本书所有安装命令默认使用最新稳定版本：
- Walrus CLI 和节点组件：优先使用
suiup install walrus，或从官方mainnet/testnet分支安装。 - Walrus Sites：优先使用官方文档推荐的最新
site-builder安装方式。 - npm SDK：示例项目固定到写作时通过 npm registry 查询到的最新稳定版本，并在附录 A 中记录查询时间和命令。
- 实验性或预发布版本只在明确标注的章节出现，不作为主线教程默认选择。
读者准备
你需要熟悉基本命令行、JavaScript/TypeScript 和 HTTP。读到 Move 集成章节时，最好已经知道 Sui 对象、交易和 package 的基本概念；如果还没有，也可以先按书中的最小示例跑通，再回头补 Sui Move。
如何阅读本书
前两部分适合顺序阅读。CLI 章节会建立全书最重要的直觉：一次写入会产生 blob_id 和 Sui object ID，读取路径、生命周期管理和费用都围绕这两个标识展开。
第三部分可以作为前端工程师的主线：先发布一个最小站点，再处理路由、headers、SuiNS、portal 和 CI/CD。第四部分进入应用开发，适合后端、全栈和工具开发者。第五到第七部分解释 Move 集成、协议原理和生产运维，建议在已经跑通过上传、下载和站点发布后阅读。
第八部分是综合项目。它不是演示性质的代码片段，而是把本书前面分散出现的能力组合成可扩展的应用骨架。读者可以按项目逐步实现，也可以把其中的模块拆到自己的产品中。
代码约定
书中命令默认使用 Testnet，除非章节明确说明 Mainnet。所有对象 ID、私钥、RPC、域名和 relayer 地址都以占位符展示，复制前必须替换为自己的环境值。示例代码保存在仓库 examples/ 目录，并由 GitHub Actions 做构建和类型检查。
本书项目
全书会完成四个综合项目：
- 去中心化文件网盘：上传、下载、状态查询、分享和生命周期管理。
- Walrus Sites 内容站：静态内容发布、更新、路由、SuiNS 和 CI/CD。
- MemWal AI Agent 记忆库：用加密记忆、语义检索和 Walrus 存储构建可恢复的 Agent 记忆。
- Sui Stack Messaging 加密消息应用：用 Sui Groups、Seal、relayer 和 Walrus 构建可恢复的端到端加密群聊。
注意：Walrus 上的 Blob 默认公开可读。任何敏感数据都必须先加密，再上传到 Walrus。本书在涉及隐私和 AI 记忆的章节会使用 Seal/MemWal 的安全模型作为默认实践。