풀스택
어느 날 갑자기 API가 전부 죽었다 — Cloudflare workers.dev 서브도메인이 바뀌면 벌어지는 일
EasyPrompt 운영 기록
증상: "처음이에요"만 되고 나머지는 다 안 됨
사용자한테서 제보가 왔다.
"프롬프트 찾기 들어가면 'AI 처음이에요' 빼고 나머지는 다
'프롬프트를 불러오지 못했습니다'라고만 떠요."
EasyPrompt의 "찾기" 메뉴는 카드 4개로 되어 있다.
| 카드 | 경로 | 백엔드 호출 |
|---|---|---|
| AI 처음이에요 | /guide | 없음 (정적 페이지) |
| 일반사용자용 | /senior | GET /categories → GET /prompts |
| 사무용 프롬프트 활용하기 | /prompts | GET /categories → GET /prompts |
| AI 코딩 입문 | /coding | GET /categories → GET /prompts |
증상을 듣자마자 범위가 좁혀졌다. 유일하게 멀쩡한 "AI 처음이에요"는
백엔드를 전혀 부르지 않는 순수 정적 페이지다. 나머지 셋은 전부
GET /categories 로 카테고리를 받아온 뒤 그 id로 GET /prompts 를
호출한다. 셋이 동시에 죽었다는 건 공통 의존성인 백엔드 API가
문제라는 뜻이다. 프론트엔드 코드 문제가 아니다.
진단 1: CORS부터 의심했지만 아니었다
Cloudflare Workers 백엔드는 CORS 허용 오리진을 딱 두 개만 열어둔다.
cors({
origin: ['http://localhost:5173', 'https://easyprompt.pages.dev'],
credentials: true,
})"계정 분리 배포" 작업을 최근에 했던 터라, 사이트가 다른 도메인에서
서빙되면서 CORS에 막히는 시나리오를 먼저 떠올렸다. 하지만 사용자가
보내준 브라우저 개발자도구 스크린샷이 이 가설을 바로 깼다.
- 주소창:
https://easyprompt.pages.dev/senior→ 이미 허용된 오리진 - Network 탭의
categories요청: "Provisional headers are shown",
응답 헤더 없음, 상태 코드 없음
이 "Provisional headers are shown" 이 핵심이다. CORS 차단이라면
서버 응답은 도착하고 브라우저가 그걸 막는 형태라 상태 코드(200, 403 등)가
찍힌다. 응답 자체가 아예 없다는 건 요청이 서버에 도달조차 못 했다는
뜻이다. 네트워크 레벨, 즉 DNS나 연결 단계에서 실패했다.
진단 2: DNS를 찍어보니 도메인이 통째로 없었다
$ nslookup backend-hono.asdf1378kk.workers.dev
*** Non-existent domain
$ nslookup asdf1378kk.workers.dev
*** Non-existent domain워커 주소만이 아니라 계정 서브도메인(asdf1378kk.workers.dev) 자체가
NXDOMAIN이다. 이 프로젝트는 2026-07-31부터 이 주소를 API 엔드포인트로
써 왔고, 그동안 잘 돌아갔다. 그런데 지금은 존재하지 않는다.
한편 확인해보니:
- Worker 스크립트
backend-hono는 계정에 여전히 배포되어 있음
(마지막 배포 2026-08-03,wrangler deployments list로 확인) - 원격 D1
easyprompt-db도 멀쩡함: 카테고리 7개, 프롬프트 74개
코드도 데이터도 살아 있는데, 바깥에서 접근할 주소만 사라진 상태였다.
근본 원인: workers.dev 서브도메인이 리네임됐다
Cloudflare의 *.workers.dev 무료 서브도메인은 계정마다 하나씩 고른다.
<워커이름>.<계정서브도메인>.workers.dev 형태다. 이 계정의 서브도메인이
어느 시점엔가 asdf1378kk 에서 heohyuk 로 바뀌었다(계정/서브도메인
리네임 추정, 8월 말 "계정 분리" 작업 즈음). 서브도메인이 바뀌는 순간
기존 *.asdf1378kk.workers.dev 라우트는 전부 즉시 무효가 된다.
리다이렉트도 없다. 그냥 사라진다.
wrangler deploy 를 다시 돌리자 실제 주소가 튀어나왔다.
$ npx wrangler deploy
...
Deployed backend-hono triggers
https://backend-hono.heohyuk.workers.dev ← 진짜 주소
Current Version ID: a01b4d40-...$ curl -s https://backend-hono.heohyuk.workers.dev/categories
[{"id":1,"name":"경영기획",...}, ... 7개] ← HTTP 200, 정상복구 절차
-
Worker 재배포 —
backend-hono/에서npm install후
npx wrangler deploy. 새 주소backend-hono.heohyuk.workers.dev확인.
덤으로 2026-08-03 이후 배포 안 됐던 커밋 9개(시드 데이터,point_reason
컬럼 등)도 이때 함께 반영됐다. -
프론트엔드 설정의 URL 일괄 교체 —
frontend/.env.local,
frontend/.env.example,README.md(2곳),backend-hono/README.md의
backend-hono.asdf1378kk.workers.dev→backend-hono.heohyuk.workers.dev. -
프론트엔드 재빌드 + 배포 —
VITE_API_BASE_URL은 빌드 타임에
번들로 구워진다.npm run build후
wrangler pages deploy dist --project-name=easyprompt --branch=main.
빌드된 JS 번들에 새 URL이 들어갔는지grep으로 확인. -
Cloudflare Pages 프로젝트 환경변수도 수정 — 이게 함정이다.
Pages 대시보드(Settings → Variables and Secrets)에 저장된
VITE_API_BASE_URL이 아직 옛 주소였다. 이걸 안 고치면 다음번
GitHub push 로 자동 빌드가 돌 때 옛 주소로 원복된다.
Production / Preview 둘 다 새 주소로 변경.
검증
커밋 f95d08f 를 push 하니 GitHub 연동 자동 빌드 cc1b3d5f 가
Production 으로 떴다. 확인 포인트:
- 자동 빌드 번들의 API URL =
backend-hono.heohyuk.workers.dev✓
(대시보드 환경변수가 제대로 반영됐다는 증거) easyprompt.pages.dev가 그 번들(index-BDmTusTh.js)을 서빙 ✓/categories→ HTTP 200 ✓/senior등 목록 페이지 정상 동작 ✓
배운 것
-
정적 페이지 하나가 살아 있으면 그게 진단 도구다. "뭐는 되고 뭐는
안 되는지"의 경계선이 곧 원인의 위치를 가리킨다. API 안 부르는
페이지만 멀쩡 → 프론트가 아니라 백엔드/네트워크. -
"Provisional headers are shown" = 응답을 못 받았다. CORS 차단과
네트워크 실패를 개발자도구에서 구분하는 가장 빠른 신호. CORS는
상태 코드가 찍히고, 네트워크 실패는 안 찍힌다. -
무료
*.workers.dev주소를 프로덕션 API 엔드포인트로 쓰면
서브도메인 이름에 인프라가 묶인다. 계정 서브도메인은 대시보드에서
바꿀 수 있고, 바뀌면 기존 주소는 리다이렉트 없이 죽는다. 장기적으로는
커스텀 도메인(api.example.com)을 워커에 라우트로 붙이는 게 안전하다. -
빌드 타임 환경변수는 두 군데 있다. 레포의
.env파일과 배포
플랫폼(Pages/Vercel/Netlify)의 프로젝트 설정. 수동 배포로 급한 불을
꺼도 플랫폼 설정을 안 고치면 다음 자동 빌드가 되돌린다. 둘 다 고쳐야
끝이다. -
코드가 배포돼 있다 ≠ 접근 가능하다.
wrangler deployments list
에 배포 이력이 있어도 라우트(workers.dev든 커스텀 도메인이든)가
살아 있지 않으면 아무도 못 부른다. "배포됨"과 "라우팅됨"은 별개
상태다.
