DEV Community: Archist

복붙으로 만든 벤더 파이프라인 4벌, 무엇이 추상화할 가치가 있었나

Archist — Mon, 27 Jul 2026 09:52:15 +0000

우리 백엔드는 외부 벤더 시스템 4개에서 데이터를 받아 멀티테넌트 DB로 동기화한다. 하나는 SSH 터널 너머 DB를 직접 읽는 레거시 온프레미스 시스템이고, 나머지 셋은 HTTP API인데 각자 성격이 다르다. 하나는 터널 뒤에서 EUC-KR로 응답하고, 하나는 토큰 로그인을 쓰고, 하나는 정적 토큰을 쓰는 원내 어댑터다.

각 연동은 NestJS 모노레포 안에서 독립 모듈로 산다. 그리고 새 연동은 전부 직전 연동 모듈을 복사해서 시작됐다. 두 번째 벤더까지는 이게 합리적인 출하 방식이다. 네 번째 벤더쯤 되니, 체감은 되는데 측정은 안 해본 문제가 하나 생겨 있었다.

그래서 손대기 전에 먼저 측정했다.

감사(audit)부터

네 모듈의 파일을 전부 훑으면서 하나씩 분류했다. 이 파일은 벤더 지식인가(그쪽 API 형태, 인증, 이상한 상태 코드), 아니면 어느 벤더든 똑같이 생겼을 오케스트레이션인가.

모듈	프로덕션 LOC	boilerplate 추정
벤더 A (레거시 DB)	~10,400	20~30%
벤더 B (HTTP + 터널)	~4,300	~50%
벤더 C (REST + 토큰)	~3,000	60~70%
벤더 D (원내 어댑터)	~4,300	~45%

흥미로운 건 총량이 아니라 중복이 어디에 사는가였다. 나는 HTTP 클라이언트와 transformer가 문제일 거라 예상했다. 틀렸다. transformer는 anti-corruption 경계라서 벤더마다 진짜로 다른 스키마를 매핑한다. 그 코드는 제 몫을 하는 코드다. 진짜 중복은 그 주변에 있었다.

벤더 쪽에서 사라진 레코드를 감지해 soft-delete하는 "reconcile" 컴포넌트가 두 모듈에 거의 글자 단위로 복사돼 있었다. 두 번째 사본의 주석에는 대놓고 "다른 벤더와 같은 패턴"이라고 적혀 있었다.
스케줄러 서비스 두 개가 주석까지 동일했다. 다른 건 벤더 enum과 로그 문자열뿐.
계정 연동에 쓰는 직원 조회 서비스가 세 벌, 각각 50줄 안팎, 구조는 사실상 100% 동일.
getToday, addDays, formatDate, chunk 같은 잔챙이 헬퍼가 14개 파일에 private 메서드로 복붙돼 있었다.

한 가지가 눈에 들어왔다. 우리는 벤더를 빠뜨리는 실수에 대해서는 이미 컴파일 타임 방어가 있었다. 라우팅 지점이 전부 Record<VendorType, Port> 맵이라 enum에 값을 추가하고 어댑터 등록을 빼먹으면 빌드가 깨진다. 벤더별 계약 불변식을 강제하는 테스트 게이트도 있다. 이 장치들은 잘 작동한다. 다만 이들이 강제하는 건 존재이지 유일성이 아니다. 파일 20개를 복붙해서 계약을 충족하는 것은 아무도 막지 않는다.

함정 1: "동일한" 헬퍼가 동일하지 않았다

당연한 첫수는 날짜 헬퍼를 공용 util로 올리는 것이다. 쉬워 보인다.

거의 쉬웠다. 14개 사본을 나란히 놓고 읽어보니 getToday에 두 가지 변형이 있었다. 대부분은 "지금 시각을 비즈니스 타임존으로 시프트한 값"을 반환했는데, 두 사본은 거기에 setHours(0,0,0,0)으로 자정 절삭까지 하고 있었다. 이름도 같고 주석도 같은데 값이 다르다.

이걸 함수 하나로 합쳤다면 어떤 스케줄 윈도우는 조용히 어긋나고, 어떤 타임스탬프 비교는 조용히 바뀌었을 것이다. 그래서 공용 util은 차이를 실토하는 이름으로 둘 다 export한다.

export function getKstNow(): Date { /* 타임존 시프트된 now */ }
export function getKstTodayStart(): Date { /* 시프트 + 자정 절삭 */ }

formatDate도 같은 이야기다. 세 모듈은 YYYYMMDD를, 한 모듈은 YYYY-MM-DD를 만들고 있었다. 함수 두 개로 두었다. 변형 두 개를 하나로 "정리"하는 순간 그것은 더 이상 리팩토링이 아니다. 리팩토링의 탈을 쓴 동작 변경이다.

같은 커밋에서 나온 작은 함정 하나 더. 언젠가 10분을 아껴줄지도 모르니 적어둔다. this.chunk(...)를 import 함수로 바꾸다가 for (const chunk of chunk(codes, SIZE)) 형태의 호출부가 깨졌다. 루프 변수가 자기 초기화식 안에서 import를 가리는 temporal dead zone 에러다. 루프 변수 이름을 바꾸고 넘어갔다.

함정 2: "동일한 스케줄러 3개" 중 하나는 아니었다

감사 노트에는 HTTP 벤더 스케줄러 3개가 전부 복붙이라고 적혀 있었다. 둘은 정말 그랬다. 같은 크론 패턴, 같은 테넌트 루프, 같은 실행 추적 전이, 주석까지. 그런데 세 번째는 멀리서 보면 비슷한데 구조가 달랐다. 동기화를 인라인으로 실행하는 게 아니라 cascade 잡을 enqueue하고 나머지는 큐 워커에게 맡긴다.

일치하는 둘만 추상 베이스로 뽑았다.

export abstract class SyncSchedulerBase {
  // 소유: 테넌트 루프, 실행 추적, master -> records 실행, 에러 삼킴
  protected async runScheduled(trigger: string): Promise<void> { /* ... */ }
}

@Injectable()
export class VendorBScheduler extends SyncSchedulerBase {
  // 소유: 크론 선언 (분산 락 이름이 벤더별로 유니크해야 함)
  @DistributedCron("0 6 * * *", { name: "vendor-b-morning" })
  async morning() { await this.runScheduled("morning"); }
}

크론 데코레이터는 일부러 서브클래스에 남겼다. 우리 분산 크론 래퍼는 name을 Redis 락 키로 쓰기 때문에 벤더별로 유니크해야 하고, 데코레이터 메타데이터는 어차피 상속이 깔끔하지 않다.

세 번째 스케줄러는? 그대로 두었다. 베이스에는 왜 제외했는지 주석으로 남겼다. 억지로 베이스에 넣으려면 "인라인 vs enqueue"를 가르는 훅이 필요해지는데, 그 순간부터 추상화 비용이 중복 비용을 넘어선다. 사전에 만든 감사 문서에 "하지 말 것" 목록이 있었는데, 이 목록이 정말 필요해지는 시점이 바로 리팩토링 도중이다. 완결주의 충동은 꼭 그때 온다.

재시도 코어: 베이스 클래스가 아니라 함수

두 HTTP 클라이언트의 재시도 뼈대는 같았다. 3회 시도, [1000, 2000, 4000] backoff, private sleep. 상수도 루프도 동일하다. 하지만 루프를 둘러싼 에러 처리는 진짜로 달랐다.

벤더 B는 터널 레벨 연결 실패에 즉시 fail-fast한다. 죽은 터널에 재시도해봐야 호출당 9초를 태우고 상위 RPC 예산만 날리기 때문에, 즉시 경보를 보내고 도메인 에러를 던진다.
벤더 C는 404를 "데이터 없음"(벤더 관례상 정상적인 빈 결과)으로 변환하고, 401에는 토큰 캐시를 폐기하며, 네트워크 에러·401·5xx만 재시도한다.

여기서 유혹은 AbstractHttpClient다. 안 했다. 한쪽은 array buffer에서 EUC-KR을 디코드하고 다른 쪽은 토큰 로그인을 관리한다. 공용 베이스를 만들면 template method 훅만 가득하고 실제로 공유되는 알맹이는 없다. 대신 공용층에는 함수 하나만 두었다.

export async function retryWithBackoff<T>(
  fn: () => Promise<T>,
  options?: {
    maxAttempts?: number;
    delaysMs?: readonly number[];
    // false 반환: 원본 에러로 즉시 실패.
    // throw: *당신의* 에러로 즉시 실패 (터널 fail-fast 용).
    isRetryable?: (error: unknown, attempt: number) => boolean | Promise<boolean>;
    onRetry?: (error: unknown, attempt: number, delayMs: number) => void | Promise<void>;
  },
): Promise<T>

두 클라이언트를 모두 수용하게 해준 계약은 isRetryable이 throw할 수 있다는 것이었다. 벤더 B의 터널 체크는 훅 안에서 경보를 보내고 도메인 에러를 던진다. 그리고 코어는 최종 실패를 로깅하지도, 에러를 래핑하지도 않는다. 원본 에러를 그대로 다시 던지고, 각 호출자가 기존의 "최종 실패" 로그 라인과 에러 메시지 형식을 유지하게 했다. 덕분에 diff가 읽기 좋았다. 루프는 이동했지만 동작은 안 변했다.

결과

커밋 다섯 개로: 공용 util 층(날짜, 본문 정제, chunk, retry), reconcile 컴포넌트 두 벌 → 한 벌, 스케줄러 복사본 두 벌 → 베이스 하나, 직원 조회 세 벌 → 제네릭 베이스 하나, 손으로 만 재시도 루프 두 벌 → 코어 하나.

코드베이스 순 효과는 약 380줄 감소, 테스트 수는 오히려 증가다(공용 헬퍼마다 단위 테스트를 새로 붙였다). 호출자 변경은 0건. 클래스명, DI 토큰, public 메서드가 전부 제자리라서 리뷰도 조용히 지나갔다.

내가 진짜 신경 쓰는 숫자는 온보딩 비용이다. 전에는 HTTP 벤더 하나를 추가하려면 가장 비슷한 기존 모듈에서 파일 20개쯤을 복사해야 했다. 이제 그 복붙 층은 대부분 사라졌고, 남은 작성 대상은 진짜 벤더 고유물이다. transformer, HTTP 클라이언트의 transport 특이점, 그리고 배선.

배운 것

컴파일 타임 레지스트리와 계약 테스트 게이트는 훌륭하지만, 이들이 막는 건 누락이지 중복이 아니다. 두 번째 문제에는 다른 도구가 필요하고, 그 도구는 감사와 의도적인 추출이다.
추상화 전에 측정하라. "동일한 스케줄러 3개" 중 둘만 동일했다. 셋째는 우연히 비슷하게 들리는 다른 설계였다.
헬퍼에 변형이 있으면 변형을 유지하고 이름으로 실토하라. 합치는 것은 정리가 아니라 동작 변경이다.
추상화 경계는 지식 경계에 두어라. 벤더 지식(인증, 인코딩, 상태 코드 관례)은 훅과 서브클래스로, 오케스트레이션(루프, 실행 추적, backoff)은 공용층으로.
HTTP 재시도에는 훅 두 개짜리 얇은 함수가 베이스 클래스를 이겼다. transport가 이만큼 다르면 상속이 공유하는 것은 로직이 아니라 격식이다.

EC2 Dev 서버 운영기: PM2에서 시작해서 ECS Production까지

Archist — Sat, 14 Mar 2026 07:19:04 +0000

EC2 Dev 서버 운영기 — PM2에서 시작해서 ECS Production까지

배경

Node.js 마이크로서비스 4개를 운영하고 있다. API Gateway 1개와 백엔드 서비스 3개. Production은 AWS ECS Fargate로 돌리고, Dev 서버는 EC2 한 대에 PM2로 올려놓고 쓰고 있다.

어느 날 Dev 서버 SSH 접속이 느려졌다. 들어가보니 PM2 로그가 수 GB, Docker dangling 이미지가 디스크를 채우고 있었다. 그때부터 정리한 운영 스크립트와, EC2와 ECS를 동시에 운영하면서 느낀 점을 정리한다.

Dev 서버 (EC2) 구조

EC2 (Ubuntu, t3.medium)
├── PM2 (Fork mode)
│   ├── gateway          512MB
│   ├── service-1        512MB
│   ├── service-2        512MB
│   ├── service-3-a      1GB
│   ├── service-3-b      1GB
│   ├── admin-dashboard  256MB
│   └── nginx            (sticky session)
│
├── Docker
│   ├── PostgreSQL 15    (port 5432)
│   └── Redis 7.4        (port 6379)
│
└── Nginx (ip_hash로 SSE sticky session)

PM2를 fork 모드로 쓰는 이유가 있다. SSE(Server-Sent Events) 연결이 cluster 모드에서 끊기기 때문이다. service-3은 2개 인스턴스로 띄우고, Nginx ip_hash로 sticky session을 건다.

Production (ECS Fargate) 구조

ALB (단일, 멀티 포트)
├── :443  → Gateway (Blue/Green, 2~10 tasks)
├── :444  → Service-3 (Blue/Green, Sticky, 1~6 tasks)
├── :446  → Service-2 (Blue/Green, Sticky, 1~6 tasks)
├── :448  → Service-1 (Rolling, Sticky, 1~6 tasks)
└── :3333 → Admin Dashboard (Rolling, 1 task)

Service Discovery (Cloud Map)
├── gateway.internal:4001
├── service-1.internal:4001
├── service-2.internal:4002
└── service-3.internal:4003

각 서비스가 독립적인 Fargate Task로 돌아간다. TCP 마이크로서비스 간 통신은 AWS Cloud Map으로 서비스 디스커버리를 하고, ALB에서 SSE가 필요한 서비스에는 sticky session 쿠키를 붙인다.

배포 전략도 서비스마다 다르다

서비스	배포 방식	이유
Gateway	CodeDeploy Blue/Green	진입점이라 무중단 필수
Service-3	CodeDeploy Blue/Green	SSE 연결 graceful draining 120초
Service-1	ECS Rolling	상태 없음, 빠른 배포 우선
Service-2	ECS Rolling	상태 없음
Admin Dashboard	ECS Rolling	내부 도구, 중단 허용

두 환경의 현실적인 차이

EC2가 Dev에서 좋은 이유

# 코드 수정 → 반영: 30초
git pull && pnpm build && pm2 restart all

# 디버깅: SSH 한 방
ssh dev-server
pm2 logs service-1 --lines 100
docker exec -it postgres psql

ECS에서 같은 걸 하려면:

# 코드 수정 → 반영: 3~5분
# Docker 빌드 → ECR 푸시 → Task 재배포

# 디버깅: 의식의 흐름이 필요
aws ecs execute-command \
  --cluster my-cluster \
  --task arn:aws:ecs:... \
  --container my-service \
  --interactive --command "/bin/sh"
# + Session Manager Plugin, IAM 권한, ECS Exec 활성화 필요

.env 하나 바꾸는 것도 EC2는 vim으로 수정 후 재시작이면 끝이지만, ECS는 Secrets Manager 수정 → 태스크 재배포다.

단, ALB가 붙으면 EC2 장점이 사라진다

EC2의 가장 큰 장점은 Stop하면 과금이 멈추는 것이다. 그런데 ALB가 붙어있으면:

ALB 고정비: ~$16/월
NAT Gateway: ~$32/월 + 트래픽
Stop해도 $48/월은 계속 나간다

이 정도면 ECS Fargate로 desired_count: 0으로 내려놓는 것과 비용 차이가 없다. ALB가 필요한 Dev 서버라면 차라리 ECS로 통일하는 게 인프라 관리 포인트가 줄어든다.

EC2 Dev 서버가 의미있으려면 ALB 없이 IP 직접 접근으로 써야 한다.

EC2 Dev 서버 운영 스크립트

ALB 없이 EC2를 Dev 서버로 쓰고 있다면, 이 자동화 정도는 깔아둬야 한다.

Cron 자동 정리

crontab -e

# [매시] Docker 미사용 리소스 + systemd 로그 정리
0 * * * * docker system prune -f && sudo journalctl --vacuum-size=500M && sudo find /var/log -name "*.gz" -delete && sudo find /tmp -atime +1 -delete 2>/dev/null

# [매일 03시] PM2 로그 비우기 — GB 단위로 쌓인다
0 3 * * * pm2 flush && find ~/.pm2/logs -name "*.log" -size +500M -exec truncate -s 0 {} \;

# [매일 04시] 72시간 지난 Docker 이미지 삭제
0 4 * * * docker image prune -a -f --filter "until=72h" && docker volume prune -f

# [매일 05시] 7일 넘은 로그 파일 삭제
0 5 * * * sudo find /var/log -name "*.log.*" -mtime +7 -delete 2>/dev/null

# [매주 일요일] apt 캐시 정리
0 4 * * 0 sudo apt clean && sudo apt autoremove -y -q

30초 진단

서버가 느릴 때 이것부터:

uptime && free -h && df -h /

세 가지를 동시에 본다:

load average — 코어 수 이상이면 CPU 과부하
available — 전체 메모리의 10% 이하면 위험
Use% — 디스크 90% 이상이면 긴급

더 파고 싶으면:

# CPU/메모리 Top 5
ps aux --sort=-%cpu | head -5
ps aux --sort=-%mem | head -5

# CPU steal — 높으면 t3 같은 버스터블 인스턴스 한계
top -bn1 | grep "%Cpu" | awk '{print "steal:", $16"%"}'

# OOM Killer 발생 여부
sudo dmesg | grep -i "oom\|killed" | tail -5

Docker 인프라 모니터링

# 컨테이너 리소스
docker stats --no-stream

# PostgreSQL idle 연결 정리 (10분 이상)
docker exec $(docker ps -qf "name=postgres") psql -U postgres -c "
SELECT pg_terminate_backend(pid)
FROM pg_stat_activity
WHERE state = 'idle'
AND query_start < now() - interval '10 minutes';"

# Redis BullMQ 잔여 데이터 정리
docker exec $(docker ps -qf "name=redis") \
  redis-cli --scan --pattern "bull:*:completed" | \
  xargs -I{} docker exec $(docker ps -qf "name=redis") redis-cli DEL {}

긴급 대응

# 디스크 100%: 범인 찾고 즉시 확보
sudo du -sh /var/log /tmp ~/.pm2/logs /var/lib/docker 2>/dev/null | sort -rh
pm2 flush && docker system prune -a -f --volumes && sudo journalctl --vacuum-size=100M

# 메모리 부족: 캐시 해제 + PM2 재시작
sync && echo 3 | sudo tee /proc/sys/vm/drop_caches > /dev/null
pm2 restart all

ECS Production에서는 이게 다 필요 없다

위 스크립트들이 EC2에서 필요한 이유는 서버가 stateful하기 때문이다. ECS Fargate는:

EC2에서 수동으로 하는 것	ECS에서 자동으로 되는 것
PM2 로그 정리 Cron	CloudWatch Logs (30일 retention 자동)
Docker prune Cron	컨테이너 재생성 시 자동 정리
PM2 헬스체크	ECS 헬스체크 + 자동 재시작
`ps aux` 수동 모니터링	CloudWatch 메트릭 + 알림
fail2ban SSH 방어	SSH 자체가 없음
Swap 설정	Fargate가 메모리 관리
디스크 용량 관리	Ephemeral 스토리지, 상태 없음

ECS에서 대신 필요한 것

# 서비스 상태 확인
aws ecs describe-services --cluster my-cluster \
  --services gateway --query 'services[0].{running:runningCount,desired:desiredCount,deployments:deployments[*].status}'

# 실시간 로그
aws logs tail /ecs/my-service --follow

# 스케일링
aws ecs update-service --cluster my-cluster --service gateway --desired-count 4

# 롤백
aws ecs update-service --cluster my-cluster --service gateway \
  --task-definition my-service:$(( $(aws ecs describe-services --cluster my-cluster --services gateway --query 'services[0].taskDefinition' --output text | grep -o '[0-9]*$') - 1 ))

개선 로드맵

현재 구조에서 아직 남은 과제들:

1. Dev 환경도 ECS로 통합

EC2 Dev 서버에 ALB가 붙어있다면, 비용 이점이 없다. Terraform 모듈을 환경별로 분리하면 된다:

terraform/environments/
├── prod/    # 현재 구성
├── staging/ # desired_count: 1, 작은 리소스
└── dev/     # desired_count: 1, FARGATE_SPOT 100%

2. Auto Scaling 정책 추가

현재 ECS에 min/max만 정의되어 있고 실제 스케일링 정책이 없다. Target Tracking 추가가 필요하다:

resource "aws_appautoscaling_target" "gateway" {
  max_capacity       = 10
  min_capacity       = 2
  resource_id        = "service/my-cluster/gateway"
  scalable_dimension = "ecs:service:DesiredCount"
  service_namespace  = "ecs"
}

resource "aws_appautoscaling_policy" "gateway_cpu" {
  name               = "gateway-cpu-scaling"
  policy_type        = "TargetTrackingScaling"
  resource_id        = aws_appautoscaling_target.gateway.resource_id
  scalable_dimension = aws_appautoscaling_target.gateway.scalable_dimension
  service_namespace  = aws_appautoscaling_target.gateway.service_namespace

  target_tracking_scaling_policy_configuration {
    predefined_metric_specification {
      predefined_metric_type = "ECSServiceAverageCPUUtilization"
    }
    target_value = 70.0
  }
}

3. FARGATE_SPOT 활용

상태 없는 서비스(Service-1, Service-2)는 FARGATE_SPOT으로 전환하면 최대 70% 비용 절감이 가능하다. 중단 시 ECS가 자동으로 다른 인스턴스를 띄운다.

4. Docker 로그 제한 (EC2 운영 시)

정리보다 애초에 안 쌓이게 하는 게 낫다:

// /etc/docker/daemon.json
{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "50m",
    "max-file": "3"
  }
}

AI 활용 포인트

이 글의 시작은 "서버가 느린데 어떡하지"였다. Claude Code에게 물어보니 진단 → cron 자동화 → 문서화까지 한 세션에서 끝났다.

특히 도움된 부분:

코드베이스의 ecosystem.config.js, docker-compose.yml, Terraform 설정을 자동으로 분석해서 프로젝트 스택에 맞는 스크립트 생성
cron 표현식, docker exec 파이프라인처럼 문법 실수하기 쉬운 명령어를 바로 사용 가능한 형태로 제공
EC2 vs ECS 비교를 현재 인프라 비용 기준으로 구체적으로 계산

소규모 B2B SaaS 팀을 위한 듀얼트랙 애자일 — 2주 사이클 실전 운영기

Archist — Tue, 10 Mar 2026 15:31:28 +0000

소규모 B2B SaaS 팀을 위한 듀얼트랙 애자일 — 2주 사이클 실전 운영기

스크럼? 칸반? 어느 쪽도 우리 상황에 딱 맞지 않아서 직접 프로세스를 설계했다. 소규모 팀에서 기획과 개발이 서로를 기다리지 않는 구조를 만든 경험을 공유한다.

왜 직접 만들었나

일반적인 스크럼은 "기획 → 개발 → 배포"가 한 스프린트 안에 순차적으로 일어난다. 문제는 개발팀이 기획을 기다리는 유휴 시간이 생긴다는 것이다. 소규모 팀에서 이 유휴 시간은 치명적이다.

듀얼트랙 애자일의 핵심은 단순하다: 다음 사이클의 기획(Discovery)과 현재 사이클의 개발(Delivery)을 동시에 돌린다. 개발팀이 이번 차수를 만드는 동안, 기획/디자인팀은 다음 차수를 준비한다.

2주 사이클 전체 그림

두 트랙이 2주 주기로 맞물려 돌아간다. Discovery가 끝나면 그 결과물이 다음 Delivery의 입력이 된다. 파이프라인처럼.

Phase 1. Discovery — 다음에 뭘 만들지

백로그 정제

고객 피드백, 내부 아이디어를 유저 스토리 단위로 정리한다. 이 단계에서 중요한 건 "무엇을"이지 "어떻게"가 아니다. 기술 부채도 별도 섹션으로 관리하면서 매 사이클 리소스를 강제 할당한다. 이걸 안 하면 기능 개발에 밀려서 영원히 처리 안 된다.

Blueprint & PRD

우선순위가 높은 항목은 아키텍처 영향도를 검토하는 Blueprint를 먼저 만든다. 이 기능이 기존 시스템에 어떻게 붙는지, 어떤 서비스에 변경이 필요한지를 미리 파악하는 것이다. 그 위에 기능 목적과 제약사항을 담은 PRD를 작성한다.

디자인 및 프로토타이핑

개발 착수 전에 시각적 결과물을 확정한다. "개발 중 스펙 변경"이 가장 큰 낭비라는 걸 몇 번 겪고 나서 이 단계를 반드시 거치게 만들었다.

경영진 컨펌

2주치 작업 계획이 비즈니스 방향과 맞는지 검증하는 게이트. 스타트업 규모라면 이 단계가 빠르게 돌아간다.

Phase 2. Delivery — 실제로 만들기

킥오프 + 회고

사이클 시작일에 두 가지를 동시에 한다:

이전 사이클 회고: Keep/Problem 공유 (길게 안 한다, 15분)
이번 사이클 킥오프: 확정된 스토리 브리핑, 세부 일정 확인

개발 → QA → 배포

확정된 스펙에 따라 개발하고, 배포 전 기능 명세 기반 QA를 거쳐 정기 배포한다. 2주마다 예측 가능한 릴리즈가 나간다는 게 핵심이다.

Hot-track — 현실은 계획대로 안 된다

정기 사이클만으로는 부족하다. 운영 중인 서비스에서 크리티컬 버그가 터지거나, 고객사에서 긴급 요청이 들어온다.

운영 원칙:

전체 리소스의 ~20%를 버퍼로 확보해둔다
정기 사이클 배포를 기다릴 수 없는 건만 Hot-track으로 처리
Hot-track 배포 건은 다음 킥오프에서 함께 리뷰
발생한 기술 부채는 즉시 백로그에 등록

20% 버퍼가 없으면 Hot-track이 정기 사이클을 잡아먹는다. 이건 협상 불가능한 원칙이다.

전체 워크플로우

티켓 관리 — 보드 상태 설계

프로세스가 있어도 티켓 상태가 이를 반영하지 않으면 무용지물이다. 듀얼트랙에 맞춰 보드 상태를 설계했다.

Phase	Status	진입 조건
Discovery	`BACKLOG`	티켓 생성
	`GROOMED`	Background/Overview 작성 완료
	`PRIORITIZED`	P0~P3 우선순위 라벨 부여
	`SPEC_READY`	PRD + 디자인 완료 (P0/P1 대상)
Commitment	`COMMITTED`	차수 계획 + 경영진 컨펌
Delivery	`IN_PROGRESS`	개발자 착수
	`IN_REVIEW`	PR 생성
	`QA`	리뷰 승인 완료
	`DONE`	QA 통과 + 배포

핵심은 SPEC_READY와 COMMITTED 사이의 게이트다. Discovery에서 스펙이 완성되지 않은 티켓은 Delivery에 넘어갈 수 없다. 이 경계가 "개발 중 스펙 변경"을 막아준다.

우선순위 기준

우선순위	의미	기획 요구사항
P0	다음 사이클 필수	PRD, 디자인 필수
P1	다음 사이클 선택	PRD, 디자인 가능한 만큼 (70% 이상 완료 지향)
P2	추후 재검토	기획 보류
P3	장기 백로그	기획 보류

P0/P1은 Commitment 단계에서 실제 포함 여부가 결정된다. P2/P3는 주기적으로 재검토해서 승격하거나 폐기한다.

핵심 관리 지표

모니터링하는 지표는 3개뿐이다:

계획 준수율: 이번 사이클에 계획한 스토리가 다 배포됐는가?
기술 부채 해결 비율: 안정화 작업에 리소스가 적절히 할당되고 있는가?
Hot-track 빈도: 긴급 배포가 정기 사이클의 예측 가능성을 해치고 있지 않은가?

지표가 많으면 아무도 안 본다. 3개만 추적하되 매 사이클 회고에서 반드시 리뷰한다.

운영하면서 느낀 점

잘 되는 것:

개발팀이 기획을 기다리는 유휴 시간이 거의 없다
2주마다 예측 가능한 배포가 나간다는 안정감
Hot-track 20% 버퍼 덕분에 긴급 대응에도 정기 사이클이 안 무너진다

아직 고민인 것:

Discovery와 Delivery 간 핸드오프 품질이 들쑥날쑥하다. PRD의 완성도 차이가 크다
기술 부채 리소스 "강제 할당"이 바쁜 시기에 지켜지기 어렵다
소규모 팀이라 한 명이 빠져도 사이클 전체가 흔들린다

완벽한 프로세스는 없다. 중요한 건 2주마다 회고하면서 프로세스 자체를 개선한다는 점이다. 프로세스도 제품처럼 반복 개선의 대상이다.

AI 활용 포인트

이 프로세스 문서 자체를 Claude Code로 구조화했다. "우리 팀이 실제로 하고 있는 일"을 설명하면 Mermaid 다이어그램과 테이블로 시각화해주고, 빠진 단계나 모호한 기준을 지적해줘서 프로세스를 더 명확하게 다듬을 수 있었다.

Terraform으로 AWS Managed Grafana 모니터링 체계 구축하기: MSA 6개 서비스를 한 눈에

Archist — Tue, 10 Mar 2026 15:26:28 +0000

문제: 서비스가 6개인데 모니터링이 없다

MSA로 전환한 뒤 가장 먼저 부딪힌 현실이 있다. "지금 어떤 서비스가 문제인지 모른다."

Gateway, AI 처리, 문서 생성, 데이터 파이프라인, 관리자 대시보드, 레거시 서비스 — 6개 ECS 서비스가 돌아가고, 각각이 Aurora PostgreSQL, Redis, ALB를 공유한다. 장애가 나면 AWS 콘솔에서 CloudWatch → ECS → RDS → ElastiCache를 돌아다니며 원인을 찾아야 했다. 서비스 하나 확인하는 데 5분, 전체 파악에 30분.

"대시보드 하나에서 전부 보고 싶다." 이 단순한 요구가 Grafana 도입의 시작이었다.

왜 AWS Managed Grafana인가

선택지	장점	단점
CloudWatch 대시보드만	추가 비용 없음	커스터마이징 한계, 대시보드 간 이동 불편
자체 호스팅 Grafana	완전한 커스터마이징	서버 관리, 업그레이드, 보안 패치
AWS Managed Grafana	관리 부담 없음 + SSO 연동	월 비용 발생
Datadog/New Relic	강력한 APM	비용이 서비스 수에 비례해서 증가

5명 팀에서 Grafana 서버를 직접 운영하는 건 과하다. AWS Managed Grafana는 SSO 인증, 데이터 소스 연결, 업그레이드를 AWS가 처리하므로 대시보드 설계에만 집중할 수 있다.

결정적으로, CloudWatch와 X-Ray를 네이티브로 지원한다. 별도 에이전트 없이 기존 AWS 메트릭을 그대로 시각화할 수 있다.

Terraform으로 전체 구성하기

모니터링 인프라도 코드로 관리한다. Grafana 워크스페이스 + IAM 역할 + 대시보드 JSON을 Terraform으로 프로비저닝한다.

워크스페이스 + IAM

# Grafana 워크스페이스
resource "aws_grafana_workspace" "main" {
  name                     = "${var.project}-${var.environment}"
  account_access_type      = "CURRENT_ACCOUNT"
  authentication_providers = ["AWS_SSO"]  # IAM Identity Center 연동
  permission_type          = "SERVICE_MANAGED"

  configuration = jsonencode({
    unifiedAlerting = { enabled = true }
    plugins         = { pluginAdminEnabled = false }  # 보안: 플러그인 설치 차단
  })

  data_sources = ["CLOUDWATCH", "XRAY"]
}

Grafana가 AWS 리소스의 메트릭을 읽으려면 IAM 역할이 필요하다. 최소 권한 원칙을 지키면서도 필요한 서비스를 모두 커버해야 한다:

resource "aws_iam_role" "grafana" {
  name = "${var.project}-grafana-role"

  assume_role_policy = jsonencode({
    Statement = [{
      Effect = "Allow"
      Principal = { Service = "grafana.amazonaws.com" }
      Action = "sts:AssumeRole"
      Condition = {
        StringEquals = {
          "aws:SourceAccount" = data.aws_caller_identity.current.account_id
        }
      }
    }]
  })
}

# 읽기 전용 정책 — 메트릭 조회만 허용
resource "aws_iam_role_policy" "grafana_permissions" {
  role = aws_iam_role.grafana.id

  policy = jsonencode({
    Statement = [
      {
        Effect = "Allow"
        Action = [
          # CloudWatch 메트릭
          "cloudwatch:DescribeAlarms",
          "cloudwatch:GetMetricData",
          "cloudwatch:GetMetricStatistics",
          "cloudwatch:ListMetrics",
          # CloudWatch Logs
          "logs:DescribeLogGroups",
          "logs:GetQueryResults",
          "logs:StartQuery",
          "logs:StopQuery",
          # ECS 서비스 상태
          "ecs:ListClusters",
          "ecs:DescribeServices",
          "ecs:ListTasks",
          # RDS + Redis
          "rds:DescribeDBClusters",
          "elasticache:DescribeCacheClusters",
          # ALB
          "elasticloadbalancing:DescribeTargetHealth",
          # X-Ray 트레이싱
          "xray:BatchGetTraces",
          "xray:GetServiceGraph",
          "xray:GetTimeSeriesServiceStatistics",
        ]
        Resource = "*"
      }
    ]
  })
}

SourceAccount 조건으로 다른 AWS 계정에서 이 역할을 사용하는 것을 방지한다. Grafana 서비스 프린시펄만 assume 가능하다.

대시보드 설계 — 7개 대시보드 체계

대시보드를 용도별로 나눴다. "하나의 대시보드에 전부 넣기" 유혹을 이기고, 관심사 분리를 적용했다:

📊 대시보드 체계
├── API Overview          # 전체 서비스 한 눈에 (첫 화면)
├── ALB Traffic           # 트래픽 패턴 + 에러율
├── ECS Metrics           # 서비스별 CPU/메모리 상세
├── Aurora DB             # 데이터베이스 성능
├── Redis Cache           # 캐시 히트율 + 메모리
├── EC2 Infrastructure    # 인스턴스 레벨 메트릭
└── ECS Logs Explorer     # 로그 검색 + 에러 추적

장애 시 동선: API Overview에서 이상 감지 → 해당 영역 대시보드로 드릴다운 → 5분 내 원인 파악.

API Overview — 운영의 첫 화면

가장 중요한 대시보드다. 한 화면에서 전체 시스템의 건강 상태를 파악한다.

// 서비스 상태 카드 — 떠있는지 죽었는지 즉시 확인
{
  "type": "stat",
  "title": "Gateway",
  "fieldConfig": {
    "defaults": {
      "thresholds": {
        "steps": [
          { "color": "red", "value": null },   // 0 = DOWN
          { "color": "green", "value": 1 }      // 1+ = UP
        ]
      }
    }
  },
  "targets": [{
    "namespace": "ECS/ContainerInsights",
    "metricName": "RunningTaskCount",
    "dimensions": {
      "ClusterName": "my-cluster",
      "ServiceName": "gateway"
    },
    "period": "60",
    "stat": "Average"
  }]
}

6개 서비스의 상태 카드가 한 줄에 나란히 표시된다. 빨간색이 보이면 즉시 대응할 수 있다.

그 아래로:

총 요청 수 (ALB RequestCount, 1분 합계)
응답 시간 (Average + p99, 0.5초 노란색 / 1초 빨간색 임계치)
서비스별 CPU/메모리 (8시간 트렌드, 70% 주의 / 90% 위험)
인프라 요약 (Aurora CPU, DB 커넥션 수, Redis 메모리, 5xx 에러)

ALB Traffic — 트래픽 패턴 읽기

// 5xx 에러 — 바 차트로 스파이크 즉시 감지
{
  "type": "barchart",
  "title": "5XX Errors",
  "fieldConfig": {
    "defaults": {
      "color": { "fixedColor": "red", "mode": "fixed" }
    }
  },
  "targets": [{
    "namespace": "AWS/ApplicationELB",
    "metricName": "HTTPCode_ELB_5XX_Count",
    "stat": "Sum",
    "period": "60"
  }]
}

트래픽 대시보드에서 가장 중요한 건 5xx 에러 바 차트다. 타임시리즈보다 바 차트가 스파이크를 잡아내기 좋다. 평소에 막대가 없다가 빨간 막대가 하나라도 나타나면 즉시 눈에 띈다.

서비스별 Healthy Host Count 카드도 배치했다. 배포 중에 한 서비스의 호스트가 0이 되면 즉시 알 수 있다.

Aurora DB — 데이터베이스 병목 추적

// Read/Write Latency 분리 — 어디서 느린지 파악
{
  "title": "Read / Write Latency",
  "targets": [
    {
      "metricName": "ReadLatency",
      "label": "Read",
      "stat": "Average",
      "period": "60"
    },
    {
      "metricName": "WriteLatency",
      "label": "Write",
      "stat": "Average",
      "period": "60"
    }
  ]
}

DB 대시보드의 핵심은 Read/Write Latency 분리와 커넥션 수 추적이다. 멀티테넌트 환경에서 테넌트가 추가될 때마다 커넥션이 늘어나는데, 80개 임계치에 접근하면 알람이 울린다.

Redis Cache — 캐시 효율 모니터링

// 캐시 히트율 계산 — Grafana 표현식 활용
{
  "title": "Cache Hit Rate",
  "targets": [
    { "id": "hits", "metricName": "CacheHits", "stat": "Sum" },
    { "id": "misses", "metricName": "CacheMisses", "stat": "Sum" }
  ],
  "expression": "IF(hits + misses > 0, hits / (hits + misses) * 100, 0)"
}

CloudWatch에는 "캐시 히트율" 메트릭이 없다. Hits와 Misses를 가져와서 Grafana Math Expression으로 직접 계산한다. 0 나누기 방지를 위한 IF 조건도 포함.

히트율이 90% 이하로 떨어지면 캐시 키 전략을 재검토해야 한다는 신호다.

ECS Logs Explorer — 에러 추적의 핵심

이 대시보드가 장애 대응에서 가장 많이 쓰인다. CloudWatch Logs Insights 쿼리를 Grafana 패널에 내장했다:

// 5분 단위 에러 카운트 — 스파이크 감지
fields @timestamp, @message
| filter @message like /(?i)(error|exception|fail)/
| stats count() as error_count by bin(5m)

// 최근 에러 로그 100건 — 원인 파악
fields @timestamp, @message, @logStream
| filter @message like /(?i)(error|exception|fail|critical)/
| sort @timestamp desc
| limit 100

서비스 선택 드롭다운과 키워드 검색 변수를 추가해서, 특정 서비스의 특정 에러를 바로 필터링할 수 있다:

{
  "templating": {
    "list": [
      {
        "name": "service",
        "type": "custom",
        "options": [
          { "text": "Gateway", "value": "/ecs/my-project-gateway" },
          { "text": "Service A", "value": "/ecs/my-project-service-a" },
          { "text": "Service B", "value": "/ecs/my-project-service-b" }
        ]
      },
      {
        "name": "search_keyword",
        "type": "textbox",
        "current": { "text": "", "value": "" }
      }
    ]
  }
}

CloudWatch 알람 + Slack 연동

Grafana 대시보드는 사후 분석에 강하다. 사전 감지는 CloudWatch Alarm이 담당한다. 15개 이상의 알람을 Terraform으로 관리한다:

# ECS 서비스별 CPU 알람 (동적 생성)
resource "aws_cloudwatch_metric_alarm" "ecs_cpu" {
  for_each = var.services  # 6개 서비스 자동 생성

  alarm_name          = "${each.key}-high-cpu"
  comparison_operator = "GreaterThanThreshold"
  evaluation_periods  = 2
  metric_name         = "CPUUtilization"
  namespace           = "AWS/ECS"
  period              = 300      # 5분
  statistic           = "Average"
  threshold           = 75       # 75% 초과 시
  treat_missing_data  = "notBreaching"

  dimensions = {
    ClusterName = var.cluster_name
    ServiceName = each.value.name
  }

  alarm_actions = [var.sns_topic_arn]  # Slack 알림
  ok_actions    = [var.sns_topic_arn]  # 복구 알림도 전송
}

# RDS 커넥션 수 알람
resource "aws_cloudwatch_metric_alarm" "rds_connections" {
  alarm_name = "rds-high-connections"
  threshold  = 80  # 멀티테넌트 환경에서 커넥션 폭증 감지
  # ...
}

# Redis 메모리 알람
resource "aws_cloudwatch_metric_alarm" "redis_memory" {
  alarm_name = "redis-high-memory"
  threshold  = 70  # 70% 초과 시 경고
  # ...
}

핵심 설계 결정:

for_each로 서비스 추가 시 알람 자동 생성. 수동으로 알람을 만들면 반드시 빠뜨린다.
ok_actions에도 SNS를 연결해서 복구 알림도 받는다. "장애 발생" 알림만 오고 "복구됨" 알림이 없으면 불안하다.
treat_missing_data = "notBreaching"으로 데이터 없음을 정상으로 취급. 배포 중 메트릭이 잠시 빈다고 알람이 울리면 피로도만 높아진다.

알람 → SNS → Lambda → Slack Webhook 흐름으로 Slack 채널에 실시간 알림이 온다.

로그 분리 라우팅 — 에러만 따로 모으기

6개 서비스의 전체 로그를 뒤지는 건 비효율적이다. 에러 로그만 별도 그룹으로 분기하는 로그 라우터를 구성했다:

# 서비스별 일반 로그 + 에러 전용 로그
resource "aws_cloudwatch_log_group" "service" {
  for_each          = var.services
  name              = "/ecs/${each.key}"
  retention_in_days = 30
}

resource "aws_cloudwatch_log_group" "error" {
  for_each          = var.services
  name              = "/${var.project}/${each.key}/error"
  retention_in_days = 30
}

# error/warn 레벨만 에러 그룹으로 분기
resource "aws_cloudwatch_log_subscription_filter" "error_filter" {
  for_each       = var.services
  name           = "${each.key}-error-filter"
  log_group_name = "/ecs/${each.key}"
  filter_pattern = "?ERROR ?WARN ?error ?warn"
  destination_arn = aws_lambda_function.log_router.arn
}

효과: Grafana Logs Explorer에서 에러 전용 로그 그룹을 선택하면 노이즈 없이 에러만 볼 수 있다. 장애 시 원인 파악 시간이 체감상 절반으로 줄었다.

아쉬웠던 점

대시보드 JSON 관리가 번거롭다. Grafana UI에서 대시보드를 수정한 뒤 JSON을 export해서 Terraform에 반영하는 과정이 수동이다. Grafana API + CI로 자동화하고 싶지만 아직 못 했다.
CloudWatch 메트릭의 1분 해상도 한계. 순간적인 스파이크는 1분 평균에 묻힌다. 커스텀 메트릭으로 초 단위 데이터를 보내면 비용이 급증한다.
서비스 간 호출 추적이 부족하다. X-Ray 데이터 소스를 연결해놨지만, NestJS TCP 통신에 X-Ray를 제대로 붙이려면 커스텀 미들웨어가 필요하다. 현재는 서비스별 메트릭만 볼 수 있고 호출 체인을 시각화하진 못한다.
알람 피로도. 초기에 임계치를 낮게 잡았더니 하루에 알람이 10개씩 왔다. 임계치를 올리니 진짜 장애를 놓칠까 불안하다. 적정선을 찾는 게 예상보다 어렵다.

향후 보완할 점

Grafana Dashboard as Code 자동화: 대시보드 변경을 Grafana API로 export → Terraform JSON 자동 동기화
OpenTelemetry 연동: AsyncLocalStorage 기반 분산 트레이싱을 OTEL로 전환, Grafana Tempo와 연결하여 서비스 간 호출 체인 시각화
비즈니스 메트릭 대시보드 추가: 인프라 메트릭 외에 "분당 처리 건수", "AI 추론 성공률" 같은 비즈니스 KPI 패널
알람 정책 고도화: 정적 임계치 → 이상 탐지(Anomaly Detection) 기반 동적 알람. CloudWatch Anomaly Detection을 활용하면 "평소 대비 비정상" 패턴을 자동 감지할 수 있다

배운 점

대시보드는 관심사별로 분리해야 한다. 하나에 다 넣으면 스크롤 지옥이 된다. Overview → 드릴다운 구조가 장애 대응에 가장 효과적이다.
Terraform으로 알람을 관리하면 빠뜨림이 없다. for_each로 서비스 추가 시 알람이 자동 생성되므로 "새 서비스 올렸는데 모니터링이 없었다"는 사고가 발생하지 않는다.
에러 로그 분리는 필수다. 전체 로그에서 에러를 grep하는 것과, 에러만 모인 그룹을 조회하는 것은 장애 시 체감 차이가 크다.
캐시 히트율처럼 CloudWatch에 없는 메트릭은 Grafana Expression으로 만들 수 있다. Math Expression을 적극 활용하면 커스텀 메트릭 비용 없이 파생 지표를 만들 수 있다.
ok_actions 설정을 잊지 마라. 장애 알림만 오고 복구 알림이 없으면 팀의 불안감이 불필요하게 높아진다.

AI 활용 포인트

7개 대시보드의 JSON 정의를 Claude Code로 생성했다. "ECS 6개 서비스의 CPU/메모리를 한 패널에, 임계치는 70%/90%로"라고 요청하면 Grafana JSON 스펙에 맞는 패널 정의가 나온다. 특히 Math Expression 문법(Cache Hit Rate 계산)이나 CloudWatch Logs Insights 쿼리 작성에서 AI가 시행착오를 크게 줄여줬다.

NestJS MSA Lite 실전 아키텍처 (3/3) — 운영, 배포, 그리고 진화

Archist — Tue, 10 Mar 2026 15:17:17 +0000

여러 레포에 흩어져 있던 B2B SaaS 서비스를 MSA Lite 모노레포로 통합한 경험을 정리한 시리즈의 마지막 글이다.

Part 1: 서비스 구조와 통신 설계

Part 2: 데이터 레이어와 비동기 처리

Part 3: 운영, 배포, 그리고 진화 (이 글)

Terraform + ECS Fargate — 백엔드 2명의 인프라 선택

MSA를 도입하면 배포 단위가 늘어난다. 우리는 5개 서비스(Gateway, AI 처리, 문서 생성, 데이터 파이프라인, 관리자 대시보드)를 운영하고 있다. 이걸 수동으로 관리하면 인프라 변경 하나에 반나절이 날아간다.

Terraform: 인프라 변경 이력이 Git에 남고, plan → apply 2단계로 실수를 사전 차단한다.
ECS Fargate: EC2 인스턴스 관리 부담 없이 서비스별 CPU/메모리를 독립 설정 가능. Kubernetes보다 운영 복잡도가 낮다.

모듈 구조

14개 모듈로 인프라 전체를 관리한다:

terraform/
├── environments/prod/
│   ├── main.tf                 # 모듈 조합 + 서비스별 설정
│   ├── variables.tf
│   ├── backend.tf              # S3 + DynamoDB 상태 관리
│   └── task-definitions/       # ECS 태스크 정의 템플릿
└── modules/
    ├── alb/                    # Application Load Balancer
    ├── alerting/               # CloudWatch 알람 + Slack 알림
    ├── cloudwatch-dashboard/   # 통합 모니터링 대시보드
    ├── codedeploy/             # Blue/Green 배포 자동화
    ├── ecs-cluster/            # ECS 클러스터 + Service Discovery
    ├── ecs-service/            # ECS Fargate 서비스 정의
    ├── grafana/                # AWS Managed Grafana
    ├── iam/                    # IAM 역할 + 정책
    ├── log-router/             # 에러 로그 분리 라우팅
    ├── network/                # 보안 그룹
    ├── secrets/                # Secrets Manager
    └── waf/                    # Web Application Firewall

핵심 설계 원칙: 하나의 모듈은 하나의 인프라 관심사만 담당한다. 모듈 간 의존성은 main.tf에서 output → input으로 연결한다.

서비스별 리소스 설계

서비스	CPU	Memory	배포 전략	비고
Gateway	512	1024MB	Blue/Green	HTTP 진입점, SSE
Service A (AI)	1024	2048MB	Rolling	AI 추론 → 높은 리소스
Service B (문서)	512	1024MB	Rolling	PDF 생성
Service C (데이터)	512	1024MB	Blue/Green	ETL + MCP 서버
Admin Dashboard	256	512MB	Rolling	React SPA

Service A가 다른 서비스의 2배 리소스를 쓴다. 외부 AI 서버와 스트리밍 통신하면서 후처리하는 작업이 CPU/메모리를 잡아먹기 때문이다. Fargate의 장점이 여기서 빛난다 — 서비스별로 리소스를 독립 조정할 수 있다.

Service Discovery — TCP 통신의 핵심

ECS 서비스 간 TCP 통신에 AWS Cloud Map을 사용한다. 하드코딩된 IP 대신 DNS 기반으로 동적 연결한다:

// NestJS TCP 클라이언트 설정
ClientsModule.register([
  {
    name: ServiceToken.SERVICE_A,
    transport: Transport.TCP,
    options: {
      host: 'service-a.my-project.local',  // Cloud Map DNS
      port: 4001,
    },
  },
])

배포 시 태스크가 교체되면 Cloud Map이 자동으로 DNS 레코드를 업데이트한다. TTL 10초이므로 최대 10초 내에 새 태스크로 전환된다.

보안 계층

3중 보안으로 인프라를 보호한다:

인터넷 → WAF (Rate Limiting) → ALB → 보안 그룹 → ECS 태스크

WAF: 5분간 2000 요청 초과 시 IP 차단
보안 그룹: 마이크로서비스 포트는 개발 서버 + 사무실 IP만 허용
Secrets Manager: 환경 변수에 시크릿 하드코딩 없이 ECS가 런타임에 주입

무중단 배포 — Expand-Contract 패턴

Blue/Green 배포 중 Gateway(v2)와 Microservice(v1)가 공존하는 순간이 있다. MessagePattern이나 DTO를 함부로 바꾸면 이 순간에 장애가 발생한다.

DTO 변경 규칙

// Bad: 기존 호출자가 mode를 안 보내면 validation 실패
@IsString()
mode: string;

// Good: 기존 호출자가 없어도 기본값으로 동작
@IsOptional()
@IsString()
mode?: string = "default";

변경 유형	허용 여부	조건
Request에 필드 추가	O	`@IsOptional()` + 기본값
Request에서 필드 제거	X	2단계 배포 필요
Response에 필드 추가	O	호출자가 모르는 필드는 무시
Response에서 필드 제거	X	2단계 배포 필요

MessagePattern 변경: 3단계 배포

Stage 1 (Expand):   마이크로서비스에 신규 패턴 추가, 기존 패턴 유지
Stage 2 (Migrate):  Gateway가 신규 패턴 사용으로 전환
Stage 3 (Contract): 기존 패턴 제거

이 규칙 덕분에 1년 넘게 배포 중 서비스 간 통신 장애가 0건이다.

Blue/Green vs Rolling Update

외부 노출 서비스(Gateway, 데이터 파이프라인)는 CodeDeploy Blue/Green으로 트래픽을 즉시 전환한다. 내부 서비스(AI 처리, 문서 생성)는 Rolling Update로 리소스를 절약한다. 실패 시 Blue/Green은 자동 롤백, Rolling은 이전 Task Definition으로 수동 복구한다.

PM2 무중단 배포

// ecosystem.config.js
{
  name: "service-a",
  script: "./dist/main.js",
  exec_mode: "fork",        // SSE 연결 유지를 위해 cluster 아닌 fork
  wait_ready: true,         // process.send("ready") 대기
  listen_timeout: 30000,
  kill_timeout: 5000,
}

NestJS 부트스트랩 완료 후 process.send("ready")를 호출하면 PM2가 트래픽을 새 프로세스로 전환한다. 기존 프로세스는 5초 유예 후 종료.

테스트 전략 — jest.fn() 없는 세계

MSA에서 테스트가 어려운 이유는 서비스 간 의존성이 복잡하기 때문이다. Fake 구현체 패턴으로 이 문제를 풀었다.

┌─────────────────────────────────────────────┐
│  E2E (Cucumber BDD, 8 병렬 워커)             │
│  "사용자 시나리오가 동작하는가?"                │
├─────────────────────────────────────────────┤
│  Integration (InMemory DB + Fake 구현체)     │
│  "Service → Repository 쿼리가 맞는가?"       │
├─────────────────────────────────────────────┤
│  Unit (Component / 순수 함수)                │
│  "이 판단/변환 로직이 맞는가?"                │ ← 여기를 최대한 늘린다
└─────────────────────────────────────────────┘

jest.fn() 금지, Fake 구현체 사용

// jest.fn() — 타입 안전성 없음, 인터페이스 변경 시 조용히 통과
const mockDb = { getAgentRepository: jest.fn().mockResolvedValue(mockRepo) };
const service = new OrderService(mockDb as any);  // as any 필수

// Fake 구현체 — 컴파일 타임 검증, 실제 동작
class FakeAgentDatabaseService {
  constructor(private readonly dataSource: DataSource) {}

  async getAgentRepository<T>(
    _tenantId: string,
    entity: EntityTarget<T>,
  ): Promise<Repository<T>> {
    return this.dataSource.getRepository(entity);  // InMemory DB
  }
}

Fake는 implements 키워드로 인터페이스를 구현하므로, 원본 인터페이스가 변경되면 컴파일 에러가 발생한다. jest.fn()은 as any로 타입을 우회하기 때문에 이런 보호가 없다.

공유 Fake 패키지

// @myorg/infrastructure/testing
export { FakeAgentDatabaseService, createInMemoryDataSource };
export { NoOpLogger };
export { FakeS3Service };
export { FakeConfigService };
export { FakeProducer };

한 번 만들면 프로젝트 전체에서 재사용한다. 레포가 분리되어 있었을 때는 각 레포에 비슷한 Fake를 따로 만들어야 했지만, 모노레포 통합 후에는 한 곳에서 관리하고 모든 서비스가 동일한 테스트 인프라를 쓴다. Fake 자체도 테스트 자산으로 축적된다.

단위 테스트: mock 0개

Usecase에서 순수 로직을 Component로 추출하면, NestJS DI 없이 new로 생성해서 테스트할 수 있다:

describe("StatusComponent", () => {
  const component = new StatusComponent();  // DI 불필요

  it.each(["READY", "SENT", "FAILED"])(
    "%s 상태이면 재처리 가능하다", (status) => {
      const order = new OrderEntity({ status });
      expect(() => component.validateCanRetry(order)).not.toThrow();
    },
  );
});

모니터링 — CloudWatch + Grafana + Slack

에러 로그 분리

일반 로그와 에러 로그를 분리한다. 에러만 따로 모으면 장애 대응 시간이 단축된다:

ECS 로그 → CloudWatch Log Group (/ecs/service-a)
                    │
                    ├── 전체 로그 (30일 보관)
                    └── ERROR/WARN 필터 → 에러 전용 로그 그룹
                                              │
                                              └→ CloudWatch Alarm → SNS → Slack

5분간 5xx 에러 10회 이상이면 Slack으로 즉시 알림이 온다. Grafana에서 서비스 간 호출 지연, 에러율 트렌드, 리소스 사용 패턴을 한 눈에 파악한다.

운영 스크립트

장애 발생 시 AWS 콘솔을 뒤지는 대신 터미널 한 줄로 대응한다:

./scripts/deploy/service-status.sh gateway     # 서비스 상태 확인
./scripts/deploy/scale-service.sh service-a 4  # 긴급 스케일링
./scripts/deploy/rollback-service.sh gateway   # 이전 버전 롤백
./scripts/deploy/logs-service.sh service-b     # 실시간 로그

여러 레포 → MSA Lite, 1년간의 체감 비교

관점	여러 레포 (Before)	MSA Lite 모노레포 (After)
배포 단위	레포 전체 재배포	서비스별 독립 배포
장애 격리	한 서비스 장애가 다른 레포에 영향 없지만 내부는 전체 다운	서비스별 격리 (Gateway 살아있으면 부분 동작)
스케일링	서비스 통째로만 가능	CPU 집약 서비스만 선택적 스케일 아웃
코드 공유	복사-붙여넣기	공유 패키지로 명시적 관리
디버깅	레포 넘나들며 추적	분산 트레이싱 (AsyncLocalStorage)
로컬 개발	`npm start` 하나	여러 서비스 동시 기동 필요 (PM2/Docker)
인프라 복잡도	낮음	중간 (Redis, 큐, Service Discovery)
새 기능 추가	레포 선택부터 고민	해당 서비스에 추가하면 끝

솔직한 평가: 백엔드 2명이서 통합 작업을 진행하는 건 쉽지 않았다. 하지만 한 번 통합하고 나니 이후 모든 개발 속도가 올라갔다. 특히 새 서비스 추가 비용이 극적으로 줄었다 — 공유 패키지에서 가져다 쓰고, Terraform 모듈 하나 추가하면 인프라까지 끝이다.

아쉬웠던 점

Gateway의 역할이 커졌다. 공통 로직을 Gateway에 넣다 보니 가장 큰 서비스가 됐다. 인증/세션을 별도 서비스로 분리할지 고민 중이지만, 백엔드 2명 규모에서는 분리 복잡도가 이점보다 크다.
TCP 통신의 타입 안전성 부재. client.send()에 잘못된 타입을 넣어도 컴파일러가 통과시킨다. gRPC의 .proto 같은 계약이 없는 셈이다.
Terraform 모듈 분리 시점을 놓쳤다. main.tf 하나에 모든 리소스를 넣다가 1000줄이 넘어간 후에야 분리했다. 처음부터 모듈 단위로 설계했어야 했다.
로컬 개발 환경 복잡도. 모든 서비스를 동시에 띄워야 해서 PM2 + Docker 의존성이 늘었다. npm start 하나로 끝나던 시절이 그립기도 하다.

추후 발전 방향

단기 (3~6개월)

OpenTelemetry 도입: AsyncLocalStorage 트레이싱을 OTEL 표준으로 마이그레이션. Jaeger/Tempo 연동
Circuit Breaker: TCP 통신에 재시도/서킷 브레이커 패턴 추가
Auto Scaling: 현재 고정 태스크 수 → CPU/메모리 기반 자동 스케일링

중기 (6~12개월)

이벤트 기반 통신 병행: 동기 TCP + 비동기 이벤트(Kafka/NATS) 하이브리드
TCP 타입 안전성 강화: 공유 패키지에 서비스별 인터페이스 정의, 컴파일 타임 페이로드 검증
카나리 배포: CodeDeploy Linear/Canary 전략으로 10% 트래픽 먼저 전환

장기 (1년 이상)

Kubernetes 마이그레이션: ECS → EKS. Service Mesh로 트래픽 관리 고도화
GitOps: ArgoCD/Flux로 인프라 변경을 Git PR 기반으로 관리

시리즈를 마치며 — 배운 점

"백엔드 2명도 MSA를 할 수 있다. 단, 범위를 잘 잡아야 한다." 풀 MSA의 인프라 오버헤드를 NestJS 내장 기능 + Terraform 모듈화로 대체하면, 소규모 팀에서도 서비스 분리의 이점을 누릴 수 있다.
모노레포가 MSA의 고통을 반으로 줄인다. 코드 공유, 일관된 린트/빌드, 원자적 커밋. 여러 레포로 분산되어 있었을 때의 패키지 버전 관리 지옥이 사라졌다.
인프라 코드는 자산이다. TracingClientProxy, MicroserviceExceptionFilter, DistributedCron 같은 인프라 레이어와 Terraform 모듈을 공들여 만들면, 이후 서비스 추가 비용이 극적으로 줄어든다.
IaC 없는 MSA는 관리 불가능하다. 서비스가 3개를 넘어가면 수동 인프라 관리는 현실적으로 불가능하다. Terraform 도입 비용은 첫 달에 회수된다.
Fake 구현체는 프로젝트 자산이다. 한 번 만들면 모든 서비스에서 재사용한다. jest.fn()을 매번 setup하는 것보다 효율적이고, 인터페이스 변경 시 컴파일 에러로 동기화된다.
과도하게 나누지 마라. 기능 단위로 적절히 분리하는 선에서 멈췄다. 처음부터 10개 서비스로 시작하면 2명이서 인프라 관리에 매몰된다.

AI 활용 포인트

Terraform 모듈 설계에 Claude Code를 활용했다. 14개 모듈 간 의존성 그래프를 분석하고, 순환 참조 없이 output → input을 연결하는 구조를 잡는 데 효과적이었다. 보안 그룹 규칙 검증 — 불필요하게 열린 포트나 과도한 IP 범위를 탐지하는 데도 AI가 도움이 됐다. 테스트 전략 수립 시에도 코드베이스 전체의 의존성 패턴을 분석해서 Fake 구현체의 인터페이스를 설계하는 데 활용했다.

NestJS MSA Lite 실전 아키텍처 (2/3) — 데이터 레이어와 비동기 처리

Archist — Tue, 10 Mar 2026 15:15:51 +0000

여러 레포에 흩어져 있던 B2B SaaS 서비스를 MSA Lite 모노레포로 통합한 경험을 정리한 시리즈의 두 번째 글이다.

Part 1: 서비스 구조와 통신 설계

Part 2: 데이터 레이어와 비동기 처리 (이 글)

Part 3: 운영, 배포, 그리고 진화

멀티테넌트 데이터베이스 — 테넌트별 DataSource 동적 관리

SaaS 서비스에서 가장 까다로운 문제 중 하나가 멀티테넌시다. 우리 경우 난이도가 한 단계 더 높았다.

각 병원(테넌트)에는 소스 DB가 있다 — 병원 EMR 시스템의 데이터베이스다. 문제는 병원마다 EMR 벤더가 다르고, DB 브랜드(Oracle, MSSQL, PostgreSQL)와 버전이 제각각이며, 심지어 같은 벤더라도 병원이 확장하면 스키마가 달라질 수 있다는 점이다. 여기에 직접 서비스 로직을 태울 수는 없다.

그래서 병원별 서비스 전용 데이터베이스(AgentDB)를 별도로 두고, 소스 DB에서 필요한 데이터를 ETL로 가져와서 정규화된 스키마로 적재하는 구조를 택했다. 서비스 로직은 항상 AgentDB만 바라본다.

아키텍처

소스 DB (병원 EMR)                    서비스 DB (AgentDB)
├── 병원 A: Oracle 11g  ──ETL──→    ├── 병원 A: PostgreSQL
├── 병원 B: MSSQL 2019  ──ETL──→    ├── 병원 B: PostgreSQL
├── 병원 C: Oracle 19c  ──ETL──→    ├── 병원 C: PostgreSQL
│   (SSH 터널 경유)                   └── ...
└── ...
                                           ↑
Config DB (공유)                    AgentDatabaseService
├── 테넌트 마스터 데이터              (런타임 DataSource 관리)
├── DataSourceConfig
│   (테넌트 → DB 접속 정보 매핑)
└── 시스템 설정

소스 DB의 다양성은 ETL 레이어가 흡수하고, AgentDB는 모두 PostgreSQL로 통일했다. 덕분에 서비스 코드에서는 DB 브랜드를 신경 쓸 필요가 없다. 하지만 테넌트별로 독립된 AgentDB가 존재하므로, 런타임에 동적으로 DataSource를 관리해야 한다.

핵심 구현

@Injectable()
export class AgentDatabaseService implements OnModuleInit, OnModuleDestroy {
  private datasourcesMap = new Map<string, DataSource>();

  async getAgentRepository<T extends ObjectLiteral>(
    tenantId: string,
    entity: EntityTarget<T>,
  ): Promise<Repository<T>> {
    const dataSource = await this.getOrCreateDataSource(tenantId);
    return dataSource.getRepository(entity);
  }

  private async getOrCreateDataSource(tenantId: string): Promise<DataSource> {
    // 1. 캐시 히트 → 즉시 반환
    let ds = this.datasourcesMap.get(tenantId);
    if (ds?.isInitialized) return ds;

    // 2. Config DB에서 접속 정보 조회
    const config = await this.loadTenantConfig(tenantId);

    // 3. DataSource 생성 + 커넥션 풀 초기화
    ds = new DataSource({
      url: config.databaseUrl,
      type: config.databaseType,
      entities: SHARED_ENTITIES,
      synchronize: false,  // 프로덕션: migration으로만 스키마 변경
      pool: { max: 20, min: 2, idleTimeoutMillis: 30000 },
    });

    await ds.initialize();
    this.datasourcesMap.set(tenantId, ds);
    return ds;
  }
}

성능 포인트

Lazy Loading: 요청이 들어온 테넌트만 DataSource 생성. 100개 테넌트가 있어도 실제 접속하는 테넌트만 메모리를 사용한다.
커넥션 풀 최적화: 테넌트당 max 20으로 제한. 초기에 기본값(1000)을 그대로 썼더니 100개 테넌트 × 1000 커넥션으로 DB 서버가 다운됐던 경험이 있다.
Graceful Shutdown: onModuleDestroy에서 모든 DataSource를 Promise.allSettled로 순차 정리. 한 테넌트의 정리 실패가 다른 테넌트에 영향을 주지 않는다.
Health Check: 전체 테넌트 DB 연결 상태를 한 번에 점검하는 healthCheck() 메서드 제공.

사용하는 쪽 코드

모든 서비스에서 동일한 패턴으로 테넌트 DB에 접근한다:

// 어떤 서비스든 동일한 인터페이스
const repository = await this.agentDatabaseService.getAgentRepository<OrderEntity>(
  tenantId,
  OrderEntity,
);
const orders = await repository.find({ where: { status: "ACTIVE" } });

비동기 처리 — BullMQ 3계층 패턴

외부 AI 서버와의 스트리밍 통신, PDF 생성, ETL 배치 같은 작업을 동기 API로 처리하면 타임아웃의 늪에 빠진다. BullMQ로 비동기 처리하되, Producer → Consumer → Handler 3계층으로 관심사를 분리했다.

// 1. Producer: 큐에 작업 추가 (thin wrapper)
@Injectable()
class DocumentGenerateProducer {
  async produce(payload: GeneratePayload): Promise<void> {
    await this.queue.add("generate", payload, {
      attempts: 1,
      backoff: { type: "exponential", delay: 2000 },
      removeOnComplete: { age: 7 * 24 * 3600, count: 1000 },
      removeOnFail: false,  // 실패 작업은 모니터링용으로 보존
    });
  }
}

// 2. Consumer: BullMQ Worker (DI 브릿지 역할만)
@Processor("document-generate")
class DocumentGenerateConsumer extends WorkerHost {
  constructor(private readonly handler: DocumentGenerateHandler) { super(); }

  async process(job: Job<GeneratePayload>) {
    await this.handler.handle(job.data);
  }

  @OnWorkerEvent("failed")
  async onFailed(job: Job, error: Error) {
    await this.handler.handleFailure(job.data, error);
  }
}

// 3. Handler: 순수 비즈니스 로직 (테스트 가능)
@Injectable()
class DocumentGenerateHandler {
  async handle(payload: GeneratePayload): Promise<void> {
    // 실제 문서 생성 로직
  }

  async handleFailure(payload: GeneratePayload, error: Error): Promise<void> {
    // DB 상태 복구 (예: status → FAILED)
  }
}

왜 3계층인가?

레이어	테스트 용이성	책임
Producer	높음 (`FakeProducer`로 대체)	큐에 작업 추가
Consumer	낮음 (`@Processor` 데코레이터 종속)	BullMQ ↔ DI 브릿지
Handler	높음 (`new Handler(fakeDeps)`)	비즈니스 로직

Consumer가 BullMQ에 강결합되어 있어 단위 테스트가 어렵다. Handler를 분리하면 new Handler(fakeDb, fakeS3)로 mock 없이 테스트할 수 있다. E2E 테스트에서는 Handler 전체를 MockHandler로 교체하여 큐 의존성을 제거한다.

Bull Board 모니터링

BullMQRootModule.forRoot({ bullBoardRoute: "/queues" })

/queues 경로에서 모든 큐의 대기/처리/실패 작업을 실시간으로 확인할 수 있다. 실패 작업의 스택 트레이스, 재시도 횟수, 처리 시간까지 대시보드에서 바로 보인다. 프로덕션 장애 대응 시 가장 먼저 확인하는 화면이다.

실시간 업데이트 — Redis PubSub 기반 SSE

WebSocket 대신 SSE(Server-Sent Events)를 선택한 이유:

클라이언트 → 서버 양방향 통신이 불필요 (서버 → 클라이언트 단방향 Push만 필요)
HTTP/2 환경에서 다중 스트림 지원
연결 끊김 시 브라우저가 자동 재연결

문제는 마이크로서비스에서 이벤트가 발생하는데, SSE 커넥션은 Gateway에 있다는 점이다. Redis PubSub으로 이 간극을 메웠다.

Microservice                Redis PubSub            Gateway SSE
(이벤트 발생)                                       (클라이언트 연결)
     │                           │                       │
Publisher.publish()  ─────→  Channel  ─────→  Subscriber.onMessage()
     │                           │                       │
     │                           │                  res.write(event)
     │                           │                       │
     │                    Multi-instance 동기화           │

베이스 클래스 상속 패턴

새로운 도메인의 SSE를 추가할 때, 채널명과 이벤트 타입만 정의하면 된다:

// 도메인별 Publisher — 이벤트 채널 정의만 하면 된다
class OrderSsePublisher extends BaseSsePublisher<OrderEvent> {
  protected getChannelName(orderId: string): string {
    return `order_updates_${orderId}`;
  }
}

// Gateway의 Orchestrator — 구독 + 정리 라이프사이클 관리
class OrderSseOrchestrator extends BaseSseOrchestrator<OrderEvent> {
  async start(res: Response, orderId: string) {
    await this.subscriber.subscribe(this.getChannelName(orderId));
    this.startHeartbeat();            // 30초 간격 ping
    res.on("close", () => this.cleanup());  // 연결 종료 시 리소스 정리
  }
}

주의점: Gateway에서 SSE 라우트는 compression 미들웨어에서 반드시 제외해야 한다. gzip이 응답을 버퍼링하면 실시간 스트리밍이 깨진다.

Multi-instance 동기화

Gateway가 2대 이상일 때, 클라이언트 A가 Gateway-1에 연결되어 있는데 이벤트가 Gateway-2를 통해 들어올 수 있다. Redis PubSub은 모든 구독자에게 브로드캐스트하므로 이 문제가 자연스럽게 해결된다. 추가 로직 없이 모든 Gateway 인스턴스가 이벤트를 수신한다.

분산 크론 잡 — 다중 인스턴스에서 한 번만 실행

ECS에서 서비스를 2개 이상 인스턴스로 띄우면, @Cron 데코레이터가 모든 인스턴스에서 동시 실행된다. 매일 아침 알림을 2번 보내거나, ETL이 2번 실행되는 사고가 발생한다.

Redis 분산 락 기반 @DistributedCron 데코레이터로 해결했다:

@DistributedCron("0 8 * * *", {
  name: "daily-notification",  // 글로벌 유니크 락 키
  timeZone: "Asia/Seoul",
  ttlMs: 300_000,             // 5분 TTL (자동 연장)
})
async sendDailyNotification(): Promise<void> {
  // 여러 인스턴스 중 단 하나만 실행
  // 나머지는 "[daily-notification] Skipped" 로그 후 스킵
}

내부 동작

Redis SET key lockId PX ttlMs NX — key가 없을 때만 설정 (원자적 락 획득)
락 획득 성공 → 작업 실행 + TTL의 2/3 시점마다 자동 연장
락 획득 실패 → 스킵 (다른 인스턴스가 실행 중)
작업 완료 → 락 해제

자동 연장이 중요한 이유: TTL을 5분으로 설정했는데 작업이 7분 걸리면? TTL의 2/3 시점(3분 20초)에 자동으로 TTL을 갱신하므로, 장시간 작업에서도 락이 중간에 만료되지 않는다.

사용자 코드에서는 락을 전혀 의식할 필요가 없다. NestJS의 @Cron을 @DistributedCron으로 바꾸고 name만 추가하면 끝이다.

다음 편 예고

Part 3에서는 운영과 진화를 다룬다:

무중단 배포 (Expand-Contract 패턴)
테스트 전략 (jest.fn() 없는 세계)
모놀리스 vs MSA Lite 체감 비교
추후 발전 방향 (OpenTelemetry, Circuit Breaker, K8s)

AI 활용 포인트

소스 DB(병원 EMR)의 스키마 차이를 정규화하는 ETL 매핑 로직을 작성할 때 Claude Code를 활용했다. 병원별로 미묘하게 다른 컬럼명, 데이터 타입, 코드 체계를 분석하고 AgentDB의 통일된 스키마로 변환하는 매퍼를 생성하는 데 특히 유용했다. 멀티테넌트 DB의 커넥션 풀 최적화 값을 결정할 때도 전체 코드베이스의 동시 쿼리 패턴을 분석해 테넌트당 최대 동시 커넥션 수를 추정하는 데 활용했다.

NestJS MSA Lite 실전 아키텍처 (1/3) — 서비스 구조와 통신 설계

Archist — Tue, 10 Mar 2026 14:36:02 +0000

왜 "MSA Lite"인가

혼자 B2B SaaS 백엔드 코드베이스를 여러 개 운영하고 있었다. 같은 의료 도메인을 다루는 여러 개의 NestJS 서비스가 별도 레포에서 돌아가고 있었는데, 서비스가 커지면서 코드 중복, 기능별 스케일링 불가, 배포 파이프라인 다중 관리가 한계에 달했다.

그렇다, 결국엔 합쳐야 했다.

하지만 단순히 하나의 모놀리스로 합치면 또 다른 문제가 생길 것 같았다. 코드 중복은 줄겠지만, 수십 건이 병렬로 도는 ETL 배치나 외부 AI 서버와 장시간 스트리밍 통신하는 기능이 가벼운 CRUD API와 같은 프로세스에 묶이면, 기능별 스케일링은 여전히 불가능하고 한쪽의 부하가 전체 응답성을 끌어내린다.

합치되, 나눌 수 있는 구조가 필요했다.

풀 MSA를 도입하려면 서비스 메시, API Gateway 전용 솔루션, 분산 트랜잭션 관리, 독립 배포 파이프라인 등 인프라 투자가 막대하다. 스타트업에서 백엔드 개발자 2명이 이 모든 걸 감당하기는 불가능에 가깝다. 🥲

내가 절충하여 선택한 방식은 모노레포 안에서 서비스를 논리적으로 분리하되, 통신은 NestJS 내장 TCP 트랜스포트를 사용한다. Kafka나 gRPC 같은 외부 의존성을 추가하지 않으면서도, 서비스별 독립 스케일링과 장애 격리를 확보하는 구조다. 이것을 "MSA Lite"라 부르기로 했다.

┌─────────────────────────────────────────────────────────┐
│                      Monorepo                           │
│                                                         │
│  apps/                    packages/                     │
│  ├── gateway  (HTTP)      ├── api        (DTO/SDK)     │
│  ├── service-a (TCP)      ├── infrastructure (Core)    │
│  ├── service-b (TCP)      └── shared     (Constants)   │
│  ├── service-c (TCP)                                    │
│  └── admin-ui  (React)                                  │
│                                                         │
└─────────────────────────────────────────────────────────┘

1년 넘게 모놀리식을 프로덕션에서 운영하다가 MSA Lite 전환 후 3개월차가 된 현재, 느낀 장단점과 고도화 포인트를 공유한다.

출발점 — 여러 개의 레포를 하나로 합치다

위에서 말한 상황을 정리하면 여러 레포에 흩어진 서비스들이 같은 데이터 구조를 다루면서 각자 Entity, DTO, 유틸리티를 들고 있었고, 인증/인가는 한쪽 레포에서 담당하며 나머지가 이를 공유하는 구조였다.

구체적으로 터지고 있던 문제들:

코드 중복: 한쪽에서 버그를 고치면 다른 레포에는 여전히 남아있다
기능별 스케일링 불가: ETL 배치나 스트리밍 통신이 CRUD API와 같은 프로세스에 묶여 있어 따로 스케일업할 수 없었다
패키지 버전 불일치: 레포마다 TypeORM 버전이 달라 미묘한 동작 차이로 원인 불명의 버그가 발생
배포 파이프라인 다중 관리: 레포마다 CI/CD를 따로 설정. 인프라 변경 시 모든 파이프라인을 동시에 수정해야 했다

기존 서비스들의 비즈니스 로직을 보존하면서, 공통 코드는 공유 패키지로 추출하고, 기능 단위로 서비스를 재분리하고, 서비스 간 통신은 TCP로 표준화하는 방향으로 통합을 시작했다.

서비스 토폴로지

Gateway — HTTP 진입점 + 공통 비즈니스 로직

Gateway는 단순한 TCP 프록시가 아니다. 인증/인가, 세션 관리, 계정 관리 등 모든 서비스가 공통으로 필요한 비즈니스 로직을 담당한다. 기존에 한쪽 레포에서 담당하던 인증 로직을 Gateway로 끌어올린 것이다.

Gateway가 직접 처리하는 영역:

영역	핵심 기능	규모
인증/인가	JWT 발급/검증, 역할 기반 접근 제어, 권한 가드	8개 Guard/Strategy
세션 관리	Redis 기반 세션 생명주기, 재접속 유예, SSE 동기화	7일 TTL, 30초 grace period
계정 관리	CRUD, 비밀번호 재설정, 초대 시스템, 관리자 계정	35개+ Usecase
감사 로그	민감 필드 마스킹, 비동기 저장, 경로 필터링	BullMQ 기반
병원 관리	온보딩 워크플로우, 설정, 가격 정책	Slack 알림 연동
사용자 설정	컬럼 커스터마이징, 필터 프리셋	테넌트별 격리

// Gateway의 인증 — 단순 프록시가 아닌 실제 비즈니스 로직
@Post('auth/login')
@Throttle({ short: { limit: 15, ttl: 60000 } })  // 브루트포스 방지
async login(@Body() body: LoginRequest, @Res() res: Response) {
  // 1. 자격 증명 검증 (DB 직접 조회)
  // 2. JWT 토큰 발급
  // 3. Redis 세션 생성 (7일 TTL)
  // 4. SSE로 세션 상태 브로드캐스트
  // 5. 쿠키 설정 후 응답
}

// 세션 관리 — 네트워크 불안정 대응
@Injectable()
export class AuthSessionService {
  // 연결 끊김 시 30초 유예 → 재접속하면 세션 유지
  async handleDisconnect(sessionId: string) {
    await this.redis.set(
      `grace:${sessionId}`, 'disconnected',
      'EX', GRACE_PERIOD_SEC  // 30초
    );
  }
}

Gateway가 TCP로 위임하는 영역:

도메인 특화 비즈니스 로직은 해당 마이크로서비스에 TCP로 위임한다.

// TCP 위임 — 도메인 로직은 마이크로서비스에서 처리
@Post('orders')
async createOrder(@Body() body: CreateOrderRequest) {
  return await firstValueFrom(
    this.client.send(Messages.OrderService.Order.create, body),
  );
}

이 설계의 근거:
인증/세션 같은 횡단 관심사를 각 마이크로서비스에 분산시키면 일관성 유지가 어렵다. 기존에도 한쪽 레포에서 인증을 중앙 처리하고 있었으므로, 이 패턴을 Gateway로 자연스럽게 이관한 것이다. Gateway를 수평 확장할 때도 세션은 Redis에 있으므로 상태 문제가 발생하지 않는다.

Microservices — TCP + HTTP 이중 스택

각 마이크로서비스는 TCP(서비스 간 통신)와 HTTP(헬스체크/Swagger)를 동시에 서빙한다.

// main.ts (마이크로서비스)
const app = await NestFactory.create(AppModule);

// TCP 서버 연결 (서비스 간 통신)
app.connectMicroservice<MicroserviceOptions>({
  transport: Transport.TCP,
  options: { host: '0.0.0.0', port: TCP_PORT },
});

await app.startAllMicroservices();
await app.listen(HTTP_PORT);

// PM2 무중단 배포 시그널
if (process.send) process.send('ready');

왜 TCP인가? NestJS 내장이라 추가 인프라 없이 바로 쓸 수 있고, JSON 직렬화 기반이라 디버깅이 쉽다. gRPC 대비 성능은 떨어지지만, 우리 트래픽 규모(초당 수백 요청)에서는 병목이 되지 않는다. 무엇보다 백엔드 2명이 별도 인프라를 관리할 여유가 없었다. Kafka는 이벤트 소싱이 필요할 때 도입하기로 하고, 현재는 BullMQ로 비동기 처리를 충분히 커버한다.

공유 패키지 3계층 — 모노레포의 핵심 무기

여러 레포를 합치면서 가장 먼저 한 일이 중복 코드를 공유 패키지로 추출하는 것이었다. 거의 같은 도메인을 다루던 서비스들이었기에 중복이 상당했고, 이것을 정리하는 것이 모노레포 전환의 가장 큰 수확이다.

packages/
├── api/              # DTO, Request/Response 타입
│   └── dto/          # Swagger 데코레이터 포함 → SDK 자동 생성
├── infrastructure/   # Entity, DB, 공통 서비스
│   ├── database/     # TypeORM Entity + Migration
│   ├── bullmq/       # 큐 설정 + Bull Board
│   ├── filter/       # 예외 필터
│   ├── interceptor/  # 인터셉터
│   ├── sse/          # Server-Sent Events 베이스 클래스
│   ├── lock/         # 분산 락 + @DistributedCron
│   └── testing/      # Fake/Stub (FakeDBService, NoOpLogger 등)
└── shared/           # 상수, MessagePattern, ConfigService

패키지	역할	의존 방향
`shared`	상수, 메시지 패턴, 설정	없음 (leaf)
`api`	DTO 정의 + Swagger	`shared`, `infrastructure`
`infrastructure`	핵심 인프라 서비스	`shared`

이전에 여러 레포에서 복사해서 쓰던 코드가 이제 한 곳에만 존재한다. 버그를 고치면 모든 서비스에 즉시 반영된다. Turbo 빌드 파이프라인이 의존 순서를 자동으로 해결한다:

// turbo.json
{
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**"]
    }
  }
}

분산 트레이싱 — AsyncLocalStorage로 서비스 경계를 넘는 Request ID

MSA에서 한 요청이 여러 서비스를 거치면 로그 추적이 지옥이 된다. 이 문제를 Node.js AsyncLocalStorage + TCP 페이로드 주입 조합으로 해결했다.

Client → Gateway(RequestIdMiddleware) → TracingClientProxy → TCP → Microservice(RequestContextInterceptor)
         │                                │                          │
         │ AsyncLocalStorage에             │ 페이로드에                │ 페이로드에서
         │ requestId 저장                  │ __requestId 주입         │ __requestId 추출 →
         │                                │                          │ AsyncLocalStorage에 저장

1단계: Gateway에서 Request ID 생성

// RequestIdMiddleware
const requestId = req.headers['x-request-id'] || randomUUID();
res.setHeader('x-request-id', requestId);
runWithRequestId(requestId, () => next());

2단계: TCP 호출 시 자동 주입

// TracingClientProxy — NestJS ClientProxy 래퍼
private injectRequestId<T>(data: T): T {
  const requestId = getRequestId();  // AsyncLocalStorage에서 조회
  if (!requestId || typeof data !== 'object') return data;
  return { ...data, __requestId: requestId } as T;
}

3단계: 마이크로서비스에서 추출 + 전파

// RequestContextInterceptor
intercept(context: ExecutionContext, next: CallHandler) {
  const data = context.switchToRpc().getData();
  const requestId = data?.__requestId;
  delete data.__requestId;  // 비즈니스 로직에 노출되지 않도록 제거

  return new Observable((subscriber) => {
    runWithRequestId(requestId, () => {
      next.handle().subscribe(subscriber);
    });
  });
}

이 설계의 강점: 비즈니스 코드에서 Request ID를 전혀 의식하지 않는다. 파라미터로 전달하지 않아도 getRequestId() 한 줄이면 어디서든 조회 가능하다.

예외 전파 체인 — 서비스 경계를 넘는 에러 핸들링

MSA에서 가장 놓치기 쉬운 부분이 예외 전파다. Microservice에서 NotFoundException을 던졌는데 Gateway가 500으로 응답하면 클라이언트는 원인을 알 수 없다.

Microservice                    Gateway                     Client
NotFoundException(404)          RpcToHttpInterceptor         HTTP 404
  ↓                              ↓                           ↓
MicroserviceExceptionFilter     {statusCode:404, message}    {statusCode:404,
  ↓                              → HttpException(404)         message:"Not found"}
throwError({statusCode, msg})

Microservice 측: 모든 예외를 정규화

@Catch()
export class MicroserviceExceptionFilter implements RpcExceptionFilter {
  catch(exception: unknown): Observable<never> {
    let statusCode = 500;
    let message = 'Internal server error';

    if (exception instanceof HttpException) {
      statusCode = exception.getStatus();
      message = exception.message;
    }

    return throwError(() => ({ statusCode, message }));
  }
}

Gateway 측: 정규화된 에러를 HTTP 예외로 변환

@Injectable()
export class RpcToHttpInterceptor implements NestInterceptor {
  intercept(context: ExecutionContext, next: CallHandler) {
    return next.handle().pipe(
      catchError((error) => {
        if (error instanceof HttpException) throw error;
        const statusCode = error?.statusCode ?? 500;
        throw new HttpException(
          { statusCode, message: error?.message },
          statusCode,
        );
      }),
    );
  }
}

결과: 클라이언트는 어느 서비스에서 에러가 발생했든 일관된 HTTP 응답을 받는다.

TCP 통신의 계약 — MessagePattern 설계

서비스가 늘어나면 "어떤 서비스가 어떤 메시지를 처리하는가"를 추적하기 어려워진다. 모든 메시지 패턴을 하나의 객체로 중앙 관리하는 방식을 택했다.

// packages/shared/src/message/message-pattern-map.ts
const Messages = createMessagePatternMap({
  ServiceA: {
    Order: {
      create: null,
      findOne: null,
      updateStatus: null,
    },
    Report: {
      generate: null,
      getResult: null,
    },
  },
  ServiceB: {
    Pipeline: {
      start: null,
      getStatus: null,
    },
  },
});

// 자동 생성: Messages.ServiceA.Order.create = "ServiceA.Order.create"

이렇게 하면 IDE에서 자동완성이 되고, 존재하지 않는 패턴을 호출하면 컴파일 타임에 잡힌다. grep으로 "누가 이 메시지를 보내고, 누가 처리하는가"를 한 번에 추적할 수 있다.

한계: 메시지 패턴 자체는 타입 세이프하지만, 페이로드 타입까지 강제하지는 못한다. client.send(Messages.ServiceA.Order.create, 잘못된타입)을 넣어도 컴파일러는 통과시킨다. gRPC의 .proto 같은 계약이 없는 셈이다. 이 부분은 공유 패키지에 서비스별 인터페이스를 정의하는 방향으로 개선 중이다.

서비스 간 의존성 관리 — 누가 누구를 호출하는가

MSA에서 서비스 간 호출이 자유로우면 스파게티가 된다. 우리는 단순한 규칙을 세웠다:

Gateway ──→ ServiceA
Gateway ──→ ServiceB
Gateway ──→ ServiceC
ServiceA ──→ ServiceB  (필요시)

❌ ServiceB → Gateway  (역방향 금지)
❌ ServiceA ↔ ServiceC (순환 금지)

원칙:

Gateway는 모든 마이크로서비스를 호출할 수 있다
마이크로서비스 간 직접 호출은 최소화한다. 필요하면 한 방향으로만
순환 호출은 절대 금지. 순환이 생기면 설계가 잘못된 것이다
비동기로 풀 수 있는 건 BullMQ로 돌린다 (2편에서 다룸)

TCP 클라이언트 등록도 이 규칙을 코드로 강제한다:

// ServiceA의 모듈 — ServiceB만 호출 가능
TracingClientsModule.registerAsync([
  {
    name: ServiceToken.SERVICE_B,
    useFactory: (config: ConfigService) => ({
      transport: Transport.TCP,
      options: {
        host: config.get('SERVICE_B_HOST'),
        port: config.get('SERVICE_B_PORT'),
      },
    }),
    inject: [ConfigService],
  },
])

등록하지 않은 서비스는 물리적으로 호출할 수 없다. "하지 마"라는 문서보다 "할 수 없다"는 코드가 더 확실하다.

공유 패키지의 경계 — 무엇을 공유하고 무엇을 분리하는가

모노레포에서 가장 흔한 실수가 "공유 패키지에 뭐든 넣는 것"이다. 우리도 초기에 이 함정에 빠졌다.

공유해야 하는 것:

Entity 정의 (DB 스키마는 하나)
DTO / Request / Response (서비스 간 계약)
MessagePattern (통신 계약)
인프라 모듈 (DB 접속, 로깅, 예외 필터 등)

공유하면 안 되는 것:

서비스 고유 비즈니스 로직
서비스 내부에서만 쓰는 헬퍼/유틸리티
특정 서비스의 설정값

경험적으로, "2개 이상의 서비스에서 import하는가?"가 공유 패키지에 넣을지 말지의 기준이 됐다. 한 곳에서만 쓰는데 공유 패키지에 넣으면, 변경할 때 불필요한 리빌드가 전파된다.

packages/api/              → 서비스 간 "계약"만. DTO, Request, Response
packages/infrastructure/   → 서비스가 "공통으로 쓰는 인프라". DB, 큐, 로깅
packages/shared/           → 서비스가 "공통으로 참조하는 값". 상수, 메시지 패턴

apps/service-a/src/        → ServiceA만의 비즈니스 로직. 여기 있는 건 절대 공유 안 함

여러 레포 → MSA Lite 모노레포, 구조 관점의 전과 후

관점	여러 레포 (Before)	MSA Lite 모노레포 (After)
코드 공유	레포 간 복사-붙여넣기	공유 패키지로 한 곳에서 관리
통신 계약	암묵적 (문서 또는 구두)	MessagePattern 중앙 관리
서비스 경계	레포 단위 (우연한 분리)	기능 단위 (의도적 분리)
의존성 방향	추적 불가	코드로 강제
패키지 버전	레포마다 제각각	하나의 lockfile로 통일
리팩토링	여러 레포 동시 PR	원자적 커밋 하나로 완료

다음 편 예고

이번 편에서는 MSA Lite의 서비스 구조와 통신 설계를 다뤘다. 하지만 서비스를 나누고 통신을 연결하는 건 시작일 뿐이다. 실제 프로덕션에서는 멀티테넌트 DB 관리, 비동기 작업 처리, 실시간 이벤트 전파 같은 데이터 레이어 문제가 기다리고 있다.

2편: 데이터 레이어와 비동기 처리에서는 테넌트별 DataSource 동적 관리, BullMQ 3계층 패턴, Redis PubSub 기반 SSE 설계를 다룬다.

3편: 운영, 배포, 그리고 진화에서는 무중단 배포의 Expand-Contract 패턴, 분산 크론, 테스트 전략, 그리고 1년간의 회고를 공유한다.

NestJS 멀티테넌트 DB 커넥션 풀 동적 관리: Promise 캐싱과 Lazy Loading

Archist — Sun, 08 Mar 2026 12:57:30 +0000

배경 / 문제 상황

SaaS 서비스를 운영하다 보면 테넌트마다 별도 데이터베이스를 써야 하는 경우가 있다. 우리 서비스는 각 고객사가 독립된 DB를 사용하는 구조인데, 처음에는 단순하게 접근했다.

// 초기 접근: 요청마다 DataSource 생성
async getRepository(tenantCode: string, entity: EntityTarget<T>) {
  const config = await this.loadConfig(tenantCode);
  const dataSource = new DataSource(config);
  await dataSource.initialize();
  return dataSource.getRepository(entity);
}

문제는 금방 드러났다:

커넥션 폭발: 요청마다 새 DataSource를 만들어서 DB 커넥션이 기하급수적으로 증가
초기화 중복: 동시 요청이 들어오면 같은 테넌트에 대해 여러 번 초기화
메모리 누수: 사용 끝난 DataSource를 정리하지 않아 메모리 점유 증가
장애 전파: 한 테넌트 DB가 느려지면 전체 서비스가 영향 받음

CTO 관점에서 되돌아보면, 초기에 "일단 돌아가게" 만든 코드가 프로덕션에서 얼마나 빠르게 시한폭탄이 되는지를 보여주는 전형적인 사례다. 테넌트가 3개일 때는 괜찮았지만, 10개를 넘기자마자 새벽에 알람이 울리기 시작했다.

접근 방법

핵심 전략은 세 가지:

Map 캐싱: 테넌트별 DataSource를 Map에 저장하여 재사용
Promise 캐싱: 초기화 중인 Promise를 캐싱하여 동시 요청의 중복 초기화 방지
Lazy Loading: 시작 시 전체 초기화 + 미등록 테넌트는 런타임에 동적 생성

왜 이 조합인가?

대안	검토 결과	채택 여부
Schema-based 멀티테넌시	고객사별 DB 격리 요구사항 충족 불가	X
Connection Pool만 공유	테넌트별 DB 주소가 다르므로 불가	X
Lazy Loading만	첫 요청 레이턴시 문제	부분 채택
Eager Loading만	신규 테넌트 추가 시 재배포 필요	부분 채택
Eager + Lazy 혼합	기존 테넌트는 즉시, 신규는 동적	O

설계 결정의 핵심은 "재배포 없이 테넌트를 추가할 수 있는가"였다. 병원이 새로 계약하면 Config DB에 레코드만 추가하면 되는 구조를 목표로 했다.

구현

핵심 구조

@Injectable()
export class MultiTenantDatabaseService implements OnModuleInit, OnModuleDestroy {
  // 테넌트별 DataSource 캐시
  private datasourcesMap = new Map<string, DataSource>();

  // Config 조회용 DataSource (메타 정보 DB)
  private configDataSource: DataSource | null = null;

  // 초기화 상태 관리
  private initialized = false;
  private initializationPromise: Promise<void> | null = null;
}

네 가지 상태를 명확히 분리했다:

datasourcesMap: 실제 테넌트 DataSource 저장소
configDataSource: 테넌트 설정 정보를 조회하는 메타 DB
initialized: 초기화 완료 플래그
initializationPromise: 동시성 제어의 핵심

Promise 캐싱으로 중복 초기화 방지

가장 까다로운 부분이 동시성 제어다. NestJS는 onModuleInit을 한 번만 호출하지만, 초기화가 완료되기 전에 요청이 들어올 수 있다.

async onModuleInit(): Promise<void> {
  // 이미 초기화 중이면 같은 Promise를 반환
  if (this.initializationPromise) {
    return this.initializationPromise;
  }

  // 새 Promise 생성 및 캐싱
  this.initializationPromise = this.initialize();
  return this.initializationPromise;
}

이 패턴의 핵심은 같은 Promise 객체를 공유하는 것이다. 세 개의 요청이 동시에 들어와도 initialize()는 단 한 번만 실행되고, 나머지는 같은 Promise의 resolve를 기다린다.

트레이드오프: Mutex나 Semaphore를 쓰면 더 정교한 제어가 가능하지만, Node.js의 싱글 스레드 특성상 Promise 캐싱만으로 충분하다. 오히려 외부 라이브러리 의존성을 줄이는 것이 장기적으로 유리하다고 판단했다.

Lazy Loading: 런타임 동적 생성

서비스 시작 시 Config DB에서 모든 테넌트 설정을 읽어 DataSource를 미리 생성한다. 하지만 나중에 추가된 테넌트도 처리해야 한다:

async getDataSource(tenantCode: string): Promise<DataSource> {
  // 초기화 보장
  if (!this.initialized) {
    await this.ensureInitialized();
  }

  let dataSource = this.datasourcesMap.get(tenantCode);

  // Map에 없으면 Config DB에서 조회하여 동적 생성
  if (!dataSource) {
    const config = await this.getConfig(tenantCode);
    await this.createTenantDataSource(config);
    dataSource = this.datasourcesMap.get(tenantCode);
  }

  if (!dataSource || !dataSource.isInitialized) {
    throw new Error(
      `DataSource for ${tenantCode} not found. Available: ${Array.from(
        this.datasourcesMap.keys()
      ).join(', ')}`
    );
  }

  return dataSource;
}

에러 메시지에 현재 사용 가능한 테넌트 목록을 포함시킨 게 디버깅에 큰 도움이 된다. 프로덕션에서 "테넌트를 찾을 수 없다"는 에러가 뜨면, 어떤 테넌트들이 로드되어 있는지 바로 확인할 수 있다.

커넥션 풀 최적화

초기에는 테넌트당 커넥션을 1000개로 설정했다가 10개 테넌트만 연결해도 DB 서버가 비명을 질렀다. 실제 트래픽을 분석해서 적정값을 찾았다:

private async createTenantDataSource(config: ConfigEntity): Promise<void> {
  const dataSource = new DataSource({
    url: config.databaseUrl,
    type: config.databaseType as any,
    entities: SHARED_ENTITIES,
    synchronize: false,  // 스키마 동기화는 별도 모듈에서

    pool: {
      max: 20,                    // 테넌트당 최대 20개 (기존 1000)
      min: 2,                     // 테넌트당 최소 2개 (기존 10)
      idleTimeoutMillis: 30000,   // 30초 idle timeout
      acquireTimeoutMillis: 10000, // 10초 acquire timeout
    },

    extra: {
      connectionTimeoutMillis: 5000, // 5초 connection timeout
    },
  });

  await dataSource.initialize();
  this.datasourcesMap.set(config.tenantCode, dataSource);
}

핵심 수치 변경:

설정	Before	After	근거
`max`	1000	20	테넌트당 동시 쿼리 최대 15개 관측
`min`	10	2	유휴 시간대 커넥션 낭비 방지
`idleTimeoutMillis`	없음	30초	유휴 커넥션 자동 반환
`acquireTimeoutMillis`	없음	10초	풀 고갈 시 빠른 실패

테넌트 10개 기준 총 200개로 충분했고, DB 서버의 max_connections 설정과도 균형을 맞출 수 있었다.

부분 실패 허용 (Promise.allSettled)

시작 시 모든 테넌트 DataSource를 초기화하는데, 한 테넌트가 실패해도 나머지는 정상 동작해야 한다:

private async initializeAllDataSources(
  configs: ConfigEntity[]
): Promise<void> {
  const results = await Promise.allSettled(
    configs.map((config) => this.createTenantDataSource(config))
  );

  // 실패한 테넌트만 로깅 (서비스는 계속 동작)
  results.forEach((result, index) => {
    if (result.status === 'rejected') {
      this.logger.error(
        `Failed to initialize DataSource for ${configs[index].tenantCode}`,
        result.reason
      );
    }
  });
}

Promise.all 대신 Promise.allSettled를 쓴 이유가 여기 있다. 한 테넌트 DB가 점검 중이어도 나머지 테넌트는 정상 서비스된다.

실무에서 이 결정이 빛났던 순간: 특정 고객사가 DB 서버를 점검하느라 2시간 동안 연결이 불가능했다. Promise.all이었다면 서비스 전체가 시작 실패했겠지만, Promise.allSettled 덕분에 나머지 9개 고객사는 아무 영향 없이 사용할 수 있었다.

안전한 리소스 정리

async onModuleDestroy(): Promise<void> {
  // 모든 테넌트 DataSource 정리 (개별 실패 허용)
  const closePromises = Array.from(this.datasourcesMap.entries()).map(
    async ([tenantCode, dataSource]) => {
      try {
        if (dataSource.isInitialized) {
          await dataSource.destroy();
        }
      } catch (error) {
        this.logger.error(`Failed to close DataSource for ${tenantCode}`, error);
      }
    }
  );

  await Promise.allSettled(closePromises);

  // 완전 초기화
  this.datasourcesMap.clear();
  this.configDataSource = null;
  this.initialized = false;
  this.initializationPromise = null;
}

정리 시에도 try-catch로 감싸서 한 DataSource 정리 실패가 다른 정리를 막지 않도록 했다.

사용 패턴

호출하는 쪽은 이 복잡함을 전혀 모른다:

// Service/Usecase에서 사용
const repo = await this.databaseService.getRepository<OrderEntity>(
  tenantCode,
  OrderEntity
);
const orders = await repo.find({ where: { status: 'active' } });

테넌트 코드만 넘기면 적절한 DataSource에서 Repository를 반환한다. 이 단순한 인터페이스가 설계의 성공 기준이었다.

결과 / 배운 점

이 구조로 변경한 후:

지표	Before	After	개선율
테넌트당 DB 커넥션	~1000개	~20개	98% 감소
메모리 사용량	지속 증가	안정	-
장애 격리	전파 발생	테넌트별 격리	-
신규 테넌트 추가	재배포 필요	Config DB 추가만	-

배운 점:

Promise 캐싱은 동시성 제어의 가장 단순한 해법 — Mutex나 Semaphore 없이 Promise 객체 하나로 중복 초기화를 막을 수 있다
Promise.allSettled는 MSA의 필수 도구 — 부분 실패를 허용해야 전체 시스템의 가용성이 올라간다
커넥션 풀은 보수적으로 — max 1000은 "혹시 모르니까"의 함정. 실제 트래픽 기반으로 설정하자

아쉬웠던 점

솔직히 이 구현에는 몇 가지 알면서도 넘어간 부분이 있다.

Lazy Loading 시 per-tenant 락 미구현: 동시에 같은 신규 테넌트에 대한 요청이 들어오면, getDataSource()에서 Config DB 조회와 DataSource 생성이 중복 실행될 수 있다. Promise 캐싱은 onModuleInit 레벨에서만 적용했고, 개별 테넌트의 Lazy Loading에는 적용하지 않았다. 현재까지 실제 문제가 된 적은 없지만, 테넌트 수가 더 늘어나면 race condition이 발생할 수 있다.
DataSource 수 증가에 따른 메모리 모니터링 부재: 테넌트가 늘어날수록 Map에 쌓이는 DataSource가 많아지는데, 이에 대한 메트릭 수집이 없다. 현재 몇 개의 DataSource가 활성 상태인지, 각각의 커넥션 풀 사용률이 어떤지 대시보드에서 확인할 수 없다.
Config DB가 단일 장애점(SPOF): 모든 테넌트 설정을 하나의 Config DB에서 읽는다. 이 DB가 죽으면 Lazy Loading이 불가능해지고, 서비스 재시작 시 어떤 테넌트도 초기화할 수 없다. Eager Loading으로 이미 로드된 테넌트는 동작하지만, 신규 테넌트 추가나 설정 변경은 불가능하다.

향후 보완할 점

LRU 기반 DataSource 캐시 eviction: 장기간 사용되지 않는 테넌트의 DataSource를 자동으로 정리하는 메커니즘 도입. Map 대신 TTL이 있는 캐시를 사용하거나, 마지막 접근 시간을 기록해서 주기적으로 evict하는 방식을 검토 중이다.
커넥션 풀 메트릭 수집 (Prometheus): 테넌트별 활성/유휴 커넥션 수, 풀 대기 시간, acquire timeout 횟수 등을 Prometheus로 수집하고 Grafana 대시보드로 시각화할 계획이다.
Config DB 이중화: PostgreSQL Streaming Replication 또는 읽기 전용 복제본을 두어, Primary 장애 시에도 테넌트 설정 조회가 가능하도록 구성. 더 나아가 Config 정보를 Redis에 캐싱하는 방안도 고려 중이다.
테넌트별 커넥션 풀 동적 조정: 현재는 모든 테넌트에 동일한 max: 20 설정을 사용하지만, 트래픽이 많은 대형 고객사와 소형 고객사의 풀 사이즈를 다르게 가져가야 한다. Config DB에 테넌트별 풀 설정을 추가하고, 트래픽 패턴에 따라 런타임에 조정하는 것이 목표다.

AI 활용 포인트

Claude Code로 이 서비스를 리팩토링할 때, 기존 코드의 문제점(커넥션 폭발, 초기화 중복)을 분석하고 Promise 캐싱 패턴을 제안받았다. 특히 onModuleDestroy에서 Map 정리 순서와 Promise.allSettled 적용은 AI가 놓치기 쉬운 엣지 케이스를 짚어줬다.

NestJS MSA에서 TypeORM FindOperator가 사라지는 문제 — Interceptor로 해결하기

Archist — Sun, 08 Mar 2026 12:56:36 +0000

문제: TCP로 보내면 FindOperator가 깨진다

NestJS 마이크로서비스 아키텍처에서 Gateway → Microservice 간 TCP 통신을 사용한다. 문제는 TypeORM의 FindOperator가 클래스 인스턴스라는 점이다.

// Gateway에서 이렇게 보내면
this.client.send(Messages.Order.findMany, {
  filter: {
    status: In(["READY", "SENT"]),
    createdAt: Between("2025-01-01", "2025-12-31"),
  },
});

TCP 전송 과정에서 JSON 직렬화가 일어난다. In([...]) 같은 FindOperator는 클래스 인스턴스이므로, 직렬화되면 이렇게 바뀐다:

{
  "filter": {
    "status": {
      "_type": "in",
      "_value": ["READY", "SENT"],
      "_useParameter": true,
      "_multipleParameters": true
    },
    "createdAt": {
      "_type": "between",
      "_value": ["2025-01-01", "2025-12-31"]
    }
  }
}

Microservice에서 이 데이터를 그대로 TypeORM find()에 넘기면? 프로토타입 체인이 없는 순수 객체이므로 TypeORM이 인식하지 못한다. 조건 없이 전체 조회가 되거나, 에러가 발생한다.

CTO 관점: 이 문제는 MSA 전환 시 가장 간과하기 쉬운 유형이다. 모놀리식에서는 존재하지 않던 "직렬화 경계(serialization boundary)" 문제가 서비스를 분리하는 순간 터져나온다. 단일 프로세스에서 잘 동작하던 코드가 MSA에서는 근본적으로 동작하지 않을 수 있다는 것을 팀 전체가 인식해야 한다.

발견 과정

필터가 있는 목록 API를 TCP 기반 MSA로 전환하면서 발견했다. 단일 서비스였을 때는 @Transform() 데코레이터가 생성한 FindOperator가 같은 프로세스 내에서 바로 사용되니까 문제가 없었다. MSA로 분리하는 순간, JSON 직렬화라는 벽에 부딪혔다.

핵심 인사이트: TypeORM FindOperator는 내부적으로 _type과 _value 프로퍼티를 갖고 있고, 이것이 JSON 직렬화를 살아남는다. 역직렬화만 해주면 된다.

직렬화 경계에서의 데이터 변환:

Gateway (클래스 인스턴스)     →  TCP (JSON)              →  Microservice (순수 객체)
In(["READY","SENT"])         →  {_type:"in",_value:[...]}  →  ??? (TypeORM 인식 불가)
                                                            ↓ Interceptor 적용
                                                          In(["READY","SENT"]) ✓

해결: TypeORM Deserializer Interceptor

NestJS Interceptor로 RPC 요청의 페이로드를 가로채서, _type 프로퍼티가 있는 객체를 실제 FindOperator로 복원한다:

@Injectable()
export class TypeOrmDeserializerInterceptor implements NestInterceptor {
  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    if (context.getType() === "rpc") {
      const args = context.getArgs();
      if (args && args.length > 0) {
        args[0] = this.deserializeTypeOrmOperators(args[0]);
      }
    }
    return next.handle();
  }

  private deserializeTypeOrmOperators(obj: any): any {
    if (obj === null || obj === undefined) return obj;
    if (Array.isArray(obj)) {
      return obj.map((item) => this.deserializeTypeOrmOperators(item));
    }

    if (typeof obj === "object") {
      if (obj._type) {
        if (obj._type === "between" && Array.isArray(obj._value)) {
          return Between(obj._value[0], obj._value[1]);
        }
        if (obj._type === "in" && Array.isArray(obj._value)) {
          return In(obj._value);
        }
        if (obj._type === "like") {
          return Like(obj._value);
        }
        if (obj._type === "isNull") {
          return IsNull();
        }
        if (obj._type === "not") {
          // Not의 내부 값을 재귀적으로 역직렬화
          const inner = this.deserializeTypeOrmOperators(obj._value);
          return Not(inner);
        }
        // ... ArrayContains, ArrayOverlap, MoreThanOrEqual 등
      }

      // 일반 객체는 재귀적으로 모든 속성 처리
      const result: any = {};
      for (const [key, value] of Object.entries(obj)) {
        result[key] = this.deserializeTypeOrmOperators(value);
      }
      return result;
    }
    return obj;
  }
}

동작 흐름:

Gateway                    TCP Transport              Microservice
In(["READY","SENT"])  →  {_type:"in",_value:[...]}  →  Interceptor  →  In(["READY","SENT"])
Between(a, b)         →  {_type:"between",_value:..} →  Interceptor  →  Between(a, b)
Not(IsNull())         →  {_type:"not",_value:{       →  Interceptor  →  Not(IsNull())
                           _type:"isNull"}}

설계 결정: Interceptor를 선택한 이유는 비즈니스 코드 변경 없이 인프라 레벨에서 문제를 해결할 수 있기 때문이다. Custom Pipe나 Guard로도 가능하지만, Interceptor가 요청/응답 양쪽을 다룰 수 있어 확장성이 좋다.

Not(IsNull()) — 재귀가 필요한 이유

처음엔 단순한 _type → 연산자 매핑으로 끝날 줄 알았다. Not(IsNull())을 만나기 전까지는.

Not(IsNull())이 직렬화되면:

{
  "_type": "not",
  "_value": {
    "_type": "isNull",
    "_value": null
  }
}

Not의 _value 안에 또 다른 FindOperator가 들어있다. 그래서 Not 처리 시 내부 값을 재귀적으로 역직렬화해야 한다. IsNull()의 _value는 null이므로, 초기 버전에서 if (obj._value) 같은 truthy 체크를 했더니 IsNull이 무시되는 버그도 있었다.

이 버그를 발견하기까지 걸린 시간: 이틀. Not(IsNull()) 조건이 있는 쿼리가 전체 데이터를 반환하는데, 필터가 아예 적용되지 않은 건지 Not 조건만 무시된 건지 구분하기 어려웠다. null이 falsy라는 JavaScript의 기본 동작이 이렇게 치명적일 수 있다는 교훈을 얻었다.

DTO와의 연동

Gateway 쪽 DTO에서 @Transform()으로 FindOperator를 생성한다:

export class OrderFilterInput {
  @Transform(({ value }) => {
    if (!value) return undefined;
    if (Array.isArray(value)) return In(value);
    if (typeof value === "string") return In([value]);
    return undefined;
  })
  status?: FindOperator<OrderStatus>;

  @Transform(({ value }: { value: DateDto }) => {
    if (!value) return undefined;
    return Between(value.start, value.end || value.start);
  })
  createdAt?: FindOperator<Date>;
}

Microservice 컨트롤러에서 Interceptor를 적용하면, DTO의 Transform → JSON 직렬화 → Interceptor 역직렬화가 자동으로 이어진다:

@MessagePattern(Messages.Order.findMany)
@UseInterceptors(TypeOrmDeserializerInterceptor)
async findMany(body: OrderListInput): Promise<OrderListOutput> {
  // body.filter.status는 이미 In(["READY", "SENT"])로 복원됨
  return this.service.findByPagination(body);
}

적용 범위 선택

두 가지 등록 방식을 상황에 따라 사용한다:

// 1. 모듈 전역: 모든 핸들러에 필터가 있을 때
@Module({
  providers: [
    { provide: APP_INTERCEPTOR, useClass: TypeOrmDeserializerInterceptor },
  ],
})
export class OrderModule {}

// 2. 핸들러 단위: 특정 API만 필터를 사용할 때
@MessagePattern(Messages.Order.findMany)
@UseInterceptors(TypeOrmDeserializerInterceptor)
async findMany(body: OrderListInput) { }

등록 방식	장점	단점	권장 상황
모듈 전역	누락 방지	불필요한 순회 발생	대부분 핸들러가 필터 사용
핸들러 단위	정확한 범위	데코레이터 누락 가능	필터 사용 핸들러가 소수

필터가 필요 없는 create, update, delete 핸들러에는 불필요한 재귀 순회를 하지 않도록 핸들러 단위 적용을 권장한다.

결과 / 배운 점

MSA에서 클래스 인스턴스 전송은 근본적으로 불가능하다. JSON 직렬화를 거치는 순간 프로토타입 체인이 사라진다. 이것은 TypeORM에만 국한된 문제가 아니다.
TypeORM FindOperator의 _type 프로퍼티가 구원이었다. 내부 구조를 들여다보니 역직렬화에 필요한 정보가 이미 있었다. 라이브러리 소스를 읽는 습관이 여기서 빛을 발했다.
재귀 설계에서 edge case는 항상 중첩에서 나온다. Not(IsNull())처럼 연산자 안에 연산자가 들어가는 케이스를 놓치기 쉽다.
Interceptor 패턴이 인프라 레벨 문제에 적합하다. 비즈니스 코드를 전혀 수정하지 않고, 직렬화/역직렬화 문제를 한 곳에서 해결했다.

아쉬웠던 점

TypeORM 버전 업데이트 시 _type 값 변경 리스크: 이 Interceptor는 TypeORM의 내부 구현(private property)에 의존한다. _type은 public API가 아니므로, TypeORM 메이저 버전 업데이트 시 이름이 바뀌거나 구조가 변경될 수 있다. 현재 TypeORM 0.3.x 기준으로 작성했는데, 0.4.x나 1.0에서 깨질 가능성을 인지하면서도 별도의 방어 장치를 두지 않았다.
ArrayContains 등 일부 연산자 지원 누락 발견이 늦었음: 초기에 In, Between, Like, IsNull, Not만 구현했는데, 프로덕션에 배포한 후 한참 뒤에야 ArrayContains, ArrayOverlap, MoreThanOrEqual 등이 필요한 쿼리에서 조용히 실패하는 것을 발견했다. "조용한 실패"가 가장 위험하다 — 에러 대신 필터가 무시되어 전체 데이터가 반환되는 식이었다.
성능 오버헤드 측정 미비: 모든 RPC 페이로드를 재귀적으로 순회하는 비용을 측정하지 않았다. 현재 페이로드가 작아서 체감되지 않지만, 대형 응답 객체에 전역 적용하면 불필요한 오버헤드가 발생할 수 있다.

향후 보완할 점

TypeORM 버전별 _type 매핑 자동화 테스트: CI 파이프라인에 TypeORM 버전 업그레이드 시 자동으로 돌아가는 테스트를 추가할 계획이다. 각 FindOperator를 직렬화 → 역직렬화하여 원본과 동일한 쿼리를 생성하는지 검증한다.
FindOperator 커버리지 100% 단위 테스트: TypeORM이 제공하는 모든 FindOperator(Raw, Any, ArrayContains, ArrayOverlap, ILike, LessThan, MoreThan 등)에 대한 직렬화/역직렬화 테스트를 작성하고, 미지원 연산자가 들어오면 명시적으로 에러를 throw하도록 개선한다.
역직렬화 성능 벤치마크: 페이로드 크기별(100B, 1KB, 10KB, 100KB) 역직렬화 소요 시간을 측정하고, 임계치를 넘기면 경고를 내는 메트릭을 추가한다. 이를 근거로 모듈 전역 vs 핸들러 단위 적용 기준을 정량적으로 제시할 수 있다.

AI 활용 포인트

TypeORM FindOperator의 내부 구조(_type, _value)를 Claude Code로 분석했다. TypeORM 소스에서 FindOperator 클래스의 프로퍼티 목록과 각 연산자별 _type 값을 빠르게 추출해서, 지원해야 할 연산자 목록을 확정하는 데 활용했다.

NestJS 마이크로서비스에서 SSE 스트리밍 추상화하기 — Redis Pub/Sub 기반 3-Tier Base Class 설계

Archist — Sun, 08 Mar 2026 08:44:55 +0000

NestJS 마이크로서비스에서 SSE 스트리밍 추상화하기 — Redis Pub/Sub 기반 3-Tier Base Class 설계

배경 / 문제 상황

MSA 환경에서 실시간 이벤트를 클라이언트에 전달해야 했다. 우리 서비스는 ECS 위에 여러 인스턴스가 뜨고, 이벤트를 발행하는 마이크로서비스와 SSE를 내려보내는 Gateway가 물리적으로 다른 프로세스다.

문제는 이렇다:

인스턴스 A의 BullMQ Consumer가 작업을 완료하고 이벤트를 발생시킨다
인스턴스 B의 Gateway에 클라이언트가 SSE로 연결되어 있다
A에서 발생한 이벤트가 B의 클라이언트에게 도달해야 한다

단순히 EventEmitter로는 불가능하다. 프로세스 경계를 넘어야 하니까.

게다가 SSE 도메인이 점점 늘어나면서 (실시간 편집 세션, 인증 세션, 채팅 등) 매번 Redis 구독, 하트비트, 연결 정리 코드를 반복 작성하고 있었다. 한 곳에서 버그를 고치면 다른 곳에는 여전히 남아있는 상황이 반복됐다.

CTO 관점에서의 설계 판단: SSE vs WebSocket vs Long Polling을 비교했다. WebSocket은 양방향 통신이 필요 없는 우리 케이스에서 과하고, ALB WebSocket 연결 유지 비용도 부담이었다. Long Polling은 지연이 불가피했다. SSE는 HTTP/1.1 기반으로 인프라 변경 없이 적용 가능하고, 단방향 실시간 전달에 최적화되어 있어 선택했다.

접근 방법

SSE 연결의 생명주기를 분석하면 도메인과 무관하게 항상 같은 흐름이 반복된다:

연결 → 세션 시작 → Redis 구독 → 이벤트 수신/전송 → 하트비트 → 연결 종료 → 정리

이 흐름을 3개의 추상 클래스로 분리했다:

클래스	책임	위치	도메인이 구현할 것
BaseSsePublisher	Redis Pub/Sub 채널에 이벤트 발행	마이크로서비스	`getChannelName()`, 이벤트 발행 메서드
BaseSseSubscriber	Redis 구독 + SSE 응답 스트리밍	Gateway	`handleMessage()`, `sendConnected()`
BaseSseOrchestrator	연결 생명주기 전체 조율	Gateway	`startSession()`, `endSession()`

핵심 설계 원칙은 "도메인 로직만 구현하면 나머지는 Base가 처리한다"였다.

트레이드오프: 상속 기반 설계는 컴포지션보다 유연성이 떨어진다. 하지만 SSE의 생명주기가 모든 도메인에서 동일한 순서로 실행되어야 하는 제약이 있어서, Template Method 패턴이 적합하다고 판단했다. 잘못된 순서로 호출하는 실수를 컴파일 타임에 방지할 수 있다.

구현

1. Publisher — 이벤트 발행의 단일 진입점

export abstract class BaseSsePublisher<TEvent = any> {
  protected abstract readonly channelPrefix: string;

  constructor(
    protected readonly redisService: RedisService,
    protected readonly logger: Logger,
  ) {}

  protected abstract getChannelName(...keys: string[]): string;

  protected async publishEvent(
    channel: string,
    eventType: string,
    data: TEvent,
  ): Promise<void> {
    const message = JSON.stringify({ type: eventType, ...data });
    await this.redisService.publish(channel, message);
  }

  createSubscriber() {
    return this.redisService.createSubscriber();
  }
}

마이크로서비스에서 BullMQ Handler가 작업을 완료하면 Publisher를 호출한다. Redis Pub/Sub이므로 어떤 인스턴스에서 발행하든, 구독 중인 모든 Gateway 인스턴스가 수신한다.

// BullMQ Handler 내부
await this.ssePublisher.publishStatusChanged(tenantId, orderCode, {
  status: 'COMPLETED',
});

2. Subscriber — SSE 응답 스트리밍의 핵심

여기가 가장 까다로운 부분이다. Express Response 객체를 직접 다루면서 Redis 구독, 하트비트, 연결 끊김 감지를 모두 처리해야 한다.

export abstract class BaseSseSubscriber<TEvent = any> {
  protected subscriber: RedisSubscriber;
  protected isClosed = false;
  protected heartbeatInterval?: NodeJS.Timeout;
  protected onWriteFailureCallback?: () => void;

  constructor(
    protected readonly res: Response,
    protected readonly redisService: RedisService,
    protected readonly channel: string,
    protected readonly enableHeartbeat: boolean = false,
    protected readonly heartbeatIntervalMs: number = 30000,
  ) {
    this.subscriber = this.redisService.createSubscriber();
  }

  setupHeaders(): void {
    this.res.setHeader('Content-Type', 'text/event-stream');
    this.res.setHeader('Cache-Control', 'no-cache');
    this.res.setHeader('Connection', 'keep-alive');
    this.res.setHeader('X-Accel-Buffering', 'no'); // Nginx 버퍼링 비활성화
    this.res.flushHeaders();
  }

  // 서브클래스가 이벤트 타입별 분기만 구현
  protected abstract handleMessage(data: TEvent): void;
  abstract sendConnected(data?: any): void;
}

X-Accel-Buffering: no가 빠지면 Nginx 뒤에서 이벤트가 지연된다. 실제로 이것 때문에 프로덕션에서 이벤트가 30초씩 밀리는 이슈를 겪었다. Base 클래스에 넣어둔 이유다.

Write Failure 감지

SSE에서 가장 흔한 버그 중 하나가 "이미 끊긴 연결에 계속 쓰는 것"이다. res.write()의 반환값으로 이를 감지한다:

sendEvent(event: string, data: string | object): void {
  if (this.isClosed) return;
  const message = typeof data === 'string' ? data : JSON.stringify(data);
  try {
    const success = this.res.write(`event: ${event}\n`);
    this.res.write(`data: ${message}\n\n`);
    if (success === false) {
      // 버퍼가 가득 찼거나 연결이 끊김
      this.onWriteFailureCallback?.();
    }
  } catch (error) {
    this.onWriteFailureCallback?.();
  }
}

res.write()가 false를 반환하면 TCP 버퍼가 가득 찬 것이다. 대부분 클라이언트가 이미 떠났다는 의미다. 이 콜백으로 세션 상태를 즉시 업데이트할 수 있다.

리소스 정리 — 중복 호출 방지

protected cleanup(): void {
  if (this.isClosed) return; // 가드
  this.isClosed = true;

  if (this.heartbeatInterval) {
    clearInterval(this.heartbeatInterval);
  }

  this.subscriber.unsubscribe().catch(() => {});
  this.subscriber.quit().catch(() => {});
}

isClosed 플래그가 없으면 res.on('close')와 에러 핸들러가 동시에 cleanup을 호출하면서 Redis unsubscribe가 두 번 날아간다.

프로덕션에서 배운 것: cleanup에서 .catch(() => {})로 에러를 무시하는 것은 편의상 그렇게 했지만, 최소한 로깅은 해야 한다. Redis 연결 문제가 cleanup에서 발생하면 디버깅 단서가 완전히 사라진다.

3. Orchestrator — 생명주기 조율

Orchestrator는 "세션 시작 → SSE 설정 → 이벤트 등록 → 종료 처리"라는 전체 흐름을 하나의 start() 메서드로 캡슐화한다:

export abstract class BaseSseOrchestrator<
  TSubscriber extends BaseSseSubscriber,
  TStartResult = void,
> {
  protected sessionStarted = false;

  protected abstract createSseSubscriber(): TSubscriber;
  protected abstract startSession(): Promise<TStartResult>;
  protected abstract endSession(): Promise<void>;
  protected abstract getConnectedData(result: TStartResult): any;

  async start(): Promise<void> {
    try {
      const sessionResult = await this.startSession();
      this.sessionStarted = true;

      this.sse.setupHeaders();
      await this.sse.subscribe();
      this.registerEventHandlers();
      this.sse.sendConnected(this.getConnectedData(sessionResult));
      this.sse.startHeartbeat();
    } catch (error) {
      this.handleError(error);
    }
  }

  protected async cleanup(): Promise<void> {
    if (this.sessionStarted) {
      await this.endSession();
    }
    this.sse.close();
  }
}

sessionStarted 플래그가 중요하다. startSession()에서 예외가 발생하면 endSession()을 호출하면 안 된다. 시작하지도 않은 세션을 종료하면 다른 사용자의 세션을 건드릴 수 있다.

에러 발생 시에도 SSE 프로토콜을 지킨다. JSON을 직접 내려보내는 게 아니라 SSE 포맷으로 에러 이벤트를 전송한다:

protected handleError(error: unknown): void {
  this.res.setHeader('Content-Type', 'text/event-stream');
  this.res.flushHeaders();
  this.res.write(
    `event: error\ndata: ${JSON.stringify({
      error: true,
      message: error instanceof Error ? error.message : 'Connection failed',
    })}\n\n`,
  );
  this.res.end();
}

실제 사용 — 도메인 구현체

새로운 SSE 도메인을 추가할 때 구현해야 할 것:

// 1. Publisher (마이크로서비스)
class OrderSsePublisher extends BaseSsePublisher<OrderEvent> {
  protected readonly channelPrefix = 'order:status';
  protected getChannelName(tenantId: string, orderId: string) {
    return `${this.channelPrefix}:${tenantId}:${orderId}`;
  }
}

// 2. Subscriber (Gateway)
class OrderSseSubscriber extends BaseSseSubscriber<OrderEvent> {
  protected handleMessage(data: OrderEvent): void {
    this.sendEvent(data.type, data);
  }
  sendConnected(data: any): void {
    this.sendEvent('CONNECTED', data);
  }
}

// 3. Orchestrator (Gateway)
class OrderSseOrchestrator extends BaseSseOrchestrator<OrderSseSubscriber> {
  protected createSseSubscriber() { return new OrderSseSubscriber(...); }
  protected async startSession() { /* TCP로 마이크로서비스 호출 */ }
  protected async endSession() { /* 세션 정리 */ }
  protected getConnectedData(result) { return { orderId: result.id }; }
}

새 도메인 추가 시 작성하는 코드 vs Base가 처리하는 코드:

항목	도메인이 구현	Base가 처리
채널명 생성	O	-
이벤트 타입별 분기	O	-
세션 시작/종료	O	-
Redis 구독/해제	-	O
SSE 헤더 설정	-	O
하트비트	-	O
Write failure 감지	-	O
연결 끊김 정리	-	O
에러 핸들링	-	O

잊기 쉬운 함정: Compression 미들웨어

SSE 라우트는 반드시 compression 미들웨어에서 제외해야 한다:

// gateway.module.ts
compression({
  filter: (req: Request) => {
    if (req.path === '/order/sse/subscribe') {
      return false; // 압축 비활성화
    }
    return compression.filter(req, req.res);
  },
})

compression이 켜져 있으면 응답 버퍼링이 발생해서 이벤트가 실시간으로 내려가지 않는다. 이것도 Base 수준에서 해결할 수 없는 문제라 문서화해뒀다.

결과 / 배운 점

이 구조를 적용한 뒤 새로운 SSE 도메인을 추가하는 데 걸리는 시간이 크게 줄었다. 하트비트, 연결 정리, Write failure 감지 같은 보일러플레이트를 신경 쓸 필요가 없다.

핵심 교훈:

SSE는 "보내기"보다 "정리"가 어렵다. isClosed 가드, sessionStarted 플래그 같은 방어 코드가 프로덕션 안정성을 결정한다
res.write()의 반환값을 무시하면 좀비 연결이 쌓인다. 반드시 체크해야 한다
Redis Pub/Sub은 다중 인스턴스 SSE의 가장 실용적인 해법이다. Kafka나 RabbitMQ는 이 용도엔 과하다
X-Accel-Buffering: no와 compression 제외는 코드 리뷰에서 빠지기 쉬운데, 빠지면 프로덕션에서 바로 장애가 된다

아쉬웠던 점

Redis Pub/Sub의 at-most-once 특성으로 이벤트 유실 가능: Redis Pub/Sub은 구독자가 없으면 메시지를 버린다. 클라이언트가 SSE 재연결하는 짧은 순간에 발행된 이벤트는 영원히 유실된다. 현재 서비스 특성상 "최종 상태만 정확하면 되는" 케이스가 대부분이라 큰 문제는 아니었지만, 정확한 이벤트 순서가 중요한 도메인에서는 치명적일 수 있다.
하트비트만으로 연결 상태를 판단하는 한계: 30초 간격 하트비트로 연결 유지를 확인하지만, 하트비트 사이에 연결이 끊어지면 최대 30초간 감지가 안 된다. 그 사이에 세션 상태가 "활성"으로 남아있어서, 같은 사용자가 다른 디바이스에서 접속할 때 중복 세션 문제가 발생한 적이 있다.
Orchestrator의 제네릭 타입이 복잡해져서 신규 도메인 추가 시 학습 비용: BaseSseOrchestrator<TSubscriber extends BaseSseSubscriber<TEvent>, TStartResult> 같은 중첩 제네릭이 되면서, TypeScript에 익숙하지 않은 팀원이 새 도메인을 추가할 때 타입 에러와 씨름하는 시간이 길어졌다. 추상화의 편의성을 타입 복잡성이 상쇄하는 아이러니한 상황이었다.

향후 보완할 점

Redis Streams 도입 검토 (이벤트 유실 방지): Redis Pub/Sub 대신 Redis Streams를 사용하면 메시지가 영구 저장되어, 구독자가 없는 동안의 이벤트도 나중에 소비할 수 있다. Consumer Group을 활용하면 다중 인스턴스 환경에서도 정확히 한 번 처리(at-least-once)가 가능하다. 다만 Pub/Sub 대비 복잡도가 증가하므로, 이벤트 유실이 치명적인 도메인부터 단계적으로 적용할 계획이다.
SSE 재연결 시 lastEventId 기반 이벤트 재전송: SSE 표준의 Last-Event-ID 헤더를 활용하여, 재연결 시 놓친 이벤트를 재전송하는 메커니즘을 구현할 계획이다. Redis Streams의 메시지 ID와 SSE의 id 필드를 연계하면, 클라이언트가 마지막으로 받은 이벤트 이후의 메시지만 정확하게 재전송할 수 있다.
Base 클래스 가이드 문서 정비: 제네릭 타입의 복잡성을 코드로 해결하기보다, 잘 작성된 예제와 가이드로 학습 비용을 줄이는 것이 현실적이라고 판단했다. 각 도메인별 구현 예제, 자주 발생하는 타입 에러와 해결법, 체크리스트를 포함한 내부 가이드 문서를 작성 중이다.

AI 활용 포인트

Claude Code로 3개의 Base 클래스를 동시에 리팩토링하면서 기존 구현체와의 호환성을 검증했다. 특히 제네릭 타입 파라미터 설계(BaseSseOrchestrator<TSubscriber, TStartResult>)에서 여러 도메인의 사용 패턴을 한꺼번에 분석해 최적의 인터페이스를 도출하는 데 AI가 효과적이었다.

Claude Code를 팀의 시니어 개발자로 만들기: .claude 디렉토리 설계 전략

Archist — Sun, 08 Mar 2026 08:41:59 +0000

배경 / 문제 상황

AI 코딩 도구를 사용하다 보면 한 가지 불만이 생긴다. 매번 같은 규칙을 알려줘야 한다는 것.

"Entity에는 반드시 comment를 넣어줘", "DTO에는 ApiProperty 빼먹지 마", "import 순서는 이렇게 해"... 10명짜리 팀에서도 코드 리뷰 때마다 같은 코멘트를 반복하는데, AI한테까지 매번 프롬프트로 컨벤션을 주입해야 한다니.

더 큰 문제는 컨텍스트 유실이다. 대화가 길어지거나 새 세션을 열 때마다 AI는 프로젝트의 아키텍처, 네이밍 규칙, 배포 전략 같은 맥락을 잃어버린다. 이전 대화에서 "우리는 Blue/Green 배포를 하니까 Request DTO에 필수 필드를 갑자기 추가하면 안 돼"라고 설명해놓아도 다음 세션에서는 아무것도 기억하지 못한다.

Claude Code의 .claude 디렉토리를 체계적으로 설계하면, AI가 프로젝트의 규칙과 패턴을 항상 이해한 상태에서 코드를 작성한다. 마치 프로젝트에 오래 있었던 시니어 개발자처럼.

나는 NestJS 기반 MSA 모노레포에서 .claude 디렉토리를 설계하면서 얻은 경험을 공유한다.

접근 방법

.claude 디렉토리는 크게 5개 레이어로 나눈다:

.claude/
├── settings.json        # 전역 설정 (hooks, MCP, permissions)
├── rules/               # 코드 작성 규칙 (항상 로드)
├── agents/              # 역할별 전문 에이전트 (12개)
├── skills/              # 슬래시 명령어 워크플로우 (11개)
├── hooks/               # 자동화 훅 (3개)
└── docs/                # 참조 문서

각 레이어의 역할이 명확히 구분되어 있다:

레이어	역할	비유
Rules	어떻게 코드를 써야 하는지	팀 코드 컨벤션 문서
Agents	누구에게 시킬 것인지	역할별 전문가 배정
Skills	무엇을 할 것인지	반복 업무 SOP
Hooks	자동으로 체크할 것	CI/CD 파이프라인
Docs	참고할 것	위키/노션 문서

구현

1. Rules: 코드 컨벤션을 강제하는 법

.claude/rules/ 에 도메인별 규칙 파일을 분리했다. 총 14개의 규칙 파일이 있다:

rules/
├── entity.md              # Entity 작성 규칙
├── dto.md                 # DTO 데코레이터 규칙
├── usecase.md             # Usecase 20줄 제한
├── gateway.md             # Gateway에 비즈니스 로직 금지
├── bullmq.md              # Consumer + Handler 분리 패턴
├── backward-compatible.md # Blue/Green 배포 호환성
├── error-handling.md      # 에러 전파 흐름
├── tcp-communication.md   # 마이크로서비스 통신 규칙
├── sse.md                 # SSE 스트리밍 규칙
├── e2e-test.md            # E2E 테스트 병렬 실행 규칙
├── distributed-cron.md    # 분산 크론 잡 규칙
├── module.md              # NestJS 모듈 구성 규칙
├── import-order.md        # Import 순서 규칙
└── microservice.md        # 마이크로서비스 레이어 규칙

핵심은 구체적인 코드 예시를 함께 넣는 것이다. "이렇게 하지 마" + "이렇게 해"의 Before/After 패턴이 효과적이다:

// 잘못된 예 - 기존 호출자가 mode를 안 보내면 실패
@IsString()
mode: string;

// 올바른 예 - 기존 호출자가 안 보내도 동작
@IsOptional()
@IsString()
mode?: string = 'legacy';

CTO 관점에서 중요한 포인트: Rules 파일 하나가 보통 30~80줄인데, 이 분량이 적절하다. 너무 길면 AI가 핵심을 놓치고, 너무 짧으면 맥락이 부족하다. 하나의 Rule 파일은 하나의 관심사만 다루도록 했다.

2. Agents: 역할별 전문가 팀 구성

12개의 전문 에이전트를 구성했다. 각 에이전트는 모델, 사용 가능 도구, 출력 형식이 다르다:

에이전트	모델	역할	도구 제한
`planner`	opus	구현 계획 수립	Read-only
`code-reviewer`	sonnet	코드 리뷰	Read-only
`debugger`	sonnet	에러 원인 추적	전체
`monorepo-builder`	sonnet	빌드 문제 해결	전체
`api-designer`	haiku	API 엔드포인트 설계	전체
`dto-entity-designer`	haiku	Entity/DTO 생성	전체
`refactorer`	sonnet	코드 리팩토링	전체
`test-designer`	sonnet	테스트 설계	Read-only
`business-logic`	sonnet	비즈니스 로직 구현	전체
`feature-researcher`	sonnet	기존 기능 분석	Read-only
`migration-designer`	haiku	DB 마이그레이션 설계	전체
`docker-troubleshooter`	sonnet	Docker 문제 해결	전체

Read-only 에이전트를 분리한 게 핵심이다. code-reviewer와 planner는 disallowedTools: Edit, Write로 설정해서 코드를 분석만 하고 수정하지 않는다. 리뷰하면서 코드를 바꿔버리는 실수를 방지한다.

---
name: code-reviewer
tools: Read, Grep, Glob, Bash
disallowedTools: Edit, Write  # 읽기 전용!
model: sonnet
---

모델 선택 전략도 중요하다. 계획 수립처럼 고수준 판단이 필요한 작업은 opus, 코드 리뷰나 디버깅처럼 분석 위주 작업은 sonnet, Entity/DTO 생성처럼 패턴화된 작업은 haiku로 배정했다. 비용 대비 품질의 균형이다.

3. Skills: 반복 워크플로우를 명령어로

Skills는 /명령어 형태로 호출하는 워크플로우다. 11개를 만들었는데, 가장 임팩트가 큰 3개:

/aidlc (AI-Driven Development Lifecycle):
User Story 티켓을 기반으로 Unit -> Bolt 단위 구현 계획을 수립한다. MCP 서버에서 User Story를 조회하고, 4시간 단위 작업(Bolt)으로 분해한다. 각 Bolt는 Acceptance Criteria 기반 검증 체크리스트를 포함한다.

/implement:
AIDLC에서 만든 Bolt 문서를 읽고 Entity -> DTO -> Service -> Usecase -> Controller 순서로 구현한다. 작업 완료마다 Bolt 문서의 체크리스트를 업데이트하고, 구현 전에 Mermaid 다이어그램으로 데이터 흐름을 시각화한다.

/bdd-cycle:
User Story의 Acceptance Criteria를 Cucumber E2E 테스트로 자동 변환한다. 테스트 결과를 MCP로 다시 업데이트하는 양방향 동기화. 기존 Feature 파일이 있으면 MCP 코드 태그를 자동 매칭한다.

이 세 가지가 연결되면 기획 -> 계획 -> 구현 -> 테스트 사이클이 완성된다:

/aidlc US-42 → spec.md + bolt-01.md 생성
/implement US-42 bolt-01 → 코드 구현 + 빌드 검증
/bdd-cycle 42 → E2E 테스트 자동 생성 + 실행 + MCP 업데이트

4. Hooks: 실수를 자동으로 차단

3개의 hook을 설정했다:

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{ "command": "bash .claude/hooks/block-dangerous.sh" }]
    }],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "command": "bash .claude/hooks/auto-format.sh" }]
      },
      {
        "matcher": "Bash",
        "hooks": [{ "command": "bash .claude/hooks/pr-convention.sh" }]
      }
    ]
  }
}

block-dangerous.sh (PreToolUse): DROP TABLE, rm -rf /, force push main 같은 위험한 명령을 실행 전에 차단
auto-format.sh (PostToolUse): 파일 수정 후 자동으로 Prettier 실행, .ts/.tsx/.js/.json 파일만 대상
pr-convention.sh (PostToolUse): PR 생성 시 변경된 scope와 stats를 자동으로 PR body에 추가

특히 block-dangerous.sh는 MCP로 DB에 연결된 환경에서 필수다. AI가 실수로 위험한 쿼리를 실행하는 것을 원천 차단한다. 실제로 이 블로그 글을 작성할 때도 본문에 포함된 키워드 때문에 hook이 발동해서 차단당했다. Hook이 잘 작동한다는 증거다.

5. MCP 서버 연동

MCP 서버 2개를 연결해서 AI가 프로덕션 DB를 읽고, User Story를 관리할 수 있게 했다:

{
  "mcpServers": {
    "my-db": {
      "type": "sse",
      "url": "https://my-service.example.com/sse",
      "headers": { "Authorization": "${MCP_TOKEN}" }
    },
    "my-data-platform": {
      "type": "sse",
      "url": "https://my-platform.example.com/sse",
      "headers": { "Authorization": "${MCP_TOKEN}" }
    }
  }
}

DB MCP는 실제 스키마를 조회하면서 Entity를 설계하고, Data Platform MCP는 User Story를 조회/업데이트하며 AIDLC 사이클을 돌린다. AI가 실제 데이터를 보면서 코드를 쓰기 때문에 "테이블에 이 컬럼 있어?" 같은 질문이 사라진다.

결과 / 배운 점

이 설정으로 얻은 것:

코드 일관성: Entity comment 누락, import 순서 위반 같은 실수가 거의 없어짐
워크플로우 자동화: 기획 티켓에서 테스트까지 /aidlc -> /implement -> /bdd-cycle 3단계로 완성
안전장치: Hooks로 위험한 명령 차단, Read-only 에이전트로 리뷰와 수정 분리
온보딩 시간 단축: 새 팀원이 .claude 디렉토리를 보면 프로젝트 컨벤션을 한눈에 파악 가능

설계하면서 배운 점:

Rules는 구체적일수록 좋다 — "좋은 코드를 써" 보다 "Entity에 comment 필수, Before/After 예시 포함"이 100배 효과적
에이전트는 역할로 나눠야 한다 — 만능 에이전트보다 planner(Read-only) + implementer(Edit 가능) 분리가 안전
Skills는 조합이 핵심 — 개별 스킬보다 /aidlc -> /implement -> /bdd-cycle 체인이 진짜 가치

아쉬웠던 점

솔직히 몇 가지 아쉬운 부분이 있다.

1. Rules 파일이 너무 많아졌다. 14개 규칙 파일이 매 대화마다 컨텍스트에 로드되면서 토큰을 상당량 차지한다. AI의 응답 품질과 속도에 영향을 줄 수 있다. 핵심 규칙과 참조용 규칙을 분리하는 전략이 필요했다.

2. Agent 간 컨텍스트 공유가 안 된다. planner가 수립한 계획을 code-reviewer가 참조하려면 파일 시스템을 경유해야 한다. 에이전트 간 직접적인 컨텍스트 전달 메커니즘이 없어서, .aidlc/ 디렉토리에 중간 산출물을 남기는 우회 방식을 쓰고 있다.

3. Skill 프롬프트 유지보수 비용이 크다. /implement 스킬 하나가 400줄짜리 마크다운이다. 프로젝트 구조가 바뀌면 스킬 프롬프트도 같이 수정해야 하는데, 이 동기화가 빠지기 쉽다. 스킬이 코드베이스의 실제 상태와 어긋나면 AI가 존재하지 않는 패턴을 따르려고 한다.

4. Hook의 false positive. block-dangerous.sh가 본문 내용의 키워드를 감지해서 정상적인 명령도 차단하는 경우가 있었다. 실제로 이 블로그 글을 DEV.to에 올릴 때도 본문에 포함된 DB 관련 키워드 때문에 curl 명령이 차단당했다. 패턴 매칭의 정밀도를 높여야 한다.

향후 보완할 점

1. Rules의 계층화: 현재는 모든 규칙이 동일한 우선순위로 로드된다. rules/core/(항상 로드)와 rules/reference/(필요 시 참조)로 나눠서 토큰 효율을 높일 계획이다.

2. Skill 자동 검증: 스킬 프롬프트에서 참조하는 파일 경로가 실제로 존재하는지 CI에서 검증하는 스크립트를 추가하려고 한다. grep -r 'apps/' .claude/skills/ | xargs -I{} test -f {} 같은 간단한 체크만으로도 상당한 drift를 잡을 수 있다.

3. Agent 메모리 시스템 활용: Claude Code의 auto memory 기능을 좀 더 적극적으로 활용해서, 자주 반복되는 디버깅 패턴이나 의사결정 히스토리를 세션 간에 공유할 수 있게 할 예정이다.

4. 팀 단위 확장: 현재는 1인 CTO가 설계하고 사용하는 구조다. 팀원들이 각자의 .claude/settings.local.json으로 개인 설정을 오버라이드하면서도 핵심 Rules와 Skills는 공유하는 구조로 발전시켜야 한다.

5. 성과 측정: .claude 설정의 ROI를 정량적으로 측정하고 싶다. AI가 생성한 코드의 코드 리뷰 리젝률, 컨벤션 위반 건수, 기능 개발 리드타임 같은 메트릭을 수집해서 설정 최적화에 피드백 루프를 만들 계획이다.

AI 활용 포인트

Claude Code 자체의 .claude 시스템을 최대한 활용한 사례다. 별도 도구 없이 Claude Code가 제공하는 rules, agents, skills, hooks만으로 개발 워크플로우 전체를 커버했다.

특히 MCP 서버 + Skills 조합이 강력했다. AI가 단순히 코드만 쓰는 게 아니라, 기획 티켓을 읽고 -> 계획을 세우고 -> 구현하고 -> 테스트까지 하는 전체 사이클을 돌린다.

.claude 디렉토리 설계에 초기 투자만 하면, 이후 모든 기능 개발에서 그 투자가 복리로 돌아온다. 다만 그 "초기 투자"가 생각보다 크고, 유지보수도 꾸준히 필요하다는 점은 미리 감안해야 한다.

AWS 클라우드 환경에서 SSH 터널 서버 안정성 확보하기 — 다층 방어 설계

Archist — Sun, 08 Mar 2026 08:35:59 +0000

문제 상황

MSA 환경에서 온프레미스 DB에 접근하기 위해 리버스 SSH 터널을 사용하고 있었다. 구조는 이렇다:

[온프레미스 PC] ──리버스 터널──► [EC2 SSH 서버] ◄──포워드 터널── [앱 서버 (NestJS)]

온프레미스 DB에 방화벽 인바운드가 차단되어 있어서, 현장 미니 PC가 먼저 밖으로 SSH 연결을 열어두고(리버스 터널), 앱 서버가 그 통로를 통해 DB에 접근하는 구조다.

그런데 EC2 터널 서버가 주기적으로 CPU 급상승 후 넉다운되는 현상이 반복되었다. 연결성 검사(health check)가 실패 상태로 남아, 수동 복구가 필요한 상황이 계속됐다.

CTO 관점: 리버스 SSH 터널은 "빠르게 연결할 수 있는" 방법이지 "운영에 적합한" 방법은 아니다. 처음에 이 구조를 선택한 이유는 온프레미스 환경의 네트워크 제약(인바운드 차단, VPN 불가)과 빠른 MVP 출시 압박 때문이었다. 기술 부채를 인식하면서도 일단 출시하고 나중에 개선하자는 판단이었는데, 그 "나중"이 새벽 알람으로 돌아왔다.

원인 분석: 3개 레이어의 복합 문제

Claude Code로 코드베이스 전체(터널 관리, ETL 스케줄링, PM2 설정, BullMQ 큐)를 병렬로 분석한 결과, 한 곳이 아니라 3개 레이어에 걸친 복합 문제였다.

레이어	문제	영향
앱 서버 코드	백오프 없는 재연결 폭풍	sshd fork 폭발
SSH 서버 설정	좀비 sshd 방치	메모리/CPU 누적
온프레미스 네트워크	NAT 만료로 터널 끊김	위 두 문제의 트리거

Layer 1 — 앱 서버: 백오프 없는 재연결 폭풍

터널 매니저가 10초마다 헬스체크를 하고, 실패하면 아무 제어 없이 즉시 재연결을 시도하고 있었다:

// 문제: setInterval로 10초마다 무조건 실행, 백오프 없음
startHealthCheck(config: TunnelConfig, intervalMs = 10000) {
  const interval = setInterval(async () => {
    await this.checkAndReconnectTunnel(config);
  }, intervalMs);
}

private async checkAndReconnectTunnel(config: TunnelConfig) {
  if (await this.isPortReachable(config.localPort)) return;
  // 실패 → 바로 새 SSH 연결 → 터널 서버에 sshd fork
  await this.createTunnel(config);
}

거기에 PM2로 같은 서비스를 2개 인스턴스로 띄우고 있어서, 동일한 터널에 대해 사실상 5초에 한 번꼴로 재연결을 시도했다. 각 재연결은 터널 서버에 새로운 sshd 프로세스를 fork한다.

Layer 2 — SSH 서버: 좀비 sshd 방치

sshd_config에 ClientAliveInterval 설정이 없었다. 앱 서버가 client.end()로 SSH 세션을 종료해도, TCP 연결이 이미 끊어진 상태면 그 메시지가 원격 sshd에 도달하지 않는다. 결과적으로 좀비 sshd 프로세스가 OS 기본 TCP keepalive(2시간) 동안 살아남는다.

Layer 3 — 온프레미스 네트워크 불안정

온프레미스 미니 PC의 리버스 터널이 끊기면 연쇄 반응이 시작된다:

트래픽 감소 → NAT 테이블 만료 → 리버스 터널 끊김
  → 앱 서버 헬스체크 "포트 도달 불가"
  → 10초마다 재연결 (2인스턴스 x N개 테넌트)
  → 리버스 터널이 없으므로 전부 실패
  → 하지만 sshd fork는 이미 생성됨
  → 좀비 누적 → CPU 급상승 → 넉다운

특히 트래픽이 적은 시간대에 NAT 매핑이 만료되면서 이 사이클이 가속된다. 새벽에 알람이 오는 이유가 바로 이것이었다.

해결: 코드만으론 부족하다

"코드만 고치면 되겠지?"라고 생각했지만, 3개 레이어를 전부 손봐야 했다.

1. 앱 서버 코드 — 재연결 제어

setInterval → setTimeout 체인: 이전 체크가 끝나야 다음이 스케줄되도록 변경했다. setInterval은 콜백 실행 시간과 무관하게 다음 호출이 잡히기 때문에, 재연결이 오래 걸리면 체크가 겹쳐서 동시 SSH 연결이 발생할 수 있었다.

// 개선: setTimeout 체인 + 완료 후 다음 스케줄
startHealthCheck(config: TunnelConfig, intervalMs = 30000) {
  const scheduleNext = () => {
    const timeout = setTimeout(async () => {
      try {
        await this.checkAndReconnectTunnel(config);
      } catch (error) {
        this.logger.error(`Health check error: ${error.message}`);
      }
      // 현재 체크가 완료된 후에만 다음 체크 스케줄
      if (this.healthCheckIntervals.has(name)) {
        scheduleNext();
      }
    }, intervalMs);
    this.healthCheckIntervals.set(name, timeout);
  };
  scheduleNext();
}

Per-name 락: 같은 터널에 대한 동시 생성 시도를 차단했다. 2개 인스턴스가 동시에 같은 포트의 터널을 만들려 할 때 하나만 실행되고 나머지는 대기 후 리턴한다.

async createTunnel(config: TunnelConfig) {
  const { name } = config;

  // 동일 터널의 동시 생성 방지
  const existingLock = this.locks.get(name);
  if (existingLock) {
    await existingLock.catch(() => {});
    return;  // 다른 호출이 이미 생성 완료
  }

  const lockPromise = this.createTunnelInternal(config);
  this.locks.set(name, lockPromise);
  try {
    await lockPromise;
  } finally {
    this.locks.delete(name);
  }
}

분산 크론: ETL 스케줄러의 @Cron → @DistributedCron으로 변경하여, 2개 인스턴스 중 하나만 ETL을 실행하도록 했다. 이전에는 두 인스턴스 모두 동일한 ETL을 실행하며 동시에 터널 연결을 시도하고 있었다.

// Before: 2개 인스턴스 모두 실행
@Cron("0 6 * * *", { name: "morning-etl", timeZone: "Asia/Seoul" })

// After: Redis 락으로 하나만 실행
@DistributedCron("0 6 * * *", { name: "morning-etl", timeZone: "Asia/Seoul" })

2. EC2 터널 서버 — 좀비 sshd 자동 정리 스크립트

sshd 설정 강화(ClientAliveInterval)와 별개로, 2중 안전장치로 좀비 sshd를 직접 탐지해서 kill하는 스크립트를 작성했다.

단순히 "오래된 프로세스를 죽이는" 것이 아니라, 실제 I/O가 있는지 측정해서 판단한다. 리버스 터널이 정상 작동 중인 세션은 절대 건드리지 않아야 하기 때문이다.

#!/bin/bash
# cleanup-idle-tunnels.sh
set -euo pipefail

SAMPLE_SEC=10       # I/O 측정 시간 (초)
MIN_AGE_SEC=3600    # 1시간 미만 세션은 스킵

# sshd 메인 프로세스의 자식들만 대상
MAIN_SSHD_PID=$(pgrep -o -x sshd)
CHILD_PIDS=$(pgrep -P "$MAIN_SSHD_PID" -x sshd)

핵심 판별 로직은 /proc/{pid}/net/dev에서 네트워크 바이트를 10초 간격으로 두 번 읽어서 delta가 0인지 확인하는 것이다:

get_net_bytes() {
  awk 'NR>2 { rx+=$2; tx+=$10 } END { print rx+tx }' "/proc/$1/net/dev"
}

for PID in $CHILD_PIDS; do
  # 1시간 미만 세션은 보호 (방금 생성된 정상 세션일 수 있음)
  AGE=$((NOW - $(stat -c %Y "/proc/$PID")))
  [[ $AGE -lt $MIN_AGE_SEC ]] && continue

  # 10초간 I/O 측정
  BYTES_BEFORE=$(get_net_bytes "$PID")
  sleep "$SAMPLE_SEC"
  BYTES_AFTER=$(get_net_bytes "$PID")

  if [[ $((BYTES_AFTER - BYTES_BEFORE)) -eq 0 ]]; then
    kill "$PID"           # graceful 종료 시도
    sleep 2
    kill -9 "$PID" 2>/dev/null || true  # 안 죽으면 강제
  fi
done

정리 결과는 Slack으로 자동 리포트된다. CPU, 메모리, 로드 평균과 함께 세션 현황을 알려준다:

[Tunnel Server] Idle 세션 정리 완료
────────────────────
Host: tunnel-server
Time: 2026-03-08 11:00:05 KST

[시스템 리소스]
CPU: 12.3%
Memory: 487MB / 978MB (49.8%)
Load Avg: 0.15 0.10 0.08

[SSH 세션]
Total: 14 | Killed: 6 | Active: 5 | Skipped: 3

하루 2번 cron으로 등록했다:

0 11 * * * /usr/local/bin/cleanup-idle-tunnels.sh >> /var/log/cleanup-idle-tunnels.log 2>&1
0 23 * * * /usr/local/bin/cleanup-idle-tunnels.sh >> /var/log/cleanup-idle-tunnels.log 2>&1

--dry-run 모드도 지원해서, 처음에는 kill 없이 상태만 Slack으로 받아보며 패턴을 관찰한 후 실제 적용했다.

왜 sshd 설정만으로 부족한가?

ClientAliveInterval 30 + ClientAliveCountMax 3을 설정하면 90초 내에 죽은 세션이 정리된다. 하지만 이것은 SSH 프로토콜 레벨 keepalive다. TCP 연결 자체가 half-open 상태(한쪽만 끊어진 상태)일 때는 SSH keepalive 패킷이 OS TCP 스택에서 버퍼링만 되고 실제 전송되지 않을 수 있다. 특히 중간에 NAT 장비가 있으면 이 상황이 빈번하다. 그래서 프로세스 레벨에서 실제 I/O를 측정하는 2중 안전장치가 필요하다.

3. 온프레미스 미니 PC — keepalive 강화

# SSH keepalive 30초로 단축 (NAT 만료 방지)
ssh -R 5555:192.168.x.x:1433 -N \
  -o ServerAliveInterval=30 \    # 60 → 30초
  -o ServerAliveCountMax=3 \
  tunnel-service@ssh-server -p 222

해결 구조 요약

[앱 서버 코드]
  - setInterval → setTimeout 체인 (겹침 방지)
  - 10초 → 30초 헬스체크 주기
  - per-name 락 (동시 터널 생성 차단)
  - @DistributedCron (2인스턴스 중복 실행 방지)

[EC2 터널 서버]
  - sshd_config: ClientAliveInterval 30 (SSH 레벨)
  - sysctl: tcp_keepalive_time 60 (OS TCP 레벨)
  - cleanup-idle-tunnels.sh cron (프로세스 I/O 레벨)
  - Slack 모니터링 알림

[온프레미스 미니 PC]
  - SSH keepalive 60초 → 30초 (NAT 만료 방지)
  - 절전 모드 해제

배운 점

"코드만 고치면 된다"는 착각이다. 이 문제는 앱 코드, SSH 서버 설정, 온프레미스 네트워크 3개 레이어가 전부 기여하고 있었다. 어느 하나만 고치면 증상이 완화될 뿐 재발한다.
주기적 장애는 트래픽 패턴과 리소스 생명주기의 교차점을 의심해야 한다. 활성 트래픽이 연결을 유지해주다가, 트래픽이 줄어드는 시간대에 숨어있던 결함이 드러나는 패턴이다.
재연결 로직에는 반드시 백오프가 필요하다. 상대방이 죽었을 때 더 빨리 재연결한다고 살아나지 않는다. 오히려 시체를 더 빨리 쌓을 뿐이다.
방어는 다층으로. SSH 프로토콜 keepalive → OS TCP keepalive → 프로세스 I/O 측정, 각 레이어가 서로 다른 실패 모드를 커버한다.

아쉬웠던 점

3개 레이어를 동시에 수정해야 해서 배포 조율이 복잡했다: 앱 서버 코드 변경은 CI/CD로 배포하지만, EC2 터널 서버의 sshd_config와 cron 스크립트는 Ansible로, 온프레미스 미니 PC의 SSH 설정은 현장 담당자에게 요청해야 했다. 세 가지를 동시에 적용하지 않으면 효과가 반감되는데, 실제로는 2주에 걸쳐 순차 적용했다. 그 2주 동안 부분적으로만 개선된 상태에서 여전히 간헐적 알람이 발생했다.
cleanup 스크립트의 10초 sleep이 프로덕션에서 부담: 각 sshd 프로세스마다 I/O를 10초간 측정하므로, 좀비가 20개 쌓이면 스크립트 실행에 최소 200초(3분 이상)가 소요된다. 그 동안 정상 세션에 대한 측정도 지연된다. 병렬 측정을 도입하면 좋겠지만, bash 스크립트의 한계로 복잡도가 급격히 증가한다.
온프레미스 환경 제어가 어려운 현실: 미니 PC의 네트워크 환경, OS 업데이트, 전원 상태 등을 원격으로 확인하거나 제어할 수 없다. 현장 담당자에게 "절전 모드 해제해달라", "라우터 재부팅해달라" 요청을 반복하는 것은 확장 가능한 운영 방식이 아니다.

향후 보완할 점

WireGuard VPN으로 SSH 터널 대체 검토: WireGuard는 UDP 기반으로 NAT 환경에서 더 안정적이고, 커널 레벨에서 동작하여 sshd 프로세스 관리 문제가 근본적으로 사라진다. 온프레미스 PC에 WireGuard 클라이언트를 설치하고, AWS 측에 WireGuard 서버를 두는 구조를 PoC 중이다. 가장 큰 허들은 온프레미스 환경에 소프트웨어를 설치하는 것 자체의 승인 프로세스다.
터널 상태 대시보드 구축: 현재 Slack 알림만으로는 전체 터널 상태를 한눈에 파악하기 어렵다. 테넌트별 터널 상태(connected/disconnected/reconnecting), 마지막 성공 시간, 재연결 횟수 등을 Grafana 대시보드로 시각화할 계획이다. CloudWatch Custom Metrics로 수집하거나, 앱 서버에서 Prometheus 메트릭을 노출하는 방식을 검토 중이다.
온프레미스 PC를 IoT 디바이스 수준으로 관리하는 MDM 도입: 원격 모니터링(CPU, 메모리, 네트워크 상태), 원격 명령 실행, 자동 업데이트 등이 가능한 MDM(Mobile Device Management) 솔루션 도입을 검토하고 있다. 현장 방문 없이 미니 PC의 상태를 파악하고 문제를 해결할 수 있어야 테넌트 수가 늘어나도 운영이 가능하다.

AI 활용 포인트

Claude Code의 병렬 에이전트로 터널 관리 코드, ETL 스케줄러, PM2 설정, BullMQ 큐, SSH 아키텍처 문서를 동시에 분석했다. 수십 개 파일을 읽으며 상관관계를 파악해야 하는 작업에서, AI가 전체 코드베이스를 빠르게 훑고 "이 setInterval이 여기서 문제를 일으키고, 그 결과가 저 서버에서 좀비 sshd로 나타난다"는 레이어 간 인과관계를 짚어주는 것이 결정적이었다.