# GUARDiA Manager — 라이선스 키 등록 및 관리 가이드

> **버전**: 2.0.0 | **작성일**: 2026-05-30  
> **접속 URL**: http://zioinfo.co.kr:8090/licenses  
> **대상**: 시스템 관리자 (admin 역할)

---

## 1. 개요

GUARDiA Manager의 **라이선스 관리** 페이지는 GUARDiA ITSM 플랫폼의 라이선스를
통합 관제하는 화면입니다.

### 주요 기능

| 기능 | 설명 |
|------|------|
| **현재 상태 확인** | 에디션, 만료일, 남은 기간, 허용 한도 실시간 표시 |
| **라이선스 키 등록** | 발급받은 라이선스 키를 붙여 넣고 즉시 활성화 |
| **무료 체험 시작** | 7/14/30일 체험 라이선스 즉시 발급 (설치당 1회) |
| **키 검증** | 등록 없이 키 유효성만 검증 (발급 전 사전 확인) |
| **라이선스 비활성화** | 현재 라이선스 비활성화 (서비스 제한 발생) |
| **이력 조회** | 과거 등록된 모든 라이선스 이력 테이블 |
| **에디션 비교** | TRIAL/COMMUNITY/STANDARD/ENTERPRISE 기능 비교 |

---

## 2. 라이선스 에디션

### 2-1. 에디션 비교표

| 구분 | TRIAL | COMMUNITY | STANDARD | ENTERPRISE |
|------|-------|-----------|----------|------------|
| 가격 | 무료 (7일) | 무료 | 협의 | 협의 |
| 기관 수 | 1 | 1 | 50 | 무제한 |
| 사용자 수 | 10명 | 10명 | 200명 | 무제한 |
| 서버 수 | 20대 | 50대 | 500대 | 무제한 |
| AI 에이전트 | ❌ | ❌ | ✅ | ✅ |
| LDAP/MFA | ❌ | ❌ | ✅ | ✅ |
| SLA 관리 | ✅ 기본 | ✅ 기본 | ✅ 고급 | ✅ 고급 |
| 취약점 스캔 | ❌ | ❌ | ❌ | ✅ |
| FinOps | ❌ | ❌ | ❌ | ✅ |
| Scouter APM | ❌ | ❌ | ❌ | ✅ |
| 기술 지원 | ❌ | 커뮤니티 | 이메일 | 전담 지원 |

### 2-2. 라이선스 키 형식

```
TRIAL:      GRD-{Base64URL 인코딩 페이로드}  (자동 생성)
COMMUNITY/  grd_lic_{발급기관코드}_{서명}
STANDARD/
ENTERPRISE:
```

---

## 3. 화면 구성 (NCloud 콘솔 스타일)

```
┌─────────────────────────────────────────────────────────────────┐
│  업그레이드 배너 (만료 3일 전 표시)                                │
│  ⚠️ 체험판이 X일 후 만료됩니다. [라이선스 등록] 버튼              │
├─────────────────────────────────────────────────────────────────┤
│  현재 라이선스 상태 카드                                          │
│  [에디션 배지] [체험판/만료 배지]                                  │
│  고객명: 지오정보기술 체험판                                       │
│  메시지: TRIAL 라이선스 활성 (6일 남음)                            │
│                         [🔑 등록] [🎁 체험] [🔍 검증] [비활성화] │
│  ─────────────────────────────────────────────────────────────  │
│  [만료 게이지 바]      [라이선스 ID]      [허용 한도]              │
│  ████████░░ 6일 남음   TRL-290EA0FB       기관:1/사용자:10/서버:20 │
├─────────────────────────────────────────────────────────────────┤
│  액션 패널 (선택한 액션에 따라 표시)                               │
│  예) 라이선스 키 등록: [textarea] [활성화 버튼]                    │
├─────────────────────────────────────────────────────────────────┤
│  에디션 비교 (4개 카드 — 현재 에디션 강조)                         │
│  [TRIAL]  [COMMUNITY]  [STANDARD ★]  [ENTERPRISE]               │
├─────────────────────────────────────────────────────────────────┤
│  라이선스 이력 테이블                                              │
│  ID | 라이선스ID | 에디션 | 고객명 | 체험판 | 만료일 | 상태 | 등록자│
└─────────────────────────────────────────────────────────────────┘
```

---

## 4. 기능별 사용 방법

### 4-1. 라이선스 키 등록

> **사전 조건**: admin 역할로 로그인, GUARDiA ITSM 서버에 `GUARDIA_LICENSE_KEY` 환경변수 설정

1. [🔑 라이선스 등록] 버튼 클릭
2. 발급받은 라이선스 키를 텍스트 영역에 붙여 넣기
3. [활성화] 버튼 클릭
4. 성공 시 현재 상태 카드가 즉시 갱신됨

```bash
# 라이선스 키 발급 (서버 관리자용 — Python 직접 실행)
ssh root@zioinfo.co.kr

source /opt/guardia/venv/bin/activate
cd /opt/guardia/app
python -m core.license \
  --customer "서울특별시 정보화부" \
  --edition STANDARD \
  --days 365 \
  --key $GUARDIA_LICENSE_KEY
```

### 4-2. 무료 체험 시작

> **제한**: 설치당 1회만 가능

1. [🎁 무료 체험] 버튼 클릭
2. 고객/기관명 입력 (기본값: "GUARDiA 체험판")
3. 체험 기간 선택: 7일 / 14일 / 30일
4. [🎁 체험 시작] 버튼 클릭
5. **발급된 체험 키가 팝업으로 1회만 표시** → 반드시 복사 보관
6. 즉시 TRIAL 에디션으로 활성화

> ⚠️ 체험 라이선스 키는 발급 시 화면에 1회만 표시됩니다. 화면을 닫으면 다시 확인할 수 없습니다.

### 4-3. 라이선스 키 검증

등록 전 키가 유효한지 먼저 확인할 때 사용합니다.

1. [🔍 키 검증] 버튼 클릭
2. 확인할 키 입력
3. [검증] 버튼 클릭
4. 결과 확인: 에디션, 고객명, 발급일, 만료일 표시
5. 유효한 경우 [이 키로 활성화] 버튼으로 즉시 등록 가능

### 4-4. 라이선스 비활성화

> **주의**: 비활성화 시 서비스 제한이 발생합니다.

1. [비활성화] 버튼 클릭 (빨간 버튼)
2. 확인 다이얼로그에서 [확인]
3. 상태가 "활성 라이선스가 없습니다."로 변경됨

---

## 5. API 명세

GUARDiA ITSM API를 직접 호출하는 엔드포인트입니다.

### 기본 정보

| 항목 | 값 |
|------|-----|
| Base URL | `http://zioinfo.co.kr:8001` |
| 인증 | `Authorization: Bearer {JWT Token}` |
| 로그인 | `POST /api/auth/login` (JSON, admin 역할 필요) |

### 엔드포인트 목록

| 메서드 | 경로 | 인증 | 설명 |
|--------|------|------|------|
| `GET` | `/api/license/status` | 로그인 | 현재 라이선스 상태 |
| `POST` | `/api/license/trial` | admin | 체험 라이선스 발급 |
| `POST` | `/api/license/activate` | admin | 라이선스 키 활성화 |
| `POST` | `/api/license/verify` | admin | 라이선스 키 검증만 |
| `DELETE` | `/api/license` | admin | 라이선스 비활성화 |
| `GET` | `/api/license/history` | admin | 등록 이력 조회 |

### 요청/응답 예시

**체험 라이선스 발급**
```bash
curl -X POST http://zioinfo.co.kr:8001/api/license/trial \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"customer":"지오정보기술","days":7}'
```
```json
{
  "message": "🎁 7일 무료 체험이 시작되었습니다!",
  "license_id": "TRL-XXXXXXXXXX",
  "edition": "TRIAL",
  "customer": "지오정보기술",
  "expires_at": "2026-06-06T11:37:25",
  "days_remaining": 7,
  "is_trial": true,
  "license_key": "GRD-..."
}
```

**라이선스 상태 조회**
```bash
curl http://zioinfo.co.kr:8001/api/license/status \
  -H "Authorization: Bearer $TOKEN"
```
```json
{
  "activated": true,
  "valid": true,
  "expired": false,
  "is_trial": true,
  "edition": "TRIAL",
  "customer": "지오정보기술",
  "days_remaining": 6,
  "limits": {
    "max_institutions": 1,
    "max_users": 10,
    "max_servers": 20
  },
  "message": "TRIAL [체험판] 라이선스 활성 (6일 남음)"
}
```

---

## 6. 테스트 결과

### 6-1. 테스트 환경

| 항목 | 값 |
|------|-----|
| 서버 | Ubuntu 24.04 (zioinfo.co.kr) |
| GUARDiA ITSM | v2.0.0 |
| GUARDiA Manager | v1.0.0 |
| 테스트 일자 | 2026-05-30 |

### 6-2. 테스트 결과 (7/7 PASS)

| 테스트 | 항목 | 결과 |
|--------|------|------|
| T1 | admin 로그인 (JSON) | ✅ PASS |
| T2 | 라이선스 현재 상태 조회 | ✅ PASS |
| T3 | 체험 라이선스 발급 (7일) | ✅ PASS |
| T4 | 활성화 후 상태 확인 (TRIAL, 6일) | ✅ PASS |
| T5 | 라이선스 이력 조회 (1건) | ✅ PASS |
| T6 | 잘못된 키 검증 (에러 처리) | ✅ PASS |
| T7 | Manager UI 접속 | ✅ PASS |
| T8 | Manager Backend API | ✅ PASS |

### 6-3. 버그 수정 이력

| 날짜 | 파일 | 버그 | 수정 내용 |
|------|------|------|---------|
| 2026-05-30 | `routers/license.py` | `datetime` timezone-aware/naive 충돌 | `datetime.fromisoformat(...).replace(tzinfo=None)` 적용 |

---

## 7. 운영 절차

### 7-1. 정기 만료일 모니터링

```bash
# 라이선스 만료일 확인 (서버 직접 확인)
ssh root@zioinfo.co.kr
curl -s -X POST http://localhost:8001/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"1111"}' \
  | python3 -c "import json,sys; print(json.load(sys.stdin).get('access_token')[:20])"

TOKEN=$(...)
curl -s http://localhost:8001/api/license/status \
  -H "Authorization: Bearer $TOKEN" \
  | python3 -m json.tool | grep -E "edition|days_remaining|expires_at"
```

### 7-2. 라이선스 갱신 절차

1. 새 라이선스 키 발급 (담당자에게 요청)
2. GUARDiA Manager → 라이선스 관리 → [🔍 키 검증]으로 사전 확인
3. [🔑 라이선스 등록] → 새 키 입력 → 활성화
4. 기존 라이선스는 자동 비활성화됨

### 7-3. 라이선스 환경변수 설정

STANDARD/ENTERPRISE 라이선스 사용 시 서버에 마스터 키 설정이 필요합니다:

```bash
# /opt/guardia/app/.env 에 추가
GUARDIA_LICENSE_KEY=<64자리 hex 마스터 키>

# 서비스 재시작
systemctl restart guardia
```

---

## 8. 트러블슈팅

| 증상 | 원인 | 해결 |
|------|------|------|
| 체험판 발급 실패 (409) | 이미 체험 이력 존재 | 체험은 1회 한정, 정식 키 필요 |
| 키 검증/등록 500 에러 | `GUARDIA_LICENSE_KEY` 미설정 | .env에 마스터 키 설정 |
| 이력 조회 403 | admin 역할 아님 | admin 계정으로 로그인 |
| 만료 배너 표시 | 만료 3일 이내 | 새 라이선스 등록 |
| `datetime` 오류 | timezone aware/naive 충돌 | `license.py` 패치 적용 (완료) |

---

*GUARDiA ITSM v2.0.0 | (주)지오정보기술 | 2026-05-30*