RootNode 연결 가이드

관리자 콘솔에서 사이트를 등록하고 DNS TXT 또는 검증 파일로 소유권을 확인하세요. API Keys에서 서버 비밀키를 발급할 수 있습니다. 키는 발급 시 한 번만 표시됩니다.

SDK는 RootNode 소스에 포함된 workspace 패키지를 사용합니다. Node.js 22 이상, Next.js 16 이상에서 실행하세요.

# RootNode 저장소에서 실행
pnpm install --frozen-lockfile

# 연결할 앱의 package.json
"dependencies": {
  "@rootnode/next": "workspace:*"
}

사이트 ID와 발급한 키를 서버 환경변수에 저장하세요. 비밀키는 브라우저에 전달하거나 Git에 커밋하지 마세요. 키 유효기간은 90일이며 콘솔에서 폐기할 수 있습니다.

ROOTNODE_SITE_ID=site_...
ROOTNODE_API_KEY=rn_sk_...
ROOTNODE_API_URL=https://api.admin.rootnode.kr

앱 루트의 proxy.ts에 보호할 경로를 설정하세요. 기존 Proxy가 있다면 withRootNode로 합성할 수 있습니다. 연결한 경로의 보호는 기존 애플리케이션 인증과 함께 적용됩니다.

import { createRootNodeProxy } from '@rootnode/next';

export const proxy = createRootNodeProxy({
  siteId: process.env.ROOTNODE_SITE_ID!,
  apiKey: process.env.ROOTNODE_API_KEY!,
  apiUrl: process.env.ROOTNODE_API_URL!,
});

export const config = {
  matcher: ['/((?!_next/static|_next/image|favicon.ico|health$).*)'],
};

Maintenance에서 점검 안내를 설정하고 직접 시작·종료합니다. 점검 중 연결한 페이지와 API는 HTTP 503과 Retry-After를 반환합니다. 예상 종료 시각은 안내용입니다. Security에서 브라우저 확인과 요청 제한을 관리할 수 있으며, Monitor는 보안 규칙을 기록하고 Enforce는 실제 적용합니다. 설정은 최대 23초 안에 반영됩니다.

자동 검사 후 추가 확인이 필요한 요청에는 6자리 보안문자를 표시합니다. 검증 요청은 3분, 입력은 최대 5회까지 유효하며 문자를 바꿔도 남은 횟수가 유지됩니다. 확인을 마치면 등록된 사이트로 돌아가며 방문자 쿠키는 최대 15분 유지됩니다. 이 검사는 기본적인 자동화 필터이며 사용자 인증을 대신하지 않습니다.

Logs에서 최근 설정 변경과 보안 이벤트를 확인하세요. Feature Flags는 사이트별 불리언 값을 서버 SDK에 전달합니다. 클라이언트에는 공개할 플래그만 전달하고 사용자 권한은 별도로 확인하세요.

401은 로그인 또는 키, 403은 권한과 소유권, 429는 요청 제한, 503은 점검 또는 서버 연결을 확인하세요. API 연결이 끊기면 기본적으로 보호 경로는 503을 반환합니다. SDK가 실행되지 않는 원본 서버와 별도 API에는 별도 접근 제어가 필요합니다. 네트워크 DDoS 방어는 CDN/WAF에서 구성하세요. 요청 제한은 Firestore 할당량을 사용하며 IP 단위 제한에는 신뢰할 수 있는 IP 어댑터가 필요합니다.