148개 중 바뀐 5개만 올리는 재배포

결론부터

• 대부분은 wrangler를 쓰면 된다. Cloudflare의 명령줄 도구 npx wrangler pages deploy 폴더가 아래 과정을 자동으로 해 줍니다.
• 원리 — 모든 파일의 지문(해시) 목록을 보내고, Cloudflare가 "없다"고 답한 파일만 올린 뒤, 목록으로 새 배포를 만듭니다. 안 바뀐 파일은 지문이 같아서 다시 올릴 필요가 없습니다.
• 함정 — 파일을 올린 뒤 upsert-hashes 단계를 빼먹으면 Cloudflare가 방금 올린 파일도 계속 "없다"고 답했습니다.

올린 5개는 새 글, 글 목록, 사이트맵, llms.txt, 공유용 대표 이미지입니다.

왜 직접 했나

저는 AI(클로드)와 함께 작업하는데, AI가 일하는 클라우드 작업 공간은 보안상 Cloudflare API 주소에 직접 접속할 수 없었습니다. 대신 제 크롬에 로그인돼 있는 Cloudflare 대시보드 탭 안에서 같은 API를 호출하는 방식으로 배포했습니다. 비밀번호나 API 토큰을 어디에 붙여 넣을 필요가 없어서 오히려 안전했습니다.

컴퓨터에서 직접 작업한다면 wrangler를 쓰는 편이 훨씬 간단합니다. 이 글은 그 안에서 무슨 일이 일어나는지, 그리고 직접 만들 때 막힌 곳을 적은 기록입니다.

바뀐 파일만 올리는 순서

1. 지문 목록 만들기 — 모든 파일마다 /blog.html → 5a3c…처럼 경로와 지문을 짝지은 목록(manifest)을 만듭니다. 지문은 파일 내용으로 계산하므로 내용이 같으면 지문도 같습니다. wrangler는 blake3(base64(내용) + 확장자)의 앞 32글자를 씁니다. 이 방식에 맞춰야 이미 올라간 파일과 지문이 맞습니다.
2. 업로드 토큰 받기 — 프로젝트의 upload-token 주소에서 짧게 쓰는 업로드용 토큰을 받습니다.
3. 없는 파일 묻기 — 지문 전체를 check-missing으로 보내면, Cloudflare가 가지고 있지 않은 지문만 돌려줍니다.
4. 없는 파일만 올리기 — 그 파일들만 upload로 보냅니다.
5. 지문 등록 (빠뜨리기 쉬움) — 지문 전체를 upsert-hashes로 한 번 더 보냅니다.
6. 배포 만들기 — 지문 목록과 _headers 파일을 함께 deployments로 보내면 새 배포가 생기고, 몇 초 뒤 실제 주소에 반영됩니다.

막혔던 곳 1 — 올렸는데 계속 없다고 한다

4단계까지 하고 다시 check-missing을 물으면, 방금 올린 파일들이 여전히 "없음"으로 나왔습니다. 업로드 응답은 성공이었는데도요.

5단계 upsert-hashes를 호출한 뒤에야 "없음"이 0개가 됐습니다. 업로드만으로는 파일이 프로젝트에 연결되지 않고, 이 단계에서 "이 지문들은 이 프로젝트 것"이라고 등록되는 것으로 보입니다. 이후 모든 배포에서 업로드 직후 이 단계를 넣고, 배포 전에 "없음 0개"를 확인하도록 했습니다.

막혔던 곳 2 — 설정 파일은 목록에 넣지 않는다

_headers(캐시 시간, 보안 헤더 같은 설정)와 _redirects는 일반 파일처럼 지문 목록에 넣는 게 아니라, 배포를 만들 때 따로 첨부합니다. 이 사이트는 _headers로 다음을 정해 둡니다.

• 드럼 추출기(/drum/*)의 교차 출처 격리 헤더 — 브라우저 AI가 여러 CPU 코어를 쓰는 데 필요
• 사진·글꼴은 길게, 게임 본체는 매번 확인하는 캐시 시간

그래서 배포할 때마다 _headers를 빼먹지 않고 같이 보냅니다. 캐시 시간을 정한 이유는 홈 화면 사이트가 옛 버전으로 뜰 때에 있습니다.

실수를 막는 확인 장치

• 목록 체크섬 — 배포 전에 브라우저에 있는 지문 목록 전체를 다시 지문으로 만들어(SHA-256), 작업 공간에서 계산한 값과 같은지 비교합니다. 다르면 배포하지 않습니다.
• 파일 크기 확인 — 올리려는 파일 크기가 예상과 다르면 멈춥니다. 한 번은 옛 파일이 올라갈 뻔한 것을 이걸로 잡았습니다.
• 배포 뒤 실제 주소 확인 — 새 글 주소, 대표 이미지, 사이트맵이 200(정상)으로 열리는지 확인합니다.

참고한 자료

• Cloudflare Pages 직접 업로드 (공식 문서)
• Cloudflare Pages 한도 (공식 문서)