techlog

Astro 블로그를 Cloudflare Pages에 배포하고 Worker 초안을 배포하는 방법

· cloudflare, astro, pages, workers, wrangler

배경

GitHub 저장소와 Astro 7 정적 빌드(Node 22.23.4 이상)를 사용한다. main 브랜치가 정식 사이트가 되고, 다른 브랜치는 미리보기 URL로 자동 배포한다. 주제 입력용 폼을 통해 Workers AI가 초안을 작성하고 GitHub에 draft PR을 여는 별도 Worker도 배포한다.

Cloudflare Pages 연결

대시보드 Workers & Pages에서 Create 버튼을 누르면 기본 화면은 Worker 생성 화면이다. 화면 맨 아래 “Looking to deploy Pages?” 링크를 클릭해 Pages 설정 화면으로 이동한다. Pages → Connect to Git → 저장소를 선택하고 다음과 같이 설정한다.

설정 후 정식 주소는 <프로젝트>.pages.dev가 된다. 브랜치마다 <브랜치명>.<프로젝트>.pages.dev 형태의 미리보기 URL이 자동 생성된다. PR이 열리면 Cloudflare 봇이 PR에 미리보기 URL을 댓글로 달아준다. Draft 글은 빌드 환경변수 CF_PAGES_BRANCH가 main이 아닐 때만 보이게 하여 미리보기에서만 확인하도록 구성한다.

Workers Builds 체크 오류

PR에 “Workers Builds: techlog” 체크가 실패한다. 오류 메시지는 “Preview creation failed: This Worker does not exist on your account.”이다. 원인은 Pages 프로젝트와 동일한 이름의 Worker가 계정에 존재하지 않아 발생한다. 대시보드에서 해당 Worker 항목을 삭제하면 오류가 사라진다. Pages와 Worker는 이름이 같아도 별개의 리소스임을 기억한다.

원격 SSH 서버에서 wrangler 로그인

npx wrangler login은 브라우저를 열어 OAuth 인증을 수행하고, http://localhost:8976/oauth/callback?code=… 로 콜백한다. SSH 환경에서는 로컬 브라우저가 서버의 localhost에 접근할 수 없으므로 로그인에 실패한다. 두 가지 해결 방법을 사용한다.

  1. 로그인 시 표시된 콜백 주소를 복사하고, 서버의 다른 SSH 창에서 curl "<주소>" 를 실행한다. wrangler가 콜백을 받아 로그인 절차가 완료된다.
  2. ssh -L 8976:localhost:8976 서버 로 포트 포워딩을 설정하고, 로컬 브라우저에서 로그인한다.

wrangler는 인증 정보를 서버 사용자 계정에 저장하므로 폴더와 무관하게 재사용할 수 있다.

wrangler secret 설정 및 배포

wrangler secret put GITHUB_TOKEN "값" 형태로 값을 바로 전달하면 Unknown argument 오류가 발생한다. 명령만 입력하면 터미널에서 값을 물어보도록 설계돼 있어 셸 기록에 토큰이 남지 않는다.

wrangler secret put GITHUB_TOKEN
# 프롬프트에 토큰 입력

Required Worker name missing 오류는 wrangler.jsonc 파일이 없는 작업 디렉터리에서 명령을 실행했기 때문이다. git pull 후 worker/ 디렉터리가 비어 있으면 해당 오류가 발생한다.

git pull
cd worker
npm install

npm run deploy 를 실행하면 *.workers.dev 주소가 생성된다. 접속 시 Basic 인증 화면이 나타나며, 사용자 이름은 임의로 입력하고 비밀번호는 FORM_PASSWORD 로 설정한다.

npm run deploy
# 배포 완료 후
curl https://my-worker.workers.dev
# Basic 인증 화면 확인

정리

Cloudflare에서는 Pages와 Workers가 독립적인 리소스로 관리된다. 대시보드에서 Pages 프로젝트를 생성할 때 Workers 항목을 별도로 삭제해야 체크 오류가 사라진다. 원격 SSH 서버에서 OAuth 로그인은 콜백 URL을 curl 로 직접 호출하거나 포트 포워딩을 이용해 해결한다. wrangler secret put 은 프롬프트 입력 방식을 사용해 토큰이 셸 기록에 남지 않도록 설계돼 있다. 이러한 절차를 따라 Astro 블로그와 주제 초안 Worker를 안전하게 배포할 수 있다.