Siirry sisältöön

Tietokantasisällön siirtäminen tiedostoihin sisällön synkronoinnilla

Lohkot, mallit ja tiedostopohjaiset sivut ovat jo repositoriossasi. Osa sisällöstä ei sovi tähän malliin, koska muokkaajat luovat sen hallintapaneelissa: tiimin jäsenet, toimipisteet ja tapaustutkimukset. Sisältö on silti tärkeä projektille. Esittelysivustolla tarvitaan sama tiimisivu kuin tuotantosivustolla, uusi kehittäjä tarvitsee realistista dataa, ja tarkastajan pitäisi nähdä, kun joku muuttaa tehtävänimikettä. Tietokantavedokset eivät ratkaise mitään näistä ongelmista hyvin. Ne sisältävät kaiken, tunnukset ovat eri ympäristöissä erilaiset, eikä kukaan tarkista SQL-muutoksia.

Content Sync kattaa tämän aukon. WP-CLI-komento vie sallittujen listalle määritetyt artikkelit, termit, suhteet ja metatiedot teeman JSON- ja HTML-tiedostoihin. Toinen komento soveltaa tiedostot toiseen tietokantaan. Jokainen entiteetti saa siirrettävän UID:n, ja entiteettien väliset viittaukset kirjoitetaan uudelleen vain niissä kohdissa, jotka määrität.

Tässä oppaassa käydään läpi tiimihakemisto: sen vieminen tiedostoihin, tarkistaminen, tiedoston muokkaaminen, siirtäminen uuteen ympäristöön ja turvallinen karsiminen.

Esimerkki

Teema rekisteröi acme_member-artikkelityypin ja acme_team-taksonomian jokaisessa ympäristössä. Kunkin jäsenartikkelin metatiedoissa voi olla:

Metatietoavain Sisältö
_acme_role Tehtävänimike, tavallinen merkkijono
_acme_mentor Toisen jäsenen artikkelitunniste
_thumbnail_id Muotokuvan liitetunniste
_acme_api_token Integrointitunniste, joka ei saa koskaan päätyä paikkaan git

Content Sync ei koskaan rekisteröi artikkelityyppejä tai taksonomioita. Niiden on oltava olemassa kaikissa ympäristöissä, joihin työnnät sisältöä.

Vaihe 1: Määritä Content Sync

Content Sync on pois käytöstä, kunnes otat sen käyttöön kohteessa blockstudio.json. Siihen asti jokainen komento palauttaa yhden skipped-rivin:

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

Lisää content-ryhmä:

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

Jokainen avain rajaa toimintaa:

  • postTypes ja taxonomies ovat sallittujen listoja. Niiden ulkopuolista sisältöä ei lueta, kirjoiteta eikä karsita. Tyhjä postTypes tarkoittaa, ettei artikkeleihin kosketa.
  • meta.include määrittää sallitut meta-avaimet ja niiden *-jokerimerkit. meta.exclude ohittaa sen aina, ja _edit_lock, _edit_last ja _wp_old_slug on oletusarvoisesti suljettu pois.
  • meta.references määrittää, mitkä meta-arvot ovat tunnuksia. Content Sync ei koskaan arvaa, että kokonaisluku on tunnus.
  • id nimeää sisältöjoukon. Se tallennetaan jokaiseen synkronoituun entiteettiin, ja karsinta koskee vain saman joukon entiteettejä.
  • path on tulostuskansio suhteessa käytössä olevaan teemahakemistoon.

Vaihe 2: Nouda sisältö

Esikatsele ensin, mitä tuodaan. Mitään ei kirjoiteta, eikä näytettyjä UID-tunnuksia ole vielä tallennettu:

Shell
wp bs content pull --dry-run
Koodi
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

Nouda sitten sisältö oikeasti. Tämä antaa pysyvän _blockstudio_content_uid-tunnuksen jokaiselle entiteetille, jolta se puuttuu, ja kirjoittaa tiedostot:

Shell
wp bs content pull
Koodi
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

Teemahakemiston sisältö:

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

Tiedostonimissä yhdistyvät polkutunnus ja UID:n alkuosa. Artikkelin JSON sisältää kentät, termisuhteet ja sallitut metatiedot:

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

Termisuhde ja esikatselukuva ovat UID-tunnuksia, eivät paikallisia tunnuksia. Artikkelin sisältö on sen vieressä kohteessa jane.5d4bf9b5.html raakana lohkomerkintänä. Tyhjä sisältö, kuten Samilla, tarkoittaa, ettei .html-tiedostoa luoda. Samin _acme_mentor tallennetaan Janen UID-tunnuksena, koska avain on määritetty post-viittaukseksi.

Vaihe 3: Tarkista ennen toimitusta

Suorita status ennen toimitusta. Se vertaa tiedostoja ja tietokantaa sekä ilmoittaa riskialttiista tiedoista:

Shell
wp bs content status
Koodi
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_*-jokerimerkki osui tunnisteeseen. Käsittele meta.include-arvoa toimitusrajana ja sulje avain pois erikseen:

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

Seuraava pull kirjoittaa sam.208db72e.json-tiedoston uudelleen ilman tunnistetta ja jättää muut tiedostot koskemattomiksi. status varoittaa myös lohkomerkinnän sisällä olevista numeerisista tunnuksista, sillä Content Sync ei kirjoita .html-tiedostojen tunnuksia uudelleen.

Toimita content/-kansio.

Vaihe 4: Muokkaa tiedostoa ja työnnä muutokset

Tiedostot ovat kohteen push totuuden lähde. Muuta Janen roolia JSON-tiedostossa arvosta Design Lead arvoon Head of Design ja tarkista sitten, mitä tapahtuisi:

Shell
wp bs content status
Koodi
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 tulostaa saman suunnitelman työntöjärjestyksessä. Ota se käyttöön:

Shell
wp bs content push
Koodi
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

Työntö validoi koko suunnitelman ennen kirjoittamista. Ratkaisemattomat määritetyt viittaukset, polkutunnusristiriidat, puuttuvat artikkelityypit ja virheelliset tiedostot keskeyttävät toiminnon.

WordPress antaa päivitetylle artikkelille uuden muokkausajan, mutta tiedostossa on yhä vanha arvo modified. Siksi heti tämän työnnön jälkeen suoritettu status ilmoittaa Janen artikkelin tilaksi conflict ja viestiksi “Tietokanta muuttunut edellisen synkronoinnin jälkeen.” Suorita työntämisen jälkeen kerran pull, jotta uusi aika tallentuu. Sen jälkeen status ilmoittaa tilaksi unchanged.

Vaihe 5: Siirrä sisältö toiseen ympäristöön

Uudessa ympäristössä tiedostot kuvaavat artikkeleita, joita ei vielä ole siellä. Tässä esimerkissä termi ja muotokuvan liitetiedosto ovat jo olemassa samoilla UID-tunnuksilla, joten vain kaksi jäsentä puuttuu:

Shell
wp bs content status
Koodi
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
Shell
wp bs content push
Koodi
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

Artikkelit saivat uudet paikalliset tunnukset 536 ja 537. Viittaukset päivittyivät niiden mukana: Samin _acme_mentor sisältää nyt arvon 536, Jane kuuluu taas termiin leadership, ja hänen _thumbnail_id-arvonsa viittaa paikalliseen liitetiedostoon, jolla on vastaava UID. Artikkelien ylätason artikkelit, termien ylätason termit ja termisuhteet tallennetaan aina UID-tunnuksina. Meta-arvot kirjoitetaan uudelleen vain avaimille, jotka on määritetty kohdassa meta.references.

Turvallinen karsiminen

Tiedoston poistaminen ei poista mitään työntövaiheessa, ellet pyydä sitä erikseen. Poista sam.208db72e.json ja kokeile karsimista:

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

Kuivakoe näyttää, mitä poistettaisiin:

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

push --prune --yes siirtää sitten Samin artikkelin roskakoriin ja ilmoittaa pruned-trash. Karsimisen rajat varmistetaan usealla suojauksella:

  • Ehdokkaita ovat vain tähän sisältöjoukkoon kuuluvat entiteetit (content.id).
  • Huomioon otetaan vain määritetyt artikkelityypit ja taksonomiat.
  • Koko lähdesuunnitelma jäsennetään ja validoidaan ennen kirjoittamista tai karsimista. Jos kansiossa on virheellinen JSON-tiedosto, työntö ilmoittaa virherivin error, esimerkiksi could not be read: Syntax error, eikä karsi mitään.

Oletustoiminto on trash. blockstudio/content/orphan_action-suodatin voi palauttaa kullekin entiteetille arvon trash, delete tai keep. Näin termit säilytetään ja artikkelit jätetään oletustoiminnon varaan:

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

Sen ansiosta orvoksi jäänyt termi ilmoitetaan tilassa would-prune-keep tilan would-prune-trash sijaan.

Media

Mediatiedostoja ei koskaan kopioida. content.media määrittää, mitä määritetyille liitetiedostoviittauksille tapahtuu:

  • "manifest" (oletus) tallentaa liitetiedostojen UID-tunnukset ja luettelee ne kohteessa content/media/manifest.json sekä niiden polut, MIME-tyypit ja vaihtoehtoiset tekstit. Työntö edellyttää, että jokainen viitattu liitetiedoston UID löytyy kohdeympäristöstä. Siirrä siis lataukset ensin tavallisen mediatiedostojen siirtokäytäntösi mukaisesti.
  • "none" jättää määritetyt liitetiedostoviittaukset pois tiedostoista. Janen JSON sisältää silloin vain arvon _acme_role. Koska pois jätettyä avainta ei sovelleta työnnössä, kohdeartikkelin nykyinen esikatselukuva säilyy.

Entiteetin lukitseminen

Joskus kohdeympäristössä on säilytettävä tietyn artikkelin oma versio. Aseta kyseisen artikkelin _blockstudio_content_locked-metalle totuusarvoinen arvo, jolloin työntö ohittaa sen, palauttaa locked-rivin ja viestin “Lukittu entiteetti ohitettiin.” Poista meta, jos haluat ottaa sen taas mukaan.

Omistussäännöt

  • Tiedostopohjaisten sivujen hallinnoimat artikkelit jätetään oletusarvoisesti pois. Asetuksella includePageSyncManaged: true Content Sync voi synkronoida niiden määritetyt metatiedot, mutta Page Sync hallinnoi edelleen niiden post_content-sisältöä. Näissä JSON-näkymissä on bodyOwner: "page-sync", ja nouto ilmoittaa erikseen ohitetusta rungosta. Olemassa olevat .html-tarkistuskopiot säilytetään, ja push jättää ne huomiotta. Synkronoi sivut kohdeympäristössä ennen niiden metadata-näkymien push-toimintoa.
  • Tekijät jätetään oletusarvoisesti huomiotta, koska käyttäjiä ei synkronoida. Asetuksella authors: "login" artikkelitiedostoihin tallennetaan tekijän kirjautumistunnus, ja push yhdistää sen olemassa olevaan käyttäjään. Jos käyttäjää ei löydy, esikartoitus epäonnistuu.
  • pull ei koskaan poista tiedostoja. Kun tietokantakohde on poistettu, nouto ilmoittaa tiedoston olevan vanhentunut ja jättää siivouksen sinulle.

Milloin sitä ei kannata käyttää

Content Sync sopii huolellisesti valittuun, vähän muuttuvaan sisältöön: kymmeniin tai satoihin tietueisiin ja jopa muutamaan tuhanteen, jos tiedot ovat jäsenneltyjä ja jaettu erillisiin, tarkoituksenmukaisiin artikkelityyppeihin. Se ei korvaa tietokannan varmuuskopioita tai siirtoja. Tilaukset, lomakelähetykset, lokit, analytiikka ja suurivolyyminen toimituksellinen sisältö kuuluvat niille tarkoitettuihin työkaluihin. Taksonomiamääritelmät, mediatiedostot ja lohkomerkinnän sisäiset tunnukset jäävät sen soveltamisalan ulkopuolelle.

Seuraavat vaiheet