walrus-sites

Walrus Sites — 分散型ウェブサイトホスティング

情報源の制約： このスキルの情報はすべて、 Walrus Sites documentation と MystenLabs/walrus-sites repository から取得しています。 このスキルを拡張する場合は、これらの情報源のみを参照してください。

Walrus Sites を使うと、静的ウェブサイト（HTML/CSS/JS）を Walrus にデプロイでき、オンチェーンの Sui オブジェクトでサイトのリソースを追跡できます。ポータルサーバーがサイトのサブドメインを解決し、Walrus からリソースを取得して HTTP 経由で配信します。その結果、中央集権型のサーバー、CDN、DNS を必要としない、完全に分散化されたフロントエンドを実現できます。

よくある失敗：

1. Blob の有効期限切れ。 エポック数が少なすぎる状態で公開されたサイトは、Blob の有効期限が切れると予告なく動作しなくなります。常に余裕のある --epochs 値、または --epochs max（最大 53 エポック。テストネットでは約 53 日、メインネットでは約 2 年）を指定してください。注：--permanent は Blob を削除不可にするだけで、--epochs の値を超えてストレージ期間を延長するものではありません。
2. ポータルの設定ミス。 ポータルの original_package_id は、アプリの Move パッケージではなく、Walrus Sites フレームワークのパッケージ（site::Site）と一致している必要があります。
3. テストネットのサイトでは wal.app を使用できません。 公開されている wal.app ポータルが配信するのはメインネットのみです。テストネットでは、セルフホスト型のローカルポータルが必要です。
4. SPA のルーティング。 シングルページアプリでは、クライアント側ルーティング用の ws-resources.json ルーティング設定が必要です。設定しない場合、ディープリンクに直接アクセスすると 404 が返されます。

---

サブスキル

publishing — サイトの構築とデプロイ

パス： publishing/SKILL.md 読み込むタイミング： 新しいサイトのデプロイ、既存サイトの更新、エポック期間の選択、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/
ポータルに「ページが見つかりません」と表示される	portal/ + publishing/（Blob の有効期限を確認）
SPA ルーティングまたはカスタムヘッダーを設定する	publishing/
カスタムドメイン（SuiNS）を設定する	以下のスキルの内容
GitHub Actions で CI/CD をセットアップする	以下のスキルの内容
サイトが保有するリソースを確認する	publishing/（site-builder sitemap）
デプロイ済みのサイトを削除する	publishing/
Walrus Sites と従来型のホスティングを比較して選ぶ	以下のスキルの内容

---

スキルの内容

主な概念

• サイトオブジェクト。 Walrus Sites フレームワークパッケージの型 site::Site を持つ Sui オブジェクトです。メタデータと、リソースパスを Walrus の blob 参照に対応付ける動的フィールドを保持します。site-builder deploy で作成され、パブリッシャーのアドレスが所有します。

• リソース。 デプロイしたディレクトリ内の各ファイルは、Walrus に保存されるリソースになります。小さなファイルはまとめてキルトに格納される場合があります。各リソースにはパス（例：/index.html、/assets/main.js）と、任意の HTTP ヘッダーがあります。

• ポータル。 <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 エポック）、期間が過ぎると失効します。blob が失効すると、ポータルは本文に「このコンテンツは利用できなくなりました／有効期限が切れた可能性があります」と表示し、Blob ID を示す固有の 404 を返します。これは通常のページが見つからない場合の 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	1 つ以上のリソースを追加または更新します
site-builder destroy <OBJECT_ID>	サイトを完全に削除します
site-builder convert <HEX>	16 進数のオブジェクト ID を Base36 に変換します

deploy は、--object-id <OBJECT_ID> または ws-resources.json の object_id フィールドからオブジェクト ID を見つけるとサイトを更新し、見つからない場合は新しいサイトを公開します。--epochs は必須です（最長期間にするには max を指定します）。--list-directory はファイル一覧のインデックスページを生成します。インストール済みバージョンでのフラグの表記を確認するには、site-builder deploy --help を実行してください。ドキュメントのチュートリアルでは --object-ids、リファレンスページでは --object-id が使われています。

HTTP リダイレクト

ws-resources.json の redirects フィールドで、サーバー側の HTTP リダイレクトを定義します。ルールは Site オブジェクトの動的フィールドとして保存され、ポータルはリソースを取得する前にこれらのルールを評価します。

{
  "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 形式で、* は 1 つのパスセグメント、**/* は任意の数のパスセグメントに一致します。これは、クライアント側のルーティングのみを行う routes セクションとは異なります。公開ポータルでは、リダイレクトチェーンの深さは最大 3 に制限されています。

本番環境のチェックリスト

ドキュメントの本番環境ガイドより：

• ポータル： wal.app が配信するのは、SuiNS 名を持つ Mainnet サイトのみです。app.myname.wal.app のようなネストされたサブネームは解決されないため、サイトごとに SuiNS 名を1つ使用してください。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つを選択）：

1. SUI_ADDRESS + SUI_KEYSTORE — アドレスとキーストアファイルの内容
2. SUI_BECH32_PRIVATE_KEY — bech32 形式でエンコードされた秘密鍵
3. SUI_SECRET_PHRASE — 12語または24語のリカバリーフレーズ

この Action は、ビルド、公開、ws-resources.json の更新を処理します。初回デプロイ後に更新された ws-resources.json を含む PR を Action に作成させるには、GITHUB_TOKEN を使用してください。

既知の制限事項

• 静的サイトのみです。 サーバーサイドレンダリング、リクエストハンドラー、データベースには対応していません。ws-resources.json の redirects フィールドを通じた HTTP リダイレクトには対応しています。routes セクションはクライアントサイド専用で、リクエスト時にサーバーサイドで実行されるフレームワークのリダイレクトプラグインは動作しません。
• シークレットには対応していません。 すべてのコンテンツは Walrus 上に保存され、公開されます。API キー、認証情報、非公開データを含めないでください。
• 公開ポータルでのリダイレクトは最大3回までです。セルフホスト可能なポータルでは、上限を設定できます。
• ルートのワイルドカードはパターンの末尾にのみ指定できます（/path/* は使用できますが、/path/*/to は使用できません）。ルートのターゲットはデプロイ済みファイルの中に存在する必要があります。また、カスタムヘッダーは完全一致するリソースパスごとに設定され、グローバルには設定できません。
• iOS および一部ブラウザーでは、サービスワーカーポータルに制限があります。
• PWA は完全にはサポートされていません。

ルール

1. 適切な --epochs の値を選択してください。 最大は53エポックです（テストネットでは1エポック＝1日のため約53日、メインネットでは1エポック＝14日のため約2年）。ストレージ期間を最長にするには、--epochs max を使用してください。注：--permanent は削除を防ぐだけで、ストレージ期間は延長しません。
2. デプロイ前にビルドしてください。 npm run build（または同等のコマンド）を実行して、静的な出力ディレクトリを生成します。site-builder は指定したディレクトリをデプロイします。
3. Walrus Sites フレームワークパッケージがアップグレードされたと分かっている場合を除き、ポータル設定の original_package_id を変更しないでください。
4. wal.app は SuiNS 名を持つメインネットのサイトのみを提供します。 テストネットのサイトや、ネストされたサブネームには対応していません。テストネットでは、MystenLabs/walrus-sites リポジトリからポータルをセルフホストしてください。
5. ws-resources.json をバージョン管理に含めてください。 このファイルにはサイトオブジェクト ID が記録されています。これがないと、次回のデプロイで既存サイトが更新されず、新しいサイトが作成されます。
6. publish／update ではなく、site-builder deploy を使用してください。 deploy コマンドが推奨される統合コマンドです。

よくある間違い

• --epochs 5 で公開して、サイトが消えた理由が分からなくなる。 Blob の有効期限が切れています。より大きな --epochs の値、または --epochs max を指定して再デプロイしてください。
• ポータルの original_package_id をアプリのパッケージ ID に変更する。 ポータルに必要なのは、Move コントラクトの ID ではなく、Walrus Sites フレームワークのパッケージ ID（site::Site）です。
• テストネットのサイトに wal.app でアクセスしようとする。 wal.app が提供するのはメインネットのみです。テストネットにはローカルのポータルを使用してください。
• デプロイ前にフロントエンドをビルドし忘れる。 site-builder deploy dist/ は、dist/ ディレクトリの内容をデプロイします。先にビルドしていない場合、ソースファイルや古い出力がデプロイされます。
• フォールバックルーティングなしで SPA をデプロイする。 React／Vue／Svelte の SPA はクライアントサイドルーティングを使用します。/dashboard に直接移動すると、ポータルは存在しない /dashboard リソースを探します。ws-resources.json でフォールバックルートを設定してください。
• ポータルを起動する前にポート3000を解放しない。 他の開発ツールがポート3000を使用していることがよくあります。ポートが使用中の場合、ポータルはエラーを表示せずに起動に失敗します。
• 初回デプロイ後に ws-resources.json をコミットし忘れる。 このファイルがないと、次回のデプロイで既存サイトが更新されず、新しいサイトが作成されます。
• WASM ファイルで503エラーが返される。 大きな .wasm ファイルでは、ポータルから upstream connect error or disconnect/reset before headers が返されることがあります。これは Blob のサイズ制限ではなく、アグリゲーターの応答がポータルのアイドルタイムアウトを超えることが原因です。修正（コミット a31ec78、#714）では、アグリゲーターの再試行予算に基づいて idleTimeout を設定します。この問題が発生した場合は、環境変数 AGGREGATOR_REQUEST_TIMEOUT_MS／PORTAL_IDLE_TIMEOUT_MAX_S で調整してください。
• Windows ユーザーが Docker コマンドで $(pwd) を使用する。 PowerShell は $(pwd) に対応していません。代わりに絶対パスを指定してください。
• SuiNS ドメインの費用。 カスタム .sui 名の費用は、SuiNS を通じて年間約10ドルです。これは Walrus のストレージ費用とは別です。
• ビルド出力ではなく、リポジトリのルートをデプロイする。 site-builder deploy には、リポジトリのルートではなく dist/、build/、または out/ を指定してください。ルートをデプロイすると、node_modules/、ソースファイル、設定ファイルがアップロードされ、費用が大幅に増加します。
• ws-resources.json がない状態で既存サイトに再デプロイする。 ファイルを紛失した場合は、--object-id <SITE_OBJECT_ID> を使用して既存のサイトオブジェクトを直接指定してください。