커스텀 도메인 연결: DNS와 HTTPS 확인

도메인 연결 흐름

커스텀 도메인은 다음 흐름으로 연결됩니다.

사용자 브라우저
↓
DNS 조회
↓
배포 플랫폼의 대상 주소
↓
HTTPS 연결
↓
TaskFlow 애플리케이션

따라서 오류를 확인할 때도 같은 순서로 나누는 편이 좋습니다.

DNS가 배포 플랫폼을 가리키는가?
↓
TLS 인증서가 정상인가?
↓
HTTP 요청이 애플리케이션까지 도달하는가?
↓
애플리케이션 route가 정상인가?

apex와 www

다음 두 주소는 서로 다른 호스트 이름입니다.

example.com
www.example.com

example.com처럼 호스트 이름 앞에 별도 레이블이 없는 도메인을 흔히 apex 또는 root domain이라고 부릅니다.

운영에서는 둘 중 하나를 기준 주소로 정하는 것이 좋습니다.

예를 들어 다음처럼 정할 수 있습니다.

canonical
https://example.com

redirect
https://www.example.com
→ https://example.com

반대로 www를 기준으로 사용해도 됩니다. 중요한 것은 정책을 정하고 모든 링크와 인증 설정이 같은 기준을 사용하게 만드는 것입니다.

DNS 레코드 이해

배포 플랫폼은 도메인을 연결할 때 필요한 DNS 레코드를 안내합니다.

주로 다음 레코드를 볼 수 있습니다.

A
도메인 → IPv4 주소

AAAA
도메인 → IPv6 주소

CNAME
호스트 이름 → 다른 호스트 이름

중요한 원칙은 “인터넷에서 본 예시 값을 그대로 복사”하지 않는 것입니다.

플랫폼이 현재 프로젝트에 요구하는 레코드를 확인하고 DNS 제공자의 설정에 반영해야 합니다.

예를 들어 서브도메인은 CNAME을 사용하는 경우가 많지만, apex 도메인은 DNS 제공자와 플랫폼 구성에 따라 안내 방식이 달라질 수 있습니다.

DNS 전파와 TTL

DNS 레코드를 변경했다고 모든 사용자가 즉시 새 값을 보는 것은 아닙니다.

DNS 응답은 resolver와 캐시에 일정 시간 저장될 수 있습니다.

TTL은 해당 레코드를 캐시할 수 있는 시간을 나타내는 값입니다.

따라서 변경 직후 접속이 안 된다고 애플리케이션 코드를 먼저 수정할 필요는 없습니다.

확인 순서는 다음처럼 잡을 수 있습니다.

1. DNS 관리 화면의 레코드 확인
2. 공개 DNS 조회 결과 확인
3. Vercel 도메인 상태 확인
4. HTTPS 인증서 상태 확인
5. 실제 HTTP 응답 확인

Windows에서는 nslookup을 사용할 수 있습니다.

nslookup example.com

다른 DNS 서버를 지정해서 확인할 수도 있습니다.

nslookup example.com 1.1.1.1

결과는 자신의 플랫폼 설정과 비교해야 합니다.

HTTPS 확인

HTTPS는 단순히 주소 앞에 s를 붙이는 기능이 아닙니다.

브라우저와 서버는 TLS를 사용해 암호화된 연결을 설정하고 서버 인증서를 확인합니다.

관리형 플랫폼에서는 도메인이 올바르게 연결되면 인증서 발급과 갱신을 자동으로 처리하는 경우가 많습니다.

하지만 DNS가 아직 플랫폼을 가리키지 않거나 인증서 발급 조건이 충족되지 않으면 HTTPS 상태가 정상으로 바뀌지 않을 수 있습니다.

다음 항목을 구분합니다.

DNS 정상
HTTPS 인증서 대기

DNS 오류
인증서 발급도 진행되지 않음

HTTPS 정상
앱 내부에서 404 또는 500

canonical 정책

검색엔진과 사용자에게 같은 콘텐츠가 여러 URL로 열리면 관리가 복잡해질 수 있습니다.

운영 기준 도메인을 하나 정하고 나머지는 redirect하는 편이 좋습니다.

http://example.com
→ https://example.com

https://www.example.com
→ https://example.com

프로젝트에 인증 callback URL, CORS allowlist, OAuth authorized domain 같은 설정이 있다면 새 도메인을 함께 반영해야 합니다.

도메인만 연결하고 인증 시스템의 허용 URL을 바꾸지 않으면 로그인 단계에서 별도 오류가 발생할 수 있습니다.

DNS 문제와 404 구분

다음 두 상황은 서로 다릅니다.

도메인이 배포 플랫폼까지 도달하지 못함

DNS lookup 실패
잘못된 레코드
인증서 연결 실패

이 경우 애플리케이션 route보다 DNS 설정을 먼저 확인합니다.

도메인은 열리지만 특정 URL만 404

https://example.com/
→ 정상

https://example.com/tasks
→ 404

이 경우 DNS보다 애플리케이션 라우팅이나 rewrite를 확인해야 합니다.

자주 발생하는 오류

기존 DNS 레코드와 충돌합니다

같은 호스트에 서로 충돌하는 레코드를 여러 개 두면 의도하지 않은 곳으로 요청이 갈 수 있습니다.

플랫폼이 요구하는 값과 기존 레코드를 함께 검토합니다.

www만 연결하고 apex를 확인하지 않습니다

두 호스트를 모두 사용할 계획이라면 각각 연결 상태와 redirect 정책을 확인합니다.

HTTPS 오류를 브라우저 캐시 문제로만 생각합니다

인증서 상태와 DNS 연결을 먼저 확인합니다.

도메인 변경 후 인증이 실패합니다

OAuth, Firebase Auth, Supabase Auth 등 외부 서비스의 authorized domain이나 redirect URL을 다시 확인합니다.

학습 완료 체크리스트

• apex와 www의 차이를 설명할 수 있습니다.
• A, AAAA, CNAME의 역할을 구분할 수 있습니다.
• DNS 변경과 실제 반영 사이에 캐시가 존재할 수 있음을 이해했습니다.
• DNS 오류와 앱 404를 구분할 수 있습니다.
• HTTPS 인증서 상태를 별도로 확인할 수 있습니다.
• canonical 도메인 정책을 정할 수 있습니다.

# TaskFlow Deployment Plan


## Build
- package manager: npm
- install: npm ci
- build: npm run build


## Primary deployment
- platform: Vercel
- environment: Production


## Alternative deployment
- Firebase Hosting: static output일 때 검토
- Firebase App Hosting: server runtime이 필요할 때 검토


## Verification
- Production URL 응답
- 주요 화면 확인
- 환경변수 확인
- 주요 route 확인
- 현재 commit 확인
- rollback 가능 여부 확인

## Runtime decision


- static-only: no
- server runtime required: yes
- reasons:
  - Route Handler
  - server-side environment variables


## Primary
Vercel Production


## Firebase alternative
App Hosting 우선 검토


## Static variant
정적 결과물로 분리할 경우 Firebase Hosting 검토

## Production deployment


- deployment URL: 운영 문서에서 관리
- commit SHA: 배포마다 기록
- deployment status: 확인
- build log: 확인
- smoke test: 확인

## Domain


- canonical domain: 운영 문서에서 관리
- www policy: canonical로 redirect
- HTTPS: 확인
- DNS status: 확인
- auth callback / allowed origin: 확인

# 기존 앱에서 실제 사용하는 변수만 설정하세요. 값은 개발/운영 플랫폼에서 별도 관리합니다.
NEXT_PUBLIC_API_URL=
API_SECRET=

# TaskFlow Deployment Plan


## Build
- package manager: npm
- install: npm ci
- build: npm run build


## Primary deployment
- platform: Vercel
- environment: Production


## Alternative deployment
- Firebase Hosting: static output일 때 검토
- Firebase App Hosting: server runtime이 필요할 때 검토


## Verification
- Production URL 응답
- 주요 화면 확인
- 환경변수 확인
- 주요 route 확인
- 현재 commit 확인
- rollback 가능 여부 확인

## Runtime decision


- static-only: no
- server runtime required: yes
- reasons:
  - Route Handler
  - server-side environment variables


## Primary
Vercel Production


## Firebase alternative
App Hosting 우선 검토


## Static variant
정적 결과물로 분리할 경우 Firebase Hosting 검토

## Production deployment


- deployment URL: 운영 문서에서 관리
- commit SHA: 배포마다 기록
- deployment status: 확인
- build log: 확인
- smoke test: 확인

## Domain


- canonical domain: 운영 문서에서 관리
- www policy: canonical로 redirect
- HTTPS: 확인
- DNS status: 확인
- auth callback / allowed origin: 확인

# Server Access Runbook


## Connection
- host: 저장하지 않음
- user: 환경별 문서에서 별도 관리
- authentication: SSH key 우선
- private key: 저장소에 포함 금지


## Before upload
1. 대상 서버 확인
2. 현재 경로 확인
3. 배포 대상 경로 확인
4. 기존 파일 상태 확인


## After upload
1. 파일 존재 확인
2. owner / permission 확인
3. 서비스가 실제 경로를 읽는지 확인
4. HTTP 결과 확인


## Never commit
- private key
- password
- access token
- production secret

# 배포·서버 05 — deploy-step-05-domain-https

이 ZIP은 배포 준비·운영 문서와 해당 회차 설정/코드 조각을 누적한 적용 자료입니다. 실행 앱 전체는 포함하지 않습니다. 기존 deploy-step-00-build-ready 프로젝트에 해당 파일을 검토하여 적용하세요. 이 ZIP 루트에서 npm ci/build를 실행하는 구조가 아닙니다.

.env.example은 값이 빈 설정 안내입니다. 독자의 앱에서 사용하는 변수만 .env.local 또는 플랫폼의 해당 환경에 설정하세요. URL·계정·비밀키를 ZIP에 넣지 않습니다.

이 자료에는 실제 배포·DNS 변경·SSH 접속·메일/알림·롤백 결과가 없습니다. 운영 작업은 독자가 본인 환경과 권한을 확인한 후 수행해야 합니다. 문서의 확인 항목은 수행할 체크리스트이며 이미 통과했다는 기록이 아닙니다.

deploy-step-04-vercel-production

## Domain

- canonical domain: 운영 문서에서 관리
- www policy: canonical로 redirect
- HTTPS: 확인
- DNS status: 확인
- auth callback / allowed origin: 확인

nslookup example.com
curl.exe -I https://example.com/

DNS가 배포 플랫폼 대상과 일치
HTTPS 인증서 정상
HTTP → HTTPS 정책 정상
canonical 주소 정상
핵심 화면 정상

deploy-step-05-domain-https

다음 학습

다음 글부터 자동 배포 과정에서 발생하는 오류를 다룹니다. 먼저 GitHub Actions에서 npm ci가 실패하는 원인을 lockfile과 Node 버전 관점에서 확인합니다.

다음 글: GitHub Actions npm ci 실패 해결: lockfile과 Node 버전 확인

다음 회차 확인 과제: 06회차에서는 배포 브랜치의 GitHub Actions에서 npm ci와 build가 같은 commit으로 재현되는지 확인합니다.

공식 문서

공식 문서 확인 기준: 2026-09-21

• https://vercel.com/docs/domains
• https://vercel.com/docs/domains/working-with-domains
• https://developer.mozilla.org/en-US/docs/Glossary/DNS
• https://developer.mozilla.org/en-US/docs/Glossary/TLS