분산 에이전트 원격 관리와 무중단 패치
기간, 인원, 역할: 2025.11 – 2026.03 · 6인 · 에이전트 · 원격 제어 · 패치 담당
- 기간
- 5개월
- 팀
- 6명
- 운영 장비
- 200대
- 장비당 모듈
- 4종 (각자 JVM)
- 지원 OS
- Windows XP~7 · Red Hat
- Java
- Spring Boot
- SQLite
- WebSocket
- Airflow
한눈에 보기
시범 검증 후 확대 운영 중
- OS가 제각각(Windows XP ~ 7, Red Hat)이고 자원이 넉넉하지 않은 장비 컴퓨터마다 프로그램을 설치해, 로그를 모으고 원격으로 관리 · 업데이트해야 했습니다.
- 장비마다 Java 8 에이전트(모듈)를 프로세스별로 나눠 띄우고, 중앙 서버가 REST API로 받은 하트비트를 WebSocket으로 화면에 실시간 반영하며 원격 제어와 원자적 패치 · 자동 롤백을 하게 만들었습니다.
- 장비 1대로 검증한 뒤 지금은 장비 200대에서 운영 중이며, 업데이트 도중 문제가 생겨도 이전 버전으로 자동 복구됩니다.
배경과 문제
OS가 제각각인 장비 컴퓨터 200대 규모에 에이전트를 배포해, 로그를 모으고 원격으로 제어 · 업데이트하는 분산 시스템입니다.
도메인 배경: 반도체 후공정(OSAT, 칩 조립 · 검사 공정) 고객사의 시스템입니다. 고객사는 기존에 상용 솔루션을 쓰고 있었는데, 비용을 줄이기 위해 자체 시스템으로 바꾸기로 했습니다.
장비마다 컴퓨터가 한 대씩 붙어 있고, 측정 로그는 이 장비 컴퓨터에 쌓입니다. 프로젝트 전체의 목표는 이렇습니다.
- 서버실에 메인 서버를 두고, 장비 컴퓨터의 로그를 메인 서버로 가져옵니다.
- 로그를 파싱해 화면에 시각화하고 DB에 저장합니다.
- 쌓인 데이터로 AI 학습 · 추론을 해서 수율(양품 비율)을 올립니다.
이 중 1단계는 장비의 로그를 빠짐없이, 장비에 부담 없이 모으는 기반을 만드는 일이었습니다.
AI 학습 · 추론은 이 시스템으로 데이터가 쌓여야 할 수 있어서, 개발 기간 동안 AI 팀은 STDF(장비 측정 결과 파일 형식) 파일로 따로 테스트하며 준비했습니다.
팀 구성과 내 역할
6인이 진행했습니다. 저는 각 장비 컴퓨터에 들어가는 모듈과, 메인 서버에서 그 모듈들을 원격으로 제어 · 패치 · 헬스체크하는 부분을 맡았습니다. 장비 모듈 중 controller와 sender를 직접 만들었고, 나머지 모듈이 함께 쓰는 공통 골격을 설계했습니다. Airflow 배치 수집 파이프라인은 기본 작업과 틀을 만든 뒤 팀원에게 인수인계했습니다. 장비 자체를 통제하는 operator 모듈은 다른 팀원이 개발했습니다.
시스템 구조도
-
장비 컴퓨터 (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 |
패치 순서
관리 화면에서 장비와 모듈을 골라 패치를 누르면, 각 장비의 controller가 아래 순서로 교체합니다. 어느 단계에서 중단되더라도 실행 중인 파일은 보존됩니다.
- 스테이징: 새 버전 JAR를 내려받아 기존 파일 옆에
.new파일로 둡니다. 이 단계에서 실패하면.new만 지우면 됩니다. - 무결성 검증: 내려받은 파일이 온전한지 확인합니다. 실패하면 교체하지 않고 끝냅니다.
- 정지: 대상 모듈만
STOPPING→PATCHING으로 바꿉니다. 모듈마다 JVM이 따로라 다른 모듈은 계속 돕니다. - 원자적 교체: 기존 JAR를 이전 버전으로 남겨 두고,
.new를 실행 파일 자리로 한 번에 옮깁니다. - 기동 확인: 새 버전으로 띄워
RUNNING이 되면 완료입니다. 뜨지 않으면 이전 버전으로 롤백해 다시 띄웁니다. - 자동 복구: 패치 도중 장비가 꺼졌다면, controller가 다시 기동할 때 남아 있는
.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를 정했습니다. 앞 프로젝트에서 배운 “사용 환경부터 먼저 본다”를 이번에는 처음부터 적용했습니다.
- 아쉬운 점: 모듈을 나눈 설계 의도를 프로세스 구조까지 반영하지 못해, 개발 중에 구조를 다시 잡아야 했습니다.
- 다음에는: 구현에 들어가기 전에 설계 의도를 “모듈 하나가 죽으면 나머지는 어떻게 되나”, “모듈 하나만 업데이트할 수 있나” 같은 운영 상황 질문으로 바꿔, 구조가 그 답을 지키는지부터 확인하겠습니다.
서명인