제작·이전

Astro 블로그는 글을 어떻게 발행할까, CMS 없이 운영해본 과정

목차 보기

고스트를 쓸 때는 관리자 화면에서 제목과 본문을 쓰고 발행 버튼을 누르면 끝났습니다. 지금 minml에는 그 버튼이 없습니다. 글 한 편을 공개하려면 다음 순서를 거칩니다.

  1. src/content/posts/에 Markdown 파일을 만듭니다.
  2. npm run dev로 로컬 화면을 확인합니다.
  3. npm run build와 검증 스크립트로 사이트 전체를 검사합니다.
  4. 발행 전 보안 검토를 마치고 커밋합니다.
  5. npm run deploy -- --check-path=/new-post/로 배포합니다.

단계는 고스트 때보다 늘었습니다. 대신 각 단계가 무엇을 확인하는지 저장소의 설정 파일과 스크립트로 남아 있습니다. 아래 설명은 2026년 9월 26일 저장소 기준입니다.

글 한 편은 Markdown 파일 하나

글은 src/content/posts/ 폴더의 .md 파일입니다. 파일 위쪽 frontmatter에 제목, 주소, 날짜, 대표 이미지 같은 정보를 적고 그 아래에 본문을 씁니다. 새 글을 쓸 때 실제로 채우는 필드만 추리면 다음과 같습니다.

---
title: "글 제목"
slug: "new-post"
description: "검색 결과와 공유 미리보기에 쓰는 설명"
excerpt: "글 목록 카드에 보이는 요약"
publishedAt: "2026-09-26 21:00:00"
updatedAt: "2026-09-26 21:00:00"
tags: ["Astro", "블로그 운영"]
featureImage: "/content/images/2026/09/new-post.webp"
featureImageAlt: "대표 이미지 설명"
draft: false
---

여기부터 본문입니다.

필드 형식은 src/content.config.ts의 스키마가 정합니다. 일부만 옮기면 이렇습니다.

const commonSchema = z.object({
  title: z.string(),
  slug: z.string(),
  description: z.string().default(""),
  publishedAt: z.coerce.date(),
  updatedAt: z.coerce.date(),
  // …중략…
  draft: z.boolean().default(false)
});

title, slug, 두 날짜처럼 기본값이 없는 필드를 빼먹거나 형식을 틀리면 Astro가 스키마 오류를 알려줍니다. 전체 스키마에는 필드가 24개 있는데, 대부분은 Ghost에서 옮길 때 글마다 붙어 있던 검색·소셜 공유용 메타데이터를 그대로 가져온 것입니다. draft: true로 두면 파일은 저장소에 남지만 글 목록과 공개 주소에서는 빠집니다. 목록과 글 페이지를 만드는 코드가 모두 !data.draft 조건으로 글을 불러오기 때문입니다.

초안과 사실 확인

본문 초안은 Claude Code나 Codex에 제가 겪은 일과 결론을 전달해 만들고, 가격·정책·버전처럼 바뀌는 내용은 공식 문서로 다시 확인합니다. 이 확인 기준은 AI가 쓴 기술 글을 검증한 과정에 따로 적었습니다. 서버 작업을 다룬 글이라면 명령 출력에 IP나 내부 경로가 섞이지 않았는지 발행 전 보안 검토도 거칩니다.

로컬 미리보기

파일을 저장하면 npm run dev로 개발 서버를 띄워 브라우저에서 봅니다. 관리자 화면의 미리보기가 아니라 실제 사이트 구성 요소로 그린 화면이라 글 목록 카드와 글 페이지를 함께 확인할 수 있습니다.

이 단계에서는 사람이 눈으로 판단해야 하는 것만 봅니다.

  • 제목과 설명이 목록 카드에서 어색하게 잘리지 않는가
  • 표와 코드 블록이 모바일 폭에서도 읽히는가
  • 대표 이미지가 다른 글의 이미지와 어울리는가

링크와 이미지 경로처럼 스크립트가 더 정확하게 보는 항목은 다음 단계에 맡깁니다.

빌드와 검증 스크립트

npm run build는 astro build를 실행해 dist 폴더에 사이트 전체의 HTML과 자산을 만듭니다. 새 글 하나가 아니라 모든 페이지를 다시 만들기 때문에 스키마 오류나 코드 오류가 여기서 드러납니다.

하지만 빌드 성공이 링크까지 보장하지는 않았습니다. 존재하지 않는 주소를 본문에 넣어도 빌드는 끝났습니다. 이 시험은 깨진 링크를 넣어도 빌드가 성공한 기록에 정리했습니다. 그래서 빌드 뒤에 scripts/verify-migration.mjs(npm run verify:migration)를 따로 실행합니다. 이름에 migration이 붙은 것은 Ghost 이전 결과를 검사하려고 처음 만들었기 때문이고, 지금은 배포할 때마다 실행합니다.

이 스크립트가 dist를 읽고 확인하는 항목은 다음과 같습니다.

  • draft가 아닌 글과 페이지마다 해당 주소의 HTML이 생성됐는가
  • 공개 글의 대표 이미지 파일이 실제로 있는가
  • 초안이 공개 주소나 사이트맵에 섞이지 않았는가, 공개 글은 사이트맵에 모두 있는가
  • 통합한 옛 주소의 리디렉션 페이지, RSS, robots.txt, 사이트맵, 작성자 페이지가 생성됐는가
  • 링크와 이미지 주소에 Ghost의 __GHOST_URL__ 자리표시자가 남아 있지 않은가
  • 모든 HTML의 href·src 내부 경로와 /content/images/ 이미지가 실제 출력 파일로 이어지는가

하나라도 걸리면 오류 목록을 출력하고 실패로 끝납니다. 통과하면 검사한 글, HTML 파일, 내부 경로, 이미지 대상의 개수를 출력합니다.

배포 명령과 커밋

배포는 npm run deploy -- --check-path=/new-post/ 한 줄입니다. --check-path에는 새로 공개할 주소를 적고, 새 글이나 이미지가 여러 개라면 옵션을 반복해서 붙입니다.

scripts/deploy.mjs는 가장 먼저 Git 작업 트리를 확인합니다. 커밋하지 않은 변경이 하나라도 있으면 Refusing to deploy with an uncommitted Git worktree.라는 오류를 내고 멈춥니다. 그래서 배포 전에는 반드시 커밋부터 하고, 서버에 올라가는 결과는 항상 커밋된 소스에서 만들어집니다.

그다음 순서는 --dry-run 옵션이 출력하는 계획과 같습니다.

Deployment plan:
1. Require a clean Git worktree, then build and verify the site.
2. Upload dist into a new release directory.
3. Set release directories to 755 and regular files to 644.
4. Abort if any group- or world-writable path remains.
5. Atomically switch current and run public checks; roll back on failure.
6. Retain the newest five verified releases and prune older releases.

빌드와 검증을 한 번 더 실행한 뒤 결과물을 서버의 새 릴리스 폴더(예: /srv/example-site/releases/<배포 시각>)에 올리고, 권한을 맞춘 다음 current 링크를 새 릴리스로 바꿉니다. 교체 뒤 홈, 사이트맵, --check-path 주소의 200 응답과 없는 주소의 404, 통합한 옛 주소의 301을 확인하고, 하나라도 실패하면 직전 릴리스로 되돌립니다. 성공하면 최근 릴리스 5개만 남깁니다.

단계마다 이렇게 만든 이유는 각 글에 따로 있습니다. 릴리스 교체와 롤백, 보존 개수는 새 릴리스로 교체하는 배포에서, 755·644 권한은 배포 후 파일 권한이 707이었던 기록에서 다뤘습니다.

데이터베이스는 어디로 갔을까

고스트를 쓸 때는 방문자가 글을 열면 실행 중인 Ghost 애플리케이션이 MySQL에서 글을 조회해 테마에 넣고 HTML을 만들어 보냈습니다. 둘 중 하나가 멈추면 블로그도 열리지 않는 구조였습니다.

Astro로 옮긴 뒤에는 새 사이트가 실제 도메인에서 정상 동작하는 것을 확인하고 Ghost 애플리케이션과 전용 MySQL 데이터베이스를 서버에서 정리했습니다. 그 과정은 Ghost에서 Astro로 옮긴 과정에 있습니다. 데이터베이스를 정리한 뒤에도 블로그는 그대로 열렸습니다. 방문자에게 필요한 글이 이미 dist의 HTML 파일 안에 들어 있기 때문입니다.

차이는 페이지를 만드는 시점입니다. Astro는 빌드할 때 Markdown 파일을 읽어 글마다 완성된 HTML을 만들고, 웹 서버는 방문 요청이 오면 주소에 맞는 파일을 보내기만 합니다. Astro 공식 문서도 별도 설정이 없으면 페이지를 빌드 시점에 정적 페이지로 미리 렌더링한다고 설명합니다(2026년 9월 26일 확인).

항목 고스트를 쓸 때 지금
글 원본 MySQL 데이터베이스 Markdown 파일
페이지를 만드는 시점 방문 요청 때 Ghost가 조립 빌드할 때 Astro가 생성
방문 때 실행되는 것 웹 서버, Ghost, MySQL 웹 서버
글 수정 반영 발행 버튼을 누르면 즉시 다시 빌드하고 배포

그래서 “데이터베이스가 없다”보다 “공개 페이지를 보여주는 데 실행 중인 데이터베이스가 필요 없다”가 정확한 표현입니다. 데이터가 사라진 것이 아니라 frontmatter와 본문이 되어 파일로 옮겨졌습니다. 댓글이나 로그인처럼 방문자가 만드는 데이터를 저장해야 하는 기능을 붙인다면 그때는 데이터베이스나 외부 서비스가 다시 필요합니다. minml에는 현재 그런 기능이 없습니다. 데이터베이스 덤프 대신 무엇을 백업하는지는 Astro 블로그 백업과 복구에 정리했습니다.

관리자 화면이 없어서 불편한 점

휴대전화로 로그인해 바로 글을 고치는 일은 할 수 없습니다. 오타 하나를 고쳐도 빌드, 검증, 커밋, 배포를 다시 거쳐야 합니다. 여러 사람이 함께 쓰거나 예약 발행, 뉴스레터가 필요하다면 CMS가 훨씬 자연스럽습니다.

제가 이 불편을 감수하는 이유는 발행이 실패했을 때 어디서 멈췄는지가 남기 때문입니다. 스키마 오류는 빌드에서, 깨진 링크는 검증 스크립트에서, 커밋하지 않은 수정은 배포 첫 단계에서, 권한과 응답 문제는 공개 직후 검사에서 걸립니다. 고스트의 발행 버튼 하나가 처리하던 일이 네 개의 확인 지점으로 나뉜 셈입니다.

참고한 공식 문서

2026년 9월 26일 확인