라이선스 문제 해결
라이선스 관련 문제와 해결 방법을 안내합니다.
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 배너 표시, 드라이버 신규 연결 불가.
해결 방법
- 갱신 토큰 발급: NEXCODE에 갱신 요청 (matrix@live.co.kr)
- 토큰 업로드: Admin UI → 토큰 업로드 → 새 JWT 붙여넣기
- 즉시 적용: 재시작 없이 Safe Mode 자동 해제
Safe Mode 진입 중에도 기존 드라이버 연결과 데이터 수집은 유지됩니다. 단, 신규 드라이버 추가와 고급 기능(AI·ML 등) 접근이 차단됩니다.
토큰 업로드 실패
증상
토큰 업로드 후 "검증 실패" 메시지 표시.
에러 코드별 대응
| 에러 코드 | 원인 | 해결 방법 |
|---|---|---|
InvalidSignature | JWT 서명 불일치 (위변조 또는 잘못된 발급자) | NEXCODE에 재발급 요청 |
TokenExpired | JWT 자체 만료 (exp 클레임 경과) | 갱신 토큰 요청 |
HwidMismatch | 토큰 내 HWID와 현재 서버 HWID 불일치 | HWID 재발급 요청 |
MalformedToken | JWT 형식 오류 (잘려서 붙여넣기 등) | 토큰 전체를 다시 복사하여 재시도 |
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 불일치 |
InvalidSignature | JWT 서명 검증 실패 |
MalformedToken | JWT 형식 오류 |
TamperedSystemClock | 시스템 시계 조작 감지 |
LicenseLimitExceededException 대응
증상
태그 또는 드라이버 추가 시도 시 예외 발생:
LicenseLimitExceededException: 현재 라이선스(Community) 드라이버 한도(2개)에 도달했습니다.
Admin UI에서 태그/드라이버 사용량 바가 빨간색으로 표시됩니다.
해결 방법
| 상황 | 해결책 |
|---|---|
| 단기적 해결 필요 | 사용하지 않는 드라이버/태그 삭제 |
| 장기적 운영 | Professional 이상으로 업그레이드 |
| 평가 중 | Trial 라이선스 발급 요청 |
업그레이드 문의: matrix@live.co.kr
Bridge PKV 라이선스 문제
PKV 키 활성화 실패
증상: Bridge UI(:5100) → 라이선스 → PKV 키 입력 시 "키 검증 실패" 메시지.
| 원인 | 해결 방법 |
|---|---|
| 잘못된 키 형식 | NEXCODE에서 발급한 Bridge 전용 PKV 키인지 확인 (Engine JWT 토큰과 다름) |
| 키 복사 오류 | 키 전체를 공백·줄바꿈 없이 정확히 복사하여 재시도 |
| 이미 활성화 | /api/bridge/license 로 현재 상태 확인 후 필요 시 재활성화 |
Bridge는 PKV 오프라인 키 방식, Engine은 JWT + HWID 방식입니다. 서로 다른 키를 사용하므로 혼동하지 않도록 주의하세요.
Engine 바인딩 후 Professional 미적용
증상: Admin UI에서 Bridge 바인딩 완료 후에도 Bridge가 Community로 표시.
- Bridge.Host 프로세스가 정상 실행 중인지 확인
- Bridge UI(
:5100) →/api/bridge/license접속하여 현재 티어 확인 - Engine 라이선스가 Professional/Enterprise인지 확인 (Community Engine은 Pro 키 미전달)
- Bridge.Host를 재시작하여 설정 재로드
언바인딩 후 Professional 유지
증상: Engine에서 언바인딩했으나 Bridge가 Professional을 유지.
→ 정상 동작입니다. PKV 키로 수동 활성화한 Bridge는 언바인딩해도 Professional이 유지됩니다. Engine 바인딩으로 자동 활성화된 경우에만 Community로 복귀합니다.
Bridge Config UI 접속 문제
Bridge UI 접속 불가
증상: http://<bridge-ip>:5100 접속 시 응답 없음.
| 원인 | 해결 방법 |
|---|---|
| Bridge.Host 미실행 | cafe setup status로 서비스 상태 확인 후 cafe setup으로 재시작 |
| 포트 충돌 | `netstat -tlnp |
| 방화벽 차단 | 5100 포트 인바운드 허용 |
First-Run Setup 재실행 불가
증상: 초기 설정이 완료된 후 /api/bridge/auth/setup 호출 시 409 Conflict.
→ 보안 정책상 First-Run Setup은 1회만 가능합니다. 비밀번호를 초기화하려면 bridge_config.json 파일에서 users 섹션을 삭제 후 Bridge.Host를 재시작하세요.
감사 로그 미표시
증상: Bridge UI에서 감사 로그 메뉴가 비어있음.
→ 감사 로그는 Bridge Professional에서만 활성화됩니다. Community 티어에서는 감사 로그가 기록되지 않습니다. PKV 키 또는 Engine 바인딩으로 Professional 활성화 후 확인하세요.
추가 지원
위 방법으로 해결되지 않는 경우:
/api/license/historyAPI로 이벤트 로그 수집- Serilog 로그에서
[License]접두사 항목 수집 - 수집한 정보와 함께 matrix@live.co.kr로 문의
처음으로: 라이선스 & 가격 정책 →