内容同步
Blockstudio 以文件优先工作流为核心:区块、字段、模板、资源、样式模式和基于文件的页面都可以存放在你的项目中。内容同步将这一模式扩展到选定的 WordPress 数据库内容,让团队也能在 git 中管理经过整理的文章、分类项、关联关系和声明的元数据。
它是一种 WP-CLI 工作流,不是实时数据库复制。拉取时,内容同步会将允许列表中的文章、文章元数据、分类项、分类元数据和文章与分类项的关联关系投影到主题中的可移植文件。推送时,它会使用稳定的 UID 将这些文件应用到另一个环境,并且只重写你明确声明的引用。
注意
内容同步按需运行,不会在每次管理请求时执行。在
true之前,命令会返回一条已跳过的行,直到content.enabled。
何时使用内容同步
对于需要进行版本控制、审核并在不同环境间迁移的内容集,请使用内容同步:
- 团队成员、地点、案例研究、产品、文档条目或营销活动页面等结构化内容
- 与这些内容集关联的分类法和关联关系
- 可安全提交且需要稳定引用的允许列表元数据
- 小型到中型内容集;在 git 中审核文件仍然切实可行
一般来说,内容同步适合几十到几百行数据;如果数据结构化、变更较少,并拆分到多个专用文章类型中,也能处理几千行。它不适合镜像整个生产数据库、高流量编辑内容、日志、订单、分析数据、表单提交、会话或其他高容量、高频变更的数据。如果生成的文件难以审核、推送计划耗时过长且难以理清,或者大多数行都在部署工作流之外发生变化,请改用数据库备份、迁移或导入/导出工具。
媒体二进制文件不会被复制。附件引用可以记录在 清单中并进行验证,但文件本身必须已存在于目标 环境中。
配置
在 blockstudio.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 中列出该文件。
{
"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 中配置的引用才会被重写。
{
"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" 时,声明的附件引用会从可移植文件中省略。由于推送时不会应用被省略的键,目标文章会保留其现有附件元数据。
可移植性工作流程
- 在每个环境中注册目标文章类型。
- 配置
content.postTypes、meta.include和任何已声明的引用。 - 在源环境中运行
wp bs content pull。 - 提交生成的文件。
- 在目标环境中运行
wp bs content push。 - 运行
wp bs content status,验证数据库与文件一致。
对于 push,文件是事实来源。使用 pull 可将数据库内容重新捕获到文件中。
范围
内容同步支持:
- 来自允许列表中文章类型的文章
- 允许列表中的文章元数据
- 来自允许列表中已注册分类法的术语
- 允许列表中的术语元数据
- 文章与术语的关系
- 已声明的
post、attachment和term引用 - 可移植的文章和术语 UID 及内容集归属
- 默认排除页面同步
- 附件清单和预检验证
pull、push、status、--dry-run、--prune以及锁定实体处理
不支持捕获分类法定义、复制媒体二进制文件以及重写区块标记中的 ID。