네트워크 토폴로지 가이드

서버와 데이터베이스, 그리고 이들 사이의 연결을 3D 우주 공간으로 시각화한 네트워크 토폴로지(Net3D) 화면을 활용하는 방법을 안내합니다.

🚀 네트워크 토폴로지 페이지로 이동 →

⚠️ 이 문서의 적용 범위

이 문서는 화면 사용법만 다룹니다. 데이터를 직접 넣는 형식(tKVS kFactor/kKey/kValue)은 여기에 없으므로, 이 문서만으로는 데이터를 넣을 수 없습니다.

• 데이터를 직접 넣으려면 → 네트워크 토폴로지(Net3D) API 레퍼런스
• 네트워크가 아닌 임의의 데이터(주문 흐름, 조직도, 서비스 의존 관계 등)를 이 3D 레이아웃으로 보여주고 싶다면 → API 레퍼런스의 "부록: 네트워크가 아닌 데이터를 이 레이아웃으로 보여주기" 절. kFactor 만 임의 값으로 바꿔 tKVS 에 넣는 방법은 동작하지 않습니다(저장은 성공하지만 화면에는 아무것도 표시되지 않습니다).

📋 개요

네트워크 토폴로지는 현재 프로젝트(CSN)에 속한 서버와 데이터베이스를 3D 그래프로 표현합니다. 노드 사이의 연결선은 실제 SQL 통신을 나타내며, 부하 상태에 따라 색과 입자 흐름 속도가 실시간으로 변합니다. 로그인한 세션의 CSN을 기준으로 데이터가 로드됩니다.

🔍 화면 구성

1. 노드 (Nodes)

• 서버는 구(sphere), 데이터베이스는 원기둥(cylinder) 모양으로 표시됩니다.
• 노드 색상은 상태를 의미합니다: 정상은 파란색/녹색, 부하가 임계값을 넘으면 빨간색, 활성 쿼리가 임계값을 초과하면 붉은색, 열린 트랜잭션(Open Transaction)이 있으면 주황색으로 표시됩니다.
• 노드에 직접 지정한 사용자 색상(커스텀 색)이 있으면 우선 적용됩니다.

2. 연결선 (Links)

노드를 잇는 선은 SQL 통신 경로입니다. CPU 부하에 따라 녹색 → 노랑 → 주황 → 빨강으로 변하며, 최근 SQL이 흐르는 링크에는 방향성 입자가 더 빠르게 흐릅니다.

3. 노드 상세 버블 (Node Bubble)

노드를 클릭하면 카메라가 해당 노드로 이동하고 상세 정보 버블이 나타납니다. 서버는 호스트 상세 정보와 IP 목록을, 데이터베이스는 DB 상세를 보여줍니다. 버블에서 커스텀 색상과 메모를 저장하거나, 수정(Modify) 버튼으로 서버/DB 상세 편집 모달을 열 수 있습니다.

4. 검색 및 자동 새로고침

화면의 검색 창에서 노드 이름을 찾아 바로 포커스할 수 있습니다. 자동 새로고침 토글을 켜면 데이터가 주기적으로 갱신됩니다.

5. Known Nodes (외부 노드 관리)

등록되지 않은 외부 노드를 Known Nodes로 관리합니다. 목록 모달에서 노드 삭제, IP 연결 해제 등을 수행할 수 있습니다.

6. 타임라인 & 시간여행 (History 모드)

화면 하단의 타임라인에서 과거 시점을 선택하면 그 시점의 토폴로지 상태로 되돌아가 볼 수 있습니다(History 모드). 이때 우측 하단에 HISTORY MODE와 대상 시각이 표시됩니다.

7. 설정 (Thresholds)

설정 모달에서 노드/링크 부하 경고 임계값과 활성 쿼리 위험 임계값 등을 조정하면 색상 기준이 즉시 다시 계산되어 그래프에 반영됩니다.

🛠️ 활용 팁

• 우측 하단에 현재 표시 중인 노드 수와 링크 수가 표시됩니다.
• 노드나 데이터가 하나도 없으면 [머신 등록] 또는 [데이터베이스 등록] 안내 화면이 나타나며, 클릭하면 해당 등록 페이지로 이동합니다.
• 노드/링크 총합이 많아지면(약 700개 초과) 성능을 위해 입자 효과가 자동으로 줄어듭니다.

💡 유의 사항

• 이 페이지는 로그인이 필요하며, 세션의 CSN을 기준으로 데이터를 표시합니다.
• 커스텀 색상·메모 저장이 실패하면 브라우저 콘솔에 오류가 기록됩니다.

문제 해결

증상	원인	해결
화면에 노드가 없고 등록 안내만 표시됨	현재 CSN에 등록된 서버/DB가 없음	[머신 등록] 또는 [데이터베이스 등록]을 눌러 자산을 먼저 등록합니다.
"Loading Universe..."에서 멈춤	데이터 로드 지연 또는 세션 만료	자동 새로고침을 켜거나 페이지를 새로고침하고, 필요 시 다시 로그인합니다.
Error 메시지가 표시됨	데이터 조회 API 호출 실패	잠시 후 다시 시도하고, 반복되면 CSN·네트워크 상태를 확인합니다.
커스텀 색상/메모가 저장되지 않음	저장 API 응답이 성공(200)이 아님	브라우저 콘솔의 오류를 확인하고 다시 시도합니다.
노드 색상이 예상과 다름	부하/활성 쿼리 임계값 설정 때문	설정 모달에서 임계값을 조정합니다.

---

버전: 1.1 최종 업데이트: 2026-09-14 소스 파일: giipv3/public/help/network-topology.ko.md