1. 권장 아키텍처

Client
 ├─ REST API ──> Express API 서버 ──> PostgreSQL
 └─ WebSocket ─> Realtime Gateway ──> Redis Pub/Sub
                                      └─ PostgreSQL

• REST: 대화방 조회, 메시지 이력, 읽음 처리
• WebSocket: 새 메시지, 읽음 상태, 실시간 알림
• PostgreSQL: 영구 데이터와 정합성 보장
• Redis: WebSocket 서버 간 이벤트 전달, 접속 상태, 단기 캐시
• Node.js 프로세스는 여러 대로 수평 확장
• WebSocket은 ws 또는 Socket.IO 사용. 단순성과 성능을 중시하면 ws 권장

동시 접속 1만 명은 단일 Node.js 서버에서도 처리 가능할 수 있지만, 장애와 배포를 고려해 다음처럼 시작하는 것이 안전합니다.

• API 서버 3대 이상
• Realtime Gateway 3대 이상
• 로드밸런서 앞단에 배치
• Redis 1 primary + replica 또는 관리형 Redis
• PostgreSQL connection pool을 서버당 20~30개 이하로 제한

WebSocket 연결 수가 많아도 PostgreSQL 연결 수를 같이 늘리면 안 됩니다. 실시간 연결 수와 DB 연결 수는 별도로 관리해야 합니다.

---

2. PostgreSQL 스키마

사용자

기존 사용자 테이블을 사용한다고 가정합니다.

CREATE TABLE chat_rooms (
    id              BIGSERIAL PRIMARY KEY,
    item_id         BIGINT NULL,
    created_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
    updated_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
    last_message_id BIGINT NULL
);

CREATE TABLE chat_room_members (
    room_id     BIGINT NOT NULL REFERENCES chat_rooms(id),
    user_id     BIGINT NOT NULL REFERENCES users(id),
    joined_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
    left_at     TIMESTAMPTZ NULL,

    PRIMARY KEY (room_id, user_id)
);

1:1 채팅이라도 chat_room_members를 사용하면 차후 다자간 채팅으로 확장하기 쉽습니다.

메시지

CREATE TABLE chat_messages (
    id              BIGSERIAL PRIMARY KEY,
    room_id         BIGINT NOT NULL REFERENCES chat_rooms(id),
    sender_id       BIGINT NOT NULL REFERENCES users(id),
    client_message_id UUID NOT NULL,
    body            TEXT NOT NULL,
    message_type    VARCHAR(20) NOT NULL DEFAULT 'text',
    created_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
    deleted_at      TIMESTAMPTZ NULL,

    UNIQUE (sender_id, client_message_id)
);

CREATE INDEX idx_chat_messages_room_id_id
    ON chat_messages (room_id, id DESC);

CREATE INDEX idx_chat_messages_room_id_created_at
    ON chat_messages (room_id, created_at DESC);

client_message_id는 클라이언트가 생성하는 UUID입니다. 네트워크 재전송 시 같은 메시지가 중복 생성되지 않도록 하는 멱등성 키입니다.

읽음 상태

CREATE TABLE chat_room_reads (
    room_id           BIGINT NOT NULL REFERENCES chat_rooms(id),
    user_id           BIGINT NOT NULL REFERENCES users(id),
    last_read_message_id BIGINT NULL REFERENCES chat_messages(id),
    last_read_at      TIMESTAMPTZ NULL,

    PRIMARY KEY (room_id, user_id)
);

1:1 채팅에서는 메시지마다 읽음 행을 만들지 않고, 사용자가 마지막으로 읽은 메시지 ID만 저장합니다.

알림

CREATE TABLE notifications (
    id          BIGSERIAL PRIMARY KEY,
    user_id     BIGINT NOT NULL REFERENCES users(id),
    type        VARCHAR(50) NOT NULL,
    payload     JSONB NOT NULL,
    dedupe_key  VARCHAR(200) NULL,
    read_at     TIMESTAMPTZ NULL,
    created_at  TIMESTAMPTZ NOT NULL DEFAULT now(),

    UNIQUE (user_id, dedupe_key)
);

CREATE INDEX idx_notifications_user_created
    ON notifications (user_id, created_at DESC);

CREATE INDEX idx_notifications_unread
    ON notifications (user_id, created_at DESC)
    WHERE read_at IS NULL;

알림 payload에는 최소한 다음 정보를 포함합니다.

{
  "roomId": 123,
  "messageId": 456,
  "senderId": 789,
  "preview": "안녕하세요"
}

---

3. 메시지 전송 흐름

1. 클라이언트가 WebSocket 또는 REST로 메시지 전송
2. 서버가 room 멤버십과 차단 여부 확인
3. PostgreSQL transaction 시작
4. chat_messages INSERT
5. chat_rooms.last_message_id, updated_at 갱신
6. 상대방 알림 INSERT
7. transaction commit
8. Redis Pub/Sub으로 message.created 발행
9. 각 Gateway가 연결된 사용자에게 WebSocket 전달

메시지 저장이 성공한 뒤에만 실시간 이벤트를 발행해야 합니다. 데이터 저장 전에 이벤트를 보내면 클라이언트가 존재하지 않는 메시지를 보게 될 수 있습니다.

다만 PostgreSQL commit 직후 프로세스가 죽으면 Redis 발행이 누락될 수 있으므로, 운영 환경에서는 Outbox 패턴을 권장합니다.

CREATE TABLE event_outbox (
    id           BIGSERIAL PRIMARY KEY,
    event_type   VARCHAR(100) NOT NULL,
    aggregate_id BIGINT NOT NULL,
    payload      JSONB NOT NULL,
    created_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
    published_at TIMESTAMPTZ NULL
);

CREATE INDEX idx_event_outbox_unpublished
    ON event_outbox (id)
    WHERE published_at IS NULL;

메시지와 Outbox 이벤트를 같은 transaction에서 저장하고, 별도 worker가 Redis에 발행합니다.

---

4. API 설계

대화방 목록

GET /v1/chat/rooms?cursor=123&limit=30

응답:

{
  "data": [
    {
      "roomId": 123,
      "itemId": 88,
      "counterpart": {
        "userId": 42,
        "nickname": "user42"
      },
      "lastMessage": {
        "id": 456,
        "body": "네, 확인했습니다.",
        "createdAt": "2026-09-24T10:00:00Z"
      },
      "unreadCount": 3,
      "updatedAt": "2026-09-24T10:00:00Z"
    }
  ],
  "nextCursor": "456"
}

페이지네이션은 OFFSET 대신 cursor 기반으로 처리합니다.

메시지 이력

GET /v1/chat/rooms/{roomId}/messages?before=456&limit=50

SELECT *
FROM chat_messages
WHERE room_id = $1
  AND id < $2
  AND deleted_at IS NULL
ORDER BY id DESC
LIMIT 50;

메시지 ID가 전역적으로 증가하므로 cursor로 사용하기 좋습니다. 서버에서는 반환 순서를 클라이언트 요구에 맞게 뒤집을 수 있습니다.

메시지 전송

REST fallback과 재시도 지원을 위해 다음 API를 둡니다.

POST /v1/chat/rooms/{roomId}/messages
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

{
  "body": "안녕하세요",
  "messageType": "text",
  "clientMessageId": "550e8400-e29b-41d4-a716-446655440000"
}

응답:

{
  "messageId": 456,
  "roomId": 123,
  "senderId": 10,
  "body": "안녕하세요",
  "createdAt": "2026-09-24T10:00:00Z"
}

읽음 처리

PUT /v1/chat/rooms/{roomId}/read

{
  "lastReadMessageId": 456
}

알림 조회 및 읽음 처리

GET /v1/notifications?cursor=123&limit=30
PUT /v1/notifications/{notificationId}/read
PUT /v1/notifications/read-all

---

5. 읽음 처리 로직

핵심은 클라이언트가 “현재 보고 있는 마지막 메시지 ID”를 서버에 보내는 것입니다.

INSERT INTO chat_room_reads (
    room_id,
    user_id,
    last_read_message_id,
    last_read_at
)
VALUES ($1, $2, $3, now())
ON CONFLICT (room_id, user_id)
DO UPDATE SET
    last_read_message_id = GREATEST(
        chat_room_reads.last_read_message_id,
        EXCLUDED.last_read_message_id
    ),
    last_read_at = CASE
        WHEN EXCLUDED.last_read_message_id >
             chat_room_reads.last_read_message_id
        THEN now()
        ELSE chat_room_reads.last_read_at
    END;

항상 GREATEST를 사용해야 합니다. 네트워크 지연으로 이전 메시지의 읽음 요청이 늦게 도착해도 읽음 위치가 뒤로 가지 않게 합니다.

읽지 않은 메시지 수:

SELECT COUNT(*)
FROM chat_messages m
LEFT JOIN chat_room_reads r
  ON r.room_id = m.room_id
 AND r.user_id = $2
WHERE m.room_id = $1
  AND m.sender_id <> $2
  AND m.deleted_at IS NULL
  AND (
      r.last_read_message_id IS NULL
      OR m.id > r.last_read_message_id
  );

대화방 목록에서 모든 방의 unread count를 매번 COUNT하면 비용이 커질 수 있습니다. 초기에는 위 방식으로 시작하되, 트래픽 증가 시 다음 중 하나를 적용합니다.

• chat_room_members.unread_count를 비정규화하여 관리
• 사용자별 전체 unread count를 Redis에 캐싱
• 읽음 상태를 (room_id, user_id, last_read_message_id) 기준으로 계산하고 방 목록을 제한

읽음 이벤트는 WebSocket으로 상대방에게 전달할 수 있습니다.

{
  "type": "chat.read",
  "roomId": 123,
  "userId": 42,
  "lastReadMessageId": 456
}

---

6. WebSocket 이벤트

연결 시:

wss://api.example.com/realtime
Authorization: Bearer <access-token>

서버는 인증된 사용자 ID를 기준으로 Redis에 연결 정보를 관리합니다.

주요 이벤트:

{
  "type": "chat.message.created",
  "data": {
    "roomId": 123,
    "messageId": 456,
    "senderId": 10,
    "body": "안녕하세요",
    "createdAt": "2026-09-24T10:00:00Z"
  }
}

{
  "type": "notification.created",
  "data": {
    "notificationId": 99,
    "type": "new_chat_message",
    "roomId": 123
  }
}

{
  "type": "chat.read",
  "data": {
    "roomId": 123,
    "userId": 42,
    "lastReadMessageId": 456
  }
}

연결 안정성을 위해 다음을 포함합니다.

• ping/pong heartbeat
• 자동 재연결
• eventId 또는 메시지 ID 기반 중복 제거
• 재연결 시 lastEventId 전달
• 유실 가능성에 대비한 REST 동기화
• 메시지 순서 보장을 위한 room별 messageId 정렬

WebSocket을 신뢰성 있는 저장소로 사용하지 말고, 재연결 후 REST API로 누락 메시지를 보완하는 구조가 안전합니다.

---

7. Redis 채널 설계

간단한 초기 구조:

chat:room:{roomId}
user:{userId}:notifications

Redis Pub/Sub은 전달 보장이 없으므로, 중요한 이벤트 자체를 Redis에만 보관하면 안 됩니다. 메시지 원본은 PostgreSQL에 있고 Redis는 실시간 전달용으로만 사용해야 합니다.

전달 유실 복구가 중요하면 Redis Streams 또는 Outbox worker를 사용합니다.

stream:realtime-events
consumer-group: realtime-gateway

다만 WebSocket 서버가 직접 모든 이벤트를 소비하는 방식은 사용자 라우팅 구조가 복잡해질 수 있으므로, 초기에는 Outbox worker + Redis Pub/Sub로 시작하고 장애 복구 요구가 커질 때 Streams로 확장하는 방식이 현실적입니다.

---

8. 보안 및 운영 필수사항

• 모든 room API에서 사용자의 room 멤버십 검증
• 메시지 본문 길이 제한: 예를 들어 2,000자
• HTML 허용 금지 또는 서버 측 sanitization
• 첨부파일은 메시지 API와 분리하고 object storage 사용
• 사용자별 메시지 전송 rate limit
• WebSocket 연결 및 인증 시도 rate limit
• 차단한 사용자 간 메시지 전송 금지
• JWT 만료 및 WebSocket 재인증 처리
• 로그에 메시지 본문과 토큰 기록 금지
• 메시지 삭제는 soft delete
• 알림 생성은 중복 방지용 dedupe_key 사용

예시 rate limit:

메시지 전송: 사용자당 10초에 30회
WebSocket 연결: IP당 분당 20회
대화방 목록: 사용자당 초당 10회

---

9. 초기 배포 구성

Load Balancer
 ├─ Express API × 3
 ├─ Realtime Gateway × 3
 ├─ Outbox Worker × 2
 ├─ PostgreSQL Primary
 ├─ PostgreSQL Read Replica
 └─ Redis

읽기 트래픽은 replica로 분산할 수 있지만, 메시지 생성 직후 이력 조회나 읽음 처리 직후 상태 조회처럼 read-after-write가 필요한 요청은 잠시 primary를 사용하거나 애플리케이션에서 일관성을 보장해야 합니다.

가장 먼저 구현할 범위는 다음입니다.

1. PostgreSQL 메시지·멤버·읽음 스키마
2. 멱등성을 지원하는 메시지 생성 API
3. cursor 기반 메시지 조회
4. last_read_message_id 방식의 읽음 처리
5. Redis 기반 WebSocket fan-out
6. Outbox 이벤트 발행
7. 재연결 후 메시지 동기화

이 구조면 현재 12만 가입자 규모에서 시작하면서도, 동시 접속 1만 명과 이후 수평 확장에 대응할 수 있습니다.