LabEx 를 Cloudflare 계정에 연결하기

소개

이 실습이나 VM 을 시작하기 전에 반드시 Cloudflare 학습용 계정 준비를 읽고 브라우저에서 계정을 준비하세요. 이 필수 사전 준비에는 LabEx VM 이 필요하지 않습니다. 로그인 이메일 인증을 마치고, 본인 소유의 전용 학습 계정을 선택할 수 있으며, 현재 요금제가 Workers Free 이고 같은 계정에서 Workers & Pages 를 열 수 있을 때만 계속하세요. 계정 이름을 기억해 두세요. LabEx Learning은 권장 표시 이름입니다. 이미 계정이 준비되어 있어도 먼저 문서를 읽고 이 항목들을 확인하세요.

Cloudflare 학습용 계정을 준비했습니다. 이제 Cloudflare 의 명령줄 도구인 Wrangler를 사용해 LabEx Linux 환경을 해당 계정에 연결합니다. 브라우저에서 신원을 확인하면 Wrangler 가 이 VM 에 인증 정보를 저장합니다. Dashboard 에 로그인하는 것만으로는 터미널이 연결되지 않습니다.

Prepare Your Cloudflare Learning Account에서 준비한 것처럼, 이메일 주소가 인증되었고 Workers Free 플랜을 사용하는 본인 소유의 계정을 사용합니다. 계정 이름을 바로 확인할 수 있도록 준비해 두세요. LabEx Learning을 권장합니다. 이 실습에서는 사용자 및 계정 정보에 대한 읽기 액세스를 요청합니다. 애플리케이션을 배포하거나 도메인을 준비하거나 유료 서비스를 추가하지 않습니다.

실습 환경에서 Node.js 22.22.0 과 Wrangler 4.131.1 을 자동으로 설치합니다. 표준 Wrangler 명령과 프로젝트 구성을 사용하며, 이 방법은 개인 컴퓨터에서도 동일하게 사용할 수 있습니다. 직접 연결을 승인하고 결과를 확인한 다음 마지막에 로그아웃합니다. 새 VM 마다 새로 인증해야 합니다.

브라우저를 통해 Wrangler 인증하기

이 단계에서는 본인의 Cloudflare 로그인 정보를 사용해 LabEx VM 의 Wrangler 를 인증합니다.

LabEx Terminal 을 열고 준비된 프로젝트 디렉터리로 이동합니다. cd 명령은 현재 작업 디렉터리를 변경하며, 이후 명령은 이 디렉터리에서 실행됩니다.

cd /home/labex/project/cloudflare-connect

Wrangler 는 이 프로젝트의 개발 종속 항목으로 로컬 설치되어 있습니다. npx wrangler를 실행하면 설치된 버전이 실행됩니다. 설정 과정에서 Node.js 와 프로젝트 종속 항목을 이미 설치했으므로 다시 설치할 필요가 없습니다. 버전을 확인합니다.

npx wrangler --version

버전이 4.131.1인지 확인합니다. 프로젝트의 package.json은 이 정확한 버전을 고정하고, package-lock.json은 확인된 종속 항목 버전을 기록합니다. 개인 컴퓨터에서 Node.js 를 설치한 후에는 npm install --save-dev --save-exact wrangler@4.131.1을 사용해 프로젝트에 Wrangler 를 추가할 수 있습니다. 이 내용은 설명이며, 준비된 실습 환경에서 추가로 실행할 명령은 아닙니다. 기존 lockfile 이 커밋된 프로젝트를 재현할 때는 npm ci를 사용합니다.

프로젝트별로 Wrangler 를 로컬 설치하면 각 프로젝트의 도구 버전을 서로 독립적으로 관리할 수 있습니다. 자세한 내용은 Cloudflare 의 설치 안내를 참조하세요.

이제 기기 인증을 시작합니다. --device는 localhost 콜백 없이 브라우저의 승인 결과를 원격 터미널에 연결합니다. --browser=false는 Wrangler 가 VM 안에서 브라우저를 실행하지 않도록 합니다. 두 가지 scope 는 이 연결 실습에 필요한 계정 및 사용자 읽기 액세스를 요청합니다. Cloudflare 는 Wrangler 가 인증을 유지하는 데 필요한 Background Access 도 함께 포함합니다. Worker 쓰기 권한은 요청하지 않습니다.

npx wrangler login --device --browser=false --scopes account:read user:read

Wrangler 가 인증 URL 과 짧은 코드를 표시합니다. 이 명령은 계속 실행 중인 상태로 둡니다. 본인의 브라우저에서 표시된 Cloudflare URL 을 열고, 현재 터미널에 표시된 코드를 입력한 후 계속 진행합니다. URL 에 코드가 이미 포함되어 있다면 터미널의 코드와 일치하는지 확인합니다. 스크린샷이나 다른 사람의 세션에 표시된 코드는 사용하지 않습니다.

코드 입력란이 비어 있는 Cloudflare 기기 인증 양식

비슷하게 생긴 문자를 혼동하지 않도록 터미널에서 코드를 직접 복사합니다. Continue를 선택합니다. Cloudflare 가 코드를 확인하지 못하면 문자가 정확한지, 현재 로그인 명령이 아직 대기 중인지 확인합니다.

요청이 표시되면 로그인합니다. 동의 페이지에서 애플리케이션이 Wrangler 인지 확인하고 요청된 권한을 검토한 다음, 계정 선택 항목이 표시되면 본인의 학습용 계정만 선택합니다. 동의 페이지에서 Account Read는 Account & Billing 아래에 그룹으로 표시됩니다. 해당 그룹을 펼쳐 내용을 확인합니다. User Read와 Background Access는 Required 아래에 표시됩니다.

User Read, Background Access, Account Read 가 표시된 Wrangler 동의 권한

Edit 옆에 표시된 계정 이름을 확인합니다. 학습용 계정이 아니라면 Edit을 선택하고 올바른 계정을 선택한 후 동의 화면으로 돌아갑니다. 아래의 잘린 스크린샷에는 선택한 계정과 Authorize 버튼이 표시되어 있습니다. 전체 페이지에서는 이 영역 위에 로그인한 사용자의 신원이 표시됩니다.

Edit 및 Authorize 컨트롤이 표시된 선택된 LabEx Learning 계정

표시된 개인정보 보호 정보를 검토한 후, 다음 내용을 확인하고 Authorize를 선택합니다. Terminal 로 돌아와 Successfully logged in.이 표시될 때까지 기다린 다음 계속합니다. 브라우저 승인과 터미널 완료는 서로 다른 확인 단계입니다.

Cloudflare 에서 Wrangler 에 인증이 허용되었음을 확인하는 화면

성공 페이지에는 일반적인 개발 권장 사항이 표시됩니다. 에이전트 도구를 설치하거나 제안된 프롬프트를 복사할 필요는 없습니다. 일반적인 배포 안내는 이 실습에서 요청한 읽기 권한을 확대하지 않습니다.

코드는 짧은 시간 후 만료됩니다. 코드가 만료되거나 요청을 거부했다면 명령이 완료될 때까지 기다리거나 Ctrl+C 를 누른 다음, 같은 명령을 다시 실행해 새 코드를 받습니다. 실수로 일반 로그인을 시작해 연결할 수 없는 localhost 페이지가 표시되면 해당 명령을 중지하고 위의 기기 인증 명령을 사용합니다.

Wrangler 자체에서 저장된 로그인을 확인합니다.

npx wrangler whoami --json

"loggedIn": true, "authType": "OAuth Token", 그리고 학습용 계정이 포함된 accounts 배열을 찾습니다. 각 계정 객체에는 name과 id가 있습니다. --json 옵션을 사용하면 사람이 읽는 보고서 대신 구조화된 데이터가 반환됩니다. 다른 계정 설정은 이해하지 않아도 됩니다. 브라우저에 성공 페이지가 표시되었다는 사실만으로는 VM 이 인증을 받았다고 볼 수 없습니다. Wrangler 가 인증되지 않았다고 보고하면 기기 인증을 다시 수행합니다.

이 단계의 확인 버튼을 사용합니다. LabEx 가 별도로 이 VM 에 저장된 OAuth 로그인이 액세스 가능한 계정을 읽을 수 있는지 확인합니다.

Wrangler 는 VM 사용자의 구성에 인증 정보를 저장합니다. 인증 파일을 출력하거나 복사하지 말고, 토큰을 표시하는 명령도 실행하지 않습니다. 자세한 기기 인증 흐름은 공식 Wrangler 로그인 문서를 참조하세요.

학습용 계정 선택 및 확인하기

이 단계에서는 학습용 계정을 식별하고 해당 계정의 ID 를 Wrangler 표준 프로젝트 구성에 저장합니다.

하나의 로그인으로 여러 계정에 액세스할 수 있습니다. 같은 신원 확인 명령을 실행해 accounts 배열에 있는 계정의 이름과 ID 를 확인합니다.

npx wrangler whoami --json

name으로 학습용 계정을 식별할 수 있는 객체를 찾습니다. 계정이 하나만 표시되더라도 이름을 확인합니다. 여러 계정이 표시되면 Dashboard 의 계정 선택기를 사용해 학습용 계정이 어느 것인지 확인합니다. 단순히 첫 번째로 표시된 계정을 선택하지 않습니다. 원하는 계정이 없다면 인증을 다시 수행하고 브라우저에서 해당 계정을 선택합니다.

같은 계정 객체에 있는 **32 자리 id**를 복사합니다. 계정 이름은 표시용 레이블이고, ID 는 실제 계정을 식별합니다. Wrangler 의 account_id 설정은 로그인으로 여러 계정에 액세스할 수 있을 때도 프로젝트의 대상 계정을 명확하게 지정합니다.

wrangler.jsonc를 만듭니다. 아래 블록을 실행하기 전에 YOUR_ACCOUNT_ID를 방금 복사한 ID 로 바꿉니다. 따옴표는 그대로 유지합니다. here-document 는 CONFIG 구분자 사이의 모든 내용을 파일에 기록하며, >는 파일의 기존 내용을 대체합니다.

cat > wrangler.jsonc <<'CONFIG'
{
  "account_id": "YOUR_ACCOUNT_ID"
}
CONFIG

저장된 구성을 확인합니다.

cat wrangler.jsonc

account_id가 whoami --json의 학습용 계정 객체와 일치하고 placeholder 가 사라졌는지 확인합니다. 이 파일에는 식별자가 들어 있을 뿐 비밀번호나 OAuth 토큰은 들어 있지 않습니다. 주석이 없는 JSON 은 유효한 JSONC 입니다. 이 실습에서는 표시된 형식을 사용합니다. 이후 실습에서는 같은 표준 구성 파일에 Worker 설정을 추가합니다. 자세한 내용은 Wrangler 구성을 참조하세요.

로그아웃하기 전에 이 단계의 확인 버튼을 사용합니다. 백엔드가 구성을 읽고 인증된 읽기 전용 계정 요청을 보냅니다. Cloudflare 가 정확히 해당 계정에 대한 액세스를 확인하는지 검사하므로, 파일을 저장한 것만으로는 충분하지 않습니다. 실패하면 복사한 ID, 인증 상태 및 연결을 확인합니다. 터미널에서 별도의 사용자 지정 명령을 실행할 필요는 없습니다.

이 단계에서는 계정 읽기 액세스를 확인합니다. 이후 실습에서는 배포를 위해 추가 권한을 요청합니다.

이 VM 연결 해제하기

이 단계에서는 이 VM 의 Wrangler 로그인을 제거하고 더 이상 인증되지 않았는지 확인합니다.

먼저 이전 단계의 확인을 완료합니다. 로그아웃하면 이전 단계의 실제 API 확인에 필요한 인증이 제거됩니다. 이 실습에서는 클라우드 리소스를 만들지 않았으므로 삭제할 애플리케이션이나 계정이 없습니다.

Wrangler 의 로그아웃 명령을 실행합니다.

npx wrangler logout

그런 다음 인증되지 않은 상태인지 명시적으로 확인합니다.

npx wrangler whoami --json

구조화된 출력에서 "loggedIn": false를 찾습니다. 이 Wrangler 버전에서는 로그아웃된 상태일 때 명령이 0 이 아닌 종료 코드로 끝나는 것도 정상입니다. 이 명시적인 상태 없이 네트워크 오류만 표시되는 것은 로그아웃을 증명하지 않습니다. 결과를 독립적으로 확인하려면 이 단계의 확인 버튼을 사용합니다.

동의 페이지에서 연결된 링크를 통해 Dashboard 의 My Profile → Access Management → Connected Applications에서 애플리케이션 권한 부여 상태를 검토할 수도 있습니다. Cloudflare 에서는 이곳에서 애플리케이션 액세스를 관리하거나 취소할 수 있습니다. 제거하려는 권한만 취소합니다. 다른 환경에서 같은 애플리케이션을 사용 중일 수 있습니다.

Wrangler 에서 로그아웃해도 Cloudflare 학습용 계정이 삭제되거나 브라우저의 Dashboard 세션에서 로그아웃되지는 않습니다. 이후 수업에서 사용할 수 있도록 계정을 유지합니다. wrangler.jsonc 파일에는 인증 정보가 아니라 식별자가 들어 있지만, 이 파일만으로 새 VM 을 인증할 수는 없습니다. 다음 실습은 새 환경에서 시작하며, 별도의 연결 절차를 진행합니다.

이후에 앞 단계의 확인을 다시 실행하면 인증 실패가 발생하는 것이 정상입니다. 실습을 반복하려는 경우에만 다시 인증하고, 완료한 후 다시 로그아웃합니다.

요약

Cloudflare 의 기기 인증 흐름을 통해 원격 LabEx VM 을 인증하고, 본인의 학습용 계정을 선택한 다음, 독립된 프로세스에서 실제 계정 액세스를 확인했습니다. 그런 다음 Wrangler 에서 로그아웃하고 명시적인 인증되지 않음 상태를 확인했습니다.

학습용 계정은 과정에서 계속 사용할 수 있습니다. 브라우저 로그인, VM 인증, 선택한 계정은 연결을 구성하는 서로 다른 요소입니다. 새 환경을 시작할 때마다 세 가지를 모두 확인합니다.