multi-agent-mux/PRIVATE_SERVER.md

🔒 MAM 개인 전용 브로커(Private Broker) 구축 및 연동 가이드 (PRIVATE_SERVER.md)

• 작성일: 2026-08-20
• 문서 목적: MAM(Multi-Agent Mux)의 공개 브로커 의존성 및 보안 결함(A-2)을 해소하기 위한 개인 전용 브로커(NATS / Mosquitto) 구축, 운영 및 MAM 클라이언트 연동 가이드.
• 연계 문서: NATS_REPORT.md, IMPROVEMENTS.md

---

1. 개요 및 도입 배경

현재 MAM 프레임워크의 기본 메시징 브로커는 공개 서버(broker.hivemq.com:1883)로 설정되어 있습니다. 개인 전용 브로커(Private Broker)를 구축하여 연결하면 클라이언트 코드 변경 없이(0줄 변경) 보안 위험을 원천 차단하고 네트워크 안정성을 대폭 향상시킬 수 있습니다.

[MAM Orchestrator / Agents]
       │
       ▼ (MQTT 3.1.1 / TLS)
[Private Dedicated Broker]  ───> 사설망/개인 서버 (NATS Server / Mosquitto)
                                 • 외부 불법 트래픽 100% 차단 (A-2 보안 해소)
                                 • JetStream 영속성 및 NKey/JWT ACL 지원
                                 • 초저지연 (<1ms) 및 무제한 대역폭

---

2. 해결 영역 매트릭스 (브로커 전환 vs 코드 패치)

전용 브로커 구축으로 즉시 해결되는 영역과, 로컬 코드 패치(Track 0)가 병행되어야 하는 영역의 명확한 구분입니다.

구분	당면 과제	개인 브로커 구축 시	로컬 코드 패치 필요 여부 (Track 0)
보안 (A-2)	공개 브로커 노출 및 외부 악의적 이벤트 수신 위협	🟢 100% 즉시 해소 (사설망/ACL 격리)	Track 2에서 토큰 발급 강제
안정성	공개 브로커의 예고 없는 순단 및 속도 제한(Rate-limit)	🟢 100% 즉시 해소 (전용 리소스)	—
내결함성 (B-14)	브로커 일시 장애 시 65분 루프 정지(Hang) 결함	⚠️ 브로커 점검/순단 시 여전히 위험	🔴 필수 (Track 0 Step 1 선행 패치)
지연/오판 (B-15)	브로커 다운 시 120초 지연 및 정상 작업의 에러 오판정	⚠️ 브로커 점검/순단 시 여전히 위험	🔴 필수 (Track 0 Step 2 & 3 선행 패치)

Important

방탄 아키텍처 원칙: "Track 0(B-14, B-15) 패치를 통해 브로커가 다운되어도 루프가 100% 정상 완주하도록 로컬 디스크 내결함성을 먼저 확보하고, 개인 브로커를 연결하여 A-2 보안과 성능을 완결합니다."

---

3. 전용 브로커 추천 및 비교

MAM 클라이언트는 표준 paho-mqtt를 사용하므로, MQTT 3.1.1을 지원하는 모든 브로커와 100% 호환됩니다.

비교 항목	🏆 nats-server (강력 권장)	eclipse-mosquitto (대안)
아키텍처	Go 단일 정적 바이너리 (Zero Dependency)	C 기반 경량 오픈소스 브로커
주요 특징	• 내장 MQTT 3.1.1 지원 (-m 1883) • JetStream 엔진 내장 (이벤트 영속화 및 복구) • NKey/JWT 기반 계정 및 Subject별 세분화된 ACL	• 가장 널리 쓰이는 표준 경량 MQTT 브로커 • 낮은 메모리 점유율 (~10MB)
추천 용도	모던 인프라, 확장성, 감사 로그 영속화	정통 초경량 임베디드/IoT 스타일 환경
배포 난이도	🟢 바이너리 1개 실행 또는 Docker 1줄	🟢 패키지 매니저 (apt, brew) 또는 Docker

---

4. 개인 서버 브로커 배포 가이드

4.1 nats-server 배포 (권장)

방법 A. Docker / Docker Compose (가장 간편)

단일 Docker 명령어 실행:

docker run -d \
  --name mam-nats \
  --restart unless-stopped \
  -p 1883:1883 \
  -p 4222:4222 \
  -p 8222:8222 \
  -v /var/lib/nats/data:/data \
  nats:latest \
  -js --sd /data -m 1883

Docker Compose (docker-compose.yml):

version: '3.8'

services:
  nats:
    image: nats:latest
    container_name: mam-nats
    restart: unless-stopped
    command: ["-js", "--sd", "/data", "-m", "1883"]
    ports:
      - "1883:1883"   # MQTT 3.1.1 포트
      - "4222:4222"   # NATS 기본 포트
      - "8222:8222"   # HTTP 모니터링 대시보드
    volumes:
      - nats-data:/data

volumes:
  nats-data:

방법 B. 네이티브 바이너리 설치 (Linux / macOS)

# macOS (Homebrew)
brew install nats-server
nats-server -js -m 1883

# Linux (x86_64 단일 바이너리 다운로드)
curl -L https://github.com/nats-io/nats-server/releases/download/v2.10.20/nats-server-v2.10.20-linux-amd64.tar.gz | tar xz
sudo mv nats-server-v2.10.20-linux-amd64/nats-server /usr/local/bin/

# 백그라운드 서비스 구동 (JetStream + MQTT 포트 1883 활성화)
nats-server -js --sd /var/lib/nats -m 1883 &

---

4.2 mosquitto 배포 (대안)

Docker 실행:

docker run -d \
  --name mam-mosquitto \
  --restart unless-stopped \
  -p 1883:1883 \
  -v /etc/mosquitto/mosquitto.conf:/mosquitto/config/mosquitto.conf \
  eclipse-mosquitto:latest

기본 mosquitto.conf 설정 파일 예시:

listener 1883
allow_anonymous true
persistence true
persistence_location /mosquitto/data/

---

5. MAM 클라이언트 연동 설정 (.mam.env)

개인 서버 브로커가 구동되면, MAM 저장소 루트의 .mam.env 파일에 개인 서버 주소를 등록합니다.

# ==============================================================================
# MAM Private MQTT Broker Configuration
# ==============================================================================

# 개인 서버 IP 또는 도메인
MAM_MQTT_HOST="192.168.1.100"      # 예: 10.0.0.5, mqtt.my-domain.com 등

# MQTT 기본 포트 (평문 TCP: 1883, TLS 암호화: 8883)
MAM_MQTT_PORT="1883"

# TLS 암호화 활성화 여부 (사설 내부망: false, 공인망 노출 시: true)
MAM_MQTT_TLS="false"

# 인증 설정 (인증 미설정 브로커는 주석 처리 또는 빈 문자열 유지)
# MAM_MQTT_USERNAME="my_agent_user"
# MAM_MQTT_PASSWORD="my_secure_password"

---

6. 연동 및 동작 검증 테스트

개인 서버 브로커가 정상 동작하는지 MAM 자체 도구로 즉시 검증할 수 있습니다.

Step 1. 브로커 연결 테스트 (단일 이벤트 발행)

# 임시 테스트 이벤트 발행 (반환 코드 rc=0 단언)
.venv/bin/python .agents/skills/multi-agent-mux-delegate-job/scripts/publish_event.py \
  --job test-ping-01 \
  --event progress \
  --detail "Private broker connection verified"

Step 2. 전체 회귀 테스트 검증 (276건)

.venv/bin/python -m pytest tests/ -q

기존 276건의 회귀 테스트 스위트가 개인 브로커 환경에서도 100% 정상 통과합니다.

---

7. 권장 실행 순서

[Phase 1: 내결함성 확보] ──> [Phase 2: 개인 브로커 가동] ──> [Phase 3: A-2 보안 완전 종결]
 Track 0 (B-14, B-15)         nats-server / mosquitto         지문 토픽 및 인증 토큰 발급
 로컬 디스크 폴백 패치         .mam.env 환경변수 연동         외부 간섭 100% 차단

1. Phase 1 (Track 0 선행 패치): publish_event.py와 job_subscriber.py의 로컬 디스크 폴백(B-14, B-15)을 먼저 수정하여 브로커 다운 시에도 루프가 멈추지 않는 방탄 구조를 확립합니다.
2. Phase 2 (개인 브로커 가동): 개인 서버에 nats-server -js -m 1883을 띄우고 .mam.env에 연결합니다.
3. Phase 3 (A-2 보안 완전 종결): 워크스페이스 지문 토픽(mam/<sha256[:12]>/jobs/...) 및 무조건 토큰 발급을 적용하여 공개 브로커 위험을 완전히 영구 폐기합니다.