第 10 章 SuiNS、Portal 与自定义域名

Walrus Sites 没有传统源站。portal 是浏览器和 Walrus/Sui 之间的 HTTP 网关：它根据域名或子域名找到站点对象，从 Sui 读取资源索引，再从 Walrus 读取资源字节并返回 HTTP 响应。

portal 如何解析站点

一次请求大致经过这些步骤：

1. 浏览器请求 https://NAME.wal.app/path/to/page 或你的自托管 portal 域名。
2. portal 解析主机名，得到 SuiNS 名称或 Base36 站点对象 ID。
3. portal 查询 Sui 上的 Walrus Site 对象和动态字段。
4. portal 根据路径、routes、redirects 和资源索引找到目标资源。
5. portal 从 Walrus aggregator 读取资源，并带上配置的 headers 返回给浏览器。

这意味着静态资源可以完全去中心化存储，但 portal 仍是访问体验的一部分。生产项目要明确使用公共 portal、第三方 portal，还是自托管 portal。

使用 SuiNS 访问 wal.app

官方 Mainnet portal 是 https://wal.app。当前规则是：通过 wal.app 访问 Walrus Site 需要 SuiNS 名称；Base36 对象 ID 子域名不再用于 wal.app 访问。Base36 仍可用于本地或其他 portal。

SuiNS 设置流程：

1. 部署站点并拿到十六进制对象 ID：

   site-builder --context mainnet deploy --epochs max dist
   

2. 记录输出中的 Walrus Site object ID，或从 dist/ws-resources.json 读取：

   jq -r .object_id dist/ws-resources.json
   

3. 在 SuiNS 注册或管理页面设置名称：

   网络	入口
   Mainnet	https://suins.io
   Testnet	https://testnet.suins.io

4. 把 SuiNS 名称的 Walrus Site 目标设置为你的站点对象 ID。

5. 通过 https://YOURNAME.wal.app 访问。

SuiNS 名称应提前规划。wal.app 对可解析名称长度有限制，官方文档当前说明最多 21 个字符；名称字符也应保持在小写字母和数字范围内，避免把品牌名设计成无法解析的域名。

Base36 对象 ID

自托管 portal 或本地 portal 通常需要 Base36 形式的对象 ID：

site-builder convert 0xYOUR_SITE_OBJECT_ID

输出值可用于 portal 子域名或 portal-config.yaml 中的固定站点配置。十六进制对象 ID 是链上对象标识；Base36 是面向域名子域名的编码形式，不要混用。

自定义 DNS 域名

如果你要把站点放到 https://example.com 或 https://docs.example.com，当前官方方案不是把 DNS CNAME 指到 wal.app。wal.app 公共 portal 不支持任意自定义 DNS 域名。

正确架构是：

1. 部署 Walrus Site，拿到对象 ID。
2. 部署自己的 Walrus Sites portal。
3. 在 portal 配置中固定服务你的站点。
4. 把 DNS A/AAAA/CNAME 记录指向你的 portal。
5. 在 portal 前配置 TLS，例如 Caddy、Nginx、Cloudflare 或云厂商负载均衡。

最小配置示意：

# portal-config.yaml
landing_page_oid_b36: "BASE36_SITE_OBJECT_ID"
allowed_domains:
  - "example.com"
  - "www.example.com"

不同版本的 portal 配置字段可能随仓库演进调整，生产前以 MystenLabs/walrus-sites 仓库中的模板和 README 为准。关键原则不变：你的 DNS 域名指向你控制的 portal，portal 再固定解析到 Walrus Site。

DNS 与 TLS

以 docs.example.com 为例：

docs.example.com.  300  CNAME  portal.example.net.

或直接指向服务器：

docs.example.com.  300  A      203.0.113.10
docs.example.com.  300  AAAA   2001:db8::10

TLS 可以由反向代理终止：

server {
    listen 443 ssl http2;
    server_name docs.example.com;

    ssl_certificate /etc/letsencrypt/live/docs.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/docs.example.com/privkey.pem;

    location / {
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto https;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_pass http://127.0.0.1:3000;
    }
}

portal 应只服务你允许的域名。不要把一个没有限制的 portal 暴露为任意站点网关，除非你明确要运营公共 portal。

外部链接

Walrus Site 内部的相对链接指向同一个站点对象中的资源：

<a href="/about.html">About</a>

外部网站、API、CDN、其他 Walrus Site 都应该使用绝对 URL：

<a href="https://docs.wal.app" target="_blank" rel="noopener noreferrer">
  Walrus Docs
</a>

使用 target="_blank" 时保留 rel="noopener noreferrer"，避免新页面拿到原页面的 window.opener。

生产检查清单

发布前确认：