> 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/security-migration.md).

# 보안 구성 마이그레이션

릴리스 범위를 확인하고 localhost 바인딩, 모델 인증, 비디오 제한, 런타임 강화에 대한 자체 호스팅 Inference 설정을 업데이트합니다.

이 가이드는 자체 호스팅 Inference Server, CLI 또는 이미지를 업그레이드할 때 사용하세요. 네트워크 노출 변경과 명시적으로 기능을 활성화해야 하는 변경을 구분합니다.

## 릴리스 상태

이 문서는 2026년 9월 11일 소스 코드와 대조해 확인했습니다. 소스에 병합되었다고 해서 어떤 배포 패키지나 이미지에 해당 변경이 포함되었는지는 알 수 없습니다.

<table data-search="false"><thead><tr><th>변경 사항</th><th>소스 상태</th><th>릴리스 범위</th></tr></thead><tbody><tr><td>로컬호스트 게시 및 데스크톱 바인딩, PR #2943</td><td>병합됨</td><td>설치된 CLI와 데스크톱 번들을 확인하세요. 최초 릴리스 버전은 여기서 검증되지 않았습니다.</td></tr><tr><td>관리형 파이프라인 프로세스 한도 및 RAM 보호 장치, PR #2944</td><td>병합됨</td><td>해당 변경 사항이 포함된 서버 이미지가 필요합니다. 최초 릴리스 버전은 여기서 검증되지 않았습니다.</td></tr><tr><td>로컬 모델 권한 부여 보호 장치, PR #2956</td><td>병합됨</td><td>해당 변경 사항이 포함된 서버 빌드가 필요합니다. 최초 릴리스 버전은 여기서 검증되지 않았습니다.</td></tr><tr><td>모델, 미디어, TLS, 게이트웨이, 오프라인 실행 및 OPC UA 보안 강화, PR #2952</td><td>보류 중, 커밋 54a663f1d에서 검토됨</td><td>릴리스된 이미지에 대한 주장이 아닙니다. 아래 섹션에서는 제안된 런타임 보안 강화 빌드를 설명합니다.</td></tr></tbody></table>

배포하는 패키지와 이미지 버전을 고정한 다음, 해당 버전에 관련 변경 사항이 포함되어 있는지 확인하세요. 소스나 이미지 기본값이 바뀌었다고 기존 컨테이너에 이 변경 사항이 자동으로 적용되는 것은 아닙니다.

## 로컬호스트 게시

일반적인 CPU 및 GPU 실행 시 CLI는 모든 호스트 인터페이스 대신 `127.0.0.1` 에서 게시합니다. 원격 클라이언트는 다음과 같이 명시적으로 노출된 주소를 사용해야 합니다. `inference server start --bind-address 0.0.0.0`. 이 주소에 대한 접근은 신뢰할 수 있는 클라이언트로 제한하세요.

Jetson CLI 실행에서는 `0.0.0.0`을 유지하며, `--tunnel` 도 터널이 연결될 수 있도록 `0.0.0.0` 에서 게시합니다. 데스크톱 번들의 기본값은 `127.0.0.1` 이며 `HOST`를 따릅니다. 수동 Docker 포트 매핑은 운영자가 선택합니다.

### 기능 및 관측 가능성 기본값

사용자 지정 Python은 계속 활성화되어 있으며, 기본적으로 로컬 실행을 사용합니다. 2026년 6월 19일에 기본값을 전환한다는 이전 공지는 더 이상 적용되지 않습니다. Stream API 활성화와 Workspace 인증은 기존 동작을 유지하며, 새로운 스트림 관리 토큰은 추가되지 않습니다.

상태 확인, 문서 및 메트릭 엔드포인트에는 기존 API 키 예외가 계속 적용됩니다. 네트워크 경계와 엔드포인트 목록은 [서버 보안](https://docs.roboflow.com/deployment/ko/self-hosted/inference-server/configuration/security.md) 을 참조하세요.

## 파이프라인 용량

새 프로세스 할당은 `STREAM_MANAGER_MAX_ACTIVE_PIPELINES`에서 중단되며, 기본값은 `8`입니다. 프리로드 수가 더 높으면 유효 한도는 해당 수까지 올라갑니다. 한도에 도달해도 기존 유휴 워커는 할당할 수 있으며, 웜 풀 보충은 이 한도를 초과하지 않습니다.

더 많은 워커가 필요한 배포 환경에서는 용량을 확인한 후 더 높은 한도를 설정해야 합니다. RAM 보호 장치는 샘플이 없는 워커도 처리하므로 초기화 중에 실패하지 않습니다. 자세한 내용은 [비디오 구성](https://docs.roboflow.com/deployment/ko/self-hosted/inference-server/configuration/video-configuration.md#managed-pipeline-limits).

## 로컬 모델 권한 부여

온라인 서버에서는 다음 설정을 함께 사용하는 것을 거부합니다. `MODELS_CACHE_AUTH_ENABLED=True` 및 `ALLOW_INFERENCE_MODELS_DIRECTLY_ACCESS_LOCAL_PACKAGES=True`. 모델별 API 키 검사가 필요하면 로컬 로딩을 비활성화하세요. 로컬 패키지 호출자를 의도적으로 신뢰하는 경우에만 모델 권한 부여를 비활성화하세요.

오프라인 배포 환경에서는 명시적으로 설정하는 `ALLOW_OFFLINE_MODEL_CACHE_AUTH_BYPASS` 요구사항입니다. 자세한 내용은 [모델 패키지 보안](https://docs.roboflow.com/deployment/ko/self-hosted/inference-server/configuration/model-security.md).

## 비디오 소스 검증

런타임 강화 빌드가 적용되면 기본적으로 원시 GStreamer 설명은 거부되며, 다음과 같은 경로만 있는 파일 이름은 `video.mp4` 다음과 같이 바꿔야 합니다. `./video.mp4`다음 설정은 `ALLOW_UNSAFE_GSTREAMER_PIPELINES=True` 원시 파이프라인 해석이 필요하고 이를 신뢰하는 워크로드에만 사용하세요.

다음 [지원되는 참조 형식](https://docs.roboflow.com/deployment/ko/self-hosted/inference-server/configuration/video-configuration.md#server-side-video-references) 에는 별도의 옵트인 없이 일반 RTSP 및 RTMP URL이 포함됩니다. 직접 로컬 Python 미디어를 사용하거나 SDK 클라이언트에서 파일을 여는 방식은 변경되지 않습니다.

## 모델 패키지 신뢰

런타임 강화 빌드가 적용되면 JetPack 5.1.1, 6.2.0, 7.2.0 이미지는 `ALLOW_INFERENCE_MODELS_UNTRUSTED_PACKAGES` 설정을 `True` 에서 `False`로 변경합니다. `inference-models-speed` 벤치마크도 CLI, 어댑터, Python 헬퍼의 기본값을 변경해 신뢰할 수 없는 패키지를 거부합니다.

실행 가능한 패키지를 신뢰하는 경우에만 이미지 설정 또는 벤치마크의 `--allow-untrusted-packages` 플래그를 사용해 명시적으로 옵트인하세요. 자세한 내용은 [모델 패키지 보안](https://docs.roboflow.com/deployment/ko/self-hosted/inference-server/configuration/model-security.md#package-trust-defaults)을 참조하세요. 로컬 패키지에 직접 액세스하는 설정은 별개입니다.

이 변경으로 이전에 게시된 JetPack 6.0 이미지는 업데이트되지 않으며, 검토된 소스에는 해당 Dockerfile이 더 이상 없습니다. 해당 배포는 별도로 목록을 작성해 관리하세요.

## TLS 클라이언트 인증서

런타임 강화 빌드가 적용되면 Python Uvicorn, 셸 Uvicorn 및 병렬 Gunicorn 실행기는 `ENABLE_HTTPS=True` 와 `SSL_CA_CERTS` 가 모두 설정된 경우 유효한 클라이언트 인증서를 요구합니다. 업그레이드하기 전에 애플리케이션과 상태 확인 또는 메트릭 확인에 사용할 클라이언트 인증서를 준비하세요.

클라이언트 CA 없이 HTTPS를 사용하면 서버 전용 TLS가 유지되며, HTTPS를 비활성화하면 HTTP가 기본값으로 사용됩니다. 자세한 내용은 [HTTPS를 통한 추론 제공](https://docs.roboflow.com/deployment/ko/self-hosted/inference-server/configuration/https.md#mutual-tls).

### 암호화된 키

병렬 Gunicorn 실행기는 해당 옵션을 지원하지 않으므로 `SSL_KEYFILE_PASSWORD` 를 거부합니다. 암호화된 키를 사용하려면 Uvicorn 실행기를 사용하세요. Python 및 셸 Uvicorn 모두 암호를 지원합니다.

## 게이트웨이 전송

Inference 1.6.0 이상에서는 포트가 지정된 호스트 형식의 `SECURE_GATEWAY=host:port` 값이 HTTP를 HTTPS로 전환하고 마이그레이션 경고를 표시합니다. 업그레이드하기 전에 명시적인 `https://` URL을 사용하고 게이트웨이 인증서 신뢰를 구성하세요.

일반 HTTP는 명시적으로 구성된 루프백 IP 또는 `localhost`에 대해서만 허용됩니다. 예를 들면 다음과 같습니다. `http://127.0.0.1:8080`; 원격 및 LAN 게이트웨이는 HTTPS를 제공해야 합니다. 지원되지 않는 스킴, 포함된 사용자 인증 정보, 쿼리, 프래그먼트 및 공백이 있으면 Inference와 별도로 설치된 `inference-models` 패키지 모두에서 구성 가져오기에 실패합니다.

루프백 터널은 서버 자체의 네트워크 네임스페이스에서 연결할 수 있어야 합니다. 게이트웨이 설정(기존 [Inference 서버 연결](https://docs.roboflow.com/deployment/ko/self-hosted/enterprise/secure-gateway.md#connecting-inference-servers) 의 설정 포함)에 대해서는 `LICENSE_SERVER` 별칭을 참조하세요.

## 오프라인 사용자 지정 Python

런타임 강화 예정 빌드에서는 `OFFLINE_MODE=True` 와 `WORKFLOWS_CUSTOM_PYTHON_EXECUTION_MODE=modal` 을 함께 설정하면 코드가 로컬에서 조용히 실행되는 대신 시작이 실패합니다. 신뢰할 수 있는 코드에 대해 로컬 실행을 허용하려면 `local` 을 명시적으로 선택하고, Modal을 사용하려면 온라인 연결을 유지하세요.

실행 모드에는 `local` 과 `modal`을 사용할 수 있습니다. 대소문자와 앞뒤 공백은 무시되며, 알 수 없는 값을 지정하면 시작이 실패합니다. 이 설정은 일반적인 로컬 사용자 지정 Python 실행을 비활성화하지 않습니다.

## OPC UA 자격 증명

런타임 강화 예정 빌드에서는 풀링된 OPC UA 세션을 엔드포인트, 사용자 이름 및 암호별로 격리합니다. 암호가 잘못되었거나 비어 있거나 생략된 요청은 다른 암호로 인증된 세션을 재사용할 수 없습니다. 자격 증명을 교체하면 별도의 연결이 생성됩니다.

워크플로 작성자는 기존과 같은 자격 증명 필드를 계속 사용하면 됩니다. 연결 관리자를 직접 호출하는 통합은 원래 암호를 `release_connection` 및 `invalidate_connection`에 전달해야 합니다. 익명 세션의 경우 명시적으로 `None` 을 전달해야 합니다.

## 기타 수정 사항

런타임 강화 예정 빌드는 메모리 내 큐가 가득 찼을 때 사용량 수집기가 멈추는 문제를 수정합니다. 사용량 수집을 비활성화하거나 모니터링 수신 동의를 변경하지는 않습니다. CI 셸 입력 검증 및 검토 도구 설치 변경에는 배포 구성 변경이 필요하지 않습니다.
