diff --git a/04_운영자지침서.md b/04_운영자지침서.md index 7c7af4f..b02071a 100644 --- a/04_운영자지침서.md +++ b/04_운영자지침서.md @@ -932,4 +932,35 @@ curl -X POST http://localhost:8001/api/license/activate \ --- -*본 운영자 지침서는 GUARDiA ITSM v1.0 기준으로 작성되었습니다.* +## 17. 신규 기능 (v2.0 — 2026-06-02) + +| 기능 | 위치 | 상세 가이드 | +|------|------|------------| +| 📱 모바일 앱 QR 직접 배포 | Manager → 앱 배포 | `44_신규기능_운영가이드.md` §1 | +| ⚡ 배치 SSH 일괄 실행 | ITSM → 배치 SSH 실행 | `44_신규기능_운영가이드.md` §2 | +| 🏷️ 자산 QR 태그 관리 | ITSM → 자산 QR 태그 | `44_신규기능_운영가이드.md` §3 | +| 🔔 스마트 알림 규칙 편집기 | ITSM/Manager → 알림 규칙 | `44_신규기능_운영가이드.md` §4 | +| 📧 웹메일 주소록·서명 | Webmail → 주소록/서명 탭 | `44_신규기능_운영가이드.md` §5 | + +### 17.1 빠른 시작 — APK QR 배포 + +``` +1. Manager(https://zioinfo.co.kr:8090) 로그인 +2. 사이드바 → 📱 앱 배포 +3. APK 파일 선택 + 버전 입력 → 🚀 배포 + QR 생성 +4. 생성된 QR 이미지를 사용자에게 공유 +5. 사용자: QR 스캔 → APK 다운로드 → 설치 완료 +``` + +### 17.2 빠른 시작 — 배치 SSH + +``` +1. ITSM(https://zioinfo.co.kr:8443) 로그인 +2. 사이드바 → ⚡ 배치 SSH 실행 +3. 명령어 + 서버 ID 목록 입력 → 실행 +4. 서버별 결과(성공/실패·stdout) 즉시 확인 +``` + +--- + +*본 운영자 지침서는 GUARDiA ITSM v2.0 기준으로 작성되었습니다.* diff --git a/44_신규기능_운영가이드.md b/44_신규기능_운영가이드.md new file mode 100644 index 0000000..34daf5e --- /dev/null +++ b/44_신규기능_운영가이드.md @@ -0,0 +1,403 @@ +# 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. **기본 서명으로 설정** → 메일 작성 시 자동 삽입 + +#### 보안 처리 +- `