# GUARDiA 신규 기능 운영 가이드 **문서 버전**: 1.0 **작성일**: 2026-06-02 **대상**: 시스템 운영자, IT 관리자 **관련 시스템**: GUARDiA ITSM · Manager · Messenger · Webmail --- ## 목차 1. [모바일 앱 QR 직접 배포](#1-모바일-앱-qr-직접-배포) 2. [배치 SSH 일괄 실행](#2-배치-ssh-일괄-실행) 3. [자산 QR 태그 관리](#3-자산-qr-태그-관리) 4. [스마트 알림 규칙 편집기](#4-스마트-알림-규칙-편집기) 5. [웹메일 주소록 · 서명 관리](#5-웹메일-주소록--서명-관리) 6. [신규 API 엔드포인트 목록](#6-신규-api-엔드포인트-목록) --- ## 1. 모바일 앱 QR 직접 배포 ### 1.1 개요 공공기관은 Google Play Store · Apple App Store 등록 절차가 복잡하고 시간이 오래 걸립니다. GUARDiA Manager에서 APK를 직접 업로드하면 **QR 코드가 즉시 생성**되고, 사용자는 QR 스캔만으로 GUARDiA Messenger를 설치할 수 있습니다. ``` 관리자 (Manager) ↓ APK 파일 업로드 ITSM 서버 저장 (/opt/guardia/app/uploads/apk/) ↓ QR 코드 자동 생성 (랜딩 페이지 URL 인코딩) QR 이미지 표시 (PNG, #003366 색상) ↓ 사용자: QR 스캔 → 랜딩 페이지 → Android 다운로드 버튼 클릭 ↓ APK 다운로드 · 설치 (Play Store 불필요) GUARDiA Messenger 설치 완료 ``` ### 1.2 관리자 화면에서 APK 배포 1. `https://zioinfo.co.kr:8090` (GUARDiA Manager) 접속 → 로그인 2. 좌측 사이드바 하단 **📱 앱 배포** 클릭 3. "새 버전 배포" 영역: - **버전**: 예) `1.2.3` - **APK 파일**: `.apk` 파일 선택 (최대 200MB) - **iOS URL** (선택): TestFlight 링크 - **업데이트 내용**: 변경사항 입력 4. **🚀 배포 + QR 생성** 클릭 5. 상단에 QR 코드 이미지와 랜딩 페이지 링크가 표시됩니다. > **외부 URL 방식**: EAS 빌드 APK URL 등 외부 링크가 있으면 > "외부 URL 연결" 탭에서 URL 입력 → QR 생성 가능합니다. ### 1.3 사용자 앱 설치 방법 (Android) 1. GUARDiA Manager에서 QR 이미지 출력 또는 화면 공유 2. Android 기기로 QR 스캔 (카메라 앱 또는 GUARDiA Messenger 앱) 3. 랜딩 페이지 열림 → **"Android 다운로드 (APK)"** 버튼 클릭 4. APK 파일 다운로드 완료 후: - 설정 → 보안 → **"알 수 없는 출처"** 허용 (최초 1회) - 다운로드된 APK 파일 실행 → 설치 5. GUARDiA Messenger 실행 → 서버 주소 입력 후 로그인 ### 1.4 버전 관리 | 작업 | 방법 | |------|------| | 최신 버전 확인 | Manager → 앱 배포 → 상단 "현재 최신 버전" 카드 | | 이전 버전 삭제 | 버전 이력 테이블 → "삭제" 버튼 (최신 버전은 삭제 불가) | | 다운로드 통계 | 상단 통계 카드: 총 다운로드·Android·iOS 횟수 | ### 1.5 관련 API | 엔드포인트 | 설명 | |-----------|------| | `POST /api/app/upload` | APK 업로드 (multipart/form-data) | | `GET /api/app/latest` | 최신 버전 정보 + QR URL | | `GET /api/app/qr?token=xxx` | QR 코드 PNG 이미지 (인증 불필요) | | `GET /api/app/landing?token=xxx` | 다운로드 랜딩 페이지 (인증 불필요) | | `GET /api/app/versions` | 버전 이력 목록 | | `GET /api/app/stats` | 다운로드 통계 | --- ## 2. 배치 SSH 일괄 실행 ### 2.1 개요 여러 서버에 **동시에 동일한 SSH 명령을 실행**하고 결과를 한눈에 확인합니다. 점검, 패치, 모니터링 명령을 수동으로 서버마다 반복 실행할 필요가 없습니다. **주요 사용 사례:** - 전체 서버 디스크 사용량 일괄 점검: `df -h /` - 모든 Tomcat 서버 스레드 수 확인: `ps aux | grep tomcat | wc -l` - 동시 패치 적용 상태 확인: `rpm -q <패키지명>` - 로그 파일 존재 여부 확인: `ls -lh /app/logs/error.log` ### 2.2 사용 방법 #### ITSM 화면에서 실행 1. GUARDiA ITSM (`https://zioinfo.co.kr:8443`) → 로그인 2. 좌측 사이드바 → **⚡ 배치 SSH 실행** 클릭 3. 폼 입력: - **명령어**: 실행할 셸 명령 (단일 명령 또는 세미콜론 구분) - **서버 목록**: 서버 ID 또는 태그 (콤마 구분, 예: `1,2,3` 또는 `web,db`) - **타임아웃(초)**: 기본 30초 4. **⚡ 실행** 클릭 5. 결과 카드 확인: 서버별 성공/실패·stdout·stderr 표시 #### API 직접 호출 ```bash curl -X POST https://zioinfo.co.kr:8443/api/batch-ssh/run \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "command": "df -h /", "server_ids": ["1", "2", "3"], "timeout_sec": 30 }' ``` ### 2.3 보안 제약 다음 명령어는 **위험 패턴**으로 차단됩니다: ``` rm -rf / mkfs dd if=/dev/zero shutdown halt reboot > /etc/passwd chmod 777 / ``` > 위험 패턴이 포함된 명령은 실행 전 거부되며 감사 로그에 기록됩니다. ### 2.4 실행 이력 - ITSM → 배치 SSH 실행 → 하단 "실행 이력" 테이블에서 확인 - API: `GET /api/batch-ssh/jobs?limit=20` --- ## 3. 자산 QR 태그 관리 ### 3.1 개요 서버·네트워크 장비 등 물리 자산에 **QR 라벨을 부착**하여 Messenger 앱으로 스캔하면 CMDB 정보를 즉시 확인하고 **실사 체크인**을 자동화합니다. ``` 운영자 ↓ ITSM에서 서버별 QR 토큰 생성 QR 라벨 인쇄 (50×30mm) ↓ 장비에 라벨 부착 현장 점검 시: GUARDiA Messenger → QR 탭 → QR 스캔 ↓ 서버 CMDB 정보 즉시 표시 (이름·OS·위치·상태) ↓ "실사 체크인" 버튼 클릭 실사 완료 기록 자동 저장 ``` ### 3.2 QR 토큰 생성 (관리자) 1. ITSM → 좌측 사이드바 → **🏷️ 자산 QR 태그** 2. "서버 ID" 입력 → **🏷️ QR 생성** 클릭 3. QR 이미지와 토큰 UUID가 표시됩니다. 4. **🖨️ 라벨 인쇄** 링크 클릭 → 50×30mm HTML 라벨 인쇄 ```bash # API로 생성 POST /api/asset-qr/generate/{server_id} Authorization: Bearer # 라벨 HTML 조회 (인쇄용) GET /api/asset-qr/label/{qr_token} # 인증 불필요 ``` ### 3.3 Messenger 앱에서 스캔 1. GUARDiA Messenger 실행 2. 하단 탭바 → **📷 QR** 탭 선택 3. 장비 라벨의 QR 코드 스캔 4. 서버 정보 확인 (이름·IP·OS·위치·상태) 5. **📋 실사 체크인** 버튼 → 체크인 완료 > **토큰 직접 입력**: QR 스캔 대신 "⌨️ 토큰 입력" 탭에서 UUID를 직접 입력해도 됩니다. ### 3.4 스캔 이력 조회 ```bash GET /api/asset-qr/audit-log/{server_id} Authorization: Bearer ``` 응답 예시: ```json [ {"scanned_at": "2026-06-02T10:30:00", "scanned_by": "홍길동", "checkin": true, "note": "모바일 실사"}, {"scanned_at": "2026-06-01T14:20:00", "scanned_by": "김엔지니어", "checkin": false} ] ``` --- ## 4. 스마트 알림 규칙 편집기 ### 4.1 개요 **노코드 방식**으로 알림 규칙을 정의합니다. 조건이 AND 모두 충족될 때 지정된 채널로 알림을 발송합니다. Ollama AI가 알림 중요도를 재평가하여 **알림 피로도를 자동 관리**합니다. ### 4.2 규칙 생성 (Manager) 1. Manager → 좌측 사이드바 → **🔔 알림 규칙** 2. **+ 규칙 추가** 클릭 3. 설정: | 항목 | 설명 | 예시 | |------|------|------| | 규칙 이름 | 식별 이름 | `CRITICAL SR 즉시 알림` | | 조건 | field + 연산자 + 값 | `sr_priority == CRITICAL` | | 알림 채널 | 메신저·이메일·SMS | `messenger, email` | | 우선순위 필터 | HIGH 이상만 등 | `CRITICAL` | | 무음 시작/종료 | 야간 알림 차단 | `22:00 ~ 08:00` | | 다이제스트 모드 | 묶음 발송 | ON/OFF | 4. **저장** → 즉시 활성화 #### 사용 가능한 조건 필드 | 필드 | 설명 | 예시 값 | |------|------|---------| | `sr_priority` | SR 우선순위 | `CRITICAL`, `HIGH`, `MEDIUM`, `LOW` | | `sr_category` | SR 카테고리 | `INCIDENT`, `CHANGE`, `PROBLEM` | | `sr_status` | SR 상태 | `RECEIVED`, `IN_PROGRESS` | | `server_cpu` | CPU 사용률 (%) | `90` | | `server_memory` | 메모리 사용률 (%) | `85` | | `server_disk` | 디스크 사용률 (%) | `80` | | `tenant_id` | 특정 기관 알림 | `1` | #### 지원 연산자 `==` `!=` `>` `>=` `<` `<=` `contains` ### 4.3 규칙 관리 (ITSM) 1. ITSM → 좌측 사이드바 → **🔔 스마트 알림 규칙** 2. 등록된 규칙 목록 확인 (활성/비활성 배지) 3. **테스트** 버튼 → 실제 발송 없이 동작 검증 4. **활성화/비활성화** 토글로 즉시 제어 ### 4.4 다이제스트 모드 같은 규칙이 단시간에 여러 번 트리거될 때 알림을 묶어서 발송합니다. ``` 규칙: CRITICAL SR 알림 (다이제스트 ON, 60분 간격) 09:00 CRITICAL SR-001 발생 09:15 CRITICAL SR-002 발생 09:45 CRITICAL SR-003 발생 ↓ 10:00 [다이제스트] "지난 1시간 CRITICAL SR 3건: SR-001, SR-002, SR-003" ``` --- ## 5. 웹메일 주소록 · 서명 관리 ### 5.1 주소록 #### 자동 저장 메일 발송 시 수신자가 자동으로 주소록에 저장됩니다. 자주 연락하는 사람일수록 자동완성 목록 상단에 표시됩니다. #### 수동 추가 1. 웹메일 (`https://mail.zioinfo.co.kr:8025`) 접속 2. 사이드바 → **주소록** 탭 3. **+ 추가** 버튼 → 이름·이메일·전화번호·회사 입력 #### 메일 작성 시 자동완성 - 수신자 필드에 이름 또는 이메일 앞 글자 입력 - 주소록 자동완성 목록 표시 → 클릭으로 선택 #### API ```bash GET /api/contacts?q=홍&limit=8 # 검색 POST /api/contacts # 추가 PUT /api/contacts/{id} # 수정 DELETE /api/contacts/{id} # 삭제 POST /api/contacts/auto-save # 자동 저장 (메일 발송 후 호출) ``` ### 5.2 HTML 서명 #### 서명 만들기 1. 웹메일 → 사이드바 → **서명** 탭 2. **+ 새 서명** 클릭 3. 프리셋 선택 또는 HTML 직접 입력: ```html
홍길동 | 지오정보기술(주)
📧 hong@zioinfo.co.kr  |  📞 02-0000-0000
🌐 www.zioinfo.co.kr
``` 4. **미리보기** 탭에서 렌더링 확인 5. **기본 서명으로 설정** → 메일 작성 시 자동 삽입 #### 보안 처리 - `