Cloudflare 통합 가이드

NetFUNNEL Cloudflare 에이전트는 Cloudflare Workers에서 동작하며, 요청이 오리진 서버에 도달하기 전에 엣지에서 대기열을 제어합니다. 애플리케이션 코드를 수정하지 않고 Cloudflare 대시보드 설정만으로 적용할 수 있습니다.

1. 사전 준비

Workers를 사용할 수 있는 Cloudflare 계정
Cloudflare에서 관리 중인 서비스 도메인
NetFUNNEL 콘솔에서 확인한 CLIENT_ID
STCLab에 문의해 받은 NetFUNNEL Cloudflare 에이전트 파일

2. 에이전트 동작 흐름

대기열 제어 지점은 NetFUNNEL 콘솔의 세그먼트 트리거 규칙을 통해 설정할 수 있습니다. 사용자가 접속한 페이지의 URL과 트리거 규칙을 비교하여 일치하는 경우 대기열이 적용됩니다.

대기 전: 엣지로 요청 유입 → Worker 실행 → 트리거 규칙 매치
대기 중: 넷퍼넬 서버 요청 → 넷퍼넬 키 발급 → 대기실 페이지로 이동
대기 후: 서비스 페이지 진입 → 넷퍼넬 키 반납

3. Worker 생성

Cloudflare 대시보드에서 Workers & Pages > Create를 클릭합니다.
Hello world 템플릿을 선택하고 Deploy를 클릭합니다.

4. 에이전트 적용

생성한 Worker 화면 우측 상단의 Edit code를 클릭합니다.
왼쪽 패널의 Explore를 클릭해 파일 목록을 엽니다.
STCLab에서 받은 에이전트 파일을 추가합니다.
worker.js를 아래와 같이 수정합니다. {AGENT_FILE_NAME}은 추가한 에이전트 파일의 이름으로 바꿉니다.

import handleEvent from './{AGENT_FILE_NAME}';

export default {
  async fetch(request, env, ctx) {
    // 모든 요청을 NetFUNNEL 에이전트로 처리
    return await handleEvent(request, env, ctx);
  },
};

Deploy를 클릭합니다.

5. 라우트 설정

Worker가 실행될 도메인과 경로를 지정합니다.

생성한 Worker를 선택하고 Settings > Domains & Routes에서 + Add > Route를 클릭합니다.
Zone에서 서비스 도메인을 선택합니다.
Route에 Worker를 실행할 경로 패턴을 입력합니다.
실패 시 동작은 **Fail open (proceed)**을 선택합니다.
Add route를 클릭합니다.

항목	값	예시
Route	서비스 도메인 + `/*`	`www.example.com/*`
Failure mode	Fail open (proceed)	-

6. 변수 설정

Worker의 Settings > Variables and Secrets에 아래 변수를 Text 타입으로 추가하고 Deploy를 클릭합니다.

변수	값	설명
`CLIENT_ID`	`{CLIENT_ID}`	NetFUNNEL 콘솔에서 확인한 클라이언트 아이디

7. DNS 설정

5단계에서 라우트로 지정한 도메인의 DNS 레코드를 Proxied(주황색 구름) 상태로 설정합니다. 요청이 Cloudflare를 거쳐야 Worker가 실행됩니다.

항목	값
Type	`CNAME`
Name	서비스 도메인 (예: `www`)
Proxy status	Proxied

8. 부가 기능 설정

Worker의 Settings > Variables and Secrets에 Text 타입 변수를 추가해 부가 기능을 사용할 수 있습니다. 변수를 추가하거나 바꾼 뒤에는 Deploy를 클릭해야 적용됩니다.

변수	기본값	설명
`GOOD_BOTS`	-	대기열 제어에서 제외할 선의의 봇 키워드입니다. `User-Agent`에 포함되면 에이전트를 거치지 않습니다. 예: `Googlebot, Bingbot, Slurp, Applebot, facebookexternalhit`
`RETURN_KEY`	`true`	`true`: 대기 완료 후 즉시 키를 반납합니다. `false`: 세그먼트의 타임아웃 시점에 반납합니다.
`VWR_PAGE_DOMAIN`	`agent-lib.stclab.com`	대기실 페이지 도메인을 지정합니다. 형식: `http(s)://{CNAME_DOMAIN}` (예: `https://wait.stclab.com`). 사용 전 STCLab에 도메인 등록을 요청해야 합니다.
`COOKIE_DOMAIN`	현재 페이지 도메인	키 쿠키의 도메인을 지정합니다. 형식: `.{MAIN_DOMAIN}` (예: `.stclab.com`). 하위 도메인 간에 키를 공유할 때 사용합니다.

9. 트리거 규칙 설정

트리거 규칙 설정 방법은 트리거 규칙 문서를 참고하세요.