---
title: 도메인·터널 토큰 발급 가이드 (당신이 직접 하는 부분)
date: 2026-06-29
type: guide
domain: homelab
tags: [cloudflare, tunnel, dns, homelab]
---


**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](/docs/homelab/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 로그인(이메일 `yjs890403@gmail.com` 권장) → 도메인 검색·구매.
**성공 신호:** 결제 완료 + 대시보드에 도메인이 뜸.

---

## 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`에 추가 후 "넣었어"라고만 알려주세요.
```bash
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분 내 마무리.

## 참조
- 전체 런북(서버·DNS·Access·롤백): [infra__guide-domain-activation](/docs/homelab/domain-activation/)
- 시스템 구조: [infra__ref-wiki-portal-architecture](/docs/homelab/wiki-portal-architecture/)