Skip to content

USER_GUIDE.md

Latest commit

 

History

History
101 lines (76 loc) · 9.21 KB

USER_GUIDE.md

File metadata and controls

101 lines (76 loc) · 9.21 KB
Raw

백본 상태 추적기 사용자 가이드

문서 버전: v0.9.0 작성일: 2026-08-24 대상: 백본 3/4호기 상태 점검 및 휴전 작업 검증 담당자

1. 핵심 흐름

v0.8.52부터 프로그램 공통 테마는 HPE Aruba AirWave 계열 운영 콘솔을 참고한 차분한 색상과 조밀한 정보 배치를 사용합니다. v0.8.53에서는 장비 설정, 상태 수집, 비교 결과, 작업 로그 화면의 안내 패널과 선택 상태 표시를 더 명확하게 정리했고, v0.8.54에서는 비교 결과와 HTML 리포트에서 선택한 상태와 상세 맥락을 더 쉽게 추적하도록 개선했습니다. v0.8.55에서는 이 화면 기준을 사용자 가이드 이미지, 개발자 가이드, 릴리스 체크리스트, ZIP 산출물 검증 기준에 맞춰 마감했습니다. v0.8.57에서는 개발자 가이드에 현대화 전 문제 원인과 설계 대응 요약을 추가했습니다.

  1. 장비 설정에서 접속 계정, 백본3/4 대상 장비, 상태 수집을 한 화면에서 처리합니다.
  2. 대상 장비는 기본 2개 행으로 시작하며, 추가 장비가 있으면 장비 추가로 행을 늘립니다.
  3. 대상 장비가 많아져도 장비 설정 화면을 스크롤해 상태 수집 영역까지 이어서 확인합니다.
  4. 첫 상태 수집은 기준 스냅샷으로 저장됩니다.
  5. 이후 상태 수집은 사용자가 입력한 단계명으로 저장하고 최신 기준 스냅샷과 자동 비교합니다.
  6. 단계명을 비우면 점검시간_YYYYMMDD_HHMM 이름으로 저장됩니다.
  7. 수집이 시작되거나 오류가 발생하면 작업 로그 화면으로 자동 이동합니다.
  8. 비교 결과의 긴급, 주의, 정보, 변경없음 카드를 누르면 해당 등급만 볼 수 있습니다.

2. 장비 설정과 상태 수집

장비 설정과 상태 수집

  • 계정에는 SSH 접속 계정을 입력합니다. 암호는 저장하지 않습니다.
  • 첫 실제 수집 전에 보안 정책에 따라 별도 채널로 fingerprint를 확인하고 config/known_hosts를 만듭니다. 파일 없음·주석-only·형식 오류·미등록 키는 접속 전에 차단됩니다.
  • 대상 장비에는 백본3/4호기의 IP, 포트, 장비 타입을 입력합니다.
  • 추가 점검 대상이 있으면 장비 추가를 눌러 새 행에 장비명, IP/호스트, 포트를 입력합니다.
  • 장비명과 IP/호스트가 모두 비어 있는 추가 행은 저장과 수집 대상에서 제외됩니다.
  • 버튼 줄 오른쪽의 대상 요약 칩에서 사용 N대 / 입력 N대 / 행 N개로 현재 수집 대상과 입력 행 수를 확인합니다.
  • 운영 입력 순서, 수집 흐름, 설정 점검 상태 패널은 계정/장비 입력 후 설정 점검, 상태 수집으로 이어지는 흐름을 보여줍니다.
  • 장비 행이 많아지면 마우스 휠이나 오른쪽 스크롤바로 상태 수집 영역까지 이동합니다.
  • 장비 목록 불러오기로 3대 이상이 들어 있는 YAML을 읽으면 필요한 만큼 행이 자동으로 늘어납니다.
  • 설정 점검은 장비 목록과 명령 세트 설정을 로컬에서 먼저 검증합니다.
  • 상태 수집 시작은 읽기 전용 점검 명령만 실행합니다.
  • 수집, 비교, 샘플 검증이 진행 중이면 설정 점검과 스냅샷 목록 새로고침은 잠기며, 완료 후 다시 사용할 수 있습니다.
  • config/commands.yaml에 정의된 명령만 실행되며, show vrrp를 포함한 읽기 전용 상태 확인 명령만 사용합니다. shutdown, save, reboot 같은 변경 명령은 포함하지 않습니다.

3. 비교 결과 확인

비교 결과

  • 상단의 긴급, 주의, 정보, 변경없음 카드는 필터 버튼입니다.
  • 선택한 등급 카드는 배경색과 테두리가 함께 바뀌어 현재 필터 상태를 바로 구분할 수 있습니다.
  • 목록은 장비, 명령, 판단, 변경 유형, 라인, 변경 내용을 함께 보여줍니다.
  • 변경 행을 선택하면 기준 값과 비교 값, 원본 파일 위치, 운영 메모를 확인할 수 있습니다.
  • v0.8.54부터 선택한 변경 행의 등급, 장비, 명령, 유형, 라인이 선택 변경 맥락 패널에 별도로 표시됩니다.
  • 장비가 접속되지 않으면 여러 명령 누락으로 흩어지지 않고 device_connectivity 한 줄로 표시됩니다.

4. 작업 로그

작업 로그

  • 수집 시작, 설정 오류, 비교 완료, 리포트 생성 위치가 시간 순서로 남습니다.
  • v0.8.53부터 로그 영역은 실행 이력 패널과 고정폭 글꼴을 사용해 시간, 파일 경로, 오류 메시지를 더 쉽게 읽을 수 있습니다.
  • 로그에는 명백한 비밀 값이 마스킹됩니다.
  • 장비 원본 출력은 증거 보존을 위해 raw/*.txt에 별도 저장됩니다. 외부 공유 전 민감 정보 포함 여부를 확인하세요.

5. 등급 판단 기준

  • 긴급: 장비 접속 실패, 명령 실패, 인터페이스 Down, LACP selected 수 감소, OSPF Full 이탈, cpu_usage 5초/1분/5분 값 중 70% 이상, memory_usage FreeRatio 30% 이하, power_status State가 Normal이 아닌 상태, major alarm, fault, abnormal, offline, missing 같은 즉시 확인이 필요한 변화입니다.
  • 주의: cpu_usage 5초/1분/5분 값 중 5069%, memory_usage FreeRatio 3140%, minor alarm, warning, error, 라우팅/STP/로그/리소스 변화처럼 영향 확인이 필요한 변화입니다.
  • 정보: 접속 복구, cpu_usage 5초/1분/5분 값이 모두 50% 미만, memory_usage FreeRatio 40% 초과, 또는 긴급/주의 키워드가 없는 일반 출력 변화입니다.
  • 변경없음: 의미 있는 변경이 감지되지 않은 항목입니다. HTML 리포트에서는 해당 등급을 선택한 뒤 필요 시 접힌 상세를 펼쳐 확인합니다.

6. HTML 리포트

  • HTML 리포트는 처음 열면 상단의 긴급, 주의, 정보, 변경없음 등급 카드만 보여줍니다.
  • v0.8.54부터 등급 카드 아래의 상태 안내 바가 현재 필터가 적용되었는지 알려줍니다.
  • 등급 카드는 상태별 색상 톤을 가지며, 상세 블록 헤더에는 장비, 명령, 상태, 분류, 변경 수가 함께 표시됩니다.
  • 등급 카드를 클릭하면 선택한 상태의 바로가기 버튼, 요약 카드, 상세 블록만 표시합니다.
  • 상태별 바로가기에서 장비/명령 버튼을 누르면 해당 명령별 상세 블록으로 바로 이동합니다.
  • 같은 등급 카드를 한 번 더 누르면 선택이 해제되고 바로가기, 요약, 상세 블록이 다시 숨겨집니다.
  • 요약 카드의 상세 보기를 누르면 현재 다른 등급 필터가 켜져 있어도 해당 상세가 보이도록 필터가 자동으로 맞춰집니다.
  • HTML 리포트 상단의 기준 또는 비교에 샘플 스냅샷이 들어가면 샘플: 접두어로 실제 작업 증적과 구분합니다.
  • 변경없음 요약 카드 묶음과 명령별 상세 블록은 제목만 보이고 접혀 있으므로 필요한 경우에만 펼칩니다.
  • 변경 표는 각 행 안에 등급, 장비, 명령, 분류, 변경 수, 첫 변경, 요약을 함께 보여주도록 구성되어 있습니다.
  • 명령별 상세에는 기준 값과 비교 값이 같은 줄에 표시되어 어느 라인이 바뀌었는지 바로 확인할 수 있습니다.
  • 공유 리포트 ZIP에는 사용자, 명령어, 초급 개발자, 버전 변경내역, 릴리스 체크리스트 문서의 MD/HTML과 화면 이미지가 함께 들어갑니다.
  • v0.8.55 기준 가이드 이미지는 실제 앱의 장비 설정, 비교 결과, 작업 로그 화면을 샘플 데이터로 캡처한 것입니다. 실제 장비 IP, 계정, 원본 출력은 포함하지 않습니다.

7. 샘플 검증

  • 비교 결과의 샘플 검증 생성은 실제 장비에 접속하지 않습니다.
  • 샘플은 백본3 접속 실패, 백본4 링크 변화, 복구 후 상태 예시를 생성해 UI와 리포트 동작을 검증합니다.
  • 샘플 스냅샷은 실제 작업 전 기준 스냅샷으로 사용되지 않습니다. 샘플만 있는 상태에서 첫 실제 수집을 시작하면 여전히 작업 전 기준으로 저장됩니다.
  • 샘플 스냅샷이 프로그램 상단 기준/비교 대상 또는 HTML 리포트 상단 기준/비교에 표시될 때는 샘플: 접두어가 붙습니다.

8. 배포 ZIP 확인

Windows 통합 ZIP 예시:

Get-FileHash -Algorithm SHA256 .\backbone_state_tracker_v0.9.0_windows.zip
python .\tools\verify_release_package.py .\dist\backbone_state_tracker_v0.9.0_windows.zip --type windows --require-manifest

GitHub Release에서는 Windows ZIP과 같은 이름의 SHA-256 sidecar, release manifest, CycloneDX SBOM을 함께 받습니다. Source code (zip) / Source code (tar.gz)는 실행용 파일이 아닙니다.

압축 해제 뒤 실제 수집 전 gui\config\known_hosts를 직접 준비합니다. 배포 ZIP의 known_hosts.example은 형식 안내일 뿐 승인된 실제 키를 포함하지 않습니다.

사내 메일이 .exe, .py, .ps1 포함 ZIP을 차단할 수 있습니다. 이 경우 승인된 내부 파일 반입 절차를 사용하세요.