개인 사이트를 Astro와 Cloudflare Workers로 짓기: 빌드부터 검색·AI 인용까지

한 줄 요약

본문이 처음부터 정적 HTML로 존재하는 SSG(Static Site Generation, 정적 사이트 생성)를 택하면 크롤러도 사람도 같은 문서를 읽는다.
빌드 산출물을 Cloudflare Workers의 정적 자산으로 얹고 wrangler로 배포하면, 1인 운영자도 서버를 직접 돌보지 않고 사이트를 유지한다.
글을 파일이 아니라 스키마가 걸린 데이터로 다루면, 검색과 AI 인용을 위한 메타데이터를 실수 없이 자동으로 붙일 수 있다.

이 글은 개인 사이트나 블로그를 혼자 짓고 운영하려는 개발자·메이커에게 유용하다. 특히 서버 상태를 최소로 줄이면서 검색·AI 인용까지 챙기고 싶은 1인 운영자를 위한 구현 기록이다.

개인 사이트를 혼자 짓고 고치며 운영한다. 프레임워크를 고르는 일부터 배포 파이프라인, 글의 메타데이터까지 전부 한 사람이 손대야 하므로, 화려함보다 “손이 덜 가고 덜 깨지는가”가 선택 기준이 된다. 이 글은 그 기준으로 Astro와 Cloudflare Workers를 고르고 운영한 과정을 구현 순서대로 정리한다.

혼자 여러 도구를 얽어 운영하는 감각은 Slack 봇 업무 자동화 구축기의 1인 운영 맥락과도 이어진다.

개인 사이트를 혼자 짓고 출판물처럼 정리해 내보내는 1인 운영 작업 맥락

왜 Astro와 Cloudflare Workers를 골랐나

블로그 위주 개인 사이트에는 클라이언트에서 무겁게 렌더링하는 방식보다 정적 생성이 맞다. 본문이 빌드 시점에 HTML로 확정되면, 사람이 보는 문서와 크롤러가 읽는 문서가 같아진다. Astro는 기본이 정적 출력이라 이 전제를 자연히 충족한다.

현재 이 사이트는 Astro ^7.0.6 위에서 돈다. 필요할 때만 자바스크립트를 얹는 구조라, 글 위주 페이지는 거의 순수 HTML로 남는다.

Cloudflare Workers는 빌드 산출물을 전 세계 엣지에서 내보낸다. 정적 자산 위주라 서버 프로세스를 상주시켜 돌볼 일이 적고, 체감상 응답도 가볍다.

빌드에서 배포까지 어떻게 흐르나

흐름은 단순하다. Astro가 dist 폴더에 정적 산출물을 만들고, wrangler가 그 폴더를 Workers의 정적 자산으로 올린다. 배포는 npx wrangler deploy 한 줄로 하거나, 저장소에 push하면 Workers Builds가 대신 빌드·배포하도록 맡긴다.

설정은 wrangler.jsonc 한 곳에 모여 있다. 정적 자산 디렉터리는 ./dist로 지정하고, 없는 경로 처리는 404-page로 두어 커스텀 404 페이지가 응답하게 했다. 호환성 기준일(compatibility_date)은 2026-07-01로 고정해 런타임 동작이 조용히 바뀌는 것을 막는다.

도메인은 커스텀 도메인 연결로 붙였다. seonoh.dev를 Workers에 직접 매핑해 두면 DNS와 SSL을 Cloudflare가 처리해, 배포마다 도메인 설정을 다시 만질 일이 없다.

빌드된 정적 산출물이 하나의 패키지로 묶인 뒤 여러 엣지 지점으로 퍼져 나가는 배포 구조를 문자 없이 나타낸 도식

글은 어떻게 데이터로 관리하나

글을 자유 형식 파일이 아니라 스키마가 걸린 데이터로 다룬다. Astro의 콘텐츠 컬렉션에 zod 스키마를 걸어 각 글의 머리말(frontmatter)이 정해진 필드를 갖추도록 강제하면, 필드가 빠지거나 형식이 어긋날 때 빌드가 실패해 실수를 배포 전에 잡는다.

머리말에는 제목, 분류(category는 정해진 값만 받는 enum), 요약, 태그, 발행일과 수정일, 노출 게이트(highlight), 색인 제외 여부(noindex), 대표 이미지 경로(cover)를 둔다. 발행일 하나로 사이트맵·구조화 데이터·목록 정렬이 한 번에 정해지니, 사람이 챙길 항목이 줄어든다.

글을 스키마가 걸린 데이터로 다루며 머리말과 원고 구조를 정리하는 작업 맥락

검색과 AI 인용을 어떻게 준비했나

정적 HTML은 SEO(Search Engine Optimization, 검색엔진 최적화)와 GEO(Generative Engine Optimization, 생성형 검색 최적화)의 공통 토대다. 그 위에 사이트맵·구조화 데이터·크롤러 정책을 얹으면 검색 노출과 AI 답변 인용에 대비할 수 있다. 인용을 보장하는 장치는 아니고, AI가 인용하기 쉬운 구조로 정리하는 쪽에 가깝다. 검색과 AI 인용을 나눠 설계하는 관점은 GEO와 SEO를 나눠 설계하는 글에서 더 깊이 다뤘다.

역할은 넷으로 나뉜다. 첫째, 사이트맵은 @astrojs/sitemap ^3.7.3으로 만들고 site를 https://seonoh.dev로 지정해 크롤러에 색인 대상 목록을 넘긴다. noindex로 표시한 글은 사이트맵에서 자동으로 빠져, 메모성·중복 글이 색인 후보로 새 나가지 않는다.

둘째, 구조화 데이터는 JSON-LD(JavaScript Object Notation for Linked Data, 연결 데이터 표기)의 @graph로 WebSite·Organization·Person을 함께 기술해, 이 글이 누가·어떤 사이트에 쓴 무엇인지를 기계가 읽도록 명시한다. 글마다 OG(Open Graph, 공유 카드용 메타데이터)와 article 메타도 붙인다.

셋째, 크롤러 정책은 robots.txt가 맡는다. GPTBot·ClaudeBot·PerplexityBot 등 AI 봇을 명시적으로 허용해, 검색 봇과 AI 봇의 접근 범위를 갈라 둔다.

넷째, AI 안내 파일로 llms.txt를 둔다. AI 에이전트가 사이트 구조와 핵심 문서를 빠르게 파악하도록 돕는 목적의 파일이다. 한편 GA(Google Analytics) 측정 ID 같은 식별값은 소스에 넣지 않고 환경 설정으로만 관리한다.

운영하며 걸렸던 함정

가장 크게 걸린 것은 URL 끝의 슬래시였다. 표준 주소(canonical)를 정규화하지 않으면 /blog/x와 /blog/x/가 서로 다른 페이지로 취급돼 색인과 지표가 갈린다. 내 사이트에서 2026-07-15 하루의 GA 데이터를 봤더니 같은 글이 14조회와 5조회로 쪼개져 잡혀 있었다. 이건 일반적인 성능·SEO 효과 수치가 아니라 특정 날짜에 내 사이트에서 관찰한 값일 뿐이지만, 끝슬래시 정규화가 필요하다는 신호로는 충분했다. 그래서 표준 주소를 끝슬래시 기준으로 정규화했다.

두 번째는 없는 경로의 처리다. Workers 설정의 404-page 처리로 커스텀 404가 응답하게 맞췄다.

세 번째는 크롤러 허용의 착각이다. robots.txt를 열어 둔 것과 크롤러가 실제로 통과하는 것은 다르니, 열어 뒀다고 단정하지 말고 접근을 직접 확인해야 한다.

배포 전 사이트맵·구조화 데이터·크롤러 정책을 순서대로 점검하는 작업 맥락

배포 전 점검표

배포 직전 아래를 순서대로 확인한다. 한 번 어긋나면 색인·인용에서 조용히 손해를 본다.

빌드 산출물이 dist에 정상 생성되는가.
wrangler.jsonc의 자산 디렉터리(./dist)·404-page·호환성 기준일이 의도대로인가.
표준 주소가 끝슬래시 기준으로 정규화되는가.
noindex 글이 사이트맵에서 실제로 빠지는가.
JSON-LD·OG·article 메타가 글마다 붙는가.
robots.txt의 AI 봇 허용과 llms.txt가 올라가 있는가.
커스텀 도메인 매핑과 DNS·SSL이 살아 있는가.

자주 묻는 질문

Astro와 Cloudflare Workers를 굳이 함께 써야 하나?

함께 쓸 의무는 없다. 다만 Astro가 만든 정적 산출물을 Workers의 정적 자산으로 얹으면, 빌드는 Astro가, 엣지 배포와 도메인·SSL은 Cloudflare가 맡아 역할이 깔끔히 나뉜다. 1인 운영에서 돌봐야 할 상태를 줄이려는 목적이라면 잘 맞는 조합이다.

배포는 명령과 push 중 무엇으로 하나?

둘 다 쓴다. 손으로 확실히 올릴 때는 npx wrangler deploy를 한 줄로 실행하고, 평소에는 저장소에 push하면 Workers Builds가 대신 빌드·배포하도록 맡긴다. 급한 수정은 명령으로, 일상 운영은 push로 나눠 쓰면 흐름이 단순해진다.

정적 사이트인데 검색·AI 인용에 불리하지 않나?

오히려 유리하다. AI 크롤러 상당수는 자바스크립트를 실행하지 않아, 본문이 처음부터 정적 HTML로 있는 편이 읽히기 쉽다. 그 위에 사이트맵·구조화 데이터·크롤러 정책을 얹으면, 검색 노출과 AI 답변 인용의 토대를 함께 갖춘다.

Cloudflare Pages가 아니라 Workers를 쓴 이유는?

둘 다 정적 사이트를 잘 올린다. 다만 Workers의 정적 자산 방식을 고르면, 나중에 같은 배포 위에서 엣지 함수나 리다이렉트 같은 동적 처리를 덧붙일 여지가 열려 있다. 지금은 순수 정적이라도 운영 도구를 하나둘 얹게 되는 1인 운영 특성상, 확장 여지를 남겨 두는 쪽을 택했다.

이 글은 AI 업무 자동화 허브의 ‘토대(사이트)’ 관련 글이다.

참고 자료

_{이 글은 개인·자동화 인프라의 내부 식별정보를 익명화해 공개 스택 중심으로 정리했으며, 사람이 검수했다. 근거가 확인되지 않은 요금·성능 수치는 단정하지 않고 체감 표현으로 완화했고, 수치를 밝힌 항목은 출처를 함께 적었다.}