본문으로 건너뛰기

콘텐츠 동기화

Blockstudio는 파일 우선 워크플로우를 중심으로 구축되었습니다. 블록, 필드, 템플릿, 에셋, 패턴, 파일 기반 페이지를 모두 프로젝트에 둘 수 있습니다. Content Sync는 이 모델을 선택한 WordPress 데이터베이스 콘텐츠로 확장하므로, 엄선한 게시물, 용어, 관계, 선언된 메타데이터도 git에 저장할 수 있습니다.

이는 WP-CLI 워크플로우이며 실시간 데이터베이스 복제 기능은 아닙니다. 가져올 때는 허용 목록에 지정한 글, postmeta, 용어, termmeta, 글과 용어 간 관계를 테마의 이식 가능한 파일로 내보냅니다. 내보낼 때는 안정적인 UID를 사용해 해당 파일을 다른 환경에 적용하며, 명시적으로 선언한 참조만 다시 작성합니다.

참고

콘텐츠 동기화는 필요할 때만 실행되며 관리 요청이 있을 때마다 실행되지 않습니다. true가 content.enabled되기 전에는 명령 결과에 건너뜀 행이 표시됩니다.

콘텐츠 동기화 사용 시기

버전을 관리하고 검토하여 환경 간에 옮겨야 하는 콘텐츠 세트에 콘텐츠 동기화를 사용하세요:

  • 팀원, 위치, 사례 연구, 제품, 문서 항목 또는 캠페인 페이지와 같은 구조화된 콘텐츠
  • 해당 콘텐츠 세트에 속하는 분류 체계와 관계
  • 커밋해도 안전하고 안정적인 참조가 필요한 허용 목록 등록 메타데이터
  • 파일을 git에서 검토하는 방식이 여전히 실용적인 소규모에서 중간 규모의 콘텐츠 세트

일반적으로 수십 개에서 수백 개의 행까지는 무리 없이 처리하며, 데이터 구조가 잘 잡혀 있고 변경이 드물며 전용 글 유형별로 나뉘어 있다면 수천 개 초반까지도 처리할 수 있습니다. 전체 프로덕션 데이터베이스, 트래픽이 많은 편집 콘텐츠, 로그, 주문, 분석 데이터, 양식 제출, 세션 또는 그 밖의 대용량이거나 자주 바뀌는 데이터를 복제하기 위한 기능은 아닙니다. 생성된 파일을 검토하기 어렵거나, 푸시 내용을 파악하는 데 시간이 너무 오래 걸리거나, 배포 워크플로우 밖에서 대부분의 행이 변경된다면 데이터베이스 백업, 마이그레이션 또는 가져오기/내보내기 도구를 사용하세요.

미디어 바이너리 파일은 복사되지 않습니다. 첨부 파일 참조를 매니페스트에 기록하고 검증할 수 있지만, 파일 자체는 대상 환경에 있어야 합니다.

구성

blockstudio.json에서 콘텐츠 동기화를 활성화하세요:

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에 저장되므로 비밀, 토큰, 자격 증명 또는 PII가 포함된 키는 넣지 마세요. 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 Sync는 구성된 content.path 아래에 파일을 씁니다:

코드
content/
  posts/
    team_member/
      jane.9b1c0e6e.json
      jane.9b1c0e6e.html
  terms/
    category/
      leadership.5e900000.json
  media/
    manifest.json

게시물 .json 파일에는 ID, 게시물 필드, 용어 관계, 선언된 메타데이터 및 메타데이터 인코딩이 저장됩니다. 함께 있는 .html 파일에는 post_content이 원시 블록 마크업으로 저장되며 콘텐츠가 비어 있으면 생략됩니다. 용어 .json 파일에는 ID, 분류 체계, 슬러그, 이름, 설명, 상위 UID, 선언된 용어 메타데이터 및 메타데이터 인코딩이 저장됩니다.

.html 파일이 없는 다른 경우는 bodyOwner 위에서 식별한 Page Sync 소유 본문입니다. 일반 게시물의 본문이 비게 되면 pull은 기존 본문 파일을 제거하고 별도의 deleted 본문 행에 그 파일 이름을 표시합니다.

JSON
{
  "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 이식 가능한 콘텐츠 ID
_blockstudio_content_set content.id의 콘텐츠 세트 네임스페이스
_blockstudio_content_source 테마 기준 소스 파일 경로
_blockstudio_content_fingerprint 마지막으로 동기화한 파일/데이터베이스 지문
_blockstudio_content_locked 참 값이면 푸시가 엔터티를 덮어쓰지 않음

참조

Content Sync는 정수가 ID라고 추측하지 않습니다. 참조는 meta.references에 구성된 경우에만 다시 작성됩니다.

JSON
{
  "meta": {
    "references": {
      "_related_posts": { "kind": "post", "path": "*" },
      "_topic": { "kind": "term" },
      "_hero": { "kind": "attachment", "path": "image.id" }
    }
  }
}

가져올 때 해당 경로의 로컬 ID는 이식 가능한 UID로 바뀝니다. 푸시할 때는 현재 데이터베이스의 로컬 ID로 UID를 변환합니다.

게시물 상위 항목, 용어 상위 항목 및 게시물-용어 관계는 Content Sync가 관리하는 구조적 참조이며 자동으로 UID로 저장됩니다. 구성된 분류 체계는 비어 있어도 게시물 파일에 기록됩니다. 빈 배열을 푸시하면 해당 분류 체계의 관계가 모두 지워집니다.

첨부 파일 참조는 가져오지 않고 검증합니다. media: "manifest"을 사용하면 참조된 첨부 파일이 content/media/manifest.json에 나열되며, 푸시하려면 참조된 첨부 파일 UID가 로컬에 있어야 합니다. media: "none"을 사용하면 선언된 첨부 파일 참조가 이식 가능한 파일에서 생략됩니다. 생략된 키는 푸시 중 적용되지 않으므로 기존 대상 게시물의 현재 첨부 파일 메타데이터는 유지됩니다.

이식 워크플로우

  1. 모든 환경에서 대상 게시물 유형을 등록합니다.
  2. content.postTypes, meta.include 및 선언할 참조를 구성합니다.
  3. 소스 환경에서 wp bs content pull을 실행합니다.
  4. 생성된 파일을 커밋합니다.
  5. 대상 환경에서 wp bs content push을 실행합니다.
  6. wp bs content status을 실행해 데이터베이스와 파일이 일치하는지 확인합니다.

push의 기준은 파일입니다. pull을 사용하면 데이터베이스의 내용을 파일로 다시 가져옵니다.

범위

Content Sync에서 지원하는 항목:

  • 허용 목록에 있는 게시물 유형의 게시물
  • 허용 목록에 있는 게시물 메타데이터
  • 허용 목록에 있는 등록된 분류 체계의 용어
  • 허용 목록에 있는 용어 메타데이터
  • 게시물-용어 관계
  • 선언된 post, attachment 및 term 참조
  • 이식 가능한 게시물 및 용어 UID와 콘텐츠 세트 소유권
  • 기본적으로 Page Sync에서 제외
  • 첨부 파일 매니페스트 및 사전 검증
  • pull, push, status, --dry-run, --prune 및 잠긴 엔터티 처리

분류 체계 정의 캡처, 미디어 바이너리 복사 및 블록 마크업 ID 재작성은 지원하지 않습니다.