Godopu
a9934ad104
- Synthesize collaborative multi-agent architectural analysis in NATS_REPORT.md - Establish Option C: retain MQTT client protocol while adopting nats-server as dedicated broker - Add private server deployment and configuration guide in PRIVATE_SERVER.md - Update IMPROVEMENTS.md with latent defect findings (B-14, B-15, B-16, O-5) and 4-track priority roadmap - Archive durable loop planning and review reports in .agents/reports/
191 lines
7.7 KiB
Markdown
191 lines
7.7 KiB
Markdown
# 🔒 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/...`) 및 무조건 토큰 발급을 적용하여 공개 브로커 위험을 완전히 영구 폐기합니다.
|