Към съдържанието

Преместване на съдържание от базата данни във файлове със синхронизиране на съдържание

Блоковете, шаблоните и страниците от файлове вече се намират във вашето хранилище. Част от съдържанието не се вписва в този модел, защото редакторите го създават в административния панел: членове на екипа, офиси, казуси. Това съдържание също е важно за проекта. Сайта за тестване му е нужна същата страница за екипа като на продукционния сайт, нов разработчик има нужда от реалистични данни, а проверяващият трябва да вижда кога някой променя длъжност. Дъмповете на базата данни не решават добре нито една от тези задачи. Те съдържат всичко, ID се различават между средите и никой не преглежда разлика SQL.

Content Sync запълва тази празнина. Една команда WP-CLI проектира списък с разрешени публикации, термини, връзки и метаданни във файлове JSON и HTML в темата ви. Друга команда прилага тези файлове към друга база данни. Всяка единица получава преносим UID, а препратките между единиците се пренаписват само когато изрично го зададете.

Това ръководство проследява директория с екип: извличането ѝ във файлове, прегледа им, редактирането на файл, прехвърлянето ѝ в нова среда и безопасното почистване.

Примерът

Темата регистрира тип публикация acme_member и таксономия acme_team във всяка среда. Всяка публикация за член може да съдържа:

Мета ключ Съдържание
_acme_role Длъжността, обикновен низ
_acme_mentor ID на публикацията на друг член
_thumbnail_id ID на прикачения портрет
_acme_api_token Токен за интеграция, който никога не бива да попада в git

Content Sync никога не регистрира типове публикации или таксономии. Те трябва да съществуват навсякъде, където изпращате данни.

Стъпка 1: Конфигуриране на Content Sync

Content Sync е изключен, докато не го активирате в blockstudio.json. Дотогава всяка команда връща един ред skipped:

Обвивка
wp bs content status
Код
action   entity   id       uid  message
skipped  content  default       Content Sync is disabled. Set content.enabled to true to run this command.

Добавете група content:

JSON
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "content": {
    "enabled": true,
    "id": "team",
    "path": "content",
    "postTypes": ["acme_member"],
    "taxonomies": ["acme_team"],
    "meta": {
      "include": ["_acme_*", "_thumbnail_id"],
      "references": {
        "_acme_mentor": { "kind": "post" },
        "_thumbnail_id": { "kind": "attachment" }
      }
    },
    "media": "manifest"
  }
}

Всеки ключ задава граница:

  • postTypes и taxonomies са списъци с разрешени елементи. Нищо извън тях не се чете, записва или премахва. Празен postTypes означава, че публикациите не се засягат.
  • meta.include задава разрешените мета ключове, като поддържа заместващи знаци *. meta.exclude винаги има предимство, а _edit_lock, _edit_last и _wp_old_slug са изключени по подразбиране.
  • meta.references указва кои мета стойности са ID. Content Sync никога не предполага, че цяло число е ID.
  • id задава името на набора от съдържание. То се съхранява във всяка синхронизирана единица, а почистването засяга само единици от същия набор.
  • path е изходната папка спрямо директорията на активната тема.

Стъпка 2: Извличане

Първо прегледайте проекцията. Нищо не се записва, а показаните UID все още не са съхранени:

Обвивка
wp bs content pull --dry-run
Код
action       entity  id   uid          message
would-write  post    530  4c8e9997-...  .../posts/acme_member/jane.4c8e9997.json
would-write  post    531  6cddc303-...  .../posts/acme_member/sam.6cddc303.json
would-write  term    4    6661b6d9-...  .../terms/acme_team/leadership.6661b6d9.json

След това извлечете данните наистина. Това присвоява постоянен _blockstudio_content_uid на всяка единица, която все още няма такъв, и записва файловете:

Обвивка
wp bs content pull
Код
action   entity  id        uid          message
written  post    530       5d4bf9b5-...  .../posts/acme_member/jane.5d4bf9b5.json
written  post    531       208db72e-...  .../posts/acme_member/sam.208db72e.json
written  term    4         7491a6a1-...  .../terms/acme_team/leadership.7491a6a1.json
written  media   manifest                .../media/manifest.json

Резултатът в темата:

Код
content/
├── media/
│   └── manifest.json
├── posts/
│   └── acme_member/
│       ├── jane.5d4bf9b5.html
│       ├── jane.5d4bf9b5.json
│       └── sam.208db72e.json
└── terms/
    └── acme_team/
        └── leadership.7491a6a1.json

Имената на файловете съчетават slug с началната част на UID. Публикацията JSON съдържа полетата, връзките с термини и разрешените метаданни:

JSON
{
    "uid": "5d4bf9b5-16b7-4975-acc6-51dc1d4e49ec",
    "type": "acme_member",
    "status": "publish",
    "slug": "jane",
    "title": "Jane Doe",
    "date": "2026-10-13T03:03:02+00:00",
    "modified": "2026-10-13T03:03:02+00:00",
    "parent": null,
    "menuOrder": 0,
    "terms": {
        "acme_team": [
            "7491a6a1-702c-4a29-9993-9ae7b2a79c0a"
        ]
    },
    "meta": {
        "_acme_role": "Design Lead",
        "_thumbnail_id": "72a2db75-6fd2-41f9-8d3c-b323ce3b3551"
    },
    "metaEncoding": {
        "_acme_role": "scalar",
        "_thumbnail_id": "scalar"
    }
}

Връзката с термина и миниатюрата са UID, а не локални ID. Тялото на публикацията се намира до тях във jane.5d4bf9b5.html като необработен блоков код. Публикация с празно съдържание, като тази на Сам, няма файл .html. _acme_mentor на Сам се съхранява като UID на Джейн, защото ключът е зададен като препратка post.

Стъпка 3: Преглед преди ангажиране

Изпълнете status преди ангажиране. Командата сравнява файловете и базата данни и също така открива рискови данни:

Обвивка
wp bs content status
Код
action     entity  id               uid          message
unchanged  post    530              5d4bf9b5-...  .../posts/acme_member/jane.5d4bf9b5.json
unchanged  post    531              208db72e-...  .../posts/acme_member/sam.208db72e.json
unchanged  term    4                7491a6a1-...  .../terms/acme_team/leadership.7491a6a1.json
warning    meta    _acme_api_token                Allowlisted meta key may contain secrets or PII; review before committing synced files.

Заместващият знак _acme_* засече токена. Считайте meta.include за граница при ангажиране и изключете ключа изрично:

JSON
"meta": {
  "include": ["_acme_*", "_thumbnail_id"],
  "exclude": ["_acme_api_token"],
  "references": {
    "_acme_mentor": { "kind": "post" },
    "_thumbnail_id": { "kind": "attachment" }
  }
}

Следващото pull пренаписва sam.208db72e.json без токена и оставя останалите файлове непроменени. status предупреждава и за цифрови ID в телата на блоковия код, защото Content Sync не пренаписва ID във файлове .html.

Ангажирайте папката content/.

Стъпка 4: Редактиране на файл и изпращане

Файловете са източникът на истина за push. Променете ролята на Джейн във файла JSON от Design Lead на Head of Design, след което проверете какво би станало:

Обвивка
wp bs content status
Код
action        entity  id   uid          message
would-update  post    530  5d4bf9b5-...  .../posts/acme_member/jane.5d4bf9b5.json
unchanged     post    531  208db72e-...  .../posts/acme_member/sam.208db72e.json
unchanged     term    4    7491a6a1-...  .../terms/acme_team/leadership.7491a6a1.json

push --dry-run показва същия план в реда за изпращане. Приложете го:

Обвивка
wp bs content push
Код
action     entity  id   uid          message
unchanged  term    4    7491a6a1-...  .../terms/acme_team/leadership.7491a6a1.json
updated    post    530  5d4bf9b5-...  .../posts/acme_member/jane.5d4bf9b5.json
unchanged  post    531  208db72e-...  .../posts/acme_member/sam.208db72e.json

Преди запис изпращането валидира целия план. Неразрешени зададени препратки, конфликти в slug, липсващи типове публикации и невалидни файлове спират операцията.

WordPress задава нов час на промяна за обновена публикация, докато файлът все още съдържа старата стойност modified. Затова изпълнение на status веднага след това изпращане отчита публикацията на Джейн като conflict със съобщение „Базата данни е променена след последната синхронизация.“ Изпълнете pull веднъж след изпращането, за да запишете новия час; тогава status отчита unchanged.

Стъпка 5: Преместване на съдържанието в друга среда

В нова среда файловете описват публикации, които все още не съществуват. В този пример терминът и прикаченият портрет вече съществуват там със същите UID, така че липсват само двамата членове:

Обвивка
wp bs content status
Код
action      entity  id    uid          message
missing-db  post    jane  5d4bf9b5-...  .../posts/acme_member/jane.5d4bf9b5.json
missing-db  post    sam   208db72e-...  .../posts/acme_member/sam.208db72e.json
unchanged   term    4     7491a6a1-...  .../terms/acme_team/leadership.7491a6a1.json
Обвивка
wp bs content push
Код
action     entity  id   uid          message
unchanged  term    4    7491a6a1-...  .../terms/acme_team/leadership.7491a6a1.json
created    post    536  5d4bf9b5-...  .../posts/acme_member/jane.5d4bf9b5.json
created    post    537  208db72e-...  .../posts/acme_member/sam.208db72e.json

Публикациите получиха нови локални ID: 536 и 537. Препратките се актуализираха: _acme_mentor на Сам сега съдържа 536, Джейн отново е в термина leadership, а нейният _thumbnail_id сочи към локалния прикачен файл със съответстващ UID. Родителските публикации, родителските термини и връзките с термини винаги се съхраняват като UID; мета стойностите се пренаписват само за ключовете в meta.references.

Безопасно почистване

Изтриването на файл не изтрива нищо при изпращане, освен ако не поискате това. Премахнете sam.208db72e.json и опитайте почистване:

Обвивка
wp bs content push --prune
Код
Error: Refusing to prune without --yes. Re-run with --dry-run to inspect the plan or --yes to confirm.

Пробното изпълнение показва какво би било премахнато:

Обвивка
wp bs content push --prune --dry-run
Код
action             entity  id   uid          message
...
would-prune-trash  post    537  208db72e-...

След това push --prune --yes премества публикацията на Сам в кошчето и отчита pruned-trash. Няколко защити ограничават обхвата:

  • Само единиците, притежавани от този набор съдържание (content.id), са кандидати.
  • Разглеждат се само конфигурираните типове публикации и таксономии.
  • Целият план от източника се анализира и валидира, преди нещо да бъде записано или премахнато. Ако в папката има невалиден файл JSON, изпращането отчита ред error, например could not be read: Syntax error, и не премахва нищо.

Действието по подразбиране е trash. Филтърът blockstudio/content/orphan_action може да върне trash, delete или keep за всяка единица. Така термините се запазват, докато публикациите остават с действието по подразбиране:

PHP
add_filter(
	'blockstudio/content/orphan_action',
	function ( string $action, string $type ) {
		return 'term' === $type ? 'keep' : $action;
	},
	10,
	2
);

С него осиротял термин се отчита като would-prune-keep вместо като would-prune-trash.

Медийни файлове

Медийните файлове никога не се копират. content.media определя какво става с зададените препратки към прикачени файлове:

  • "manifest" (по подразбиране) съхранява UID на прикачените файлове и ги изброява в content/media/manifest.json с път, тип MIME и алтернативен текст. Изпращането изисква всеки посочен UID на прикачен файл да съществува в целевата среда, затова първо преместете качените файлове по обичайния си начин за работа с медийни файлове.
  • "none" не включва зададените препратки към прикачени файлове във файловете. JSON на Джейн тогава съдържа само _acme_role. Тъй като пропуснат ключ не се прилага при изпращане, съществуващата миниатюра на целевата публикация се запазва.

Заключване на единица

Понякога в целевата среда трябва да се запази собствената версия на дадена публикация. Задайте метаданните _blockstudio_content_locked на тази публикация на истинна стойност и изпращането ще я пропусне с ред locked и съобщението „Пропусната е заключена единица.“ Изтрийте метаданните, за да я включите отново.

Правила за собственост

  • Публикациите, управлявани от страници, базирани на файлове, са изключени по подразбиране. С includePageSyncManaged: true Content Sync може да синхронизира конфигурираните им метаданни, но Page Sync продължава да управлява тяхното post_content. Тези проекции на JSON съдържат bodyOwner: "page-sync", а pull изрично посочва пропуснатото съдържание. Съществуващите копия за преглед на .html се запазват и се игнорират при push. Синхронизирайте страниците в целевата среда, преди да изпратите проекциите на метаданните им.
  • Авторите се игнорират по подразбиране, защото потребителите не се синхронизират. С authors: "login" файловете на публикациите съхраняват потребителското име на автора и push го свързва със съществуващ потребител; липсващ потребител е грешка при предварителната проверка.
  • pull никога не изтрива файлове. Когато даден обект в базата данни вече не съществува, pull посочва файла като остарял и оставя почистването на вас.

Кога да не го използвате

Content Sync е подходящ за подбрано съдържание, което се променя рядко: десетки или стотици записи, до няколко хиляди, когато данните са структурирани и разделени в специализирани типове публикации. Не е заместител на резервни копия или миграции на бази данни. Поръчки, изпращания на формуляри, регистрационни файлове, анализи и редакционно съдържание с голям обем принадлежат в съответните инструменти. Дефинициите на таксономии, двоичните медийни файлове и ID във вътрешността на блоковия код са извън обхвата му.

Следващи стъпки