라이선스 활성화 가이드
Caffeine Framework 라이선스를 발급받고 활성화하는 전체 절차를 안내합니다.
라이선스 동작 원리
Caffeine은 JWT + HWID(하드웨어 ID) 이중 바인딩 방식으로 라이선스를 검증합니다.
- JWT (JSON Web Token): NEXCODE가 서명한 라이선스 토큰. 티어, 만료일, 기능 목록 포함
- HWID: 서버 CPU·네트워크 인터페이스 기반 하드웨어 지문. VM 이동이나 하드웨어 교체 시 변경됨
- 이중 검증: JWT 서명 검증 + HWID 일치 확인을 동시에 수행
JWT 발급 시: HWID를 포함하여 서명
실행 시: 현재 HWID와 JWT 내 HWID 비교 → 불일치 시 Safe Mode 진입
활성화 프로세스
Admin UI 라이선스 관리
대시보드 (/license)
라이선스 현황을 한눈에 확인합니다.
- 티어 배지: Community / Professional / Enterprise
- D-Day: 만료까지 남은 일수 (30일 이하 주황, 7일 이하 빨강)
- 태그 사용량 바: 현재/최대 태그 수 (70% 주황 경고, 90% 빨강 경고)
- 드라이버 사용량 바: 현재/최대 드라이버 수
하드웨어 정보 (/license/hardware)
HWID를 확인하고 복사합니다.
- Admin UI → 라이선스 → 하드웨어 정보 메뉴 클릭
- Machine ID 필드의 값을 복사 버튼으로 클립보드에 복사
- 이메일로 NEXCODE에 전달
HWID 구성
HWID는 CPU ID + 기본 네트워크 인터페이스 MAC 주소를 SHA-256으로 해시한 값입니다. Docker 컨테이너 환경에서는 호스트 네트워크 모드(--network host)를 사용해야 HWID가 안정적으로 유지됩니다.
토큰 업로드 다이얼로그
- 라이선스 대시보드 우측 상단 토큰 업로드 버튼 클릭
- 수령한 JWT 토큰 전체를 텍스트 박스에 붙여넣기
- 미리보기 버튼으로 티어·만료일 사전 확인
- 업로드 클릭 → 즉시 적용
이력 (/license/history)
라이선스 관련 이벤트 전체 기록을 조회합니다:
- 활성화 / 갱신 이력
- 검증 실패 이력
- Safe Mode 진입·해제 이력
API를 통한 관리
| 메서드 | 경로 | 설명 |
|---|---|---|
GET | /api/license/status | 라이선스 상태 조회 |
GET | /api/license/hwid | 하드웨어 ID 조회 |
GET | /api/license/features | 활성화된 기능 목록 |
GET | /api/license/history | 이벤트 이력 |
POST | /api/license/upload | 토큰 업로드 |
POST | /api/license/revalidate | 재검증 요청 |
API 상세 사양은 License API 레퍼런스를 참조하세요.
토큰 자동 영속화
v2.0.8부터 토큰 업로드 성공 시 로컬 디스크에 자동 저장됩니다.
- 기본 저장 경로:
- Windows:
%LocalApplicationData%/Caffeine/license.jwt - Linux:
~/.local/share/Caffeine/license.jwt
- Windows:
- 자동 로드: 서버 재시작 시 저장된 토큰을 자동으로 불러옵니다 — 재업로드 불필요
- 경로 커스터마이징:
appsettings.json의Licensing.TokenStorePath로 경로 오버라이드 가능
영속화 비활성화
TokenStorePath를 빈 문자열("")로 설정하면 디스크 저장 없이 메모리에만 유지됩니다.
서버 설정
appsettings.json의 Licensing 섹션으로 동작을 구성합니다.
"Licensing": {
"PublicKeyXml": "",
"TokenStorePath": ""
}
| 설정 키 | 기본값 | 설명 |
|---|---|---|
PublicKeyXml | "" | RSA 공개키 XML (NEXCODE 제공, 배포 패키지에 포함) |
TokenStorePath | "" | 토큰 저장 경로 오버라이드 (빈 문자열이면 OS 기본 경로) |
DI 등록은 AddCaffeineLicensing(IConfiguration) 확장 메서드를 사용합니다:
// Program.cs
builder.Services.AddCaffeineLicensing(builder.Configuration);
라이선스 갱신 절차
만료 30일 전부터 Admin UI 대시보드에 갱신 알림이 표시됩니다.
- NEXCODE에 갱신 요청 (이메일: matrix@live.co.kr)
- 새 JWT 토큰 수령
- Admin UI → 토큰 업로드 → 기존 토큰 교체
- 서버 재시작 불필요 — 즉시 적용 (토큰이 디스크에 자동 저장됩니다)
만료 후 동작
라이선스 만료 시 Safe Mode로 자동 전환됩니다. 데이터 수집은 중단되지 않지만 신규 드라이버 연결 및 고급 기능이 제한됩니다.
Safe Mode
진입 조건
| 조건 | 설명 |
|---|---|
| 라이선스 없음 | 최초 설치 후 토큰 미업로드 상태 |
| 라이선스 만료 | JWT 만료일 경과 |
| HWID 불일치 | 하드웨어 변경으로 바인딩 불일치 |
| JWT 서명 오류 | 위변조 또는 발급 기관 불일치 |
Safe Mode 동작
- Admin UI에 Safe Mode 배너 표시
- 기존 수집 데이터 보존 (읽기 전용)
- 신규 드라이버 연결 차단
- Community 한도(태그 100개, 드라이버 2개) 적용
Safe Mode 해제
- 유효한 JWT 토큰 업로드
- 또는 NEXCODE에 HWID 재발급 요청
자세한 문제 해결 방법은 라이선스 문제 해결을 참조하세요.
다음: 에디션별 기능 비교 →