Nodemanager
nodemanager
Overview
HPCMATE의 노드 원격 관리 웹 콘솔. 일반 사용자가 웹 브라우저에서 Linux 노드를 모니터링하고 관리할 수 있습니다.
요약
- 무엇인가: Linux 노드 모니터링 + 원격 관리 WebUI (Node.js + Express + WebSocket + RequireJS)
- 왜 필요한가: SSH 없이 웹에서 노드 상태 확인, 계정/패키지/컨테이너 관리, 감사 로그 조회
- 언제 사용하는가: HPCMATE 노드/클러스터 운영 · GPU 서버 모니터링 · 원격 관제
조사 정보
- 작성일: 2026-10-17
- 버전: v0.1.0 (Phase 9 S1 완료 상태)
- 다음 업데이트: Phase 9 S2(크로스노드 실시간) 구현 시
Purpose
- Goal: SSH 없이 웹에서 노드 전체(성능·계정·패키지·컨테이너·저장·로그·감사)를 관리
- Scope: 단일 노드 원격 관리 + 멀티노드 레지스트리(Phase 9 S1)
- Non-goals: 원격 명령 평면(S3), 클러스터 오케스트레이션(K8s), GPU 조도 관리
Key Concepts
| 개념 ! 설명 ! 관련 |
|---|
| topic/REST/DB에 노드 차원(`self`) 포함 — 멀티노드 전환 시 마이그레이션 없음 | Server |
| 서버 측 수신자별 필터 — 비admin은 권한 밖 토픽 drop(fail-closed) | Network |
| 특권 명령 단일 직렬 큐 — shell 불경유(arg 배열) 인젝션 차단 | Linux |
| admin(`nm-admin` 그룹) vs user(읽기 + 매핑된 Docker 리소스) | Linux |
| 현재 community tier, maxNodes=1 — 실 구현은 독립 라이선스 프로그램 연계 예정 | Server |
Architecture
Browser (RequireJS, eventemitter3 bus)
⇄ WebSocket /ws?token= + REST /api
Node Server
├─ collectors/ (2s/5s 주기, systeminformation / nvidia-smi)
├─ bus (EventEmitter — 모든 데이터의 hub)
├─ ws.js (relay — 수신자별 서버 측 필터)
├─ svc/ (users | packages | services | docker | quotas | mapping | nodes)
├─ cmd/runner (특권 명령 단일 직렬 큐, arg 배열만)
├─ lic/ (라이선스 인터페이스, stub: community/1node)
└─ db (SQLite: nodes, audit, tokens, mappings, quotas)
Views (화면)
로그인
노드 로컬 계정으로 로그인 (실 shadow 검증).
Dashboard
실시간 성능 모니터링. CPU·메모리·GPU(4개, 색상별)·네트워크(2 인터페이스)·파일시스템·상위 프로세스를 실시간 차트로 표시.
Users
로컬 계정 CRUD. 계정 생성/수정/삭제, 비밀번호 설정, 잠금/해제. root는 WebUI에서 보호됨.
Packages / Services
패키지 검색·설치·업그레이드·제거 (apt/dnf/yum/pacman/apk 자동 감지) + systemd 서비스 관리 (start/stop/restart/enable/disable). 작업 진행도는 WebSocket으로 실시간 스트리밍.
Docker
컨테이너/이미지 CRUD. pull 진행도, 실시간 상태·로그. dockerode 경유.
Docker Mapping
사용자 ↔ 컨테이너/이미지 접근 권한 매핑 (view / exec / manage). 비admin의 Docker 접근 통로.
Storage Quota
사용자별 저장 공간 할당·사용량·한도. 80%/90%/100% 초과 시 알림.
Logs / Security
journalctl 실시간 스트리밍 + 보안 이벤트 피드 (로그인 실패, 403, 스로틀). admin 전용.
Log Analysis
수집된 로그를 패턴으로 디코딩 — OOM, 디스크 I/O, segfault, 유닛 실패, 마운트, 네트워크, 인증 오류를 감지하고 한국어 진단 + 권장 조치를 제공.
BMC
기본 관리 컨트롤러(BMC) 접근. 이노텍 DCIM 등.
Audit
관리 작업 감사 로그 (15초 자동 갱신). 로그인 성공/실패, 계정/패키지/컨테이너/쿼터/매핑/노드 작업 전부 기록.
Nodes (Phase 9 S1)
멀티노드 레지스트리 + 라이선스 관리 + 온보딩. 라이선스 상한 내 노드 등록, 10초 주기 health 프로브, 실시간 상태.
Roles & RBAC
| 리소스 ! user (비admin) ! admin | ||||||
|---|---|---|---|---|---|---|
| ✅ | ✅ | ✅ | ✅ | ❌ 403 | ✅ | ✅ (매핑된 리소스만) | ✅ 전체 | ❌ 403 | ✅ | ❌ 403 | ✅ | ❌ 403 | ✅ |
- 인증: 로컬 노드 계정 (pam → python3 shadow 폴백)
- 세션: 32B 랜덤 토큰, TTL 기본 12시간
- 스로틀: 10분 내 실패 5회 → 60초 잠금 (429)
- WS: `/ws?token=...` — 토큰 부재/만료 시 close `4401`
Deployment
프로덕션 (Docker)
docker build -t nodemanager .
docker run -d --name nodemanager --privileged --net=host \
-v nm-data:/var/lib/nodemanager \
-v /var/run/docker.sock:/app/docker.sock \
nodemanager
- `--net=host` 필수 — host NIC 가시성 + `-p` 불필요
- GPU: `deploy/gpu/`에 바이너리+라이브러리 이미지에 베이킹 (재조성 시 소실 없음)
- 관리자: `docker exec nodemanager usermod -aG nm-admin <user>`
- WebUI: `http://<host>:8080`
개발 (host mount)
docker run -i --rm --name nm-dev --privileged --net=host \
-v $PWD/server:/app/server -v $PWD/public:/app/public -v $PWD/test:/app/test \
-v /var/run/docker.sock:/app/docker.sock \
-v /etc/passwd:/etc/passwd -v /etc/shadow:/etc/shadow -v /etc/group:/etc/group \
nodemanager-dev
- `NM_DEV_AUTH=1` — 계정 존재만으로 로그인 (프로덕션 image에는 미포함)
- `-i --rm` + host mount (CLAUDE.md: `-d` detached 개발 금지)
API Summary
REST base: `http://<host>:<port>/api` (기본 포트 8080)
| 메서드 ! 경로 ! 역할 ! 설명 |
|---|
| `/login` | 공개 | `{username, password}` → `{token, user, role}` |
| `/health` | 무인증 | `{ok, version, license, uptimeSec, ...}` |
| `/users` | admin | 계정 목록 |
| `/packages?q=` | 인증 | 검색/설치 목록 |
| `/services` | 인증 | systemd 서비스 목록 |
| `/docker/containers` | 인증 | 컨테이너 목록 (비admin: 매핑 필터) |
| `/audit?limit=` | admin | 감사 로그 |
| `/nodes` | admin | 노드 레지스트리 + 라이선스 |
| `/nodes` | admin | 노드 등록 (라이선스 slot 소모) |
WebSocket base: `/ws?token=<token>`
| 토픽 ! 주기 ! 가시성 |
|---|
| 2초 | 전체 |
| 이벤트 | 전체 |
| 5초 | 비admin: 매핑 필터 |
| 10초 + CRUD | admin 전용 |
| 이벤트 | admin 전용 |
| 주기 | admin 전용 |
Best Practices
- Docker 컨테이너는 반드시 `--net=host` 사용 (host NIC/proc 가시성)
- docker.sock은 `/app/docker.sock`에 마운트 (systemd tmpfs 마스킹 회피)
- 관리자 계정은 `nm-admin` 그룹에 명시적 부여
- dev 환경에서는 `NM_DEV_AUTH=1` 사용 — 프로덕션 image에는 절대 포함 금지
- 업그레이드 시 `nm-data` 볼륨 유지 (DB 영속)
- GPU 라이브러리 업데이트: `deploy/gpu/update.sh` + 재빌드 + 컨테이너 재조성
Limitations
- Phase 9 S2 (크로스노드 실시간 telemetry 브리징)는 **설계 완료, 구현 대기**
— 노드 선택 대시보드, 원격 노드 CPU/GPU/네트워크 실시간 차트 아직 불가
- Phase 9 S3 (원격 명령 평면, 원격 exec)는 설계 미착수
- 라이선스 실 구현 (오프라인 서명 key + HWID 바인딩)은 독립 프로그램 연계 시점
- BMC 뷰는 DCIM 연동 상태에 따라 기능이 제한될 수 있음
References
- 프로젝트: `~/work/nodemanager` (git.hpcmate.com)
- API 전체: [API.md](git.hpcmate.com)
- 배포: [DEPLOY.md](git.hpcmate.com)
- 설계: [[[Plan|PLAN]].md](git.hpcmate.com)
- HPCMATE: [1](http://www.hpcmate.com)