본문으로 건너뛰기

라이선스 문제 해결

라이선스 관련 문제와 해결 방법을 안내합니다.

HWID 불일치​

증상​

Admin UI에 "하드웨어 ID 불일치" 오류 표시 및 Safe Mode 진입.

LicenseVerificationResult: HwidMismatch

원인별 해결 방법​

VM 이동 또는 클라우드 인스턴스 교체

HWID는 CPU ID + 네트워크 MAC 주소 기반입니다. VM을 다른 호스트로 마이그레이션하면 HWID가 변경됩니다.

→ 새 HWID를 확인하여 NEXCODE에 재발급 요청합니다.

하드웨어 교체 (NIC, CPU)

→ 새 HWID를 확인하여 NEXCODE에 재발급 요청합니다.

Docker 컨테이너 환경

브리지 네트워크 사용 시 컨테이너 재시작마다 MAC 주소가 변경될 수 있습니다.

→ --network host 또는 mac_address 고정:

# docker-compose.yml
services:
  caffeine-engine:
    network_mode: "host"
    # 또는
    networks:
      default:
        mac_address: "AA:BB:CC:DD:EE:FF"

HWID 재발급 요청

수신: matrix@live.co.kr
제목: Caffeine HWID 재발급 요청

라이선스 ID: [기존 JWT의 jti 클레임]
기존 HWID: [이전 HWID]
신규 HWID: [현재 HWID]
변경 사유: [VM 이동 / 하드웨어 교체 / Docker 설정 변경]

라이선스 만료 / Safe Mode 복구​

증상​

Admin UI 상단에 Safe Mode 배너 표시, 드라이버 신규 연결 불가.

해결 방법​

  1. 갱신 토큰 발급: NEXCODE에 갱신 요청 (matrix@live.co.kr)
  2. 토큰 업로드: Admin UI → 토큰 업로드 → 새 JWT 붙여넣기
  3. 즉시 적용: 재시작 없이 Safe Mode 자동 해제
Safe Mode 중 데이터 보존

Safe Mode 진입 중에도 기존 드라이버 연결과 데이터 수집은 유지됩니다. 단, 신규 드라이버 추가와 고급 기능(AI·ML 등) 접근이 차단됩니다.

토큰 업로드 실패​

증상​

토큰 업로드 후 "검증 실패" 메시지 표시.

에러 코드별 대응​

에러 코드원인해결 방법
InvalidSignatureJWT 서명 불일치 (위변조 또는 잘못된 발급자)NEXCODE에 재발급 요청
TokenExpiredJWT 자체 만료 (exp 클레임 경과)갱신 토큰 요청
HwidMismatch토큰 내 HWID와 현재 서버 HWID 불일치HWID 재발급 요청
MalformedTokenJWT 형식 오류 (잘려서 붙여넣기 등)토큰 전체를 다시 복사하여 재시도
UnsupportedTier지원하지 않는 티어 값NEXCODE 문의

토큰 형식 확인

JWT는 점(.)으로 구분된 3개 부분으로 구성됩니다:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ...}.signature

중간에 줄바꿈이나 공백이 포함되지 않도록 주의하세요.

Trial 문제​

Trial 미시작​

증상: 업로드한 토큰이 Community로 표시됨.

→ TRIAL- 접두사가 있는 Trial 전용 토큰인지 확인하세요. Community 토큰과 다른 별도 발급 절차가 필요합니다.

시간 조작 감지​

증상: Trial 토큰 업로드 시 TamperedSystemClock 오류.

Caffeine 라이선스 검증은 NTP 서버 시간을 기준으로 합니다. 시스템 시계를 수동 변경하면 조작으로 간주됩니다.

→ 시스템 시간을 NTP 서버와 동기화하세요:

# Linux
timedatectl set-ntp true
systemctl restart systemd-timesyncd

# Windows
w32tm /resync /force

에러 코드 레퍼런스​

LicenseVerificationResult 열거형 값 전체 목록:

값설명
Valid정상 검증 완료
NotFound라이선스 파일/토큰 없음
Expired라이선스 만료
HwidMismatch하드웨어 ID 불일치
InvalidSignatureJWT 서명 검증 실패
MalformedTokenJWT 형식 오류
TamperedSystemClock시스템 시계 조작 감지

LicenseLimitExceededException 대응​

증상​

태그 또는 드라이버 추가 시도 시 예외 발생:

LicenseLimitExceededException: 현재 라이선스(Community) 드라이버 한도(2개)에 도달했습니다.

Admin UI에서 태그/드라이버 사용량 바가 빨간색으로 표시됩니다.

해결 방법​

상황해결책
단기적 해결 필요사용하지 않는 드라이버/태그 삭제
장기적 운영Professional 이상으로 업그레이드
평가 중Trial 라이선스 발급 요청

업그레이드 문의: matrix@live.co.kr

추가 지원​

위 방법으로 해결되지 않는 경우:

  1. /api/license/history API로 이벤트 로그 수집
  2. Serilog 로그에서 [License] 접두사 항목 수집
  3. 수집한 정보와 함께 matrix@live.co.kr로 문의

처음으로: 라이선스 & 가격 정책 →