본문으로 건너뛰기

자주 묻는 질문 (FAQ)

Caffeine Framework에 대해 자주 묻는 질문과 답변입니다.

📋 일반​

Q1: Caffeine Framework란 무엇인가요?​

A: Caffeine은 산업용 IoT 환경을 위한 엔터프라이즈급 엣지 컴퓨팅 플랫폼입니다. 다양한 산업 프로토콜(Modbus, OPC UA, SECS/GEM 등)을 지원하며, 실시간 데이터 수집, 처리, 저장을 제공합니다.

주요 특징:

  • 실시간 데이터 처리 (마이크로초 단위)
  • 확장 가능한 마이크로서비스 아키텍처
  • 플러그인 방식의 드라이버 시스템
  • 클라우드 연동 및 엣지 컴퓨팅

Q2: Caffeine V1과 V2의 차이점은 무엇인가요?​

A:

기능V1 (2024-2025)V2 (2026+)
아키텍처모놀리식마이크로서비스
프로토콜Modbus, OPC UA+MQTT, GraphQL, gRPC
확장성단일 서버Kubernetes 클러스터
모니터링기본 로깅Prometheus/Grafana
이벤트없음Kafka 스트리밍

Q3: 라이선스 정책은 어떻게 되나요?​

A: Caffeine은 3개 에디션의 프로젝트 기반 라이선스를 제공합니다.

에디션태그드라이버가격
Community100개2개무료 (영구)
Professional1,000개10개연간 구독
Enterprise무제한무제한견적 문의

태그당 과금이 아닌 티어 내 자유 사용 모델입니다. 30일 무료 Trial로 전체 기능을 먼저 평가할 수 있습니다.

자세한 내용은 라이선스 & 가격 정책을 참조하세요.

Q: Trial 평가판은 어떻게 시작하나요?​

A:

  1. Admin UI → 라이선스 → 하드웨어 정보에서 Machine ID(HWID) 확인
  2. matrix@live.co.kr로 HWID와 회사명을 포함하여 Trial 요청 이메일 발송
  3. 수령한 TRIAL-... 토큰을 Admin UI에서 업로드

Trial은 30일간 Professional 수준의 전체 기능을 제공합니다. 자세한 내용은 30일 무료 Trial을 참조하세요.

Q: 라이선스 업그레이드 시 데이터가 유지되나요?​

A: 네, 완전히 유지됩니다.

라이선스 업그레이드는 JWT 토큰만 교체하는 방식입니다. InfluxDB, TypeDB, Redis에 저장된 모든 데이터와 드라이버 설정은 그대로 유지되며, 서버 재시작도 필요하지 않습니다.

Q: HWID가 변경되면 어떻게 하나요?​

A: HWID는 CPU ID + 네트워크 MAC 주소 기반으로, VM 이동이나 하드웨어 교체 시 변경됩니다.

새 HWID를 확인하여 NEXCODE(matrix@live.co.kr)에 재발급을 요청하세요. 재발급은 유료 라이선스 보유 고객에게 무료로 제공됩니다. 자세한 내용은 라이선스 문제 해결을 참조하세요.

Q: Safe Mode에서 벗어나려면?​

A: 유효한 JWT 라이선스 토큰을 Admin UI에서 업로드하면 즉시 Safe Mode가 해제됩니다.

Safe Mode는 라이선스 없음·만료·HWID 불일치·서명 오류 시 진입합니다. Safe Mode 중에도 기존 데이터 수집은 유지되지만 신규 드라이버 추가와 고급 기능은 차단됩니다. 자세한 내용은 라이선스 활성화 가이드 — Safe Mode를 참조하세요.

Q: Community 에디션에서 사용 가능한 기능은?​

A: Community 에디션에서 기본 제공되는 기능:

  • 태그 최대 100개, 드라이버 최대 2개
  • Modbus, Simulation 드라이버
  • Redis 실시간 캐시
  • Admin UI 기본 대시보드
  • gRPC, SignalR, MQTT, REST API
  • CLI 도구 (cafe)
  • ASP.NET Core Identity + JWT 인증

InfluxDB, TypeDB, AI·ML, Kafka 등 고급 기능은 Professional 이상에서 활성화됩니다. 전체 비교는 에디션별 기능 비교를 참조하세요.

🔧 설치 및 설정​

Q4: 설치 요구사항은 무엇인가요?​

A: 최소 요구사항:

소프트웨어:

  • .NET SDK 10.0 이상
  • PostgreSQL 14+ 또는 SQL Server 2019+
  • Redis 6.0+
  • InfluxDB 2.0+ (선택사항)

하드웨어:

  • CPU: 2 cores
  • RAM: 4GB
  • Disk: 20GB

운영체제:

  • Windows 10/11, Windows Server 2019+
  • Linux (Ubuntu 20.04+, RHEL 8+)
  • macOS 11+ (개발 환경)

Q5: Docker 없이 설치할 수 있나요?​

A: 네, 가능합니다.

수동 설치:

# 1. PostgreSQL 설치
# 2. Redis 설치
# 3. Caffeine Server 설치
dotnet tool install -g NEXCODE.Caffeine.Cli

# 4. 실행
caffeine-server --urls http://localhost:5001

하지만 Docker 사용을 권장합니다 (의존성 관리가 쉬움).

Q6: appsettings.json이 적용되지 않습니다.​

A: 다음을 확인하세요:

  1. 파일 위치: 실행 파일과 같은 디렉토리에 있어야 함
  2. 빌드 액션: "Content", "Copy if newer"로 설정
  3. 환경 변수 우선순위: 환경 변수가 appsettings.json보다 우선함
  4. JSON 형식: 유효한 JSON인지 확인

디버깅:

var config = builder.Configuration;
Console.WriteLine($"ServerUrl: {config["Caffeine:ServerUrl"]}");

🚀 드라이버 개발​

Q7: 지원하는 프로토콜은 무엇인가요?​

A: 기본 제공 드라이버:

  • SECS/GEM: 반도체 장비 통신
  • Modbus TCP/RTU: 산업 자동화
  • OPC UA: 표준 산업 통신
  • MQTT: IoT 메시징
  • Siemens S7: PLC 통신
  • FINS: Omron PLC

커스텀 드라이버: IDriver 인터페이스를 구현하여 모든 프로토콜 지원 가능

Q8: 드라이버를 개발하려면 어떻게 시작하나요?​

A:

1단계: CLI로 프로젝트 생성

cafe init --name MyDriver --template driver-full --git

2단계: IDriver 구현

public class MyDriver : IDriver
{
    public Task<bool> ConnectAsync(CancellationToken ct) { ... }
    public Task DisconnectAsync() { ... }
    public Task<TagValue?> ReadTagAsync(string tagName, CancellationToken ct) { ... }
    public Task<bool> WriteTagAsync(string tagName, object value, CancellationToken ct) { ... }
}

3단계: 테스트 및 패키징

dotnet test
cafe package

자세한 내용은 드라이버 개발 가이드를 참조하세요.

Q9: 여러 장비를 동시에 연결할 수 있나요?​

A: 네, 가능합니다.

방법 1: 드라이버 인스턴스 여러 개 생성

services.AddCaffeineDriver<ModbusDriver>("Equipment1", config =>
{
    config.Host = "192.168.1.100";
});

services.AddCaffeineDriver<ModbusDriver>("Equipment2", config =>
{
    config.Host = "192.168.1.101";
});

방법 2: 연결 풀 사용

var pool = new DriverPool<ModbusDriver>(poolSize: 10);

💾 데이터 관리​

Q10: 태그 데이터는 어디에 저장되나요?​

A: 3계층 스토리지 아키텍처:

  1. Redis (Hot Path): 최신 값 캐싱 (밀리초 조회)
  2. InfluxDB (Cold Path): 시계열 데이터 (장기 보관)
  3. PostgreSQL: 메타데이터, 설정

예제:

실시간 조회 → Redis (빠름)
히스토리 조회 → InfluxDB (대용량)
태그 설정 → PostgreSQL (관리)

Q11: 얼마나 많은 태그를 처리할 수 있나요?​

A:

단일 서버:

  • 최대 10,000 태그
  • 1초 폴링 간격
  • 평균 CPU 사용률 30%

클러스터 (Kubernetes):

  • 100,000+ 태그
  • 수평 확장 가능
  • 자동 로드 밸런싱

성능 최적화:

  • 배치 읽기/쓰기
  • 적응형 폴링
  • 연결 풀링

Q12: InfluxDB 없이 사용할 수 있나요?​

A: 네, 가능합니다.

InfluxDB는 선택사항이며, 히스토리 데이터가 필요하지 않으면 생략 가능합니다.

대안:

  • PostgreSQL TimescaleDB 확장
  • Azure Time Series Insights
  • AWS Timestream

🌐 배포 및 운영​

Q13: Kubernetes에 배포하려면 어떻게 하나요?​

A:

1단계: Docker 이미지 빌드

docker build -t mycompany/caffeine-server:latest .

2단계: Helm 차트 사용

helm install caffeine ./charts/caffeine \
  --namespace caffeine \
  --create-namespace \
  --values values-production.yaml

자세한 내용은 Kubernetes 배포 가이드를 참조하세요.

Q14: 무중단 배포가 가능한가요?​

A: 네, Kubernetes Rolling Update를 사용합니다.

Deployment 설정:

spec:
  replicas: 3
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 0

Health Check:

app.MapHealthChecks("/health");
app.MapHealthChecks("/health/ready");

Q15: 모니터링은 어떻게 하나요?​

A:

Prometheus + Grafana:

services.AddHealthChecksUI()
    .AddPrometheusGateway();

주요 메트릭:

  • 태그 읽기/쓰기 성공률
  • 평균 응답 시간
  • 연결된 드라이버 수
  • Redis/PostgreSQL 연결 상태

로그:

  • Serilog → Seq
  • ELK Stack
  • Azure Application Insights

🔒 보안​

Q16: API 인증은 어떻게 설정하나요?​

A:

API Key 방식:

services.AddAuthentication("ApiKey")
    .AddScheme<ApiKeyAuthenticationOptions, ApiKeyAuthenticationHandler>("ApiKey", null);

JWT 방식:

services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.Authority = "https://your-identity-server.com";
        options.Audience = "caffeine-api";
    });

Q17: SSL/TLS는 어떻게 설정하나요?​

A:

appsettings.json:

{
  "Kestrel": {
    "Endpoints": {
      "Https": {
        "Url": "https://*:5001",
        "Certificate": {
          "Path": "certs/certificate.pfx",
          "Password": "${CERT_PASSWORD}"
        }
      }
    }
  }
}

Let's Encrypt (자동):

dotnet add package LettuceEncrypt

🛠️ 문제 해결​

Q18: "Connection refused" 오류가 발생합니다.​

A:

확인 사항:

  1. 서버가 실행 중인지 확인
  2. 방화벽 설정 확인 (포트 5001)
  3. URL이 올바른지 확인 (https:// vs http://)

테스트:

curl http://localhost:5001/health
telnet localhost 5001

Q19: 태그 값이 업데이트되지 않습니다.​

A:

체크리스트:

  1. 드라이버 연결 상태 확인
  2. 폴링 간격 확인
  3. 태그 주소가 올바른지 확인
  4. 로그 확인

디버깅:

_logger.LogDebug("Reading tag: {TagName}", tagName);
var result = await driver.ReadTagAsync(tagName);
_logger.LogDebug("Result: {Value}, Quality: {Quality}", result.Value, result.Quality);

Q20: 성능이 느립니다.​

A:

최적화 방법:

  1. 배치 읽기 사용
var tags = await driver.ReadTagsAsync(new[] { "Tag1", "Tag2", "Tag3" });
  1. 폴링 간격 조정
{
  "PollingInterval": "00:00:00.100"  // 100ms
}
  1. 연결 풀링
services.AddSingleton<IDriverPool>(new DriverPool(poolSize: 20));
  1. Redis 캐싱 활용

📚 추가 리소스​

Q21: 더 많은 예제는 어디서 찾을 수 있나요?​

A:

Q22: 커뮤니티 지원은 어떻게 받나요?​

A:

  • GitHub Discussions: 질문 및 토론
  • Stack Overflow: caffeine-framework 태그
  • 이메일: matrix@live.co.kr
  • 카카오톡 채널: NEXCODE Caffeine

🔄 업데이트​

Q23: 새 버전으로 업그레이드하려면?​

A:

# NuGet 패키지 업데이트
dotnet add package NEXCODE.Caffeine.Core --version 2.0.9

# 또는 모든 Caffeine 패키지 업데이트
dotnet list package --outdated | grep Caffeine
dotnet add package NEXCODE.Caffeine.* --version 2.0.9

Breaking Changes: Changelog를 확인하세요.

작성일: 2026-01-28
버전: 2.0