소개
상태 확인 엔드포인트는 애플리케이션이 응답 중인지 알려 주는 작은 URL 입니다. 이 실습에서는 JavaScript Cloudflare Worker 를 작성하고, LabEx 안에서 JSON 응답을 테스트하고, 같은 코드를 공개 workers.dev URL 에 배포하고, 요청 로그 하나를 확인한 다음 테스트 배포를 삭제합니다.
Prepare Your Cloudflare Learning Account에서 준비한 인증된 이메일과 Workers Free 가 적용된 학습 계정을 사용합니다. Connect LabEx to Your Cloudflare Account에서 사용한 디바이스 인증 절차를 알고 있어야 하며, JavaScript 기본 지식이 필요합니다. 이 새 VM 에서도 별도의 인증이 필요하고, Worker 를 배포하고 삭제할 수 있는 권한을 부여해야 합니다. 구매한 도메인, 데이터베이스 또는 유료 업그레이드는 필요하지 않습니다. 테스트 응답은 공개되며 샘플 데이터만 포함합니다.
설정 과정에서 Node.js 22.22.0 과 프로젝트 로컬 Wrangler 4.131.1 이 /home/labex/project/first-worker에 설치되었습니다. Wrangler 로 계정 정보를 확인하고 curl 로 응답을 테스트합니다. 이 도구들은 LabEx 외부에서도 사용할 수 있습니다. Worker 와 설정 파일은 직접 작성하고 표준 Wrangler 명령을 실행합니다. 삭제와 로그아웃이 확인될 때까지 이 VM 을 종료하지 마세요.
상태 확인용 Worker 작성
이 단계에서는 JavaScript 진입점 파일을 만들고 Wrangler 가 이를 실행하는 방법을 지정합니다. Worker 는 fetch 핸들러를 내보냅니다. Cloudflare 는 들어오는 HTTP 요청마다 이 핸들러를 호출하고, 핸들러가 반환한 Response를 HTTP 응답으로 사용합니다. 이 첫 번째 Worker 는 모든 경로에 같은 상태 메시지를 반환합니다. 라우팅은 다음 실습에서 다룹니다.
준비된 프로젝트 디렉터리로 이동하고 CLI 버전을 확인합니다.
cd /home/labex/project/first-worker
npx wrangler --version
버전은 4.131.1이어야 합니다. Wrangler 는 프로젝트 의존성이므로 이 디렉터리에서 명령을 실행해야 합니다. 개인 컴퓨터에서는 lockfile 이 제공된 프로젝트의 고정된 의존성을 npm ci로 설치합니다.
다음 명령은 here-document를 사용합니다. cat은 <<'WORKER'와 WORKER 사이의 줄을 src/index.js에 씁니다. >는 해당 파일을 덮어씁니다. 구분자를 따옴표로 감싸면 셸이 JavaScript 텍스트를 변경하지 않습니다. 마지막 구분자를 포함한 전체 블록을 붙여 넣으세요.
cat > src/index.js <<'WORKER'
export default {
async fetch(request) {
console.log("health-request", request.method, new URL(request.url).pathname);
return Response.json({ service: "labex-first-worker", status: "ok" });
},
};
WORKER
Response.json은 상태 코드 200 과 JSON 콘텐츠 유형을 사용하는 JSON 응답을 만듭니다. 콘솔 메시지는 헤더나 인증 정보를 기록하지 않고 요청 메서드와 경로를 기록합니다.
기존 Worker 를 덮어쓰지 않도록 고유한 이름을 생성합니다. Node.js 의 내장 crypto 모듈은 임의의 6 바이트를 생성하고 이를 12 개의 16 진수 문자로 표시합니다. $(...)는 해당 텍스트를 셸 변수에 저장합니다.
WORKER_NAME="labex-first-$(node -p "require('node:crypto').randomBytes(6).toString('hex')")"
설정 파일을 만듭니다. 여기서는 구분자를 따옴표로 감싸지 않았으므로 $WORKER_NAME이 고유한 값으로 확장됩니다.
cat > wrangler.jsonc <<CONFIG
{
"name": "$WORKER_NAME",
"main": "src/index.js",
"compatibility_date": "2026-09-14",
"workers_dev": true,
"preview_urls": false
}
CONFIG
main은 JavaScript 파일을 지정합니다. compatibility_date는 런타임 호환성 동작을 선택하는 값이며 배포 시각이 아닙니다. workers_dev는 공개 테스트 URL 을 활성화하고, preview_urls는 추가 버전 미리보기 URL 을 비활성화합니다. 주석이 없는 JSON 은 유효한 JSONC 입니다. 이 실습에서는 표시된 형식을 사용합니다.
cat wrangler.jsonc
이름이 labex-first-로 시작하고 고유한 접미사가 포함되어 있는지 확인합니다. 실습 전체에서 이 이름을 유지하세요. 배포와 삭제 대상이 이 이름으로 지정됩니다. 계정 인증이 끝난 후 계정 ID 를 추가합니다.
단계의 검증 버튼을 사용해 설정과 핸들러를 확인합니다. 다음 단계에서는 로컬 런타임을 통해 직접 응답을 확인합니다.
로컬에서 Worker 실행 및 테스트
이 단계에서는 Worker 를 게시하기 전에 VM 안에서 실행합니다. Wrangler 의 로컬 런타임은 클라우드에 배포하지 않고 핸들러를 실행합니다.
같은 터미널에서 HTTP 요청을 보낼 수 있도록 개발 서버를 백그라운드에서 시작합니다. --ip 0.0.0.0은 VM 서비스를 LabEx 웹 인터페이스에서 사용할 수 있게 하고, --port 8080은 포트를 지정합니다. > local.log는 표준 출력을 저장하고, 2>&1은 오류를 같은 파일로 보내며, &는 서버가 실행되는 동안 터미널 프롬프트를 반환합니다.
npx wrangler dev --ip 0.0.0.0 --port 8080 > local.log 2>&1 &
cat local.log
로그에 서버가 포트 8080 에서 준비되었다고 표시될 때까지 기다립니다. 아직 시작 중이라면 계속하기 전에 cat local.log를 다시 실행합니다. 이 단계가 끝날 때까지 서버를 실행 상태로 유지하세요.
curl로 요청을 보냅니다. -i는 응답 헤더를 포함하므로 상태 코드와 콘텐츠 유형을 모두 확인할 수 있습니다.
curl -i http://127.0.0.1:8080/health
응답에는 다음과 같은 안정적인 값이 포함됩니다. 헤더 순서와 대소문자는 달라질 수 있습니다.
HTTP/1.1 200 OK
Content-Type: application/json
...
{"service":"labex-first-worker","status":"ok"}
주소 127.0.0.1은 이 VM 을 가리킵니다. 개인 컴퓨터나 공개 Cloudflare 배포를 가리키지 않습니다. 계속하기 전에 HTTP 상태 코드, JSON 콘텐츠 유형 및 두 응답 필드를 확인합니다.
개발 서버가 계속 실행 중인 상태에서 이 단계의 검증을 완료합니다.
Cloudflare 인증 및 배포
이 단계에서는 이 VM 을 학습 계정에 연결하고 테스트한 Worker 를 배포합니다. 먼저 백그라운드 작업을 확인합니다. jobs는 이 터미널에서 시작한 작업을 나열하며, 항목에 wrangler dev가 표시되어야 합니다.
jobs
kill %1로 해당 작업을 중지합니다. 여기서 %1은 시스템 프로세스 ID 가 아니라 이 터미널의 작업 1 을 의미합니다. jobs에 wrangler dev가 다른 번호로 표시되면 그 번호를 사용합니다. 이 명령은 해당 작업에 종료 신호를 보냅니다.
kill %1
디바이스 인증을 시작합니다. 읽기 범위는 계정을 식별하고, workers_scripts:write는 스크립트 배포와 삭제를 허용하며, workers_tail:read는 실시간 로그 확인을 허용합니다. --browser=false는 직접 브라우저에서 열 수 있는 링크를 출력합니다.
npx wrangler login --device --browser=false --scopes account:read user:read workers_scripts:write workers_tail:read
표시된 링크를 열고, 요청되면 Cloudflare 에 로그인한 후 현재 디바이스 코드를 입력하고 Wrangler 의 권한 요청을 검토합니다. 모든 계정이 아니라 학습 계정을 선택합니다. 동의 페이지에는 필요한 Background Access도 포함되어 있습니다. 애플리케이션, 계정 및 권한을 확인한 후에만 승인하세요. 그런 다음 터미널로 돌아와 인증이 완료될 때까지 기다립니다. 코드가 만료되면 로그인 명령을 다시 실행해 새 코드를 받습니다. 토큰을 터미널에 붙여 넣거나 인증 정보 파일을 공유하지 마세요.
Account & Billing과 Developer Platform을 펼쳐 아래에 표시된 권한 이름을 확인합니다. 이 실습에서는 Worker 를 배포하고 실시간 로그를 열기 때문에 읽기 전용 연결 실습보다 더 광범위한 권한이 필요합니다.
학습 계정이 선택되었는지 확인합니다. 잘못된 계정 또는 모든 계정이 선택되었다면 Edit를 사용해 수정하고, Authorize를 클릭하기 전에 선택 내용을 다시 확인합니다.
이 로그인에서 사용할 수 있는 계정을 확인합니다.
npx wrangler whoami --json
"loggedIn": true와 "authType": "OAuth Token"을 확인합니다. accounts 배열에서 학습 계정의 name과 일치하는 객체를 찾고 32 자 id를 복사합니다. 이 실습에는 다른 계정 설정이 필요하지 않습니다. 계정이 하나만 표시되어도 이름을 확인합니다. 여러 계정이 표시되면 Dashboard 에서 구분합니다. 계정이 없으면 의도한 계정을 선택해 인증을 다시 수행합니다.
설정에 account_id를 추가합니다. 실행하기 전에 이 블록의 YOUR_ACCOUNT_ID를 복사한 ID 로 바꿉니다. 이 명령은 1 단계의 $WORKER_NAME 변수를 유지하면서 설정 파일을 다시 작성합니다. 터미널을 계속 열어 두세요. 변수를 잃어버렸다면 cat wrangler.jsonc로 원래 이름을 확인하고, 먼저 WORKER_NAME을 정확히 같은 이름으로 복원합니다. 배포 후에는 새 이름을 생성하거나 계정을 변경하지 마세요.
cat > wrangler.jsonc <<CONFIG
{
"name": "$WORKER_NAME",
"main": "src/index.js",
"compatibility_date": "2026-09-14",
"workers_dev": true,
"preview_urls": false,
"account_id": "YOUR_ACCOUNT_ID"
}
CONFIG
cat wrangler.jsonc
고유한 Worker 이름을 확인하고 account_id를 whoami --json에서 확인한 의도한 계정 객체의 ID 와 비교합니다. 이 ID 는 비밀번호가 아니라 설정 값입니다. Wrangler 는 배포와 삭제 시 이 값을 읽습니다. 이제 로컬 소스를 게시합니다.
npx wrangler deploy
이 계정에 아직 workers.dev 서브도메인이 없으면 Wrangler 가 등록 여부를 묻습니다. yes라고 답하고, 문자·숫자·하이픈으로 구성된 사용 가능한 소문자 이름을 선택한 후 확인합니다. 이 계정 수준의 이름은 앞으로 만들 Worker 와 공유되며, 이 실습의 고유한 Worker 이름과는 다릅니다. 이미 서브도메인이 있다면 그대로 사용하고 이름을 변경하지 마세요. 사용자 지정 도메인 구매나 요금제 업그레이드는 필요하지 않습니다.
배포가 완료될 때까지 기다립니다. Wrangler 는 다음 형식의 URL 을 출력합니다.
https://<your-worker-name>.<your-subdomain>.workers.dev
배포 결과에 표시된 실제 URL 을 셸 변수에 복사합니다. 아래 예시 URL 전체를 실제 URL 로 바꾸고, 따옴표는 유지하며, 끝에 슬래시는 넣지 않습니다.
WORKER_URL="https://YOUR_WORKER.YOUR_SUBDOMAIN.workers.dev"
curl -i "$WORKER_URL/health"
HTTP 200 과 로컬 테스트에서 본 것과 같은 JSON 이 반환되어야 합니다. 새 호스트 이름이 아직 전파 중이면 잠시 기다린 후 다시 시도합니다. 오류 페이지는 성공적인 배포를 의미하지 않습니다. 브라우저에서 실제 /health URL 을 열어도 됩니다. 브라우저나 네트워크가 workers.dev를 차단하면 VM 의 curl 결과를 사용하고, 브라우저 보안 설정은 비활성화하지 마세요. VM 요청과 아래의 독립적인 확인이 필수 응답 테스트입니다.
이제 Cloudflare Dashboard에서 같은 배포를 시각적으로 확인합니다. 터미널은 계속 열어 두세요.
계정 전환기에서 학습 계정을 선택합니다. 선택한 계정의 ID 가 위에서 선택한 계정과 일치해야 합니다.
Compute → Workers & Pages를 엽니다. 필요하면 애플리케이션 목록을 새로 고친 다음 설정에 표시된 정확한 labex-first-... 이름을 찾습니다. 애플리케이션이 많으면 전체 이름으로 검색합니다.
해당 Worker 를 엽니다. 이름을 확인하고 workers.dev 주소를 찾은 다음, 그 주소를 wrangler deploy가 출력한 URL 과 비교합니다.
이 스크린샷은 배포 예시입니다. 실제로 생성된 Worker 의 무작위 접미사와 계정 서브도메인은 다릅니다. 예시를 복사하지 말고 자신의 값을 찾으세요. Dashboard 는 터미널에서 만든 리소스를 다른 방식으로 보여 주는 화면입니다. 여기서 두 번째 Worker 를 만들거나 코드를 수정하지 마세요. Worker 가 보이지 않으면 먼저 선택한 계정, 정확한 이름, 배포 명령의 완료 여부를 확인합니다.
애플리케이션 목록은 클라우드 리소스가 존재한다는 것을 보여 주고, curl 로 테스트한 HTTP 응답은 코드가 작동한다는 것을 확인해 줍니다. 직접 스크린샷을 찍거나 제출할 필요는 없습니다.
단계의 검증 버튼을 사용합니다. 독립적인 백엔드 검사는 선택한 계정의 Worker 설정을 읽고 공개 엔드포인트를 테스트하므로, 비슷한 텍스트를 반환하는 다른 웹사이트로는 검증을 통과할 수 없습니다.
실시간 요청 로그 확인
이 단계에서는 실시간 로그 스트림에 연결하고 핸들러가 생성한 메시지를 찾습니다. 로그 스트림에는 연결된 동안 수신된 요청만 표시되며, 이전 요청은 다시 재생되지 않습니다.
Wrangler tail 을 백그라운드에서 시작합니다. --format json은 구조화된 이벤트를 생성합니다. 이번에는 표준 출력과 오류를 별도 파일로 보내 진단 텍스트가 이벤트 데이터에 섞이지 않게 합니다.
npx wrangler tail --format json > requests.json 2> tail-errors.log &
연결이 초기화될 때까지 몇 초 기다린 다음 새 요청을 보냅니다.
curl -i "$WORKER_URL/health"
이벤트 파일에는 많은 요청 메타데이터도 포함됩니다. head -n 32는 처음 32 줄을 표시하므로 첫 번째 이벤트와 애플리케이션 메시지에 집중할 수 있습니다.
head -n 32 requests.json
outcome이 ok인 이벤트, /health로 끝나는 GET 요청, health-request가 포함된 콘솔 메시지를 찾습니다. 다른 필드, 타임스탬프 및 요청 헤더는 달라질 수 있습니다. 파일이 비어 있으면 tail-errors.log를 확인하고 연결이 완료될 때까지 기다린 다음 요청을 다시 보내고 파일을 다시 읽습니다.
저장된 이벤트를 완전히 확인하기 전에 tail 을 중지합니다. jobs를 확인하고 wrangler tail에 표시된 번호를 사용합니다. 이전 작업이 중지된 후에는 일반적으로 1 입니다.
jobs
kill %1
단계의 검증 버튼을 사용해 배포된 Worker 에서 캡처한 이벤트를 확인합니다.
파일에는 요청 메타데이터가 포함될 수 있습니다. 이 파일은 VM 안에 보관하고 스크린샷으로 공개하거나 공개 저장소에 제출하지 마세요.
테스트 Worker 삭제
이 단계에서는 관리 권한이 아직 활성화된 동안 테스트 Worker 만 삭제하고 결과를 확인합니다. VM 을 삭제해도 배포된 Worker 는 삭제되지 않습니다.
프로젝트 설정을 다시 확인하고 name이 이 실습에서 사용한 고유한 labex-first-... 이름인지 확인합니다.
cat wrangler.jsonc
프로젝트 설정을 사용해 해당 Worker 를 삭제합니다.
npx wrangler delete
확인 프롬프트를 읽고 정확한 이름을 확인한 다음 y를 눌러 확인합니다. 강제 삭제를 사용하거나 다른 프로젝트를 삭제하지 마세요. 일반적으로 Wrangler 는 Worker 가 삭제되었다고 보고합니다. 고정된 버전과 이 범위의 권한을 사용하는 경우, Worker 를 삭제한 후 /storage/kv/namespaces에 대한 인증 오류를 출력할 수도 있습니다. Wrangler 는 정리 과정에서 레거시 Workers Sites 스토리지도 확인하기 때문입니다. 이 실습에서는 KV 네임스페이스를 만들지 않습니다. 제안된 모든 권한을 부여하거나 이 진단 메시지를 해결하기 위해 배포를 다시 수행하지 마세요. 단계의 검증 버튼으로 Worker 가 실제로 삭제되었는지 확인합니다. 그 밖의 오류는 계속 조사해야 합니다.
Cloudflare Dashboard 에서 학습 계정의 Workers & Pages를 열고 목록을 새로 고칩니다. 정확한 Worker 이름이 없는지 확인한 다음 단계의 검증 버튼을 사용해 독립적인 API 확인을 수행합니다.
검증에는 인증된 인벤토리 응답이 성공적으로 반환되어야 합니다. 네트워크 요청 실패나 만료된 로그인은 삭제 완료로 인정되지 않습니다. 학습 계정과 계정 수준의 workers.dev 서브도메인은 이후 실습에서 계속 사용할 수 있습니다. 로그아웃하기 전에 이 단계의 검증을 완료합니다.
VM 연결 해제
이 단계에서는 클라우드 정리가 완료되었는지 확인한 후 Wrangler 에 저장된 인증 정보를 삭제합니다. 로컬 소스 파일은 VM 에 남아 있지만 더 이상 계정에 액세스할 수 있는 권한을 부여하지 않습니다.
npx wrangler logout
npx wrangler whoami --json
"loggedIn": false를 찾습니다. 이 Wrangler 버전은 로그아웃 상태에서 0 이 아닌 종료 코드를 반환하며, 이는 예상된 동작입니다. 이 명시적인 상태 없이 네트워크 오류만 발생한 경우 로그아웃의 증거가 아닙니다. 단계의 검증 버튼을 사용해 독립적으로 확인합니다.
브라우저에서는 Cloudflare Dashboard 에 계속 로그인한 상태로 두어도 됩니다. 브라우저 로그인과 이 VM 의 Wrangler 인증은 서로 별개입니다. 이후 실습에서는 새 VM 으로 시작하고 별도의 인증을 요청합니다.
요약
Worker fetch 핸들러와 설정을 작성하고, JSON 응답을 로컬에서 테스트하고, 자신의 학습 계정에 배포한 다음 실시간 요청 로그를 확인했습니다. 공개 응답과 리소스 소유권을 독립적으로 검증하고, 인증된 상태에서 테스트 Worker 를 삭제했으며, VM 에서 로그아웃했습니다.
자세한 내용은 Cloudflare 의 Wrangler commands, fetch handler, workers.dev configuration을 참고하세요.
