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

- **작성일**: 2026-08-20
- **문서 목적**: MAM(Multi-Agent Mux)의 공개 브로커 의존성 및 보안 결함(A-2)을 해소하기 위한 개인 전용 브로커(NATS / Mosquitto) 구축, 운영 및 MAM 클라이언트 연동 가이드.
- **연계 문서**: [`NATS_REPORT.md`](NATS_REPORT.md), [`IMPROVEMENTS.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`)<br>• JetStream 엔진 내장 (이벤트 영속화 및 복구)<br>• NKey/JWT 기반 계정 및 Subject별 세분화된 ACL | • 가장 널리 쓰이는 표준 경량 MQTT 브로커<br>• 낮은 메모리 점유율 (~10MB) |
| **추천 용도** | 모던 인프라, 확장성, 감사 로그 영속화 | 정통 초경량 임베디드/IoT 스타일 환경 |
| **배포 난이도** | 🟢 바이너리 1개 실행 또는 Docker 1줄 | 🟢 패키지 매니저 (`apt`, `brew`) 또는 Docker |

---

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

### 4.1 `nats-server` 배포 (권장)

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

**단일 Docker 명령어 실행:**
```bash
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`):**
```yaml
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)

```bash
# 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 실행:
```bash
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` 설정 파일 예시:**
```conf
listener 1883
allow_anonymous true
persistence true
persistence_location /mosquitto/data/
```

---

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

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

```bash
# ==============================================================================
# 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. 브로커 연결 테스트 (단일 이벤트 발행)
```bash
# 임시 테스트 이벤트 발행 (반환 코드 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건)
```bash
.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/...`) 및 무조건 토큰 발급을 적용하여 공개 브로커 위험을 완전히 영구 폐기합니다.