> 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
```

이 페이지에서는 변경할 가능성이 높은 옵션을 다룹니다. 전체 목록은 [환경 변수](https://docs.roboflow.com/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`입니다. Jetson 및 터널 관련 예외는 [네트워크 액세스](https://docs.roboflow.com/deployment/ko/self-hosted/inference-server/configuration/security.md#restrict-network-access) 를 참조하세요.

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

**`ALLOW_ORIGINS`**: 문자열(기본값 `*`). HTTP 인터페이스에서 FastAPI와 함께 사용하는 CORS 미들웨어의 `allow_origins` 속성을 설정합니다. 쉼표로 구분해 여러 값을 지정할 수 있습니다. 예: `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`). 모든 `/clip` 경로에서 사용할 OpenAI 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`**: boolean (기본값 `False`). 설정하면 Inference Server는 HTTP 대신 HTTPS로 트래픽을 제공하며, 인증서와 개인 키는 다음에서 읽습니다. `SSL_CERTFILE` 및 `SSL_KEYFILE`.

**`SSL_CERTFILE`**: string (기본값 `/etc/inference/certs/server.crt`) 및 **`SSL_KEYFILE`**: string (기본값 `/etc/inference/certs/server.key`). 컨테이너 내부에서 PEM으로 인코딩된 인증서와 개인 키의 경로입니다. 기본값은 편리한 마운트 지점이므로, 일반적으로 인증서와 키를 다음 경로에 바인드하고 `/etc/inference/certs/` 에 설정한 다음 `ENABLE_HTTPS=true`.

`SSL_KEYFILE_PASSWORD`: string (선택 사항). 암호화된 개인 키의 암호를 Uvicorn 실행기에 제공합니다. 병렬 Gunicorn 실행기는 이를 지원하지 않습니다.

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

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

## 보안 게이트웨이

**`SECURE_GATEWAY`**: string (기본값 미설정). 에어갭 배포에 사용할 [Roboflow 보안 게이트웨이](https://docs.roboflow.com/deployment/ko/self-hosted/enterprise/secure-gateway.md) 의 주소를 설정합니다. Roboflow API 및 모델 다운로드 트래픽은 이 프록시를 통해 라우팅됩니다. 프록시를 사용할 수 없는 트래픽은 다음과 같이 비활성화되거나 다른 경로로 전달됩니다.

* Inference 버전 확인(다음 주소를 호출하는 `api.github.com`기능)은 강제로 비활성화됩니다. `DISABLE_VERSION_CHECK` 는 다음으로 설정됩니다. `True` 명시적으로 다른 값으로 설정했더라도 마찬가지입니다.
* 다음 설정을 `WORKFLOWS_STEP_EXECUTION_MODE=remote` 다음 설정과 함께 사용하면 `WORKFLOWS_REMOTE_API_TARGET=hosted`, 단계 실행은 다음으로 대체됩니다. `local` 경고가 표시됩니다. 호스팅된 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`, 게이트웨이 인증서를 신뢰하도록 설정하세요. Inference 1.6.0 이상에서는 스킴이 없는 주소를 HTTPS로 처리하며 루프백이 아닌 일반 텍스트 게이트웨이를 거부합니다. 자세한 내용은 다음을 참조하세요: [마이그레이션 범위](https://docs.roboflow.com/deployment/ko/self-hosted/inference-server/configuration/security-migration.md#gateway-transport).

기존 `LICENSE_SERVER` 환경 변수도 계속 사용할 수 있지만 더 이상 사용되지 않습니다.
