> For the complete documentation index, see [llms.txt](https://docs.roboflow.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.roboflow.com/deployment/ko/self-hosted/inference-server/configuration/docker-configuration.md).

# Docker 구성 옵션

자체 호스팅 Roboflow Inference 컨테이너를 구성합니다 - 네트워킹, CORS, NMS 기본값, 모델 캐시, 워커, HTTPS 및 Secure Gateway.

추론 서버에는 환경 변수로 설정하는 여러 구성 가능한 매개변수가 있습니다. 환경 변수를 설정하려면 `docker run`, 다음을 사용하세요 `-e` 플래그:

```bash
docker run -it --rm -e ENV_VAR_NAME=env_var_value -p 127.0.0.1:9001:9001 --gpus all roboflow/roboflow-inference-server-gpu:latest
```

이 페이지에서는 변경할 가능성이 가장 높은 옵션을 다룹니다. 전체 목록은 다음을 참조하세요: [환경 변수](/deployment/ko/self-hosted/inference-server/configuration/environment-variables.md).

## 네트워킹

`HOST`: 문자열(기본값 `0.0.0.0`). 컨테이너 내부의 인터페이스를 선택합니다. Docker 브리지 네트워킹에서는 게시된 포트가 서버에 도달할 수 있도록 이 값을 유지하세요.

호스트 측 매핑을 사용하세요 `-p 127.0.0.1:9001:9001` 로컬 전용 액세스에는 사용하거나, 의도적으로 LAN 인터페이스를 선택하세요. CLI의 `--bind-address` 이 매핑을 제어합니다. 대신 macOS 및 Windows 데스크톱 번들은 `HOST`, 기본값은 `127.0.0.1`. 참조: [네트워크 액세스](/deployment/ko/self-hosted/inference-server/configuration/security.md#restrict-network-access) 는 Jetson 및 터널 예외에 대해 설명합니다.

**`PORT`**: 정수(기본값 `9001`). HTTP 인터페이스에서 사용하는 포트를 설정합니다.

**`ALLOW_ORIGINS`**: 문자열(기본값 `*`). 다음을 설정합니다: `allow_origins` HTTP 인터페이스에 FastAPI와 함께 사용되는 CORS 미들웨어의 속성입니다. 여러 값을 쉼표로 구분하여 제공할 수 있습니다. 예: `ALLOW_ORIGINS=orig1.com,orig2.com`.

## 추론 동작

**`CLASS_AGNOSTIC_NMS`**: 불리언(기본값 `False`). 탐지 모델(객체 탐지, 인스턴스 분할 등)의 기본 비최대 억제(NMS) 동작을 설정합니다.  `True`다음일 때, NMS는 클래스 비구분 방식이므로 서로 다른 클래스의 겹치는 탐지가 IoU 임계값에 따라 제거될 수 있습니다. 다음일 때 `False`, 같은 클래스의 겹치는 탐지만 제거 대상으로 고려됩니다.

**`MAX_CANDIDATES`**: 정수(기본값 `3000`). 탐지를 위한 최대 후보 수입니다.

**`MAX_DETECTIONS`**: 정수(기본값 `300`). 모델이 반환하는 최대 탐지 수입니다.

**`FIX_BATCH_SIZE`**: 불리언(기본값 `False`). 다음일 때 `True`, 배치 크기는 이 서버에 대해 구성된 최대 배치 크기로 고정됩니다.

**`MAX_ACTIVE_MODELS`**: 정수(기본값 `8`). 내부 모델 관리자가 한 번에 메모리에 유지하는 최대 모델 수입니다. 기본적으로 모델 큐는 새 모델을 위한 공간을 만들 때 가장 최근에 접근되지 않은 모델을 제거합니다.

**`NUM_WORKERS`**: 정수(기본값 `1`). HTTP 인터페이스에서 사용하는 워커 수입니다.

## CLIP 모델 옵션

**`CLIP_VERSION_ID`**: 문자열(기본값 `ViT-B-16`). 다음에서 사용하는 OpenAI CLIP 버전을 설정합니다: `/clip` 라우트입니다. 사용 가능한 버전은 `RN101`, `RN50`, `RN50x16`, `RN50x4`, `RN50x64`, `ViT-B-16`, `ViT-B-32`, `ViT-L-14-336px`, 그리고 `ViT-L-14`.

**`CLIP_MAX_BATCH_SIZE`**: 정수(기본값 `8`). CLIP 모델 추론 함수가 허용하는 최대 배치 크기를 설정합니다.

## 모델 캐시

**`MODEL_CACHE_DIR`**: 문자열(기본값 `/tmp/cache`). 루트 모델 캐시 디렉터리의 컨테이너 경로를 설정합니다.

**`TENSORRT_CACHE_PATH`**: 문자열(기본값: 다음 값) `MODEL_CACHE_DIR`). TensorRT 캐시 디렉터리의 컨테이너 경로를 설정합니다. 이 경로를 호스트에 마운트된 볼륨과 함께 설정하면 TensorRT 기반 서버의 콜드 스타트 시간이 줄어듭니다.

### 영구 모델 캐시

기본적으로 모델 가중치는 컨테이너 내부의 다음 위치에 저장됩니다: `/tmp/cache` 그리고 **컨테이너 재시작 또는 시스템 재부팅 시 손실됩니다**. 프로덕션 배포에서는 다운로드한 가중치를 보존하기 위해 영구 호스트 볼륨을 마운트하세요:

```bash
# 호스트에 영구 캐시 디렉터리 생성
mkdir -p /var/lib/roboflow/cache

# 영구 캐시로 컨테이너 실행
docker run -d \
  -p 127.0.0.1:9001:9001 \
  -v /var/lib/roboflow/cache:/tmp/cache \
  -e MODEL_CACHE_DIR=/tmp/cache \
  roboflow/roboflow-inference-server-cpu:latest
```

유의할 점:

* 호스트 경로는 영구 저장소에 있어야 하며, 다음 위치에 있으면 안 됩니다: `/tmp`.
* 마운트된 디렉터리는 컨테이너 사용자에 맞는 적절한 권한이 필요합니다(일반적으로 이미지에 따라 UID 1000 또는 root).
* 영구 캐시를 사용하면 배포 전에 가중치를 미리 채워둘 수 있고, 컨테이너 업데이트 후에도 유지됩니다.

참조 [오프라인 가중치 다운로드](https://docs.roboflow.com/reference/inference/inference-python/offline-weights) 가중치를 미리 다운로드하고 캐싱하는 방법에 대한 자세한 내용은 다음을 참조하세요.

## HTTPS / TLS

**`ENABLE_HTTPS`**: 불리언(기본값 `False`). 설정하면 추론 서버는 HTTP 대신 HTTPS로 트래픽을 제공하며, 인증서와 개인 키를 다음에서 읽습니다: `SSL_CERTFILE` 와 `SSL_KEYFILE`.

**`SSL_CERTFILE`**: 문자열(기본값 `/etc/inference/certs/server.crt`) 그리고 **`SSL_KEYFILE`**: 문자열(기본값 `/etc/inference/certs/server.key`). 컨테이너 내부의 PEM 인코딩된 인증서와 개인 키 경로입니다. 기본값은 편리한 마운트 지점이므로, 보통은 인증서와 키를 다음 위치에 바인드하기만 하면 됩니다: `/etc/inference/certs/` 그리고 다음을 설정합니다: `ENABLE_HTTPS=true`.

`SSL_KEYFILE_PASSWORD`: 문자열(선택 사항). Uvicorn 런처에 암호화된 개인 키의 암호문구를 제공합니다. 병렬 Gunicorn 런처는 이를 지원하지 않습니다.

`SSL_CA_CERTS`: 문자열(선택 사항). HTTPS가 활성화된 경우 mTLS용 클라이언트 CA 번들을 제공합니다. 다음을 참조하세요: [HTTPS 구성](/deployment/ko/self-hosted/inference-server/configuration/https.md#mutual-tls) 강제 적용 및 릴리스 범위에 대해

자체 서명 인증서를 사용한 전체 안내: [HTTPS로 Inference 제공](/deployment/ko/self-hosted/inference-server/configuration/https.md).

## 보안 게이트웨이

**`SECURE_GATEWAY`**: 문자열(기본값 미설정). 다음의 주소를 설정합니다: [Roboflow Secure Gateway](/deployment/ko/self-hosted/enterprise/secure-gateway.md) 에어갭 배포용 프록시입니다. Roboflow API 및 모델 다운로드 트래픽은 이 프록시를 통해 라우팅됩니다. 프록시할 수 없는 트래픽은 다음과 같이 비활성화되거나 재라우팅됩니다:

* 추론 버전 확인(다음을 호출함) `api.github.com`)은 강제로 비활성화됩니다: `DISABLE_VERSION_CHECK` 는 다음으로 설정됩니다: `True` 다른 값으로 명시적으로 구성되었더라도 마찬가지입니다.
* 만약 `WORKFLOWS_STEP_EXECUTION_MODE=remote` 가 다음과 함께 사용되면 `WORKFLOWS_REMOTE_API_TARGET=hosted`, 단계 실행은 다음으로 폴백됩니다: `로컬` 경고와 함께, 호스티드 Roboflow 추론 엔드포인트는 게이트웨이 프록시를 통해 도달할 수 없기 때문입니다. 원격 실행을 유지하려면 다음을 사용하세요: `WORKFLOWS_REMOTE_API_TARGET=self-hosted` **와** 지정하세요 `LOCAL_INFERENCE_API_URL` (기본값 `http://127.0.0.1:9001`)을 게이트웨이 경계 내부에서 도달 가능한 추론 서버로 지정합니다.
* Google Vision 및 Gemini 직접 키 경로, Stability AI, Twilio 미디어 업로드, 외부 호스트로의 웹훅과 같은 타사 통합은 프록시되지 않으며, 게이트웨이 네트워크가 이를 허용하지 않으면 실패합니다.

다음과 같은 명시적 HTTPS 게이트웨이 URL을 사용하세요: `SECURE_GATEWAY=https://gateway.example.com`, 그리고 게이트웨이 인증서를 신뢰하세요. 진행 중인 런타임 강화 빌드는 일반 주소를 HTTPS로 변경하고 루프백이 아닌 평문 게이트웨이를 거부합니다. 다음을 참조하세요: [마이그레이션 범위](/deployment/ko/self-hosted/inference-server/configuration/security-migration.md#gateway-transport).

기존의 `LICENSE_SERVER` 환경 변수는 여전히 허용되지만 더 이상 권장되지 않습니다.