Cloudflare Pages 배포

이 문서 사이트는 moa-laravel 안의 일부 디렉터리입니다. 전체 Laravel 저장소를 Cloudflare Pages Git 연동에 연결하지 않고, storefront-api-docs에서 직접 빌드한 dist 폴더만 Cloudflare Pages에 업로드합니다.

권장 방식

Cloudflare Pages의 Direct Upload 방식을 사용합니다.

GitHub/GitLab 저장소 연결을 사용하지 않습니다.
Cloudflare가 moa-laravel 전체를 빌드하지 않습니다.
문서 패치 후 로컬에서 cd storefront-api-docs로 들어가 직접 배포합니다.

첫 배포

처음 한 번은 Wrangler 로그인을 하고 Pages 프로젝트를 만듭니다.

cd storefront-api-docs
npm install
npx wrangler login
npx wrangler pages project create

프로젝트 이름은 예를 들어 아래처럼 지정합니다.

runmoa-developer-docs

Wrangler가 production branch를 물어보면 main을 입력합니다. Git 연동은 아니지만 Cloudflare Pages가 production/preview 배포를 구분하기 위해 사용하는 값입니다.

그 다음 빌드 후 업로드합니다.

npm run build
npx wrangler pages deploy dist

배포가 끝나면 Cloudflare가 *.pages.dev URL을 출력합니다.

이후 패치 배포

문서만 수정한 뒤에는 아래 명령만 사용합니다.

cd storefront-api-docs
npm run deploy

npm run deploy는 내부적으로 아래 작업을 실행합니다.

npm run build
npx wrangler pages deploy dist

Preview 배포가 필요할 때는 아래 명령을 사용합니다.

cd storefront-api-docs
npm run deploy:preview

도메인 연결

권장 도메인 예시:

developers.runmoa.com

Cloudflare Pages 프로젝트의 Custom domains에서 도메인을 추가합니다. DNS가 Cloudflare에서 관리되는 경우 CNAME 레코드는 대시보드에서 자동으로 추가될 수 있습니다.

도메인을 연결한 뒤 아래 URL을 확인합니다.

https://developers.runmoa.com/
https://developers.runmoa.com/llms.txt
https://developers.runmoa.com/llms-full.txt
https://developers.runmoa.com/openapi.yaml
https://developers.runmoa.com/sitemap-index.xml

배포 산출물

빌드 결과에는 아래 파일이 포함되어야 합니다.

파일	역할
`/index.html`	문서 홈
`/_astro/*`	Starlight/Astro 정적 자산
`/openapi.yaml`	OpenAPI YAML
`/llms.txt`	AI용 짧은 문서 지도
`/llms-full.txt`	AI용 전체 요약 문서
`/sitemap-index.xml`	검색 엔진과 crawler용 sitemap index
`/_headers`	Cloudflare Pages 헤더 설정

운영 체크리스트

Cloudflare Pages 프로젝트가 Git integration이 아니라 Direct Upload 프로젝트인지 확인합니다.
배포는 항상 storefront-api-docs 디렉터리 안에서 실행합니다.
openapi.yaml, llms.txt, llms-full.txt가 배포 URL에서 열리는지 확인합니다.
문서 검색에서 결제 초기화, Schoolmoa, 서버용 비공개 API, 상품 생성 같은 키워드가 검색되는지 확인합니다.
외부 문서에는 내부 라우트명이나 deprecated 경로가 노출되지 않는지 확인합니다.