제작·이전

Ghost에서 Astro로 글과 이미지를 옮긴 실제 과정

목차 보기

고스트를 떠나기로 결정한 뒤 가장 먼저 걱정한 것은 새 디자인이 아니었습니다. 기존 글과 이미지가 빠짐없이 옮겨지고, 사용하던 주소가 그대로 열리며, 문제가 생기면 이전 상태로 되돌릴 수 있어야 했습니다.

minml은 당시 Ghost 6.42.0으로 운영되고 있었고, 최종적으로 글 18편과 고정 페이지 3개를 Astro 콘텐츠로 옮겼습니다. 회원, 유료 구독, 뉴스레터를 쓰지 않는 개인 블로그였기 때문에 가능한 선택도 있었으므로 모든 Ghost 사이트에 그대로 적용되는 방법은 아닙니다. 고스트를 떠나기로 한 이유는 고스트를 두 달 만에 떠난 이유에 따로 적었습니다.

백업부터

처음부터 Ghost를 삭제하거나 서버 설정을 바꾸지 않았습니다. Astro 사이트를 만들다가 문제가 생겨도 기존 블로그로 돌아갈 수 있도록 전체 백업부터 만들었습니다.

당시 보관한 항목은 다음과 같습니다.

  • Ghost 데이터베이스 덤프
  • Ghost의 content 디렉터리와 운영 설정
  • Ghost CLI 관련 설정
  • Nginx 가상 호스트와 Ghost 서비스 설정
  • 각 백업 파일의 SHA-256 해시

파일이 존재하는 것만으로 백업이 끝났다고 보지 않았습니다. 압축 파일의 내부 목록이 열리는지, 데이터베이스 압축 스트림이 정상적으로 풀리는지, SQL 덤프에 완료 표시가 있는지 확인했습니다. 당시 데이터베이스 덤프에서는 81개 테이블과 완료 표시를 확인했고, 서버에서 만든 해시와 로컬로 내려받은 파일의 해시도 비교했습니다.

Ghost 공식 문서도 직접 운영하는 설치본을 백업할 때 데이터베이스와 content 폴더, JSON 내보내기와 별도로 이미지·파일·미디어 폴더, 경로와 리디렉션 설정까지 따로 보관하도록 안내합니다(2026년 9월 26일 확인).

글 데이터와 이미지 파일 분리

Ghost에서 글을 내보내면 제목과 본문, 작성자, 태그, 발행일 같은 정보는 JSON으로 다룰 수 있습니다. 하지만 본문이 이미지를 가리킨다고 해서 이미지 파일까지 JSON에 들어가지는 않습니다. 그래서 두 부분으로 나눴습니다.

  1. 글과 페이지, 메타데이터를 JSON으로 수집했습니다.
  2. 서버의 이미지 디렉터리를 별도로 복사했습니다.

JSON에는 총 21개 항목이 있었습니다. 글 18개와 소개·문의·개인정보처리방침 페이지 3개입니다. 이미지 원본 폴더에는 여러 크기와 형식으로 생성된 파일까지 포함해 163개가 있었습니다. 글마다 이미지를 많이 써서가 아니라 Ghost가 화면 크기에 맞춘 변형 파일을 함께 만들어뒀기 때문입니다. 이 구조는 Ghost 이미지 파일이 여러 개 생기는 이유에서 자세히 다뤘습니다. 원본 백업에는 163개를 그대로 두고, Astro 사이트에는 글이 실제로 참조하는 경로를 기준으로 파일을 연결했습니다.

변환 스크립트

JSON의 HTML 본문을 Markdown 파일로 바꾸는 일은 scripts/migrate-ghost.mjs가 맡았습니다. HTML을 Markdown으로 바꾸는 데는 turndown 라이브러리를 썼습니다. 코드는 AI의 도움으로 작성했고, 아래는 그 파일에서 그대로 옮긴 부분입니다.

먼저 본문의 주소를 정리합니다.

function htmlToMarkdown(html) {
  const normalized = (html ?? "")
    .replaceAll("__GHOST_URL__", "")
    .replaceAll("https://minml.kr/content/images/", "/content/images/");

Ghost 본문에는 사이트 주소 자리에 __GHOST_URL__이라는 자리표시자가 들어간 링크가 있었습니다. 이것을 지우면 /content/images/... 같은 사이트 내부 경로가 남습니다. 전체 도메인으로 적힌 이미지 주소도 같은 내부 경로로 바꿨습니다. 그래야 로컬 미리보기와 실제 서버에서 같은 이미지 구조를 쓸 수 있습니다. 대표 이미지와 공유 이미지 필드에도 같은 규칙을 적용했습니다.

모든 HTML을 Markdown으로 바꾸지는 않았습니다.

turndown.keep(["iframe", "table", "thead", "tbody", "tfoot", "tr", "th", "td", "details", "summary", "video", "audio"]);

표, iframe, 접기 영역, 동영상과 오디오는 HTML 그대로 남깁니다. Ghost 편집기의 HTML 카드(kg-html-card)와 북마크 카드(kg-bookmark-card)도 별도 규칙을 둬서 원래 HTML을 통째로 넣었습니다. 표현할 수 없는 요소까지 억지로 Markdown으로 바꾸면 본문 일부가 사라질 수 있기 때문입니다.

frontmatter는 Ghost 글의 필드를 하나씩 대응시켜 만들었습니다. 설명은 meta_description, 없으면 custom_excerpt, 그것도 없으면 본문 앞부분 155자로 채웠고, 태그는 공개 태그(visibility === "public")만 옮겼습니다. 검색·소셜 공유용 제목과 설명도 모두 옮겼기 때문에 지금 Astro 콘텐츠 스키마의 필드가 24개나 됩니다.

이 스크립트는 실행할 때마다 src/content/posts와 src/content/pages를 비운 뒤 JSON에서 다시 만듭니다. 프로젝트 폴더 밖에는 쓰지 못하도록 막아두긴 했지만, 이전 뒤 새 글을 쓰기 시작한 지금 다시 실행하면 그 글들이 지워집니다. 처음부터 한 번만 쓰는 변환 도구였던 셈입니다.

기존 글 주소 유지

Ghost에서 /ghost-feature-image-resize/였던 글은 Astro에서도 같은 주소로 열리게 했습니다. 변환할 때 Ghost의 slug를 frontmatter에 그대로 저장하고, Astro가 이 값을 페이지 주소로 쓰도록 구성했습니다.

주소를 유지한 이유는 기존 링크를 깨뜨리지 않기 위해서였습니다. 검색 결과나 다른 글에 남은 링크의 주소가 바뀌면 방문자는 404 페이지를 보게 됩니다. 꼭 바꿔야 하는 주소만 리디렉션 대상으로 두고 나머지는 그대로 뒀습니다.

변환 개수보다 결과물 검사

변환 스크립트는 마지막에 Migrated ${postCount} posts and ${pageCount} pages. 형식으로 변환 개수만 출력합니다. 파일이 만들어졌어도 페이지 주소나 이미지가 깨질 수 있으므로 이 한 줄로는 부족했습니다. 그래서 Astro를 빌드한 뒤 결과물을 읽는 scripts/verify-migration.mjs를 따로 만들었습니다.

이 스크립트는 dist의 HTML을 모두 읽어 다음을 확인합니다.

  • 공개 글과 페이지마다 원래 주소의 HTML이 생성됐는가
  • 대표 이미지와 본문 이미지가 실제 파일을 가리키는가
  • href·src의 내부 경로가 실제 출력 파일로 이어지는가
  • RSS와 사이트맵, 작성자 페이지가 생성됐는가
  • 링크와 이미지 주소에 변환에서 놓친 __GHOST_URL__이 남아 있지 않은가

마지막 항목은 변환 스크립트의 주소 정리를 한 번 더 확인하는 장치입니다.

if (/(?:href|src)="[^"]*__GHOST_URL__/.test(html)) {
  errors.push(`Unresolved Ghost URL in ${path.relative(root, file)}`);
}

처음에는 HTML 어디에든 이 문자열이 있으면 실패로 처리했습니다. 2026년 9월 26일 이 글에 변환 코드를 예시로 넣자, 검사가 설명용 코드 블록까지 남은 자리표시자로 보고 배포 전 검증을 멈췄습니다. 실제 문제는 링크와 이미지 주소에 남은 경우뿐이므로 href와 src 속성 안만 찾도록 좁혔습니다.

초기 이전 당시에는 글 18편과 고정 페이지 3개, HTML 파일 28개, 내부 경로 32개, 로컬 이미지 대상 20개를 확인했습니다. 개수만 센 것이 아니라 각 경로가 실제 파일로 이어지는지 검사했습니다. 이 스크립트는 이후 초안과 리디렉션 검사가 추가되어 지금도 배포할 때마다 실행됩니다. 현재 발행 과정에서의 역할은 Astro 블로그 발행 과정에 정리했습니다.

서버 전환과 Ghost 정리

로컬에서 정상으로 보인다고 바로 Ghost를 지우지 않았습니다. Astro 결과물을 서버의 새 릴리스 폴더에 올리고, 도메인이 새 정적 파일을 가리키게 한 뒤 실제 운영 환경을 확인했습니다.

  • 홈페이지와 개별 글이 HTTPS로 열리는가
  • 기존 글 주소가 유지되는가
  • 이미지와 CSS가 정상적으로 표시되는가
  • RSS, 사이트맵과 robots.txt가 열리는가
  • 같은 서버의 다른 웹사이트에 영향이 없는가

같은 서버에 있는 다른 사이트는 처음부터 작업 범위에서 제외했습니다.

운영 환경 확인이 끝난 뒤에야 Ghost 애플리케이션과 전용 데이터베이스를 정리했습니다. 그 직전에도 Ghost 전체 백업, Astro 소스, 실제 배포 파일을 한 묶음으로 다시 보관했습니다. 지금 Ghost를 복구하려면 다시 설치해야 하지만 콘텐츠와 데이터베이스, 당시 설정은 로컬 백업에 남아 있습니다.

작업 순서 정리

돌아보면 변환 코드보다 순서가 더 중요했습니다.

  1. 복원 가능한 전체 백업을 만든다.
  2. 글 데이터와 이미지 파일을 따로 확보한다.
  3. 기존 주소를 유지하며 콘텐츠 형식을 변환한다.
  4. 로컬에서 화면과 빌드를 확인한다.
  5. 생성된 주소, 링크와 이미지 파일을 자동 검사한다.
  6. 새 사이트를 먼저 운영 환경에 올린다.
  7. 실제 도메인에서 확인한 뒤에만 기존 서비스를 정리한다.

이 순서를 지키면 어느 단계에서 문제가 생겨도 이전 단계로 돌아갈 수 있습니다. 기존 서비스를 먼저 지우고 변환을 시작하면 작은 누락도 복구 작업이 됩니다.

어떤 데이터가 반드시 남아야 하는지, 주소를 유지할지, 다른 사이트를 작업 대상에서 뺄지, 언제 Ghost를 삭제해도 되는지는 AI가 아니라 제가 정해야 했습니다. 변환 스크립트와 검사 스크립트는 빨리 만들 수 있었지만, 위 순서와 기준은 작업 전에 먼저 정해둔 것입니다.

결과적으로 바뀐 것

Ghost의 내보내기 기능이 부족해서 옮긴 것은 아닙니다. Ghost는 설정 화면에서 글·페이지·태그·설정을 JSON 하나로 내보내는 기능을 제공합니다(2026년 9월 26일 확인). 저는 그 데이터를 다시 CMS로 복원하는 대신 Markdown 파일과 정적 HTML로 바꿔 보관하기로 했을 뿐입니다.

그래서 이 작업은 블로그 프로그램을 교체했다기보다 저장 형식을 바꾼 작업에 가까웠습니다. 글은 Markdown으로, 이미지는 일반 파일로, 공개 페이지는 빌드 때 만든 HTML로 남았습니다. 이전 뒤 사이트 구조를 바꿀 때도 콘텐츠 파일은 그대로 두고 목록을 만드는 코드만 고칠 수 있었던 것은 이렇게 셋을 나눠 옮겨둔 덕분입니다.

참고한 공식 문서

2026년 9월 26일 확인