Synchronizacja treści
Blockstudio opiera się na pracy z plikami: bloki, pola, szablony, zasoby, wzorce i strony oparte na plikach mogą znajdować się w Twoim projekcie. Synchronizacja treści rozszerza ten model o wybrane dane z bazy WordPress dla zespołów, które chcą również przechowywać w git wyselekcjonowane wpisy, terminy, relacje i zadeklarowane metadane.
Jest to przepływ pracy WP-CLI, a nie replikacja bazy danych na żywo. Podczas pobierania synchronizacja eksportuje do przenośnych plików w motywie dozwolone wpisy, postmeta, terminy, termmeta i relacje między wpisami a terminami. Podczas wysyłania stosuje te pliki w innym środowisku, używając stałych identyfikatorów UID i zmieniając tylko jawnie zadeklarowane odwołania.
Uwaga
Synchronizacja treści jest uruchamiana na żądanie. Nie działa przy każdym żądaniu administratora. Polecenia zwracają pominięty wiersz, dopóki
content.enablednie zostanietrue.
Kiedy używać synchronizacji treści
Używaj synchronizacji treści w przypadku zestawów treści, które warto wersjonować, sprawdzać i przenosić między środowiskami:
- uporządkowane treści, takie jak członkowie zespołu, lokalizacje, studia przypadków, produkty, wpisy dokumentacji lub strony kampanii
- taksonomie i relacje powiązane z tymi zestawami treści
- dozwolone metadane, które można bezpiecznie zatwierdzić i które wymagają stałych odwołań
- małe i średnie zestawy treści, w przypadku których przeglądanie plików w git jest nadal praktyczne
Zasadniczo synchronizacja treści dobrze sprawdza się przy dziesiątkach lub setkach wierszy, a także przy kilku tysiącach, jeśli dane mają uporządkowaną strukturę, rzadko się zmieniają i są podzielone na skoncentrowane typy wpisów. Nie służy do odzwierciedlania całej produkcyjnej bazy danych, często aktualizowanych treści redakcyjnych, dzienników, zamówień, analiz, zgłoszeń z formularzy, sesji ani innych danych o dużej objętości lub zmienności. Jeśli wygenerowane pliki są zbyt zaszumione, by je przeglądać, analizowanie wysyłania zmian zajmuje zbyt dużo czasu albo większość wierszy zmienia się poza procesem wdrażania, użyj kopii zapasowej bazy danych, migracji lub narzędzia do importu i eksportu.
Pliki binarne mediów nie są kopiowane. Odwołania do załączników można zapisać w manifeście i zweryfikować, ale same pliki muszą już istnieć w środowisku docelowym.
Konfiguracja
Włącz synchronizację treści w 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 to lista dozwolonych elementów. Jeśli jest pusta, synchronizacja treści nie obejmuje wpisów. taxonomies to lista zarejestrowanych taksonomii, których terminy i relacje z wpisami powinny być synchronizowane. Blockstudio nie rejestruje definicji taksonomii na podstawie plików synchronizacji treści. Listę dozwolonych postmeta i termmeta określa meta.include; meta.exclude zawsze ma pierwszeństwo.
Ostrzeżenie
Traktuj
meta.includejako granicę zatwierdzania zmian. Synchronizowane pliki mają być przechowywane w git, więc nie uwzględniaj kluczy zawierających tajne dane, tokeny, dane uwierzytelniające ani dane osobowe.wp bs content statuszgłasza wiersze z ostrzeżeniem, gdy dozwolony klucz metadanych wygląda na wrażliwy.
content.id jest przechowywane w synchronizowanych obiektach jako _blockstudio_content_set. Kontrola przycinania i własności jest ograniczona do tej wartości, więc jeden zestaw treści nie może usunąć treści należących do innego.
Domyślnie wpisy zarządzane przez synchronizację stron są wykluczone. Jeśli włączono includePageSyncManaged, synchronizacja treści może synchronizować ich skonfigurowane metadane, ale własność ich post_content nadal należy do synchronizacji stron.
Te projekcje zawierają "bodyOwner": "page-sync". Pull zgłasza zapis JSON jako zawierający wyłącznie metadane i dodaje wiersz treści skipped zamiast przedstawiać wpis jako pozbawiony treści. Nie zapisuje ani nie usuwa sąsiedniego pliku .html. Istniejąca kopia do przeglądu zostaje zachowana i jest ignorowana przez push. Te same komunikaty o własności są uwzględniane w danych wyjściowych trybu dry-run.
W innym środowisku najpierw uruchom Page Sync. Projekcja z bodyOwner: "page-sync" musi odwoływać się do istniejącego wpisu zarządzanego przez Page Sync; push odmawia utworzenia pustego zastępczego wpisu lub zastosowania kopii roboczej treści do przeglądu. Projekcje bez tego znacznika ze starszych wersji są nadal obsługiwane.
Autorzy są domyślnie pomijani, ponieważ użytkownicy nie są synchronizowani. Ustaw authors: "login", aby zapisać login autora w plikach wpisów i powiązać ten login z istniejącym użytkownikiem podczas wysyłania zmian. Brakujący użytkownik powoduje błąd kontroli wstępnej; synchronizacja treści nie tworzy użytkowników.
Polecenia
wp bs content pull [--post-type=<type>] [--taxonomy=<taxonomy>] [--dry-run]
wp bs content push [--dry-run] [--prune] [--yes]
wp bs content status
pull zapisuje treść z bazy danych do plików. Przypisuje _blockstudio_content_uid wpisom objętym zakresem, które jeszcze go nie mają, i zgłasza nieaktualne pliki, których źródło w bazie już nie istnieje. Nieaktualne pliki nie są usuwane podczas pobierania.
push stosuje pliki w bieżącej bazie danych. Przed zapisem weryfikuje plan i blokuje nierozwiązane zadeklarowane odwołania, konflikty slugów, zablokowane obiekty i brakujące typy wpisów.
status porównuje pliki z bazą danych i oznacza każdy obiekt jako unchanged, would-update, missing-db, conflict, locked lub orphaned. Ostrzega też przed dozwolonymi kluczami metadanych, które wyglądają na tajne dane, zanim ich wartości zostaną zatwierdzone, oraz przed liczbowymi identyfikatorami w treści znaczników bloków, ponieważ synchronizacja treści nie zmienia identyfikatorów w plikach .html.
Użyj --dry-run, aby sprawdzić pobieranie lub wysyłanie zmian bez zapisu. Użyj push --prune --yes, aby usunąć z bazy danych obiekty należące do zestawu treści, których nie ma już w plikach.
Bezpieczne postępowanie w razie błędów
push analizuje i weryfikuje cały plan źródłowy, zanim cokolwiek zapisze lub
usunie. Nieprawidłowy JSON, nierozwiązane zadeklarowane odwołania, błędna własność i
inne błędy kontroli wstępnej blokują etap usuwania. Usuwanie pozostaje ograniczone
do skonfigurowanych typów wpisów, taksonomii i content.id.
pull zapisuje każdy wyeksportowany plik, zanim oznaczy dany obiekt jako zsynchronizowany. Błąd zapisu w systemie plików jest zgłaszany jako wiersz błędu i nie aktualizuje zapisanego stanu synchronizacji tego obiektu.
Obsługa załączników działa zgodnie z content.media. Przy "manifest" wskazane UID-y załączników muszą istnieć w środowisku docelowym. Przy "none" zadeklarowane odwołania do załączników są celowo usuwane z przenośnego wyjścia zamiast zachowywania identyfikatorów specyficznych dla środowiska.
Pliki
Content Sync zapisuje pliki w skonfigurowanym content.path:
content/
posts/
team_member/
jane.9b1c0e6e.json
jane.9b1c0e6e.html
terms/
category/
leadership.5e900000.json
media/
manifest.json
Pliki .json posta przechowują tożsamość, pola posta, relacje z terminami, zadeklarowane metadane i kodowanie metadanych. Sąsiedni plik .html przechowuje post_content jako surowy znacznik bloku i jest pomijany, gdy zawartość jest pusta. Pliki .json terminu przechowują tożsamość, taksonomię, slug, nazwę, opis, UID elementu nadrzędnego, zadeklarowane metadane terminu i kodowanie metadanych.
Drugi przypadek, w którym brak pliku .html, dotyczy treści zarządzanej przez Page Sync, wskazanej powyżej przez bodyOwner. W przypadku zwykłych wpisów, których treść staje się pusta, pull usuwa stary plik treści i wymienia go w osobnym wierszu treści 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"
}
}
Zapisany stan synchronizacji:
| Klucz metadanych | Cel |
|---|---|
_blockstudio_content_uid |
Przenośna tożsamość treści |
_blockstudio_content_set |
Przestrzeń nazw zestawu treści z content.id |
_blockstudio_content_source |
Ścieżka pliku źródłowego względem motywu |
_blockstudio_content_fingerprint |
Ostatni odcisk pliku/bazy danych po synchronizacji |
_blockstudio_content_locked |
Wartość uznawana za prawdziwą zapobiega nadpisaniu encji przez wypychanie zmian |
Odwołania
Content Sync nie zgaduje, że liczba całkowita jest identyfikatorem. Odwołania są przepisywane tylko wtedy, gdy skonfigurowano je w meta.references.
{
"meta": {
"references": {
"_related_posts": { "kind": "post", "path": "*" },
"_topic": { "kind": "term" },
"_hero": { "kind": "attachment", "path": "image.id" }
}
}
}
Podczas pobierania lokalne identyfikatory w tych ścieżkach stają się przenośnymi UID-ami. Podczas wysyłania UID-y są mapowane z powrotem na lokalne identyfikatory w bieżącej bazie danych.
Elementy nadrzędne postów i terminów oraz relacje między postami a terminami to odwołania strukturalne obsługiwane przez Content Sync i automatycznie zapisywane jako UID-y. Skonfigurowane taksonomie są zapisywane w plikach postów nawet wtedy, gdy są puste; pusta tablica usuwa relacje z tą taksonomią podczas wysyłania zmian.
Odwołania do załączników są weryfikowane, a nie importowane. Przy media: "manifest" wskazane załączniki są wymienione w content/media/manifest.json; wysyłanie zmian wymaga, aby wskazany UID załącznika istniał lokalnie. Przy media: "none" zadeklarowane odwołania do załączników są pomijane w przenośnych plikach. Ponieważ pominięty klucz nie jest stosowany podczas wysyłania zmian, istniejący post w środowisku docelowym zachowuje bieżące metadane załączników.
Proces przenoszenia
- Zarejestruj typ posta w każdym środowisku.
- Skonfiguruj
content.postTypes,meta.includei wszelkie zadeklarowane odwołania. - Uruchom
wp bs content pullw środowisku źródłowym. - Zatwierdź wygenerowane pliki.
- Uruchom
wp bs content pushw środowisku docelowym. - Uruchom
wp bs content status, aby sprawdzić, czy baza danych jest zgodna z plikami.
Pliki są źródłem prawdy dla push. Baza danych jest z powrotem zapisywana do plików za pomocą pull.
Zakres
Content Sync obsługuje:
- posty z dozwolonych typów postów
- dozwolone postmeta
- terminy z dozwolonych zarejestrowanych taksonomii
- dozwolone termmeta
- relacje postów z terminami
- zadeklarowane odwołania
post,attachmentiterm - przenośne UID-y postów i terminów oraz przypisanie do zestawu treści
- domyślne wykluczenie Page Sync
- manifest załączników i weryfikację wstępną
pull,push,status,--dry-run,--pruneoraz obsługę zablokowanych encji
Przechwytywanie definicji taksonomii, kopiowanie plików multimedialnych i przepisywanie identyfikatorów znaczników bloków nie są obsługiwane.