Skip to main content
Version: LinkBoard 개발 중

아키텍처 개요

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으로 제공합니다.
EMQXMQTT 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) — 룰 처리 부하 분산

자세한 프로덕션 배포·확장 방법은 셀프호스팅 배포를 참고하세요.