커스텀 도메인 설정

설치 및 설정

어떤 단계를 시작하기 전에 시작하기 전에 및 터미널 기본 사항을 읽어보세요. 이 지침에서는 VS Code에서 전체 supastack 단일 저장소를 열었다고 가정합니다. 해당 루트 package.json은 저장소 루트를 표시합니다. pnpm 명령에서 작업 영역 패키지는 앱 또는 공유 코드 폴더입니다. 제품에서 작업공간은 팀의 데이터 컨테이너이자 보안 경계입니다. corepack pnpm --filter ... 명령이 해당 루트에서 실행되는 동안 monorepo에서 하나의 패키지를 선택합니다. 동기화된 모바일 또는 데스크톱 폴더만 열었다면 웹 백엔드, Docker 설정 또는 루트 스크립트가 포함되지 않습니다. 이 모노 저장소 또는 연결 가능한 호스팅 서버에서 백엔드를 실행하고 플랫폼 폴더의 자체 스크립트를 사용하세요. 환경 변수는 로컬 .env 파일이나 호스팅 대시보드에 저장된 명명된 설정입니다. 관련 앱을 변경한 후 다시 시작하고, NEXT_PUBLIC_ 및 EXPO_PUBLIC_ 값에서 서버 비밀을 유지하세요.

1. apps/web/.env.local를 열고 CUSTOM_DOMAINS_PROVIDER=local를 사용하여 DNS 변경 없이 도메인 화면을 미리 봅니다.

2. 실제 고객 호스트 이름의 경우 자체 영역, 해당 영역으로 제한된 API 토큰 및 CNAME 대상을 사용하여 SaaS용 Cloudflare를 구성합니다. 브라우저가 아닌 웹 호스트에 서버 전용 값을 입력하십시오.

3. corepack pnpm --filter @supastack/web dev를 사용하여 웹을 실행하고 작업 공간 소유자/관리자로 설정 → 도메인을 엽니다. 예상: 로컬 어댑터가 테스트 도메인을 즉시 활성화합니다. Cloudflare 어댑터는 표시된 DNS 레코드를 기다립니다.

CLOUDFLARE_API_TOKEN, CLOUDFLARE_ZONE_ID 및 CUSTOM_DOMAIN_CNAME_TARGET를 사용하여 CUSTOM_DOMAINS_PROVIDER=cloudflare를 설정합니다. API 토큰에는 영역에 대한 SSL 및 인증서:편집 권한이 필요합니다(사용자 정의 호스트 이름 API는 /zones/{zone_id}/custom_hostnames 아래에 있음). CNAME 대상은 배포된 앱을 확인하는 Cloudflare 영역(예:customers.example.com)의 호스트 이름입니다.

원본(SaaS 용어에 대한 Cloudflare의 대체 원본)에서 CNAME 대상을 가리키는 영역에 DNS 레코드를 추가하세요. Cloudflare는 각 사용자 지정 호스트 이름에 DCV TXT 레코드와 선택적 소유권 TXT 레코드를 발급합니다. 설정 화면에는 어떤 기록을 생성해야 하는지 고객에게 정확히 표시됩니다.

로컬 개발의 경우 대상 고객에게 즉시 활성화된 모든 호스트 이름을 표시하는 CUSTOM_DOMAINS_PROVIDER=local를 사용하십시오.localhost. CUSTOM_DOMAINS_PROVIDER=off(기본값)는 섹션의 컨트롤을 숨깁니다.

CUSTOM_DOMAINS_PROVIDER=cloudflare
CLOUDFLARE_API_TOKEN=cf_token_with_ssl_edit
CLOUDFLARE_ZONE_ID=zone_id
CUSTOM_DOMAIN_CNAME_TARGET=customers.example.com

복사 명령

설명을 따라 명령이 실행되는 폴더를 확인하세요. 두 개의 터미널에 레이블이 지정되어 있으면 두 개의 터미널 창을 열고 두 번째 명령을 사용하는 동안 첫 번째 명령을 계속 실행하세요.

corepack pnpm --filter @supastack/web dev

구현 워크플로

워크스페이스 소유자와 관리자는 설정 → 도메인(워크스페이스당 5개)에서 도메인을 관리합니다. 고객은 CNAME 대상에서 호스트 이름에 대한 CNAME 레코드를 가리키고 소유권 및 인증서 검증을 위해 표시된 TXT 레코드를 추가한 다음 상태 새로 고침을 누릅니다. Cloudflare가 활성 호스트 이름을 보고하면 해당 배포에 대한 인증을 위한 신뢰할 수 있는 원본이 되며 작업 영역 이름/로고는 해당 호스트 이름의 앱 크롬 브랜드를 표시합니다.

Apex(루트) 도메인은 대부분의 DNS 공급자에서 CNAME이 될 수 없습니다. 고객은 Portal.example.com과 같은 하위 도메인이나 CNAME 평면화 기능을 갖춘 공급자를 사용해야 합니다. 쿠키는 각 호스트로 범위가 지정되므로 고객 도메인은 별도의 로그인입니다. 사용자 정의 도메인 전체의 Single Sign-On은 범위를 벗어납니다.

검증 및 문제 해결

Cloudflare가 계속 보류 중인 경우 고객의 CNAME 및 TXT 레코드를 도메인 카드에 표시된 정확한 값과 비교하고 DNS가 업데이트될 때까지 기다립니다. DNS 공급자가 루트 도메인 CNAME를 평면화할 수 없는 경우 하위 도메인을 사용합니다. 메뉴가 없는 경우 해당 기능이 활성화되어 있고 로그인한 사용자가 워크스페이스 소유자 또는 관리자인지 확인하세요.

오랫동안 보류 중이라는 것은 일반적으로 고객의 CNAME가 누락되었거나 계속 전파되고 있음을 의미합니다. 도메인 카드에 표시된 DNS 레코드를 다시 확인하세요. 이동 또는 실패 상태는 Cloudflare가 더 이상 해당 영역에 대한 호스트 이름을 확인할 수 없음을 의미합니다. 제거하고 다시 추가하세요. 검증 데이터는 공급자 JSON로 저장되므로 향후 Cloudflare 검증 형태에는 스키마 변경이 필요하지 않습니다.