# 환경 변수

> 운영자가 조정할 수 있는 모든 환경 변수 — 번들 .env 파일, 백엔드, 추론 런타임, TLS 노브.

구성은 두 수준에서 스택에 들어갑니다: **번들 `.env` 파일**(오프라인 설치 시 Docker Compose가
읽음)과 **컨테이너별 환경 변수**(compose 파일 자체가 설정). 이 페이지는 둘 다 나열합니다.

번들 설치에서는 보통 `compose/.env`만 편집합니다 — 설치 프로그램이 `.env.template`에서 이를
생성하며 업데이트 후에도 유지됩니다. 컨테이너별 변수는 릴리스 compose에 사전 배선되어
있습니다. 직접 유지 관리하는 compose 오버라이드 파일로만 이를 재정의하세요.

## 번들 `.env` (릴리스 설치)

| 변수 | 기본값 | 효과 |
|---|---|---|
| `AIBOARD_JWT_SECRET` | 설치 시 생성 | JWT 서명 키(≥ 32바이트). **필수** — 릴리스 compose는 이것 없이는 시작을 거부합니다. |
| `AIBOARD_HTTP_PORT` | `80` | 대시보드 HTTP 포트. |
| `AIBOARD_ALT_PORT` | `3000` | 보조 대시보드 포트. |
| `AIBOARD_HTTPS_PORT` | `443` | HTTPS 포트(TLS 오버레이 전용). |
| `AIBOARD_TLS_ENABLED` | `0` | `1` = 생성된 자체 서명 인증서로 HTTPS를 제공하고 80 → 443 리디렉션. |
| `AIBOARD_TLS_HOST` | — | 인증서 SAN에 구워 넣을 공백/쉼표 구분 IP/호스트명. |
| `AIBOARD_TLS_DIR` | `<bundle>/tls` | `cert.pem` / `key.pem`이 위치하는 곳(설치 시 절대 경로로 기록). |
| `AIBOARD_CERTS_ENABLED` | `0` | `1` = 운영자가 프로비저닝한 데이터소스 클라이언트 인증서를 마운트. |
| `AIBOARD_CERTS_DIR` | `<bundle>/certs` | 보안 MQTT / OPC UA용 CA + 클라이언트 인증서, 읽기 전용 마운트. |
| `AIBOARD_MODEL_SEED_DIR` | `<bundle>/models` | 시드 모델 디렉터리(`update.sh`가 재지정). |
| `BACKEND_IMAGE` · `FRONTEND_IMAGE` · `INFERENCE_IMAGE` | 번들 매니페스트에서 | 실행할 이미지 태그 — `install.sh` / `update.sh`가 관리. 수동으로 편집하지 마세요. |

## 백엔드 컨테이너

| 변수 | 기본값(릴리스) | 효과 |
|---|---|---|
| `ASPNETCORE_ENVIRONMENT` | `Production` | 구성 오버레이 선택. |
| `Grpc__InferenceService__Address` | `http://inference:50051` | 추론 런타임 gRPC 대상. |
| `Database__ConnectionString` | `Data Source=/data/aiboard.db` | SQLite 데이터베이스 위치(영속 볼륨). |
| `AIBOARD_JWT_SECRET` | `.env`에서 | JWT 서명 키 폴백. 개발 외 환경에서는 필수. |
| `CORS_ORIGINS` | localhost 개발 오리진 | 쉼표 구분 허용 브라우저 오리진 — 기본이 아닌 호스트에서 UI를 제공할 때 재정의. |
| `AIBOARD_CERTS_ROOT` | `/certs` | 데이터소스 TLS 인증서 경로의 감옥(jail) 루트(임의 파일 읽기 차단). |
| `AIBOARD_CSV_ROOT` | `/data/csv` | CSV 재생/출력 파일 경로의 감옥 루트. |

더 깊은 백엔드 튜닝(토큰 수명, 속도 제한, 모델 검증 상한, 보존 윈도우)은 `appsettings` 키에
있습니다. 이 중 어느 것이든 표준 .NET 이중 밑줄 관례로 재정의할 수 있습니다. 예:
`Auth__Jwt__ExpiryHours=12` 또는 `LoginRateLimit__PermitLimit=10`.

| appsettings 키 | 기본값 | 효과 |
|---|---|---|
| `Auth:Jwt:ExpiryHours` | `8` | 로그인 토큰 수명(리프레시 토큰 없음). |
| `LoginRateLimit:*` | on, 60초당 5회 | IP당 실패 로그인 게이트. |
| `ExternalApi:Enabled` + `ExternalApi:RateLimit:*` | on, 60초당 100회 | 외부 API 키 표면과 그 속도 제한. |
| `ModelManagement:MaxVersionsToKeep` | `5` | 정리 시 버전 가지치기. |
| `ModelManagement:Validation:MaxModelSizeMb` | `500` | 업로드 크기 상한. |
| `InferenceObservability:RetentionDays` | `3` | 추론 감사 로그 보존(SQLite). |
| `LoggingService:Retention:MaxEntries` | `10000` | LogViewer 저장소 상한. |
| `Swagger:Enabled` | `true` | `http://<box>:5000/`의 Swagger UI. 잠긴 사이트에서 API 문서를 숨기려면 `false`로 설정. |

## 추론 컨테이너

| 변수 | 기본값 | 효과 |
|---|---|---|
| `EXECUTION_MODE` | `auto` | `auto`(TensorRT → CUDA → CPU), `tensorrt`, `cuda`, 또는 `cpu`. |
| `STRICT_EP` | off | `1` = 핀 고정된 GPU 모드를 조용히 CPU로 저하시키는 대신 시작을 거부. |
| `MODEL_PATH` | `/app/models/predictive_maintenance.onnx` | 시작 시 로드되는 시드 모델(볼륨 마운트, 이미지에 절대 굽지 않음). |
| `MODEL_STORAGE_PATH` | `/data/models` | 등록된 모델 버전(백엔드와 공유 볼륨). |
| `LOG_DIR` | `/data/logs`(릴리스) | 회전형 Warning+ 포렌식 로그 파일 활성화. 미설정 = 콘솔 전용. |
| `USE_REAL_INFERENCE` | `true` | `true`로 유지해야 함 — mock 모드는 폐기됨. 아니면 서비스가 빠르게 실패. |
| `INFERENCE_STUB` | `0` | 0 예측을 반환하는 디버그 우회. **프로덕션에서 절대 활성화하지 마세요.** |
| `FORCE_CPU` | off | `EXECUTION_MODE=cpu`의 레거시 별칭. |

Jetson 번들은 추가로 `OPENBLAS_CORETYPE`를 핀 고정하고 `runtime: nvidia`로 실행합니다 —
[Jetson 배포](/ko/install-deploy/jetson-deployment/)를 참조하세요.

## 프런트엔드 컨테이너

| 변수 | 기본값 | 효과 |
|---|---|---|
| `AIBOARD_TLS_ENABLED` | `0` | TLS 인식 nginx 엔트리포인트 활성화(`AIBOARD_TLS_DIR`에서 인증서 마운트). |

API 및 허브 URL은 빌드 시 프런트엔드에 컴파일됩니다(동일 오리진 `/api` + `/hub/realtime`) —
런타임에 구성할 것이 없습니다.

## 다음 단계

  - [오프라인 번들 설치](/ko/install-deploy/offline-bundle-install/) — .env 파일이 어디서 오고 비밀이 어떻게 생성되는지.
  - [시스템 아키텍처](/ko/architecture/) — 어느 서비스가 어떤 설정을 읽는지.
  - [보안](/ko/security/) — 노출된 포트와 비밀에 대한 강화 체크리스트.