跳转到正文

部署一个 Blockstudio 网站

只要将主题文件夹复制到服务器,区块就能正常工作:Blockstudio 会从文件系统中发现区块,其缓存也会自动检测输入的变化。实际网站还涉及更多环节。基于文件的页面只有在同步后才会进入数据库。静态预渲染内容会一直提供昨天的 HTML,直到有内容替换它。前面的 CDN 也会继续提供它缓存的内容。

本指南将介绍如何部署名为 acme 的主题,该主题通过 Composer 打包 Blockstudio。内容涵盖 CI 中运行的任务、文件部署到服务器后运行的任务、如何阅读页面同步报告,以及发布流程应包含哪些 wp bs 命令。

发布流程一图概览

  1. 构建。 CI 安装生产环境 Composer 依赖。
  2. 上传。 包含 vendor/ 在内的主题会部署到服务器。
  3. 同步页面。 wp bs pages sync 将页面文章与文件保持一致,并输出报告。
  4. 刷新源站缓存。 页面有更改时清除已存储的 HTML,然后重新预热。
  5. 清除 CDN。 最后执行,让边缘节点从全新的源站重新填充缓存。

步骤 3 和 4 需要服务器上有 WP-CLI。下面的脚本还会使用 jq 来读取 JSON。

步骤 1:在 CI 中安装 Composer

将 Blockstudio 打包到主题中并提交 composer.lock,这样 CI 就会安装你测试过的确切版本:

JSON
{
  "require": {
    "blockstudio/blockstudio": "^7.0"
  }
}
PHP
<?php
require_once __DIR__ . '/vendor/autoload.php';

在 CI 中安装时不包含开发依赖:

命令行
composer install --no-dev --optimize-autoloader --no-interaction --prefer-dist

Blockstudio 从自动加载器启动,其运行时依赖也已打包并在包内使用命名空间。当它从 vendor/ 目录加载时,内置的 GitHub 更新器会被禁用,因此只有 Composer 能更改版本。

步骤 2:确定哪些目录必须可写

Blockstudio 会在运行时写入生成的文件。在部署替换或锁定目录之前,先确认写入位置:

  • 运行时缓存默认位于 wp-content/blockstudio/cache/ 下。如果需要,可将 cache.path 指向专用的可写卷。更改路径后缓存将从空状态开始。
  • 已编译的区块资源默认写入每个区块旁边的 _dist 文件夹。如果发布目录为只读,或每次部署都会被替换,请将 assets.output 设为 cache,让这些文件改为写入缓存目录:
JSON
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "assets": {
    "output": "cache"
  }
}

部署时无需清除缓存。每个缓存条目都以其输入为键,其中包括区块文件、设置、当前主题和插件,以及 WordPress、PHP 和 Blockstudio 版本,因此更改这些内容的发布会生成新的键。在 production 和 staging 中,Blockstudio 会信任经过验证的监视快照 20 秒,然后才再次检查文件,因此更改可能需要最多 20 秒才会被发现。blockstudio/cache/watch_debounce 过滤器可以更改这个时间窗口。

步骤 3:同步页面

页面文章只会通过明确的同步操作发生变化。前端、管理后台、Ajax、REST、cron 和普通的 WP-CLI 请求都不会发现页面源文件或写入页面文章。部署时必须执行以下操作:

命令行
wp bs pages sync --format=json

在主题中有两个页面 about 和 contact 的网站上,首次运行会创建这两个页面:

JSON
{
    "discovered": 2,
    "created": 2,
    "updated": 0,
    "unchanged": 0,
    "removed": 0,
    "failed": 0,
    "fullReconciliation": true,
    "sourceId": "f88baddfd5a1deb94eb8c9bbeca10d5a0d47a72f16b50efdb25a7127945af7dd",
    "sourceIdentity": {
        "commit": "",
        "dirtyHash": "",
        "inventoryHash": "aaec5b9dd13d74eea872117b6167caa7a5d5c1abad9572fba22f6ddf6340adfe",
        "engineFingerprint": "2c442442bb49f91e7187560e6db8f3475caa0b62b47708cab95b6ff13aba4469",
        "hash": "f88baddfd5a1deb94eb8c9bbeca10d5a0d47a72f16b50efdb25a7127945af7dd"
    },
    "pages": {
        "about": {
            "status": "created",
            "postId": 545,
            "locked": false
        },
        "contact": {
            "status": "created",
            "postId": 546,
            "locked": false
        }
    },
    "errors": []
}

如何理解这些数据:

  • created、updated、unchanged、removed 和 failed 统计页面数量。如果页面的源文件指纹未发生变化,则不会写入文章或文章元数据,也不会触发更新钩子。
  • 每次执行都会比较完整的页面清单。fullReconciliation 会报告此次执行是否算作完整同步:首次运行时为 true,传入 --full 时也为此值,或者同步引擎本身发生变化时为此值;如果存在先前成功同步的标识,则为 false。下游工具可用它来决定是否重建全部内容。
  • sourceIdentity 是页面清单和同步引擎的确定性指纹。命令会在成功执行后保存它。

不带 --format=json 时,命令会输出一行摘要和一条成功提示。在 CI 日志中(此时不是终端),摘要行以制表符分隔:

Text
discovered	created	updated	unchanged	removed	failed	source_id
2	0	1	1	0	0	7bd575b4ee6c0a948f439dd83ce5fa403f8113c9406c3b13b6ade2f2b19f3c2c
Success: File-backed pages synchronized.

这次运行是在编辑 about/index.php 后执行的:一个页面已更新,另一个未更改。

同步失败时

如果发现或同步过程中报告错误,命令会以状态码 1 退出,导致 CI 步骤失败。仍会输出 JSON 报告,请将其记录到日志中。格式错误的 page.json 如下所示:

JSON
{
    "discovered": 0,
    ...
    "failed": 1,
    ...
    "pages": [],
    "errors": [
        {
            "code": "invalid_page_json",
            "message": "Invalid page.json file.",
            "context": {
                "path": ".../wp-content/themes/acme/pages/pricing/page.json"
            }
        }
    ]
}

只有在执行过程无错误结束后,源文件已消失的受管理页面才会被清理,因此同步失败的发布不会破坏线上页面。默认情况下,被移除的页面会移至回收站;blockstudio/pages/orphan_action 过滤器可以返回 trash、delete 或 keep。

每次部署都运行

即使页面没有变化,也要运行同步。如果你部署到发布目录并切换符号链接,那么即使页面未更改,它仍会指向上一版本的模板和布局路径,直到下一次同步刷新这些路径。此刷新不会触及 post_content 或修改日期。

--authoritative 和 --full

普通同步会保留编辑者在带键区块中更改的内容。--authoritative 则会用文件中的受管理内容替换现有内容,并可能清除页面同步锁。适用于以文件为准的场景,例如重置暂存站点,或没有人在编辑器中修改由文件管理的页面时。对于有活跃编辑者的站点,不要在每次部署时都使用它。

--full 会将此次执行标记为完整同步,无论保存的标识是什么。每次执行都会完成页面比较,因此此标志只会更改报告中的 fullReconciliation,不会改变检查哪些页面。后续步骤需要依据该值执行完整重建时,请传入此标志。

使用 PHP 编写的工具可以直接调用 Blockstudio\Pages::reconcile()。它会返回同一份报告,但不会保存标识:在发布的其余部分(例如已激活的静态资源)验证通过后,调用 Blockstudio\Pages::store_successful_source_identity()。

步骤 4:刷新静态缓存

如果网站在默认的 signature 模式下使用 静态预渲染,由 WP-CLI 更新的页面文章不会自行清除已存储的 HTML。读取报告;只要有任何更改就清除缓存,然后预热:

命令行
#!/usr/bin/env bash
set -euo pipefail

cd /var/www/example.com
report=$(mktemp)

# 1. Reconcile file-backed pages and keep the report.
if ! wp bs pages sync --format=json > "$report"; then
  cat "$report"
  exit 1
fi
jq '{discovered, created, updated, unchanged, removed}' "$report"

# 2. Drop stored HTML when page content changed.
changed=$(jq '.created + .updated + .removed' "$report")
if [ "$changed" -gt 0 ]; then
  wp bs prerender purge
fi

# 3. Re-warm in bounded passes until a pass warms nothing.
for _ in $(seq 1 50); do
  warmed=$(wp bs prerender warm | jq '.warmed')
  [ "$warmed" -gt 0 ] || break
done

wp bs prerender status | jq '{files, queue}'

每次 wp bs prerender warm 运行都会将过期的公开 URL 加入队列,最多渲染其中的 warm.concurrency 个,并输出摘要。在这次执行中,六个排队的 URL 有四个被领取,但四个都未能渲染:

JSON
{"queued":6,"processed":4,"warmed":0,"skipped":0,"failed":4}

未能渲染的 URL 会继续处于过期状态,并在下次运行时重新入队。因此循环会在首次没有预热任何内容时停止,而不是一直等到队列清空。剩余内容由定时预热程序或下一次匿名访问处理。

在 graph 模式下,按 URL 运行的预热程序会关闭,且 warm 不会将任何内容加入队列。图站点会用自己的构建替代步骤 2 和 3,渲染受影响的 URL,并以原子方式激活结果。参见签名模式和图模式。

步骤 5:CI 工作流

以下工作流是一个 GitHub Actions 示例。其流程适用于任何 CI 系统:构建、上传、在服务器上运行脚本,然后清除 CDN。

YAML
name: Deploy

on:
  push:
    branches: [main]

concurrency:
  group: deploy-production
  cancel-in-progress: false

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/checkout@v4

      - uses: shivammathur/setup-php@v2
        with:
          php-version: "8.2"
          tools: composer:v2

      - name: Install production dependencies
        run: composer install --no-dev --optimize-autoloader --no-interaction --prefer-dist

      - name: Configure SSH
        run: |
          mkdir -p ~/.ssh
          echo "${{ secrets.DEPLOY_KEY }}" > ~/.ssh/id_ed25519
          chmod 600 ~/.ssh/id_ed25519
          ssh-keyscan example.com >> ~/.ssh/known_hosts

      - name: Upload the theme
        run: |
          rsync -az --delete --exclude ".git" --exclude ".github" \
            ./ deploy@example.com:/var/www/example.com/wp-content/themes/acme/

      - name: Sync pages and refresh the static cache
        run: ssh deploy@example.com 'bash -s' < scripts/post-deploy.sh

      - name: Purge the CDN
        run: curl -fsS -X POST "${{ secrets.CDN_PURGE_URL }}"

concurrency 配合 cancel-in-progress: false 使用时,会将第二次推送排在正在运行的部署之后,而不是在同步中途取消它。PHP 8.2 是 Blockstudio 的最低版本要求。将最后一步替换为你的 CDN 清除 API 的操作。

维护命令

这些命令不属于每次发布流程,但部署手册应介绍它们。

清理旧锁积压。 7.6.14 之前的版本会在每次内容更改时留下一个 .build.lock 文件。升级后,WP-Cron 会分批删除这些文件。检查积压并一次性清理:

命令行
wp bs cache status
wp bs cache cleanup
Text
0 legacy build lock(s) across 0 cache namespace(s).
Next cleanup batch in 0 second(s).

cleanup 会将创建时间不到一小时的锁,以及仍由正在运行的请求持有的锁,留到下次执行处理。网站正在提供服务时,切勿手动删除锁文件。

清除运行时缓存。 wp bs cache clear 会清除当前站点的所有缓存,wp bs cache clear --scope=runtime 会清除所有命名空间中某个作用域的缓存。下一个请求会从空缓存开始重建,因此应在流量较低时运行,并且只在确有需要时运行:输入发生变化时,缓存键已经会自动轮换。

移除 Blockstudio。 Composer 安装没有插件停用钩子,因此包消失时,不会取消 cron 事件的计划,也不会移除提前提供服务的 drop-in 文件。移除依赖项之前,请运行此命令:

命令行
wp bs teardown

它会移除本安装所拥有的 cron 事件和静态预渲染状态,保留其他组件的 drop-in 文件和配置文件不变,并确保之后重新启用时从干净状态开始。

后续步骤