MQE 상세 사양 가이드 (기술용)

GIIP 메시지 큐 엔진(MQE)의 프로토콜, 데이터 구조 및 신뢰성 보장 메커니즘에 대한 기술 상세 사양을 안내합니다.

🔔 메시지 큐 설정 페이지로 이동 →

📋 개요

**MQE(Message Queue Engine)**는 GIIP 생태계의 신경망 역할을 합니다. 분산된 에이전트들과 중앙 서버 간의 고성능, 고신뢰성 통신을 위해 설계되었으며, 네트워크 불안정 상황에서도 데이터 유실을 최소화하는 기술적 장치들을 포함하고 있습니다.

🛠️ 기술 규격

1. 통신 프로토콜 및 포트

Primary Protocol: AMQP 0-9-1 (RabbitMQ 기반) 또는 AMQP 1.0 (Azure Service Bus 기반)
Port: 5671 (TLS 암호화 통신 필수)
Fallback: 웹소켓(WebSocket) 기반의 HTTPS(443) 통신을 지원하여 방화벽 환경에 대응합니다.

2. 메시지 페이로드 구조 (JSON)

모든 메시지는 아래의 공통 헤더를 포함합니다.

{
  "header": {
    "msgId": "UUID",
    "timestamp": "ISO8601",
    "originNode": "AgentID",
    "priority": "0-9"
  },
  "payload": {
    "type": "METRIC | ISSUE | COMMAND",
    "data": { ... }
  }
}

3. 신뢰성 및 보안

At-Least-Once Delivery: 소비자가 메시지 처리를 완료하고
```
ACK
```
를 보내기 전까지는 큐에서 메시지를 삭제하지 않습니다.
End-to-End Encryption: 페이로드 데이터 영역은 발신 시점에서 AES-256으로 암호화되어 전송될 수 있습니다.
Circuit Breaker: 특정 노드에서 초과 트래픽 발생 시 자동으로 인입을 차단하여 전체 시스템을 보호합니다.

⚙️ 개발자 참고 사항

에이전트 구현: 신규 에이전트를 개발할 경우, 반드시 MQE SDK를 활용하여 하트비트(Heartbeat) 및 재연결(Reconnection) 로직을 구현해야 합니다.
처리 지연 대응: 컨슈머(Consumer) 단의 처리 속도가 느려지면
```
Queue Depth
```
가 증가하므로, 스케일 아웃(Scale-out)을 통해 효율을 높이세요.

문제 해결

증상	원인	해결
5671 포트로 MQE 연결이 실패한다	방화벽이 AMQP(5671) 포트를 차단함	WebSocket 기반 HTTPS(443) Fallback 통신으로 전환한다
동일한 메시지가 중복 처리된다	At-Least-Once 전달 특성상 `ACK` 이전에 재전송됨	컨슈머에서 `msgId` 를 기준으로 멱등성 처리를 구현한다
`Queue Depth` 가 계속 증가한다	컨슈머의 처리 속도가 유입 속도를 따라가지 못함	스케일 아웃(Scale-out)으로 컨슈머를 증설한다
특정 노드의 메시지 인입이 차단된다	초과 트래픽으로 Circuit Breaker가 작동함	트래픽 정상화 후 Heartbeat/재연결 로직을 통해 재접속한다

버전: 1.0 최종 업데이트: 2026-03-19 소스 파일:

giipv3/public/help/mqe-spec.ko.md