homelab89 Docs Logs Legacy Files ☰ TOC 🌓
guidehomelab 2026-06-29cloudflaretunneldnshomelab

도메인·터널 토큰 발급 가이드 (당신이 직접 하는 부분)

Date: 2026-06-29 호스트: ubuntu (home server) 도메인: 운영 / 네트워킹 목적: quick tunnel(리붓마다 URL 변경)을 고정 도메인으로 바꾸기 위해, 본인이 Cloudflare에서 직접 해야 하는 발급 절차(도메인 + Named Tunnel 토큰)만 액션 중심으로 정리. 서버 쪽 배선은 Claude가 처리.

전체 end-to-end 레퍼런스(DNS·Caddy·CF Access·검증·롤백 포함): infra__guide-domain-activation (~/Documents/docs/cloudflare-domain-activation-runbook.md). 이 문서는 그중 “사람이 직접 하는 발급” 부분만 발췌·집중함.

0. 역할 분담 (방법론)

발급은 계정·결제·신원이 걸려 위임 불가 → 본인이 함. 서버 배선은 Claude가 함.

+---------------------------------------+      +-------------------------------+
|  당신 (Cloudflare 대시보드/결제)       |      |  Claude (홈서버)               |
+---------------------------------------+      +-------------------------------+
| 1. 도메인 구매 (로그인+카드+신원)      |      | A. .env에 토큰 반영            |
| 2. 사이트 Active 확인                  |      | B. compose tunnel command 교체 |
| 3. Named Tunnel 생성 -> 토큰 복사      | ===> | C. docker compose up -d tunnel |
| 4. Public Hostname 매핑(docs->8080)    | 토큰 | D. DNS/HEALTHY/접속 검증       |
| 5. 토큰을 .env에 넣거나 Claude에 전달  |      | E. 작업 로그 저장              |
+---------------------------------------+      +-------------------------------+
구분 누가 한 줄
도메인 구매 본인만 계정 로그인 + 결제(카드) + WHOIS 등록자 신원
사이트 추가/네임서버 본인 Registrar로 사면 자동
Named Tunnel 생성·토큰 본인 대시보드가 본인 로그인 필요, 토큰만 복사
Public Hostname 매핑 본인 터널 화면에서 docs.<도메인> → localhost:8080
compose 배선·재시작·검증 Claude 토큰만 받으면 끝

1. 도메인 구매 (~5분, ~$10/년)

  • 추천: Cloudflare Registrar (대시보드 내). 원가 판매(.com ≈ $10/년), WHOIS 프라이버시 무료, 네임서버 자동 연결(→ 2단계 자동 통과).
  • 외부 업체(Namecheap/Porkbun 등)도 가능하나 네임서버를 Cloudflare로 직접 바꿔야 함.
  • 무료(DuckDNS 등)는 불가 — Named Tunnel은 도메인이 Cloudflare 존이어야 자동 CNAME 생성 가능.

할 일: https://dash.cloudflare.com 로그인(이메일 [email protected] 권장) → 도메인 검색·구매. 성공 신호: 결제 완료 + 대시보드에 도메인이 뜸.

2. 사이트 Active 확인

  • Registrar 구매면 보통 즉시~수 분. 외부 업체면 네임서버를 Cloudflare 것 2개로 바꾼 뒤 활성화 대기(최대 24h, 보통 수십 분).
  • 성공 신호: 대시보드의 도메인 상태가 Active(초록). 메일 알림 도착.
  • 확인 명령(! 프롬프트로 실행 가능): dig +short NS <도메인> → *.ns.cloudflare.com 2개.

3. Named Tunnel 생성 → 토큰 복사 (핵심)

  1. 대시보드 좌측 Zero Trust 진입(첫 진입 시 team 이름 1회 설정 + Free).
  2. Networks → Tunnels(계정에 따라 Networking → Tunnels) → Create a tunnel.
  3. 커넥터 Cloudflared → Next.
  4. 터널 이름 homelab → Save tunnel.
  5. 환경에서 Docker 선택. 화면에 이런 설치 명령이 뜸: 
    docker run cloudflare/cloudflared:latest tunnel --no-autoupdate run --token eyJhIjoi...(아주 긴 문자열)
    → eyJ로 시작하는 토큰 문자열만 복사. (전체 docker run은 실행하지 말 것 — Claude가 compose에 넣음.)

토큰이란? 이 터널의 제어 권한을 담은 bearer 자격증명. 이것만 있으면 커넥터를 띄울 수 있으므로 비밀로 취급(공개 채널·git에 올리지 말 것).

4. Public Hostname 매핑

같은 터널 생성 흐름의 다음 화면 Public Hostnames(또는 Routes) → Add a public hostname:

  • Subdomain: docs (또는 비우면 루트)
  • Domain: 본인 도메인 선택
  • Type: HTTP, URL: localhost:8080
  • Save.

(가장 단순한 구성은 호스트네임 1개: docs.<도메인> → localhost:8080. 호스트 분리는 나중에.)

5. 토큰 전달 → Claude가 마무리

방법 A (권장, 토큰이 채팅에 안 남음): ! 프롬프트로 직접 .env에 추가 후 “넣었어"라고만 알려주세요.

echo 'CF_TUNNEL_TOKEN=eyJ...복사한토큰' >> ~/docs-publish/.env

방법 B: 토큰을 그대로 붙여 주시면 Claude가 .env에 넣음(개인 홈랩 터널이라 허용 가능하나, 전사 보안 관점에선 A가 깔끔).

그 다음 Claude가 자동 처리:

  • ~/docs-publish/docker-compose.yml의 kb-tunnel command를 tunnel --no-autoupdate run --token ${CF_TUNNEL_TOKEN} 한 줄로 교체.
  • docker compose up -d tunnel → 로그에 Registered tunnel connection.
  • 대시보드 Tunnels HEALTHY / dig +short docs.<도메인>(Cloudflare 애니캐스트 IP) / https://docs.<도메인> 200 검증.
  • 작업 로그 저장.

완료 후 효과: 리붓해도 주소 불변. 더 이상 *.trycloudflare.com 휘발성 URL을 매번 확인할 필요 없음.

체크리스트 (당신 쪽)

  • 도메인 구매 완료, 상태 Active
  • Named Tunnel homelab 생성, 토큰 복사
  • Public Hostname docs.<도메인> → localhost:8080 저장
  • 토큰을 .env에 넣거나 Claude에 전달

이 4개가 끝나면 나머지는 Claude가 5~10분 내 마무리.

참조

Files