바이브코딩 웹앱 2편 - Cloudflare Worker로 API 붙이기
정적 홈페이지를 올린 뒤 결과 저장, AI 호출, 로그인 같은 기능을 붙이려면 브라우저 밖의 처리가 필요해진다. 이때 프런트 코드에 API 키를 넣는 방식은 편해 보여도 공개 사이트에서는 위험하다. 세븐핑거스의 sfs_apps는 GitHub Pages의 React 화면과 Cloudflare Worker API를 나눴다. 브라우저는 공개 API 주소만 알고, 민감한 인증 정보는 Worker의 시크릿으로 처리한다.
Worker는 화면 뒤의 작은 창구다
Cloudflare Worker는 요청을 받아 필요한 로직을 실행하고 응답을 돌려주는 서버리스 실행 환경이다. sfs_apps의 Worker는 /api/nblog/...처럼 기능별 경로를 받고, 프런트는 VITE_API_URL에 설정된 공개 API 주소로 요청한다. 화면에서 입력한 주제나 선택값은 Worker에 전달되고, Worker가 검증·가공한 뒤 결과를 JSON으로 돌려준다.
이 분리는 기능을 작게 나누는 데도 도움이 된다. 프런트는 버튼 상태와 결과 화면을 담당하고, Worker는 요청 형식 확인과 외부 API 호출, 데이터 기록을 담당한다. 한쪽을 바꿔도 다른 쪽의 배포 범위를 줄일 수 있다. sfs_apps도 frontend와 workers에 각자 build·deploy 명령을 둬서 화면 변경과 API 변경을 분리했다.
비밀값은 Worker 시크릿에 둔다
브라우저에 전달되는 JavaScript는 누구나 내려받아 볼 수 있다. 따라서 OpenAI API 키나 Google 서비스 계정 JSON을 프런트 환경 변수에 넣으면 안 된다. Cloudflare는 시크릿을 Worker 런타임에서 사용할 수 있게 관리하며, 공식 문서도 민감한 값에는 시크릿 사용을 안내한다. sfs_apps의 Worker 설정 역시 OPENAI_API_KEY, GOOGLE_SERVICE_ACCOUNT_JSON, GOOGLE_SHEET_ID 등을 배포 환경의 시크릿으로 분리한다.
여기서 API 주소와 API 키를 혼동하기 쉽다. API 주소는 요청을 보낼 위치이므로 프런트에 있어도 된다. 키·토큰·서비스 계정처럼 요청 권한을 주는 값은 Worker에만 둔다. Worker는 요청을 받자마자 입력값 길이, 허용된 기능, 오류 응답을 정리해야 한다. 아무 입력이나 외부 API로 넘기면 사용량과 오류를 통제하기 어렵다.
CORS와 오류 화면도 기능의 일부
GitHub Pages와 Worker 주소는 서로 다른 도메인이 될 수 있다. 이때 Worker는 허용할 출처와 메서드를 CORS 헤더로 명시해야 브라우저 요청이 막히지 않는다. 개발 중에는 넓게 열어 두기 쉽지만, 운영에서는 실제 프런트 도메인을 기준으로 제한하는 편이 낫다. 정상 응답만 확인하지 말고 네트워크 오류, 잘못된 입력, 외부 서비스 실패 때 화면이 어떤 문장을 보여 주는지도 같이 점검해야 한다.
운영자 실전 노트
세븐핑거스(Seven Fingers Studio)는 Nblog Studio에서 이미지 생성과 이력 저장을 Worker 경유로 처리한다. 프런트에서 키를 직접 호출하지 않으니, GitHub Pages에 공개되는 빌드 파일에 민감한 JSON이 섞이는 일을 피할 수 있다. Worker 시크릿 이름을 코드와 맞춘 뒤, 배포 환경에 값이 실제로 등록됐는지 확인하는 단계는 별도로 남겨 두는 편이 안전했다.
FAQ
Q. Worker가 있으면 별도 서버를 계속 켜 둘 필요가 없나요?
Worker는 요청에 맞춰 실행되는 서버리스 방식이다. 다만 장기 연결, 복잡한 데이터베이스 처리처럼 요구사항이 커지면 다른 Cloudflare 제품이나 별도 인프라 검토가 필요할 수 있다.
Q. API 키를 깃 저장소의 비공개 파일에만 두면 안전한가요?
비공개 저장소라도 키가 커밋 기록이나 빌드 산출물에 남으면 교체가 필요해진다. 운영 키는 배포 플랫폼의 시크릿에 넣고, 이미 노출된 키는 즉시 폐기·재발급하는 방식이 낫다.