Docker 배포

Docker로 AnyCrawl을 셀프 호스팅하는 단계별 가이드, 구성 옵션 및 모범 사례

사전 빌드 이미지로 Docker 사용

AnyCrawl은 GitHub Container Registry를 통해 사전 빌드 Docker 이미지를 제공합니다. 소스에서 빌드하지 않고도 빠르게 배포할 수 있습니다.

제공 이미지

GitHub Container Registry에서 다음 이미지를 사용할 수 있습니다.

anycrawl: 올인원 이미지. 모든 서비스와 의존성 포함.
anycrawl-api: 메인 API 서비스
anycrawl-scrape-cheerio: Cheerio 스크래핑 엔진
anycrawl-scrape-playwright: Playwright 스크래핑 엔진
anycrawl-scrape-puppeteer: Puppeteer 스크래핑 엔진

빠른 시작

AnyCrawl용 올인원 사전 빌드 이미지는 ghcr.io/any4ai/anycrawl:latest이며 모든 서비스와 의존성을 포함합니다. 다음으로 실행할 수 있습니다.

docker run -p 8080:8080 ghcr.io/any4ai/anycrawl:latest

참고: arm64 이미지에는 scrape-puppeteer 서비스가 포함되지 않았습니다. Puppeteer가 꼭 필요하면 docker run에 platform을 linux/amd64로 지정하세요.

docker run -p 8080:8080 --platform linux/amd64 ghcr.io/any4ai/anycrawl:latest

참고: 네이티브 arm64 이미지보다 성능이 낮아질 수 있습니다.

백그라운드 실행:

docker run -d -p 8080:8080 ghcr.io/any4ai/anycrawl:latest

Arm64에서 실행하며(Puppeteer 미지원) 다음 이미지를 쓸 수 있습니다.

docker run -p 8080:8080 ghcr.io/any4ai/anycrawl:latest-arm64

환경 변수와 함께

# 사용자 정의 구성으로 실행
docker run -d \
  -p 8080:8080 \
  -e NODE_ENV=production \
  -e ANYCRAWL_API_AUTH_ENABLED=false \
  -e ANYCRAWL_HEADLESS=true \
  ghcr.io/any4ai/anycrawl:latest

`.env` 파일과 함께

# 로컬 .env 파일 마운트
docker run -d \
  -p 8080:8080 \
  -v $(pwd)/.env:/usr/src/app/.env:ro \
  ghcr.io/any4ai/anycrawl:latest

Docker 빌드

직접 이미지를 빌드하려면 아래를 따르세요.

사전 요구 사항

Docker: 20.10 이상
Docker Compose: 2.0 이상

Docker 및 Docker Compose 설치

macOS

brew install docker docker-compose

# 또는 Docker Desktop
# https://www.docker.com/products/docker-desktop

Ubuntu/Debian

sudo apt-get update
sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update

sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

빠른 시작(소스)

1. 저장소 클론

git clone https://github.com/any4ai/AnyCrawl.git
cd AnyCrawl

2. 서비스 시작

docker compose up --build

# 또는 백그라운드
docker compose up --build -d

3. 배포 확인

docker compose ps
curl http://localhost:8080/health

서비스 아키텍처

AnyCrawl은 마이크로서비스 구조를 사용합니다.

핵심 서비스

서비스 이름	설명	포트	의존성
`api`	API 게이트웨이 및 메인 인터페이스	8080	redis
`scrape-puppeteer`	Puppeteer 스크래핑 엔진	-	redis
`scrape-playwright`	Playwright 스크래핑 엔진	-	redis
`scrape-cheerio`	Cheerio 스크래핑 엔진(SPA 미지원)	-	redis
`redis`	메시지 큐 및 캐시	6379	-

환경 변수

기본

변수 이름	설명	기본값	예
`NODE_ENV`	런타임 환경	`production`	`production`, `development`
`ANYCRAWL_API_PORT`	API 포트	`8080`	`8080`

스크래핑

변수 이름	설명	기본값	예
`ANYCRAWL_HEADLESS`	헤드리스 모드	`true`	`true`, `false`
`ANYCRAWL_PROXY_URL`	기본 프록시 주소	-	`http://proxy:8080`
`ANYCRAWL_PROXY_STEALTH_URL`	스텔스 프록시 주소	-	`http://residential-proxy:8080`
`ANYCRAWL_PROXY_STEALTH_CREDITS`	스텔스 프록시 사용 시 추가 차감 크레딧	`5`	`5`
`ANYCRAWL_STEALTH_TIMEOUT_MS`	스텔스/auto 프록시 모드 기본 타임아웃(ms)	`120000`	`120000`
`ANYCRAWL_IGNORE_SSL_ERROR`	SSL 오류 무시	`true`	`true`, `false`

데이터베이스

변수 이름	설명	기본값
`ANYCRAWL_API_DB_TYPE`	DB 타입	`sqlite`
`ANYCRAWL_API_DB_CONNECTION`	연결 경로	`/usr/src/app/db/database.db`

Redis

변수 이름	설명	기본값
`ANYCRAWL_REDIS_URL`	Redis URL	`redis://redis:6379`

인증

변수 이름	설명	기본값
`ANYCRAWL_API_AUTH_ENABLED`	API 인증 사용 여부	`false`

사용자 정의 구성

환경 파일 생성

cp .env.example .env

`.env` 예시

NODE_ENV=production
ANYCRAWL_API_PORT=8080

ANYCRAWL_HEADLESS=true
ANYCRAWL_PROXY_URL=
ANYCRAWL_PROXY_STEALTH_URL=
ANYCRAWL_PROXY_STEALTH_CREDITS=5
ANYCRAWL_STEALTH_TIMEOUT_MS=120000
ANYCRAWL_IGNORE_SSL_ERROR=true

ANYCRAWL_API_DB_TYPE=sqlite
ANYCRAWL_API_DB_CONNECTION=/usr/src/app/db/database.db

ANYCRAWL_REDIS_URL=redis://redis:6379

ANYCRAWL_API_AUTH_ENABLED=false

데이터 영속성

볼륨

volumes:
    - ./storage:/usr/src/app/storage # 스크래핑 데이터
    - ./db:/usr/src/app/db # DB 파일
    - redis-data:/data # Redis 데이터

백업

docker compose exec api cp /usr/src/app/db/database.db /usr/src/app/storage/backup.db

docker compose exec redis redis-cli SAVE
docker compose cp redis:/data/dump.rdb ./backup/

자주 쓰는 명령

서비스 관리

docker compose up -d
docker compose down
docker compose restart api
docker compose logs -f api

스케일링

docker compose up -d --scale scrape-puppeteer=3
docker compose up -d --scale scrape-playwright=2

모니터링

docker compose ps
docker stats
docker compose logs -f --tail=100 api

문제 해결

흔한 이슈

1. 포트 충돌

lsof -i :8080

# docker-compose.yml에서 포트 매핑 변경
ports:
  - "8081:8080"

2. 메모리 부족

docker stats
# Docker Desktop → Settings → Resources → Memory

3. DB 연결 실패

ls -la ./db/
docker compose down -v
docker compose up --build

4. Redis 연결 실패

docker compose exec redis redis-cli ping
docker compose logs redis

디버그 모드

export NODE_ENV=development
export DEBUG=anycrawl:*
docker compose up --build

프로덕션 배포

보안

인증 켜기:

ANYCRAWL_API_AUTH_ENABLED=true

켜면 ApiKey를 추가하고 요청 헤더에 사용합니다.

API 키 생성

ANYCRAWL_API_AUTH_ENABLED=true인 경우 저장소 루트에서:

pnpm --filter api key:generate
pnpm --filter api key:generate -- default

출력된 uuid, key, credits를 확인합니다. Authorization: Bearer <KEY> 헤더에 키를 넣습니다.

Docker 컨테이너 안에서 실행

Docker Compose:

docker compose exec api pnpm --filter api key:generate
docker compose exec api pnpm --filter api key:generate -- default

단일 컨테이너(<container_name_or_id> 교체):

docker exec -it <container_name_or_id> pnpm --filter api key:generate
docker exec -it <container_name_or_id> pnpm --filter api key:generate -- default

HTTPS 사용:

services:
    nginx:
        image: nginx:alpine
        ports:
            - "443:443"
        volumes:
            - ./nginx.conf:/etc/nginx/nginx.conf
            - ./ssl:/etc/ssl/certs

nginx를 리버스 프록시로 사용합니다.

업데이트 및 유지보수

docker compose pull
docker compose up --build -d
docker image prune -f

목차