Skip to content

USER_MANUAL.md

Latest commit

 

History

History
445 lines (299 loc) · 19.9 KB

USER_MANUAL.md

File metadata and controls

445 lines (299 loc) · 19.9 KB
Raw

MoniGrid 사용자 메뉴얼

목차

  1. 로그인
  2. 대시보드 개요
  3. 위젯 관리
  4. 위젯 유형별 사용법
  5. 알람 시스템
  6. 대시보드 설정
  7. 로그 뷰어
  8. 문제 해결
  9. 사용자 계정 관리 (관리자 전용)

1. 로그인

1.1 접속

브라우저에서 대시보드 URL에 접속하면 로그인 화면이 나타납니다.

항목 설명
사용자명 관리자가 제공한 계정
비밀번호 관리자가 제공한 비밀번호

비밀번호 입력 칸 우측의 눈 모양 아이콘 으로 입력값을 잠깐 평문으로 확인할 수 있습니다 (이 토글은 이후 모든 비밀번호 입력 칸에 동일하게 적용됩니다).

로그인에 성공하면 대시보드 메인 화면으로 이동합니다. 세션은 24시간 유지되며, 만료 시 자동으로 로그인 화면으로 돌아갑니다.

1.2 로그아웃

화면 우측 상단의 사용자 메뉴에서 로그아웃을 클릭합니다.

2. 대시보드 개요

대시보드는 위젯 기반 그리드 레이아웃으로 구성됩니다.

2.1 화면 구성

┌─────────────────────────────────────────────────┐
│  헤더 (타이틀 · 메뉴 · 새로고침 · 설정 · 사용자) │
├──────────┬──────────┬──────────┬────────────────┤
│  위젯 A  │  위젯 B  │  위젯 C  │                │
│ (테이블)  │ (차트)   │ (헬스체크)│    위젯 D      │
│          │          │          │  (서버리소스)    │
├──────────┴──────────┼──────────┤                │
│      위젯 E         │  위젯 F  │                │
│   (네트워크 테스트)   │(상태목록) │                │
└─────────────────────┴──────────┴────────────────┘
  • 12컬럼 그리드 (0.5 단위): 가로폭은 12등분이지만, 모든 위젯은 0.5 단위(반칸) 로 늘리고 줄일 수 있습니다. 예: 가로 1.5칸, 세로 2.5칸. 드래그 리사이즈 / ⚙ 모달 직접 입력 모두 0.5 스텝으로 스냅됩니다.
  • 드래그 앤 드롭: 위젯 헤더를 드래그하여 위치를 변경합니다.
  • 크기 조절: 위젯 우측 하단 모서리를 드래그하여 크기를 변경합니다.
  • 반응형 표시: 화면 크기에 따라 레이아웃이 자동 조정되며, 서버 리소스 / API 상태 리스트 / 네트워크 테스트 위젯은 위젯 폭에 맞춰 폰트와 컬럼 표시(예: URL 컬럼 숨김)를 자동으로 조절합니다.

2.2 위젯 공통 요소

모든 위젯은 다음 공통 UI를 갖습니다:

요소 설명
제목 위젯 상단에 표시되는 이름
⟳ (새로고침) 수동으로 데이터를 즉시 갱신
⚙ (설정) 위젯 설정 모달 열기
✕ (제거) 위젯을 대시보드에서 삭제
갱신 주기 표시 ⏱ 30초 형태로 자동 갱신 주기 표시
마지막 갱신 시간 데이터가 마지막으로 갱신된 시각

3. 위젯 관리

3.1 위젯 추가

  1. 대시보드 헤더의 위젯 추가(+) 버튼을 클릭합니다.
  2. 위젯 유형을 선택합니다:
유형 설명 추가 시 입력
테이블 데이터 API 응답을 테이블로 표시 데이터 API URL
라인 차트 시계열 데이터를 라인 그래프로 시각화 데이터 API URL
바 차트 데이터를 막대 그래프로 시각화 데이터 API URL
헬스 체크 단일 URL의 HTTP 상태 모니터링 모니터링할 URL
상태 목록 여러 API 의 HTTP 200 여부를 한 눈에 확인 백엔드에 등록된 API 상태 대상 다중 선택
네트워크 테스트 Ping / Telnet 연결 진단 백엔드에 등록된 네트워크 체크 대상 다중 선택
서버 리소스 CPU / 메모리 / 디스크 사용률 모니터링 백엔드에 등록된 서버 리소스 대상 다중 선택
  1. 필요한 설정을 입력하고 저장합니다.

서버 리소스 / 네트워크 테스트 / 상태 목록 위젯은 위젯이 직접 호스트·URL·자격증명을 가지지 않습니다. 관리자가 백엔드 설정의 해당 탭에 미리 등록한 대상 중에서 골라서 추가합니다. 등록된 대상이 없으면 추가 화면에서 안내가 표시되며, 등록 후 다시 시도하면 됩니다.

3.2 위젯 이동 및 크기 변경

  • 이동: 위젯 헤더 영역을 마우스로 드래그합니다.
  • 크기 변경: 위젯 우측 하단 모서리를 드래그합니다 — 0.5 단위로 스냅됩니다.
  • 크기 범위: 가로 0.512 (사용자 단위), 세로 112. ⚙ 모달에서도 동일한 0.5 스텝 입력이 가능합니다.

3.3 위젯 제거

위젯 헤더의 ✕ 버튼을 클릭합니다. 제거 시 확인 대화상자가 표시됩니다.

3.4 레이아웃 자동 저장

위젯의 위치·크기·설정값·알람 기준은 로그인한 계정 단위로 서버(monigrid_user_preferences) 에 저장됩니다. 같은 계정이라면 다른 브라우저·다른 PC 에서 로그인해도 동일한 레이아웃 이 복원됩니다.

관리자가 사용자 계정을 삭제하면 해당 사용자의 레이아웃도 함께 지워집니다. 백업이 필요하면 6.4 대시보드 내보내기 / 가져오기 를 사용하세요.

4. 위젯 유형별 사용법

4.1 테이블 위젯

API 엔드포인트에서 가져온 JSON 데이터를 테이블 형태로 표시합니다.

기본 기능

  • 정렬: 컬럼 헤더를 클릭하면 오름차순 → 내림차순 → 정렬해제 순으로 전환됩니다.
  • 컬럼 순서 변경: 컬럼 헤더를 드래그하여 순서를 변경합니다.
  • 컬럼 너비 조절: 컬럼 헤더 경계를 드래그하여 너비를 조절합니다.
  • 행 상세 보기: 행을 클릭하면 해당 행의 전체 데이터를 JSON 형태로 볼 수 있습니다.
  • 셀 복사: 셀을 클릭하면 값이 클립보드에 복사됩니다.

설정 항목

설정 설명
엔드포인트 데이터를 가져올 API 경로 (예: /api/status)
갱신 주기 자동 갱신 간격 (초 단위, 1~3600)
크기 그리드 폭(W) × 높이(H)
제목 위젯 상단에 표시할 이름
컬럼 표시/숨김 표시할 컬럼을 선택
알람 기준 컬럼별 조건 설정 (아래 알람 시스템 참조)

4.2 라인 차트 위젯

시계열 데이터를 라인 그래프로 시각화합니다.

설정 항목

설정 설명
엔드포인트 데이터를 가져올 API 경로
X축 시간/카테고리 컬럼 선택
Y축 하나 이상의 숫자형 컬럼 선택
시간 범위 전체 / 1시간 / 6시간 / 24시간 / 7일
임계값 시리즈별 상한/하한 기준선 설정

사용 팁

  • 마우스를 그래프 위에 올리면 해당 지점의 상세 값이 툴팁으로 표시됩니다.
  • 범례 항목을 클릭하면 해당 시리즈를 표시/숨김할 수 있습니다.
  • 500개 이상의 데이터 포인트는 자동으로 다운샘플링됩니다.

4.3 바 차트 위젯

라인 차트와 동일한 설정을 지원하며, 데이터를 막대 그래프 형태로 표시합니다.

4.4 헬스 체크 위젯

단일 URL의 HTTP 응답 상태를 모니터링합니다.

표시 정보

항목 설명
상태 🟢 정상 (HTTP 2xx/3xx) / 🔴 장애 (4xx/5xx/연결 실패)
HTTP 상태 코드 200, 404, 500 등
응답 시간 밀리초 단위의 응답 시간

설정 항목

설정 설명
URL 모니터링할 대상 URL
갱신 주기 자동 체크 간격 (초)

4.5 상태 목록 위젯

여러 API 의 상태를 한 화면에서 확인합니다. 자격증명/URL 은 위젯이 아닌 백엔드 설정 → API 상태 탭에서 관리자가 등록하며, 위젯에서는 그 대상 중 표시할 항목들만 선택합니다.

표시 정보

  • 엔드포인트별 OK / FAIL 상태
  • 각 엔드포인트의 응답 시간
  • 상단 요약: OK 8 / FAIL 2
  • 실패한 엔드포인트가 목록 상단에 표시됩니다.
  • 위젯이 좁아지면 row 가 자동으로 컴팩트해지고 URL 컬럼이 숨겨집니다 — 행에 마우스를 올리면 툴팁으로 URL/오류 메시지를 볼 수 있습니다.

위젯 설정 항목

설정 설명
대상 선택 백엔드에 등록된 API 상태 대상 중 다중 선택 (체크박스). 등록된 대상이 0개이면 안내가 표시됩니다
갱신 주기 위젯 자동 갱신 간격 (초) — 실제 외부 호출 주기는 백엔드 측 interval_sec 으로 별도 관리

같은 URL 을 보는 브라우저가 여러 대여도 외부 서비스에 가는 호출은 백엔드가 1회만 수행합니다. 폴링 부담이 한 곳에 모이므로 외부 API 에 부담을 주지 않습니다.

4.6 네트워크 테스트 위젯

원격 호스트에 대한 Ping 또는 TCP 연결(Telnet) 테스트 결과를 표시합니다. 자격증명/호스트는 위젯이 아닌 백엔드 설정 → 네트워크 체크 탭에서 관리자가 등록하며, 위젯에서는 그 대상 중 표시할 항목들만 선택합니다.

테스트 유형 (관리자가 등록할 때 선택)

유형 설명
Ping ICMP 에코 요청
Telnet TCP 포트 연결 테스트

위젯 설정 항목

설정 설명
대상 선택 백엔드에 등록된 네트워크 체크 대상 중 다중 선택 (체크박스). 등록된 대상이 없으면 "백엔드 설정 → 네트워크 체크 탭에서 먼저 추가하세요" 안내가 표시됩니다
갱신 주기 위젯 자동 갱신 간격 (초) — 실제 수집 주기는 백엔드 설정 쪽 interval_sec 으로 별도 관리

4.7 서버 리소스 위젯

원격 또는 로컬 서버의 CPU, 메모리, 디스크 사용률을 표시합니다. 자격증명은 위젯에 들어가지 않으며, 관리자가 백엔드 설정에 등록한 대상 중에서 표시할 항목만 선택합니다.

표시 정보

항목 설명
CPU 사용률 (%)
메모리 전체 GB / 사용 GB / 사용률 (%)
디스크 마운트 포인트별 전체 GB / 사용 GB / 사용률 (%)
상태 🟢 OK / 🔴 NG (임계값 초과 시) / DEAD (연결 불가) / STALE (갱신 지연)

지원 OS 및 연결 방식 (관리자가 등록할 때 선택)

OS 타입 연결 방식
linux-rhel8 / linux-rhel7 / linux-generic SSH
windows WMI (로컬/원격)
windows-ssh SSH + PowerShell
windows-winrm WinRM (NTLM / Basic / Kerberos)

위젯 설정 항목

설정 설명
대상 선택 백엔드에 등록된 서버 리소스 대상 중 다중 선택 (체크박스)
갱신 주기 위젯 자동 갱신 간격 (초) — 실제 SSH/WinRM 수집 주기는 백엔드 설정 쪽 interval_sec 으로 별도 관리

호스트/사용자명/비밀번호/포트/임계값 등은 모두 백엔드 설정 → 서버 리소스 탭에서 관리자가 관리합니다. 자격증명이 브라우저로 내려오지 않으므로 사용자 단말이 노출되어도 안전합니다.

상세 보기

서버 행을 더블클릭하면 해당 서버의 CPU/메모리 사용률 추이를 차트로 확인할 수 있습니다. 최대 100개의 히스토리 포인트가 표시됩니다.

5. 알람 시스템

5.1 개요

위젯 데이터가 설정된 기준을 초과하면 알람이 발생합니다. 알람 발생 시:

  • 해당 위젯에 빨간색 테두리가 표시됩니다.
  • 화면 상단에 알람 배너가 나타납니다.
  • 설정에 따라 경고음이 재생됩니다.

5.2 테이블 위젯 알람 기준

위젯 설정 → 알람 기준 탭에서 컬럼별 조건을 설정합니다.

항목 설명
컬럼 조건을 적용할 컬럼
연산자 ==, !=, >, >=, <, <=
기준값 비교할 값
활성화 해당 조건의 사용 여부

예시: CPU 사용률이 80% 이상이면 알람

  • 컬럼: cpu_usage, 연산자: >=, 기준값: 80

5.3 차트 위젯 임계값

차트 위젯 설정 → 임계값 탭에서 시리즈별 기준선을 설정합니다.

항목 설명
시리즈 적용할 Y축 시리즈
연산자 >, >=, <, <=
값 임계값

임계값을 초과하는 구간은 차트에 빨간색/노란색 영역으로 표시됩니다.

5.4 서버 리소스 위젯 알람

서버별 설정에서 CPU, 메모리, 디스크의 **경고 임계값(%)**을 설정할 수 있습니다. 임계값 초과 시 해당 서버가 NG 상태로 표시됩니다.

5.5 알람 소리

소리 특징
beep 짧은 경고음
siren 사이렌
pulse 반복 펄스음

알람 배너의 확인 버튼을 클릭하면 소리가 멈춥니다. 새로운 알람이 발생하면 다시 울립니다.

6. 대시보드 설정

헤더의 ⚙ 설정 버튼을 클릭하면 대시보드 전체 설정을 변경할 수 있습니다.

6.1 화면 설정

설정 범위 기본값 설명
글꼴 크기 10~18px 13px 위젯 내 텍스트 크기

대시보드 전체 확대/축소가 필요하면 웹 브라우저의 확대/축소 기능(Ctrl +/Ctrl -)을 사용하세요.

위젯 레이아웃 자동 보정 — 이전 버전(12컬럼 정수 단위) 에서 저장된 레이아웃은 첫 로그인 시 0.5 단위(24컬럼 내부) 그리드로 1회 자동 변환됩니다. 별도 작업 없이도 기존 화면 비율이 유지됩니다.

6.2 API 서버 설정

설정 설명
API Base URL 백엔드 서버 주소 (변경 시 페이지 새로고침 필요)

6.3 알람 설정

설정 설명
소리 켜기/끄기 알람 발생 시 소리 재생 여부
소리 종류 beep / siren / pulse 중 선택

6.4 대시보드 내보내기 / 가져오기

현재 대시보드 구성을 JSON 파일로 내보내거나, 이전에 내보낸 파일을 가져올 수 있습니다.

  • 내보내기: 모든 위젯 구성, 레이아웃, 설정이 JSON 파일로 다운로드됩니다.
  • 가져오기: JSON 파일을 업로드하면 대시보드가 해당 구성으로 복원됩니다.

다른 사용자에게 동일한 대시보드를 공유하거나, 백업 용도로 활용할 수 있습니다.

7. 로그 뷰어

헤더의 로그 메뉴를 클릭하면 백엔드 서버의 로그를 조회할 수 있습니다.

7.1 필터 옵션

옵션 설명
시작일 조회 시작 날짜 (YYYY-MM-DD)
종료일 조회 종료 날짜
최대 줄 수 한 번에 표시할 로그 줄 수 (기본 1000)
자동 갱신 5초마다 새 로그를 자동으로 가져오기

7.2 사용 방법

  1. 날짜 범위를 선택합니다.
  2. 조회 버튼을 클릭합니다.
  3. 자동 갱신을 켜면 실시간으로 새 로그가 추가됩니다.
  4. 스크롤이 맨 아래에 있으면 새 로그가 추가될 때 자동으로 따라갑니다.

8. 문제 해결

8.1 자주 발생하는 문제

증상 원인 해결 방법
로그인 후 바로 로그아웃됨 토큰 만료 또는 서버 시간 차이 브라우저 캐시 삭제 후 재접속
위젯 데이터가 갱신되지 않음 네트워크 오류 또는 백엔드 중단 수동 새로고침(⟳) 시도, 헤더의 API URL 확인
"요청이 너무 많습니다" 오류 서버 Rate Limit 초과 (429) 잠시 대기하면 자동 복구. 지속 시 관리자에게 문의
서버 리소스가 DEAD 표시 SSH/WinRM 연결 실패 서버 접속 정보(호스트, 계정, 포트) 확인
서버 리소스가 STALE 표시 갱신 지연 (일시적) 수동 새로고침 시도, 지속 시 네트워크 확인
차트에 데이터가 표시되지 않음 X축/Y축 미설정 또는 데이터 없음 위젯 설정에서 축 설정 확인
위젯 레이아웃이 초기화됨 브라우저 데이터 삭제 내보내기 기능으로 미리 백업 권장

8.2 지원 브라우저

브라우저 최소 버전
Chrome 90+
Edge 90+
Firefox 90+
Safari 14+

Internet Explorer는 지원하지 않습니다.

9. 사용자 계정 관리 (관리자 전용)

관리자 계정으로 로그인하면 헤더 우측 👥 사용자 계정 관리 버튼이 나타납니다. 이 화면에서 monigrid_users 테이블의 계정을 추가 / 수정 / 삭제할 수 있습니다.

9.1 계정 목록

화면을 열면 등록된 모든 계정이 표시됩니다.

항목 설명
사용자명(username) 로그인 ID — 소문자로 저장
표시 이름(display_name) UI 표기용 별칭 (선택)
역할(role) admin (모든 기능) / user (대시보드 사용자)
활성(enabled) 체크 해제 시 로그인 차단

비밀번호는 bcrypt 해시로만 저장되므로 화면에 절대 노출되지 않습니다.

9.2 새 계정 만들기

  1. + 새 사용자 버튼을 클릭합니다.
  2. 사용자명, 비밀번호, 역할, 표시 이름, 활성 여부를 입력합니다.
  3. 저장 을 누르면 즉시 계정이 생성됩니다.

비밀번호는 8자 이상을 권장합니다. 사용자에게 임시 비밀번호를 전달한 뒤 첫 로그인 후 변경하도록 안내하세요 (수정 화면에서 비밀번호만 교체 가능).

9.3 계정 수정

행을 클릭하여 편집 패널을 여십시오. 비밀번호 필드는 비워 두면 기존 값이 유지되고, 입력하면 새 값으로 교체됩니다. 역할 변경 또는 비활성 전환도 이 화면에서 처리합니다.

9.4 자기 자신에 대한 제한

관리자가 자기 계정에는 다음 작업을 수행할 수 없습니다 — 서버가 400 오류로 차단합니다.

  • 자기 계정 삭제
  • 자기 계정 역할을 user 로 강등
  • 자기 계정을 비활성(enabled=false) 으로 변경

이는 관리자가 1명 남은 상태에서 자기를 잘라 버려 마스터 잠금 상태가 되는 사고를 방지하기 위한 규칙입니다. 먼저 다른 관리자 계정을 만든 뒤 그 계정으로 로그인해서 기존 계정을 내리세요.

9.5 최초 관리자 전환 (기본 admin / admin 제거)

시스템이 새로 구축된 직후에는 환경변수로 정의된 부트스트랩 계정(기본 admin/admin) 으로만 로그인할 수 있습니다. 운영에 들어가기 전에 반드시 아래 순서를 따르세요.

  1. admin / admin 으로 로그인
  2. 사용자 계정 관리 화면에서 실제 운영용 관리자 계정을 만든다 (예: alice, 강력한 임시 비밀번호)
  3. 로그아웃 후 신규 계정으로 재로그인
  4. 이 시점부터 환경변수 부트스트랩 로그인은 자동으로 잠깁니다 — 기본 admin/admin 으로는 더 이상 접속할 수 없습니다.