김신건의 로그 - 위키 / distributed-systems

[Distributed] NATS: 가벼움, JetStream, subject 라우팅

koa (김신건) — Thu, 16 Jul 2026 00:00:00 GMT

정의

NATS = 극도로 가벼운 메시징 시스템. core NATS = at-most-once Pub/Sub + request-reply. JetStream = 영속 / at-least-once / exactly-once 까지.

특징:

1 바이너리 (Go), 메모리 ~10MB.
마이크로초 latency.
수백만 msg/s/노드.
edge / IoT / 마이크로서비스 친화.

두 모드: Core vs JetStream

-	Core NATS	JetStream
영속	없음 (in-memory)	있음
신뢰성	at-most-once	at-least-once / exactly-once
Latency	매우 낮음	낮음
사용	telemetry, signal	event log, queue

Subject 계층

orders.created
orders.paid
orders.shipped.us
orders.shipped.eu
inventory.low.warehouse-a

와일드카드	의미
`*`	단어 1개
`>`	나머지 모두

subscribe orders.*    → orders.created, orders.paid (1단 차이만)
subscribe orders.>    → orders.created, orders.paid, orders.shipped.us, ...

Request-Reply (Core NATS 의 강점)

sequenceDiagram
    autonumber
    participant R as Requester
    participant N as NATS
    participant S as Service

    S->>N: SUB shop.getItem
    R->>N: PUB shop.getItem (reply=INBOX.abc)
    N->>S: deliver
    S->>S: 처리
    S->>N: PUB INBOX.abc 결과
    N->>R: deliver

RPC 가 Pub/Sub 위에 자연스럽게.
load balancing = 같은 subject 의 queue group 으로.

// Queue group: 여러 service 가 같은 subject 구독, 한 명에게 전달
nats.subscribe('shop.getItem', { queue: 'shop' }, (msg) => { ... });

JetStream 개요

JetStream 은 NATS 에 내장된 영속 스트리밍 레이어:

flowchart LR
    P[Producer] -->|"PUB orders.>"| JS[("JetStream Stream")]
    JS --> Consumer1[Push consumer]
    JS --> Consumer2[Pull consumer]
    JS --> Consumer3[Durable consumer]

Consumer 타입	의미
Push	broker 가 능동 push
Pull	consumer 가 poll
Ephemeral	임시 (재접속 시 처음부터)
Durable	진행 상태 영속

JetStream Stream 설정

# nats CLI 또는 API 로 Stream 생성
stream:
  name: ORDERS
  subjects:
    - orders.>
  storage: file          # file (영속) / memory (빠름)
  retention: limits      # limits / workqueue / interest
  max_age: 24h           # 메시지 보존 기간
  replicas: 3            # 노드 수 (HA 필수)
  max_bytes: 10GB
  discard: old           # 한계 초과 시 오래된 것 삭제

JetStream 메시지 흐름 (Ack)

sequenceDiagram
    autonumber
    participant P as Producer
    participant JS as JetStream
    participant C as Consumer

    P->>JS: PUB orders.created
    JS-->>P: PubAck (seq=42)
    JS->>C: deliver msg (seq=42)
    C->>C: 처리
    C->>JS: Ack
    Note over JS: 해당 seq 완료 마킹
    alt Ack 없이 timeout
        JS->>C: redeliver (at-least-once)
    end

Consumer Ack 정책

AckPolicy	동작
`explicit`	각 메시지 개별 Ack. 가장 안전
`all`	N번 Ack = 1~N 모두 확인 (배치 처리 효율)
`none`	Ack 불필요. fire-and-forget

// Durable Consumer: 재연결 후 마지막 위치부터
const consumer = await js.consumers.get('ORDERS', 'order-processor');
for await (const msg of await consumer.consume()) {
  await processOrder(msg.json());
  msg.ack();   // explicit ack
}

NATS KV / Object Store

JetStream 위 추가 추상:

// KV
const kv = await jsm.views.kv('config');
await kv.put('feature.x', 'enabled');
const val = await kv.get('feature.x');

// Object Store
const os = await jsm.views.os('images');
await os.put('logo.png', readableStream);

Redis 같은 KV, S3 같은 object store 가 NATS 안에 통합. 작은 인프라 친화.

NATS Cluster 구성

# nats.conf (3-node cluster)
cluster {
  name: my-cluster
  listen: 0.0.0.0:6222
  routes: [
    nats-route://nats-0:6222
    nats-route://nats-1:6222
    nats-route://nats-2:6222
  ]
}
jetstream {
  store_dir: /data/jetstream
  max_memory_store: 4GB
  max_file_store: 100GB
}

3 노드 이상 권장 (Raft 합의)
JetStream replica = 노드 수 이하 로 설정 (보통 3)

Edge / IoT 패턴

flowchart TB
    subgraph Edge["Edge devices (수천 ~ 수백만)"]
        E1[Sensor 1]
        E2[Sensor 2]
        EN[Sensor N]
    end
    Edge --> NEdge["NATS edge cluster"]
    NEdge --> Leaf["Leaf node"]
    Leaf --> NCloud["NATS central cluster"]
    NCloud --> Apps["Apps / Analytics"]

Leaf node = edge → central 의 경량 게이트웨이.
bandwidth 최적: 같은 메시지 한 번만 전송.
오프라인 buffer + 재연결 시 sync.

NATS vs Kafka vs RabbitMQ

항목	NATS	Kafka	RabbitMQ
바이너리 크기	10 MB	수백 MB	수십 MB
운영 복잡도	낮음	높음	중간
처리량	매우 높음	매우 높음	중간
Latency	최저	중간	낮음
영속	옵션 (JS)	항상	옵션
Replication	빌트인 (JS)	빌트인	mirror queue
학습 곡선	낮음	높음	중간
Request-Reply	네이티브 지원	어색	가능
Edge/IoT	최적	부적합	가능

Kafka 와 NATS 의 핵심 차이:

-	NATS JetStream	Kafka
설계 목적	빠른 메시징 + 선택적 영속	대용량 영속 로그
장기 retention	가능하지만 Kafka 만큼 최적화 안 됨	최적 (수개월)
Offset 관리	consumer 별 server-side	consumer 가 broker 에 commit
Subject 라우팅	와일드카드 (`*`, `>`)	없음 (topic = exact match)

적합 / 부적합

flowchart TD
    Good[적합]
    Good --> G1[마이크로서비스 사이 메시징]
    Good --> G2["Edge / IoT"]
    Good --> G3[Real-time telemetry]
    Good --> G4["작은 영속 큐 (JS)"]
    Bad[부적합]
    Bad --> B1["복잡한 라우팅 (Topic exchange 같은)"]
    Bad --> B2[수개월 retention 의 거대 로그]

흔한 함정

[!WARNING]

Core NATS 의 손실 가능성 무시 = subscriber 없으면 조용히 사라짐. JS 로 가야.

JS replica 1 = 노드 다운 시 손실. RF 3 권장.

Wildcard 과도 사용 = > 가 모든 메시지 받음 → 클라이언트 부하.

Subject 표준화 없음 = 작은 팀에서는 OK, 큰 팀에서는 충돌 / 중복. 네임스페이스 가이드 필요.

JetStream max_age 미설정 = 디스크 무한 증가. retention 정책 명시 필수.

[Distributed] RabbitMQ: exchange, queue, routing key

koa (김신건) — Thu, 16 Jul 2026 00:00:00 GMT

정의

RabbitMQ = AMQP 0.9.1 기반 traditional message broker. exchange → queue 라우팅, workload distribution, publish-subscribe. Kafka 보다 작은 단위 메시지 라우팅에 강함.

메시지는 반드시 exchange 를 경유해 binding 규칙에 따라 queue 로 전달된다. Producer 는 queue 를 직접 알지 못하고 exchange 에만 발행한다.

언제 쓰이나

Task queue: 백그라운드 작업 배포 (이메일 발송, 이미지 처리)
Request-Reply: RPC 패턴 (reply_to + correlation_id)
복잡한 라우팅: topic/headers exchange 로 세밀한 메시지 필터링
마이크로서비스 이벤트: 서비스 간 비동기 통신
작은 메시지, 낮은 지연: Kafka 보다 단순하고 빠른 설정

구조

flowchart LR
    P[Producer] --> Exch[Exchange]
    Exch -->|"routing key 매칭"| Q1[Queue 1]
    Exch -->|"routing key 매칭"| Q2[Queue 2]
    Exch -->|"routing key 매칭"| Q3[Queue 3]
    Q1 --> C1[Consumer 1]
    Q2 --> C2[Consumer 2]
    Q3 --> C3[Consumer 3]

컴포넌트	의미
Producer	메시지 발행자
Exchange	routing 규칙. 4 종류
Queue	메시지 저장소
Binding	exchange ↔ queue 연결 + key
Consumer	소비자

Exchange 4 종류

flowchart TB
    Direct["Direct\n(routing_key 정확 일치)"]
    Topic["Topic\n(*.error.* 와일드카드)"]
    Fanout["Fanout\n(모든 queue 로 broadcast)"]
    Headers["Headers\n(header attribute 매칭)"]

1. Direct

publish key=ORDER.PAID → queue:paid (binding key=ORDER.PAID)
publish key=ORDER.SHIPPED → queue:shipped (binding key=ORDER.SHIPPED)

하나의 exchange 에 여러 binding key 를 달아 다른 queue 로 보낼 수 있다. 같은 key 에 여러 queue 를 binding 하면 round-robin 분배.

2. Topic

publish key=order.paid.us → matches "order.*.us", "order.paid.*", "#"

와일드카드	의미
`*`	단어 1개
`#`	0+ 단어

3. Fanout

모든 binding 된 queue 로 무조건 복사

Pub/Sub fan-out 의 정통. routing key 를 무시한다.

4. Headers

header { type: "order", region: "us" } 매칭

routing key 대신 메시지 헤더 attribute 로 라우팅. x-match: all (AND) 또는 x-match: any (OR).

실전: Python pika 로 Topic Exchange

import pika
import json

connection = pika.BlockingConnection(pika.ConnectionParameters('localhost'))
channel = connection.channel()

# Exchange 선언
channel.exchange_declare(exchange='orders', exchange_type='topic', durable=True)

# Queue 선언 (DLX 포함)
channel.queue_declare(
    queue='orders.paid',
    durable=True,
    arguments={
        'x-dead-letter-exchange': 'orders.dlx',
        'x-message-ttl': 60000,   # 60초 미처리 시 DLQ
        'x-max-length': 10000,
    }
)

# Binding: order.*.paid 패턴
channel.queue_bind(exchange='orders', queue='orders.paid', routing_key='order.*.paid')

# Publish (persistent 메시지)
channel.basic_publish(
    exchange='orders',
    routing_key='order.kr.paid',
    body=json.dumps({"order_id": 42, "amount": 9900}).encode(),
    properties=pika.BasicProperties(
        delivery_mode=pika.DeliveryMode.Persistent,  # 디스크 저장
        content_type='application/json',
    )
)

print("Published order.kr.paid")
connection.close()

Consumer: ack / nack

def on_message(channel, method, properties, body):
    try:
        data = json.loads(body)
        process_order(data)
        channel.basic_ack(delivery_tag=method.delivery_tag)
    except Exception as e:
        # requeue=False → DLQ 로 라우팅
        channel.basic_nack(delivery_tag=method.delivery_tag, requeue=False)

channel.basic_qos(prefetch_count=10)  # 한 번에 10개만 가져옴
channel.basic_consume(queue='orders.paid', on_message_callback=on_message)
channel.start_consuming()

메시지 보장

sequenceDiagram
    P->>Broker: publish
    Broker->>Disk: persistent? → disk write
    Broker->>P: confirm
    P->>P: confirm 받음 → 안전
    Broker->>C: deliver
    C->>C: 처리
    C->>Broker: ack
    Broker->>Broker: ack 받음 → 제거

설정	의미
`persistent` 메시지	broker 재시작 후에도 보존
`durable` queue	broker 재시작 후 queue 유지
`publisher confirms`	broker 의 받음 확인
`consumer ack`	처리 완료 확인
`mandatory` flag	routing 안 되면 unroutable 반환

[!IMPORTANT] 모든 4가지 켜야 실제 at-least-once 보장. 하나라도 빠지면 손실 가능.

Queue 속성 (x-arguments)

속성	의미	예시 값
`x-message-ttl`	큐 내 메시지 최대 대기 시간 (ms)	`60000` (60초)
`x-max-length`	큐 최대 메시지 수	`10000`
`x-max-length-bytes`	큐 최대 바이트	`104857600` (100MB)
`x-dead-letter-exchange`	TTL/reject 시 라우팅할 DLX	`"orders.dlx"`
`x-dead-letter-routing-key`	DLX 로 보낼 때 routing key	`"failed"`
`x-queue-type`	큐 타입	`"quorum"`, `"stream"`
`x-priority`	Priority Queue 최대 우선순위	`10`

DLQ (Dead Letter Queue)

flowchart LR
    Q1["primary queue"] -->|"reject 또는 ttl 만료"| DLX["Dead Letter Exchange"]
    DLX --> DLQ["DLQ"]
    DLQ --> Inspect["운영자 검사"]

trigger	동작
reject (requeue=false)	DLQ 로
TTL 만료	DLQ 로
queue 길이 한도 초과	DLQ 로

자동 retry 패턴:

flowchart LR
    Q1["primary"] -->|"fail"| DLQ["DLQ"]
    DLQ -->|"ttl 5s"| Retry1["retry-1"]
    Retry1 -->|"fail"| DLQ2["DLQ 2"]
    DLQ2 -->|"ttl 30s"| Retry2["retry-2"]
    Retry2 -->|"fail"| Final["parking lot"]

Quorum Queue (HA)

RabbitMQ 3.8+ 의 고가용성 큐 타입. Raft 합의 알고리즘으로 데이터 복제.

# Quorum Queue 선언
channel.queue_declare(
    queue='orders.quorum',
    durable=True,
    arguments={'x-queue-type': 'quorum'}
)

항목	Classic Queue	Quorum Queue
고가용성	Mirrored (구식)	Raft 기반
메시지 보장	브로커 장애 시 손실 가능	과반 노드 생존 시 보장
성능	빠름	약간 느림 (consensus overhead)
권장	비중요 로컬	프로덕션 중요 메시지

[!CAUTION] Classic mirrored queue 는 RabbitMQ 3.12+ 에서 deprecated. 새 프로젝트는 Quorum Queue 를 사용하세요.

RabbitMQ vs Kafka

항목	RabbitMQ	Kafka
모델	큐 + exchange 라우팅	append-only log
처리량	수만 ~ 수십만/s	수백만/s
Latency	낮음 (ms)	좀 더 큼
영속	옵션	항상
재처리	한 번 소비 후 사라짐	offset 으로 임의 재생
라우팅	유연 (exchange 패턴)	단순 (topic + partition)
사용	task queue, request-reply	event log, stream

RabbitMQ Streams (Kafka 흉내)

3.9+ 의 Stream 큐 타입. append-only log + replica + 재생 가능.

# declare 시
queue.declare("my-stream", arguments={ "x-queue-type": "stream" })

Kafka 와 비슷한 흐름. RabbitMQ 안에서 durable log + fan-out 임의 시점.

흔한 함정

[!WARNING]

persistent 없이 신뢰 = broker 재시작 시 모든 메시지 손실.

prefetch 너무 큼 = 한 consumer 가 수천 메시지 lock → 다른 consumer 가 굶음. prefetch=10~100 권장.

DLQ 없이 reject = 메시지 영구 손실 또는 무한 재시도.

auto_ack=true = consumer 다운 시 처리 안 한 메시지가 ack 됨 (손실).

Classic mirrored queue 신규 사용 = deprecated. Quorum Queue 로 전환.

[Pattern] Microservices vs Monolith: 언제 분리, 언제 통합

koa (김신건) — Thu, 16 Jul 2026 00:00:00 GMT

정의

-	Monolith	Modular Monolith	Microservices
배포 단위	1개	1개 (모듈 명확)	N개
데이터	단일 DB	단일 DB (스키마 분리)	DB per service
통신	함수 호출	함수 호출	네트워크 (HTTP/gRPC)
운영 복잡도	낮음	낮음	높음
스케일링	전체 함께	전체 함께	service 별 독립
장애 격리	약함	약함	강함 (이상적)
적합 팀	< 30	< 100	100+

결정 트리

flowchart TD
    Q1{팀 크기}
    Q1 -->|"< 10"| Mono[Monolith]
    Q1 -->|"10-50"| Q2{성장 속도?}
    Q2 -->|느림| Mono
    Q2 -->|빠름| MM[Modular Monolith]
    Q1 -->|"50-200"| MM
    Q1 -->|"200+"| MS[Microservices]
    MM -->|"진짜 필요해지면"| MS

시작은 Monolith (Fowler 의 “Monolith First”)

flowchart LR
    Start[새 프로젝트] --> Mono["Monolith 로 시작"]
    Mono --> Grow["성장 + 도메인 명확"]
    Grow --> MM[Modular Monolith]
    MM --> Carve["필요시 service 분리"]
    Carve --> MS["Microservices 일부"]

[!IMPORTANT] 대부분의 새 프로젝트는 monolith 로 시작 이 정답. 마이크로서비스로 시작 한 팀이 2년 후 distributed monolith 가 되는 사례가 압도적.

Microservices 가 진짜 도움될 때

flowchart TD
    Q1{독립 배포 절실?}
    Q1 -->|예| C1[조건 1 ✓]
    Q2{팀 별 자율성 절실?}
    Q2 -->|예| C2[조건 2 ✓]
    Q3{스케일 차이 큼?}
    Q3 -->|예| C3[조건 3 ✓]
    C1 & C2 & C3 -->|모두 ✓| Go[Microservices 도입]

Distributed Monolith (안티 패턴)

flowchart LR
    A[Service A] -->|동기 호출| B[Service B]
    B -->|동기 호출| C[Service C]
    C -->|동기 호출| D[Service D]
    Note1[하나 다운 = 전체 다운]

증상:

여러 service 가 함께 배포 되어야 함 (calling contract 변경 시)
한 service 다운 = 전체 다운
분산의 비용 + monolith 의 결합 동시
코드 변경 영향이 service 경계 넘김

[!CAUTION] 마이크로서비스의 최악의 결과. monolith 보다 모든 면에서 나쁨.

Service Boundary 가르는 기준

flowchart TD
    Best[좋은 boundary]
    Best --> B1["Domain (DDD bounded context)"]
    Best --> B2["Team ownership (Conway's Law)"]
    Best --> B3[데이터 모델 자연 분리]
    Bad[나쁜 boundary]
    Bad --> X1["기술 계층 (API / DB / UI)"]
    Bad --> X2["유사 데이터 기준 (DB 테이블 1:1)"]
    Bad --> X3[CRUD 단위 분리]

DDD Bounded Context

Domain-Driven Design 에서 Bounded Context = 독립적인 도메인 모델이 유효한 경계.

flowchart TB
    subgraph Order["Order Context"]
        O_Order[Order]
        O_Item[OrderItem]
        O_Price[Price]
    end
    subgraph Inventory["Inventory Context"]
        I_Product[Product]
        I_Stock[Stock]
    end
    subgraph Payment["Payment Context"]
        P_Payment[Payment]
        P_Invoice[Invoice]
    end
    Order -.->|"ProductId (ref only)"| Inventory
    Order -.->|"PaymentId (ref only)"| Payment

각 context 안에서 같은 이름이라도 의미가 다름 (Order 의 Product vs Inventory 의 Product)
Bounded Context 경계 = Microservice 분리 경계의 자연스러운 후보
Context Map 으로 context 간 관계 (ACL, Shared Kernel, Partnership) 명시

Conway’s Law

“시스템 구조는 그것을 만든 조직의 의사소통 구조를 닮는다”

flowchart TB
    Team1["Team A<br/>(독립 의사소통)"] --> Service1[Service A]
    Team2["Team B<br/>(독립 의사소통)"] --> Service2[Service B]
    Team3["Team C<br/>(독립 의사소통)"] --> Service3[Service C]
    Team1 -.협업.-> Team2
    Service1 -.API.-> Service2

팀 경계와 service 경계의 일치 가 Conway’s Law 의 실용적 활용. 한 service 가 두 팀에 걸치면 운영 사고.

Inverse Conway Maneuver

반대로 service 구조부터 정해 → 팀 구조 맞추기. 큰 조직 재편 에서 사용.

API 통신 패턴: 동기 vs 비동기

flowchart TB
    Sync["동기 (HTTP / gRPC)"]
    Sync --> S1[즉각 응답 필요]
    Sync --> S2[결과 바로 사용]
    Sync --> S3["단점: 결합, 장애 전파"]
    Async["비동기 (Kafka / NATS / RabbitMQ)"]
    Async --> A1[결과 나중에 처리]
    Async --> A2["단점: eventual consistency"]
    Async --> A3["장점: 결합 없음, 장애 격리"]

패턴	사용처	예시
동기 REST/gRPC	즉각 응답, 읽기	상품 조회, 인증
비동기 이벤트	후속 처리, 팬아웃	결제 완료 후 알림 발송
Saga	분산 트랜잭션	주문 생성 + 재고 감소 + 결제

데이터 일관성 전략

분산 트랜잭션 (2PC) 은 마이크로서비스에서 피해야 할 패턴. 대안:

sequenceDiagram
    participant O as Order Service
    participant E as Event Bus
    participant I as Inventory Service
    participant P as Payment Service

    O->>E: OrderCreated (event)
    E->>I: OrderCreated
    I->>I: 재고 감소
    I->>E: StockReserved
    E->>P: StockReserved
    P->>P: 결제 처리
    P->>E: PaymentCompleted
    E->>O: PaymentCompleted
    O->>O: 주문 확정

Choreography-based Saga: 각 서비스가 이벤트를 듣고 다음 단계를 직접 실행.

분리 비용 카탈로그

flowchart TB
    Cost[Microservices 의 추가 비용]
    Cost --> Net[네트워크 호출]
    Cost --> Obs["관측성 (Tracing 필수)"]
    Cost --> Auth["mTLS / Service Mesh"]
    Cost --> Data["데이터 일관성 (Saga)"]
    Cost --> Deploy["K8s, CI/CD 복잡도"]
    Cost --> Test["Contract / E2E 테스트"]
    Cost --> Skill[엔지니어 학습 비용]

Service Mesh 개요

마이크로서비스 간 네트워크 복잡성 을 인프라 레벨에서 해결:

기능	설명
mTLS	service 간 자동 암호화 + 인증
Load balancing	L7 수준, 헬스체크 기반
Circuit breaker	연쇄 장애 방지
Observability	자동 trace / metric 수집
Traffic management	canary, retry, timeout

대표 구현: Istio (풍부한 기능), Linkerd (경량), Cilium (eBPF 기반).

[!IMPORTANT] Service Mesh 는 마이크로서비스의 운영 복잡도 비용 의 일부를 낮춰주지만, 도입 자체도 학습 비용이 크다. 팀 규모와 트래픽 수준에 맞게 도입.

모듈 모놀리스 (Modular Monolith)

flowchart TB
    subgraph App[Single deployable]
        U[User module]
        O[Order module]
        P[Payment module]
    end
    U -.interface only.-> O
    O -.interface only.-> P
    App --> DB[("단일 DB<br/>스키마 분리")]

모듈 간 직접 호출 금지. interface만.
같은 DB, 다른 스키마.
나중에 service 분리 쉬움.
대부분의 회사가 결국 여기서 멈춤 (충분).

흔한 함정

[!WARNING]

너무 일찍 분리 = 도메인 잘못 잡고 분리 후 재경계. 가장 큰 후회.

DB 공유 = “Service 단위 분리” 가 DB 결합 으로 무의미. 각 service 자기 DB.

분산 트랜잭션 (2PC) = 마이크로서비스의 영혼. Saga 패턴으로 대체.

shared library 의 영원한 결합 = service A 가 라이브러리 v2 로 못 올라가면 모든 service 정체.

Bounded Context 무시 = 잘못된 경계로 분리 후 service 간 결합이 더 강해짐.

[Pattern] API Gateway: BFF, 라우팅, auth, rate limit

koa (김신건) — Wed, 15 Jul 2026 00:00:00 GMT

정의

API Gateway = 클라이언트와 마이크로서비스 사이의 단일 진입점. 라우팅, auth, rate limit, transformation, monitoring 의 cross-cutting 책임 을 모음.

역할

flowchart LR
    Client[Mobile / Web / IoT] --> GW[API Gateway]
    GW -->|/users/*| US[User Service]
    GW -->|/orders/*| OS[Order Service]
    GW -->|/payments/*| PS[Payment Service]
    GW -.cross-cutting.-> Auth[Auth]
    GW -.cross-cutting.-> RL[Rate Limit]
    GW -.cross-cutting.-> Log[Logging]
    GW -.cross-cutting.-> Cache[Cache]
    GW -.cross-cutting.-> Transform[Request/Response transform]

요청 처리 파이프라인

flowchart LR
    Req[Request] --> Auth[Auth 검증]
    Auth -->|fail| E401[401]
    Auth -->|pass| RL[Rate Limit]
    RL -->|limit| E429[429]
    RL -->|pass| Route[라우팅]
    Route --> ReqT[Request Transform]
    ReqT --> Back[Backend]
    Back --> RespT[Response Transform]
    RespT --> Log[로깅]
    Log --> Res[Response]

모든 요청이 이 파이프라인을 통과한다. 각 단계는 plugin 또는 middleware 로 구현된다. 실패 시 해당 단계에서 즉시 응답을 반환한다.

책임 카탈로그

책임	예시
라우팅	path / header / host 기준
인증 / 인가	JWT 검증, OAuth, API key
Rate limiting	per-API key, per-IP
Transformation	request/response 변환 (gRPC, REST)
캐싱	응답 캐시
Load balancing	백엔드 분산
Circuit breaker	백엔드 다운 시 차단
Logging / metrics	중앙 집계
WAF	SQLi, XSS 차단
TLS termination	인증서 관리
Versioning	URL / 헤더 기반 분기

인증 플로우

sequenceDiagram
    autonumber
    participant C as Client
    participant GW as Gateway
    participant Auth as AuthSvc
    participant Back as Backend

    C->>GW: GET /api/orders, Authorization Bearer JWT
    GW->>Auth: POST /verify, token
    Auth-->>GW: 200 OK, user_id and roles
    GW->>Back: GET /orders, X-User-Id header
    Back-->>GW: 200 OK, order list
    GW-->>C: 200 OK, order list

Gateway 가 JWT 를 검증하고 X-User-Id 헤더를 추가해 백엔드로 전달한다. 백엔드는 JWT 를 다시 검증하지 않아도 된다.

[!IMPORTANT] Zero-trust 환경에서는 백엔드도 mTLS 또는 별도 인증 토큰으로 검증한다. Gateway 신뢰만으로는 lateral movement 공격에 취약하다.

BFF (Backend For Frontend)

flowchart LR
    iOS[iOS App] --> iOSGW[iOS BFF]
    Web[Web App] --> WebGW[Web BFF]
    Android[Android App] --> AnGW[Android BFF]
    iOSGW & WebGW & AnGW --> Services[(공통 services)]

각 클라이언트 종류마다 별도 gateway. 클라이언트 별 응답 형식 / 페이지네이션 / 압축 차이 흡수. 모바일 = 작은 응답, 웹 = 큰 응답.

BFF 패턴의 장점

클라이언트 팀이 BFF 를 직접 소유하고 배포 가능
공통 백엔드를 수정하지 않고 클라이언트별 최적화 가능
응답 데이터 형식, GraphQL/REST 혼용도 BFF 레벨에서 해결

Kong 설정 예시

Kong 은 Nginx 기반 오픈소스 API Gateway. 선언적 YAML 설정이 가능하다.

_format_version: "3.0"
services:
  - name: order-service
    url: http://order-svc:8080
    routes:
      - name: orders-route
        paths:
          - /api/orders
        methods:
          - GET
          - POST
    plugins:
      - name: jwt
        config:
          secret_is_base64: false
          key_claim_name: kid
      - name: rate-limiting
        config:
          minute: 100
          policy: redis
          redis_host: redis-host
          redis_port: 6379
      - name: request-transformer
        config:
          add:
            headers:
              - X-Gateway-Version:2

# Kong 적용
deck gateway sync kong.yaml

AWS API Gateway

AWS 에서 관리되는 fully managed gateway. Lambda 통합이 강점이다.

# SAM template 예시
Resources:
  ApiGateway:
    Type: AWS::Serverless::Api
    Properties:
      StageName: prod
      Auth:
        DefaultAuthorizer: CognitoAuthorizer
        Authorizers:
          CognitoAuthorizer:
            UserPoolArn: !GetAtt UserPool.Arn
      Cors:
        AllowMethods: "'GET,POST,PUT,DELETE'"
        AllowHeaders: "'Content-Type,Authorization'"
        AllowOrigin: "'*'"

  OrderFunction:
    Type: AWS::Serverless::Function
    Properties:
      Handler: index.handler
      Runtime: nodejs20.x
      Events:
        GetOrders:
          Type: Api
          Properties:
            RestApiId: !Ref ApiGateway
            Path: /orders
            Method: GET

항목	HTTP API	REST API
지연 시간	낮음	높음
기능	기본	완전 (usage plan, caching)
비용	저렴	비쌈
gRPC	미지원	미지원

Envoy + gRPC 트랜스코딩

Envoy 는 Lyft 가 만든 C++ proxy. Service mesh 의 data plane 이자 standalone gateway 로도 쓰인다.

# envoy.yaml: gRPC-JSON transcoding
http_filters:
  - name: envoy.filters.http.grpc_json_transcoder
    typed_config:
      "@type": type.googleapis.com/envoy.extensions.filters.http.grpc_json_transcoder.v3.GrpcJsonTranscoder
      proto_descriptor: /etc/envoy/api.pb
      services:
        - mypackage.UserService
      print_options:
        add_whitespace: true
        always_print_primitive_fields: true

HTTP JSON 요청이 들어오면 Envoy 가 gRPC 로 변환해 백엔드로 전달한다. 클라이언트는 REST 로, 내부는 gRPC 로 통신할 수 있다.

Rate Limiting at Gateway

Gateway 레벨 rate limit 은 Redis 로 분산 카운터를 관리해야 한다. 단일 노드 in-memory 카운터는 인스턴스가 여럿이면 N배 한도가 허용된다.

# Redis Lua atom: sliding window counter
SLIDING_WINDOW_LUA = """
local key = KEYS[1]
local now = tonumber(ARGV[1])
local window = tonumber(ARGV[2])
local limit = tonumber(ARGV[3])

redis.call('ZREMRANGEBYSCORE', key, 0, now - window)
local count = redis.call('ZCARD', key)
if count < limit then
    redis.call('ZADD', key, now, now)
    redis.call('EXPIRE', key, window)
    return 1
end
return 0
"""

Kong / Envoy / AWS API Gateway 모두 Redis 기반 rate limit 을 기본 지원한다.

API Gateway vs Service Mesh

항목	API Gateway	Service Mesh
위치	외부 ↔ 내부 경계 (north-south)	내부 ↔ 내부 (east-west)
책임	인증, transformation, public API	mTLS, retry, circuit, observability
클라이언트 인지	직접 호출	sidecar 자동
예	Kong, AWS API Gateway, Envoy	Istio, Linkerd

둘 다 운영하는 경우가 흔하다. gateway 가 north-south, mesh 가 east-west.

도구 비교

도구	종류	강점
Kong	OSS gateway	plugin 생태계
Tyk	OSS gateway	옵션
Envoy	Proxy	gRPC, L7, mesh 토대
AWS API Gateway	Managed	Lambda 통합
Cloudflare Workers	Edge	글로벌
Apigee	Enterprise	엔터프라이즈
Apollo Router	GraphQL	federation

패턴: GraphQL Federation Gateway

flowchart TB
    Client --> Router[Apollo Router]
    Router --> A[User subgraph]
    Router --> B[Order subgraph]
    Router --> C[Payment subgraph]

자세한 건 [[graphql]] 참고.

흔한 함정

[!WARNING]

Gateway 가 모든 비즈니스 로직 흡수 = monolith 의 재림. cross-cutting 만.

단일 gateway 의 bottleneck = HA + auto-scaling 필수.

Auth 검증 백엔드 마다 다시 = gateway 가 검증 → 백엔드는 trust. 단 zero-trust 환경에서는 백엔드도 검증.

Rate limit 의 분산 상태 = 단일 노드 카운터 = race. 중앙 store (Redis) + sliding window.

[Distributed Systems] CAP Theorem과 PACELC

koa (김신건) — Tue, 14 Jul 2026 00:00:00 GMT

정의

CAP Theorem (Eric Brewer, 2000): 분산 시스템에서 3가지 중 2개만 동시에 보장 가능.

C (Consistency): 모든 노드가 같은 시점에 같은 데이터 반환 (강한 일관성)
A (Availability): 모든 요청이 응답 받음 (실패도 응답)
P (Partition Tolerance): 네트워크 분할이 있어도 동작

현실: P는 선택지 아님 (네트워크는 항상 깨질 수 있음). 따라서 실질적 선택은:

CP: 분할 시 일관성 우선 → 일부 노드 응답 안 함
AP: 분할 시 가용성 우선 → 일관성 일시 깨짐

CP vs AP 선택 다이어그램

flowchart TD
    P{"네트워크 분할 발생"}
    P -->|"CP 선택"| CP["일관성 우선\n일부 노드 응답 거부\n(minority partition 정지)"]
    P -->|"AP 선택"| AP["가용성 우선\n모든 노드 응답\n(일시적 불일치 허용)"]
    CP --> CPex["etcd, Consul, ZooKeeper\nHBase, Spanner\nPostgreSQL (single)"]
    AP --> APex["Cassandra, DynamoDB\nCouchDB, Riak\nDNS"]

실제 시스템 매핑

시스템	CAP 분류	이유
etcd	CP	Raft 합의, minority 정지
Consul	CP	Raft 기반, quorum 필요
ZooKeeper	CP	ZAB 프로토콜, leader 필요
Cassandra	AP	모든 노드 응답, eventual consistency
DynamoDB	AP (기본)	가용성 우선, 강한 일관성 옵션
Riak	AP	vector clock 기반 충돌 해결
CouchDB	AP	MVCC, eventual consistency
HBase	CP	HDFS + ZooKeeper
Spanner	CP	TrueTime, global consistency
MongoDB	CP (기본)	primary-only write
Redis Cluster	AP	분할 시 일부 write 손실 가능
DNS	AP	캐시로 stale 응답 허용

[!IMPORTANT] 이 분류는 단순화. 실제 시스템은 설정에 따라 달라진다. DynamoDB는 ConsistentRead=true로 CP에 가깝게, Cassandra는 CONSISTENCY ALL로 CP에 가깝게 동작 가능.

etcd / Consul: CP 상세

sequenceDiagram
    autonumber
    participant C as "Client"
    participant L as "Leader (etcd)"
    participant F1 as "Follower 1"
    participant F2 as "Follower 2 (분리됨)"

    C->>L: write key=value
    L->>F1: AppendEntries (Raft)
    L->>F2: AppendEntries (Raft)
    F1-->>L: ack
    Note over F2: 네트워크 분할
    L->>L: quorum (2/3) 달성 → commit
    L-->>C: OK

    C->>F2: read (분리된 노드)
    F2-->>C: 오류 또는 stale 거부

Raft quorum (N/2 + 1)이 없으면 write 거부
minority partition은 read도 거부 (stale 방지)
분할 복구 후 자동 동기화

Cassandra: AP 상세

flowchart LR
    subgraph DC1["DC1 (분할됨)"]
        N1["Node A\nwrite: x=1"]
    end
    subgraph DC2["DC2 (분할됨)"]
        N2["Node B\nwrite: x=2"]
    end
    N1 -.분할 복구.-> N2
    N2 -.충돌 해결 LWW.-> Result["x=2 (최신 timestamp 승리)"]

분할 중에도 양쪽 모두 write 허용
복구 후 Last Write Wins (LWW) 또는 vector clock으로 충돌 해결
일시적으로 다른 사용자가 다른 결과를 볼 수 있음

CAP의 한계와 PACELC

CAP는 “분할 시” 시나리오만 다룸. 정상 작동 시의 trade-off는?

PACELC (Daniel Abadi, 2010):

Partition 시: Availability vs Consistency
Else (정상): Latency vs Consistency

flowchart TD
    Q{"네트워크 상태"}
    Q -->|"분할 발생 (P)"| PQ{"A vs C"}
    Q -->|"정상 (E)"| EQ{"L vs C"}
    PQ -->|"A 선택"| PA["PA: Cassandra, DynamoDB, Riak"]
    PQ -->|"C 선택"| PC["PC: etcd, HBase, Spanner"]
    EQ -->|"L 선택"| EL["EL: Cassandra, DynamoDB"]
    EQ -->|"C 선택"| EC["EC: Spanner, VoltDB"]

시스템	PACELC	해석
MongoDB	PA / EC	분할 시 A, 정상 시 C
Cassandra	PA / EL	분할 시 A, 정상 시 L (낮은 latency)
HBase	PC / EC	항상 C
DynamoDB	PA / EL	항상 가용성 / latency 우선
PostgreSQL	PC / EC	단일 노드 강한 일관성
Spanner	PC / EC	글로벌 강한 일관성

PACELC가 더 실제적: 정상 시간이 훨씬 길기 때문.

Conflict Resolution (충돌 해결)

AP 시스템에서 분할 후 복구 시 충돌 해결 방법:

Last Write Wins (LWW)

Node A: x=1 at t=100
Node B: x=2 at t=101
→ x=2 승리 (최신 timestamp)

단순하지만 clock skew 위험 (NTP 오차로 잘못된 승리)
Cassandra 기본 전략

Vector Clock

Node A: x=1, vc=[A:1, B:0]
Node B: x=2, vc=[A:0, B:1]
→ 충돌 감지 (두 vc가 비교 불가)
→ 애플리케이션이 해결 (또는 두 값 모두 보존)

인과 관계 추적 가능
Riak, Amazon Dynamo 사용

CRDT (Conflict-free Replicated Data Type)

G-Counter: 각 노드가 자기 카운터만 증가
merge: max(A.count, B.count) per node
→ 충돌 없이 자동 병합

특정 데이터 타입 (counter, set, map)에서 자동 병합
Redis CRDT, Riak 지원

Consistency Spectrum

CAP의 “C”는 strong consistency. 실무는 더 세밀한 spectrum:

flowchart TD
    S["Strong Consistency\n가장 엄격"]
    S --> L["Linearizability\n실시간 순서 보장"]
    L --> Seq["Sequential Consistency"]
    Seq --> Cau["Causal Consistency\n인과 관계만 보장"]
    Cau --> E["Eventual Consistency\n가장 느슨"]

수준	의미	예시
Linearizability	실시간 순서 보장, 가장 강함	etcd, Spanner
Sequential	모든 노드가 같은 순서로 봄	ZooKeeper
Causal	인과 관계 있는 연산만 순서 보장	MongoDB causal sessions
Eventual	결국 수렴, 시간 보장 없음	Cassandra (ONE), DNS

대부분 AP 시스템 = eventual. CP 시스템 = strong (or linearizable).

Tunable consistency (Cassandra 패턴)

CONSISTENCY LEVEL = ONE / QUORUM / ALL / EACH_QUORUM

ONE: 1개 노드 응답이면 OK (빠르지만 stale 위험)
QUORUM: 과반수 (N/2 + 1)
ALL: 모든 replica 응답 (느리지만 가장 일관)

write QUORUM + read QUORUM = strong consistency 보장 (N=3이면 2+2 = 4 > 3).

-- Cassandra CQL
CONSISTENCY QUORUM;
SELECT * FROM orders WHERE id = ?;

실무 선택 기준

금융 / 결제: CP

계좌 잔액은 절대 stale 안 됨
→ HBase, PostgreSQL (single instance), Spanner
→ 분할 시 거래 차단이 안전

SNS / Feed: AP

타임라인이 일시적으로 다르게 보여도 됨
→ Cassandra, DynamoDB
→ 분할이라도 게시 / 조회 가능

검색 인덱스: AP (eventual)

검색 결과가 몇 초 지연돼도 OK
→ Elasticsearch (near real-time)

서비스 디스커버리: CP

잘못된 서비스 주소 = 장애
→ etcd, Consul (Raft 기반)
→ 분할 시 등록 거부가 안전

메시지 큐: 두 모드

Kafka: AP (high throughput)
RabbitMQ: 모드별 선택 (mirror queue는 CP)

CAP의 흔한 오해

오해 1: CA 시스템도 가능?

NO. 분산 환경에서 P는 선택지 아님 (네트워크는 항상 깨질 수 있음). “CA”는 single-node 시스템 (MySQL standalone).

오해 2: AP = 일관성 없음?

NO. AP는 eventual consistency 또는 weaker. 결국엔 수렴.

오해 3: CAP가 영구 선택?

NO. 분할 발생 시점에만 trade-off. 정상 시간엔 PACELC의 E (latency vs consistency).

오해 4: P는 datacenter 분할만?

분할 = network가 잠시라도 깨짐. 짧은 packet loss / latency spike도 포함. 빈번히 발생.

consensus와의 관계

CAP의 “C”를 보장하려면 합의 (consensus) 필요. Raft, Paxos 같은 알고리즘이 분할 시 majority만 진행:

5-node cluster
├── 3-node majority (가능, 진행)
└── 2-node minority (정지)

majority가 사라지면 (3+ 노드 분할) cluster 전체 정지. [[distributed-systems-consensus]] 참고.

흔한 함정

[!WARNING]

CAP는 정상 시 trade-off 안 다룸: PACELC가 더 현실적

P는 항상: CA 시스템은 single-node에서만

eventual consistency도 정확한 정의: 결국 수렴, 시간 보장 X

Tunable consistency 활용: Cassandra의 QUORUM 패턴

금융은 CP, SNS는 AP: 도메인별 명확

단순화하지 말 것: 모든 read가 strong 필요 X, 모든 write가 eventual OK X

monitoring: stale read 비율, partition 빈도 추적

[Distributed] Kafka Consumer Group: rebalancing, offset, lag

koa (김신건) — Tue, 14 Jul 2026 00:00:00 GMT

정의

Consumer Group = 같은 group.id를 가진 consumer들이 함께 한 topic을 분담 소비. partition 단위로 분배.

핵심 특성:

한 partition → 한 consumer (group 안에서)
여러 Consumer Group은 같은 topic을 독립적으로 소비 가능
Group Coordinator (Kafka broker)가 멤버십과 partition 할당 관리

Partition 할당

flowchart LR
    subgraph T["Topic: orders (6 partitions)"]
        P0[p0] & P1[p1] & P2[p2] & P3[p3] & P4[p4] & P5[p5]
    end
    subgraph CG["Consumer Group"]
        C1["Consumer 1"] --> P0 & P1
        C2["Consumer 2"] --> P2 & P3
        C3["Consumer 3"] --> P4 & P5
    end

규칙:

partition 수 >= consumer 수면 모두 분배
partition 수 < consumer 수면 일부 consumer idle
한 partition → 한 consumer (group 안)

Group Coordinator

Group Coordinator = consumer group의 멤버십과 rebalancing을 관리하는 Kafka broker.

sequenceDiagram
    autonumber
    participant C as "Consumer"
    participant GC as "Group Coordinator (Broker)"
    participant ZK as "__consumer_offsets topic"

    C->>GC: FindCoordinator (group.id)
    GC-->>C: Coordinator broker 주소
    C->>GC: JoinGroup
    GC->>GC: 모든 멤버 대기 (sync barrier)
    GC-->>C: JoinGroup Response (leader 선출)
    Note over C: Group Leader가 partition 할당 계산
    C->>GC: SyncGroup (할당 결과)
    GC-->>C: SyncGroup Response (내 할당)
    C->>ZK: offset commit

__consumer_offsets 내부 topic에 offset 저장
Group Leader (consumer 중 하나)가 실제 partition 할당 계산
Coordinator는 할당 결과를 모든 멤버에게 배포

Rebalancing

consumer 추가 / 제거 / 죽음 → partition 재할당:

sequenceDiagram
    autonumber
    participant C1 as "Consumer 1"
    participant C2 as "Consumer 2 (new)"
    participant Coord as "Group Coordinator"

    C1->>Coord: heartbeat
    C2->>Coord: join group
    Note over Coord: rebalance 시작
    Coord->>C1: stop fetching (revoke)
    C1->>Coord: ack + commit offset
    Coord->>C1: "new assignment (p0, p1, p2)"
    Coord->>C2: "new assignment (p3, p4, p5)"
    C1->>C1: resume fetching
    C2->>C2: start fetching

Eager vs Cooperative

	Eager (옛 기본)	Cooperative (Kafka 2.4+)
Rebalance 시	모든 consumer 정지	영향받는 partition만
처리 중단	길음 (수십 초 가능)	짧음
Throughput	하락 큼	적음
구현	RangeAssignor	CooperativeStickyAssignor

[!IMPORTANT] Cooperative rebalancing이 2026 권장 기본. partition.assignment.strategy=org.apache.kafka.clients.consumer.CooperativeStickyAssignor.

Cooperative Sticky Assignor 설정

# consumer.properties
group.id=my-consumer-group
partition.assignment.strategy=org.apache.kafka.clients.consumer.CooperativeStickyAssignor

# 또는 여러 전략 조합 (마이그레이션 시)
partition.assignment.strategy=\
  org.apache.kafka.clients.consumer.CooperativeStickyAssignor,\
  org.apache.kafka.clients.consumer.RangeAssignor

// Java 코드
Properties props = new Properties();
props.put(ConsumerConfig.GROUP_ID_CONFIG, "my-group");
props.put(ConsumerConfig.PARTITION_ASSIGNMENT_STRATEGY_CONFIG,
    CooperativeStickyAssignor.class.getName());

KafkaConsumer<String, String> consumer = new KafkaConsumer<>(props);
consumer.subscribe(List.of("orders", "payments"));

Static Membership (KIP-345)

group.instance.id=consumer-1

consumer가 동일 ID로 재접속하면 partition 유지
배포 / 재시작 시 rebalance 회피
보통 수십 초 ~ 수 분 안의 짧은 재시작 가정

flowchart LR
    C1["Consumer 1\ngroup.instance.id=c1"] -->|"재시작"| C1b["Consumer 1 (재시작)"]
    C1b -->|"동일 ID로 재접속"| GC["Group Coordinator"]
    GC -->|"partition 유지 (rebalance 없음)"| P["p0, p1 유지"]

Offset 관리

flowchart LR
    C[Consumer] -->|fetch| K[(Kafka)]
    C -->|commit| Offset["__consumer_offsets\n(internal topic)"]
    Note1["정기 commit 또는 명시적"]

모드	안전성
`enable.auto.commit=true` (기본)	중복 또는 손실 가능
명시적 sync commit	안전
명시적 async commit + 마지막 sync	balanced

Auto commit 함정

1. fetch [100, 101, 102]
2. 처리 중 ...
3. 5초 후 auto commit (103까지 commit)
4. consumer crash (102 처리 미완)
5. 재시작 → 103부터 fetch → 102 손실!

명시적 commit 패턴

while (true) {
    ConsumerRecords<String, String> records = consumer.poll(Duration.ofMillis(100));
    for (ConsumerRecord<String, String> record : records) {
        process(record);
    }
    // 배치 처리 완료 후 명시적 commit
    consumer.commitSync();
}

[!CAUTION] Auto commit은 손실 또는 중복의 함정. exactly-once가 필요하면 명시적 commit + idempotent 처리.

Exactly-once 처리 패턴

Kafka 자체의 EOS (Exactly-Once Semantics)는 Kafka → Kafka 구간만 보장. 외부 DB까지 포함하려면 추가 패턴 필요.

flowchart LR
    K[(Kafka)] -->|"fetch"| C[Consumer]
    C -->|"처리"| DB[(Database)]
    C -->|"offset commit"| K
    DB -->|"idempotency key 체크"| DB

// Transactional producer (Kafka → Kafka exactly-once)
producer.initTransactions();

try {
    producer.beginTransaction();
    producer.send(new ProducerRecord<>("output-topic", key, value));
    // offset commit을 트랜잭션에 포함
    producer.sendOffsetsToTransaction(offsets, consumerGroupMetadata);
    producer.commitTransaction();
} catch (Exception e) {
    producer.abortTransaction();
}

// DB까지 exactly-once: idempotency key 패턴
@Transactional
public void processRecord(ConsumerRecord<String, Order> record) {
    String idempotencyKey = record.topic() + "-" + record.partition() + "-" + record.offset();

    if (processedOffsets.existsByKey(idempotencyKey)) {
        return;   // 이미 처리됨
    }

    orderService.process(record.value());
    processedOffsets.save(idempotencyKey);
    // DB 트랜잭션 커밋 후 offset commit
}

Consumer Lag

flowchart LR
    Last["partition의 last offset (LEO): 1000"] --> Lag
    Curr["consumer current offset: 800"] --> Lag
    Lag["Lag = 200\nprocessing 못 따라옴"]

도구	의미
`kafka-consumer-groups.sh --describe`	즉시 확인
Kafka Lag Exporter	Prometheus 메트릭
Burrow (LinkedIn)	더 세련된 lag 분석

# lag 확인
kafka-consumer-groups.sh \
  --bootstrap-server localhost:9092 \
  --group my-consumer-group \
  --describe

# 출력 예시
GROUP           TOPIC     PARTITION  CURRENT-OFFSET  LOG-END-OFFSET  LAG
my-group        orders    0          800             1000            200
my-group        orders    1          950             1000            50

Lag 기반 Auto-Scaling

flowchart LR
    Lag["Consumer Lag"] -->|KEDA| HPA["Kubernetes HPA"]
    HPA --> Scale["Consumer pod 수 증가"]

KEDA가 Kafka lag을 Kubernetes HPA 지표로 사용. spike 자동 흡수.

# KEDA ScaledObject
apiVersion: keda.sh/v1alpha1
kind: ScaledObject
metadata:
  name: kafka-consumer-scaler
spec:
  scaleTargetRef:
    name: order-consumer
  minReplicaCount: 1
  maxReplicaCount: 10   # partition 수 이하로
  triggers:
    - type: kafka
      metadata:
        bootstrapServers: kafka:9092
        consumerGroup: my-consumer-group
        topic: orders
        lagThreshold: "100"   # lag 100 이상이면 scale out

Heartbeat / Session

설정	의미	기본
`session.timeout.ms`	이 시간 heartbeat 없으면 죽었다고 판단	45s
`heartbeat.interval.ms`	heartbeat 보내는 주기	3s
`max.poll.interval.ms`	poll 사이 최대 시간	5min

[!WARNING] max.poll.interval.ms 초과 = consumer 추방. 처리 시간이 길면 명시적 늘림 또는 워커 별도 스레드.

Consumer Group 성능 튜닝

설정	기본	권장 (고처리량)
`fetch.min.bytes`	1	1024 (배치 효율)
`fetch.max.wait.ms`	500ms	500ms
`max.poll.records`	500	100~500 (처리 시간에 따라)
`max.partition.fetch.bytes`	1MB	1MB
`enable.auto.commit`	true	false (명시적 commit)

# 고처리량 consumer 설정
fetch.min.bytes=1024
fetch.max.wait.ms=500
max.poll.records=200
enable.auto.commit=false
auto.offset.reset=earliest

흔한 함정

[!WARNING]

Rebalancing 폭주 = consumer 자주 추가/제거 → 처리 정지 반복. cooperative + static membership.

auto.offset.reset=latest + 다운 = 다운 사이 메시지 손실. 보통 earliest.

너무 큰 batch = max.poll.records 너무 큼 → 처리 시간 길어 추방.

상태 있는 consumer + rebalance = partition이 다른 consumer로 가면서 처리 진행 정보 손실. 상태는 외부 store에.

partition 수 < consumer 수 = 초과 consumer는 idle. partition 수를 consumer 최대 수 이상으로 설정.

[Distributed] Message Broker 비교: Kafka / RabbitMQ / NATS / SQS / Redis Streams

koa (김신건) — Tue, 14 Jul 2026 00:00:00 GMT

정의

Message Broker = 생산자(Producer)와 소비자(Consumer) 사이에서 메시지를 중계하는 미들웨어. 비동기 통신, 부하 분산, 시스템 디커플링의 핵심.

결정 트리

flowchart TD
    Q1{"사용 패턴"}
    Q1 -->|"event log + replay"| Kafka[Kafka]
    Q1 -->|"복잡 라우팅 + task queue"| Rabbit[RabbitMQ]
    Q1 -->|"마이크로서비스 가벼움"| NATS[NATS]
    Q1 -->|"AWS managed + 단순 큐"| SQS[SQS]
    Q1 -->|"Redis 위 fan-out / 짧은 큐"| RedisS[Redis Streams]
    Q1 -->|"레거시 JMS / 엔터프라이즈"| AMQ[ActiveMQ]
    Q1 -->|"클라우드 native pub-sub"| GCP["Google Pub/Sub"]

6가지 broker 매트릭스

항목	Kafka	RabbitMQ	NATS	SQS	Redis Streams	ActiveMQ
모델	log	exchange-queue	subject pub-sub	queue	log	queue/topic
영속	항상	옵션	옵션 (JS)	항상	옵션	항상
Throughput	수백만/s	수만/s	수백만/s	거의 무한	수십만/s	수만/s
Latency	중간 (ms)	낮음	마이크로초	수십 ms	낮음	낮음
운영 복잡도	높음	중간	낮음	없음	낮음	중간
라우팅	partition by key	exchange 패턴	subject 계층	FIFO/standard	consumer group	topic/queue
Re-play	자유 (offset)	한 번만	JS 가능	DLQ만	가능 (XREAD)	제한적
학습 곡선	높음	중간	낮음	낮음	낮음	중간
프로토콜	자체	AMQP 0-9-1	NATS	HTTP/SQS	RESP	AMQP/OpenWire

브로커별 아키텍처

Kafka: Log 모델

flowchart LR
    P1[Producer 1] --> T["Topic: orders\n(6 partitions)"]
    P2[Producer 2] --> T
    T --> P0["Partition 0\noffset 0,1,2..."]
    T --> P1b["Partition 1\noffset 0,1,2..."]
    T --> P2b["Partition 2\noffset 0,1,2..."]
    P0 --> CG1["Consumer Group A\nConsumer 1"]
    P1b --> CG1
    P2b --> CG2["Consumer Group B\nConsumer 1"]
    P0 --> CG2

메시지는 삭제되지 않음 (retention 기간 동안)
여러 Consumer Group이 독립적으로 같은 topic 소비
offset으로 임의 시점 replay 가능

RabbitMQ: Exchange-Queue 모델

flowchart LR
    P[Producer] --> EX["Exchange\n(direct/fanout/topic/headers)"]
    EX -->|"routing key: order.created"| Q1["Queue: order-processor"]
    EX -->|"routing key: order.*"| Q2["Queue: audit-log"]
    EX -->|"fanout"| Q3["Queue: notification"]
    Q1 --> C1[Consumer 1]
    Q2 --> C2[Consumer 2]
    Q3 --> C3[Consumer 3]

Exchange 타입: direct (정확 매칭), fanout (브로드캐스트), topic (패턴), headers
메시지는 소비 후 삭제 (기본)
복잡한 라우팅 로직을 브로커가 처리

처리량 / 지연 / 운영비용 (직관)

ActiveMQ 상세

ActiveMQ (Apache)는 JMS(Java Message Service) 표준을 구현한 전통적인 엔터프라이즈 메시지 브로커.

항목	ActiveMQ Classic	ActiveMQ Artemis
프로토콜	OpenWire, AMQP, STOMP, MQTT	AMQP, STOMP, MQTT, OpenWire
성능	중간	Classic보다 높음
아키텍처	단일 브로커	고성능 비동기 코어
권장	레거시 유지	신규 프로젝트

<!-- Spring Boot + ActiveMQ Artemis -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-artemis</artifactId>
</dependency>

spring:
  artemis:
    mode: native
    host: localhost
    port: 61616
    user: admin
    password: admin

[!IMPORTANT] ActiveMQ는 JMS 기반 레거시 시스템 통합에 적합. 신규 마이크로서비스 아키텍처에서는 Kafka (이벤트 스트리밍) 또는 NATS (경량 pub-sub)를 권장.

시나리오별 추천

시나리오	추천	이유
Event sourcing (큰 로그)	Kafka	retention + replay
마이크로서비스 commands	NATS 또는 RabbitMQ	낮은 지연, 라우팅
AWS Lambda + 큐	SQS	managed, Lambda trigger
Sidekiq 같은 Ruby job queue	Redis (list 기반)	단순, 빠름
실시간 채팅 fan-out	NATS 또는 Redis Pub/Sub	마이크로초 지연
CDC (DB → search)	Kafka + Debezium	log 기반 변경 감지
트래픽 spike 자동 흡수	SQS (managed)	무한 확장
빠른 MVP / startup	Redis Streams	이미 Redis 쓰면 추가 비용 없음
레거시 JMS 통합	ActiveMQ	JMS 표준 준수
복잡한 라우팅 규칙	RabbitMQ	exchange 패턴

메시지 보장 비교

Broker	At-most-once	At-least-once	Exactly-once
Kafka	옵션	기본	EOS 가능
RabbitMQ	옵션	persistent + ack	외부 idempotency 필요
NATS Core	기본	-	-
NATS JS	-	기본	옵션
SQS	-	기본	FIFO + 5분 dedup
Redis Streams	-	XACK로	외부 idempotency
ActiveMQ	옵션	persistent + ack	XA 트랜잭션

[!IMPORTANT] Exactly-once는 broker 내부에서만 의미 있음. *외부 시스템 (DB, API)*까지 완벽한 exactly-once는 불가능. idempotency + outbox가 현실적 정답. 자세한 건 [[outbox-pattern]], [[idempotency-keys]].

영속 / 재처리 비교

flowchart TD
    Kafka["Kafka\ndays~weeks retention\n임의 offset replay"]
    Rabbit["RabbitMQ\nqueue 안의 메시지\n소비 = 사라짐"]
    Nats["NATS JS\nretention 정책\n임의 시점 replay"]
    Sqs["SQS\n최대 14일\n한 번 소비 = 사라짐"]
    Stream["Redis Streams\nMAXLEN만큼\n임의 offset"]
    AMQ["ActiveMQ\nKahaDB / journal\n재처리 제한적"]

마이그레이션 비용

출발	도착	비용
Sidekiq (Redis)	Kafka	큼 (consumer group, exactly-once 재설계)
RabbitMQ	Kafka	중간 (라우팅 → topic 재설계)
Kafka	NATS	작음 (둘 다 log)
ActiveMQ	RabbitMQ	작음 (둘 다 AMQP)
ActiveMQ	Kafka	큼 (JMS → Kafka API 전면 교체)
자체 호스팅	Managed	작음 (운영 측면 큰 이득)

운영자 시점 체크리스트

체크 항목                          관련 설정
----------------------------------------------
메시지 손실 허용?              acks, persistent, ack 정책
순서 보장 필요?                partition key, FIFO
재처리 가능?                   offset / position
DLQ + parking lot             실패 메시지 격리
Backpressure                  prefetch, max-in-flight
Monitoring                    lag, dead messages, throughput
Consumer auto-scaling         lag 기반 (KEDA)
Schema registry               Avro/Protobuf 스키마 진화

Dead Letter Queue (DLQ) 패턴

처리 실패 메시지를 격리해 재처리하거나 분석하는 패턴.

flowchart LR
    P[Producer] --> Q["Main Queue / Topic"]
    Q --> C[Consumer]
    C -->|"처리 실패 (N회)"| DLQ["Dead Letter Queue"]
    DLQ --> Alert["알림 / 모니터링"]
    DLQ --> Replay["수동 재처리"]

Broker	DLQ 지원
Kafka	별도 topic 수동 구현 또는 Kafka Streams
RabbitMQ	`x-dead-letter-exchange` 설정
SQS	자동 DLQ 연결 (maxReceiveCount 설정)
NATS JS	`MaxDeliver` 초과 시 별도 subject

# SQS DLQ 설정 예시 (AWS CDK)
const dlq = new sqs.Queue(this, 'DLQ');
const mainQueue = new sqs.Queue(this, 'MainQueue', {
  deadLetterQueue: {
    queue: dlq,
    maxReceiveCount: 3,   # 3회 실패 후 DLQ로
  },
});

Schema Registry와 메시지 진화

Kafka 등에서 메시지 스키마를 중앙 관리:

flowchart LR
    P[Producer] -->|"Avro/Protobuf 직렬화"| SR["Schema Registry"]
    SR -->|"schema_id 포함"| K[(Kafka)]
    K --> C[Consumer]
    C -->|"schema_id로 역직렬화"| SR

Confluent Schema Registry: Kafka 생태계 표준
AWS Glue Schema Registry: AWS 관리형
스키마 진화 규칙: backward / forward / full compatibility

흔한 함정

[!WARNING]

Kafka를 단순 큐로 쓰기: Kafka는 log 기반. 단순 task queue라면 RabbitMQ나 SQS가 더 적합.

RabbitMQ에서 replay 기대: 소비된 메시지는 사라짐. replay가 필요하면 Kafka.

NATS Core에서 영속성 기대: NATS Core는 fire-and-forget. 영속성이 필요하면 NATS JetStream.

partition 수 부족: Kafka에서 consumer 수 > partition 수면 일부 consumer idle. 처음부터 충분히 설정.

메시지 크기 과대: Kafka 기본 최대 1MB. 큰 payload는 S3에 저장 후 reference만 전송.

DLQ 모니터링 없음: DLQ에 메시지가 쌓여도 알림 없으면 데이터 손실 인지 불가.

[Distributed] Kafka: 분산 로그, partition, consumer group

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

Apache Kafka = 분산 commit log. 고처리량 (수백만 msg/s), 영속, 수평 확장. event-driven 아키텍처 의 de facto.

핵심 개념: topic = partition 들 = 노드에 분산된 append-only log.

토폴로지

flowchart TB
    P1[Producer 1] --> T1[Topic: events]
    P2[Producer 2] --> T1
    subgraph T1[Topic: events]
      Part0["partition 0<br/>(broker A)"]
      Part1["partition 1<br/>(broker B)"]
      Part2["partition 2<br/>(broker C)"]
    end
    T1 --> CG1[Consumer Group: analytics]
    T1 --> CG2[Consumer Group: search]
    CG1 --> C11[Consumer 1]
    CG1 --> C12[Consumer 2]
    CG1 --> C13[Consumer 3]
    CG2 --> C21[Consumer 1]

Partition: 핵심 단위

{}

속성	의미
Append-only	끝에만 추가
Immutable	변경 불가
Ordered	partition 안에서 순서 보장
Distributed	노드 간 분산
Replicated	RF (Replication Factor) 만큼 복제
Offset	각 메시지의 partition 내 ID

Partition 수 선택

flowchart TD
    Q{Partition 수}
    Q -->|"적음 (1-3)"| Low[병렬성 낮음<br/>순서 보장 쉬움]
    Q -->|"중간 (10-50)"| Med[일반적]
    Q -->|"많음 (100+)"| High[오버헤드 증가<br/>리밸런싱 비용]

[!IMPORTANT] Partition 수 = 한 consumer group 의 최대 병렬성. 늘리는 건 가능하지만 줄이는 건 불가. 보수적으로 시작.

Consumer Group

flowchart LR
    subgraph CG1[Consumer Group A]
        C1[Consumer 1] --> P0[part 0]
        C2[Consumer 2] --> P1[part 1]
        C3[Consumer 3] --> P2[part 2]
    end
    subgraph CG2[Consumer Group B]
        D1[Consumer 1] --> P0
        D1 --> P1
        D1 --> P2
    end

규칙	의미
한 partition → 한 consumer (group 안)	순서 보장
한 consumer → N partitions	OK
Consumer 수 > Partition 수	남는 consumer는 idle
다른 group → 독립 offset	fan-out

Offset 관리

sequenceDiagram
    C->>K: poll() (offset 100 ~)
    K-->>C: msgs [100, 101, 102]
    C->>C: 처리
    C->>K: commit offset 103
    Note over C,K: 다음 poll 부터 103 부터

모드	의미
Auto commit	주기적 자동. 최대 한 번 손실 또는 중복
Manual sync commit	처리 후 동기 commit. 정확
Manual async commit	비동기 commit. 최후 commit 실패 가능

Replication + ISR

flowchart LR
    Leader["Leader replica"] --> F1["Follower 1"]
    Leader --> F2["Follower 2"]
    Leader --> ISR{"ISR<br/>In-Sync Replica set"}
    F1 --> ISR
    F2 -.지연.-> ISR

Leader 가 모든 write 수신.
Follower 가 동기 (또는 비동기) 복제.
ISR = 충분히 따라온 replica 집합.
Leader 다운 → ISR 중 새 leader.

설정	의미
`acks=0`	응답 안 기다림 (손실 가능)
`acks=1`	leader 만 (기본)
`acks=all`	ISR 전체 (가장 안전)
`min.insync.replicas`	최소 ISR 수. 미달 시 write 거절

[!CAUTION] acks=all + min.insync.replicas=2 가 프로덕션 표준. 낮은 settings 는 운영 사고 단골.

Exactly-once Semantics (EOS)

flowchart LR
    P[Producer<br/>idempotent + transactional] --> K[Kafka]
    K --> C[Consumer<br/>read_committed]
    P -->|transactional.id| TC[Transaction Coordinator]
    C -->|isolation.level=read_committed| K

Producer idempotence: 재전송 시 중복 제거.
Transactional producer: 여러 topic write 를 원자적.
Consumer isolation.level=read_committed: aborted 트랜잭션 무시.

[!NOTE] 완벽한 EOS 는 Kafka 안에서만. Kafka → DB → Kafka 등 외부 시스템 포함 은 outbox + idempotency 패턴이 추가로 필요. 자세한 건 [[outbox-pattern]].

KRaft (Kafka Raft, ZooKeeper 제거)

flowchart LR
    subgraph Old[옛 구조]
        K1[Kafka 브로커] --> Zk[(ZooKeeper)]
    end
    subgraph New[KRaft 구조]
        K2[Kafka 브로커] -.-> Quorum[메타데이터 controller<br/>Raft 합의]
    end

2.8+ preview, 3.5+ production, 4.0+ ZK 완전 제거.
운영 단순화 + 확장성 (수백만 partition).

주요 Producer 설정

설정	기본값	권장 프로덕션	효과
`acks`	`1`	`all`	데이터 유실 방지
`batch.size`	16KB	64KB ~ 1MB	처리량 향상
`linger.ms`	`0`	`5` ~ `50`	배치 유리 (latency 조금 증가)
`compression.type`	`none`	`snappy` / `lz4`	네트워크 절약
`enable.idempotence`	`false`	`true`	중복 전송 방지
`retries`	`0`	`MAX_INT`	재시도
`max.in.flight.requests`	`5`	`1` (순서 중요 시)	순서 보장

주요 Consumer 설정

설정	기본값	설명
`auto.offset.reset`	`latest`	`earliest` 권장 (재시작 시 손실 방지)
`enable.auto.commit`	`true`	수동 commit 추천 (`false`)
`max.poll.records`	`500`	한 번에 가져올 최대 수
`fetch.min.bytes`	`1`	배치 효율 위해 늘림
`session.timeout.ms`	`45000`	consumer 죽었다고 판단하는 시간

처리량 최적화 결정 트리

flowchart TD
    Q["처리량 부족?"]
    Q --> A1{"Producer 측?"}
    A1 -->|"Yes"| P1["batch.size 늘리기<br/>linger.ms=5~50<br/>compression 추가"]
    A1 -->|"No"| A2{"Consumer 측?"}
    A2 -->|"Yes"| P2["partition 수 늘리기<br/>consumer 수 늘리기<br/>max.poll.records 조정"]
    A2 -->|"No"| A3{"Broker 측?"}
    A3 -->|"Yes"| P3["브로커 추가<br/>replication factor 검토<br/>log.flush 설정"]

Kafka Streams 개요

Kafka 위에서 실시간 스트림 처리. 별도 클러스터 불필요.

StreamsBuilder builder = new StreamsBuilder();
KStream<String, String> orders =
    builder.stream("orders-topic");

// 필터 + 변환
orders
    .filter((key, val) -> val.contains("status=PAID"))
    .mapValues(val -> enrich(val))
    .to("paid-orders-topic");

KafkaStreams streams = new KafkaStreams(builder.build(), config);
streams.start();

개념	설명
KStream	무한 레코드 스트림
KTable	최신 값만 유지 (changelog)
GlobalKTable	전체 파티션 로컬 복사
Topology	처리 그래프
State Store	로컬 RocksDB (조인/집계)

모니터링 핵심 지표

flowchart LR
    subgraph Producer
        PR1["records-sent-rate<br/>초당 전송 건수"]
        PR2["record-error-rate<br/>전송 실패율"]
    end
    subgraph Consumer
        CR1["consumer-lag<br/>파티션별 미처리 수"]
        CR2["records-consumed-rate<br/>초당 소비 건수"]
    end
    subgraph Broker
        BR1["UnderReplicatedPartitions<br/>복제 따라가지 못한 수"]
        BR2["ActiveControllerCount<br/>1 이어야 함"]
    end

[!WARNING] consumer-lag 이 지속 증가 = consumer 처리 속도 부족. 파티션/consumer 수 증설 또는 처리 로직 최적화.

Kafka 의 적합 / 부적합

적합	부적합
Event sourcing	작은 데이터 (RabbitMQ 가 단순)
로그 수집	request-reply (가능하지만 어색)
Stream processing	1-N 즉시 fan-out (Pub/Sub 가 간단)
CDC (Change Data Capture)	짧은 retention task queue (Sidekiq 가 적합)

흔한 함정

[!WARNING]

Partition 수 부족 = 병렬성 제한. 늘리는 건 가능하지만 기존 키 분포 깨짐.

Rebalancing 폭주 = consumer 가 자주 join/leave → 모든 consumer 정지 후 재할당. cooperative rebalancing (Kafka 2.4+) 으로 완화.

Hot partition = key 선택 잘못 → 한 partition 만 트래픽. key 디자인 재검토.

auto.offset.reset=latest = consumer 가 죽었다 살아나면 그동안 메시지 손실. 보통 earliest.

[Pattern] CQRS: Command / Query 분리, read model

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

CQRS (Command Query Responsibility Segregation) = 쓰기 모델 과 읽기 모델 을 분리. 같은 데이터를 다른 형태 로 저장 / 조회.

[!IMPORTANT] CQRS 는 쓰기 / 읽기 모델 분리 라는 추상 패턴. 반드시 다른 DB 일 필요는 없다. 대부분 시작 단계는 같은 DB + 다른 모델.

동기

flowchart LR
    Trad[전통 CRUD]
    Trad --> ProbW[복잡한 비즈니스 로직 + 정규화 DB]
    Trad --> ProbR[복잡한 join 으로 화면 그리기]
    CQRS[CQRS]
    CQRS --> Write[Write: 정규화, 트랜잭션, 비즈니스 규칙]
    CQRS --> Read[Read: 화면 친화, denormalized, 빠른 조회]

CRUD 의 읽기 / 쓰기 사용 패턴이 매우 다른 워크로드 (대시보드, 추천, 검색) 에서 효과적.

기본 구조

flowchart TB
    Cmd[Command<br/>CreateOrder, ConfirmOrder] --> CH[Command Handler]
    CH --> WM[(Write Model<br/>정규화, 트랜잭션)]
    WM -->|event| EH[Event Handler / Projection]
    EH --> RM[(Read Model<br/>denormalized, optimized)]
    Query[Query<br/>GetOrderSummary] --> QH[Query Handler]
    QH --> RM

항목	Command Side	Query Side
입력	비즈니스 의도 (Command)	정보 요청 (Query)
검증	비즈니스 규칙	권한만
결과	변경 사실 (성공/실패)	데이터
모델	정규화 (3NF)	denormalized
DB	RDB 가 일반	다양 (RDB, ES, Redis)
일관성	강	보통 eventual

예시: 전자상거래

-- Write Model (정규화)
TABLE orders (id, user_id, status, ...);
TABLE order_items (id, order_id, product_id, qty, price);
TABLE products (id, name, ...);

-- Read Model (denormalized, 화면 친화)
TABLE order_summary_view (
  order_id, user_name, total, item_count,
  status_label, created_at, items_json
);

읽기 1 쿼리:

SELECT * FROM order_summary_view WHERE order_id = ?;

쓰기 - 정상 트랜잭션 + event 발행:

BEGIN;
INSERT INTO orders ...;
INSERT INTO order_items ...;
INSERT INTO outbox (event) VALUES ('OrderCreated', ...);
COMMIT;

이후 event handler 가 order_summary_view 갱신.

Event Sourcing 과 자주 같이

flowchart LR
    Cmd[Command] --> Agg[Aggregate]
    Agg -->|emit event| ES[(Event Store)]
    ES -->|project| V1[(Read View 1)]
    ES -->|project| V2[(Read View 2)]
    ES -->|project| V3[(Read View 3)]
    Query --> V1 & V2 & V3

자세한 건 [[event-sourcing]].

Read Model 종류

Read Model	적합
Materialized view (DB)	같은 RDB 안
ElasticSearch / OpenSearch	검색 + aggregation
Redis	작은 hot data
Cassandra	시계열 / 대용량
GraphQL cache	API 응답 캐시
클라이언트 IndexedDB	offline-first

Eventual Consistency

sequenceDiagram
    User->>API: POST /orders (command)
    API->>WriteDB: INSERT
    WriteDB-->>API: OK
    API-->>User: 200 OK (order_id)
    Note over API,ReadDB: 비동기 projection 진행
    User->>API: GET /orders/123 (query)
    API->>ReadDB: SELECT
    ReadDB-->>API: NOT FOUND? (projection lag)

[!CAUTION] 방금 만든 주문이 안 보이는 UX 함정. 해결책:

짧은 lag (수 ms) 보장 + UI 가 낙관적 표시

write 후 즉시 같은 transaction 으로 read 시 write DB 우회

작성자 본인은 강 일관성, 다른 사람은 eventual (read-your-writes)

언제 CQRS? (안 쓸 때가 더 많다)

flowchart TD
    Q1{비즈니스 도메인 복잡?}
    Q1 -->|아니오| Simple[CRUD 충분]
    Q1 -->|예| Q2{읽기 / 쓰기 패턴 매우 다름?}
    Q2 -->|아니오| Simple
    Q2 -->|예| Q3{팀이 ES + 분산 시스템 이해?}
    Q3 -->|아니오| Risk[학습 비용 큼 → 천천히]
    Q3 -->|예| CQRS[CQRS 시작]

[!IMPORTANT] 대부분의 앱은 CQRS 가 과한 솔루션. 진짜 도움 되는 곳 (큰 e-commerce, 트레이딩 시스템, 큰 SaaS 대시보드) 가 아니면 모듈 모놀리스 + 일부 read model 정도면 충분.

단순 CQRS (가벼운 형태)

flowchart LR
    Cmd[Command Handler<br/>POST /orders] --> Write[(DB)]
    Write -->|trigger / event| Mat[Materialized View<br/>갱신]
    Query[Query Handler<br/>GET /orders/dashboard] --> Mat

같은 DB.
materialized view 또는 summary table.
별도 인프라 없이 80% 의 효과.

Projection 구현 패턴

projection 은 write model 의 event 를 소비해 read model 을 갱신하는 컴포넌트다. 구현 방법은 크게 3 가지.

1. Synchronous (트랜잭션 내)

BEGIN;
  INSERT INTO orders (...) VALUES (...);
  INSERT INTO order_items (...) VALUES (...);
  -- 같은 트랜잭션에서 read model 도 갱신
  INSERT INTO order_summary_view (order_id, user_name, total, ...)
    SELECT o.id, u.name, SUM(oi.price * oi.qty), ...
    FROM orders o
    JOIN users u ON o.user_id = u.id
    JOIN order_items oi ON oi.order_id = o.id
    WHERE o.id = NEW.id
    GROUP BY o.id, u.name;
COMMIT;

장점: 즉각적 일관성, read-your-writes 문제 없음.
단점: write latency 증가, read model 이 여러 개면 트랜잭션 커짐.

2. Asynchronous (outbox + event bus)

orders 테이블 INSERT
  → outbox 에 OrderCreated event INSERT (같은 트랜잭션)
  → outbox relay 가 Kafka/NATS 에 발행
  → projection consumer 가 구독 → read model 갱신

장점: write path 가 가볍다, read model 독립 배포 가능.
단점: projection lag 발생, idempotency 필수.

3. Catch-up (재구성)

# event store 를 처음부터 재생 → read model 처음부터 재구성
projection rebuild --from-event-store --target order_summary_view

event sourcing 을 쓸 때 강점.
새 read model 추가, 버그 수정 후 재계산에 유용.

Idempotent Projection

projection 은 반드시 idempotent 이어야 한다. 같은 event 가 두 번 들어와도 결과가 같아야 함.

-- upsert 패턴
INSERT INTO order_summary_view (order_id, total, status, updated_at)
VALUES (:order_id, :total, :status, :ts)
ON CONFLICT (order_id)
DO UPDATE SET
  total      = EXCLUDED.total,
  status     = EXCLUDED.status,
  updated_at = EXCLUDED.updated_at
WHERE order_summary_view.updated_at < EXCLUDED.updated_at;  -- 순서 보장

updated_at 비교로 out-of-order event 도 안전하게 처리.
자세히는 [[idempotency-keys]].

흔한 함정

[!WARNING]

모든 곳에 CQRS = 단순 CRUD 도 분리. 복잡도 폭증.

Projection 동기 실행 = read model 갱신이 write 막음. async + idempotent.

Read-your-writes 무시 = 사용자가 방금 한 일을 못 봄 UX.

Read model 재구성 어려움 = event log 없으면 replay 불가. ES + CQRS 가 자주 묶이는 이유.

Projection 스키마 변경 = 기존 event 로 재구성 가능한지 확인 필요.

테스트 전략

레이어	테스트 대상	도구
Command Handler	비즈니스 규칙, 검증, event 발행	단위 테스트
Projection	idempotency, 특정 event sequence 후 상태	단위 테스트
Read Model	쿼리 결과, 인덱스	통합 테스트
End-to-End	eventual consistency 타이밍	통합/E2E

eventual consistency E2E: awaitility (Java) 같은 polling assertion 사용.

[Pattern] Event Sourcing: 상태 대신 이벤트 누적

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

Event Sourcing = 현재 상태 대신 과거 이벤트 시퀀스 를 저장. 현재 상태 = event 모두 replay 한 결과.

전통: state = { balance: 100 }
ES:   events = [Deposited(50), Deposited(60), Withdrawn(10)]
      state = events.reduce(apply) = { balance: 100 }

핵심 약속

과거 모든 변화 기록. 감사 / 디버깅 / 시간 여행 자유.
읽기 모델 자유 (어떻게든 projection).
replay 로 새 view 생성 (옛 데이터에서 새 통찰).
비파괴. 옛 이벤트는 불변.

구조

flowchart LR
    Cmd[Command<br/>Deposit 50] --> Agg[Aggregate]
    Agg -->|emit| Event["Deposited(50)"]
    Event --> Store[(Event Store<br/>append-only)]
    Store -->|project| V1[(Balance View)]
    Store -->|project| V2[(Audit View)]
    Store -->|project| V3[(Search View)]

Event Store

이벤트 = 불변 사실. 형식:

{
  "event_id": "evt_abc",
  "aggregate_id": "account_42",
  "aggregate_type": "Account",
  "event_type": "Deposited",
  "version": 5,
  "payload": { "amount": 50, "currency": "USD" },
  "metadata": { "user_id": "...", "correlation_id": "..." },
  "occurred_at": "2026-06-25T12:00:00Z"
}

Store	특징
Kafka	log + retention
EventStoreDB	ES 전용
PostgreSQL	append-only 테이블 + outbox
DynamoDB	partition key = aggregate_id
Axon	Java 프레임워크

Replay (재계산)

sequenceDiagram
    autonumber
    participant App
    participant Store as Event Store
    App->>Store: load events for aggregate_id=42
    Store-->>App: [e1, e2, e3, e4, e5]
    App->>App: state = e1.apply(empty)<br/>state = e2.apply(state)<br/>...
    Note over App: state 복원 완료

Snapshot

이벤트 수 만이면 replay 가 느림. 주기적 snapshot 저장:

flowchart LR
    Store[(Event Store)] --> Snap[(Snapshot Store)]
    Note1["Snapshot at version 1000:<br/>{ balance: 5000 }"]
    Load[Load aggregate] --> Snap
    Snap -->|version 1000 부터| Replay[event 1001 ~ 현재 replay]

def load_aggregate(id):
    snapshot = snapshot_store.latest(id)
    events = event_store.from_version(id, snapshot.version)
    state = snapshot.state
    for e in events:
        state = e.apply(state)
    return state

CQRS 와의 자연 결합

flowchart TB
    Cmd --> Write[Write side]
    Write --> Store[(Event Store)]
    Store -->|stream| P1[Projection 1] --> View1[(Read View 1)]
    Store -->|stream| P2[Projection 2] --> View2[(Read View 2)]
    Store -->|stream| P3[Projection 3] --> View3[(Read View 3)]
    Query --> View1 & View2 & View3

자세한 건 [[cqrs]].

새 View 추가

기존 데이터에서 새 인사이트 가 필요할 때:

sequenceDiagram
    Dev->>Code: 새 projection 함수 추가
    Code->>Store: from version 0 부터 replay
    Store-->>Code: 모든 이벤트
    Code->>NewView: 새 view 채우기 (수 시간 ~ 일)
    Note over Code,NewView: 이후 실시간 stream 으로 유지

[!IMPORTANT] 이게 ES 의 가장 큰 매력. 과거에 안 묻던 질문 을 나중에 데이터로 만들 수 있다.

적합 / 부적합

flowchart TD
    Good[적합]
    Good --> G1["감사 추적 필수 (금융, 의료)"]
    Good --> G2[과거 시점 상태 조회]
    Good --> G3["복잡 비즈니스 (주문 흐름)"]
    Good --> G4[CQRS 가 자연스러운 도메인]
    Bad[부적합]
    Bad --> B1[단순 CRUD]
    Bad --> B2["GDPR 의 *잊혀질 권리* (이벤트 불변과 충돌)"]
    Bad --> B3[빠른 prototype]

함정: 이벤트 진화

v1: Deposited(amount: int)
v2: Deposited(amount: int, currency: string)   ← currency 추가

옛 이벤트는 currency 가 없다. 처리 시:

전략	의미
Default value	옛 이벤트에 currency=“USD” 가정
Up-cast	load 시 옛 → 새 형태로 변환
Lazy migration	처리 시점에 보강
Re-write event (안 권장)	불변 원칙 위반

flowchart TD
    Q["GDPR: 사용자 데이터 삭제 요구"]
    Q --> Issue["ES: 이벤트는 불변 → 어떻게 지움?"]
    Issue --> S1["1. Crypto-shredding: 개인정보 암호화, key 만 삭제"]
    Issue --> S2["2. Event redaction: 특정 필드 null 처리"]
    Issue --> S3["3. 별도 저장: 개인정보는 가변 DB, 이벤트는 reference"]

Aggregate 설계 원칙

원칙	의미
단일 트랜잭션 경계	Aggregate 안에서만 불변식 보장
작게 유지	한 개 Aggregate = 한 개 Entity + 직접 소유 ValueObject
다른 Aggregate 는 ID 참조	직접 참조 금지
Eventually consistent	Aggregate 간 일관성은 eventual

flowchart LR
    subgraph Order["Order Aggregate"]
        O[Order] --> L1[OrderLine]
        O --> L2[OrderLine]
        O --> Addr[ShippingAddress]
    end
    subgraph Customer["Customer Aggregate (별개)"]
        C[Customer]
    end
    O -.->|"customerId (ID 참조)"| C

Command vs Event 구분

flowchart LR
    Cmd["Command<br/>(의도, 거절 가능)"]
    Evt["Event<br/>(사실, 불변)"]
    Agg[Aggregate]
    Cmd -->|"validate + apply"| Agg
    Agg -->|"emit"| Evt
    Evt -->|"append"| Store[(Event Store)]

구분	Command	Event
형식	`PlaceOrder`	`OrderPlaced`
시제	현재/미래	과거
거절 가능?	Yes (validation)	No (이미 발생)
저장	저장 안 함 (보통)	영구 저장

Projection 전략

flowchart TB
    Store[(Event Store)] -->|"event stream"| P1[Projection Worker 1]
    Store -->|"event stream"| P2[Projection Worker 2]
    P1 -->|"upsert"| V1[("잔액 View")]
    P2 -->|"upsert"| V2[("거래 내역 View")]
    P1 -->|"checkpoint"| CP1[("checkpoint 1")]
    P2 -->|"checkpoint"| CP2[("checkpoint 2")]

checkpoint: 마지막으로 처리한 event version. 재시작 시 여기서 재개.
eventual consistency: projection 이 약간 뒤처짐 허용.

이벤트 스키마 진화 전략

전략	설명	추천
Default value	신규 필드에 기본값 삽입	단순 추가 시
Up-cast	로드 시 구버전 → 신버전 변환	필드 이름 변경
Weak schema	JSON + 필드 검사 코드에서	스키마 불안정
Re-write (비권장)	옛 이벤트 수정	불변 원칙 위반

# Up-cast 예시
class DepositedV1ToV2:
    def upcast(self, event: dict) -> dict:
        if event['version'] == 1:
            event['payload']['currency'] = 'USD'   # 기본값 보강
            event['version'] = 2
        return event

테스트 전략

# Given-When-Then 패턴 (이벤트 기반)
def test_withdraw_sufficient_funds():
    # Given: 과거 이벤트로 상태 세팅
    account = Account.from_events([
        Deposited(amount=200),
        Deposited(amount=100),
    ])

    # When: 커맨드 실행
    events = account.withdraw(50)

    # Then: 발행 이벤트 검증
    assert len(events) == 1
    assert isinstance(events[0], Withdrawn)
    assert events[0].amount == 50

def test_withdraw_insufficient_funds():
    account = Account.from_events([Deposited(amount=30)])
    with pytest.raises(InsufficientFundsError):
        account.withdraw(50)

[!TIP] ES 테스트의 핵심: DB 없이 이벤트 리스트만으로 Aggregate 를 만들고 검증. 매우 빠른 단위 테스트 가능.

흔한 함정

[!WARNING]

모든 도메인에 ES = 단순 CRUD 까지 복잡 모델. 진짜 도메인 가치 있는 곳에만.

이벤트 schema 영구 보존 안 함 = 1년 뒤 옛 이벤트 해석 불가. 스키마 진화 정책.

이벤트 크기 폭증 = 작은 이벤트 + 정기 snapshot. 큰 binary 는 reference.

Aggregate 경계 잘못 = aggregate 가 너무 크면 concurrent write 충돌, 너무 작으면 일관성 사라짐.

[Pattern] Idempotency Keys: 중복 요청 안전 처리

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

Idempotency = 같은 요청을 N번 보내도 결과가 1번과 동일. 분산 시스템 / 결제 / API 의 안전망.

[!IMPORTANT] 네트워크는 항상 timeout / retry. 진짜 exactly-once 는 불가능 → at-least-once + idempotent 가 현실적 정답.

HTTP 의 idempotent method

Method	Idempotent
GET	O
HEAD	O
OPTIONS	O
PUT	O
DELETE	O
POST	X (기본)
PATCH	X (대개)

POST 의 비-멱등성 이 결제 중복 같은 사고의 근원.

Idempotency-Key Header

Stripe / Square / PayPal 등이 표준화:

POST /v1/charges HTTP/1.1
Authorization: Bearer sk_...
Idempotency-Key: 7f4d8e2a-c-3a-4e-9f-1234567890ab
Content-Type: application/json

{"amount": 5000, "currency": "usd", "customer": "cus_..."}

서버 응답:

1번째 호출: 200 OK (실제 처리)
2번째 호출 (같은 key): 200 OK (옛 응답 그대로)

서버 구현

sequenceDiagram
    autonumber
    participant Client
    participant API
    participant Store as Idempotency Store
    participant DB

    Client->>API: POST + Idempotency-Key: abc
    API->>Store: GET key abc
    alt 처음
        Store-->>API: not found
        API->>Store: SET key abc IN_PROGRESS
        API->>DB: 실제 처리
        DB-->>API: 결과
        API->>Store: SET key abc COMPLETED + 응답
        API-->>Client: 응답
    else 옛 응답 있음
        Store-->>API: COMPLETED + 옛 응답
        API-->>Client: 같은 옛 응답 (실제 처리 없음)
    else 진행 중
        Store-->>API: IN_PROGRESS
        API-->>Client: 409 Conflict (같은 key 중복)
    end

def idempotent_post(key, request, handler):
    cached = store.get(key)
    if cached and cached.status == "completed":
        return cached.response

    if cached and cached.status == "in_progress":
        raise Conflict("Same key in progress")

    store.set(key, "in_progress", ttl=24*3600)
    try:
        response = handler(request)
        store.set(key, "completed", response=response, ttl=24*3600)
        return response
    except Exception:
        store.delete(key)   # 또는 "failed" 로 표시
        raise

Store 선택

Store	적합
Redis	빠름, TTL 자동
PostgreSQL	트랜잭션 친화
DynamoDB	분산 + TTL

[!TIP] PostgreSQL 의 UNIQUE constraint + ON CONFLICT 가 가장 단순. 결제 같이 강한 일관성 필요할 때.

CREATE TABLE idempotency_keys (
  key TEXT PRIMARY KEY,
  request_hash BYTEA NOT NULL,
  response JSONB,
  status TEXT,
  expires_at TIMESTAMPTZ
);

INSERT INTO idempotency_keys (key, request_hash, status)
VALUES (?, ?, 'in_progress')
ON CONFLICT (key) DO NOTHING
RETURNING ...;

Request Hashing (재시도 안전)

def request_hash(req):
    return sha256(req.method + req.url + req.body).hexdigest()

같은 key + 다른 body = 수상. 거절 (400) 또는 옛 응답.
같은 key + 같은 body = 재시도. 옛 응답.

TTL 정책

기간	적합
24시간	Stripe 표준
7일	더 안전
영구	결제처럼 극한 안전

짧으면 재시도 보호 부족. 길면 store 부담.

분산 / 큐의 idempotency

flowchart LR
    P[Producer] -->|publish + msg_id| Broker
    Broker --> C[Consumer]
    C -->|이미 처리?| Inbox[(Inbox table)]
    Inbox -->|YES| Skip
    Inbox -->|NO| Process[처리 + 기록]

자세한 건 [[outbox-pattern]] 의 Inbox.

멱등한 작업 만드는 패턴

작업	멱등으로 만드는 방법
이메일 발송	deduplication store + 발송 전 체크
DB INSERT	UNIQUE constraint + ON CONFLICT
계좌 송금	transaction_id 컬럼 + UNIQUE
Webhook 수신	event_id + 처리 표시
API 호출	Idempotency-Key 헤더

흔한 함정

[!WARNING]

클라이언트가 매번 새 key 생성 = idempotency 의미 없음. retry 시 같은 key 재사용.

key 충돌 = UUID v4 사용. 클라이언트 라이브러리가 자동 생성.

TTL 너무 짧음 = 24시간 뒤 재시도 시 중복 처리.

in-progress 처리 = 그동안 동일 key 가 또 오면 대기 vs 거절 정책. 보통 409.

Key 생성 전략


// 클라이언트에서 생성 (가장 일반적)
const idempotencyKey = uuidv4();   // 무작위, 충돌 거의 없음

// 결정론적 key (UUID v5 = namespace + 입력의 SHA-1)
const NAMESPACE = '6ba7b810-9dad-11d1-80b4-00c04fd430c8';
const key = uuidv5(`payment:${userId}:${orderId}:${amount}`, NAMESPACE);
// 같은 입력이면 항상 같은 key = 재시도 시 동일 key 재사용 가능

방식	장점	단점
UUID v4 (랜덤)	간단, 충돌 거의 없음	재시작 시 새 key 생성됨
UUID v5 (해시)	결정론적, 재시도 가능	namespace 관리 필요
`${requestId}`	직관적	클라이언트 구현 필요

[!WARNING] 클라이언트가 retry 마다 새 key 를 생성 = idempotency 의미 없음. retry 시 반드시 같은 key 재사용.

클라이언트 구현 패턴

// Axios interceptor: 자동 idempotency-key 추가


const api = axios.create({ baseURL: '/api' });

api.interceptors.request.use(config => {
    const method = config.method?.toLowerCase() ?? '';
    if (['post', 'patch', 'put'].includes(method)) {
        // ??= 로 retry 시 같은 key 유지
        config.headers['Idempotency-Key'] ??= uuidv4();
    }
    return config;
});

# Python + httpx + tenacity retry
import httpx, uuid
from tenacity import retry, stop_after_attempt, wait_exponential

@retry(stop=stop_after_attempt(3), wait=wait_exponential(min=1, max=10))
def charge(amount: int, key: str | None = None):
    key = key or str(uuid.uuid4())
    # retry 할 때 외부에서 key 를 넘겨야 같은 key 재사용
    response = httpx.post(
        '/v1/charges',
        json={'amount': amount},
        headers={'Idempotency-Key': key},
        timeout=30,
    )
    response.raise_for_status()
    return response.json()

# 올바른 재시도: key 를 먼저 생성 후 함수에 전달
key = str(uuid.uuid4())
result = charge(5000, key=key)

Idempotency 라이프사이클

flowchart TD
    A["클라이언트: key 생성 (UUID v4)"] --> B["요청 전송"]
    B --> C{"Store 조회"}
    C -->|"없음"| D["IN_PROGRESS 저장"]
    D --> E["비즈니스 로직 실행"]
    E -->|"성공"| F["COMPLETED + 응답 저장"]
    E -->|"실패"| G["DELETE or FAILED 저장"]
    F --> H["응답 반환"]
    G --> I["에러 반환, 재시도 가능"]
    C -->|"COMPLETED"| J["캐시된 응답 즉시 반환"]
    C -->|"IN_PROGRESS"| K["409 Conflict 반환"]
    B2["재시도 (같은 key)"] --> C

테스트 전략

import pytest

class TestIdempotency:
    def test_first_call_processes(self, client):
        key = "test-key-1"
        res = client.post('/charges', json={'amount': 100},
                          headers={'Idempotency-Key': key})
        assert res.status_code == 200
        assert res.json()['id'] is not None

    def test_retry_returns_same_response(self, client):
        key = "test-key-2"
        res1 = client.post('/charges', json={'amount': 100},
                           headers={'Idempotency-Key': key})
        res2 = client.post('/charges', json={'amount': 100},
                           headers={'Idempotency-Key': key})
        # 응답 동일
        assert res1.json()['id'] == res2.json()['id']
        # DB 에 결제 1건만
        assert count_charges() == 1

    def test_different_keys_create_different_charges(self, client):
        res1 = client.post('/charges', json={'amount': 100},
                           headers={'Idempotency-Key': 'key-A'})
        res2 = client.post('/charges', json={'amount': 100},
                           headers={'Idempotency-Key': 'key-B'})
        assert res1.json()['id'] != res2.json()['id']
        assert count_charges() == 2

    def test_body_mismatch_same_key_returns_400(self, client):
        key = "test-key-3"
        client.post('/charges', json={'amount': 100},
                    headers={'Idempotency-Key': key})
        res = client.post('/charges', json={'amount': 999},
                          headers={'Idempotency-Key': key})
        # 같은 key + 다른 body = 거절
        assert res.status_code == 400

[Pattern] Outbox Pattern: DB + 메시지의 원자성

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

Outbox Pattern = DB 변경 + 메시지 발행 의 원자성 보장. 이중 쓰기 (dual write) 문제 의 표준 해결.

문제: Dual Write

sequenceDiagram
    autonumber
    participant App
    participant DB
    participant Broker as Kafka/RabbitMQ

    App->>DB: BEGIN<br/>INSERT order<br/>COMMIT
    DB-->>App: OK
    App->>Broker: publish OrderCreated
    Note over App,Broker: ✗ App crash, 또는<br/>Broker timeout
    Broker--xApp: 응답 없음
    Note over DB,Broker: DB 는 INSERT 됨<br/>이벤트는 안 감 → *불일치*

시나리오	결과
DB OK + Publish OK	일관성
DB OK + Publish fail	불일치 (DB 만 변경)
DB fail + Publish OK	불일치 (이벤트만 갔음)
둘 다 fail	OK (취소)

→ 두 시스템을 한 번에 일관 시키는 건 불가능. 2PC 는 비현실적.

해결: Outbox 테이블

flowchart LR
    App -->|단일 트랜잭션| DB
    DB --> Orders[(orders)]
    DB --> Outbox[(outbox)]
    Outbox -.relay.-> Broker[(Broker)]

BEGIN;
  INSERT INTO orders (id, ...) VALUES (?, ...);
  INSERT INTO outbox (event_type, payload, aggregate_id)
    VALUES ('OrderCreated', ?, ?);
COMMIT;
-- 한 트랜잭션 = 원자성!

이후 별도 프로세스 가 outbox 를 읽고 broker 로 publish.

2가지 Relay 방식

1. Polling Publisher

flowchart LR
    Outbox[(outbox)] -.SELECT unpublished.-> Relay[Relay process]
    Relay -->|publish| Broker
    Relay -->|UPDATE published=true| Outbox

while True:
    rows = db.query("SELECT * FROM outbox WHERE published=false LIMIT 100")
    for row in rows:
        broker.publish(row.event)
        db.execute("UPDATE outbox SET published=true WHERE id=?", row.id)
    time.sleep(0.1)

구현 간단.
DB 부담 (polling).
Latency ≈ polling 주기.

2. CDC (Change Data Capture)

flowchart LR
    DB[(DB)] -->|WAL / binlog| CDC[Debezium / Maxwell]
    CDC --> Kafka[(Kafka)]
    Kafka -->|topic| Consumers

DB 의 transaction log (PostgreSQL WAL / MySQL binlog) 를 실시간 캡처.

도구	DB
Debezium	PG, MySQL, MongoDB, Oracle 등
Maxwell	MySQL
AWS DMS	다양
Striim	다양

[!IMPORTANT] Outbox + CDC 는 2026 시점 마이크로서비스 메시징의 표준. 더 이상 애플리케이션 코드에서 publish 하지 않는다.

Outbox 테이블 디자인

CREATE TABLE outbox (
  id BIGSERIAL PRIMARY KEY,
  aggregate_type TEXT NOT NULL,        -- 'Order'
  aggregate_id TEXT NOT NULL,           -- 'order_42'
  event_type TEXT NOT NULL,             -- 'OrderCreated'
  payload JSONB NOT NULL,
  occurred_at TIMESTAMPTZ DEFAULT NOW(),
  published BOOLEAN DEFAULT false,
  published_at TIMESTAMPTZ
);

CREATE INDEX idx_outbox_unpublished
  ON outbox(id) WHERE published = false;

[!TIP] partial index 로 unpublished 만 빠른 SELECT.

처리 후 정리

flowchart TD
    P[Outbox 너무 큼?]
    P --> O1[옵션 1: published row 즉시 DELETE]
    P --> O2[옵션 2: 별도 archive 테이블]
    P --> O3["옵션 3: TTL (며칠 보관)"]

CDC 가 binlog stream 위주 라 published 컬럼 자체 필요 없음. Debezium 이 INSERT 이벤트 그대로 전송.

메시지 순서 보장

flowchart LR
    Tx1[Tx 1: INSERT outbox id=100] --> Order
    Tx2["Tx 2: INSERT outbox id=99 (먼저 시작했지만 commit 늦음)"]
    Tx2 --> Order
    Note["DB ID 순 ≠ commit 순"]

[!CAUTION] concurrent transaction 때문에 id 순서 ≠ commit 순서. strict 순서 보장 이 필요하면 aggregate ID 별 partition 으로.

At-least-once + Idempotency

Outbox + relay 는 at-least-once. 중복 발행 가능 (relay 가 publish 후 update 전 crash).

→ consumer 가 idempotent 처리. 자세한 건 [[idempotency-keys]].

Inbox Pattern (반대 방향)

flowchart LR
    Broker -->|consume| Inbox[(inbox)]
    Inbox -->|단일 트랜잭션| DB
    DB -->|이미 처리?| Skip[중복 skip]

수신 측의 멱등 보장. Outbox 와 대칭.

사용 상황

상황	권장 방식
마이크로서비스 간 이벤트	Outbox + CDC
레거시 DB (WAL 접근 불가)	Polling Publisher
실시간 latency < 100ms	CDC 권장
단순 단일 서비스	불필요 (직접 publish)
이벤트 감사 로그 필요	Outbox + archive 테이블

Polling vs CDC 선택

flowchart TD
    S[Relay 방식 선택]
    S --> Q1{"DB WAL/binlog<br/>접근 가능?"}
    Q1 -->|"Yes"| Q2{"Latency 요구<br/>< 500ms?"}
    Q1 -->|"No"| Poll["Polling Publisher<br/>(구현 단순)"]
    Q2 -->|"Yes"| CDC["CDC (Debezium)<br/>(실시간, 저 latency)"]
    Q2 -->|"No"| Poll2["Polling Publisher<br/>(latency 허용)"]

[!TIP] Debezium + PostgreSQL WAL 조합이 2026 표준. wal_level=logical 설정 필요.

프레임워크 통합

Spring Boot + Spring Modulith

// @ApplicationModuleListener 가 Outbox 자동 관리
@ApplicationModuleListener
public void on(OrderCreated event) {
    // Spring Modulith 가 ApplicationEvent 를 Outbox 로 직렬화
}

Debezium Connector 설정

{
  "name": "outbox-connector",
  "config": {
    "connector.class": "io.debezium.connector.postgresql.PostgresConnector",
    "database.hostname": "localhost",
    "table.include.list": "public.outbox",
    "transforms": "outbox",
    "transforms.outbox.type":
      "io.debezium.transforms.outbox.EventRouter",
    "transforms.outbox.table.field.event.id": "id",
    "transforms.outbox.table.field.event.key": "aggregate_id",
    "transforms.outbox.table.field.event.type": "event_type"
  }
}

운영 고려사항

1. Relay Lag 모니터링

-- 발행 안 된 건수 + 최고령 행 나이
SELECT
    COUNT(*) AS unpublished_count,
    EXTRACT(EPOCH FROM (NOW() - MIN(occurred_at))) AS oldest_sec
FROM outbox
WHERE published = false;

[!WARNING] oldest_sec 이 SLA (예: 30초) 를 넘으면 relay 가 막혔다는 신호. 알람 설정 필수.

2. Dead Letter 처리

ALTER TABLE outbox ADD COLUMN retry_count INT DEFAULT 0;
ALTER TABLE outbox ADD COLUMN last_error TEXT;

-- relay 에서 실패 시
UPDATE outbox
SET retry_count = retry_count + 1,
    last_error  = 'Broker timeout'
WHERE id = ?;

-- retry_count > 5 → DLQ 이동

3. 대용량 정리 정책

flowchart LR
    Pub[published 행 누적]
    Pub --> A{"보관 정책?"}
    A -->|"즉시"| Del["DELETE WHERE published=true<br/>(relay 직후)"]
    A -->|"TTL"| TTL["DELETE WHERE published_at &lt; NOW()-7d<br/>(배치 job)"]
    A -->|"Archive"| Arc["INSERT INTO outbox_archive<br/>+ DELETE FROM outbox"]

-- 효율적 배치 삭제 (lock 최소화)
DELETE FROM outbox
WHERE published = true
  AND published_at < NOW() - INTERVAL '7 days'
LIMIT 10000;

테스트 전략

# 통합 테스트: outbox 행 확인
def test_order_creates_outbox_event(db, client):
    resp = client.post('/orders', json={'item': 'Widget'})
    assert resp.status_code == 201

    rows = db.execute(
        "SELECT event_type, payload FROM outbox WHERE published=false"
    ).fetchall()
    assert len(rows) == 1
    assert rows[0]['event_type'] == 'OrderCreated'

# relay 테스트: 멱등성 확인
def test_relay_idempotent(db, broker, relay):
    db.execute("INSERT INTO outbox (event_type, payload) VALUES ('E', '{}')")
    relay.run_once()  # 첫 번째 relay
    relay.run_once()  # relay 가 crash 후 재시작 시나리오

    msgs = broker.consumed_messages('events')
    assert len(msgs) == 1  # 중복 없음 (consumer idempotent)

흔한 함정

[!WARNING]

*UPDATE published=true 와 publish 가 별도 transaction = relay crash 시 중복 발행. at-least-once 인정 + consumer idempotent.

Outbox 의 순서 무시 = 다운스트림이 순서 가정. partition / sequence 명시.

Outbox 가 너무 큼 = 정리 필요. 보관 정책.

SELECT FOR UPDATE SKIP LOCKED 없이 multi worker = 같은 row 동시 처리 → 중복.

[Pattern] Saga: 분산 트랜잭션의 보상 흐름

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

Saga = 여러 service 의 로컬 트랜잭션 을 연결한 긴 흐름. 한 단계 실패 시 이전 단계의 보상 (compensating) 트랜잭션 으로 논리적 롤백.

[!IMPORTANT] Saga 는 ACID 트랜잭션이 아니다. 분산 환경에서 2PC (XA) 가 비현실적이라 eventually consistent + 보상 으로 대체.

시나리오: 주문

sequenceDiagram
    autonumber
    participant O as Order Service
    participant P as Payment Service
    participant I as Inventory Service
    participant S as Shipping Service

    O->>O: T1: 주문 생성 (pending)
    O->>P: T2: 결제 요청
    P-->>O: 결제 완료
    O->>I: T3: 재고 차감
    I-->>O: 차감 완료
    O->>S: T4: 배송 요청
    S-->>O: 배송 시작
    O->>O: T5: 주문 confirmed

실패 시 보상:

sequenceDiagram
    O->>P: T2 결제
    P-->>O: ✓
    O->>I: T3 재고
    I-->>O: 실패 (재고 부족)
    O->>P: C2: 결제 환불 (보상)
    O->>O: C1: 주문 취소 (보상)

단계	Compensating
T1 주문 생성	C1 주문 취소
T2 결제	C2 환불
T3 재고 차감	C3 재고 복원
T4 배송	C4 배송 취소

두 스타일: Choreography vs Orchestration

1. Choreography (이벤트 기반)

flowchart LR
    O[Order] -->|OrderCreated| P[Payment]
    P -->|PaymentSucceeded| I[Inventory]
    I -->|StockReserved| S[Shipping]
    S -->|Shipped| O
    P -->|PaymentFailed| O
    I -->|StockUnavailable| P

각 service 가 event 듣고 자기 일.
중앙 제어자 없음.
유연, 낮은 결합.
흐름 추적 어려움 (어디까지 갔는지).

2. Orchestration (중앙 코디네이터)

flowchart LR
    Coord[Saga Orchestrator] --> O[Order]
    O -->|성공| Coord
    Coord --> P[Payment]
    P -->|성공| Coord
    Coord --> I[Inventory]
    I -->|실패| Coord
    Coord -->|보상| P
    Coord -->|보상| O

중앙 상태 기계.
흐름 명확.
결합도 약간 높음 (orchestrator 가 모든 service 안)
문제 추적 쉬움.

항목	Choreography	Orchestration
결합도	낮음	약간 높음
흐름 추적	어려움	쉬움
디버깅	어려움	쉬움
적합	단순 흐름 (3-4 단계)	복잡 흐름 (5+ 단계)
운영 도구	event tracer	상태 기계 시각화

[!TIP] 3-4 단계까지는 choreography, 그 이상은 orchestration 이 일반 권장. Netflix 도 Conductor 라는 orchestrator 사용.

보상 트랜잭션의 함정

flowchart TD
    Q[보상이 *항상 가능* 한가?]
    Q --> X1["✗ 이메일 발송 (취소 불가)"]
    Q --> X2["✗ SMS / push 알림"]
    Q --> X3["✗ 외부 API 호출 (paypal 환불 한도)"]
    Q --> Sol1["→ 가능한 단계만 saga 안"]
    Q --> Sol2["→ 비가역 단계는 saga *마지막* 으로"]

[!CAUTION] 비가역 작업 (이메일, push, 외부 API) 은 saga 가 commit 결정 후 실행. 그 전에 실행하면 보상 불가.

멱등성 + Idempotency Key

각 단계 / 보상은 멱등 (idempotent) 해야 한다. 자세한 건 [[idempotency-keys]].

# 보상 시
async def compensate_payment(saga_id, payment_id):
    if already_refunded(saga_id):
        return                       # 멱등
    await payment_service.refund(payment_id, key=saga_id)

Saga 상태 저장

flowchart LR
    Orch[Orchestrator] --> Store[(Saga State Store)]
    Store --> SQL[(PostgreSQL)]
    Store --> Stream[(Kafka)]
    Store --> SF[(Step Functions)]

Store	특징
PostgreSQL (DB)	트랜잭션 친화
Kafka topic	event log 자연 통합
AWS Step Functions	managed orchestrator
Temporal	워크플로 엔진
Camunda	BPMN 표준

Temporal / Step Functions (워크플로 엔진)

flowchart LR
    SDK["Application code<br/>(workflow + activity)"] --> Temporal[Temporal Server]
    Temporal --> StateDB[(상태 DB)]
    Temporal --> Workers["Workers<br/>(activity 실행)"]

워크플로 코드 가 durable execution.
retry / timeout / sleep 이 언어 native 처럼.
마치 함수 호출 같은데 분산 + 영속.

흔한 함정

[!WARNING]

모든 분산 흐름 = saga = 단순 async event 가 충분한데도 복잡한 saga. 진짜 보상 필요한 흐름에만.

보상 없거나 미구현 = “해피 패스만 만들고 실패는 운영자 처리”. 1년 뒤 데이터 불일치 폭증.

Choreography 의 순환 의존성 = A → B → C → A 같은 흐름. 디버깅 지옥.

상태 저장 안 함 = orchestrator 다운 시 진행 잃음. event log 또는 DB 필수.

Saga 상태 기계

stateDiagram-v2
    [*] --> STARTED
    STARTED --> PROCESSING : 단계 실행
    PROCESSING --> PROCESSING : 다음 단계
    PROCESSING --> COMPENSATING : 단계 실패
    COMPENSATING --> COMPENSATING : 보상 단계 실행
    COMPENSATING --> FAILED : 보상 완료
    PROCESSING --> COMPLETED : 모든 단계 성공
    FAILED --> [*]
    COMPLETED --> [*]

상태	의미
STARTED	saga 생성, 첫 단계 전
PROCESSING	정방향 단계 실행 중
COMPENSATING	실패 후 보상 단계 실행 중
COMPLETED	모든 단계 성공
FAILED	보상 완료, 논리적 롤백 완료

Saga 와 2PC 비교

항목	Saga	2PC (XA)
트랜잭션 격리	약함 (eventually consistent)	강함 (ACID)
가용성	높음 (부분 실패 허용)	낮음 (코디네이터 블로킹)
구현 복잡도	보상 로직 필요	분산 코디네이터 필요
성능	비동기 가능	동기, 잠금
적합	마이크로서비스	단일 조직 DB 간

[!NOTE] 2PC 가 필요하다고 느껴진다면 saga 를 먼저 검토. saga 로 해결 안 되는 경우에만 2PC.

Temporal 워크플로 예시

# Temporal Python SDK
from temporalio import workflow, activity
from datetime import timedelta

@workflow.defn
class OrderSaga:
    @workflow.run
    async def run(self, order_id: str) -> str:
        # T1: 주문 확인
        order = await workflow.execute_activity(
            confirm_order,
            order_id,
            start_to_close_timeout=timedelta(seconds=10),
        )
        try:
            # T2: 결제
            payment = await workflow.execute_activity(
                charge_payment,
                order.payment_info,
                start_to_close_timeout=timedelta(seconds=30),
            )
        except Exception:
            # C1: 보상 - 주문 취소
            await workflow.execute_activity(cancel_order, order_id)
            raise
        try:
            # T3: 재고 차감
            await workflow.execute_activity(
                deduct_stock,
                order.items,
                start_to_close_timeout=timedelta(seconds=10),
            )
        except Exception:
            # C2: 결제 환불
            await workflow.execute_activity(refund_payment, payment.id)
            await workflow.execute_activity(cancel_order, order_id)
            raise
        return "completed"

Temporal 의 핵심:

activity 실패 시 자동 retry (정책 설정 가능)
workflow state 는 영속 저장: 서버 재시작 후에도 재개
언어 native 코드처럼 쓰지만 분산 + 내구성

Saga 테스트 전략

테스트 레벨	목적	도구
Unit	각 서비스 보상 로직 멱등성	Jest / pytest
Integration	오케스트레이터 + 스텁 서비스	Testcontainers
Contract	서비스 간 이벤트 스키마	Pact
End-to-End	실패 시나리오 전체 흐름	Temporal test env

# 멱등성 단위 테스트 예시
def test_compensate_payment_idempotent():
    saga_id = "test-saga-1"
    payment_id = "pay-1"

    # 첫 번째 보상
    compensate_payment(saga_id, payment_id)

    # 두 번째 보상 (중복) 도 에러 없이 통과
    compensate_payment(saga_id, payment_id)

    # DB 에 환불 기록 1건만
    assert count_refunds(payment_id) == 1

Saga 테스트 핵심: 실패 경로마다 보상이 올바르게 실행되는지, 보상 자체가 실패할 때 어떻게 되는지 검증.

프로덕션 체크리스트

각 단계에 Idempotency Key 부여 (재시도 안전)
모든 보상 트랜잭션 구현 및 멱등성 검증
Saga 상태 영속 저장 (DB 또는 워크플로 엔진)
비가역 작업 (이메일, push) saga 마지막에 배치
실패 알람 및 Dead Letter Queue 운영
각 단계 timeout + retry 정책 설정
correlationId / traceid 로 분산 추적 연결
보상 단계 실패 시 수동 개입 알람

[Voice AI] 파이프라인 디커플링: Redis Streams / Kafka 적용

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

대규모 음성 에이전트 = STT/LLM/TTS 를 분리 배포 + 메시지 큐로 디커플링. 수평 확장 + 독립 실패.

[!NOTE] 소규모 (수십 동시 통화) 는 monolith pipeline (Pipecat 한 프로세스) 으로 충분. 수백 ~ 수천 동시 부터 디커플링 의미.

Monolith vs Decoupled

flowchart TB
    subgraph Mono["Monolith"]
        M1["Pipecat process<br/>(STT + LLM + TTS 한 프로세스)"]
    end
    subgraph Decoupled["Decoupled"]
        D1["Orchestrator (stateless)"]
        D2[STT Workers]
        D3[LLM Workers]
        D4[TTS Workers]
        Q1[(Queue: stt-tasks)]
        Q2[(Queue: llm-tasks)]
        Q3[(Queue: tts-tasks)]
        D1 --> Q1 --> D2
        D2 --> Q2 --> D3
        D3 --> Q3 --> D4
        D4 --> D1
    end

	Monolith	Decoupled
운영 복잡도	낮음	높음
수평 확장	동일 비율	단계별 독립
독립 실패	전체 다운	단계별 격리
지연	최저	+ queue hop (~10ms)
동시 통화	수십	수천+

큐 선택

큐	적합
Redis Streams	가장 단순, < 수만 RPS
Redis Pub/Sub	손실 OK, 알림만
Kafka	큰 throughput, 영속, replay
NATS JetStream	가벼움, edge
AWS SQS	managed, AWS only

음성 에이전트 = Redis Streams 가 가장 흔함 (latency 낮음, 운영 단순).

Redis Streams 패턴

# Producer (STT worker)
async def stt_worker():
    while True:
        # stt-tasks 에서 받음
        msgs = await redis.xreadgroup(
            "stt-group", "stt-worker-1",
            {"stt-tasks": ">"},
            count=10, block=100,
        )
        for stream, items in msgs:
            for msg_id, data in items:
                audio_url = data["audio_url"]
                transcript = await deepgram.transcribe(audio_url)

                # 다음 단계로 전달
                await redis.xadd("llm-tasks", {
                    "session_id": data["session_id"],
                    "transcript": transcript,
                })
                await redis.xack("stt-tasks", "stt-group", msg_id)

자세한 Streams 는 [[Redis Streams]].

Orchestrator (stateless)

class VoiceOrchestrator:
    """Session 만 관리. 실제 처리는 worker."""

    async def on_call_start(self, call_id: str):
        # Session 을 Redis 에 저장 (stateless 의 외부 상태)
        await redis.hset(f"call:{call_id}", mapping={
            "started_at": time.time(),
            "status": "active",
        })

    async def on_audio_chunk(self, call_id: str, audio: bytes):
        # 큐에 던지고 끝
        await redis.xadd("stt-tasks", {
            "call_id": call_id,
            "audio": audio,
        })

    async def on_llm_result(self, call_id: str, text: str):
        # TTS 큐로
        await redis.xadd("tts-tasks", {
            "call_id": call_id,
            "text": text,
        })

    async def on_tts_audio(self, call_id: str, audio_chunk: bytes):
        # 사용자에게 stream
        await self.send_to_user(call_id, audio_chunk)

Orchestrator 인스턴스 자체는 상태 없음. 모든 상태 Redis. 수평 확장 + 무중단 배포 자유.

수평 확장

flowchart TB
    LB[Load Balancer] --> O1[Orchestrator 1]
    LB --> O2[Orchestrator 2]
    LB --> O3[Orchestrator 3]
    O1 & O2 & O3 --> Redis[(Redis: 상태 + 큐)]
    Redis --> STT_W["STT Workers (auto-scale)"]
    Redis --> LLM_W["LLM Workers (auto-scale)"]
    Redis --> TTS_W["TTS Workers (auto-scale)"]

컴포넌트	스케일링 기준
Orchestrator	동시 connection 수
STT Worker	stt-tasks lag
LLM Worker	llm-tasks lag, GPU
TTS Worker	tts-tasks lag

각자 다른 자원. STT 는 CPU, LLM 은 GPU, TTS 는 GPU 또는 API. 분리 = 효율적 자원.

Sticky vs Stateless

flowchart LR
    Q{Voice agent stateless?}
    Q -->|"Yes (모든 state Redis)"| Stateless[수평 확장 자유]
    Q -->|"No (메모리에 conversation)"| Sticky[Sticky session 필수]

Sticky = 같은 통화 = 같은 orchestrator. SFU + WebRTC 환경에서 불가피할 때 있음.

Failure Recovery

flowchart LR
    Crash[Orchestrator 1 죽음]
    Crash --> Detect[Health check fail]
    Detect --> Drain[기존 통화 drain]
    Detect --> NewO[다른 orchestrator 가 이어받음]
    NewO --> Restore[Redis 에서 state 복원]

async def take_over_call(call_id: str):
    state = await redis.hgetall(f"call:{call_id}")
    if not state:
        return False

    # 이미 다른 orchestrator 처리 중?
    owner = await redis.set(
        f"call:{call_id}:owner",
        self.instance_id,
        nx=True, ex=30,
    )
    if not owner:
        return False

    # 이어받음
    await self.resume_call(call_id, state)
    return True

자세한 상태 관리 는 [[Redis Sorted Sets]] 의 session 패턴.

Sentinel + Cluster

flowchart LR
    Voice[Voice agents] --> Sentinel["Redis Sentinel<br/>(자동 failover)"]
    Sentinel --> Primary[(Redis Primary)]
    Primary --> Replica1[(Replica 1)]
    Primary --> Replica2[(Replica 2)]

음성 = Redis 단일 장애 = 모든 통화 끊김. Sentinel 또는 Cluster + sticky session 보호 필수.

외부 API 복원력

flowchart TB
    Q[복원력 패턴]
    Q --> T1["Timeout (짧게)"]
    Q --> T2["Retry + backoff (idempotent only)"]
    Q --> T3[Circuit Breaker]
    Q --> T4["Fallback (다른 vendor)"]
    Q --> T5[Health check]

단계	timeout	fallback
STT	5초	Deepgram → AssemblyAI
LLM	30초	GPT-4o-mini → Claude Haiku
TTS	10초	Cartesia → Azure

자세한 건 [[retry-with-backoff]], [[circuit-breaker]].

흔한 함정

[!WARNING]

Monolith → Decouple 전환 너무 일찍 = 운영 복잡도 폭증. 수십 동시 통화는 monolith.

상태 메모리 보관 = orchestrator restart = 통화 끊김. Redis 외부 상태.

Redis Streams MAXLEN 무제한 = 메모리 폭증. MAXLEN ~ 100K 권장.

Queue lag 모니터링 없음 = 어디서 병목인지 모름. Prometheus + alert.

[Distributed Systems] Consensus: Raft, Paxos

koa (김신건) — Wed, 24 Jun 2026 00:00:00 GMT

정의

Consensus (합의): 여러 노드가 같은 값에 동의 하는 분산 알고리즘. CAP 의 C 보장의 기반.

용도:

Leader election: 1개 leader 선출 (ZooKeeper, etcd, Consul)
Replicated log: 모든 노드가 같은 명령 순서로 적용 (DB replication, K8s etcd)
Distributed lock: 글로벌 락
Configuration management: cluster 설정

대표 알고리즘:

Paxos (1989, Lamport): 이론적 정석, 이해 어려움
Raft (2014, Ongaro & Ousterhout): Paxos 의 이해 가능한 대안. 현재 대세
PBFT, Byzantine fault tolerance: 악의적 노드 가정 (blockchain)

이 페이지는 Raft 중심 (가장 보편적).

Raft 의 3가지 역할

[Leader]   ─── 1명만 존재
   └── 모든 write 받음, log replication 책임
   
[Follower] ─── 나머지 모두
   └── leader 의 명령 받아 적용

[Candidate] ─── 전이 상태 (선거 중)
   └── leader 가 사라지면 follower 가 candidate 로 전환, 투표 요청

Raft 의 핵심: term

시간을 term (선거 회차) 으로 나눔:

term 1: Leader = A
term 2: Leader = B  (A 죽음, B 선출)
term 3: Leader = A  (B 죽음, A 복귀)

각 노드는 자신의 currentTerm 보유. term 이 낮은 노드의 요청은 거부 (오래된 leader 격리).

Leader Election

follower 가 randomized timeout (150~300ms) 동안 leader heartbeat 못 받으면:
  1. 자신을 candidate 로 전환
  2. currentTerm++
  3. 자기 자신에 투표
  4. 다른 노드에 RequestVote RPC 전송
  
응답 시나리오:
  - 과반수 (N/2 + 1) 표 받으면 → Leader 됨
  - 다른 candidate 의 더 높은 term 보면 → follower 로 복귀
  - 표 안 모이면 → 새 election (다른 timeout 후)

randomized timeout 이 split vote 회피의 핵심.

Log Replication

[Leader] receives "x = 5" from client
   ↓
1. Leader appends to its log:  [..., (term=3, x=5)]
2. Leader sends AppendEntries RPC to all followers
3. Each follower appends to its log + replies OK
4. Once majority replied → Leader commits (apply to state machine)
5. Leader notifies followers in next AppendEntries
6. Followers apply committed entries to their state machine

핵심: commit = majority 가 log 에 기록. apply 는 그 후.

Log Matching Property

같은 index + 같은 term 의 entry = 같은 명령 (강력한 invariant)

따라서 leader 의 log 가 truth. follower 가 mismatch 면 leader 의 것으로 덮어쓰기.

Safety: 어떤 leader 가 선출되나?

새 leader 는 모든 committed entry 를 가진 노드 만 가능.

RequestVote 시 candidate 가 자신의 last log term, index 보냄. follower 는 자기보다 stale 한 candidate 에게 투표 안 함 (rejects vote if candidate’s log is less up-to-date).

majority vote 보장 + commit 조건 = “어느 commit 된 entry 는 영구히 보존”.

Membership Changes

cluster 멤버 추가 / 제거는 위험 (두 majority 존재 시 split brain):

old: {A, B, C} → majority = 2
new: {A, B, C, D, E} → majority = 3

전환 중에 둘 다 자기를 majority 라고 주장 가능

Raft 의 해결:

Joint consensus (논문): old 와 new config 의 majority 모두 필요
Single server changes (실용): 한 번에 1명만 추가 / 제거

Snapshot + Log Compaction

log 가 무한히 커지면 안 됨. 주기적으로 snapshot:

1. State machine 의 현재 상태를 disk 에 저장
2. 그 시점 이전 log entry 삭제
3. Snapshot 에 last included index, term 기록

복구 시 snapshot 적용 + 그 이후 log replay.

Raft 구현체

시스템	사용처
etcd	Kubernetes 의 control plane
Consul	service discovery
CockroachDB	distributed SQL
TiKV	TiDB 의 storage
MongoDB (3.2+)	replication
Hazelcast (4.0+)	distributed cache

대부분 시스템이 직접 구현하거나 hashicorp/raft 라이브러리 사용.

Paxos 와의 비교

항목	Paxos	Raft
발표	1989	2014
이해도	매우 어려움	비교적 쉬움
Leader 개념	명시적 X (Multi-Paxos 추가)	명시적
Log replication	명시적 X	명시적
산업 채택	Spanner, Chubby	etcd, Consul, …

Raft 가 “이해 가능한 alternative” 를 목표로 설계. 안전성은 동등.

Paxos 의 단계

Prepare (round): proposer 가 proposal number 보내 majority 의 promise 받음
Accept: 가장 높은 proposal number 의 value 를 majority 에 보냄
Learn: 결정된 값 전파

Multi-Paxos: leader 가 prepare 한 번 + 여러 accept (Raft 의 leader 와 유사).

ZooKeeper 와 Zab

ZooKeeper 의 합의 알고리즘 Zab (ZooKeeper Atomic Broadcast):

Paxos / Raft 와 유사하지만 total order 강제
Leader 가 모든 update 를 ordered broadcast
ZooKeeper 의 zxid (zookeeper transaction id) 가 순서 보장

ZooKeeper 는 분산 락 / leader election 의 standard. ephemeral node + watch 가 강력.

CAP 와 합의의 관계

합의 알고리즘 = CP (강한 일관성).

분할 시 minority partition 의 노드들은:

leader 가 없음 → write 불가
또는 old leader 였다면 commit 못 함 → 정지

majority partition 만 진행. 가용성 손실 + 일관성 보장.

자주 보는 함정

함정 1: split brain

분할 후 양쪽이 각자 leader 선출 → 둘 다 update → 복구 후 충돌.

Raft 의 term + majority 가 방어. minority 의 “leader” 는 다음 term 의 leader 로 인해 거부됨.

함정 2: clock skew

Lamport timestamp / Vector clock 같은 logical clock 사용. wall clock 의존 시 NTP drift 로 깨짐.

Raft 는 wall clock 의존 안 함 (term 이 logical).

함정 3: 2 노드 cluster 의 위험

majority = 2/2. 1 노드 죽으면 cluster 정지. 3 노드가 최소.

함정 4: 짝수 노드 cluster

4 노드 cluster 의 majority = 3. 즉 3 노드 cluster 와 같은 fault tolerance (1 노드 fail). 그러나 메시지 비용 ↑. 홀수 권장.

함정 5: cross-DC 합의의 latency

majority 가 다른 DC 면 매 write 가 cross-DC latency. 보통 같은 region 에 3 노드. cross-region 은 별도 consensus (geo-replication).

성능 trade-off

3 node cluster: 1 fail tolerance, 빠른 합의
5 node cluster: 2 fail tolerance, 약간 느림
7+: 거의 안 함 (메시지 비용 폭증)

write throughput = 1 / RTT (대략). leader 가 majority 응답 기다림.

함정과 베스트 프랙티스

홀수 노드 (3, 5, 7): 짝수는 메시지 비용만 ↑
majority 가 같은 region: cross-DC 면 latency 폭주
clock skew 무관: 합의 자체엔 영향 X (logical clock)
snapshot 주기적 + tunable: log 무한 성장 방지
client retry + idempotent: leader 전환 중에도 안전
monitoring: leader election 빈도, log size, applied vs committed gap

[Distributed Systems] 분산 트랜잭션: 2PC, Saga, Outbox

koa (김신건) — Wed, 24 Jun 2026 00:00:00 GMT

정의

분산 트랜잭션 은 여러 service / DB / 메시지 큐에 걸친 작업을 ACID 처럼 묶는 문제. 마이크로서비스 / 이벤트 기반 아키텍처의 핵심 도전.

3가지 접근:

2PC (Two-Phase Commit): 동기 ACID, 전통적, 거의 안 씀
Saga: 비동기 compensating action, 마이크로서비스 표준
Outbox: DB 트랜잭션 + 메시지 큐 일관성 보장 (Saga 의 보조)

선택 기준: 시스템 복잡도, 일관성 요구, 가용성 trade-off.

2PC (Two-Phase Commit)

1단계 (Prepare): coordinator → 모든 participant 에게 “준비 됐어?” 2단계 (Commit): 모두 OK 면 → “commit”. 한 명이라도 NO 면 → “rollback”

       [Coordinator]
            │
   ┌────────┼────────┐
   ↓        ↓        ↓
 [DB A]   [DB B]   [DB C]

Phase 1 (Prepare):
   coordinator → "준비?"
   each DB → write log, lock rows, "yes"

Phase 2 (Commit):
   coordinator → "commit"
   each DB → commit, release lock, "done"

장점:

강한 ACID 보장
표준 (XA Transaction)
동기적 - 결과 즉시

단점:

Blocking: coordinator 죽으면 participant 가 락 잡은 채 영원히 대기
Performance: 매 트랜잭션 = 2 라운드 + N participant
Single point of failure: coordinator
CP 시스템: 가용성 손실

JTA (Java Transaction API) + XA driver 가 구현. 대부분 modern 시스템은 회피.

Saga Pattern

전체 트랜잭션을 여러 local 트랜잭션의 chain 으로:

T1 (서비스 A) → T2 (서비스 B) → T3 (서비스 C)
                                ↓ 실패
              C2 (B 보상) ← C3 (실패 처리)

각 step 이 commit 후 다음 발동. 실패 시 compensating transaction 으로 되돌리기.

예: 주문 처리

Step 1: Order Service → 주문 생성 (status=pending)
Step 2: Payment Service → 결제 시도
   성공 → Step 3
   실패 → Compensating: Order Service → 주문 취소

Step 3: Inventory Service → 재고 차감
   성공 → Step 4
   실패 → Compensating: Payment Service → 환불 → Order Service → 취소

Step 4: Shipping Service → 배송 시작
   성공 → 완료
   실패 → Compensating: 재고 복구, 환불, 주문 취소

각 service 가 자기 local 트랜잭션만 책임. cross-service 락 없음.

두 가지 구현 방식

1. Choreography: 각 service 가 이벤트 발행 + 구독

Order Service → "OrderCreated" 이벤트 → Kafka
Payment Service ← "OrderCreated" 구독 → 결제 시도 → "PaymentCompleted" 발행
Inventory Service ← "PaymentCompleted" 구독 → ...

장점: 분산, 결합도 낮음. 단점: 흐름 추적 어려움, 디버깅 복잡.

2. Orchestration: 중앙 orchestrator 가 흐름 제어

Saga Orchestrator
  ├── Order Service: 생성
  ├── Payment Service: 결제 (실패 시 → 이전 단계 보상)
  ├── Inventory Service: 차감
  └── Shipping Service: 시작

장점: 흐름 명시적, 디버깅 쉬움. 단점: orchestrator 가 단일 장애점, 복잡한 로직.

도구: AWS Step Functions, Camunda, Temporal, Conductor.

Saga 의 제약

Isolation 없음: 진행 중인 saga 의 중간 상태가 다른 트랜잭션에 보임 → “dirty read” 가능
Eventually consistent: 보상 완료까지 일시 비일관
Compensating transaction 설계 어려움: idempotent + 영구 부수효과 없어야 (이메일 발송 후 보상 어려움)

대응 패턴:

Semantic lock: 진행 중 자원에 flag 표시 (e.g., order.status=processing)
Commutative updates: 순서 무관하게 결과 동일하도록
Pessimistic view: 보수적 처리 (e.g., 미리 예약 → 확정)

Outbox Pattern

DB 트랜잭션 + 메시지 큐 발행 의 atomicity 보장:

[전통 문제]
INSERT order INTO orders ─ DB transaction ─ OK
kafka.publish(OrderPlaced) ─ network call ─ 실패
→ DB 에 order 있지만 알림 X (inconsistent)

또는 반대로:
kafka.publish(OrderPlaced) ─ 성공
INSERT order ─ rollback
→ 알림 갔지만 DB 에 order 없음 (worse!)

Outbox 패턴:

[같은 DB 트랜잭션 안]
BEGIN
  INSERT INTO orders (...);
  INSERT INTO outbox (event_type, payload, status='pending');
COMMIT

[별도 worker]
SELECT * FROM outbox WHERE status='pending'
  → Kafka publish
  → UPDATE outbox SET status='sent'

장점:

DB 트랜잭션 = 단일 commit (atomic)
Worker 가 죽어도 row 가 outbox 에 살아 있어 재시도
at-least-once delivery (idempotent consumer 필요)

도구:

Debezium: outbox 테이블의 CDC (Change Data Capture)
Spring Modulith Events: Spring 통합
직접 구현: 간단한 polling worker

Spring Boot 의 outbox 예

@Service
@Transactional
public class OrderService {
    private final OrderRepository orderRepo;
    private final OutboxRepository outboxRepo;
    private final ObjectMapper objectMapper;

    public Order place(Cart cart) {
        Order order = orderRepo.save(new Order(cart));

        OutboxEvent event = new OutboxEvent();
        event.setAggregateType("Order");
        event.setAggregateId(order.getId().toString());
        event.setEventType("OrderPlaced");
        event.setPayload(objectMapper.writeValueAsString(toEvent(order)));
        event.setStatus("pending");
        outboxRepo.save(event);

        return order;
    }
}

@Component
public class OutboxRelay {
    private final OutboxRepository outboxRepo;
    private final KafkaTemplate<String, String> kafka;

    @Scheduled(fixedDelay = 1000)
    public void relay() {
        List<OutboxEvent> events = outboxRepo.findTop100ByStatusOrderById("pending");
        for (OutboxEvent e : events) {
            kafka.send("orders", e.getAggregateId(), e.getPayload());
            e.setStatus("sent");
            outboxRepo.save(e);
        }
    }
}

@TransactionalEventListener(AFTER_COMMIT) 도 비슷한 효과 ([[spring-events]]) 지만 worker 인스턴스 죽으면 event 손실 → outbox 가 더 안전.

Outbox vs 2PC vs Saga 정리

항목	2PC	Saga	Outbox
일관성	Strong	Eventual	Eventual
Blocking	Yes (락)	No	No
Compensating 필요	No	Yes	(개별 step 에 따름)
운영 복잡도	높음	중간	낮음
가용성	낮음 (CP)	높음 (AP)	높음
사용처	legacy (XA)	마이크로서비스 표준	DB + MQ 양립

대부분 modern: Saga + Outbox 조합. 2PC 회피.

Idempotency

분산 시스템의 모든 작업은 idempotent:

재시도해도 결과 같음
중복 메시지 처리해도 OK
network 재시도 안전

구현 패턴:

Idempotency key: 클라이언트가 unique key 동봉 → 서버가 처음 보면 처리, 두 번째 보면 캐시 결과 반환
Conditional update: WHERE status='pending' → 이미 처리된 row 는 변경 안 됨
Distributed lock + check: race 회피

자주 보는 함정

함정 1: 보상 트랜잭션의 부수효과

“이메일 발송” 같은 영구 부수효과는 보상 불가. 패턴:

외부 호출은 saga 의 마지막 단계로
또는 confirmation 단계 분리 (PaymentPending → PaymentConfirmed)

함정 2: at-least-once delivery 의 중복

Kafka / SQS 는 at-least-once. consumer 는 idempotent 처리 필수. Outbox 자체도 publish 후 status update 사이 crash 시 중복 가능.

함정 3: outbox 의 throughput 한계

polling worker 가 단일 인스턴스면 bottleneck. 해결:

partition 별 worker
Debezium 같은 CDC tool 활용

함정 4: Saga 의 부분 실패 디버깅

choreography 면 흐름 추적 어려움. distributed tracing (OpenTelemetry) + correlation ID 필수.

함정 5: Two-Generals 문제

DB commit + 메시지 큐 publish 의 atomicity 는 본질적으로 불가 (network 위에선). Outbox 가 best-effort.

함정과 베스트 프랙티스

2PC 회피: 모든 modern 시스템
Saga + Orchestration: 흐름 추적 / 디버깅 우선이면
Outbox 가 DB+MQ 일관성의 표준
모든 작업 idempotent: idempotency key + conditional update
distributed tracing 필수: traceId + spanId
compensating action 설계가 핵심: 영구 부수효과는 마지막에
eventual consistency 명시적 안내: UX 에 반영
Outbox 의 worker scaling: 단일 worker 가 bottleneck

김신건의 로그 - 위키 / distributed-systems

[Distributed] NATS: 가벼움, JetStream, subject 라우팅

정의

두 모드: Core vs JetStream

Subject 계층

Request-Reply (Core NATS 의 강점)

JetStream 개요

JetStream Stream 설정

JetStream 메시지 흐름 (Ack)

Consumer Ack 정책

NATS KV / Object Store

NATS Cluster 구성

Edge / IoT 패턴

NATS vs Kafka vs RabbitMQ

적합 / 부적합

흔한 함정

관련 위키

[Distributed] RabbitMQ: exchange, queue, routing key

정의

언제 쓰이나

구조

Exchange 4 종류

1. Direct

2. Topic

3. Fanout

4. Headers

실전: Python pika 로 Topic Exchange

Consumer: ack / nack

메시지 보장

Queue 속성 (x-arguments)

DLQ (Dead Letter Queue)

Quorum Queue (HA)

RabbitMQ vs Kafka

RabbitMQ Streams (Kafka 흉내)

흔한 함정

관련 위키

[Pattern] Microservices vs Monolith: 언제 분리, 언제 통합

정의

결정 트리

시작은 Monolith (Fowler 의 “Monolith First”)

Microservices 가 진짜 도움될 때

Distributed Monolith (안티 패턴)

Service Boundary 가르는 기준

DDD Bounded Context

Conway’s Law

Inverse Conway Maneuver

API 통신 패턴: 동기 vs 비동기

데이터 일관성 전략

분리 비용 카탈로그

Service Mesh 개요

모듈 모놀리스 (Modular Monolith)

흔한 함정

관련 위키

[Pattern] API Gateway: BFF, 라우팅, auth, rate limit

정의

역할

요청 처리 파이프라인

책임 카탈로그

인증 플로우

BFF (Backend For Frontend)

BFF 패턴의 장점

Kong 설정 예시

AWS API Gateway

Envoy + gRPC 트랜스코딩

Rate Limiting at Gateway

API Gateway vs Service Mesh

도구 비교

패턴: GraphQL Federation Gateway

흔한 함정

관련 위키

[Distributed Systems] CAP Theorem과 PACELC

정의

CP vs AP 선택 다이어그램

실제 시스템 매핑

etcd / Consul: CP 상세

Cassandra: AP 상세

CAP의 한계와 PACELC

Conflict Resolution (충돌 해결)

Last Write Wins (LWW)

Vector Clock