walrus-sites

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Walrus Sites — Decentralized Website Hosting

Walrus Sites — 去中心化网站托管

MCP tool: When available in your environment, also query the Sui documentation MCP server (
https://sui.mcp.kapa.ai
) for up-to-date answers. Use it for verification and for details not covered by these reference files.

Walrus Sites lets you deploy a static website (HTML/CSS/JS) to Walrus, with an on-chain Sui object tracking the site's resources. A portal server resolves site subdomains, fetches resources from Walrus, and serves them over HTTP. The result is a fully decentralized frontend — no centralized server, CDN, or DNS required.

Source constraint: All information in this skill is sourced from the MystenLabs/walrus-sites repository and the Walrus Sites documentation. When extending or updating this skill, only pull from these sources. Do not use third-party blogs or unofficial tutorials.

Common failures:

Blobs expire. Sites published with too few epochs silently break — the portal returns 404 once the blobs expire. Always use a generous
```
--epochs
```
value (30+).
Portal misconfiguration. The portal's
```
original_package_id
```
must match the Walrus Sites framework package (
```
site::Site
```
), not your app's Move package. The testnet example config ships with the correct value — don't change it.
Testnet sites can't use
wal.app
. The public
```
wal.app
```
portal only serves mainnet sites. Testnet requires a self-hosted local portal.
SPA routing. Single-page apps need
```
ws-resources.json
```
routes config to handle client-side routing. Without it, direct navigation to
```
/my-route
```
returns 404.

MCP工具： 当你的环境中可用时，也可以查询Sui文档MCP服务器（
https://sui.mcp.kapa.ai
）获取最新答案。用它来验证信息，以及获取这些参考文件未涵盖的细节。

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

来源限制： 本技能中的所有信息均来自MystenLabs/walrus-sites仓库和Walrus Sites文档。扩展或更新本技能时，仅可从这些来源获取内容，请勿使用第三方博客或非官方教程。

常见故障：

Blob过期。 使用过少纪元数发布的站点会无声失效——一旦Blob过期，门户将返回404错误。请始终使用足够大的
```
--epochs
```
值（30+）。
门户配置错误。 门户的
```
original_package_id
```
必须匹配Walrus Sites框架包（
```
site::Site
```
），而非你的应用Move包。测试网示例配置已包含正确值——请勿修改。
测试网站点无法使用
wal.app
。公共
```
wal.app
```
门户仅托管主网站点。测试网需要自行搭建本地门户。
SPA路由。 单页应用需要
```
ws-resources.json
```
路由配置来处理客户端路由。如果没有该配置，直接导航到
```
/my-route
```
会返回404错误。

Sub-skills

子技能

publishing — Building and deploying sites

publishing — 构建并部署站点

Path:

publishing/SKILL.md

Load when: deploying a new site, updating an existing site, choosing epoch duration, configuring

ws-resources.json

, or troubleshooting

site-builder

errors. Covers:

site-builder publish

site-builder update

--epochs

flag, blob expiration,

ws-resources.json

configuration, SPA routing, site naming,

site-builder sitemap

for debugging,

site-builder destroy

路径：

publishing/SKILL.md

加载时机： 部署新站点、更新现有站点、选择纪元时长、配置

ws-resources.json

或排查

site-builder

错误时。 涵盖内容：

site-builder publish

、

site-builder update

、

--epochs

参数、Blob过期、

ws-resources.json

配置、SPA路由、站点命名、用于调试的

site-builder sitemap

、

site-builder destroy

。

portal — Running a local portal for testnet

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

Path:

portal/SKILL.md

Load when: the user needs to view a testnet site, set up the local portal, fix portal 404s, or understand how portal resolution works. Covers: cloning the portal, installing dependencies (Bun),

portal-config.yaml

, the

original_package_id

gotcha, starting the server, URL format, port conflicts, mainnet vs testnet differences.

路径：

portal/SKILL.md

加载时机： 用户需要查看测试网站点、搭建本地门户、修复门户404错误或了解门户解析原理时。 涵盖内容： 克隆门户仓库、安装依赖（Bun）、

portal-config.yaml

、

original_package_id

的注意事项、启动服务器、URL格式、端口冲突、主网与测试网的差异。

Routing guide

路由指南

Task	Load
Deploy a frontend to Walrus Sites	`publishing/`
Update an existing deployed site	`publishing/`
Fix 404 or expired site	`publishing/` + `portal/`
View a testnet site locally	`portal/`
Set up the local portal	`portal/`
Portal shows "Page not found"	`portal/` + `publishing/` (check blob expiry)
Configure SPA routing	`publishing/`
Check what resources a site has	`publishing/` ( `site-builder sitemap` )
Delete a deployed site	`publishing/`
Choose between Walrus Sites and traditional hosting	Skill Content below

任务	加载内容
将前端部署到Walrus Sites	`publishing/`
更新已部署的现有站点	`publishing/`
修复404或过期站点	`publishing/` + `portal/`
本地查看测试网站点	`portal/`
搭建本地门户	`portal/`
门户显示“页面未找到”	`portal/` + `publishing/` （检查Blob过期情况）
配置SPA路由	`publishing/`
查看站点包含的资源	`publishing/` （ `site-builder sitemap` ）
删除已部署的站点	`publishing/`
在Walrus Sites与传统托管之间做选择	下方技能内容

Skill Content

技能内容

Key concepts

核心概念

Site object. A Sui object of type
```
site::Site
```
(from the Walrus Sites framework package). It holds metadata (name, description) and dynamic fields mapping resource paths to Walrus blob references. Created by
```
site-builder publish
```
, owned by the publisher's address.
Resources. Each file in the deployed directory becomes a resource stored on Walrus. Small files may be batched into a single "quilt" blob. Each resource has a path (e.g.,
```
/index.html
```
,
```
/assets/main.js
```
) and optional HTTP headers.
Portal. A server that maps
```
<base36-site-id>.localhost:3000
```
URLs to on-chain site objects. It reads the site's dynamic fields to find the requested resource path, fetches the blob from a Walrus aggregator, and returns it as an HTTP response. The portal is framework-level infrastructure, not part of your app.
ws-resources.json
. A configuration file in the site's root directory that controls resource headers, routing, and site metadata. Auto-generated on first publish with the site object ID. On subsequent runs, the site-builder reads it to determine whether to create a new site or update the existing one.
Blob expiration. Walrus blobs have a finite storage duration measured in epochs. When blobs expire, the portal can no longer fetch them and returns 404. Use
```
site-builder sitemap <object-id>
```
to check expiration dates. Re-publish with a higher
```
--epochs
```
value to fix.

站点对象（Site object）：类型为
```
site::Site
```
的Sui对象（来自Walrus Sites框架包）。它包含元数据（名称、描述）以及将资源路径映射到Walrus Blob引用的动态字段。由
```
site-builder publish
```
创建，归发布者地址所有。
资源（Resources）：部署目录中的每个文件都会成为存储在Walrus上的资源。小文件可能会被批量打包到单个“拼接（quilt）”Blob中。每个资源都有路径（如
```
/index.html
```
、
```
/assets/main.js
```
）和可选的HTTP头。
门户（Portal）：将
```
<base36-site-id>.localhost:3000
```
URL映射到链上站点对象的服务器。它读取站点的动态字段以找到请求的资源路径，从Walrus聚合器获取Blob，并将其作为HTTP响应返回。门户是框架级基础设施，不属于你的应用。
ws-resources.json
：站点根目录中的配置文件，用于控制资源头、路由和站点元数据。首次发布时会自动生成并包含站点对象ID。后续运行时，site-builder会读取该文件以确定是创建新站点还是更新现有站点。
Blob过期（Blob expiration）：Walrus Blob的存储时长是有限的，以纪元数衡量。当Blob过期时，门户无法再获取它们，会返回404错误。使用
```
site-builder sitemap <object-id>
```
查看过期日期。重新发布时使用更高的
```
--epochs
```
值即可修复。

Rules

规则

Always use
--epochs 30
or higher for testnet deploys. Low values (like 5) cause blobs to expire within days. For production mainnet, use even higher values or
```
--permanent
```
.
Build before publishing. Run
```
npm run build
```
(or equivalent) to produce a static
```
dist/
```
directory. The site-builder publishes whatever directory you point it at.
Don't change
original_package_id
in the portal config unless you know the Walrus Sites framework package has been upgraded. The testnet example value is correct.
wal.app
is mainnet only. For testnet, self-host the portal from the
```
MystenLabs/walrus-sites
```
repo.
Check
ws-resources.json
after first publish. It records the site object ID. Keep it in version control so future publishes update the existing site rather than creating a new one.

测试网部署时始终使用
--epochs 30
或更高值。低值（如5）会导致Blob在数天内过期。对于生产主网，请使用更高的值或
```
--permanent
```
参数。
发布前先构建。 运行
```
npm run build
```
（或等效命令）生成静态
```
dist/
```
目录。site-builder会发布你指定的任意目录中的内容。
请勿修改门户配置中的
original_package_id
，除非你确认Walrus Sites框架包已升级。测试网示例值是正确的。
wal.app
仅适用于主网。测试网需要从
```
MystenLabs/walrus-sites
```
仓库自行托管门户。
首次发布后检查
ws-resources.json
。它记录了站点对象ID。将其纳入版本控制，以便后续发布时更新现有站点而非创建新站点。

Common mistakes

常见错误

Publishing with
--epochs 5
and wondering why the site is gone a week later. Blobs expired. Re-publish with
```
--epochs 30+
```
.
Changing the portal's
original_package_id
to your app's package ID. The portal needs the Walrus Sites framework package ID (
```
site::Site
```
), not your Move contract's package ID. These are completely different things.
Trying to visit a testnet site on
wal.app
. It only serves mainnet. You need a local portal for testnet.
Forgetting to build the frontend before publishing.
```
site-builder publish dist/
```
publishes the
```
dist/
```
directory contents. If you didn't
```
npm run build
```
first, you're publishing source files or stale output.
Deploying an SPA without fallback routing. React/Vue/Svelte SPAs use client-side routing. Direct navigation to
```
/borrows
```
hits the portal, which looks for
```
/borrows
```
as a resource — and it doesn't exist. Configure a fallback in
```
ws-resources.json
```
.
Not killing port 3000 before starting the portal. Vite dev server, Next.js, or other tools often use port 3000. The portal silently fails to bind if the port is taken.

使用
--epochs 5
发布，一周后疑惑站点为何消失。 Blob已过期。重新发布时使用
```
--epochs 30+
```
。
将门户的
original_package_id
改为应用的包ID。门户需要的是Walrus Sites框架包ID（
```
site::Site
```
），而非你的Move合约包ID。这两者完全不同。
尝试在
wal.app
上访问测试网站点。它仅托管主网站点。测试网需要本地门户。
发布前忘记构建前端。
```
site-builder publish dist/
```
会发布
```
dist/
```
目录的内容。如果未先运行
```
npm run build
```
，你发布的将是源文件或过时的输出内容。
部署SPA时未配置回退路由。 React/Vue/Svelte等SPA使用客户端路由。直接导航到
```
/borrows
```
会访问门户，而门户会查找
```
/borrows
```
作为资源——但该资源不存在。请在
```
ws-resources.json
```
中配置回退路由。
启动门户前未释放3000端口。 Vite开发服务器、Next.js或其他工具通常会使用3000端口。如果端口已被占用，门户会静默绑定失败。