zio/guardia-docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

sync: update from workspace (latest ITSM/CICD/DR changes)

Browse Source
This commit is contained in:
DESKTOP-TKLFCPR\ython 2026-06-02 20:37:35 +09:00
parent 07d1088f06
commit 188da4d44d
2 changed files with 435 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

33
04_운영자지침서.md
View File

@ -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 기준으로 작성되었습니다.*

403
44_신규기능_운영가이드.md Normal file
View File

@ -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 <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 라벨 인쇄
```bash
# 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 스캔 이력 조회
```bash
GET /api/asset-qr/audit-log/{server_id}
Authorization: Bearer <JWT>
```
응답 예시:
```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
<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
```bash
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, 스마트 알림, 웹메일 주소록·서명) |