Fastly 통합 가이드

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

1. 사전 준비

• Compute를 사용할 수 있는 Fastly 계정
• 대기열을 적용할 서비스 도메인
• NetFUNNEL 콘솔에서 확인한 CLIENT_ID
• STCLab에 문의해 받은 NetFUNNEL Fastly 에이전트 파일
• Fastly CLI

# macOS (Homebrew)
brew install fastly/tap/fastly

팁

다른 운영체제의 설치 방법은 Fastly CLI 문서를 참고하세요.

2. 에이전트 동작 흐름

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

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

3. Compute 서비스 생성

1. Fastly 콘솔에서 Compute > Create service를 클릭합니다.
2. Use starter kit를 선택합니다.
3. Service name과 Compute에 연결할 도메인을 입력하고 Next: Choose a starter kit를 클릭합니다.
4. Default starter for Rust를 선택하고 Finalize and deploy를 클릭합니다.

4. 도메인 연결

1. 배포가 끝나면 Additional setup의 Point your custom domain to Fastly를 엽니다.
2. Issue TLS Certification을 클릭해 TLS 인증서를 발급합니다.
3. 사용 중인 DNS 서비스에서 도메인의 CNAME 레코드를 Fastly로 지정합니다.

5. 백엔드 설정

1. 서비스에서 Edit configuration > Clone version 1 (active) to edit을 클릭합니다.
2. Origins > Create a host에서 아래 3개의 호스트를 추가합니다.
3. 추가한 호스트를 각각 선택해 Edit에서 Name을 아래 이름으로 바꾸고 Update를 클릭합니다.

Hostname	Name	설명
{CLIENT_ID}.netfunnel.stclab.com	nf_core	NetFUNNEL 서버 (예: stclab-0000.netfunnel.stclab.com)
nf-setting-bucket.stclab.com	nf_setting	NetFUNNEL 설정 파일 저장소 (고정값)
서비스 오리진 주소	origin	기존 서비스의 오리진 서버

4. 우측 상단의 Activate를 클릭해 저장합니다.

주의

• 백엔드 Name은 에이전트 코드가 참조하므로 위 표와 정확히 같아야 합니다.
• Compute 서비스 설정을 바꿀 때마다 현재 버전을 복제(Clone)해 수정한 뒤 Activate해야 합니다.

6. Config Store 설정

6.1 Config Store 생성

1. Resources > Config stores에서 Create store를 클릭합니다.
2. Store name에 nf_config_store를 입력합니다.
3. 아래 항목을 추가합니다.

Key	Value
CLIENT_ID	NetFUNNEL 콘솔에서 확인한 클라이언트 아이디 (예: stclab-0000)

6.2 서비스 연결

1. Config Store의 Linked Services 탭에서 Link service를 클릭합니다.
2. 3단계에서 만든 Compute 서비스를 선택하고 Next를 클릭합니다.
3. Link and activate > Confirm and activate를 클릭합니다.

7. 에이전트 배포

7.1 API 토큰 생성

Fastly CLI로 배포하려면 API 토큰이 필요합니다.

1. Account > API tokens > Personal tokens에서 Create Token을 클릭합니다.
2. Continue를 클릭하고 다시 로그인합니다.
3. 토큰 이름을 입력하고, Expiration은 Never expire를 선택한 뒤 Create Token을 클릭합니다.

참고

발급한 토큰은 Fastly CLI 인증에 사용합니다. fastly profile create 명령으로 등록하면 이후 배포 시 토큰을 다시 입력하지 않아도 됩니다.

7.2 빌드 및 배포

1. STCLab에서 받은 에이전트 파일의 압축을 풉니다.
2. fastly.toml의 cloned_from과 service_id에 Fastly 콘솔에서 확인한 Compute 서비스 ID를 입력합니다.

fastly.toml

authors = []
cloned_from = "{SERVICE_ID}"
description = "Fastly agent for NetFUNNEL - Rust implementation"
language = "rust"
manifest_version = 3
name = "netfunnel-fastly-agent"
service_id = "{SERVICE_ID}"

3. netfunnel-fastly-agent 폴더에서 빌드와 배포를 실행합니다.

fastly compute build
fastly compute deploy

8. 부가 기능 설정

nf_config_store에 아래 항목을 추가해 부가 기능을 사용할 수 있습니다.

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

주의

Config Store 값을 바꾼 뒤에는 캐시를 비워야 적용됩니다. Compute > Compute Services에서 서비스를 선택하고 Purge > Purge all을 클릭한 뒤, 서비스 이름을 입력하고 Purge all을 클릭합니다.

9. 트리거 규칙 설정

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

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