zioinfo-mail/workspace/guardia-docs/25_GUARDiA_Manager_라이선스_관리_가이드.md

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. 성공 시 현재 상태 카드가 즉시 갱신됨

# 라이선스 키 발급 (서버 관리자용 — 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	등록 이력 조회

요청/응답 예시

체험 라이선스 발급

curl -X POST http://zioinfo.co.kr:8001/api/license/trial \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"customer":"지오정보기술","days":7}'

{
  "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-..."
}

라이선스 상태 조회

curl http://zioinfo.co.kr:8001/api/license/status \
  -H "Authorization: Bearer $TOKEN"

{
  "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. 정기 만료일 모니터링

# 라이선스 만료일 확인 (서버 직접 확인)
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 라이선스 사용 시 서버에 마스터 키 설정이 필요합니다:

# /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