MirAI 사용자 매뉴얼

1. 개요

MirAI는 지능형 영상 감시 및 AI 분석 플랫폼입니다. 고성능 Rust 기반 서버(AI 추론, 스트림 관리, 데이터 저장)와 Qt C++ 데스크톱 클라이언트(실시간 모니터링, 사건 관리, 설정)로 구성됩니다.

주요 기능

• 실시간 영상 스트리밍 — GStreamer를 통한 저지연 RTSP 및 하드웨어 가속 디코딩. 서버당 최대 100대 카메라 지원.
• AI 이벤트 감지 — 불꽃(화재), 연기, 쓰러짐, 침입에 대한 파이프라인 기반 감지. ROI/RONI 영역 및 신뢰도 임계값 설정 가능.
• 멀티 카메라 그리드 — 1×1부터 10×10까지 유연한 그리드(최대 100개 동시 표시). 카메라 수에 따라 그리드가 자동으로 늘어나거나 줄어듭니다. 드래그 앤 드롭 재배치, 카메라 그룹 지원.
• 카메라 그룹 & AI 파이프라인 — 카메라를 그룹으로 구성하고 그룹별 AI 파이프라인 할당.
• 사건 녹화 & 감사 — 사전 이벤트 버퍼를 포함한 자동 녹화. 감사 워크플로우(True/False), 다중 형식 다운로드(MP4, AVI, PNG, JPG).
• 알림 시스템 — 이메일, Webhook, HTTP Endpoint, SNMP 전달을 지원하는 IF-THEN 규칙 엔진. 글로벌 속도 제한 및 조용한 시간대 설정.
• 멀티 서버 지원 — 여러 서버에 동시 연결, 각각 별도 탭으로 표시.
• 역할 기반 접근 제어 — Super_Admin, Admin, User 역할과 세분화된 권한.
• 시스템 관리 — 저장소 정책, 예약 백업/복원, 감사 추적, 로그 뷰어, 자동 업데이트.
• 다국어 지원 — 영어, 한국어, 일본어. 시간대 및 날짜 형식 설정 가능.

메인 화면 구성

시스템 요구 사항

사용자 역할

2. 시작하기

로그인

1. MirAI 실행 — 바탕화면 아이콘을 더블클릭합니다.
2. 서버 IP 입력 — 서버의 IP 주소를 입력합니다 (예: 192.168.1.100). 기본 포트: 7878 (HTTPS).
3. ID 및 비밀번호 입력 — 시스템 관리자로부터 받은 자격 증명을 사용합니다.
4. "ID/PW 저장" 체크 (선택 사항) — 다음 접속 시 ID와 비밀번호를 저장합니다.
5. "로그인" 클릭 — 서버가 시작 중인 경우 "서버 대기 중..." 대화 상자가 나타납니다.

3. 라이브 뷰

그리드 제어

그리드에 카메라 추가

• 카메라 드래그 — 서버 목록에서 빈 그리드 셀로 드롭
• 서버 드래그 → 해당 서버의 모든 카메라로 그리드 채움
• 카메라 그룹 드래그 → 그룹 내 모든 카메라로 그리드 채움
• 재배치 — 셀 간 드래그로 카메라 위치 변경

이미 그리드에 배치된 카메라를 다시 추가하면 중복으로 생성되지 않고 기존 타일이 강조 표시됩니다.

그리드 탐색

그리드 크기는 배치된 카메라 수에 따라 자동으로 조정됩니다(예: 카메라를 추가하면 1×2가 1×3으로 확장). 별도의 줌 조작은 없습니다. 카메라를 드래그하는 동안 대상 셀이 강조 표시되고 적용될 그리드 크기(예: 3 × 2)가 미리보기로 나타납니다.

카메라 호버 메뉴

카메라 타일 위에 마우스를 올리면 제어 바가 나타납니다:

알림 패널 (우측 사이드바)

AI가 이벤트를 감지하면:

1. 우측 패널에 알림 카드가 나타남: 이벤트 유형 아이콘, 카메라 이름, 서버, 타임스탬프, 썸네일
2. 알림을 클릭하면 사건 상세 보기로 바로 이동
3. "모두 지우기"를 클릭하여 모든 알림 해제
4. 음소거 버튼 (우측 상단, 스피커 아이콘)으로 알림 소리 끄기

패널에 마우스를 올려 두면 새 카드가 도착해도 스크롤 위치가 고정되어 읽고 있던 카드를 놓치지 않습니다. 패널은 최대 50개의 카드를 유지하며 가장 오래된 카드부터 정리됩니다. 패널이 접혀 있을 때 새 알림이 도착하면 다시 열기 아이콘이 빨간색으로 깜빡입니다.

이벤트 유형에 따라 알림음이 다르게 재생됩니다: 불꽃 및 연기 → Alarm, 침입 → Siren, 쓰러짐 → Alert, 기타 → Beep. 알림음은 약 2초 동안 디바운스되며, 각 알림 규칙의 "소리 재생" 토글로 규칙별로 끌 수 있습니다.

서버 관리

서버 목록 트리 구조

트리에서 카메라 이름은 현재 그리드에 표시 중이면 밝은 흰색으로, 표시되지 않은 경우 회색으로 나타납니다. 카메라 이름 옆에는 다음 아이콘이 표시됩니다:

• AI 칩 아이콘 — 보라색이면 해당 카메라에 AI 감지가 활성화되어 있음
• 알림 벨 아이콘 — 노란색이면 해당 카메라를 대상으로 하는 알림 규칙이 있음
• 녹화 점 — 빨간색=녹화 중, 노란색=대기 중, 주황색=오류

카메라 그룹을 우클릭하면 모두 펼치기 / 모두 접기 메뉴를 사용할 수 있습니다. 또한 카메라를 다른 그룹 위로 드래그하면 (확인 후) 해당 그룹으로 재할당할 수 있습니다.

서버 컨텍스트 메뉴 (서버 우클릭)

• 서버 정보 — CPU·GPU 제품명 확인
• 카메라 추가 — 카메라 추가 대화 상자 열기
• 테스트 카메라 — 스트림 작동 확인을 위한 테스트 비디오 창 열기
• 로그 확인 — 이 서버의 사건 로그 열기

카메라 컨텍스트 메뉴 (카메라 우클릭)

• 카메라 설정 — 카메라 이름, 해상도, 프로필 편집
• 로그 확인 — 이 카메라의 사건만 보기
• AI 설정 — 이 카메라의 AI 감지 구성
• 플로우 보기 — AI 파이프라인 플로우 다이어그램 보기 (읽기 전용)

모든 컨텍스트 메뉴에는 카메라 ID 표시 토글이 포함되어 그리드에 카메라 ID 배지를 켜고 끌 수 있습니다.

서버 추가

1. 서버 목록 영역에서 우클릭 → 서버 추가
2. 서버의 IP 주소, 사용자 ID, 비밀번호 입력
3. 테스트를 클릭하여 연결 확인
4. 추가 클릭
5. 새 서버가 상단에 새 탭으로 나타남

서버 정보 대화 상자

서버 우클릭 → 서버 정보에서 표시:

• 서버 이름 — 현재 로그인한 서버에서 관리자 권한으로 접속한 경우에만 편집할 수 있습니다. 그 외에는 읽기 전용이며 저장 버튼이 표시되지 않습니다.
• CPU·GPU 제품명
• 서버 제거 버튼 — 이 서버와의 연결 해제

여러 서버 사용

MirAI는 하나의 클라이언트에서 여러 서버를 모니터링할 수 있습니다. 로그인한 서버가 로그인 서버이며, (위 절차로) 추가한 서버는 추가 서버로 상단에 별도의 탭으로 표시됩니다. 탭을 클릭하여 서버를 전환합니다.

추가 서버에서도 모든 것을 모니터링할 수 있습니다. 카메라를 그리드에 배치하고, 라이브 영상을 보고, 서버 목록 트리를 탐색하고, 사건 로그를 열고, AI 이벤트를 확인할 수 있습니다. 각 카메라에는 해당 카메라가 속한 서버에 정의된 AI 이벤트 종류가 표시됩니다.

추가 서버는 읽기 전용입니다. 카메라 그룹 지정, AI 설정, 알림 규칙, 사용자 관리 및 대부분의 설정은 현재 로그인한 서버에서만 변경할 수 있습니다. 추가 서버를 구성하려면 해당 서버에 직접 로그인하세요. (추가 서버에서는 서버 이름 등의 항목이 읽기 전용이며 그룹으로의 드래그 앤 드롭이 비활성화됩니다.)

추가 서버 모니터링을 중지하려면 서버를 우클릭 → 서버 정보 → 서버 제거를 선택합니다. 이는 클라이언트 연결만 해제하며 서버 자체에는 영향을 주지 않습니다.

카메라 상태 표시기

다음 상태는 라이브 뷰 그리드의 각 카메라 타일에 표시됩니다:

AI 이벤트가 발생하면 해당 카메라 타일의 테두리가 이벤트 색상으로 깜빡입니다(해당 이벤트의 감지 박스와 동일한 색상이며, 색상이 없으면 빨간색). 이 화면 플래시 알림은 일반 설정에서 켜거나 끌 수 있습니다.

4. 설정 & 구성

상단 내비게이션 바의 설정 버튼을 통해 접근합니다. 좌측 사이드바에 설정 카테고리가 표시됩니다.

일반 설정

모든 사용자 역할에서 사용 가능. 외관 및 환경 설정 구성:

도움말 페이지

설정 → 도움말 (모든 역할에서 사용 가능). 포함 내용:

• 사용자 매뉴얼 — 기본 브라우저에서 이 매뉴얼 열기
• 지원 문의 — MarkAny Co., Ltd. 지원 정보 (웹사이트, 전화, 이메일)
• 키보드 단축키 — 모든 키보드 단축키 빠른 참조
• 서드파티 라이선스 — Qt (LGPL v3), GStreamer (LGPL v2.1+), OpenCV (Apache 2.0), Rust crates (MIT/Apache 2.0)

5. 사건 로그

상단 내비게이션의 사건 로그 탭을 통해 접근하거나, 서버/카메라 우클릭 → 로그 확인.

사건 필터링

테이블 표시: 일시, 썸네일, 카메라, 이벤트 종류, 이벤트(True/False), 확인자, 확인 일시. 하단에 페이지네이션.

사건 상세 보기

행을 클릭하여 열기:

• 비디오 재생 — 타임라인 스크러버 포함, 약 5초의 사전 이벤트 버퍼 포함. 재생 클릭, 드래그하여 탐색.
• AI 바운딩 박스 오버레이 — 감지된 내용을 보여주는 캡처 이미지 위의 오버레이
• 메타데이터: 이벤트 종류, 서버 이름, 카메라 이름, 최종 수정일시, 이벤트 True/False

사건 다운로드

• 상세 페이지에서 다운로드 아이콘 클릭
• 형식 선택: 이미지(PNG/JPG) 및/또는 비디오(MP4/AVI)
• 바운딩 박스 포함 체크박스를 선택하면 AI 감지 박스가 내보낸 이미지/비디오에 함께 그려집니다.
• 저장 폴더 선택 → 진행률 표시기와 함께 다운로드 시작

6. 자주 묻는 질문

7. 문제 해결

연결 문제

연결 끊김 & 재연결 동작

서버 연결이 끊어지면:

• 메인 화면에 "연결 끊김" 오버레이가 나타남
• 카메라 스트림이 마지막 수신 프레임에서 정지
• 클라이언트가 몇 초마다 자동으로 재연결 시도
• 재연결되면 스트림이 재개되고 오버레이가 사라짐
• 연결 끊김 중 수신된 알림은 소급하여 표시되지 않음

일반적인 연결 문제

• 대상 머신에서 서버 애플리케이션이 실행 중인지 확인
• IP 주소 및 포트 확인 (기본값: 7878)
• 방화벽이 서버 포트에서 인바운드 연결을 허용하는지 확인
• 두 머신이 동일 네트워크에 있거나 VPN이 구성되어 있는지 확인
• 사용 중 "서버 연결 끊김" → 네트워크 확인. 클라이언트가 자동 재연결합니다.

카메라 문제

피드가 표시되지 않음

• 먼저 VLC에서 RTSP URL을 테스트하여 MirAI 외부에서 작동하는지 확인
• 카메라가 서버 머신에서 접근 가능한지 확인 (클라이언트뿐만 아니라)
• 카메라 상태 표시기 확인 (녹색=온라인, 빨간색=오프라인, 노란색 깜빡임=정지)
• 서버 로그 확인: logs/server.log

검색 중 카메라를 찾을 수 없음

• IP 범위가 올바르고 카메라 전원이 켜져 있는지 확인
• 카메라가 ONVIF를 지원하고 활성화되어 있는지 확인
• 대신 RTSP URL을 통해 수동으로 추가 시도

AI 감지 문제

• 카메라에 대해 감지가 활성화되어 있는지 확인 (우클릭 → AI 설정)
• 카메라가 활성 파이프라인이 할당된 그룹에 있는지 확인
• 신뢰도 임계값 낮추기 (테스트용으로 0.3-0.5 시도)
• ROI/RONI 확인 — 이벤트가 ROI 다각형 외부에 있을 수 있음
• 서버 GPU가 과부하되지 않았는지 확인 (>90% → 프레임 드롭)
• 올바른 AI 모델이 모델 허브에서 활성 상태인지 확인
• logs/ai_pipeline.log 확인

알림 문제

• 채널이 활성 상태인지 확인 (채널 탭에서 토글 ON)
• 채널 카드의 테스트 버튼을 클릭하여 전달 확인
• 이벤트 유형을 채널에 연결하는 규칙이 있는지 확인
• 글로벌 정책 확인 — 조용한 시간대가 억제하고 있을 수 있음
• 속도 제한 확인 (분당/시간당 최대치가 소진되었을 수 있음)
• 이메일: SMTP 설정, 포트, 암호화, 자격 증명 확인
• Webhook: 서버에서 URL에 접근 가능한지 확인

일반적인 오류 메시지

성능 팁

• 클라이언트 CPU 부하를 줄이기 위해 더 작은 그리드 레이아웃 사용
• 많은 피드를 모니터링할 때 호버 메뉴에서 카메라를 저해상도로 전환
• "FPS to AI" 슬라이더를 낮춰 서버 GPU 사용량 감소
• 보존 정책을 설정하여 오래된 녹화를 자동 삭제하고 디스크 공간 확보
• 클라이언트 머신에서 다른 리소스 집약적 애플리케이션 종료

빠른 참조: 팁 & 단축키

8. 용어집