본문으로 건너뛰기

설치 및 초기화

개요​

BotManager Fastly Agent는 Fastly Compute 플랫폼에서 동작하는 엣지 기반 봇 탐지 및 차단 솔루션입니다.

주요 기능:

  • 실시간 봇/매크로 탐지 및 차단
  • 세션 기반 사용자 관리
  • 캡차/챌린지 페이지 제공
  • 설정 기반 bypass 로직

Fastly Compute란?​

Fastly Compute는 WebAssembly(WASM) 기반의 서버리스 엣지 컴퓨팅 플랫폼입니다.

특징:

  • 전 세계 엣지 로케이션에서 실행
  • 초고속 응답 시간 (sub-millisecond)
  • 자동 스케일링
  • 개발자 친화적 환경

Fastly Compute에 대한 자세한 내용은 Fastly 공식 문서를 참조하세요.

정보

이 가이드는 기존에 Fastly Compute Service가 운영 중인 환경에서 BotManager Agent를 추가 설치하는 방법을 다룹니다.

설치 방법​

BotManager Fastly Agent 설치를 위해 다음 4단계를 순서대로 진행하세요.

1. Origins 설정​

BotManager 탐지 서버를 Origin으로 등록합니다.

  1. 설치하려는 Compute Services의 Origins 탭으로 이동

  2. Create a host 클릭

  3. 다음 정보를 입력합니다:

    필드값설명
    Namebotmanager_serverOrigin 이름
    Addressbotmanager.stclab.com탐지 서버 주소
    Port443HTTPS 포트
    Use SSL✅ 체크SSL 사용
    Certificate hostnamebotmanager.stclab.com인증서 호스트명
Origins 설정 팁

Origin 설정 후 연결 테스트를 통해 정상적으로 연결되는지 확인하세요.

2. Package 업로드​

BotManager Fastly Agent 패키지를 업로드합니다.

  1. BotManager Fastly Agent 다운로드:

    https://cdn-botmanager.stclab.com/agents/cdn/fastly/botmanager-fastly-agent.tar.gz

  2. Package 탭으로 이동

  3. Upload new package 클릭

  4. 다운로드한 botmanager-fastly-agent.tar.gz 파일을 선택하거나 Drag and drop으로 업로드

  5. Upload success 메시지 확인

Package 버전

패키지 업로드 후 버전 정보를 확인하여 올바른 버전이 업로드되었는지 확인하세요.

3. Config Stores 설정​

BotManager Agent의 설정 값을 Config Store에 저장합니다.

  1. Resources → Config stores 이동

  2. Create store 클릭

  3. Store name: bm_config 입력

  4. Add item 클릭 후 아래 설정 항목 추가

필수 설정 확인

적용 도메인을 정확히 확인하기 위해 하단 도메인을 선택하세요.

필수 설정​

다음 설정은 반드시 추가해야 합니다:

KeyValue설명
BM_TENANT_ID{TENANT ID}고객 식별자 (BotManager 콘솔에서 확인)
BM_DOMAIN_NAME{DOMAIN}적용 대상 도메인 (예: example.com)
필수 설정 누락 시

필수 설정이 누락되면 Agent가 정상적으로 동작하지 않습니다. 반드시 확인하세요.

선택 설정​

다음 설정은 기본값으로 동작하며, 필요시에만 변경합니다:

Key기본값설명
BM_SERVER_URLhttps://botmanager.stclab.com/api/v1/macro탐지 서버 URL
BM_PROTECTION_URLhttps://cdn-botmanager.stclab.com차단 페이지 URL
BM_STATIC_BYPASStrue정적 리소스 bypass 여부
BM_BYPASSfalse전체 bypass 여부
BM_SERVER_TIMEOUT1000탐지 서버 타임아웃(ms)
BM_LOGLEVELERROR로그 레벨 (WARN, INFO, DEBUG)
BM_EXCLUDED_PATHS/api,/health제외 경로 (쉼표 구분)
BM_EXCLUDED_QUERYSuser,password제외 쿼리 (쉼표 구분)
선택 설정 활용

특정 경로나 쿼리 파라미터를 탐지에서 제외하려면 BM_EXCLUDED_PATHS와 BM_EXCLUDED_QUERYS를 활용하세요.

4. Service Activation​

설정한 서비스를 활성화하고 캐시를 초기화합니다.

  1. Add version comment 클릭 후 배포 내용 작성

    예: "BotManager Agent v1.0.1 배포"

  2. Service configuration 탭의 Activate 클릭

  3. Service summary 탭의 Purge all 클릭하여 캐시 초기화

활성화 후 확인

Service 활성화 후 실제 요청에서 Agent 헤더가 정상적으로 추가되는지 확인하세요.

기본 동작 테스트​

설치가 완료되면 Agent가 정상적으로 동작하는지 확인하세요.

Agent 헤더 확인​

브라우저 개발자 도구를 통해 Agent 헤더를 확인합니다.

  1. 브라우저 개발자 도구 열기 (F12)

  2. Network 탭 선택

  3. 보호된 사이트 접속

  4. Response Headers에서 다음 헤더 확인:

x-bm-agent: BM-fastly-agent-x.x.x
헤더 확인 팁

첫 요청에서 헤더가 보이지 않으면 페이지를 새로고침하거나 캐시를 비우고 다시 시도하세요.

세션 쿠키 확인​

Agent가 생성한 세션 쿠키를 확인합니다.

  1. Application 탭 (Chrome) 또는 Storage 탭 (Firefox) 선택

  2. Cookies 섹션에서 다음 쿠키 확인:

BM-session-id: [생성된 세션 ID]
  1. 명령줄로 테스트:
# curl을 이용한 헤더 확인
curl -I https://your-domain.com

# 예상 결과:
# HTTP/2 200
# x-bm-agent: BM-fastly-agent-1.0.1
# set-cookie: BM-session-id=...
세션 쿠키

세션 쿠키는 사용자 세션을 추적하기 위해 자동으로 생성됩니다. 브라우저 쿠키 설정에 따라 생성되지 않을 수 있습니다.

문제 해결​

설치 및 운영 중 발생할 수 있는 문제와 해결 방법을 안내합니다.

Agent 헤더가 보이지 않는 경우​

증상: Response Headers에 x-bm-agent 헤더가 표시되지 않음

가능한 원인:

  • Service가 활성화되지 않음
  • Package 업로드 실패
  • Configuration 오류

해결 방법:

  1. Service 상태 확인

    • Service configuration 탭에서 활성화 상태 확인
    • 비활성화 상태라면 Activate 클릭하여 재시도

  2. Package 재업로드

    • Package 탭에서 최신 버전 확인
    • 필요시 패키지 재업로드

  3. Config Store 설정 재확인

    • 필수 설정 항목(BM_TENANT_ID, BM_DOMAIN_NAME) 확인
    • Store 이름이 bm_config인지 확인
Service 활성화 필수

Service를 활성화하지 않으면 Agent가 동작하지 않습니다. 반드시 활성화 상태를 확인하세요.

탐지 서버 연결 실패​

증상: Response Headers에 다음 오류 메시지 표시

x-bm-error: Detection server timeout

해결 방법:

  1. Origins 설정 확인

    • Backend 주소가 botmanager.stclab.com인지 확인
    • SSL 설정이 올바른지 확인
    • Port가 443인지 확인

  2. 타임아웃 설정 조정

    • Config Store에서 BM_SERVER_TIMEOUT 값 증가
    • 기본값: 1000ms → 필요시 2000ms 이상으로 증가

  3. 네트워크 연결 상태 확인

    • Fastly에서 botmanager.stclab.com으로의 연결 가능 여부 확인
타임아웃 설정

네트워크 지연이 있는 환경에서는 BM_SERVER_TIMEOUT 값을 적절히 증가시키는 것이 좋습니다.

Config Store 접근 오류​

증상: Response Headers에 다음 오류 메시지 표시

x-bm-error: Config initialization failed

해결 방법:

  1. Config Store 이름 확인

    • Store 이름이 정확히 bm_config인지 확인
    • 대소문자 구분 주의

  2. 필수 설정 항목 확인

    • BM_TENANT_ID와 BM_DOMAIN_NAME이 모두 설정되어 있는지 확인
    • 값이 올바르게 입력되었는지 확인

  3. Service 연결 확인

    • Service에 Config Store가 올바르게 연결되어 있는지 확인
    • Resources 탭에서 연결 상태 확인
Config Store 오류

Config Store 접근 오류가 발생하면 Agent가 전혀 동작하지 않습니다. 반드시 해결해야 합니다.