우리 집 네트워크를 한 장의 살아있는 구성도로: homelab-diagram 스타일 웹 대시보드 만들기

요약: 집 네트워크(공유기 · NAS · 서버 · Xiaomi Wi-Fi 공유기 뒤 기기들 · Docker 컨테이너)를 자동으로 수집해서 30초마다 다시 그리는 웹 구성도를 만들었습니다. 모든 수집은 읽기 전용이고, 네트워크 스캔은 하지 않습니다.

1. 왜 만들었나

GitHub의 Goblinmine/homelab-diagram은 홈랩 구성을 아주 보기 좋게 그린 구성도입니다. 선 두께로 링크 속도를 표현하고, 스위치 포트·VLAN 막대·폴더 탭 모양 장비 카드·Docker 배지 같은 시각 규칙이 잘 정리되어 있습니다.

다만 이런 그림은 손으로 그린 정적 이미지라서, 기기가 늘거나 컨테이너가 바뀌면 금방 실제와 달라집니다. 그래서 같은 시각 언어를 쓰되, 데이터는 실제 장비에서 자동으로 가져오는 버전을 만들어 보기로 했습니다.

2. 집 네트워크 구조

인터넷 ─ ISP 공유기(게이트웨이)
          │ 1G
      HOME LAN (/24)
       ├─ Synology NAS
       ├─ 리눅스 서버 (GPU 2장, Docker 16개 컨테이너)
       └─ Xiaomi Wi-Fi 공유기 (NAT 모드)
              └─ 휴대폰 · TV · 노트북 · IoT … (Wi-Fi 기기들)

문제는 Xiaomi 공유기가 NAT 모드라서, HOME LAN 쪽에서는 그 뒤에 붙은 Wi-Fi 기기들이 보이지 않는다는 점입니다.

3. 해결 방법: 서버의 Wi-Fi로 Xiaomi 내부망에 “한 발만” 걸치기

서버에 남는 Wi-Fi 카드를 Xiaomi 공유기에 접속시키고, 공유기 관리 API의 기기 목록을 읽어 오기로 했습니다. 내부망을 스캔하지 않아도 이름·IP·대역(2.4G/5G/유선)·실시간 트래픽을 받을 수 있습니다.

두 네트워크에 동시에 붙는 만큼 안전장치를 먼저 걸었습니다.

안전장치내용
기본 경로 유지Wi-Fi 연결은 never-default — 인터넷은 계속 유선으로만
방화벽 격리Wi-Fi 쪽에서 들어오는 새 연결 전부 차단 (Docker 포트 포함), 유선↔Wi-Fi 간 포워딩 차단
자동 적용NetworkManager dispatcher로 Wi-Fi가 올라오기 전에 규칙 적용
웹 노출대시보드는 localhost와 HOME LAN 주소에만 응답
읽기 전용공유기 설정 변경 API는 호출하지 않음 · 비밀번호는 로컬 .env(권한 600)에만

4. 무엇을 어떻게 모으나

수집기출처주기
XiaomiMiWiFi 관리 API (devicelist, status, wifi_detail_all)60초
HOME LAN커널 ARP 표 (ip neigh) — 스캔 없음5분
서버lsblk, nvidia-smi, docker, ss, systemctl 등5분
서비스 상태Prometheus targets API60초

수집 결과는 하나의 latest.json으로 합쳐지고, 기기 이력은 SQLite에 7일간 남겨 새 기기(NEW), 최근 사라진 기기(흐리게), 기기별 24시간 트래픽을 보여 줍니다.

기술 스택: Python(FastAPI · httpx) + 순수 JavaScript SVG 렌더러, systemd 사용자 서비스로 상시 실행.

5. 원본 구성도 요소를 이렇게 옮겼습니다

homelab-diagram 원본이 대시보드
인터넷 구름 · 원격 접속인터넷 구름, 서버에서 실행 중인 VPN 서비스
클라우드 서비스 카드(점선)사용 중인 DNS 서버
ISP 라우터 · 스위치 포트 · VLAN 막대게이트웨이, HOME LAN 가상 포트(ARP로 본 장비)
선 두께 = 링크 속도동일 (10G/2.5G/1G/100M), 속도 모르면 ? 점선
장비 카드 (폴더 탭)NAS · 서버 · Xiaomi 카드
하드웨어 타일 · 스토리지 풀CPU/메모리/GPU 타일, 디스크별 사용률 막대 (85% 이상 주황)
Docker 배지 앱 카드compose 프로젝트별 컨테이너 묶음
Open to the internetLAN에 열린 포트 목록 (민감 포트 ⚠ 표시)
미디어 파이프라인수집 흐름 패널 (수집기 상태 실시간)
범례 · 네트워크 표 · 워터마크 · 가리기모두 구현

위 Wi-Fi 기기 화면은 실제 공유기 연결 전, 예시 데이터로 렌더링을 확인한 것입니다.

6. 원본에 없던 기능

  • 30초 자동 갱신
  • 검색(/ 키): 이름·IP·MAC·컨테이너로 찾으면 해당 카드 강조
  • 카드 클릭 → 상세 창 (기기별 24시간 트래픽 그래프, 컨테이너·프로세스 포트)
  • NEW 배지(24시간 내 처음 본 기기), 사라진 기기 흐리게 표시
  • 가리기 모드: IP 끝자리·MAC 뒤 3바이트·기기 이름을 마스킹 — 이 글의 스크린샷도 이 모드로 찍었습니다
  • 화면 맞춤/실제 크기 전환, SVG·PNG 내보내기

7. 만들면서 겪은 함정

  1. systemd 보안 옵션의 부작용 — 사용자 서비스에 ProtectSystem=strict를 넣었더니 PrivateUsers가 함께 켜져서 ss -p가 프로세스 이름을 못 읽었습니다(전부 root로 표시). 옵션을 빼고 해결.
  2. 웹폰트 로딩 전 글자 폭 측정 — SVG 레이아웃을 위해 canvas로 글자 폭을 재는데, 폰트가 로드되기 전에 재면 텍스트가 카드 밖으로 넘칩니다. document.fonts.load()로 모든 폰트를 먼저 받은 뒤 그리도록 변경.
  3. pkill -f가 자기 셸까지 종료 — 패턴이 호출한 셸의 명령줄에도 걸렸습니다. PID 파일 방식으로 교체.
  4. Xiaomi 관리 API는 비공식 — 펌웨어마다 응답 필드가 달라서, 원본 응답을 저장해 두고 파서를 맞추는 구조로 만들었습니다.

8. 마무리

손으로 그리던 구성도가 이제 스스로 최신 상태를 유지합니다. 새 기기가 붙으면 NEW가 뜨고, 디스크가 차면 막대가 주황색으로 바뀌고, 컨테이너가 늘면 카드가 늘어납니다.

다음 단계는 Xiaomi 공유기를 실제로 연결해 펌웨어 응답에 맞춰 파서를 다듬고, 실제 Wi-Fi 기기 화면을 추가하는 것입니다.

시각 디자인 아이디어: Goblinmine/homelab-diagram

You May Also Like

About the Author: chohi

답글 남기기

이메일 주소는 공개되지 않습니다. 필수 필드는 *로 표시됩니다