Astro + Cloudflare 사이트를 기능별로 확장하는 전체 설계

Astro와 Cloudflare에 CMS나 검색을 추가하기 전에 편집 담당자, 공개 데이터, 사용자별 처리를 구분하세요. 글은 정적 생성하고 제출이나 외부 API 호출은 Functions로 처리하는 구성을 기준으로 Cloudflare Pages: Bindings에서 필요한 연결만 확인하면 도입 범위를 줄일 수 있습니다.

2026년 9월 26일 추가: 이 글은 2026년 6월의 아키텍처를 기록합니다. 이후 소스 코드에서는 CMS 저장 시 권한·내용·HEAD를 검사한 뒤 GitHub App을 통해 main에 직접 커밋합니다. 번역은 OpenAI Batch와 번역 PR을 사용하고, 문의 AI는 Service Binding으로 공통 Worker를 호출합니다. 아래의 Copilot 번역, CMS의 PR 저장, AI API 직접 호출 설명은 당시 구현입니다. 각 경로는 CMS 안내, 번역 안내, AI 안내를 참고하세요.

Astro와 Cloudflare Pages로 정적 사이트를 만들 때는 처음에는 빠르고 안전하게 페이지를 배포하는 것만으로 충분합니다.

하지만 운영을 계속하면 브라우저 편집, 다국어 페이지, AI 채팅 안내, 서비스 페이지에서 폼으로 문맥 전달, 댓글 기능 같은 요구가 생깁니다.

이 글은 구현 인덱스입니다. 각 기능을 어느 레이어에 둘지, 어떤 순서로 넣을지, 다음에 어떤 상세 글을 읽을지 정리합니다. Acecore 공식 사이트를 예로 들지만, 같은 구조는 다른 Astro + Cloudflare 사이트에도 적용할 수 있습니다.

요약

역할은 다음처럼 나눕니다.

레이어	역할
Astro	페이지, 블로그, OGP, RSS, sitemap, UI
Cloudflare	Pages, Pages Functions, D1, Turnstile
GitHub	PR, CMS diff, 번역 diff, 변경 이력
Sveltia CMS	일본어 source, 작성자, 태그, 이미지
OpenAI API	문의 AI 응답 생성
Pagefind	검토된 정적 HTML의 사이트 검색 인덱스

정적으로 만들 수 있는 것은 정적으로 둡니다. 요청 시 처리가 필요한 부분만 작은 API로 보냅니다.

동적 기능은 작은 API로 둔다

문의 AI와 댓글 기능은 같은 패턴입니다.

Astro는 UI를 렌더링합니다. Pages Functions는 API 경계를 담당합니다. secret, D1 binding, Turnstile, Origin 체크, rate limit은 브라우저에 노출하지 않습니다.

CMS는 편집 UI다

Sveltia CMS는 런타임 DB가 아니라 Git 변경을 만드는 편집 UI입니다.

일본어 글, 작성자, 태그, 이미지, JSON 문구는 PR, build, review를 거쳐 공개됩니다.

다국어는 정적 콘텐츠다

다국어 운영은 브라우저 UI 번역이 아닙니다.

각 언어는 URL, title, description, OGP, JSON-LD, RSS, sitemap, hreflang을 가집니다.

문의 도선은 역할을 나눈다

AI 채팅은 아직 어떤 서비스가 맞는지 모르는 방문자에게 좋습니다. 서비스 CTA는 읽고 있던 서비스 문맥을 보존합니다. 폼은 공식 문의를 기록합니다.

AI 출력은 신뢰된 HTML이 아니다

AI가 Markdown 링크를 반환해도 그대로 innerHTML에 넣지 않습니다.

필요한 표현만 파싱하고, allowlist를 통과한 링크만 DOM으로 만듭니다.

댓글은 Cloudflare 안에 둔다

댓글은 외부 위젯이 아닙니다.

Pages Functions가 GET/POST를 받고, D1이 저장하고, Turnstile이 제출을 보호합니다.

1. 1 검토된 정적 본문 검토된 글을 정적 HTML로 제공하고 Pagefind 사이트 검색 색인에 포함합니다.
2. 2 방문자 게시물 댓글은 동적 API와 저장소에서 처리하고 폼 등 방문자 입력은 정적 검색에서 제외합니다. 색인에 넣으려면 검토와 재생성이 필요합니다.
3. 3 관리 화면과 환경 확인 관리 화면을 공개 검색에서 제외합니다. Preview와 운영을 따로 확인하고 설정 목록만으로 가동을 판단하지 않습니다.

목적별로 읽기

처음부터 전부 읽을 필요는 없습니다. 추가하려는 기능부터 보면 됩니다.

하고 싶은 일	먼저 읽을 글
브라우저에서 글과 이미지를 편집하기	Sveltia CMS 도입 가이드
다국어 페이지를 검색 대상으로 만들기	Sveltia CMS로 다국어 블로그 운영하기
AI 채팅으로 방문자를 안내하기	Astro 사이트에 문의 AI 채팅을 넣는 기술 설계
AI 답변 링크를 안전하게 렌더링하기	AI 채팅 답변의 Markdown 링크 안전 렌더링
서비스 문맥을 폼으로 넘기기	서비스 CTA 문맥을 문의 폼으로 전달하는 설계
외부 서비스 없이 댓글 기능 넣기	Cloudflare만으로 Astro 블로그 댓글 기능 만들기

추천 구현 순서

비슷한 구성을 다른 사이트에 넣는다면 실무 순서는 다음과 같습니다.

1. Astro로 정적 페이지, 블로그, RSS, sitemap, OGP를 먼저 굳힙니다.
2. Sveltia CMS로 일본어 source를 편집할 수 있게 합니다.
3. 다국어 페이지를 정적 HTML로 생성합니다.
4. AI 채팅과 서비스 CTA로 상담 도선을 정리합니다.
5. Markdown 링크, 폼 prefill, Origin 체크, rate limit의 안전 경계를 굳힙니다.
6. 필요해진 시점에 Cloudflare 안에서 댓글 기능을 추가합니다.

정리

Astro + Cloudflare는 정적 배포의 장점을 유지하면서도 공식 사이트를 계속 확장할 수 있습니다.

이 페이지를 입구로 삼으면 정적 사이트의 기반을 유지하면서 필요한 기능만 골라 확장할 수 있습니다.

보충: Worker 환경과 빌드 설정 분리

2026년 9월 30일 추가. 관련 빌드 설정 개선을 서비스 이름과 내부 값 없이 일반 원칙으로 정리합니다. 한 저장소의 여러 Worker는 Wrangler 설정, 소스 루트, 빌드·배포 대상을 각각 연결합니다. 파일 분리만으로 환경 격리가 입증되지는 않습니다.

운영과 시험별 변수, 비밀값, D1·R2·Service Binding 연결 대상을 확인합니다. Worker 환경의 bindings와 변수는 자동 상속되지 않으므로 환경별로 선언합니다. 필수 설정이 없으면 운영 자원으로 조용히 전환하지 말고 처리를 중단합니다. 지속적인 staging과 브랜치·PR Preview도 서로 다른 흐름입니다.

운영 반영 경로를 하나로 정하고 사전 검증을 요구합니다. 비운영 빌드나 버전 업로드는 확인용이며 성공만으로 운영에 승격된 것으로 보지 않습니다. Git 빌드는 브랜치, commit, 루트, 선택한 설정·환경, 배포 명령을 확인합니다. Pages 공개 성공이 별도 Worker 배포를 뜻하지는 않습니다. CI, 운영 빌드, 실제 버전·연결 대상, 도메인 동작을 각각 확인합니다. 이는 다른 환경에 적용할 때의 점검 항목이며 모든 서비스의 격리를 입증했다는 뜻이 아닙니다.

Cloudflare의 Worker 환경, 다중 Worker Builds, 빌드 설정을 참고하세요. Pages Functions 설정은 따로 구분합니다.

보충: 외부 피드 재시도와 장애를 입력원별로 분리

2026년 9월 30일 추가. RSS 등 공개 피드를 가져오는 작업은 RSS를 내보내는 작업과 별개입니다. 대기 시간과 재시도 횟수를 제한해 일시적 실패로 작업이 무한히 이어지지 않게 합니다.

입력원별 실패를 따로 다룹니다. 하나의 가져오기가 실패해도 독립적으로 갱신할 수 있는 다른 입력까지 중단하지 않습니다. 일부 성공을 전체 성공으로 보고하지 말고 입력원별 결과와 남은 실패를 보고서에 남깁니다. 가져오기, 생성 데이터, 운영 빌드, 공개 페이지도 따로 확인합니다. 일반적인 설계 점검이며 모든 장애 조건이나 향후 입력원 적용을 입증한 것은 아닙니다.

2026년 10월 6일 추가: API 계약과 첨부 검증 범위

익명화한 개선은 frontend/backend의 session·limit 계약 불일치로 처리 성공 뒤 응답이 503이 되는 경로를 수정했습니다. HTTP 결과·저장 상태·UI 표시를 별도로 대조하며 클라이언트 재전송으로 쓰기가 중복되지 않게 처리합니다.

첨부 칸 표시와 실제 파일 전송·저장·재조회 검증은 다릅니다. UI·API 수정만으로 후자를 완료로 보지 않습니다. 비공개 관리 경계는대시보드 인증과 집계, 결제 외부 상태 대조는Webhook 상태 관리에서 설명합니다.