跳转到正文

内容同步

Blockstudio 以文件优先工作流为核心:区块、字段、模板、资源、样式模式和基于文件的页面都可以存放在你的项目中。内容同步将这一模式扩展到选定的 WordPress 数据库内容,让团队也能在 git 中管理经过整理的文章、分类项、关联关系和声明的元数据。

它是一种 WP-CLI 工作流,不是实时数据库复制。拉取时,内容同步会将允许列表中的文章、文章元数据、分类项、分类元数据和文章与分类项的关联关系投影到主题中的可移植文件。推送时,它会使用稳定的 UID 将这些文件应用到另一个环境,并且只重写你明确声明的引用。

注意

内容同步按需运行,不会在每次管理请求时执行。在 true 之前,命令会返回一条已跳过的行,直到 content.enabled。

何时使用内容同步

对于需要进行版本控制、审核并在不同环境间迁移的内容集,请使用内容同步:

  • 团队成员、地点、案例研究、产品、文档条目或营销活动页面等结构化内容
  • 与这些内容集关联的分类法和关联关系
  • 可安全提交且需要稳定引用的允许列表元数据
  • 小型到中型内容集;在 git 中审核文件仍然切实可行

一般来说,内容同步适合几十到几百行数据;如果数据结构化、变更较少,并拆分到多个专用文章类型中,也能处理几千行。它不适合镜像整个生产数据库、高流量编辑内容、日志、订单、分析数据、表单提交、会话或其他高容量、高频变更的数据。如果生成的文件难以审核、推送计划耗时过长且难以理清,或者大多数行都在部署工作流之外发生变化,请改用数据库备份、迁移或导入/导出工具。

媒体二进制文件不会被复制。附件引用可以记录在 清单中并进行验证,但文件本身必须已存在于目标 环境中。

配置

在 blockstudio.json 中启用内容同步:

JSON
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "content": {
    "enabled": true,
    "id": "default",
    "path": "content",
    "includePageSyncManaged": false,
    "authors": "ignore",
    "postTypes": ["team_member"],
    "meta": {
      "include": ["_my_*"],
      "exclude": ["_edit_lock", "_edit_last", "_wp_old_slug"],
      "references": {
        "_thumbnail_id": { "kind": "attachment" },
        "_related_posts": { "kind": "post", "path": "*" },
        "_hero": { "kind": "attachment", "path": "image.id" }
      }
    },
    "taxonomies": [],
    "media": "manifest"
  }
}

postTypes 是一个允许列表。留空表示内容同步不会处理文章。taxonomies 是已注册分类法的允许列表,其分类项和文章关联关系应进行同步。Blockstudio 不会从内容同步文件中注册分类法定义。文章元数据和分类元数据通过 meta.include 加入允许列表;meta.exclude 始终优先。

警告

请将 meta.include 视为提交边界。同步文件应存放在 git 中,因此不要包含存有机密、令牌、凭据或个人身份信息的键。若允许列表中的元数据键看起来包含敏感信息,wp bs content status 会报告警告行。

content.id 会作为 _blockstudio_content_set 存储在已同步实体中。清理和所有权检查都限定于该值,因此一个内容集无法删除另一个内容集的内容。

默认情况下,页面同步管理的文章会被排除。如果启用了 includePageSyncManaged,内容同步可以同步这些文章中已配置的元数据,但页面同步仍负责管理它们的 post_content。

这些投影包含 "bodyOwner": "page-sync"。Pull 会将 JSON 写入报告为仅含元数据,并添加一行 skipped 正文记录,而不会将文章呈现为正文为空。它不会写入或删除同级 .html 文件。现有的审核副本会保留,并在 push 时忽略。试运行输出中也会包含相同的所有权消息。

在另一个环境中,先运行 Page Sync。带有 bodyOwner: "page-sync" 的投影必须引用现有的 Page Sync 管理文章;push 会拒绝创建空的替代项,也不会应用该文章正文的审核副本。较早版本中不带此标记的投影仍受支持。

默认情况下会忽略作者,因为用户不会同步。设置 authors: "login" 可将作者的登录名存储在文章文件中,并在推送时将该登录名解析为现有用户。缺少用户会导致预检错误;内容同步不会创建用户。

命令

命令行
wp bs content pull [--post-type=<type>] [--taxonomy=<taxonomy>] [--dry-run]
wp bs content push [--dry-run] [--prune] [--yes]
wp bs content status

pull 会将数据库内容捕获到文件中。对于尚无 _blockstudio_content_uid 的范围内文章,它会为其分配该值,并报告数据库源已不存在的过时文件。拉取不会删除过时文件。

push 会将文件应用到当前数据库。它会在写入前验证计划,并阻止存在未解决的声明引用、别名冲突、锁定实体或缺少文章类型的操作。

status 会比较文件与数据库,并将每个实体报告为 unchanged、would-update、missing-db、conflict、locked 或 orphaned。它还会在提交前警告看起来像机密的允许列表元数据键;如果区块标记主体中含有数字 ID,也会发出警告,因为内容同步不会重写 .html 文件中的 ID。

使用 --dry-run 检查拉取或推送操作而不写入数据。使用 push --prune --yes 删除文件中已不存在、但由内容集拥有的数据库实体。

故障安全

push 会在写入或 清理前解析并验证完整的源计划。格式错误的 JSON、未解决的声明引用、无效的所有权信息以及 其他预检失败,都会阻止破坏性阶段。清理范围仍限于配置的文章类型、分类法和 content.id。

pull 会先写入每个投影文件,然后才将对应实体记录为已同步。文件系统写入失败时,会返回一条错误行,且不会推进该实体的已存储同步状态。

附件处理遵循 content.media。使用 "manifest" 时,引用的附件 UID 必须存在于目标环境中。使用 "none" 时,声明的附件引用会从可移植输出中有意移除,而不是保留特定于环境的 ID。

文件

内容同步会将文件写入已配置的 content.path:

代码
content/
  posts/
    team_member/
      jane.9b1c0e6e.json
      jane.9b1c0e6e.html
  terms/
    category/
      leadership.5e900000.json
  media/
    manifest.json

文章 .json 文件存储身份信息、文章字段、术语关系、声明的元数据和元数据编码。同级的 .html 文件以原始区块标记形式存储 post_content;内容为空时会省略该文件。术语 .json 文件存储身份信息、分类法、别名、名称、描述、父级 UID、声明的术语元数据和元数据编码。

另一种情况是没有 .html 文件的正文,这是由上文的 bodyOwner 标识的 Page Sync 所有正文。对于正文变为空的普通文章,pull 会移除旧正文文件,并在单独的正文行 deleted 中列出该文件。

JSON
{
  "uid": "9b1c0e6e-0000-4000-9000-000000000000",
  "type": "team_member",
  "status": "publish",
  "slug": "jane",
  "title": "Jane",
  "parent": null,
  "menuOrder": 0,
  "terms": {
    "category": ["5e900000-0000-4000-9000-000000000000"]
  },
  "meta": {
    "_my_subtitle": "Creative Director",
    "_thumbnail_id": "a1b2c3d4-0000-4000-9000-000000000000"
  },
  "metaEncoding": {
    "_my_subtitle": "scalar",
    "_thumbnail_id": "scalar"
  }
}

存储的同步状态如下:

元数据键 用途
_blockstudio_content_uid 可移植内容身份
_blockstudio_content_set 来自 content.id 的内容集命名空间
_blockstudio_content_source 相对于主题的源文件路径
_blockstudio_content_fingerprint 最近一次同步的文件/数据库指纹
_blockstudio_content_locked 真值可防止推送覆盖该实体

引用

内容同步绝不会猜测整数是 ID。只有在 meta.references 中配置的引用才会被重写。

JSON
{
  "meta": {
    "references": {
      "_related_posts": { "kind": "post", "path": "*" },
      "_topic": { "kind": "term" },
      "_hero": { "kind": "attachment", "path": "image.id" }
    }
  }
}

拉取时,这些路径中的本地 ID 会变为可移植 UID。推送时,UID 会解析为当前数据库中的本地 ID。

文章父级、术语父级和文章-术语关系是由内容同步管理的结构化引用,并会自动以 UID 存储。即使配置的分类法为空,也会写入文章文件;推送时,空数组会清除该分类法的关系。

附件引用会经过验证,但不会导入。使用 media: "manifest" 时,引用的附件会列在 content/media/manifest.json 中;推送要求引用的附件 UID 在本地存在。使用 media: "none" 时,声明的附件引用会从可移植文件中省略。由于推送时不会应用被省略的键,目标文章会保留其现有附件元数据。

可移植性工作流程

  1. 在每个环境中注册目标文章类型。
  2. 配置 content.postTypes、meta.include 和任何已声明的引用。
  3. 在源环境中运行 wp bs content pull。
  4. 提交生成的文件。
  5. 在目标环境中运行 wp bs content push。
  6. 运行 wp bs content status,验证数据库与文件一致。

对于 push,文件是事实来源。使用 pull 可将数据库内容重新捕获到文件中。

范围

内容同步支持:

  • 来自允许列表中文章类型的文章
  • 允许列表中的文章元数据
  • 来自允许列表中已注册分类法的术语
  • 允许列表中的术语元数据
  • 文章与术语的关系
  • 已声明的 post、attachment 和 term 引用
  • 可移植的文章和术语 UID 及内容集归属
  • 默认排除页面同步
  • 附件清单和预检验证
  • pull、push、status、--dry-run、--prune 以及锁定实体处理

不支持捕获分类法定义、复制媒体二进制文件以及重写区块标记中的 ID。