Akamai 통합 가이드

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

1. 사전 준비

• EdgeWorkers를 사용할 수 있는 Akamai Control Center 계정
• 대기열을 적용할 서비스의 Akamai Property (또는 새로 만들 Property의 호스트 이름)
• NetFUNNEL 콘솔에서 확인한 CLIENT_ID
• NetFUNNEL Akamai 에이전트 코드

2. 에이전트 동작 흐름

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

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

3. EdgeWorker 등록

3.1 EdgeWorker 생성

1. Akamai Control Center 메뉴에서 EdgeWorkers를 클릭합니다.
2. Create EdgeWorker ID를 클릭하고 정보를 입력한 뒤, 다시 Create EdgeWorker ID를 클릭합니다.
3. 생성한 EdgeWorker를 선택하고 Create version을 클릭합니다.
4. Open editor를 클릭합니다.

3.2 에이전트 코드 업로드

Code Bundle 탭에서 아래 두 파일을 작성합니다.

• main.js: NetFUNNEL Akamai 에이전트 코드를 그대로 붙여 넣습니다.
• bundle.json: 아래와 같이 작성합니다.

bundle.json

{
  "edgeworker-version": "1.0.0",
  "description": "akamai-agent-1.0.0"
}

작성을 마치면 Create new version을 클릭합니다.

3.3 EdgeWorker 활성화

1. 생성한 버전에서 Activate version을 클릭합니다.
2. 네트워크로 Production을 선택하고 Activate version을 클릭합니다.
3. Current Status가 Complete가 될 때까지 기다립니다.

참고

활성화에는 몇 분 정도 걸릴 수 있습니다. Complete가 된 뒤 다음 단계를 진행하세요.

4. Property 설정

4.1 Property 선택

• 새 Property를 만드는 경우: New Property > Create Property > Guide me를 선택하고 호스트 이름을 입력합니다. 호스트 이름 검증, Edge Certificate 선택, 캐싱 설정을 거쳐 STEP 1~5를 완료한 뒤 Exit를 클릭합니다.
• 기존 Property를 사용하는 경우: Properties에서 대상 Property를 선택하고, 가장 최신 버전을 엽니다.

4.2 Property 변수 추가

Property의 Property Variables에 아래 변수를 추가합니다.

변수	값	설명
NF_CLIENT_ID	{CLIENT_ID}	NetFUNNEL 콘솔에서 확인한 클라이언트 아이디
NF_CLIENT_IP	(비워 둠)	사용자 IP를 담는 변수. 아래 NF EdgeWorker 규칙에서 값을 채웁니다.

참고

Property Manager에서 사용자 변수는 PMUSER_ 접두사가 붙어 PMUSER_NF_CLIENT_ID, PMUSER_NF_CLIENT_IP로 참조됩니다.

4.3 규칙 추가

Property Configuration Settings에 아래 3개의 규칙을 추가합니다. 명시하지 않은 항목은 기본값을 사용합니다.

NF EdgeWorker

HTML 페이지 요청에서 사용자 IP를 변수에 저장하고, NetFUNNEL EdgeWorker를 실행합니다.

구분	항목	값
Criteria	Path	matches one of /*
Criteria	File Extension	is one of html
Behavior	Set Variable	Variable: PMUSER_NF_CLIENT_IP Create Value From: Expression Expression: {{builtin.AK_CLIENT_REAL_IP}} Operation: None
Behavior	EdgeWorkers	Identifier: 3단계에서 생성한 EdgeWorker

NF Core Origin

대기열 처리 요청(/ts.wseq)을 NetFUNNEL 서버로 전달합니다.

구분	항목	값
Criteria	Path	matches one of /ts.wseq
Behavior	Origin Server	Origin Type: Your Origin Origin Server Hostname: {CLIENT_ID}.netfunnel.stclab.com Forward Host Header: Origin Hostname Cache Key Hostname: Origin Hostname

NF Setting Origin

NetFUNNEL 설정 파일 요청을 설정 파일 저장소로 전달합니다.

구분	항목	값
Criteria	Path	matches one of /{CLIENT_ID}.netfunnel/nf-setting.json
Behavior	Origin Server	Origin Type: Your Origin Origin Server Hostname: nf-setting-bucket.stclab.com Forward Host Header: Origin Hostname Cache Key Hostname: Origin Hostname

주의

{CLIENT_ID}는 실제 클라이언트 아이디로 바꿔 입력합니다. 예를 들어 클라이언트 아이디가 stclab-0000이면 Origin Server Hostname은 stclab-0000.netfunnel.stclab.com입니다.

5. 저장 및 활성화

1. 화면 우측 하단의 Save를 클릭합니다.
2. Activate 탭으로 이동해 Production Network의 Activate v{버전} on Production을 클릭합니다.
3. 검증 결과의 경고 내용을 확인하고 체크한 뒤, 다시 Activate v{버전} on Production을 클릭합니다.

주의

Property 변수나 규칙을 변경한 뒤에는 반드시 다시 Save하고 Production에 활성화해야 변경 사항이 적용됩니다.

6. 부가 기능 설정

Property 변수와 규칙을 추가해 부가 기능을 사용할 수 있습니다.

기능	설정 위치	기본값	설명
선의의 봇 제외	NF EdgeWorker 규칙의 Criteria에 User Agent is not one of 추가	-	검색엔진 등 선의의 봇 User-Agent를 대기열 제어에서 제외합니다.
키 자동 반납	NF_RETURN_KEY 변수	true	true: 진입 후 즉시 키를 반납합니다. false: 세그먼트의 타임아웃 시점에 반납합니다.
대기실 도메인	NF_VWR_PAGE_DOMAIN 변수	agent-lib.stclab.com	대기실 페이지 도메인을 지정합니다. 형식: http(s)://{CNAME_DOMAIN}. 사용 전 STCLab에 도메인 등록을 요청해야 합니다.
쿠키 도메인	NF_COOKIE_DOMAIN 변수	현재 페이지 도메인	키 쿠키의 도메인을 지정합니다. 형식: .{MAIN_DOMAIN} (예: .stclab.com). 하위 도메인 간에 키를 공유할 때 사용합니다.

7. 트리거 규칙 설정

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

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