第 11 章 Walrus Sites CI/CD

Walrus Sites 的 CI/CD 目标很简单：每次合并到主分支后，构建静态产物，调用官方 GitHub Action 运行 site-builder deploy，并保存更新后的 ws-resources.json。

官方 Action 是：

MystenLabs/walrus-sites-github-actions/deploy

它负责下载 site-builder、写入 Sui keystore，并对你指定的静态目录执行部署。它不会替你构建前端项目，所以 npm run build、mdbook build、astro build 等步骤必须放在 Action 之前。

凭据

在 GitHub 仓库中配置：

类型	名称	内容
Secret	`SUI_KEYSTORE`	部署钱包的 Sui keystore JSON 内容。
Variable	`SUI_ADDRESS`	部署钱包地址。

部署钱包必须拥有目标 Walrus Site 对象。生产项目建议单独创建部署钱包，只给它站点更新所需资产，不要复用个人主钱包。

最小静态站点部署 workflow

本仓库提供可复制模板：examples/sites/github-actions/deploy-walrus-site.yml。

如果你的仓库直接包含静态目录 site/：

name: Deploy Walrus Site

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: write
  pull-requests: write

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - name: Deploy to Walrus Sites
        uses: MystenLabs/walrus-sites-github-actions/deploy@main
        with:
          DIST: site
          EPOCHS: 5
          SUI_ADDRESS: ${{ vars.SUI_ADDRESS }}
          SUI_KEYSTORE: ${{ secrets.SUI_KEYSTORE }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          SITE_BUILDER_VERSION: v2

第一次部署没有 ws-resources.json 或其中没有 object_id 时，Action 会创建新站点。如果传入了 GITHUB_TOKEN 且权限足够，Action 可以把新生成或更新后的 ws-resources.json 通过 pull request 带回仓库。

Vite / React 示例

Vite 的部署目录是 dist，但 ws-resources.json 通常放在项目根目录或 public/ 中。为了让构建产物带上配置文件，可以把它放到 public/ws-resources.json：

my-app/
├── public/
│   └── ws-resources.json
├── src/
├── index.html
└── package.json

workflow：

name: Deploy Vite App to Walrus Sites

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: write
  pull-requests: write

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - uses: actions/setup-node@v6
        with:
          node-version: 22
          cache: npm

      - run: npm ci
      - run: npm run build

      - name: Deploy to Walrus Sites
        uses: MystenLabs/walrus-sites-github-actions/deploy@main
        with:
          DIST: dist
          EPOCHS: 10
          SUI_ADDRESS: ${{ vars.SUI_ADDRESS }}
          SUI_KEYSTORE: ${{ secrets.SUI_KEYSTORE }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          SITE_BUILDER_VERSION: v2

如果第一次部署后 Action 创建了更新 ws-resources.json 的 PR，先合并它，再继续后续自动部署。否则每次 CI 都会缺少 object_id，不断创建新站点。

mdBook 示例

mdBook 的构建输出默认是 book/。把 Walrus Sites 配置复制到输出目录：

name: Deploy mdBook to Walrus Sites

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: write
  pull-requests: write

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - name: Install mdBook
        run: |
          curl -LsSf https://github.com/rust-lang/mdBook/releases/download/v0.5.2/mdbook-v0.5.2-x86_64-unknown-linux-gnu.tar.gz \
            | tar -xz
          sudo mv mdbook /usr/local/bin/mdbook

      - run: mdbook build
      - run: cp ws-resources.json book/ws-resources.json

      - name: Deploy to Walrus Sites
        uses: MystenLabs/walrus-sites-github-actions/deploy@main
        with:
          DIST: book
          EPOCHS: 10
          SUI_ADDRESS: ${{ vars.SUI_ADDRESS }}
          SUI_KEYSTORE: ${{ secrets.SUI_KEYSTORE }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          SITE_BUILDER_VERSION: v2

分环境发布

建议把 Testnet 和 Mainnet 的配置分开：

config/
├── ws-resources.mainnet.json
└── ws-resources.testnet.json

部署前复制到构建目录：

cp config/ws-resources.testnet.json dist/ws-resources.json

GitHub Actions 可以用 workflow_dispatch 参数控制环境：

on:
  workflow_dispatch:
    inputs:
      target:
        type: choice
        required: true
        options: [testnet, mainnet]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - run: npm ci
      - run: npm run build
      - run: cp config/ws-resources.${{ inputs.target }}.json dist/ws-resources.json
      - uses: MystenLabs/walrus-sites-github-actions/deploy@main
        with:
          DIST: dist
          EPOCHS: 10
          SUI_ADDRESS: ${{ vars.SUI_ADDRESS }}
          SUI_KEYSTORE: ${{ secrets.SUI_KEYSTORE }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          SITE_BUILDER_VERSION: v2

Mainnet 发布建议保留人工触发，Testnet 可以在 push 后自动发布。

CI 失败排查

现象	处理
每次都创建新站点	检查 `ws-resources.json` 是否被提交或 Action 是否能创建 PR。
`owner` 或权限错误	部署钱包不是 Walrus Site 对象 owner，换钱包或转移对象。
找不到 `index.html`	`DIST` 指错目录，应该指向构建产物。
Mainnet 部署成功但打不开	`wal.app` 需要 SuiNS 名称；先把名称指向站点对象。
路由刷新 404	在 `ws-resources.json` 加 `"routes": { "/*": "/index.html" }`。
静态资源旧版本	检查 headers，入口 HTML 不要长期缓存，hash 资源可以长缓存。

CI 的核心约束是可重复：同一份源码、同一份 lockfile、同一个 ws-resources.json，应该更新同一个站点对象。只要这个约束成立，Walrus Sites 的发布流程就能稳定接入常规前端工程。

Keyboard shortcuts