설정 가이드
Caffeine Framework의 설정 옵션 및 구성 방법에 대한 완벽한 가이드입니다.
📋 개요
Caffeine은 다양한 설정 방법을 제공하여 유연한 구성이 가능합니다.
🔧 설정 방법
1. appsettings.json
가장 일반적인 설정 방법입니다.
{
"Caffeine": {
"ServerUrl": "https://localhost:5001",
"ApiKey": "${CAFFEINE_API_KEY}",
"Timeout": 30000,
"RetryPolicy": {
"MaxRetries": 3,
"BackoffMultiplier": 2
}
},
"ConnectionStrings": {
"PostgreSQL": "Host=localhost;Database=caffeine;Username=postgres;Password=secret",
"Redis": "localhost:6379",
"InfluxDB": "http://localhost:8086",
"Kafka": "localhost:9092"
},
"Logging": {
"LogLevel": {
"Default": "Information",
"Caffeine": "Debug",
"Microsoft": "Warning"
}
}
}
2. 환경 변수
# Linux/macOS
export CAFFEINE__SERVERURL="https://localhost:5001"
export CAFFEINE__APIKEY="your-api-key"
export ConnectionStrings__PostgreSQL="Host=postgres;Database=caffeine"
# Windows (PowerShell)
$env:CAFFEINE__SERVERURL="https://localhost:5001"
$env:CAFFEINE__APIKEY="your-api-key"
계층 구조: __ (double underscore)로 구분
3. 코드 기반 설정
using Caffeine.Core;
using Microsoft.Extensions.DependencyInjection;
var services = new ServiceCollection();
services.AddCaffeine(options =>
{
options.ServerUrl = "https://localhost:5001";
options.ApiKey = "your-api-key";
options.Timeout = TimeSpan.FromSeconds(30);
options.EnableSignalR = true;
options.RetryPolicy = new RetryPolicy
{
MaxRetries = 3,
BackoffMultiplier = 2
};
});
services.AddCaffeineDriver<MyDriver>(config =>
{
config.Host = "192.168.1.100";
config.Port = 502;
config.PollingInterval = TimeSpan.FromSeconds(1);
});
⚙️ 설정 옵션
Caffeine 서버 설정
| 옵션 | 타입 | 기본값 | 설명 |
|---|---|---|---|
ServerUrl | string | - | Caffeine 서버 URL (필수) |
ApiKey | string | - | API 인증 키 |
Timeout | int | 30000 | 요청 타임아웃 (ms) |
EnableSignalR | bool | true | SignalR 실시간 통신 활성화 |
RetryPolicy.MaxRetries | int | 3 | 최대 재시도 횟수 |
RetryPolicy.BackoffMultiplier | double | 2.0 | 재시도 간격 배율 |
드라이버 설정
| 옵션 | 타입 | 기본값 | 설명 |
|---|---|---|---|
Name | string | - | 드라이버 이름 |
Host | string | localhost | 장비 호스트 |
Port | int | - | 장비 포트 |
PollingInterval | TimeSpan | 1초 | 폴링 간격 |
ConnectionTimeout | int | 5000 | 연결 타임아웃 (ms) |
MaxConcurrentConnections | int | 10 | 최대 동시 연결 수 |
예제:
{
"Drivers": {
"ModbusDriver": {
"Name": "Modbus TCP Driver",
"Host": "192.168.1.100",
"Port": 502,
"PollingInterval": "00:00:01",
"ConnectionTimeout": 5000,
"Tags": [
{
"Name": "Equipment1.Temperature",
"Address": "HR:100",
"DataType": "Float"
}
]
}
}
}
데이터베이스 설정
PostgreSQL
{
"ConnectionStrings": {
"PostgreSQL": "Host=localhost;Port=5432;Database=caffeine;Username=postgres;Password=secret;Pooling=true;MinPoolSize=1;MaxPoolSize=20"
}
}
옵션:
Host: 데이터베이스 호스트Port: 포트 (기본: 5432)Database: 데이터베이스 이름Username: 사용자명Password: 비밀번호Pooling: 연결 풀링 활성화MinPoolSize,MaxPoolSize: 풀 크기
Redis
{
"ConnectionStrings": {
"Redis": "localhost:6379,password=secret,abortConnect=false,connectTimeout=5000"
}
}
옵션:
password: 비밀번호abortConnect: 연결 실패 시 중단 여부connectTimeout: 연결 타임아웃 (ms)syncTimeout: 동기 작업 타임아웃 (ms)
InfluxDB
{
"InfluxDB": {
"Url": "http://localhost:8086",
"Token": "your-token",
"Organization": "nexcode",
"Bucket": "caffeine"
}
}
로깅 설정
{
"Serilog": {
"MinimumLevel": {
"Default": "Information",
"Override": {
"Microsoft": "Warning",
"System": "Warning",
"Caffeine": "Debug"
}
},
"WriteTo": [
{
"Name": "Console",
"Args": {
"outputTemplate": "[{Timestamp:HH:mm:ss} {Level:u3}] {Message:lj}{NewLine}{Exception}"
}
},
{
"Name": "File",
"Args": {
"path": "logs/caffeine-.txt",
"rollingInterval": "Day",
"retainedFileCountLimit": 30
}
},
{
"Name": "Seq",
"Args": {
"serverUrl": "http://localhost:5341"
}
}
],
"Enrich": ["FromLogContext", "WithMachineName", "WithThreadId"]
}
}
🔒 보안 및 환경변수
필수 환경변수 (보안)
프로덕션 환경에서 반드시 설정해야 하는 환경변수입니다. 미설정 시 앱 기동이 실패합니다.
| 환경변수 | appsettings 경로 | 설명 | 예시 |
|---|---|---|---|
CAFFEINE_MASTER_API_KEY | Security:MasterApiKey | Engine API 인증 마스터 키 | sk-caffeine-prod-xxxx |
JWT__Secret | JWT:Secret | JWT 토큰 서명 비밀 키 (최소 32자) | your-256-bit-secret-key-here!! |
Security__EncryptionKey | Security:EncryptionKey | 데이터 암호화 키 | my-encryption-key-256 |
Security__EncryptionSalt | Security:EncryptionSalt | 데이터 암호화 솔트 | my-salt-value |
CAFFEINE_KEY_BYTES | - | PKV 라이선스 검증 키 (Base64 지원) | AQIDBA== |
선택 환경변수 (인프라)
| 환경변수 | appsettings 경로 | 설명 | 기본값 |
|---|---|---|---|
INFLUXDB_TOKEN | InfluxDB:Token | InfluxDB 인증 토큰 (미설정 시 비활성화) | (비활성화) |
InfluxDB__Bucket | InfluxDB:Bucket | InfluxDB 버킷 이름 | caffeine |
InfluxDB__Org | InfluxDB:Org | InfluxDB 조직 | rxiot |
MQTT_HOST | - | MQTT 브로커 호스트 | mqtt-broker |
MQTT_USE_TLS | - | MQTT TLS 활성화 | false |
MQTT_USERNAME | - | MQTT 인증 사용자명 | (없음) |
MQTT_PASSWORD | - | MQTT 인증 비밀번호 | (없음) |
선택 환경변수 (애플리케이션)
| 환경변수 | 설명 | 기본값 |
|---|---|---|
ENGINE_API_URL | Admin → Engine API 연결 URL | http://localhost:5000 |
CAFFEINE_MODEL_PATH | ML 모델 파일(.onnx) 경로 | models/anomaly_model.onnx |
CAFFEINE_TEST_MODE | 테스트 모드 (true 시 HealthChecks UI 비활성화) | (없음) |
선택 환경변수 (보안 설정)
| appsettings 경로 | 설명 | 기본값 |
|---|---|---|
Security:IpWhitelist | 허용 IP 배열 (["*"] = 전체 허용) | ["127.0.0.1", "::1"] |
JWT:ValidIssuer | JWT 발급자 검증 | Caffeine.Identity |
JWT:ValidAudience | JWT 수신자 검증 | Caffeine.Engine |
JWT:RequireHttpsMetadata | HTTPS 메타데이터 강제 (프로덕션 권장) | false |
.env 파일 템플릿
deploy/.env.example을 복사하여 사용합니다:
cp deploy/.env.example deploy/.env
# .env 파일을 편집하여 실제 값 입력
Secrets 관리
개발 환경 (User Secrets):
dotnet user-secrets init
dotnet user-secrets set "JWT:Secret" "your-256-bit-secret-key-here!!"
dotnet user-secrets set "Security:EncryptionKey" "my-encryption-key"
dotnet user-secrets set "Security:EncryptionSalt" "my-salt-value"
프로덕션 (환경 변수):
export CAFFEINE_MASTER_API_KEY="sk-caffeine-prod-xxxx"
export JWT__Secret="your-256-bit-secret-key-here!!"
export Security__EncryptionKey="my-encryption-key"
export Security__EncryptionSalt="my-salt-value"
export INFLUXDB_TOKEN="your-influxdb-token"
Docker Compose (.env 파일):
services:
caffeine-engine:
env_file:
- .env
SSL/TLS 설정
{
"Kestrel": {
"Endpoints": {
"Https": {
"Url": "https://*:5001",
"Certificate": {
"Path": "certs/certificate.pfx",
"Password": "${CERT_PASSWORD}"
}
}
}
}
}
🌍 환경별 설정
설정 파일 우선순위
appsettings.json(기본)appsettings.{Environment}.json(환경별)- 환경 변수
- 명령줄 인수
- User Secrets (개발 환경)
설정 파일 구성:
appsettings.json (공통 — 시크릿 값 미포함)
appsettings.Development.json (개발 — 디버그 로깅, IP 전체 허용)
appsettings.Production.json (프로덕션 — Warning 로깅, HTTPS 강제)
환경 설정 예제
appsettings.Production.json:
{
"Logging": {
"LogLevel": {
"Default": "Warning",
"Caffeine": "Information"
}
},
"JWT": {
"RequireHttpsMetadata": true
}
}
📊 성능 조정
태그 폴링 최적화
{
"Drivers": {
"MyDriver": {
"PollingStrategy": "Adaptive",
"MinPollingInterval": "00:00:00.100",
"MaxPollingInterval": "00:00:05",
"BatchSize": 100
}
}
}
연결 풀 설정
{
"ConnectionPools": {
"PostgreSQL": {
"MaxPoolSize": 100,
"MinPoolSize": 10,
"ConnectionIdleLifetime": 300
},
"Redis": {
"MaxPoolSize": 50
}
}
}
🔍 검증
설정 검증 코드
using Microsoft.Extensions.Options;
public class CaffeineOptionsValidator : IValidateOptions<CaffeineOptions>
{
public ValidateOptionsResult Validate(string name, CaffeineOptions options)
{
if (string.IsNullOrEmpty(options.ServerUrl))
{
return ValidateOptionsResult.Fail("ServerUrl is required");
}
if (options.Timeout <= 0)
{
return ValidateOptionsResult.Fail("Timeout must be positive");
}
return ValidateOptionsResult.Success;
}
}
// 등록
services.AddSingleton<IValidateOptions<CaffeineOptions>, CaffeineOptionsValidator>();
미들웨어 설정
ExceptionHandlingMiddleware (전역 예외 처리)
Engine의 HTTP 파이프라인에 전역 예외 처리 미들웨어가 등록되어 있다. 별도의 설정 파일 없이 자동 활성화되며, 처리되지 않은 예외를 catch하여 안전한 JSON 에러 응답을 반환한다.
동작 방식:
- 모든 예외를
ILogger<ExceptionHandlingMiddleware>로 기록 - 클라이언트에는
ApiErrorResponse형식의 고정 메시지만 반환 (내부 정보 비노출) - OpenTelemetry
Activity.Current?.Id를 TraceId로 포함
에러 응답 형식:
{
"code": "INTERNAL_SERVER_ERROR",
"message": "서버 내부 오류가 발생했습니다.",
"traceId": "00-abc123def456-789ghi-01"
}
별도의 on/off 설정은 없다. 항상 활성 상태이며, 디버깅이 필요한 경우 응답의 traceId로 서버 로그(Serilog SQLite Sink)에서 전체 스택 트레이스를 검색한다.
NullMessageProducer (Kafka 비활성화)
Kafka 메시지 브로커가 구성되지 않은 환경에서 자동으로 활성화되는 No-op 구현체이다.
| 항목 | 설명 |
|---|---|
| 등록 위치 | InfrastructureExtensions.AddCaffeineInfrastructure() |
| 인터페이스 | IMessageProducer (Caffeine.Core.Abstractions.Messaging) |
| 구현체 | NullMessageProducer (Caffeine.Infrastructure.Messaging) |
| 동작 | ProduceAsync() 호출 시 Debug 로그만 기록, 메시지 전송 생략 |
활성화 조건: InfrastructureExtensions에서 기본 등록으로 항상 NullMessageProducer가 등록된다. Kafka를 사용하려면 Engine의 Program.cs에서 IProducer<Null, string>를 별도 등록하고, 이를 사용하는 KafkaMessageProducer 구현체를 추가 등록해야 한다.
Kafka 연결 문자열 설정 (선택):
{
"ConnectionStrings": {
"Kafka": "kafka:29092"
}
}
미설정 시 기본값 kafka:29092가 사용되지만, NullMessageProducer가 등록되어 있으므로 실제 Kafka 연결 없이도 Engine이 정상 기동한다.
📚 참고 자료
작성일: 2026-02-09 버전: 2.2