Pāriet uz saturu

Pārvietojiet datubāzes saturu failos, izmantojot satura sinhronizāciju

Bloki, veidnes un no failiem veidotas lapas jau atrodas jūsu repozitorijā. Daļa satura šim modelim neatbilst, jo redaktori to izveido administrēšanas panelī: komandas biedrus, biroju atrašanās vietas un gadījumu izpētes. Arī šis saturs ir svarīgs projektam. Izstrādes vietnei vajadzīga tā pati komandas lapa, kas produkcijas vietnei; jaunam izstrādātājam vajadzīgi reālistiski dati, un pārskatītājam būtu jāredz, ja kāds maina amata nosaukumu. Datubāzes izdrukas nevienu no šīm problēmām neatrisina. Tās ietver visu, ID dažādās vidēs atšķiras, un neviens nepārskata SQL diff.

Content Sync novērš šo trūkumu. WP-CLI komanda projicē atļauto ziņu, terminu, attiecību un metadatu sarakstu JSON un HTML failos jūsu tēmā. Cita komanda piemēro šos failus citai datubāzei. Katrai entītijai tiek piešķirts pārnesams UID, un atsauces starp entītijām tiek pārrakstītas tikai tad, ja jūs tās deklarējat.

Šajā ceļvedī apskatīts komandas direktorijs: tā izgūšana failos, pārskatīšana, faila rediģēšana, pārvietošana uz jaunu vidi un droša tīrīšana.

Piemērs

Tēma katrā vidē reģistrē acme_member ziņu tipu un acme_team taksonomiju. Katras dalībnieka ziņas metadatos var būt:

Meta atslēga Saturs
_acme_role Amata nosaukums — vienkārša virkne
_acme_mentor Cita dalībnieka ziņas ID
_thumbnail_id Portreta pielikuma ID
_acme_api_token Integrācijas tokens, kas nekad nedrīkst nonākt git repozitorijā

Content Sync nereģistrē ziņu tipus vai taksonomijas. Tiem jābūt pieejamiem visur, kur veicat datu nosūtīšanu.

1. darbība: konfigurējiet Content Sync

Content Sync pēc noklusējuma ir izslēgts. Iespējojiet to sadaļā blockstudio.json. Līdz tam katra komanda atgriež vienu skipped rindu:

Apvalks
wp bs content status
Kods
action   entity   id       uid  message
skipped  content  default       Content Sync is disabled. Set content.enabled to true to run this command.

Pievienojiet content grupu:

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"
  }
}

Katra atslēga nosaka robežu:

  • postTypes un taxonomies ir atļauto vērtību saraksti. Nekas ārpus tiem netiek lasīts, rakstīts vai dzēsts. Tukšs postTypes nozīmē, ka ziņas netiek skartas.
  • meta.include nosaka atļautās meta atslēgas, izmantojot * aizstājējzīmes. meta.exclude vienmēr ir prioritāte, savukārt _edit_lock, _edit_last un _wp_old_slug pēc noklusējuma ir izslēgtas.
  • meta.references norāda, kuras meta vērtības ir ID. Content Sync nemēģina uzminēt, vai vesels skaitlis ir ID.
  • id nosauc satura kopu. Tā tiek saglabāta katrā sinhronizētajā entītijā, un dzēšana skar tikai tās pašas kopas entītijas.
  • path ir izvades mape attiecībā pret aktīvo tēmas direktoriju.

2. darbība: izgūšana

Vispirms priekšskatiet projekciju. Nekas netiek ierakstīts, un parādītie UID vēl netiek saglabāti:

Apvalks
wp bs content pull --dry-run
Kods
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

Pēc tam veiciet izgūšanu. Katrai entītijai bez UID tiek piešķirts pastāvīgs _blockstudio_content_uid, un tiek ierakstīti faili:

Apvalks
wp bs content pull
Kods
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

Rezultāts tēmā:

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

Failu nosaukumos apvienots slug ar UID sākuma daļu. Ziņas JSON satur laukus, terminu attiecības un atļautos metadatus:

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"
    }
}

Termina attiecība un sīktēls ir UID, nevis lokāli ID. Ziņas pamatteksts atrodas blakus tam mapē jane.5d4bf9b5.html kā neapstrādāts bloku marķējums. Ziņai bez satura, piemēram, Semas ziņai, nav .html faila. Semas _acme_mentor ir saglabāts kā Džeinas UID, jo atslēga ir deklarēta kā post atsauce.

3. darbība: pārskatiet pirms iesniegšanas

Pirms iesniegšanas palaidiet status. Tas salīdzina failus ar datubāzi un arī atzīmē riskantus datus:

Apvalks
wp bs content status
Kods
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_* aizstājējzīme atrada tokenu. Uztveriet meta.include kā iesniegšanas robežu un skaidri izslēdziet šo atslēgu:

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

Nākamais pull pārraksta sam.208db72e.json bez tokena, pārējos failus neaizskarot. status arī brīdina par skaitliskiem ID bloku marķējuma pamattekstā, jo Content Sync nepārraksta ID .html failos.

Iesniedziet mapi content/.

4. darbība: rediģējiet failu un nosūtiet izmaiņas

Faili ir push patiesais avots. Mainiet Džeinas lomu failā JSON no Design Lead uz Head of Design, pēc tam pārbaudiet, kas notiktu:

Apvalks
wp bs content status
Kods
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 izvada to pašu plānu nosūtīšanas secībā. Piemērojiet to:

Apvalks
wp bs content push
Kods
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

Pirms rakstīšanas Push validē visu plānu. Neatrisinātas deklarētās atsauces, slug konflikti, trūkstoši ziņu tipi un nepareizi noformēti faili aptur procesu.

WordPress atjauninātai ziņai piešķir jaunu modificēšanas laiku, kamēr failā joprojām ir vecā modified vērtība. Tāpēc, palaižot status uzreiz pēc šīs nosūtīšanas, Džeinas ziņa tiek uzrādīta kā conflict ar paziņojumu “Database changed since last sync.” Pēc nosūtīšanas vienreiz palaidiet pull, lai reģistrētu jauno laiku; tad status uzrādīs unchanged.

5. darbība: pārvietojiet saturu uz citu vidi

Jaunā vidē faili apraksta ziņas, kas vēl nepastāv. Šajā piemērā termins un portreta pielikums tur jau ir ar tiem pašiem UID, tāpēc trūkst tikai abu dalībnieku ziņu:

Apvalks
wp bs content status
Kods
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
Apvalks
wp bs content push
Kods
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

Ziņām tika piešķirti jauni lokālie ID — 536 un 537. Arī atsauces tika pārnestas: Semas _acme_mentor tagad satur 536, Džeina atkal ir terminā leadership, un viņas _thumbnail_id norāda uz lokālo pielikumu ar atbilstošo UID. Ziņu vecāki, terminu vecāki un terminu attiecības vienmēr tiek saglabātas kā UID; meta vērtības tiek pārrakstītas tikai atslēgām, kas norādītas meta.references.

Droša dzēšana

Faila dzēšana pati par sevi neko nedzēš, veicot nosūtīšanu. Lai to izdarītu, tas ir jānorāda. Noņemiet sam.208db72e.json un izmēģiniet dzēšanu:

Apvalks
wp bs content push --prune
Kods
Error: Refusing to prune without --yes. Re-run with --dry-run to inspect the plan or --yes to confirm.

Sausajā izpildē redzams, kas tiktu dzēsts:

Apvalks
wp bs content push --prune --dry-run
Kods
action             entity  id   uid          message
...
would-prune-trash  post    537  208db72e-...

push --prune --yes pēc tam pārvieto Semas ziņu uz atkritni un uzrāda pruned-trash. Šo darbību ierobežo vairāki drošības nosacījumi:

  • Kandidāti ir tikai entītijas, kas pieder šai satura kopai (content.id).
  • Tiek ņemti vērā tikai konfigurētie ziņu tipi un taksonomijas.
  • Pirms jebkādas rakstīšanas vai dzēšanas viss avota plāns tiek parsēts un validēts. Ja mapē ir nepareizi noformēts JSON fails, push uzrāda error rindu, piemēram, could not be read: Syntax error, un neko nedzēš.

Noklusējuma darbība ir trash. Filtrs blockstudio/content/orphan_action katrai entītijai var atgriezt trash, delete vai keep. Tādējādi termini tiek paturēti, bet ziņām paliek noklusējuma darbība:

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

Ar šo iestatījumu neaizsargāts termins tiek uzrādīts kā would-prune-keep, nevis would-prune-trash.

Multivide

Multivides faili nekad netiek kopēti. content.media nosaka, kas notiek ar deklarētajām pielikumu atsaucēm:

  • "manifest" (noklusējums) saglabā pielikumu UID un uzskaita tos content/media/manifest.json kopā ar ceļu, MIME tipu un alternatīvo tekstu. Push pieprasa, lai katrs atsauces pielikuma UID būtu pieejams mērķa vidē, tāpēc vispirms pārvietojiet augšupielādētos failus ar ierasto multivides darbplūsmu.
  • "none" neiekļauj deklarētās pielikumu atsauces failos. Džeinas JSON tad satur tikai _acme_role. Tā kā izlaista atslēga push laikā netiek piemērota, esošā mērķa ziņa saglabā pašreizējo sīktēlu.

Entītijas bloķēšana

Dažkārt mērķa vidē ir jāsaglabā sava konkrētās ziņas versija. Iestatiet šīs ziņas _blockstudio_content_locked meta vērtību kā patiesu vērtību, un push to izlaidīs, uzrādot locked rindu un paziņojumu “Locked entity skipped.” Izdzēsiet šo meta vērtību, lai ziņu atkal iekļautu.

Īpašumtiesību noteikumi

  • Pēc noklusējuma tiek izslēgtas ziņas, ko pārvalda ar failos balstītas lapas. Izmantojot includePageSyncManaged: true, Content Sync var sinhronizēt to konfigurētos metadatus, taču Page Sync joprojām pārvalda to post_content. Šīs JSON projekcijas ietver bodyOwner: "page-sync", un izvilkšanas darbība skaidri norāda, ka pamatteksts ir izlaists. Esošās .html pārskatīšanas kopijas tiek saglabātas un ignorētas, veicot nosūtīšanu. Pirms metadatu projekciju nosūtīšanas sinhronizējiet lapas mērķa vidē.
  • Pēc noklusējuma autori tiek ignorēti, jo lietotāji netiek sinhronizēti. Izmantojot authors: "login", ziņu failos tiek saglabāts autora pieteikšanās vārds, un nosūtīšana to piesaista esošam lietotājam; ja lietotājs nav atrasts, pirmsdarbības pārbaude ziņo par kļūdu.
  • pull nekad nedzēš failus. Ja datubāzē entītija vairs nepastāv, izvilkšana ziņo par tās failu kā novecojušu un atstāj tīrīšanu jūsu ziņā.

Kad to neizmantot

Content Sync ir piemērots atlasītam saturam, kas mainās reti: desmitiem vai simtiem ierakstu, līdz dažiem tūkstošiem, ja dati ir strukturēti un sadalīti atsevišķos ziņu tipos. Tas neaizstāj datubāzes dublējumkopijas vai migrācijas. Pasūtījumiem, veidlapu iesniegumiem, žurnāliem, analītikai un lielam redakcionālā satura apjomam jāizmanto attiecīgie rīki. Taksonomiju definīcijas, multivides binārie faili un ID bloku marķējumā ir ārpus tā darbības jomas.

Nākamie soļi