Node.js로 고성능 웹서버 만들기: Cluster와 Worker Threads

대용량 트래픽을 견디는 고성능 웹서버 구현하기

Node.js는 단일 스레드 이벤트 루프 기반으로 동작합니다. 따라서 여태까지는 싱글 스레드에서 처리되는 HTTP 웹 서버를 다루었는데요. 그런데 만약 요청의 수가 급증한다면, 멀티 코어 CPU 환경에서 하나의 스레드만 사용해서 요청을 처리하는 것이 다소 아쉽게 느껴질 수 있습니다.

 

만약 멀티 스레드를 활용해서 커버할 수 있는 영역이라면 굳이 인스턴스를 수평 확장할 필요도 없기에 있는 자원을 최대한 효율적으로 활용하는 것이 중요합니다.

 

따라서 웹 서버를 각각 멀티 프로세스/ 멀티 스레드 방식으로 처리해보고 각 방식을 비교 분석하고자 하였습니다.

 

1. cluster 모듈을 활용해 CPU 코어 수만큼 워커 프로세스를 생성

2. Worker Threads 기반 작업 처리

---

왜 멀티 프로세스/스레드가 필요할까?

Node.js의 단일 스레드 모델은 I/O 작업에서는 뛰어난 성능을 보이지만, 다음과 같은 상황에서는 한계가 있습니다.

• CPU 집약적 작업: 이미지 처리, 암호화, 데이터 변환 등
• 멀티코어 활용: 8코어 CPU에서 1코어만 사용하는 것은 낭비
• 장애 격리: 하나의 프로세스가 죽어도 서비스는 계속 운영되어야 함

이를 해결하기 위해 두 가지 도구를 활용할 수 있습니다.

1. Cluster 모듈: 여러 프로세스를 생성해 포트를 공유
2. Worker Threads: 같은 프로세스 내에서 별도 스레드로 무거운 작업 처리

---

Part 1: Cluster로 프로세스 병렬화하기

기본 개념

Cluster 모듈은 Master-Worker 아키텍처를 사용합니다.

• Master: 워커들을 생성하고 관리
• Workers: 실제 HTTP 요청을 처리

핵심은 모든 워커가 같은 포트를 공유하면서도 OS 레벨에서 로드밸런싱이 된다는 점입니다.

실전 구현: net 모듈 기반 Cluster 서버

본 프로젝트에서는 webserver/server.js에 Cluster 모드가 이미 구현되어 있습니다.

// webserver/server.js (실제 구현된 코드)
import cluster from 'cluster';
import os from 'os';
import net from 'net';

// Cluster 모드 설정 (환경변수 또는 명령행 인수로 제어)
const USE_CLUSTER = process.env.USE_CLUSTER === 'true' || process.argv.includes('--cluster');
const NUM_WORKERS = process.env.NUM_WORKERS ? parseInt(process.env.NUM_WORKERS) : os.cpus().length;

console.log(`🔧 Cluster 모드: ${USE_CLUSTER ? '활성화' : '비활성화'}`);

// HTTP 서버 생성 함수
function createServer() {
  const server = net.createServer((socket) => {
    // TCP 소켓을 직접 다루는 순수 net 모듈 기반 구현
    // ... HTTP 요청 파싱 및 응답 처리 로직
  });

  return server;
}

// Cluster 모드에 따른 서버 시작
if (USE_CLUSTER && cluster.isPrimary) {
  console.log(`🚀 Cluster 모드 시작: ${NUM_WORKERS}개 워커 프로세스 생성`);
  console.log(`📊 CPU 코어 수: ${os.cpus().length}`);

  // 워커 프로세스 생성
  for (let i = 0; i < NUM_WORKERS; i++) {
    const worker = cluster.fork();
    console.log(`🔧 워커 프로세스 생성됨: PID ${worker.process.pid}`);
  }

  // 워커 프로세스 종료 시 자동 재시작
  cluster.on('exit', (worker, code, signal) => {
    console.log(
      `💀 워커 프로세스 종료: PID ${worker.process.pid} (코드: ${code}, 시그널: ${signal})`
    );

    if (!worker.exitedAfterDisconnect) {
      console.log('워커 프로세스 재시작 중...');
      const newWorker = cluster.fork();
      console.log(`🔧 새 워커 프로세스 생성됨: PID ${newWorker.process.pid}`);
    }
  });

  // 마스터 프로세스 Graceful Shutdown
  process.on('SIGINT', () => {
    console.log('\n🛑 마스터 프로세스 종료 신호 수신');
    console.log('모든 워커 프로세스에 종료 신호 전송...');

    for (const id in cluster.workers) {
      cluster.workers[id].kill();
    }

    setTimeout(() => {
      console.log('마스터 프로세스 종료');
      process.exit(0);
    }, 2000);
  });
} else {
  // 단일 프로세스 모드 또는 워커 프로세스
  const server = createServer();
  const PORT = 80;
  const HOST = '::'; // IPv6 + IPv4 모두 수용

  server.listen(PORT, HOST, () => {
    const mode = USE_CLUSTER ? `워커 프로세스 (PID: ${process.pid})` : '단일 프로세스';
    console.log(`🚀 Codestargram Web Server running on http://${HOST}:${PORT} [${mode}]`);
  });
}

실행 방법

# 단일 프로세스 모드 (기본값)
npm start

# Cluster 모드 활성화 (CPU 코어 수만큼 워커 생성)
USE_CLUSTER=true npm start
# 또는
node server.js --cluster

# 워커 수 지정
NUM_WORKERS=4 USE_CLUSTER=true npm start

주요 포인트

1. 자동 재시작: 워커가 죽으면 즉시 새로운 워커를 생성
2. Zero Downtime: 한 워커가 죽어도 나머지 워커들이 요청 처리
3. 모니터링: Master가 워커들의 상태를 추적

---

Part 2: Worker Threads로 CPU 작업 분리하기

언제 사용할까?

• 이미지 리사이징/압축
• 대용량 파일 파싱 (CSV, JSON)
• 암호화/복호화 연산
• 복잡한 데이터 변환

Worker Thread 구현 예시

// backend/src/workers/image-processor.ts
import { Worker } from 'worker_threads';
import path from 'path';

export interface ImageProcessTask {
  imagePath: string;
  targetWidth: number;
  targetHeight: number;
}

export function processImageAsync(task: ImageProcessTask): Promise<string> {
  return new Promise((resolve, reject) => {
    const worker = new Worker(path.join(__dirname, 'image-worker.js'), {
      workerData: task
    });

    worker.on('message', (result) => {
      resolve(result.outputPath);
    });

    worker.on('error', reject);

    worker.on('exit', (code) => {
      if (code !== 0) {
        reject(new Error(`Worker stopped with exit code ${code}`));
      }
    });
  });
}

// backend/src/workers/image-worker.js
import { parentPort, workerData } from 'worker_threads';
import sharp from 'sharp';
import path from 'path';

const { imagePath, targetWidth, targetHeight } = workerData;

(async () => {
  try {
    const outputPath = path.join(
      path.dirname(imagePath),
      `resized_${path.basename(imagePath)}`
    );

    await sharp(imagePath)
      .resize(targetWidth, targetHeight, {
        fit: 'cover',
        position: 'center'
      })
      .toFile(outputPath);

    parentPort?.postMessage({ outputPath });
  } catch (error) {
    throw error;
  }
})();

게시글 작성 API에 적용하기

현재 프로젝트의 게시글 작성 로직(backend/src/routes/postRoutes.ts:224-382)에 Worker Thread를 통합하면 다음과 같습니다:

// backend/src/routes/postRoutes.ts
import { processImageAsync } from '../workers/image-processor.js';

async function createPostWithMultipart(request: HttpRequest): Promise<HttpResponse> {
  try {
    const multipartData = request.multipartData;

    // ... 기존 검증 로직 ...

    let savedImageUrl = null;

    if (multipartData.files.length > 0) {
      const imageFile = multipartData.files.find((file) => file.name === 'image');

      if (imageFile) {
        // 원본 파일 저장
        const saveResult = await saveUploadedFile(imageFile.data, imageFile.filename);

        // Worker Thread로 이미지 리사이징 (비동기, 메인 스레드 차단 없음)
        const processedPath = await processImageAsync({
          imagePath: saveResult.path,
          targetWidth: 800,
          targetHeight: 600
        });

        savedImageUrl = `/uploads/${path.basename(processedPath)}`;
        console.log(`✅ 이미지 처리 완료: ${processedPath}`);
      }
    }

    // 게시글 생성
    const newPost = {
      id: (postIdCounter++).toString(),
      userId: 'anonymous',
      username: 'Anonymous',
      content: multipartData.fields.content,
      imageUrl: savedImageUrl,
      likes: 0,
      comments: [],
      createdAt: new Date().toISOString(),
    };

    mockPosts.push(newPost);

    return {
      statusCode: 201,
      contentType: 'application/json',
      body: JSON.stringify({
        success: true,
        message: '게시글이 성공적으로 작성되었습니다.',
        data: newPost,
        timestamp: new Date().toISOString(),
      }),
    };
  } catch (error) {
    console.error('Post creation error:', error);
    // ... 에러 처리 ...
  }
}

---

Part 3: Worker Pool 패턴으로 성능 최적화

매번 Worker를 생성하면 오버헤드가 발생합니다. Worker Pool을 구현해 재사용하면 훨씬 효율적입니다.

// backend/src/workers/worker-pool.ts
import { Worker } from 'worker_threads';
import path from 'path';

export class WorkerPool {
  private workers: Worker[] = [];
  private availableWorkers: Worker[] = [];
  private taskQueue: Array<{
    data: any;
    resolve: (value: any) => void;
    reject: (error: any) => void;
  }> = [];

  constructor(private workerScript: string, private poolSize: number) {
    this.initialize();
  }

  private initialize() {
    for (let i = 0; i < this.poolSize; i++) {
      const worker = new Worker(this.workerScript);
      this.workers.push(worker);
      this.availableWorkers.push(worker);

      worker.on('message', (result) => {
        this.availableWorkers.push(worker);
        this.processQueue();
      });

      worker.on('error', (error) => {
        console.error('Worker error:', error);
        this.availableWorkers.push(worker);
        this.processQueue();
      });
    }
  }

  public execute(data: any): Promise<any> {
    return new Promise((resolve, reject) => {
      this.taskQueue.push({ data, resolve, reject });
      this.processQueue();
    });
  }

  private processQueue() {
    if (this.taskQueue.length === 0 || this.availableWorkers.length === 0) {
      return;
    }

    const task = this.taskQueue.shift()!;
    const worker = this.availableWorkers.shift()!;

    worker.once('message', task.resolve);
    worker.once('error', task.reject);
    worker.postMessage(task.data);
  }

  public terminate() {
    this.workers.forEach(worker => worker.terminate());
  }
}

사용 예시

// backend/src/services/imageService.ts
import { WorkerPool } from '../workers/worker-pool.js';
import path from 'path';

const imagePool = new WorkerPool(
  path.join(__dirname, '../workers/image-worker.js'),
  4 // 4개의 워커를 풀에 유지
);

export async function resizeImage(imagePath: string) {
  return imagePool.execute({
    imagePath,
    targetWidth: 800,
    targetHeight: 600
  });
}

구현 검증 체크리스트

본 프로젝트의 멀티 프로세스/스레드 구현이 프로덕션 레벨의 요구사항을 충족하는지 검증하기 위한 체크리스트입니다.

✅ Cluster 모드 (멀티 프로세스)

1. USE_CLUSTER 플래그로 멀티코어 확장 제어 가능한가?

✅ 구현 완료 - webserver/server.js:30-36

const USE_CLUSTER = process.env.USE_CLUSTER === 'true' || process.argv.includes('--cluster');
const NUM_WORKERS = process.env.NUM_WORKERS ? parseInt(process.env.NUM_WORKERS) : os.cpus().length;

console.log(`🔧 Cluster 모드: ${USE_CLUSTER ? '활성화' : '비활성화'}`);

검증 방법:

# Cluster 비활성화 (단일 프로세스)
npm start

# Cluster 활성화 (멀티 프로세스)
USE_CLUSTER=true npm start

---

2. 워커 수를 OS CPU 코어 수를 사용하여 자동으로 책정할 수 있는가?

✅ 구현 완료 - os.cpus().length 사용

const NUM_WORKERS = process.env.NUM_WORKERS
  ? parseInt(process.env.NUM_WORKERS)  // 명시적 지정
  : os.cpus().length;                   // 자동 감지

검증 방법:

# CPU 코어 수만큼 자동 생성
USE_CLUSTER=true npm start

# 워커 수 명시적 지정
NUM_WORKERS=4 USE_CLUSTER=true npm start

실행 예시:

🚀 Cluster 모드 시작: 8개 워커 프로세스 생성
📊 CPU 코어 수: 8
🔧 워커 프로세스 생성됨: PID 12345
🔧 워커 프로세스 생성됨: PID 12346
...

---

3. 워커가 죽었을 때 Auto Restart 가능한가?

✅ 구현 완료 - webserver/server.js:491-501

cluster.on('exit', (worker, code, signal) => {
  console.log(
    `💀 워커 프로세스 종료: PID ${worker.process.pid} (코드: ${code}, 시그널: ${signal})`
  );

  // 예기치 않은 종료인 경우에만 재시작
  if (!worker.exitedAfterDisconnect) {
    console.log('워커 프로세스 재시작 중...');
    const newWorker = cluster.fork();
    console.log(`🔧 새 워커 프로세스 생성됨: PID ${newWorker.process.pid}`);
  }
});

검증 방법:

# 1. Cluster 모드로 서버 실행
USE_CLUSTER=true npm start

# 2. 워커 프로세스 강제 종료
kill -9 <워커_PID>

# 3. 로그 확인 - 자동으로 새 워커가 생성되어야 함

핵심 포인트:

• worker.exitedAfterDisconnect: 정상 종료(graceful shutdown)와 예외 종료 구분
• 예외 종료 시에만 자동 재시작 → 무한 재시작 루프 방지

---

4. Graceful Shutdown 가능한 구조인가?

✅ 구현 완료 - webserver/server.js:504-516

process.on('SIGINT', () => {
  console.log('\n🛑 마스터 프로세스 종료 신호 수신');
  console.log('모든 워커 프로세스에 종료 신호 전송...');

  for (const id in cluster.workers) {
    cluster.workers[id].kill();
  }

  setTimeout(() => {
    console.log('마스터 프로세스 종료');
    process.exit(0);
  }, 2000); // 2초 타임아웃
});

검증 방법:

# 서버 실행 중 Ctrl+C 또는 SIGINT 전송
USE_CLUSTER=true npm start
# Ctrl+C 입력

# 또는
kill -SIGINT <마스터_PID>

 

Graceful Shutdown 프로세스:

1. 마스터가 SIGINT 시그널 수신
2. 모든 워커에게 종료 신호 전송
3. 워커들이 진행 중인 요청 완료 대기
4. 2초 타임아웃 후 마스터 프로세스 종료

개선 제안:

// 더 정교한 Graceful Shutdown
process.on('SIGINT', async () => {
  console.log('\n🛑 마스터 프로세스 종료 신호 수신');

  // 새로운 연결 차단
  server.close(() => {
    console.log('새로운 연결 차단 완료');
  });

  // 워커에게 graceful shutdown 시그널 전송
  for (const id in cluster.workers) {
    cluster.workers[id].send({ cmd: 'shutdown' });
    cluster.workers[id].disconnect(); // IPC 채널 종료
  }

  // 모든 워커 종료 대기 (최대 10초)
  const timeout = setTimeout(() => {
    console.log('⚠️ 타임아웃: 강제 종료합니다');
    process.exit(1);
  }, 10000);

  // 모든 워커 종료 완료 시
  cluster.on('disconnect', () => {
    if (Object.keys(cluster.workers).length === 0) {
      clearTimeout(timeout);
      console.log('✅ 모든 워커 정상 종료 완료');
      process.exit(0);
    }
  });
});

---

Worker Threads (멀티 스레드)

5. USE_WORKER_THREADS 플래그로 CPU 집약적 작업 분리 가능한가?

✅ 구현 완료 - webserver/server.js:22-28

// webserver/server.js
const USE_WORKER_THREADS =
  process.env.USE_WORKER_THREADS === 'true' ||
  process.argv.includes('--worker-threads');

console.log(`🧵 Worker Threads 모드: ${USE_WORKER_THREADS ? '활성화' : '비활성화'}`);

실제 적용 코드 - webserver/server.js:175-191:

if (USE_WORKER_THREADS) {
  // Worker Threads를 사용한 파일 처리
  const workerResult = await workerManager.processFile(
    filePath,
    requestedPath
  );
  contentType = workerResult.contentType;
  responseBody = workerResult.fileContent;
} else {
  // 기존 메인 스레드 파일 처리
  contentType = getMimeType(filePath);
  if (isTextMimeType(contentType)) {
    responseBody = await fs.readFile(filePath, 'utf8');
  } else {
    responseBody = await fs.readFile(filePath);
  }
}

검증 방법:

# Worker Threads 비활성화 (기본값)
npm start

# Worker Threads 활성화
USE_WORKER_THREADS=true npm start
# 또는
node server.js --worker-threads

# Cluster + Worker Threads 동시 활성화 (최고 성능)
USE_CLUSTER=true USE_WORKER_THREADS=true npm start

실행 예시:

🧵 Worker Threads 모드: 활성화
🧵 WorkerManager 초기화: 최대 워커 수 7
✅ Worker-0 생성 완료
✅ Worker-1 생성 완료
...

---

6. 워커 풀이 효율적으로 사용/관리되고 있는가? (큐잉, 밸런싱, Recovery)

✅ 구현 완료 - webserver/workers/workerManager.js

프로젝트에 완벽한 WorkerManager 클래스가 구현되어 있습니다!

주요 기능:

1. 큐잉 (Queueing) - FIFO 방식

• webserver/workers/workerManager.js:152-174

async executeTask(type, data) {
  return new Promise((resolve, reject) => {
    const taskId = ++this.taskIdCounter;
    const task = { taskId, type, data, resolve, reject, createdAt: Date.now() };

    // 사용 가능한 워커가 있으면 즉시 실행
    const availableWorker = this.getAvailableWorker();
    if (availableWorker) {
      this.assignTaskToWorker(task, availableWorker);
    } else {
      // 모든 워커가 바쁘면 큐에 추가
      this.taskQueue.push(task);
      console.log(`⏳ Task-${taskId} 큐에 대기 중 (큐 크기: ${this.taskQueue.length})`);
    }
  });
}

2. 밸런싱 (Balancing) - 최소 부하 워커 선택

• webserver/workers/workerManager.js:139-147

getAvailableWorker() {
  for (const [workerId, workerInfo] of this.workers) {
    if (!workerInfo.busy) {
      return { workerId, workerInfo };
    }
  }
  return null;
}

3. Recovery - 자동 워커 재생성

• webserver/workers/workerManager.js:88-106

restartWorker(workerId) {
  const workerInfo = this.workers.get(workerId);
  if (workerInfo) {
    try {
      workerInfo.worker.terminate();
    } catch (error) {
      console.error(`워커 종료 중 에러:`, error);
    }
    this.workers.delete(workerId);
  }

  // 새 워커 생성 (1초 후)
  setTimeout(() => {
    if (!this.isShuttingDown) {
      this.createWorker(workerId);
    }
  }, 1000);
}

에러 처리:

// 워커 에러 시 자동 재시작
worker.on('error', (error) => {
  console.error(`❌ Worker-${workerId} 에러:`, error);
  this.restartWorker(workerId);
});

// 비정상 종료 시 자동 재시작
worker.on('exit', (code) => {
  if (code !== 0) {
    console.error(`💀 Worker-${workerId} 비정상 종료 (코드: ${code})`);
    if (!this.isShuttingDown) {
      this.restartWorker(workerId);
    }
  }
});

검증 방법:

# Worker Threads 활성화하고 부하 테스트
USE_WORKER_THREADS=true npm start

# 다른 터미널에서 부하 생성
ab -n 1000 -c 50 http://localhost:8080/

실시간 통계 확인:

# Worker Pool 상태 API 호출
curl http://localhost:8080/api/worker-stats

# 출력 예시:
{
  "success": true,
  "data": {
    "totalWorkers": 7,
    "busyWorkers": 3,
    "queueSize": 5,
    "activeTasks": 3,
    "workers": [
      { "id": 0, "busy": true, "taskCount": 42, "uptime": 60000 },
      { "id": 1, "busy": false, "taskCount": 38, "uptime": 60000 },
      ...
    ]
  }
}

---

7. 워커의 생명주기가 정교하게 관리되고 있는가?

✅ 구현 완료 - 5단계 생명주기 완벽 관리

1. 워커 생성 (Initialization) ✅

• webserver/workers/workerManager.js:35-39
• CPU 코어 수에 맞춰 자동 초기화: Math.max(2, os.cpus().length - 1)
• 워커 데이터와 함께 생성: new Worker(script, { workerData: { workerId } })

initializeWorkers() {
  for (let i = 0; i < this.maxWorkers; i++) {
    this.createWorker(i);
  }
}

2. 워커 실행 (Execution) ✅

• webserver/workers/workerManager.js:178-196
• 메시지 기반 통신 (postMessage / on('message'))
• 작업 완료 후 자동으로 풀로 복귀

assignTaskToWorker(task, { workerId, workerInfo }) {
  workerInfo.busy = true;
  this.activeTasks.set(taskId, task);

  workerInfo.worker.postMessage({ taskId, type, data });
  console.log(`🚀 Task-${taskId} -> Worker-${workerId} 할당`);
}

handleWorkerMessage(workerId, message) {
  workerInfo.busy = false;  // 워커를 사용 가능 상태로 변경
  workerInfo.taskCount++;
  this.processNextTask();    // 다음 대기 작업 처리
}

3. 워커 에러 처리 (Error Handling) ✅

• webserver/workers/workerManager.js:55-59
• error 이벤트 리스닝 및 자동 재시작

worker.on('error', (error) => {
  console.error(`❌ Worker-${workerId} 에러:`, error);
  this.restartWorker(workerId);
});

4. 워커 종료 (Termination) ✅

• webserver/workers/workerManager.js:62-69
• 정상 종료(code=0) vs 비정상 종료 구분
• exit 이벤트로 감지 및 자동 재생성

worker.on('exit', (code) => {
  if (code !== 0) {
    console.error(`💀 Worker-${workerId} 비정상 종료 (코드: ${code})`);
    if (!this.isShuttingDown) {
      this.restartWorker(workerId);
    }
  }
});

5. 워커 풀 종료 (Pool Termination) ✅

• webserver/workers/workerManager.js:266-306
• Graceful Shutdown 완벽 구현
• 활성 작업 완료 대기 (최대 5초)
• 모든 워커 정리

async shutdown() {
  this.isShuttingDown = true;

  // 1. 대기 중인 작업 취소
  for (const task of this.taskQueue) {
    task.reject(new Error('Worker pool is shutting down'));
  }

  // 2. 활성 작업 완료 대기 (최대 5초)
  while (this.activeTasks.size > 0) {
    await new Promise(resolve => setTimeout(resolve, 100));
  }

  // 3. 모든 워커 종료
  await Promise.allSettled(
    Array.from(this.workers.values()).map(w => w.worker.terminate())
  );

  console.log('✅ WorkerManager 종료 완료');
}

생명주기 다이어그램:

[초기화] ──────────────────────┐
   ↓                          │
[대기 중] ←────────┐           │
   ↓               │           │
[작업 할당]         │           │
   ↓               │           │
[작업 실행]         │           │
   ↓               │           │
[결과 반환] ────────┘           │
   ↓ (에러 발생)                │
[워커 재생성] ──────────────────┘
   ↓ (shutdown)
[Graceful 종료]

시그널 핸들링:

// SIGINT/SIGTERM 시그널 처리
process.on('SIGINT', async () => {
  await workerManager.shutdown();
  process.exit(0);
});

process.on('SIGTERM', async () => {
  await workerManager.shutdown();
  process.exit(0);
});

성능 모니터링 대시보드

프로덕션 환경에서 Cluster와 Worker Threads의 성능을 실시간으로 모니터링하기 위한 API 구현:

// webserver/server.js - 서버 정보 API
if (url === '/api/server-info') {
  return createJsonResponse(200, {
    success: true,
    data: {
      mode: USE_CLUSTER ? 'cluster' : 'single',
      pid: process.pid,
      cpuCores: os.cpus().length,
      memoryUsage: process.memoryUsage(),
      uptime: process.uptime(),
      workers: USE_CLUSTER ? Object.keys(cluster.workers || {}).length : 1,
    },
    timestamp: new Date().toISOString(),
  });
}

// backend/src/routes/workerRoutes.ts - Worker Pool 통계 API
export function createWorkerStatsRoute(pool: WorkerPool): RouteHandler {
  return {
    async handle(request: HttpRequest): Promise<HttpResponse> {
      const stats = pool.getStats();

      return {
        statusCode: 200,
        contentType: 'application/json',
        body: JSON.stringify({
          success: true,
          data: stats,
          timestamp: new Date().toISOString(),
        }),
      };
    },
  };
}

모니터링 예시:

# 서버 정보 확인
curl http://localhost/api/server-info

# Worker Pool 통계 확인
curl http://localhost/api/worker-stats

---

멀티 프로세스 vs 멀티 스레드: 핵심 차이점

개념 비교

구분	Cluster (멀티 프로세스)	Worker Threads (멀티 스레드)
격리 수준	완전히 독립된 메모리 공간	같은 프로세스 내 메모리 공유
통신 방식	IPC (Inter-Process Communication)	메시지 패싱 (postMessage)
생성 비용	높음 (프로세스 전체 복제)	낮음 (스레드만 생성)
메모리 사용	각 프로세스마다 독립적 메모리	공유 메모리 영역 활용
장애 격리	한 프로세스 죽어도 다른 프로세스 영향 없음	한 스레드 에러가 프로세스 전체에 영향 가능
적합한 작업	I/O 바운드, HTTP 요청 처리	CPU 바운드, 계산 집약적 작업

실제 프로젝트 적용 예시

// webserver/server.js

// 1️⃣ Cluster: 여러 프로세스로 HTTP 요청 분산
if (USE_CLUSTER && cluster.isPrimary) {
  // 8코어 CPU라면 8개의 독립된 프로세스 생성
  for (let i = 0; i < os.cpus().length; i++) {
    cluster.fork(); // 각 프로세스는 독립된 메모리 공간 보유
  }
}

// 2️⃣ Worker Threads: 파일 처리를 별도 스레드로 분리
if (USE_WORKER_THREADS) {
  const workerResult = await workerManager.processFile(filePath);
  // 메인 스레드는 차단되지 않고 다른 요청 처리 가능
}

---

멀티 스레드를 도입하면 항상 성능이 더 좋아지는가?

❌ 그렇지 않습니다!

멀티 스레드는 특정 상황에서만 성능 향상을 가져옵니다. 오히려 잘못 사용하면 성능이 저하될 수 있습니다.

성능이 향상되는 경우 ✅

1. CPU 집약적 작업

// ✅ 좋은 예: 이미지 리사이징 (CPU 작업)
await workerManager.processImage({
  imagePath: '/uploads/large-image.jpg',
  resize: { width: 1920, height: 1080 },
  compress: true
});
// 메인 스레드는 차단되지 않고 다른 HTTP 요청 처리 가능

성능 비교:

단일 스레드: 이미지 처리 시간 500ms → 메인 스레드 차단 → 다른 요청 대기
멀티 스레드: 이미지 처리 500ms → 메인 스레드 계속 동작 → 다른 요청 즉시 처리

2. 대용량 데이터 변환

// ✅ 좋은 예: CSV 파일 파싱 (CPU 작업)
await workerManager.processData({
  inputData: largeCSVFile,
  operation: 'parse-and-transform'
});

3. 암호화/해싱 작업

// ✅ 좋은 예: 비밀번호 해싱 (CPU 작업)
await workerManager.executeTask('hash', {
  password: userPassword,
  algorithm: 'bcrypt',
  rounds: 10
});

---

성능이 저하되는 경우 ❌

1. I/O 바운드 작업

// ❌ 나쁜 예: 파일 읽기 (I/O 작업)
// Node.js는 이미 비동기 I/O로 최적화되어 있음
await workerManager.processFile('/path/to/file.txt');

// ✅ 더 나은 방법: 그냥 fs/promises 사용
await fs.readFile('/path/to/file.txt', 'utf8');

이유: Node.js의 비동기 I/O는 libuv의 스레드 풀을 이미 활용하고 있습니다. Worker Threads를 추가로 사용하면 오버헤드만 증가합니다.

2. 작은 작업들

// ❌ 나쁜 예: 간단한 JSON 파싱
await workerManager.executeTask('parse', {
  data: smallJsonString
});

// ✅ 더 나은 방법: 메인 스레드에서 직접 처리
const parsed = JSON.parse(smallJsonString);

성능 비교:

작업 시간: 1ms
워커 생성/통신 오버헤드: 5-10ms
→ 총 시간: 6-11ms (오히려 10배 느림!)

3. 빈번한 작은 메시지 전송

// ❌ 나쁜 예: 루프에서 매번 워커 호출
for (let i = 0; i < 10000; i++) {
  await workerManager.executeTask('increment', { value: i });
}
// 통신 오버헤드 10000배 발생!

// ✅ 더 나은 방법: 배치 처리
await workerManager.executeTask('batch-increment', {
  values: Array.from({ length: 10000 }, (_, i) => i)
});

---

언제 멀티 스레드를 사용해야 하는가?

결정 기준 체크리스트

✅ CPU 사용률이 100%에 가까운가?
✅ 작업 시간이 10ms 이상인가?
✅ 작업이 메인 이벤트 루프를 차단하는가?
✅ 동시 요청 처리가 중요한가?

위 질문에 모두 YES라면 → Worker Threads 고려
하나라도 NO라면 → 기존 비동기 I/O 사용

실전 판단 예시

작업	CPU 집약?	시간	멀티 스레드 필요?
이미지 리사이징	✅ YES	200-500ms	✅ 필요함
비디오 인코딩	✅ YES	5-30초	✅ 필요함
파일 읽기	❌ NO (I/O)	5-50ms	❌ 불필요
JSON 파싱 (작음)	⚠️ 약간	1ms	❌ 불필요
JSON 파싱 (대용량)	✅ YES	100ms+	✅ 필요함
DB 쿼리	❌ NO (I/O)	10-100ms	❌ 불필요
복잡한 정규식	✅ YES	50ms+	✅ 고려

---

성능 측정 실습

1. 벤치마크 코드

// benchmark.js
import { performance } from 'perf_hooks';

// 메인 스레드에서 실행
async function benchmarkMainThread() {
  const start = performance.now();

  // CPU 집약적 작업 시뮬레이션
  let result = 0;
  for (let i = 0; i < 10000000; i++) {
    result += Math.sqrt(i);
  }

  const end = performance.now();
  console.log(`메인 스레드: ${(end - start).toFixed(2)}ms`);
  return result;
}

// Worker Thread에서 실행
async function benchmarkWorkerThread() {
  const start = performance.now();

  const result = await workerManager.executeTask('heavy-compute', {
    iterations: 10000000
  });

  const end = performance.now();
  console.log(`워커 스레드: ${(end - start).toFixed(2)}ms`);
  return result;
}

// 동시 요청 시나리오
async function benchmarkConcurrent() {
  const start = performance.now();

  // 10개의 동시 요청
  await Promise.all([
    benchmarkMainThread(),
    benchmarkMainThread(),
    // ... 다른 요청들
  ]);

  const end = performance.now();
  console.log(`동시 처리 (메인): ${(end - start).toFixed(2)}ms`);
}

2. 예상 결과

# 단일 작업 비교
메인 스레드: 245ms
워커 스레드: 250ms (통신 오버헤드 +5ms)
→ 거의 동일

# 동시 작업 비교 (10개)
메인 스레드 순차: 2450ms (10 × 245ms)
워커 스레드 병렬: 300ms (워커 8개 사용)
→ 8배 빠름! 🚀

---

오버헤드 이해하기

Worker Thread 생성 비용

const { Worker } = require('worker_threads');

console.time('워커 생성');
const worker = new Worker('./worker.js');
console.timeEnd('워커 생성');
// 출력: 워커 생성: 5.2ms

console.time('워커 실행');
worker.postMessage({ task: 'simple' });
worker.on('message', () => {
  console.timeEnd('워커 실행');
  // 출력: 워커 실행: 2.1ms
});

오버헤드 요약:

• 워커 생성: ~5-10ms
• 메시지 전송: ~1-2ms
• 데이터 직렬화/역직렬화: 크기에 비례

결론: 작업 시간이 10ms 이하라면 오버헤드가 이득보다 클 수 있습니다.

---

최종 권장사항

프로젝트별 가이드

1. 소규모 API 서버 (월 1만 요청 미만)

권장: Cluster만 사용 (Worker Threads 불필요)
이유: 대부분의 작업이 I/O 바운드

2. 중규모 웹 서비스 (월 100만 요청)

권장: Cluster + 선택적 Worker Threads
이유: 이미지 처리 등 특정 CPU 작업만 분리

3. 대규모 데이터 처리 (실시간 분석)

권장: Cluster + Worker Pool
이유: CPU 집약적 작업이 지속적으로 발생

---

웹 성능 부하 테스트 도구 : Apache Bench

이 때, 성능 개선 후와 전의 성능 차이를 확인해보기 위해서 웹 성능 부하를 테스트 하기 위해 Apache Bench 를 활용했습니다.

Apache Bench (ab)

• 아파치 HTTP 서버와 함께 제공되는 간단한 벤치마크 도구
• 기본 기능: 동시 접속 수, 요청 수를 지정해서 서버에 부하 걸기
• 예:
  • -n 1000 → 총 1000번 요청
  • -c 100 → 동시에 100개 요청
• ab -n 1000 -c 100 http://localhost/

Part 4: 성능 비교 및 모니터링

부하 테스트 스크립트

# Apache Bench로 성능 측정
# 단일 프로세스
ab -n 10000 -c 100 http://localhost:3000/api/posts

# Cluster 모드 (4 workers)
ab -n 10000 -c 100 http://localhost:3000/api/posts

실제 성능 차이 (예시)

구성	Requests/sec	평균 응답시간
단일 프로세스	1,234 req/s	81ms
Cluster (4 workers)	4,567 req/s	22ms
+ Worker Pool	5,892 req/s	17ms

---

Best Practices

1. Cluster 설정

// 환경에 따라 워커 수 조절
const NUM_WORKERS = process.env.NODE_ENV === 'production'
  ? os.cpus().length
  : 2; // 개발 환경에서는 2개로 제한

2. Graceful Shutdown

// Master 프로세스
process.on('SIGTERM', () => {
  logger.info('SIGTERM received, shutting down gracefully...');

  Object.values(cluster.workers || {}).forEach((worker) => {
    worker?.kill('SIGTERM');
  });

  setTimeout(() => {
    process.exit(0);
  }, 10000); // 10초 타임아웃
});

3. Worker Thread 에러 핸들링

worker.on('error', (error) => {
  logger.error('Worker thread error:', error);
  // 에러 발생 시 재시도 로직
  retryTask(task);
});

테스트 수행 결과

(base) kimseoyeon@gimseoyeons-MacBook-Air-2 webserver % npm run test:performance

> codestargram-webserver@1.0.0 test:performance
> node test/performanceTest.js

🚀 웹서버 성능 테스트 시작
📡 대상 서버: http://127.0.0.1:80
============================================================

📊 기본 페이지 로드 성능 테스트
🚀 실행 중: ab -n 1000 -c 10 -s 60 -g gnuplot.dat -e results.csv http://127.0.0.1:80/
📝 테스트: HTML 페이지 로드 (index.html)

📊 JavaScript 파일 로드 성능 테스트
🚀 실행 중: ab -n 500 -c 10 -s 60 -g gnuplot.dat -e results.csv http://127.0.0.1:80/bundle.js
📝 테스트: JavaScript 파일 로드 (bundle.js)

📊 파비콘 로드 성능 테스트
🚀 실행 중: ab -n 500 -c 10 -s 60 -g gnuplot.dat -e results.csv http://127.0.0.1:80/favicon.ico
📝 테스트: 파비콘 로드 (favicon.ico)

📊 동시 연결 수 스트레스 테스트

🔥 동시 연결 수: 1
🚀 실행 중: ab -n 200 -c 1 -s 60 -g gnuplot.dat -e results.csv http://127.0.0.1:80/
📝 테스트: 동시 연결 1개

🔥 동시 연결 수: 5
🚀 실행 중: ab -n 200 -c 5 -s 60 -g gnuplot.dat -e results.csv http://127.0.0.1:80/
📝 테스트: 동시 연결 5개

🔥 동시 연결 수: 10
🚀 실행 중: ab -n 200 -c 10 -s 60 -g gnuplot.dat -e results.csv http://127.0.0.1:80/
📝 테스트: 동시 연결 10개

🔥 동시 연결 수: 20
🚀 실행 중: ab -n 200 -c 20 -s 60 -g gnuplot.dat -e results.csv http://127.0.0.1:80/
📝 테스트: 동시 연결 20개

🔥 동시 연결 수: 50
🚀 실행 중: ab -n 200 -c 50 -s 60 -g gnuplot.dat -e results.csv http://127.0.0.1:80/
📝 테스트: 동시 연결 50개

📊 Keep-Alive 성능 비교 테스트
🚀 실행 중: ab -n 500 -c 10 -s 60 -g gnuplot.dat -e results.csv http://127.0.0.1:80/
📝 테스트: Keep-Alive 비활성화
🚀 실행 중: ab -n 500 -c 10 -s 60 -g gnuplot.dat -e results.csv -k http://127.0.0.1:80/
📝 테스트: Keep-Alive 활성화

📊 지속 부하 테스트 (20초)
🚀 실행 중: ab -t 20 -c 10 -s 60 -g gnuplot.dat -e results.csv http://127.0.0.1:80/
📝 테스트: 20초간 지속 부하 테스트

============================================================
📊 성능 테스트 결과 요약
============================================================

🎯 HTML 페이지 로드 (index.html)
   ✅ 완료된 요청: 1000
   ❌ 실패한 요청: 0
   ⚡ 초당 요청 수: 7008.74 req/sec
   ⏱️  평균 응답 시간: 1.43 ms
   📈 전송 속도: 3114.24 KB/sec
   ⏰ 총 소요 시간: 0.143 초

🎯 JavaScript 파일 로드 (bundle.js)
   ✅ 완료된 요청: 500
   ❌ 실패한 요청: 0
   ⚡ 초당 요청 수: 4468.08 req/sec
   ⏱️  평균 응답 시간: 2.24 ms
   📈 전송 속도: 163857.07 KB/sec
   ⏰ 총 소요 시간: 0.112 초

🎯 파비콘 로드 (favicon.ico)
   ✅ 완료된 요청: 500
   ❌ 실패한 요청: 0
   ⚡ 초당 요청 수: 5574.26 req/sec
   ⏱️  평균 응답 시간: 1.79 ms
   📈 전송 속도: 947.19 KB/sec
   ⏰ 총 소요 시간: 0.09 초

🎯 동시 연결 1개
   ✅ 완료된 요청: 200
   ❌ 실패한 요청: 0
   ⚡ 초당 요청 수: 1048.29 req/sec
   ⏱️  평균 응답 시간: 0.95 ms
   📈 전송 속도: 465.79 KB/sec
   ⏰ 총 소요 시간: 0.191 초

🎯 동시 연결 5개
   ✅ 완료된 요청: 200
   ❌ 실패한 요청: 0
   ⚡ 초당 요청 수: 6928.81 req/sec
   ⏱️  평균 응답 시간: 0.72 ms
   📈 전송 속도: 3078.72 KB/sec
   ⏰ 총 소요 시간: 0.029 초

🎯 동시 연결 10개
   ✅ 완료된 요청: 200
   ❌ 실패한 요청: 0
   ⚡ 초당 요청 수: 8215.24 req/sec
   ⏱️  평균 응답 시간: 1.22 ms
   📈 전송 속도: 3650.33 KB/sec
   ⏰ 총 소요 시간: 0.024 초

🎯 동시 연결 20개
   ✅ 완료된 요청: 200
   ❌ 실패한 요청: 0
   ⚡ 초당 요청 수: 9794.80 req/sec
   ⏱️  평균 응답 시간: 2.04 ms
   📈 전송 속도: 4352.18 KB/sec
   ⏰ 총 소요 시간: 0.02 초

🎯 동시 연결 50개
   ✅ 완료된 요청: 200
   ❌ 실패한 요청: 0
   ⚡ 초당 요청 수: 8990.38 req/sec
   ⏱️  평균 응답 시간: 5.56 ms
   📈 전송 속도: 3994.75 KB/sec
   ⏰ 총 소요 시간: 0.022 초

🎯 Keep-Alive 비활성화
   ✅ 완료된 요청: 500
   ❌ 실패한 요청: 0
   ⚡ 초당 요청 수: 8943.58 req/sec
   ⏱️  평균 응답 시간: 1.12 ms
   📈 전송 속도: 3973.96 KB/sec
   ⏰ 총 소요 시간: 0.056 초

🎯 Keep-Alive 활성화
   ✅ 완료된 요청: 500
   ❌ 실패한 요청: 0
   ⚡ 초당 요청 수: 7413.89 req/sec
   ⏱️  평균 응답 시간: 1.35 ms
   📈 전송 속도: 3294.26 KB/sec
   ⏰ 총 소요 시간: 0.067 초

🎯 20초간 지속 부하 테스트
   ✅ 완료된 요청: 12342
   ❌ 실패한 요청: 0
   ⚡ 초당 요청 수: 559.31 req/sec
   ⏱️  평균 응답 시간: 17.88 ms
   📈 전송 속도: 248.52 KB/sec
   ⏰ 총 소요 시간: 22.067 초

🎉 성능 테스트 완료!

Cluster 모듈 기반 멀티 스레드 서버 구현

(base) kimseoyeon@gimseoyeons-MacBook-Air-2 webserver % node test/clusterTest.js
🚀 클러스터 모드 성능 비교 테스트 시작
📡 대상 서버: ClusterPerformanceTester
============================================================

📊 단일 vs 멀티 프로세스 성능 비교 테스트

🔹 단일 프로세스 모드 테스트
🚀 실행 중: ab -n 2000 -c 50 -s 60 -g gnuplot.dat -e results.csv http://127.0.0.1:80/
📝 테스트: 단일 프로세스 모드

⏳ 클러스터 모드 전환을 위해 서버 재시작 필요
💡 다음 명령어로 클러스터 모드 서버를 시작하세요:
   USE_CLUSTER=true node webserver/server.js
   또는
   node webserver/server.js --cluster

⏸️  클러스터 모드 서버 시작 후 아무 키나 누르세요...

🔹 클러스터 모드 테스트
🚀 실행 중: ab -n 2000 -c 50 -s 60 -g gnuplot.dat -e results.csv http://127.0.0.1:80/
📝 테스트: 클러스터 모드

============================================================
📈 클러스터 성능 비교 분석
============================================================

🔹 단일 프로세스:
   ⚡ RPS: 6191.91 req/sec
   ⏱️  응답시간: 8.07 ms
   📈 전송속도: 2751.29 KB/sec

🔹 클러스터 모드:
   ⚡ RPS: 5421.27 req/sec
   ⏱️  응답시간: 9.22 ms
   📈 전송속도: 2408.87 KB/sec

📊 성능 개선도:
   ⚡ RPS 향상: -12.45%
   ⏱️  응답시간 개선: -14.22%
   📈 전송속도 향상: -12.45%

⚠️  클러스터 모드에서 예상보다 성능 향상이 적습니다.
    높은 동시성 부하에서 더 큰 차이를 보일 수 있습니다.

============================================================
📊 성능 테스트 결과 요약
============================================================

🎯 단일 프로세스 모드
   ✅ 완료된 요청: 2000
   ❌ 실패한 요청: 0
   ⚡ 초당 요청 수: 6191.91 req/sec
   ⏱️  평균 응답 시간: 8.07 ms
   📈 전송 속도: 2751.29 KB/sec

🎯 클러스터 모드
   ✅ 완료된 요청: 2000
   ❌ 실패한 요청: 0
   ⚡ 초당 요청 수: 5421.27 req/sec
   ⏱️  평균 응답 시간: 9.22 ms
   📈 전송 속도: 2408.87 KB/sec

🎉 성능 테스트 완료!

💾 클러스터 비교 결과 저장됨: cluster-performance-test-2025-09-17T13-26-31-597Z.json
(base) kimseoyeon@gimseoyeons-MacBook-Air-2 webserver %

마무리

Node.js의 Cluster와 Worker Threads는 각각 다른 목적으로 사용됩니다.

• Cluster: 여러 프로세스로 요청을 분산 (수평 확장)
• Worker Threads: 무거운 작업을 별도 스레드로 분리 (블로킹 방지)

이 둘을 조합하면 멀티코어를 최대한 활용하면서도 메인 이벤트 루프를 막지 않는 진정한 고성능 서버를 만들 수 있습니다.

실제 프로덕션 환경에서는 PM2나 Kubernetes 같은 오케스트레이션 도구와 함께 사용하면 더욱 강력한 시스템을 구축할 수 있습니다.

---

더 읽어보기

• Node.js Cluster 공식 문서
• Worker Threads 공식 문서
• PM2 클러스터 모드 가이드