라이선스 활성화 가이드

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
자동 로드: 서버 재시작 시 저장된 토큰을 자동으로 불러옵니다 — 재업로드 불필요
경로 커스터마이징: 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 재발급 요청

자세한 문제 해결 방법은 라이선스 문제 해결을 참조하세요.

Bridge 라이선스 (설비 벤더)

Bridge 라이선스 개요

Bridge.Host는 Engine과 독립적인 라이선스 체계를 사용합니다. 설비 벤더가 Engine에 접근하지 않고도 Bridge를 독립 운영할 수 있습니다.

항목	Engine 라이선스	Bridge 라이선스
인증 방식	JWT + HWID	PKV 오프라인 키
네트워크 필요	✅ (발급 시)	❌ (완전 오프라인)
사용자 DB	Engine Identity	bridge_config.json
발급 주체	NEXCODE	NEXCODE 또는 Engine 바인딩 시 자동

Bridge Community (무료)

별도 라이선스 키 없이 즉시 사용 가능합니다.

태그 50개, 드라이버 1개 한도
자체 Web UI(:5100)로 PLC 매핑
mDNS 서비스 광고 + Engine 바인딩 가능

Bridge Professional 활성화

두 가지 방법으로 활성화됩니다:

방법 1: Engine 바인딩 시 자동 활성화 (권장)

라인 운영자가 Engine Professional/Enterprise를 운영 중
Admin UI → Bridge Discovery → 바인딩 클릭
Engine이 Bridge에 Pro 라이선스 키를 자동 전달
Bridge가 즉시 Professional로 업그레이드
언바인딩 시 Community로 복귀

방법 2: PKV 키 수동 입력

NEXCODE에 Bridge PKV 키 발급 요청 (이메일: matrix@live.co.kr)
Bridge UI(:5100) → 설정 → 라이선스 메뉴
PKV 키 입력 → 즉시 적용

Bridge 슬롯

Engine 라이선스에 포함된 Bridge 슬롯 수만큼 바인딩이 가능합니다:

Community: 3대, Professional: 20대, Enterprise: 무제한

다음: 에디션별 기능 비교 →

라이선스 동작 원리​

활성화 프로세스​

Admin UI 라이선스 관리​

대시보드 (/license)​

하드웨어 정보 (/license/hardware)​

토큰 업로드 다이얼로그​

이력 (/license/history)​

API를 통한 관리​

토큰 자동 영속화​

서버 설정​

라이선스 갱신 절차​

Safe Mode​

진입 조건​

Safe Mode 동작​

Safe Mode 해제​

Bridge 라이선스 (설비 벤더)​

Bridge 라이선스 개요​

Bridge Community (무료)​

Bridge Professional 활성화​