# GUARDiA ITSM + Messenger — 운영자 지침서

**문서 버전**: 1.0  
**작성일**: 2026-05-25  
**대상**: 시스템 운영자, IT 관리자

---

## 목차

1. [시스템 개요](#1-시스템-개요)
2. [일상 운영 절차](#2-일상-운영-절차)
3. [사용자 계정 관리](#3-사용자-계정-관리)
4. [SR(서비스요청) 관리](#4-sr서비스요청-관리)
5. [SSL 인증서 관리](#5-ssl-인증서-관리)
6. [정기점검(PM) 관리](#6-정기점검pm-관리)
7. [장애 관리](#7-장애-관리)
8. [온콜/당직 관리](#8-온콜당직-관리)
9. [배치 작업 관리](#9-배치-작업-관리)
10. [백업 및 복구](#10-백업-및-복구)
11. [모니터링 및 알림](#11-모니터링-및-알림)
12. [보안 운영 지침](#12-보안-운영-지침)
13. [장애 대응 절차](#13-장애-대응-절차)
14. [로그 관리](#14-로그-관리)
15. [주요 설정 파일](#15-주요-설정-파일)
16. [라이선스 관리](#16-라이선스-관리)

---

## 1. 시스템 개요

### 1.1 구성 요소

| 구성요소 | 역할 | 기본 포트 |
|----------|------|-----------|
| GUARDiA ITSM | IT 서비스 관리 플랫폼 | 8000 |
| GUARDiA Messenger | 내부 메신저 + 봇 | 8001 |
| SQLite DB | 데이터 저장소 | — |
| APScheduler | 백그라운드 작업 (SSL 점검, PM) | — |

### 1.2 서비스 URL

```
운영자/엔지니어 화면:  http://<서버IP>:8000/
고객 화면:             http://<서버IP>:8000/customer
로그인:                http://<서버IP>:8000/login
API 문서:              http://<서버IP>:8000/docs  (운영: 비활성화 권장)
Messenger:             http://<서버IP>:8001/
```

### 1.3 프로세스 구성

```
systemd (Linux):
  guardia-itsm.service    — ITSM 메인 서버
  guardia-messenger.service — Messenger 서버

Windows Service:
  GUARDiA-ITSM            — ITSM 메인 서버
  GUARDiA-Messenger       — Messenger 서버
```

---

## 2. 일상 운영 절차

### 2.1 매일 아침 점검 체크리스트

```
시간: 매일 09:00

□ 1. 서비스 상태 확인
   → curl http://localhost:8000/ (200 응답 확인)

□ 2. 야간 스케줄러 실행 결과 확인
   → /var/log/guardia/scheduler.log 최신 항목 확인
   → SSL 점검 결과 확인 (00:10 실행)
   → 계약 만료 점검 결과 확인 (01:00 실행)
   → PM 자동 생성 결과 확인 (06:00 실행)

□ 3. 신규 SR 확인
   → ITSM 로그인 → 대시보드 → 미배정 SR 확인
   → P1/P2 긴급 건 우선 배정

□ 4. SSL 만료 임박 도메인 확인
   → ITSM → SSL 관리 → CRITICAL/URGENT 상태 도메인 갱신 조치

□ 5. 오늘 PM 일정 확인
   → ITSM → 정기점검 → 오늘 예정 작업 확인

□ 6. 라이선스 상태 확인
   → ITSM → 사이드바 🔏 라이선스 관리 → 상태 배너 확인
   → 노랑 배너(만료 30일 이내): 갱신 준비 시작
   → 빨강 배너(만료): 즉시 갱신 키 적용
```

### 2.2 매주 점검 체크리스트

```
시간: 매주 월요일 10:00

□ DB 파일 크기 확인 (100MB 이상 시 정리 검토)
□ 로그 파일 로테이션 확인
□ 업로드 파일 디렉토리 크기 확인
□ 미해결 SR 현황 검토 (7일 이상 미처리 건)
□ 만족도 낮은 SR 원인 분석
□ 이번 주 당직 배정 확인 및 알림
□ 만료 예정 SSL 인증서 30일 이내 갱신 계획 수립
```

### 2.3 매월 점검 체크리스트

```
시간: 매월 1일 11:00

□ 월간 SR 통계 보고서 작성
□ PM 점검 완료율 확인 및 미완료 건 추적
□ 보안 패치 현황 확인
□ 사용자 계정 감사 (퇴직자 계정 비활성화 확인)
□ DB 백업 파일 무결성 확인
□ 장애 발생 현황 분석 및 재발 방지 대책 검토
```

---

## 3. 사용자 계정 관리

### 3.1 계정 역할(Role) 정의

| 역할 | 권한 | 사용 대상 |
|------|------|-----------|
| ADMIN | 전체 관리 | 시스템 관리자 |
| PM | SR 배정, 결재, PM 관리 | 프로젝트/서비스 매니저 |
| ENGINEER | SR 처리, 작업 등록 | IT 엔지니어 |
| CUSTOMER | 자신의 SR 조회/생성 | 고객/사용자 |

### 3.2 신규 사용자 등록

**방법 1: API 직접 등록 (ADMIN)**
```
POST /auth/register
{
  "username": "user001",
  "password": "초기비밀번호!123",
  "full_name": "홍길동",
  "email": "hong@example.com",
  "role": "ENGINEER"
}
```

**방법 2: seed.py 수정 (초기 구성 시)**
```python
# core/seed.py — _seed_users() 함수에 추가
{"username": "new_user", "password": "초기PW!", "role": Role.ENGINEER}
```

### 3.3 비밀번호 정책

```
최소 길이: 8자
필수 조합: 영문 + 숫자 + 특수문자
금지 비밀번호: admin1234, password, 12345678 등
변경 주기: 90일마다 강제 변경 (구현 예정)
초기 비밀번호: 등록 후 첫 로그인 시 변경 강제
```

### 3.4 계정 잠금 및 비활성화

```
# 퇴직자/이탈자 계정 비활성화
PATCH /auth/users/{id}
{"is_active": false}

# 계정 삭제 (데이터 보존 위해 비활성화 권장, 삭제 비권장)
DELETE /auth/users/{id}
```

---

## 4. SR(서비스요청) 관리

### 4.1 SR 유형 및 처리 기한

| SR 유형 | 설명 | 목표 처리 시간 |
|---------|------|----------------|
| INCIDENT | 긴급 장애, 서비스 중단 | P1: 1시간, P2: 4시간 |
| SERVICE | 일반 서비스 요청 | 2 영업일 |
| CHANGE | 변경 요청 (결재 필요) | 5 영업일 |
| LOG | 작업 기록, 배치 결과 | 정보성 (SLA 없음) |

### 4.2 SR 상태 흐름

```
OPEN → IN_PROGRESS → RESOLVED → CLOSED
  ↓                               ↑
REJECTED ← (결재 거부)          REOPENED (재오픈)
```

### 4.3 담당자 배정 방법

```
자동 배정:
  PATCH /assign/{sr_id}
  {"assignee_id": null}  → 시스템이 자동 배정

수동 배정:
  PATCH /assign/{sr_id}
  {"assignee_id": 5}  → 특정 엔지니어(ID:5)에게 배정
```

### 4.4 SLA 위반 모니터링

```
SLA 위반 기준:
  P1 INCIDENT: 1시간 이내 미처리
  P2 INCIDENT: 4시간 이내 미처리

점검 방법:
  GET /dashboard/sla-violations
  
Messenger 알림: 위반 30분 전 자동 알림 (스케줄러)
```

---

## 5. SSL 인증서 관리

### 5.1 SSL 도메인 등록

```
새 도메인 등록:
  POST /ssl-manager/domains
  {
    "domain": "www.example.com",
    "port": 443,
    "server_id": 1,
    "memo": "메인 홈페이지"
  }
```

### 5.2 자동 점검 일정

```
매일 00:10 — 모든 등록 도메인 SSL 점검 자동 실행
점검 방법: 관리 서버의 ssl_expiry_check.sh 스크립트 실행

알림 발송 조건:
  EXPIRED (만료됨) → 즉시 Critical 알림
  URGENT (7일 이내) → 매일 알림
  WARN (30일 이내) → 최초 발견 시 알림
  OK (30일 초과) → 알림 없음
```

### 5.3 SSL 갱신 처리 절차

```
1단계: 만료 임박 도메인 확인
  GET /ssl-manager/domains?level=CRITICAL
  GET /ssl-manager/domains?level=URGENT

2단계: 인증서 갱신 (외부 CA에서 수행)
  - Let's Encrypt: certbot renew
  - 상용 CA: CA 포털에서 갱신 신청

3단계: 서버에 인증서 적용
  - Nginx/Apache 인증서 파일 교체
  - 웹서버 재시작

4단계: GUARDiA ITSM에 갱신 완료 기록
  POST /ssl-manager/domains/{id}/renew
  {
    "renewed_at": "2026-05-25T10:00:00",
    "new_expiry": "2027-05-25T10:00:00",
    "memo": "Let's Encrypt 자동 갱신"
  }

5단계: 즉시 재점검으로 확인
  POST /ssl-manager/domains/{id}/check
```

### 5.4 SSL 스크립트 배포

서버에 점검 스크립트를 배포해야 SSH 점검이 가능합니다:

```bash
# 관리 대상 서버에 스크립트 배포
scp scripts/sm/ssl/ssl_expiry_check.sh user@서버IP:/opt/guardia/scripts/ssl/
ssh user@서버IP "chmod +x /opt/guardia/scripts/ssl/ssl_expiry_check.sh"

# 테스트
ssh user@서버IP "bash /opt/guardia/scripts/ssl/ssl_expiry_check.sh www.example.com"
```

---

## 6. 정기점검(PM) 관리

### 6.1 PM 스케줄 설정

```
PM 주기 옵션:
  WEEKLY       — 매주
  BIWEEKLY     — 격주
  MONTHLY      — 매월
  QUARTERLY    — 분기별 (3개월)
  SEMIANNUAL   — 반기별 (6개월)
  ANNUAL       — 연간
  CUSTOM       — 커스텀 cron 식

스케줄 등록:
  POST /pm/schedules/
  {
    "name": "운영 서버 월간 점검",
    "server_id": 1,
    "template_ids": [1, 2, 3],
    "frequency": "MONTHLY",
    "day_of_month": 15,
    "assigned_to": 5
  }
```

### 6.2 PM 작업 자동 생성

```
매일 06:00 — 스케줄러가 당일 PM 작업 자동 생성
자동 생성된 작업: GET /pm/works/

수동 생성:
  POST /pm/works/
  {
    "schedule_id": 1,
    "planned_date": "2026-06-01",
    "notes": "6월 월간 점검"
  }
```

### 6.3 PM 결과 입력

```
각 체크리스트 항목 결과 입력:
  PATCH /pm/works/{work_id}/results/{result_id}
  {
    "result": "PASS",    // PASS / FAIL / WARNING / NA
    "value": "85%",      // 측정값
    "note": ""           // FAIL인 경우 조치 내역 필수
  }

PM 완료 처리:
  PATCH /pm/works/{work_id}/complete
```

### 6.4 PM 보고서 출력

```
Excel 보고서 다운로드:
  GET /pm/works/{work_id}/report
  → Excel 파일 다운로드 (PASS: 녹색, FAIL: 빨간색, WARNING: 노란색)
```

---

## 7. 장애 관리

### 7.1 장애 등급 정의

| 등급 | 영향 | 대응 시간 | 예시 |
|------|------|-----------|------|
| P1 | 전체 서비스 중단 | 1시간 | 운영 DB Down |
| P2 | 주요 기능 장애 | 4시간 | 로그인 불가 |
| P3 | 부분 기능 장애 | 8시간 | 특정 기능 오류 |
| P4 | 경미한 장애 | 2영업일 | UI 오류 |

### 7.2 P1/P2 장애 대응 절차

```
즉시 조치 (15분 이내):
1. ITSM에 장애 등록 (POST /incidents/)
   → Messenger 긴급 알림 자동 발송
2. 온콜 담당자에게 연락
3. 장애 타임라인 기록 시작

초기 조사 (30분 이내):
4. PATCH /incidents/{id}/status — INVESTIGATING
5. 원인 파악 시작
6. 임시 우회 방안 검토

조치 및 복구:
7. PATCH /incidents/{id}/status — MITIGATED (임시 조치 완료)
8. 근본 원인 해결
9. PATCH /incidents/{id}/status — RESOLVED

사후 처리:
10. RCA(근본원인분석) 작성
11. POST /incidents/{id}/close (RCA 포함 필수)
12. 재발 방지 대책 SR 등록
```

### 7.3 장애 타임라인 기록

```
장애 진행 중 모든 주요 활동 기록:
  POST /incidents/{id}/timeline
  {
    "event_type": "INVESTIGATION",
    "description": "DB 서버 CPU 100% 확인, 쿼리 분석 중"
  }

event_type 옵션:
  DETECTION    — 최초 감지
  INVESTIGATION — 조사 활동
  ACTION       — 조치 수행
  UPDATE       — 현황 업데이트
  RECOVERY     — 복구 완료
  POSTMORTEM   — 사후 분석
```

---

## 8. 온콜/당직 관리

### 8.1 당직 배정

```
단건 배정:
  POST /oncall/duties
  {
    "duty_date": "2026-06-01",
    "shift": "ALL_DAY",     // ALL_DAY / DAYTIME / NIGHTTIME
    "user_id": 5,
    "note": "야간 비상 연락"
  }

월간 일괄 배정:
  POST /oncall/duties/bulk
  {
    "duties": [
      {"duty_date": "2026-06-01", "shift": "ALL_DAY", "user_id": 5},
      {"duty_date": "2026-06-02", "shift": "ALL_DAY", "user_id": 6}
    ],
    "overwrite": false   // true: 중복 시 덮어쓰기
  }
```

### 8.2 오늘 당직 확인

```
GET /oncall/today
→ 오늘 날짜의 당직자 목록 (교대별)

응답 예시:
{
  "date": "2026-06-01",
  "duties": {
    "ALL_DAY": [{"user": "홍길동", "phone": "010-XXXX-XXXX"}],
    "NIGHTTIME": [{"user": "김철수", "phone": "010-XXXX-XXXX"}]
  }
}
```

### 8.3 월간 당직 조회

```
GET /oncall/calendar?year=2026&month=6
→ 해당 월 전체 당직 일정
```

---

## 9. 배치 작업 관리

### 9.1 배치 작업 등록

```
POST /batch/jobs
{
  "name": "일일 DB 백업",
  "server_id": 1,
  "command": "bash /opt/scripts/backup.sh",
  "cron_expr": "0 2 * * *",   // 매일 오전 2시
  "timeout_sec": 3600,
  "alert_on_fail": true,
  "is_active": true
}
```

> **주의**: 다음 명령어 패턴은 등록 자체가 거부됩니다:  
> `rm -rf /`, `shutdown`, `reboot`, `mkfs`, `dd if=`, Fork Bomb 등

### 9.2 배치 작업 모니터링

```
최근 실행 이력:
  GET /batch/jobs/{id}/runs?limit=20

실행 상태:
  RUNNING   — 실행 중
  SUCCESS   — 성공
  FAILED    — 실패 (alert_on_fail=true 시 SR 자동 생성)
  TIMEOUT   — 타임아웃 초과

실패 시 자동 SR: GET /tasks/?sr_type=LOG&priority=HIGH
```

### 9.3 수동 실행

```
POST /batch/jobs/{id}/run
→ 202 Accepted (백그라운드 실행 시작)

실행 결과 확인:
  GET /batch/jobs/{id}/runs?limit=1 (최신 1건)
```

---

## 10. 백업 및 복구

### 10.1 DB 백업 절차

```bash
# Linux — 수동 백업
cp /opt/guardia/itsm/guardia_itsm.db /backup/guardia_itsm_$(date +%Y%m%d).db
cp /opt/guardia/messenger/guardia_messenger.db /backup/guardia_messenger_$(date +%Y%m%d).db

# 자동 백업 스크립트 (cron 등록 권장)
# crontab -e
0 3 * * * /opt/guardia/scripts/backup.sh >> /var/log/guardia/backup.log 2>&1

# Windows — PowerShell
$date = Get-Date -Format "yyyyMMdd"
Copy-Item "C:\GUARDiA\itsm\guardia_itsm.db" "D:\Backup\guardia_itsm_$date.db"
```

### 10.2 업로드 파일 백업

```bash
# 업로드 파일 디렉토리 전체 백업
tar -czf /backup/uploads_$(date +%Y%m%d).tar.gz /opt/guardia/itsm/uploads/
```

### 10.3 복구 절차

```bash
# 1. 서비스 중지
systemctl stop guardia-itsm
systemctl stop guardia-messenger

# 2. 현재 DB 보존
mv guardia_itsm.db guardia_itsm.db.broken

# 3. 백업 복원
cp /backup/guardia_itsm_20260525.db guardia_itsm.db

# 4. 서비스 재시작
systemctl start guardia-itsm
systemctl start guardia-messenger

# 5. 서비스 상태 확인
curl http://localhost:8000/
```

### 10.4 백업 보관 정책

```
일간 백업: 30일 보관
주간 백업: 12주 보관
월간 백업: 12개월 보관
```

---

## 11. 모니터링 및 알림

### 11.1 시스템 모니터링 지점

| 모니터링 항목 | 임계값 | 조치 |
|--------------|--------|------|
| ITSM 서비스 응답 | 5초 이상 → 경고 | 서비스 재시작 |
| DB 파일 크기 | 500MB 이상 → 경고 | 정리/이관 검토 |
| 디스크 사용률 | 80% 이상 → 경고 | 파일 정리 |
| 업로드 디렉토리 | 10GB 이상 → 경고 | 오래된 파일 정리 |
| 스케줄러 실행 | 오전 06:30까지 미실행 → 경고 | 재시작 |

### 11.2 Messenger 알림 채널

```
장애 알림:     #guardia-incidents
SSL 만료 알림: #guardia-ssl
PM 일정 알림:  #guardia-pm
배치 실패:     #guardia-ops
```

### 11.3 서비스 상태 확인

```bash
# Linux
systemctl status guardia-itsm
systemctl status guardia-messenger

# 로그 실시간 확인
journalctl -u guardia-itsm -f

# Windows
Get-Service -Name "GUARDiA-ITSM"
```

---

## 12. 보안 운영 지침

### 12.1 계정 보안

```
□ 기본 admin 비밀번호 즉시 변경 (초기 설치 후)
□ 퇴직자 계정 당일 비활성화
□ 공용 계정 사용 금지 (1인 1계정 원칙)
□ 분기마다 불필요 계정 감사
□ CUSTOMER 역할 계정은 자신의 SR만 조회 가능 확인
```

### 12.2 API 접근 제어

```
□ 운영 환경에서 /docs 페이지 비활성화 권장
   main.py: app = FastAPI(docs_url=None, redoc_url=None)

□ CORS 설정 확인 (운영 환경)
   allow_origins: 실제 도메인만 허가 (localhost 제거)

□ 로그인 실패 횟수 모니터링
   GET /audit/logs?action=LOGIN_FAIL
```

### 12.3 서버 자격증명 관리

```
□ SSH 비밀번호는 AES-256-GCM 암호화 저장 확인
□ 평문 비밀번호 어디에도 저장 금지
□ ENCRYPTION_KEY는 .env에만 저장, Git 제외
□ API 응답에 IP/PW 포함 여부 정기 검사
□ root SSH 직접 접속 금지 설정 확인
```

### 12.4 감사 로그 관리

```
감사 로그 확인:
  GET /audit/logs?start=2026-05-01&end=2026-05-31

무결성 검증:
  GET /audit/verify
  → "integrity": true 확인

의심 활동 모니터링:
  - 새벽 시간대 로그인
  - 다수 SR 한 번에 변경
  - 서버 자격증명 접근
```

---

## 13. 장애 대응 절차

### 13.1 ITSM 서비스 응답 없음

```
증상: curl http://localhost:8000/ 타임아웃

1단계 — 프로세스 확인
  Linux: ps aux | grep uvicorn
  Windows: Get-Process -Name python

2단계 — 로그 확인
  Linux: journalctl -u guardia-itsm --since "10 min ago"
  Linux: cat /var/log/guardia/itsm.log | tail -100

3단계 — 서비스 재시작
  Linux: systemctl restart guardia-itsm
  Windows: Restart-Service "GUARDiA-ITSM"

4단계 — 재시작 후 확인
  curl http://localhost:8000/
  → 200 응답 확인
```

### 13.2 DB 잠금(Lock) 오류

```
증상: "database is locked" 에러 로그 발생

1단계 — 연결 프로세스 확인
  Linux: fuser guardia_itsm.db
  
2단계 — 임시 잠금 파일 삭제 (서비스 중지 후)
  rm guardia_itsm.db-shm guardia_itsm.db-wal

3단계 — 서비스 재시작
  systemctl restart guardia-itsm
```

### 13.3 스케줄러 미동작

```
증상: SSL 점검, PM 자동 생성이 실행되지 않음

1단계 — 로그 확인
  grep "scheduler" /var/log/guardia/itsm.log

2단계 — APScheduler 설치 확인
  pip show apscheduler

3단계 — 서비스 재시작
  systemctl restart guardia-itsm

4단계 — 수동 실행으로 대체
  ITSM → SSL 관리 → "전체 점검" 버튼
  ITSM → 정기점검 → 수동 작업 생성
```

### 13.4 Messenger 연결 실패

```
증상: ITSM 알림이 Messenger에 미전달

1단계 — Messenger 서비스 상태 확인
  systemctl status guardia-messenger

2단계 — 연결 설정 확인
  .env 파일의 MESSENGER_BASE_URL, MESSENGER_BOT_TOKEN 확인

3단계 — 연결 테스트
  curl http://localhost:8001/api/health

4단계 — Messenger 재시작
  systemctl restart guardia-messenger

주의: Messenger 알림 실패는 ITSM 기능에 영향 없음 (알림만 안 됨)
```

---

## 14. 로그 관리

### 14.1 로그 파일 위치

```
Linux:
  /var/log/guardia/itsm.log          — ITSM 애플리케이션 로그
  /var/log/guardia/scheduler.log      — 스케줄러 실행 로그
  /var/log/guardia/messenger.log      — Messenger 로그
  /var/log/guardia/backup.log         — 백업 실행 로그

Windows:
  C:\GUARDiA\logs\itsm.log
  C:\GUARDiA\logs\scheduler.log
  C:\GUARDiA\logs\messenger.log
```

### 14.2 로그 로테이션 설정 (Linux)

```
# /etc/logrotate.d/guardia
/var/log/guardia/*.log {
    daily
    missingok
    rotate 30
    compress
    delaycompress
    notifempty
    create 640 guardia guardia
    postrotate
        systemctl reload guardia-itsm
    endscript
}
```

### 14.3 감사 로그 (DB 내 저장)

```
ITSM 내 모든 주요 활동은 tb_audit_log 테이블에 저장됩니다.
해시 체인으로 무결성 보호.

조회:
  GET /audit/logs?limit=100
  GET /audit/logs?user_id=5&start=2026-05-01

무결성 검증:
  GET /audit/verify
```

---

## 15. 주요 설정 파일

### 15.1 .env 운영 설정

```ini
# 운영 환경 .env
SECRET_KEY=<64자 이상 랜덤 문자열>
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=480
DB_URL=sqlite+aiosqlite:///./guardia_itsm.db
ENCRYPTION_KEY=<64자리 hex 문자열>

MESSENGER_BASE_URL=http://localhost:8001
MESSENGER_BOT_TOKEN=<봇 토큰>

SSH_TIMEOUT=30
UPLOAD_ROOT=./uploads
MAX_FILE_SIZE_MB=10

# 운영: API 문서 비활성화
DOCS_DISABLED=true
```

### 15.2 서비스 파일 (Linux systemd)

```ini
# /etc/systemd/system/guardia-itsm.service
[Unit]
Description=GUARDiA ITSM Service
After=network.target

[Service]
User=guardia
WorkingDirectory=/opt/guardia/itsm
EnvironmentFile=/opt/guardia/itsm/.env
ExecStart=/opt/guardia/.venv/bin/uvicorn main:app --host 0.0.0.0 --port 8000 --workers 2
Restart=always
RestartSec=5
StandardOutput=append:/var/log/guardia/itsm.log
StandardError=append:/var/log/guardia/itsm.log

[Install]
WantedBy=multi-user.target
```

### 15.3 방화벽 설정

```bash
# Linux (firewalld)
firewall-cmd --permanent --add-port=8000/tcp   # ITSM
firewall-cmd --permanent --add-port=8001/tcp   # Messenger
firewall-cmd --reload

# Windows (PowerShell)
New-NetFirewallRule -DisplayName "GUARDiA ITSM" -Direction Inbound -Protocol TCP -LocalPort 8000 -Action Allow
New-NetFirewallRule -DisplayName "GUARDiA Messenger" -Direction Inbound -Protocol TCP -LocalPort 8001 -Action Allow
```

---

## 부록 A: 운영 명령어 빠른 참조

```bash
# 서비스 시작/중지/재시작
systemctl start|stop|restart guardia-itsm
systemctl start|stop|restart guardia-messenger

# 상태 확인
systemctl status guardia-itsm
curl http://localhost:8000/

# 로그 확인
journalctl -u guardia-itsm -f --since "1 hour ago"

# DB 백업
cp guardia_itsm.db guardia_itsm_$(date +%Y%m%d%H%M).db

# 업로드 용량 확인
du -sh uploads/

# 활성 연결 확인
ss -tlnp | grep :8000
```

## 부록 B: 비상 연락망

```
ITSM 운영팀: ...
보안팀: ...
인프라팀: ...
```

---

---

## 16. 라이선스 관리

### 16.1 라이선스 등록 절차

1. ITSM 관리자 계정으로 로그인
2. 사이드바 하단 **🔏 라이선스 관리** 클릭 (`/license` 페이지)
3. **라이선스 키 등록/갱신** 섹션에 `GRD-...` 형식의 키 붙여넣기
4. **라이선스 등록** 버튼 클릭
5. 상단 배너에서 에디션·만료일 확인

**API로 등록 (자동화)**:
```bash
curl -X POST http://localhost:8001/api/license/activate \
  -H "Authorization: Bearer <ADMIN_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"license_key": "GRD-..."}'
```

### 16.2 라이선스 상태 배너 의미

| 배너 색상 | 상태 | 조치 |
|---------|------|------|
| ✅ 초록 | 정상 활성 | — |
| ⚠️ 노랑 | 만료 30일 이내 경고 | 갱신 라이선스 요청 |
| ❌ 빨강 | 만료됨 | 즉시 갱신 키 적용 필요 |
| ⬜ 회색 | 라이선스 미등록 | Community 제한 모드로 동작 |

### 16.3 에디션별 자원 제한

| 에디션 | 기관 수 | 사용자 수 | 서버 수 | 주요 기능 |
|--------|--------|---------|--------|---------|
| COMMUNITY | 1 | 10 | 20 | MFA |
| STANDARD | 50 | 200 | 500 | MFA, LDAP, PAM, AI 에이전트 |
| ENTERPRISE | 무제한 | 무제한 | 무제한 | 전체 기능 |

> **주의**: 한도 초과 시 신규 등록 API가 HTTP 403을 반환한다.  
> 기존 등록 데이터는 만료·초과 후에도 삭제되지 않는다.

### 16.4 라이선스 갱신

갱신 라이선스 키를 받은 후 16.1과 동일하게 등록하면 기존 라이선스가 자동으로 비활성화되고 새 라이선스로 교체된다.

자세한 발급·갱신 절차는 **`manual/14_라이선스_키_발급_가이드.md`** 참조.

---

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