PlatformUpdated 2026-04-01
websocket 템플릿
CtrlPlus 플랫폼의 실시간 통신 아키텍처 — MQTT over WebSocket, Spring Boot STOMP, Next.js 클라이언트 연동
Multi-tenantMariaDBSpring BootJWT
1. 전체 흐름
Bash
| 채널 | 프로토콜 | 용도 |
|---|---|---|
| ESP32 → Broker | MQTT TCP 1883 | 센서 텔레메트리 발행 |
| Broker → Spring | MQTT Subscribe | 내부 인바운드 처리 |
| Spring → Client | STOMP over WS | 대시보드 실시간 푸시 |
| FastAPI → Client | SSE | IFMS AI 에이전트 스트리밍 |
2. Spring Boot — STOMP WebSocket 설정
2-1. 의존성
Bash
2-2. WebSocketConfig
Java
2-3. MQTT → STOMP 브리지
Java
2-4. MQTT 인바운드 채널 설정
Java
2-5. Security 예외 처리
Java
3. Next.js — STOMP 클라이언트
3-1. 의존성
Bash
3-2. useMqttSocket 훅
TypeScript
3-3. 텔레메트리 실시간 차트 예시
TypeScript
4. MQTT 토픽 규칙
ctrlplus/{domain}/{deviceId}/{type}
| 필드 | 값 예시 | 설명 |
|---|---|---|
| domain | farm | factory | robot | 서브 플랫폼 |
| deviceId | device-001 | 디바이스 고유 ID |
| type | telemetry | status | command | 메시지 종류 |
토픽 예시
| MQTT 토픽 | STOMP 목적지 | 방향 |
|---|---|---|
ctrlplus/farm/device-001/telemetry | /topic/farm/device-001 | ESP32 → Client |
ctrlplus/farm/device-001/status | /topic/farm/device-001/status | ESP32 → Client |
ctrlplus/farm/device-001/command | /app/farm/command | Client → ESP32 |
5. 액추에이터 제어 (Client → ESP32)
5-1. Spring Controller
Java
Java
5-2. Next.js 액추에이터 패널
TypeScript
6. FastAPI SSE — IFMS AI 스트리밍
6-1. FastAPI 엔드포인트
Python
6-2. Next.js SSE 훅
TypeScript
7. Nginx WebSocket 프록시 설정
nginx
8. ESP32-S3 MQTT 발행 (PlatformIO)
C++
9. 환경 변수
Bash
10. 패턴 요약
| 시나리오 | 프로토콜 | 훅 / 설정 |
|---|---|---|
| 센서 실시간 수신 | STOMP/WS | useMqttSocket |
| 액추에이터 명령 전송 | STOMP/WS publish | useMqttSocket.publish |
| AI 분석 스트리밍 | SSE | useIFMSStream |
| ESP32 발행 | MQTT TCP | PubSubClient |
| WS 프록시 | Nginx upgrade | proxy_http_version 1.1 |