본문으로 건너뛰기
서명인

← 프로젝트 목록

분산 에이전트 원격 관리와 무중단 패치

기간, 인원, 역할: 2025.11 – 2026.03 · 6인 · 에이전트 · 원격 제어 · 패치 담당

기간
5개월
팀
6명
운영 장비
200대
장비당 모듈
4종 (각자 JVM)
지원 OS
Windows XP~7 · Red Hat
  • Java
  • Spring Boot
  • SQLite
  • WebSocket
  • Airflow
장비 1대에서200대 운영

시범 검증 후 확대 운영 중

  1. OS가 제각각(Windows XP ~ 7, Red Hat)이고 자원이 넉넉하지 않은 장비 컴퓨터마다 프로그램을 설치해, 로그를 모으고 원격으로 관리 · 업데이트해야 했습니다.
  2. 장비마다 Java 8 에이전트(모듈)를 프로세스별로 나눠 띄우고, 중앙 서버가 REST API로 받은 하트비트를 WebSocket으로 화면에 실시간 반영하며 원격 제어와 원자적 패치 · 자동 롤백을 하게 만들었습니다.
  3. 장비 1대로 검증한 뒤 지금은 장비 200대에서 운영 중이며, 업데이트 도중 문제가 생겨도 이전 버전으로 자동 복구됩니다.

배경과 문제

OS가 제각각인 장비 컴퓨터 200대 규모에 에이전트를 배포해, 로그를 모으고 원격으로 제어 · 업데이트하는 분산 시스템입니다.

도메인 배경: 반도체 후공정(OSAT, 칩 조립 · 검사 공정) 고객사의 시스템입니다. 고객사는 기존에 상용 솔루션을 쓰고 있었는데, 비용을 줄이기 위해 자체 시스템으로 바꾸기로 했습니다.

장비마다 컴퓨터가 한 대씩 붙어 있고, 측정 로그는 이 장비 컴퓨터에 쌓입니다. 프로젝트 전체의 목표는 이렇습니다.

  1. 서버실에 메인 서버를 두고, 장비 컴퓨터의 로그를 메인 서버로 가져옵니다.
  2. 로그를 파싱해 화면에 시각화하고 DB에 저장합니다.
  3. 쌓인 데이터로 AI 학습 · 추론을 해서 수율(양품 비율)을 올립니다.

이 중 1단계는 장비의 로그를 빠짐없이, 장비에 부담 없이 모으는 기반을 만드는 일이었습니다.

AI 학습 · 추론은 이 시스템으로 데이터가 쌓여야 할 수 있어서, 개발 기간 동안 AI 팀은 STDF(장비 측정 결과 파일 형식) 파일로 따로 테스트하며 준비했습니다.

팀 구성과 내 역할

6인이 진행했습니다. 저는 각 장비 컴퓨터에 들어가는 모듈과, 메인 서버에서 그 모듈들을 원격으로 제어 · 패치 · 헬스체크하는 부분을 맡았습니다. 장비 모듈 중 controller와 sender를 직접 만들었고, 나머지 모듈이 함께 쓰는 공통 골격을 설계했습니다. Airflow 배치 수집 파이프라인은 기본 작업과 틀을 만든 뒤 팀원에게 인수인계했습니다. 장비 자체를 통제하는 operator 모듈은 다른 팀원이 개발했습니다.

시스템 구조도

장비 컴퓨터마다 Java 8로 controller, worker, sender, operator 모듈이 돈다. worker가 폴더를 감지해 필요한 데이터를 SQLite에 저장하고 sender가 로그를 압축해 메인 서버의 FTP로 실시간 전송한다. worker가 모은 데이터는 Kafka로 메인 서버에 보낸다. controller는 하트비트와 로그를 REST API로 보내고, 관리 서버가 이를 받아 변경분만 WebSocket으로 관리 화면에 보내며 controller에 제어·패치 명령을 내린다. 메인 서버의 Airflow는 FTP로 받은 파일을 STDF 파싱해 PostgreSQL에 적재한다.장비 컴퓨터마다 Java 8로 controller, worker, sender, operator 모듈이 돈다. worker가 폴더를 감지해 필요한 데이터를 SQLite에 저장하고 sender가 로그를 압축해 메인 서버의 FTP로 실시간 전송한다. worker가 모은 데이터는 Kafka로 메인 서버에 보낸다. controller는 하트비트와 로그를 REST API로 보내고, 관리 서버가 이를 받아 변경분만 WebSocket으로 관리 화면에 보내며 controller에 제어·패치 명령을 내린다. 메인 서버의 Airflow는 FTP로 받은 파일을 STDF 파싱해 PostgreSQL에 적재한다.
메인 서버와 장비별 모듈 배치도크게 보기 (새 창)크게 보기 (새 창)
  • 장비 컴퓨터 (Java 8): 장비마다 아래 모듈이 각자의 JVM으로 실행됩니다.

    • controller: 다른 모듈을 관찰 · 기동 · 정지하고, 메인 서버로 하트비트와 로그를 REST API로 보냄
    • worker: 특정 폴더를 지켜보다 새 로그가 생기면 필요한 데이터만 장비 쪽 SQLite에 저장하고, 데이터를 Kafka로 메인 서버에 전송
    • sender: 감지된 로그를 압축해 메인 서버로 실시간 전송
    • operator: 장비 자체를 통제
  • 메인 서버 (Java 17 · Spring Boot 3.1): 모듈 상태와 패치를 통제. 장비에서 REST API로 들어오는 헬스체크 · 로그를 받아, 변경분을 WebSocket(STOMP/SockJS)으로 화면에 전달

  • 배치 수집: 메인 서버의 Airflow가 주기적으로 로그 수집 → STDF 파싱(Polars) → DB 적재

  • 화면: React 18 · TypeScript · Zustand · React Query

내가 맡은 일

2025.11 – 2026.03

  • 런타임 선정: Windows XP · Vista · 7과 Red Hat이 섞인 장비 컴퓨터에서 모두 돌고 메모리를 적게 쓰도록 장비 모듈을 Java 8로 결정
  • 관리 에이전트(controller) 개발: 장비 컴퓨터의 다른 모듈을 관찰 · 기동 · 정지하고, 메인 서버로 하트비트 · 로그를 REST API로 보내는 관리 모듈
  • 전송 에이전트(sender) 개발: worker가 감지한 로그를 압축해 메인 서버로 실시간 전송. 속도를 위해 GZIP · LZ4 · ZSTD 중 압축 방식을 고를 수 있게 구현 (Apache FtpServer)
  • 모듈 공통 골격 설계: 나머지 모듈이 함께 쓰는 설정 로딩, 파일 감지 루프, 전송 표준 패턴
  • 프로세스 격리: 하나의 JVM에 모든 모듈을 띄우던 구조를 모듈별 JVM으로 나눠, 한 모듈의 장애와 패치가 다른 모듈에 번지지 않게 함
  • 무중단 배포: 라이프사이클 상태머신과 원자적 JAR 교체. 패치 도중 장애가 나도 이전 버전으로 자동 롤백하고, 기동 시 자동 복구
  • 실시간 상태 표시: 장비 서버의 헬스체크 · 로그를 REST API로 받아, 변경분만 WebSocket으로 화면에 보내 모듈 상태를 실시간 반영
  • 관리 화면: 장비×모듈 일괄 제어 · 패치 UI
  • 배치 수집 파이프라인 기반 작업: Airflow 수집 파이프라인(30분 주기 수집, 측정 파일(STDF) 파싱, DB 적재, 실패 시 재시도)의 기본 작업과 틀을 만든 뒤 팀원에게 인수인계

모듈 라이프사이클 상태

controller는 각 모듈을 아래 상태 중 하나로 관리하고, 상태를 하트비트로 메인 서버에 알립니다. 이 헬스체크는 REST API로 들어오고, 메인 서버는 바뀐 부분만 화면에 보내므로, 장비가 200대여도 화면이 실시간으로 갱신됩니다.

상태 의미 다음 상태
STOPPED 꺼져 있음 기동 명령 → STARTING · 패치 명령 → PATCHING
STARTING 프로세스를 띄우는 중 정상 응답 → RUNNING · 기동 실패 → ERROR
RUNNING 정상 동작 중 정지 명령 → STOPPING · 프로세스 이상 → ERROR
STOPPING 하던 작업을 마무리하고 끄는 중 종료 완료 → STOPPED
PATCHING 새 버전으로 교체하는 중 교체 성공 → STARTING · 실패 → 롤백 후 STARTING
ERROR 비정상 종료 · 응답 없음 재기동 → STARTING
모듈 상태 전이: STOPPED에서 기동 명령이면 STARTING, 패치 명령이면 PATCHING. PATCHING은 교체 성공이나 롤백 후 STARTING. STARTING은 정상 응답이면 RUNNING, 실패하면 ERROR. RUNNING은 정지 명령이면 STOPPING, 프로세스 이상이면 ERROR. STOPPING은 종료 후 STOPPED, ERROR는 재기동으로 STARTING.모듈 상태 전이: STOPPED에서 기동 명령이면 STARTING, 패치 명령이면 PATCHING. PATCHING은 교체 성공이나 롤백 후 STARTING. STARTING은 정상 응답이면 RUNNING, 실패하면 ERROR. RUNNING은 정지 명령이면 STOPPING, 프로세스 이상이면 ERROR. STOPPING은 종료 후 STOPPED, ERROR는 재기동으로 STARTING.
모듈 상태 전이도크게 보기 (새 창)크게 보기 (새 창)

패치 순서

관리 화면에서 장비와 모듈을 골라 패치를 누르면, 각 장비의 controller가 아래 순서로 교체합니다. 어느 단계에서 중단되더라도 실행 중인 파일은 보존됩니다.

  1. 스테이징: 새 버전 JAR를 내려받아 기존 파일 옆에 .new 파일로 둡니다. 이 단계에서 실패하면 .new만 지우면 됩니다.
  2. 무결성 검증: 내려받은 파일이 온전한지 확인합니다. 실패하면 교체하지 않고 끝냅니다.
  3. 정지: 대상 모듈만 STOPPING → PATCHING으로 바꿉니다. 모듈마다 JVM이 따로라 다른 모듈은 계속 돕니다.
  4. 원자적 교체: 기존 JAR를 이전 버전으로 남겨 두고, .new를 실행 파일 자리로 한 번에 옮깁니다.
  5. 기동 확인: 새 버전으로 띄워 RUNNING이 되면 완료입니다. 뜨지 않으면 이전 버전으로 롤백해 다시 띄웁니다.
  6. 자동 복구: 패치 도중 장비가 꺼졌다면, controller가 다시 기동할 때 남아 있는 .new와 이전 버전 파일을 보고 마지막 정상 상태로 되돌립니다.
관리 화면에서 패치를 요청하면 메인 서버가 controller에 패치 명령을 보낸다. controller는 새 JAR를 .new로 스테이징하고 무결성을 검증한 뒤 대상 모듈을 정지하고 원자적으로 교체해 새 버전을 기동한다. 기동에 실패하면 이전 버전으로 롤백한다. 결과는 하트비트로 메인 서버에 보고되어 화면에 반영된다. 패치 중 꺼졌다면 재기동 시 마지막 정상 상태로 복구한다.관리 화면에서 패치를 요청하면 메인 서버가 controller에 패치 명령을 보낸다. controller는 새 JAR를 .new로 스테이징하고 무결성을 검증한 뒤 대상 모듈을 정지하고 원자적으로 교체해 새 버전을 기동한다. 기동에 실패하면 이전 버전으로 롤백한다. 결과는 하트비트로 메인 서버에 보고되어 화면에 반영된다. 패치 중 꺼졌다면 재기동 시 마지막 정상 상태로 복구한다.
패치 시퀀스크게 보기 (새 창)크게 보기 (새 창)

기술 선택과 이유

장비 모듈은 Java 8, 메인 서버는 Java 17

프로젝트를 시작하기 전 가장 큰 고민은 장비 컴퓨터였습니다.

  • 운영체제가 제각각이었습니다. Windows XP · Vista · 7과 Red Hat이 섞여 있어, 모든 환경에서 도는 언어와 버전이 필요했습니다.
  • 가벼워야 했습니다. 장비를 돌리는 컴퓨터라, 우리 프로그램이 메모리를 많이 잡아먹으면 안 됐습니다.

그래서 장비 모듈은 오래된 OS까지 지원하면서 관리하기 쉬운 Java 8로 정했습니다. 장비 제약이 없는 메인 서버는 Java 17 · Spring Boot 3.1을 썼습니다.

장비 쪽 저장소는 SQLite

장비 컴퓨터에는 용량을 최소화하려고 필요한 데이터만 담았고, 별도 서버 설치가 필요 없는 파일 기반 DB인 SQLite를 썼습니다.

실시간 전송과 배치 수집을 나눈 구조

  • 실시간: sender가 감지된 로그를 바로 압축해 보냅니다. 속도가 중요해 GZIP · LZ4 · ZSTD 중 압축 방식을 고를 수 있게 했습니다.
  • 배치: 메인 서버의 Airflow가 주기적으로 수집합니다.

상태 보고는 REST API, 데이터 전송은 Kafka

통신 경로를 용도에 따라 나눴습니다.

  • 헬스체크 · 로그: 장비 서버와 모듈의 상태, 모듈 로그는 controller가 메인 서버의 REST API로 보냅니다. 저는 이 API로 받은 상태를 바뀐 부분만 WebSocket으로 보내 화면에 실시간으로 표시하는 부분을 맡았습니다.
  • 수집 데이터: worker가 모은 데이터는 Kafka를 통해 메인 서버로 전송합니다.

기술적 난제와 해결

하나의 JVM에 모든 모듈을 띄웠다가 프로세스를 나눈 일

  • 상황 처음에는 controller 안에서 worker · sender · operator를 함께 돌렸습니다. 모든 모듈이 하나의 JVM에 떠 있는 구조였습니다.
  • 원인 모듈을 나눈 이유는 서로 독립적으로 돌게 하려는 것이었는데, 첫 구현에서는 이 설계 의도를 프로세스 구조까지 반영하지 못했습니다. 그래서 모듈 하나만 죽어도 전체가 죽었고, 하나만 고쳐도 모든 모듈을 함께 패치해야 했습니다.
  • 해결 개발 중에 이 문제를 확인하고, 직접 모듈마다 JVM을 따로 띄우고, controller가 각 모듈을 관찰하면서 메인 서버로 하트비트를 보내는 구조로 바꿨습니다. 모듈 상태는 RUNNING · STARTING · STOPPING · ERROR 등으로 남깁니다.
  • 결과 한 모듈의 장애가 다른 모듈로 번지지 않고, 모듈 하나만 골라 패치할 수 있게 됐습니다. 이 구조가 무중단 패치의 바탕이 됐습니다.

성과

  • 시범 장비 1대(4개 모듈, 측정 파일 40건 자동 수집과 적재)로 검증한 뒤, 현재 장비 200대 규모로 확대 운영 중
  • OS가 제각각인 장비 컴퓨터(Windows XP ~ 7, Red Hat)에서 같은 모듈로 동작
  • 모듈별 프로세스 분리로 장애 격리, 모듈 단위 패치
  • 패치 도중 어느 시점에 중단돼도 실행 파일이 보존되는 무중단 배포 구조

회고

  • 잘한 점: 개발을 시작하기 전에 장비 환경의 제약부터 확인했습니다. OS가 제각각이고 메모리가 적다는 점을 보고 Java 8과 SQLite를 정했습니다. 앞 프로젝트에서 배운 “사용 환경부터 먼저 본다”를 이번에는 처음부터 적용했습니다.
  • 아쉬운 점: 모듈을 나눈 설계 의도를 프로세스 구조까지 반영하지 못해, 개발 중에 구조를 다시 잡아야 했습니다.
  • 다음에는: 구현에 들어가기 전에 설계 의도를 “모듈 하나가 죽으면 나머지는 어떻게 되나”, “모듈 하나만 업데이트할 수 있나” 같은 운영 상황 질문으로 바꿔, 구조가 그 답을 지키는지부터 확인하겠습니다.