walrus-sites

Walrus Sites — 去中心化网站托管

来源限制： 本技能中的所有信息均来自 Walrus Sites 文档 和 MystenLabs/walrus-sites 代码仓库。 扩展本技能时，只能从这些来源获取信息。

Walrus Sites 可将静态网站（HTML/CSS/JS）部署到 Walrus，并通过链上 Sui 对象跟踪网站的资源。门户服务器会解析网站子域名，从 Walrus 获取资源，并通过 HTTP 提供服务。最终得到的是完全去中心化的前端，无需中心化服务器、CDN 或 DNS。

常见故障：

1. Blob 过期。 发布网站时选择的 epoch 数量太少，blob 过期后网站会无声无息地失效。请始终使用较大的 --epochs 值或 --epochs max（最多 53 个 epoch——测试网约 53 天，主网约 2 年）。注意：--permanent 只会使 blob 不可删除；不会延长其存储时长，超出 --epochs 值。
2. 门户配置错误。 门户的 original_package_id 必须与 Walrus Sites 框架包（site::Site）匹配，而不是与应用的 Move 包匹配。
3. 测试网网站无法使用 wal.app。 公共 wal.app 门户仅提供主网服务。测试网需要自托管的本地门户。
4. SPA 路由。 单页应用需要 ws-resources.json 路由配置来支持客户端路由。否则，直接访问深层链接会返回 404。

---

子技能

publishing — 构建和部署网站

路径： publishing/SKILL.md 适用时机： 部署新网站、更新现有网站、选择 epoch 时长、配置 ws-resources.json，或排查 site-builder 错误时。 涵盖内容： site-builder deploy、site-builder publish、site-builder update、--epochs 标志、blob 过期、ws-resources.json 配置、SPA 路由、网站命名、用于调试的 site-builder sitemap、site-builder destroy。

portal — 为测试网运行本地门户

路径： portal/SKILL.md 适用时机： 用户需要查看测试网网站、设置本地门户、运行自己的门户作为去中心化备用方案、修复门户 404，或了解门户解析的工作原理时。 涵盖内容： 克隆门户、安装依赖项（Bun）、portal-config.yaml、original_package_id 易错点、启动服务器、URL 格式、端口冲突、主网与测试网的差异。

---

路由指南

任务	加载
将前端部署到 Walrus Sites	publishing/
更新已部署的网站	publishing/
修复 404 或网站过期问题	publishing/ + portal/
在本地查看测试网网站	portal/
设置本地门户	portal/
门户显示“Page not found”	portal/ + publishing/（检查 blob 是否过期）
配置 SPA 路由或自定义标头	publishing/
设置自定义域名（SuiNS）	下方的技能内容
使用 GitHub Actions 设置 CI/CD	下方的技能内容
查看网站包含哪些资源	publishing/（site-builder sitemap）
删除已部署的网站	publishing/
在 Walrus Sites 与传统托管之间做选择	下方的技能内容

---

技能内容

核心概念

• Site 对象。 Walrus Sites 框架包中类型为 site::Site 的 Sui 对象。它保存元数据和动态字段，用于将资源路径映射到 Walrus blob 引用。由 site-builder deploy 创建，归发布者地址所有。

• 资源。 已部署目录中的每个文件都会成为存储在 Walrus 上的资源。较小的文件可能会打包成一个 quilt。每个资源都有一个路径（例如，/index.html、/assets/main.js）和可选的 HTTP 标头。

• Portal。 一种服务，可将 <base36-site-id>.localhost:3000 或 <name>.localhost:3000（可自托管／testnet），或 <name>.wal.app（配合 SuiNS 使用的 mainnet）URL 映射到链上的站点对象。它会读取站点的动态字段，以查找请求的资源路径，从 Walrus 聚合器获取 blob，并将其作为 HTTP 响应返回。

• ws-resources.json。 位于站点根目录中的配置文件，用于控制资源标头、路由规则、重定向配置、元数据和文件忽略规则。首次部署时会自动生成，并写入站点对象 ID。后续部署时，site-builder 会读取此文件，以确定是创建新站点还是更新现有站点。

• Blob 过期。 Walrus blob 的存储期限有限（最长为 53 个 epoch）。blob 过期后，portal 会返回一种特殊的 404 响应，其正文显示“此内容已无法使用／可能已过期”，并列出 Blob ID——这不同于普通的“页面未找到”404。使用 site-builder sitemap <object-id> 检查过期日期。使用更高的 --epochs 值重新部署即可修复。

• site-builder deploy。 推荐使用的统一命令，可创建新站点或更新现有站点（取代旧版 publish 和 update 命令）。

Site-builder CLI 命令

命令	用途
site-builder deploy <DIR>	创建或更新站点（推荐）
site-builder sitemap <OBJECT_ID>	列出资源及其过期日期
site-builder list-directory <DIR>	预览将要上传的内容
site-builder update-resources	添加或更新一个或多个资源
site-builder destroy <OBJECT_ID>	永久移除站点
site-builder convert <HEX>	将十六进制对象 ID 转换为 Base36

当找到对象 ID 时，deploy 会执行更新。对象 ID 可来自 --object-id <OBJECT_ID> 或 ws-resources.json 中的 object_id 字段；否则会发布新站点。必须指定 --epochs（最长时长使用 max）；--list-directory 会为原始文件生成索引页。运行 site-builder deploy --help，确认你所安装版本的标志拼写；文档教程使用 --object-ids，而参考页面使用 --object-id。

HTTP 重定向

ws-resources.json 中的 redirects 字段定义服务器端 HTTP 重定向。规则以动态字段的形式存储在 Site 对象中，portal 会在获取任何资源前先对其进行评估：

{
  "redirects": {
    "/old-page": { "location": "/new-page", "status_code": 301 },
    "/walrus-docs": { "location": "https://docs.wal.app", "status_code": 301 },
    "/legacy/**/*": { "location": "/index.html", "status_code": 302 }
  }
}

location 可以是站点内的路径，也可以是完整 URL；status_code 通常为 301、302 或 308。匹配模式采用 glob 风格：* 匹配一个路径段，**/* 匹配任意数量的路径段。这与 routes 部分不同，后者仅用于客户端路由。公共 portal 将重定向链的深度限制为 3。

生产环境检查清单

根据文档中的生产环境指南：

• 门户： wal.app 仅提供具有 SuiNS 名称的 Mainnet 站点；嵌套子名称（例如 app.myname.wal.app）无法解析，因此每个站点使用一个 SuiNS 名称。Testnet 和预览版需要本地或可自托管的门户。
• SPA 路由： "routes": { "/*": "/index.html" }；更具体的模式优先于通配符。
• 缓存： 门户和 CDN 会激进地缓存。使用内容哈希文件名，需要回滚时保留旧的站点对象，并在认定部署失败前通过无痕窗口验证新部署。
• CI： 没有监视模式；在 CI 中每次推送时运行 site-builder deploy。提交 ws-resources.json（它包含站点对象 ID），否则每次 CI 运行都会创建新站点，而不是更新现有站点。
• Next.js： 使用 output: "export" 和 images: { unoptimized: true } 构建，部署 out/，并将 ws-resources.json 放入 public/，以便重新部署时更新同一个站点。API 路由、服务器操作和按需渲染均无法运行。
• 工具链： suiup 会一起安装并固定 sui、walrus 和 site-builder 的版本。

自定义域名### 自定义域名

SuiNS 名称： 使用 SuiNS 工具将 SuiNS 名称关联到你的站点对象（这是单独的链上步骤）。门户通过 SuiNS 名称记录中的 walrusSiteId 字段，将 <name>.wal.app 解析到你的站点。注意：ws-resources.json 中的 site_name 字段只会设置 Site 对象的链上显示名称，不会配置 SuiNS。

自定义 DNS： 使用 DNS CNAME 记录将自己的域名指向 Walrus Sites 门户。详情请参阅 DNS 配置指南。

使用 GitHub Actions 实现 CI/CD

使用官方 Deploy Walrus Site GitHub Action 自动部署：

- uses: MystenLabs/walrus-sites-github-actions/deploy@v3
  with:
    DIST: ./dist
    SUI_NETWORK: testnet
    EPOCHS: 30
    SUI_ADDRESS: ${{ secrets.SUI_ADDRESS }}
    SUI_KEYSTORE: ${{ secrets.SUI_KEYSTORE }}

身份验证方式（任选一种）：

1. SUI_ADDRESS + SUI_KEYSTORE — 地址和密钥库文件内容
2. SUI_BECH32_PRIVATE_KEY — bech32 编码的私钥
3. SUI_SECRET_PHRASE — 12 或 24 个单词的恢复短语

该 Action 会处理构建、发布以及更新 ws-resources.json。使用 GITHUB_TOKEN，让该 Action 在首次部署后创建一个包含更新后的 ws-resources.json 的 PR。

已知限制

• 仅支持静态站点。 不支持服务器端渲染、请求处理程序或数据库。通过 ws-resources.json 中的 redirects 字段支持 HTTP 重定向；routes 部分仅在客户端生效，而在请求时于服务器端运行的框架重定向插件无法使用。
• 不支持机密信息。 所有内容都存储在 Walrus 上（公开可见）。请勿包含 API 密钥、凭据或私人数据。
• 公共门户最多支持 3 次重定向跳转；可自托管的门户可以配置此限制。
• 路由通配符只能出现在模式末尾（/path/*，不能是 /path/*/to）；路由目标必须存在于已部署的文件中；自定义标头按精确资源路径设置，不是全局设置。
• 服务工作线程门户在 iOS 和某些浏览器上存在限制。
• 不完全支持 PWA。

规则

1. 选择合适的 --epochs 值。 最多为 53 个 epoch（测试网上约 53 天，因为 1 个 epoch = 1 天；主网上约 2 年，因为 1 个 epoch = 14 天）。使用 --epochs max 可获得最长的存储时长。注意：--permanent 仅能防止删除，不会延长存储时长。
2. 部署前先构建。 运行 npm run build（或同等命令）以生成静态输出目录。site-builder 会部署你指定目录中的内容。
3. 除非确定 Walrus Sites 框架包已升级，否则不要更改 portal 配置中的 original_package_id。
4. wal.app 仅为带有 SuiNS 名称的 Mainnet 站点提供服务。 不支持 Testnet 站点，也不支持嵌套子名称。如需使用 Testnet，请从 MystenLabs/walrus-sites 仓库自行托管 portal。
5. 将 ws-resources.json 保留在版本控制中。 该文件记录站点对象 ID。没有它，后续部署会创建新站点，而不是更新现有站点。
6. 使用 site-builder deploy，而不是 publish/update。 deploy 命令是推荐使用的统一命令。

常见错误

• 使用 --epochs 5 发布，然后纳闷站点为何消失。 Blob 已过期。使用更高的 --epochs 值或 --epochs max 重新部署。
• 将 portal 的 original_package_id 改为应用的包 ID。 portal 需要的是 Walrus Sites 框架包 ID（site::Site），而不是 Move 合约的 ID。
• 尝试通过 wal.app 访问 Testnet 站点。 它仅提供 Mainnet 服务。Testnet 请使用本地 portal。
• 部署前忘记构建前端。 site-builder deploy dist/ 会部署 dist/ 目录中的内容。如果没有先构建，就会部署源文件或过期的输出。
• 部署 SPA 时没有设置回退路由。 React/Vue/Svelte SPA 使用客户端路由。直接导航到 /dashboard 时，portal 会查找不存在的 /dashboard 资源。请在 ws-resources.json 中配置回退路由。
• 启动 portal 前没有停止占用 3000 端口的进程。 其他开发工具经常会使用 3000 端口。如果该端口已被占用，portal 会静默失败。
• 首次部署后没有提交 ws-resources.json。 没有该文件，下次部署会创建全新站点，而不是更新现有站点。
• WASM 文件返回 503 错误。 大型 .wasm 文件可能会触发 portal 返回 upstream connect error or disconnect/reset before headers。这是因为聚合器响应超出了 portal 的空闲超时时间，而不是 blob 大小限制所致。修复方案（提交 a31ec78、#714）根据聚合器重试预算设置 idleTimeout。如果遇到此问题，请通过 AGGREGATOR_REQUEST_TIMEOUT_MS / PORTAL_IDLE_TIMEOUT_MAX_S 环境变量进行调整。
• Windows 用户在 Docker 命令中使用 $(pwd)。 PowerShell 不支持 $(pwd)。请改用完整的绝对路径。
• SuiNS 域名费用。 通过 SuiNS 注册自定义 .sui 名称的费用约为每年 10 美元。这与 Walrus 存储费用分开计算。
• 部署仓库根目录，而不是构建输出目录。 将 site-builder deploy 指向 dist/、build/ 或 out/，而非仓库根目录。部署根目录会上传 node_modules/、源文件和配置，大幅增加费用。
• 没有 ws-resources.json 就重新部署到现有站点。 如果文件已丢失，请使用 --object-id <SITE_OBJECT_ID> 直接指定现有站点对象。