guardia-docs/44_신규기능_운영가이드.md

GUARDiA 신규 기능 운영 가이드

문서 버전: 1.0
작성일: 2026-06-02
대상: 시스템 운영자, IT 관리자
관련 시스템: GUARDiA ITSM · Manager · Messenger · Webmail

---

목차

1. 모바일 앱 QR 직접 배포
2. 배치 SSH 일괄 실행
3. 자산 QR 태그 관리
4. 스마트 알림 규칙 편집기
5. 웹메일 주소록 · 서명 관리
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 직접 호출

curl -X POST https://zioinfo.co.kr:8443/api/batch-ssh/run \
  -H "Authorization: Bearer <JWT>" \
  -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 라벨 인쇄

# API로 생성
POST /api/asset-qr/generate/{server_id}
Authorization: Bearer <JWT>

# 라벨 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 스캔 이력 조회

GET /api/asset-qr/audit-log/{server_id}
Authorization: Bearer <JWT>

응답 예시:

[
  {"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

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 직접 입력:

<div style="font-family:sans-serif;font-size:13px;color:#374151;
            border-top:2px solid #003366;padding-top:10px;margin-top:10px">
  <strong style="font-size:14px">홍길동</strong> | 지오정보기술(주)<br>
  📧 hong@zioinfo.co.kr &nbsp;|&nbsp; 📞 02-0000-0000<br>
  🌐 www.zioinfo.co.kr
</div>

4. 미리보기 탭에서 렌더링 확인
5. 기본 서명으로 설정 → 메일 작성 시 자동 삽입

보안 처리

• <script>, <iframe>, on* 이벤트 핸들러 자동 제거
• XSS 필터링 후 저장 (DOMPurify 적용)

API

GET    /api/signature                # 서명 목록
POST   /api/signature                # 생성
PUT    /api/signature/{id}           # 수정
PATCH  /api/signature/{id}/default   # 기본 서명 설정
DELETE /api/signature/{id}           # 삭제

---

6. 신규 API 엔드포인트 목록

전체 엔드포인트: https://zioinfo.co.kr:8443/docs

6.1 모바일 앱 배포 (/api/app/)

메서드	경로	인증	설명
POST	/api/app/upload	Admin	APK 업로드 + QR 생성
POST	/api/app/url	Admin	외부 URL로 QR 생성
GET	/api/app/latest	필요	최신 버전 정보
GET	/api/app/qr	불필요	QR 이미지 PNG
GET	/api/app/landing	불필요	다운로드 랜딩 페이지
GET	/api/app/download	불필요	APK 파일 다운로드
GET	/api/app/versions	필요	버전 이력
DELETE	/api/app/versions/{id}	Admin	버전 삭제
GET	/api/app/stats	필요	다운로드 통계

6.2 배치 SSH (/api/batch-ssh/)

메서드	경로	설명
POST	/api/batch-ssh/run	다중 서버 동시 실행
GET	/api/batch-ssh/jobs	실행 이력 목록
GET	/api/batch-ssh/jobs/{id}	특정 작업 결과
POST	/api/batch-ssh/stop/{id}	실행 중단

6.3 자산 QR (/api/asset-qr/)

메서드	경로	인증	설명
POST	/api/asset-qr/generate/{server_id}	필요	QR 토큰 생성
GET	/api/asset-qr/scan/{qr_token}	필요	QR 스캔 (서버 정보)
POST	/api/asset-qr/checkin/{qr_token}	필요	실사 체크인
GET	/api/asset-qr/label/{qr_token}	불필요	라벨 HTML (인쇄용)
GET	/api/asset-qr/batch-print	필요	일괄 라벨 인쇄
GET	/api/asset-qr/list	필요	QR 토큰 목록
GET	/api/asset-qr/audit-log/{server_id}	필요	스캔 이력

6.4 스마트 알림 (/api/smart-notify/)

메서드	경로	설명
GET	/api/smart-notify/rules	규칙 목록
POST	/api/smart-notify/rules	규칙 생성
PUT	/api/smart-notify/rules/{id}	규칙 수정
DELETE	/api/smart-notify/rules/{id}	규칙 삭제
POST	/api/smart-notify/rules/{id}/test	테스트 발송
PATCH	/api/smart-notify/rules/{id}/toggle	활성화 토글
GET	/api/smart-notify/logs	발송 이력

6.5 웹메일 주소록/서명 (/api/contacts/, /api/signature/)

메서드	경로	설명
GET	/api/contacts	주소록 목록·검색
POST	/api/contacts	연락처 추가
PUT	/api/contacts/{id}	연락처 수정
DELETE	/api/contacts/{id}	연락처 삭제
POST	/api/contacts/auto-save	발송 후 자동 저장
GET	/api/signature	서명 목록
POST	/api/signature	서명 생성
PUT	/api/signature/{id}	서명 수정
PATCH	/api/signature/{id}/default	기본 서명 설정
DELETE	/api/signature/{id}	서명 삭제

---

변경 이력

날짜	버전	변경 내용
2026-06-02	1.0	최초 작성 — 신규 기능 5종 (APK QR 배포, 배치 SSH, 자산 QR, 스마트 알림, 웹메일 주소록·서명)