Files
dahyeon a0d218a169 Implements a comprehensive web crawler microservice
Introduces a complete NestJS-based web crawler microservice. This release establishes a robust system for web data extraction through a flexible Pipeline/Stage architecture.

Key features include:
- Supports both static (axios, cheerio) and dynamic (Playwright) page crawling.
- Implements diverse triggering options: cron-based scheduling, NATS event-driven, and manual API calls.
- Enhances system resilience with domain-specific rate limiting and configurable exponential backoff retry mechanisms.
- Provides dedicated API endpoints and database schemas for managing pipelines, stages, and execution history.
- Ensures data persistence by saving crawl results to MinIO.

The `README.md` is entirely rewritten to provide comprehensive documentation on features, architecture, setup, API usage, and troubleshooting. Core dependencies for crawling, scheduling, and API validation are added, and database models are refactored to align with the new crawler system's data structures.
2025-12-21 14:29:25 +00:00

18 KiB

MSA 기반 웹 크롤러 서비스

NestJS 기반의 마이크로서비스 아키텍처 웹 크롤러 시스템입니다. 정적/동적 웹페이지 크롤링, Pipeline/Stage 기반 병렬 실행, 다중 트리거 지원, Rate Limiting 등의 기능을 제공합니다.

주요 기능

크롤링 엔진

  • 정적 페이지 크롤링: axios + cheerio 기반 HTML 파싱
  • 동적 SPA 크롤링: Playwright 기반 JavaScript 렌더링 지원
  • 셀렉터 기반 데이터 추출: CSS 셀렉터로 원하는 데이터만 추출
  • 속성 추출: 이미지 URL 등 HTML 속성 추출 지원

Pipeline/Stage 아키텍처

  • 병렬 실행: 여러 Stage를 동시에 실행하여 성능 최적화
  • 실행 기록: 각 Stage의 실행 이력 및 결과 저장
  • 메타데이터 기반: 유연한 설정 및 확장 가능한 구조

트리거 시스템

  • 스케줄 트리거: Cron 표현식 기반 정기 실행
  • 이벤트 트리거: NATS 메시지 기반 이벤트 드리븐 실행
  • API 트리거: REST API 호출로 수동 실행

안정성 및 성능

  • Rate Limiting: 도메인별 토큰 버킷 알고리즘으로 요청 제한
  • 재시도 로직: Exponential backoff 기반 자동 재시도
  • 에러 알림: 실패 시 NATS를 통한 알림 발송
  • 결과 저장: MinIO에 크롤링 결과 자동 저장

기술 스택

프레임워크 및 런타임

  • NestJS 11: TypeScript 기반 서버 프레임워크
  • Node.js: JavaScript 런타임

크롤링 및 파싱

  • axios: HTTP 클라이언트
  • cheerio: 서버사이드 jQuery (HTML 파싱)
  • playwright: 브라우저 자동화 (동적 페이지 크롤링)

데이터베이스 및 스토리지

  • MongoDB + Mongoose: NoSQL 데이터베이스
  • MinIO: S3 호환 객체 스토리지

메시징 및 이벤트

  • NATS: 메시지 브로커 (이벤트 트리거 및 알림)

스케줄링 및 인증

  • @nestjs/schedule + cron: 작업 스케줄링
  • JWT (jose): 토큰 기반 인증 (Microsoft Entra ID 지원)
  • Infisical: 중앙화된 비밀값 관리

아키텍처

┌─────────────────────────────────────────────────────────────┐
│                         REST API                            │
│              (JWT Authentication Required)                  │
└────────────────────────┬────────────────────────────────────┘
                         │
        ┌────────────────┼────────────────┐
        │                │                │
   ┌────▼─────┐   ┌──────▼──────┐   ┌────▼─────┐
   │  Cron    │   │  NATS Event │   │   API    │
   │ Trigger  │   │   Trigger   │   │ Trigger  │
   └────┬─────┘   └──────┬──────┘   └────┬─────┘
        │                │                │
        └────────────────┼────────────────┘
                         │
              ┌──────────▼──────────┐
              │  Pipeline Engine    │
              │  (병렬 실행 관리)     │
              └──────────┬──────────┘
                         │
        ┌────────────────┼────────────────┐
        │                │                │
   ┌────▼─────┐   ┌──────▼──────┐   ┌────▼─────┐
   │ Stage 1  │   │  Stage 2    │   │ Stage 3  │
   │(EventSrc)│   │ (EventSrc)  │   │(EventSrc)│
   └────┬─────┘   └──────┬──────┘   └────┬─────┘
        │                │                │
   ┌────▼─────┐   ┌──────▼──────┐   ┌────▼─────┐
   │ Crawler  │   │   Crawler   │   │ Crawler  │
   │ Service  │   │   Service   │   │ Service  │
   └────┬─────┘   └──────┬──────┘   └────┬─────┘
        │                │                │
        └────────────────┼────────────────┘
                         │
              ┌──────────▼──────────┐
              │   MinIO Storage     │
              │  (크롤링 결과 저장)   │
              └─────────────────────┘

설치

필수 요구사항

  • Node.js: 18.x 이상
  • MongoDB: 4.x 이상
  • NATS: 2.x 이상
  • MinIO: S3 호환 객체 스토리지
  • Infisical: 비밀값 관리 (선택)

1. 저장소 클론 및 패키지 설치

git clone https://git.dahyeon.us/dahyeon/crawler.git
cd crawler
npm install

2. Playwright 브라우저 설치

npx playwright install chromium

3. 환경 변수 설정

환경별 .env 파일을 생성합니다:

# 개발 환경
cp env-vars/example.env .env.dev

# 테스트 환경
cp env-vars/example.env .env.test

# 프로덕션 환경
cp env-vars/example.env .env.prod

필수 환경 변수 (Infisical 사용 시)

# Infisical 설정
INFISICAL_SITE_URL=https://app.infisical.com
INFISICAL_CLIENT_ID=your-client-id
INFISICAL_CLIENT_SECRET=your-client-secret
INFISICAL_PROJECT_ID=a33f45fb-7564-4e4e-9931-96201395d110

Infisical을 통해 다음 값들을 관리:

  • MONGODB_CONNECTION_STRING: MongoDB 연결 문자열
  • NATS_ENDPOINT: NATS 서버 주소
  • NATS_USER: NATS 사용자명
  • NATS_PASS: NATS 비밀번호
  • JWT_CLAIM_AUDIENCE: JWT 검증 audience
  • MICROSOFT_ENTRAID_TENANT_ID: Azure AD 테넌트 ID
  • MINIO_ENDPOINT: MinIO 서버 주소
  • MINIO_ACCESS_KEY: MinIO 액세스 키
  • MINIO_SECRET_KEY: MinIO 시크릿 키

4. TLS 인증서 (선택)

NATS TLS 연결을 위해 internal-service-ca.pem 파일을 프로젝트 루트에 배치합니다.

실행

개발 모드

npm run start:dev

프로덕션 빌드

npm run build
npm run start:prod

환경 전환

# 테스트 환경
NODE_ENV=test npm run start:dev

# 프로덕션 환경
NODE_ENV=prod npm run start:prod

REST API

서버 실행 후 Swagger 문서: http://localhost:3000/api

인증

모든 API는 JWT 인증이 필요합니다 (일부 Public 엔드포인트 제외).

Authorization: Bearer {JWT_TOKEN}

Pipelinedef 관리

1. Pipelinedef 생성

POST /api/v1/crawler/pipelinedefs
Content-Type: application/json

{
  "apiVersion": "v1",
  "trigger": {
    "type": "always"
  },
  "stageIds": ["stage-id-1", "stage-id-2"],
  "schedule": {
    "cron": "0 0 * * *",
    "timezone": "Asia/Seoul"
  }
}

2. Pipelinedef 목록 조회

GET /api/v1/crawler/pipelinedefs?page=1&limit=20

3. Pipelinedef 상세 조회

GET /api/v1/crawler/pipelinedefs/{id}

4. Pipelinedef 수정

PUT /api/v1/crawler/pipelinedefs/{id}
Content-Type: application/json

{
  "schedule": {
    "cron": "0 12 * * *"
  }
}

5. Pipelinedef 삭제

DELETE /api/v1/crawler/pipelinedefs/{id}

Stagedef 관리

1. Stagedef 생성

POST /api/v1/crawler/stagedefs
Content-Type: application/json

{
  "apiVersion": "v1",
  "name": "Example Crawler",
  "topic": "crawler.results.example",
  "eventSource": [
    {
      "type": "web",
      "name": "example-source",
      "metadatas": [
        {
          "key": "url",
          "value": "https://example.com",
          "dataType": "string"
        },
        {
          "key": "selectors",
          "value": "{\"title\":\"h1\",\"content\":\".main\"}",
          "dataType": "json"
        },
        {
          "key": "dynamic",
          "value": "false",
          "dataType": "string"
        }
      ]
    }
  ]
}

2. Stagedef 목록 조회

GET /api/v1/crawler/stagedefs?page=1&limit=20

Pipeline 실행

1. Pipeline 수동 실행

POST /api/v1/crawler/pipelines/trigger
Content-Type: application/json

{
  "pipelineDefId": "pipeline-def-id",
  "variables": {
    "customVar": "value"
  }
}

2. 실행된 Pipeline 목록

GET /api/v1/crawler/pipelines?page=1&limit=20&status=completed

status 옵션: completed, failed, partial

3. Pipeline 실행 상세

GET /api/v1/crawler/pipelines/{pipelineId}

4. Pipeline의 Stage 목록

GET /api/v1/crawler/pipelines/{pipelineId}/stages

모니터링

1. 등록된 스케줄 목록

GET /api/v1/crawler/schedules

2. Rate Limit 상태

GET /api/v1/crawler/rate-limits

3. 트리거 재로드

POST /api/v1/crawler/triggers/reload

4. Health Check (Public)

GET /api/v1/crawler/health

사용 예시

1. 정적 웹페이지 크롤링

{
  "type": "web",
  "name": "news-crawler",
  "metadatas": [
    {
      "key": "url",
      "value": "https://news.example.com/latest",
      "dataType": "string"
    },
    {
      "key": "selectors",
      "value": "{\"title\":\"h2.article-title\",\"summary\":\".article-summary\",\"author\":\".author-name\"}",
      "dataType": "json"
    },
    {
      "key": "dynamic",
      "value": "false",
      "dataType": "string"
    }
  ]
}

2. 동적 SPA 페이지 크롤링

{
  "type": "web",
  "name": "spa-crawler",
  "metadatas": [
    {
      "key": "url",
      "value": "https://spa-app.example.com/products",
      "dataType": "string"
    },
    {
      "key": "selectors",
      "value": "{\"products\":\".product-item\",\"price\":\".price\"}",
      "dataType": "json"
    },
    {
      "key": "dynamic",
      "value": "true",
      "dataType": "string"
    },
    {
      "key": "waitSelector",
      "value": ".products-loaded",
      "dataType": "string"
    }
  ]
}

3. 이미지 URL 추출

{
  "type": "web",
  "name": "image-crawler",
  "metadatas": [
    {
      "key": "url",
      "value": "https://gallery.example.com",
      "dataType": "string"
    },
    {
      "key": "selectors",
      "value": "{\"title\":\"h1.gallery-title\"}",
      "dataType": "json"
    },
    {
      "key": "extractAttributes",
      "value": "{\"imageUrl\":\"img.gallery-image@src\",\"thumbnail\":\"img.thumb@data-src\"}",
      "dataType": "json"
    },
    {
      "key": "dynamic",
      "value": "false",
      "dataType": "string"
    }
  ]
}

4. 매일 자정 실행하는 스케줄 설정

{
  "apiVersion": "v1",
  "trigger": {
    "type": "always"
  },
  "stageIds": ["stage-id-1"],
  "schedule": {
    "cron": "0 0 * * *",
    "timezone": "Asia/Seoul"
  }
}

5. NATS 이벤트로 트리거

{
  "apiVersion": "v1",
  "trigger": {
    "type": "kafka-event",
    "kafkaEvent": {
      "topic": "crawler.trigger.news"
    }
  },
  "stageIds": ["stage-id-1"]
}

프로젝트 구조

src/
├── main.ts                      # 애플리케이션 진입점
├── app.module.ts                # 루트 모듈
│
├── global/                      # 글로벌 공유 모듈
│   ├── auth/                    # JWT 인증
│   │   ├── jwt.service.ts
│   │   ├── jwt.guard.ts
│   │   └── decorators...
│   ├── secret/                  # Infisical 비밀값 관리
│   │   └── secret.service.ts
│   ├── database/                # MongoDB 연결
│   │   ├── connection.service.ts
│   │   ├── schema.ts            # Mongoose 스키마
│   │   └── types.d.ts
│   ├── nats/                    # NATS 메시징
│   │   └── nats.service.ts
│   └── minio/                   # MinIO 파일 저장소
│       └── minio.service.ts
│
└── crawler/                     # 크롤러 비즈니스 로직
    ├── crawler.module.ts
    ├── crawler.controller.ts    # REST API 컨트롤러
    │
    ├── services/
    │   ├── crawler.service.ts           # HTTP + Playwright 크롤링
    │   ├── rate-limiter.service.ts      # Rate Limiting
    │   ├── retry.service.ts             # 재시도 로직
    │   ├── stage-executor.service.ts    # Stage 실행
    │   ├── pipeline-engine.service.ts   # Pipeline 관리
    │   └── trigger.service.ts           # 트리거 시스템
    │
    ├── dto/
    │   ├── common.dto.ts
    │   ├── create-pipelinedef.dto.ts
    │   ├── create-stagedef.dto.ts
    │   └── trigger-pipeline.dto.ts
    │
    └── interfaces/
        └── crawler-result.interface.ts

데이터베이스 스키마

Pipelinedef

파이프라인 정의 (재사용 가능한 템플릿)

{
  apiVersion: string;           // "v1"
  trigger: PipelineTrigger;     // always | kafka-event
  stage: ObjectId[];            // Stagedef ID 배열
  metadatas: Metadata[];        // 커스텀 메타데이터
}

Pipeline

실행된 파이프라인 인스턴스

{
  apiVersion: string;
  name: string;                 // "pipeline-1234567890"
  stage: Stage[];               // 실행 중인 Stage 배열
  metadatas: Metadata[];        // 실행 정보 (triggeredBy, status 등)
  createdAt: Date;
  updatedAt: Date;
}

Stagedef

스테이지 정의

{
  apiVersion: string;
  name: string;
  taxonomy?: string;
  eventSource: EventSource[];   // 크롤링 대상 설정
  topic: string;                // NATS 발행 토픽
  metadatas: Metadata[];
}

Stage

실행된 스테이지

{
  apiVersion: string;
  name: string;
  executions: Execution[];      // 실행 기록
  status: "pending" | "in-progress" | "completed" | "failed" | "cancelled" | "skipped";
  metadatas: Metadata[];
}

Execution

개별 실행 기록

{
  status: "pending" | "in-progress" | "completed" | "failed" | "cancelled" | "skipped";
  metadatas: Metadata[];        // crawlResult, storageKey 등
  createdAt: Date;
  updatedAt: Date;
}

Rate Limiting

도메인별 제한 설정

// 기본값: 10 req, 초당 2개 보충
rateLimiter.setLimit('example.com', {
  maxTokens: 20,    // 최대 20개 토큰
  refillRate: 5     // 초당 5개 보충
});

현재 상태 조회

GET /api/v1/crawler/rate-limits

응답:

{
  "example.com": {
    "config": {
      "maxTokens": 20,
      "refillRate": 5
    },
    "available": 15
  }
}

재시도 전략

RetryStrategy 설정

{
  limit: 3,              // 최대 3회 재시도
  delay: 1000,           // 초기 대기 시간 1초
  backoff: 2,            // 2배씩 증가 (1초 → 2초 → 4초)
  when: [
    "failed",            // 모든 실패
    "5xx",               // 5xx 에러
    "network"            // 네트워크 에러
  ],
  notify: [
    "admin-channel"      // 실패 시 알림 채널
  ]
}

NATS 이벤트

발행되는 이벤트

Pipeline 시작

Topic: crawler.pipeline.started
Payload: {
  pipelineId: string;
  pipelineDefId: string;
  triggeredBy: "api" | "schedule" | "nats";
  timestamp: string;
}

Pipeline 완료

Topic: crawler.pipeline.completed
Payload: {
  pipelineId: string;
  status: "completed" | "failed" | "partial";
  triggeredBy: "api" | "schedule" | "nats";
  stageResults: Array<{
    stageName: string;
    status: string;
    error?: string;
  }>;
  completedAt: string;
}

Stage 시작

Topic: crawler.stage.started
Payload: {
  pipelineId: string;
  stageIndex: number;
  stageName: string;
  timestamp: string;
}

Stage 완료 (커스텀 토픽)

Topic: {stagedef.topic}
Payload: {
  pipelineId: string;
  stageIndex: number;
  stageName: string;
  status: "completed" | "failed";
  results: Array<{
    url: string;
    success: boolean;
    parsedData: object;
  }>;
  timestamp: string;
}

개발

테스트

# 단위 테스트
npm run test

# E2E 테스트
npm run test:e2e

# 커버리지
npm run test:cov

린트

npm run lint
npm run format

빌드

npm run build

트러블슈팅

Playwright 브라우저 설치 실패

# 수동 설치
npx playwright install-deps
npx playwright install chromium

MongoDB 연결 실패

  • MONGODB_CONNECTION_STRING 환경 변수 확인
  • MongoDB 서버 상태 확인
  • 네트워크 연결 및 방화벽 설정 확인

NATS 연결 실패

  • NATS_ENDPOINT, NATS_USER, NATS_PASS 확인
  • TLS 인증서 경로 확인 (internal-service-ca.pem)
  • NATS 서버 상태 확인

Rate Limit 초과

// 도메인별 제한 조정
await fetch('http://localhost:3000/api/v1/crawler/rate-limits');
// 또는 코드에서 직접 설정
rateLimiter.setLimit('slow-domain.com', { maxTokens: 5, refillRate: 1 });

보안 고려사항

  1. JWT 인증: 모든 API 엔드포인트는 JWT 인증 필요
  2. 비밀값 관리: Infisical을 통한 중앙화된 비밀값 관리
  3. TLS 통신: NATS 연결 시 TLS 인증서 사용
  4. Rate Limiting: 크롤링 대상 서버 보호
  5. Input Validation: DTO 기반 요청 검증

라이선스

MIT

작성자

기술 지원

이슈 및 문의: Repository Issues 페이지