아키텍처 개요
LinkBoard는 여러 서비스로 구성된 시스템입니다. 이 페이지는 전체 구성요소와 데이터 흐름을 한눈에 정리합니다. 개별 개념은 멀티테넌시 & 자산 계층, 텔레메트리 수집, Rule Engine, 엣지 게이트웨이 문서를 참고하세요.
구성요소
┌──────────────────────┐
현장 장비 │ 프론트엔드 (React) │
(PLC·센서·OPC-UA·MQTT) │ Vite · Nginx 정적 │
│ └───────────┬──────────┘
│ Modbus/OPC-UA/... │ REST /api/v1 · WS /ws
▼ ▼
┌───────────────┐ MQTT ┌─────────────────────────────┐
│ linkboard- │──────────▶ │ EMQX (MQTT 5.0) │
│ gateway (엣지) │ └──────────────┬──────────────┘
└───────────────┘ │ 구독
▼
┌─────────────────────────────┐
HTTP/WS 텔레메트리 ───────▶ │ 백엔드 (FastAPI) │
│ API 프로세스 + 워커 프로세스 │
└───┬─────────┬─────────┬───────┘
▼ ▼ ▼
PostgreSQL Redis Celery
+ TimescaleDB (캐시/큐/ (백그라운드
(시계열) pub·sub) 작업·스케줄러)
| 구성요소 | 역할 |
|---|---|
| 프론트엔드 | React 18 + Vite SPA. 프로덕션은 Nginx가 정적 서빙하고 /api·/ws를 백엔드로 리버스프록시합니다. |
| 백엔드 | FastAPI(비동기). 전 기능을 /api/v1 REST + /ws WebSocket으로 제공합니다. |
| EMQX | MQTT 5.0 브로커. 장치·게이트웨이의 MQTT 텔레메트리 진입점이며, 백엔드가 구독합니다. |
| PostgreSQL + TimescaleDB | 관계형 데이터 + 텔레메트리 하이퍼테이블(시계열). |
| Redis | 캐시, 실시간 pub/sub(WebSocket 팬아웃), Rule Engine 스트림 큐, 분산 락. |
| Celery | 백그라운드 작업 및 스케줄러(예약 RPC·보존 정리 등). |
| linkboard-gateway | 현장 프로토콜을 MQTT로 변환해 중계하는 별도 엣지 게이트웨이. |
API 프로세스와 워커 프로세스
백엔드는 두 종류의 작업을 수행합니다 — HTTP/WS 요청 처리(API)와 백그라운드 처리(MQTT 구독·스케줄러·
Rule 스트림 소비). 단일 컨테이너/개발 환경에서는 한 프로세스가 둘 다 맡습니다
(RUN_BACKGROUND_WORKERS=true, 기본값).
수평 확장 시에는 API 컨테이너를 RUN_BACKGROUND_WORKERS=false로 무상태(stateless)화해 여러 개로
늘리고, 백그라운드 처리는 별도 워커 컨테이너(python -m app.worker)가 전담합니다. 중복 처리는 다음
장치로 방지합니다.
- MQTT 공유 구독(
$share/{group}/…) — 한 메시지를 워커 중 하나만 처리 - 스케줄러 분산 락(
lock:scheduler:tick, Redis) — 매 tick을 한 인스턴스만 실행 - Rule 스트림 소비자 그룹(Redis Stream) — 룰 처리 부하 분산
자세한 프로덕션 배포·확장 방법은 셀프호스팅 배포를 참고하세요.