포트 및 네트워크 동작
Insight는 일반적인 작동 중에 여러 포트를 사용합니다. 기본 포트는 SDK 컨테이너 내부 또는 직접 설치된 DevKit에서 사용되는 포트입니다. Neat 개발 환경에서 SDK는 해당 서비스를 호스트 포트에 게시합니다. 기본 호스트 포트가 이미 사용 중인 경우, sima-cli는 다른 사용 가능한 호스트 포트를 할당할 수 있습니다.
| 포트 맵 이름 | 기본 포트 또는 포트 범위 | 프로토콜 | 목적 |
|---|---|---|---|
mainUI | 9900 | HTTPS/TCP | 주요 Insight 웹 UI, HTTP API 및 HTTP MJPEG 스트리밍 소스입니다. |
videoUI | 8081 | HTTPS/TCP | WebRTC 비디오 뷰어 사용자 인터페이스. |
rtsp.tcp | 8554 | RTSP/TCP | 업로드된 미디어에서 생성된 RTSP 스트리밍 소스입니다. |
videoUDP | 9000-9079 | UDP | 시청자 채널을 위한 비디오 RTP 콘텐츠 업로드 0-79. |
metadataUDP | 9100-9179 | UDP | 뷰어 채널을 위한 메타데이터 JSON 가져오기 0-79. |
webRTC | 40000-40199 | UDP | WebRTC 미디어 및 메타데이터가 비디오 프레임워크에서 브라우저로 전송되는 DataChannel. |
webrtcWhip | 8889 | HTTPS/TCP | WHIP를 통해 브라우저 웹캠을 MediaMTX에 게시하고 RTSP 소스로 다시 제공합니다. |
webrtcWhipIce | 8189 | UDP | 브라우저 웹캠 게시를 위한 ICE 미디어입니다. 시그널링은 webrtcWhip를 사용하고 실제 비디오는 여기로 수신되므로 두 포트 모두 접근 가능해야 합니다. |
webSSH | 8022 | HTTPS/TCP | 사용 가능한 경우 브라우저 셸을 페어링된 DevKit로 연결합니다. |
Insight는 또한 127.0.0.1:9901(TCP)에서 mediamtx 제어 API를 실행합니다. 이 API는 루프백 전용이고, 시작할 때마다 생성되는 비밀번호로 보호되며, Insight가 웹캠 소스를 확인하고, 외부 게시자를 감지하고, 끌어온 스트림을 설정하는 데에만 사용하므로 포트 매핑이 필요 없습니다. 다른 mediamtx 포트와 마찬가지로, 다른 프로세스가 이 포트를 사용 중이면 시 작 시 해제됩니다.
실제 SDK 포트 맵을 찾아보세요.
SDK에서 기본 호스트 포트가 사용 가능하다고 가정하지 마십시오. 다음 명령을 실행하십시오.
neat --json
출력 결과에는 insight.webUiUrl과 exposedPorts 배열이 포함됩니다.
{
"exposedPorts": [
{"hostPortEnd": null, "hostPortStart": 9900, "name": "mainUI", "protocol": "tcp"},
{"hostPortEnd": 9179, "hostPortStart": 9100, "name": "metadataUDP", "protocol": "udp"},
{"hostPortEnd": null, "hostPortStart": 8554, "name": "rtsp.tcp", "protocol": "tcp"},
{"hostPortEnd": 9079, "hostPortStart": 9000, "name": "videoUDP", "protocol": "udp"},
{"hostPortEnd": null, "hostPortStart": 8081, "name": "videoUI", "protocol": "tcp"},
{"hostPortEnd": 40199, "hostPortStart": 40000, "name": "webRTC", "protocol": "udp"},
{"hostPortEnd": null, "hostPortStart": 8889, "name": "webrtcWhip", "protocol": "tcp"},
{"hostPortEnd": null, "hostPortStart": 8189, "name": "webrtcWhipIce", "protocol": "udp"},
{"hostPortEnd": null, "hostPortStart": 8022, "name": "webSSH", "protocol": "tcp"}
],
"insight": {
"serviceState": "Running",
"venv": "/opt/neat-insight/venv",
"webUiUrl": "https://10.0.0.210:9900"
}
}
호스트 포트가 재매핑된 경우, hostPortStart 값은 외부 클라이언트가 사용해야 하는 포트입니다. hostPortEnd는 비디오, 메타데이터, WebRTC와 같은 포트 범위에 사용됩니다.
채널 매핑
비디오 뷰어는 쌍으로 연결된 비디오 및 메타데이터 포트를 사용합니다. 채널 N의 경우:
video: UDP 9000 + N
metadata: UDP 9100 + N
예를 들어:
| 시청 채널 | 비디오 포트 | 메타데이터 포트 |
|---|---|---|
0 | 9000 | 9100 |
1 | 9001 | 9101 |
2 | 9002 | 9102 |
비디오와 메타데이 터 간에 채널 번호를 일관되게 유지하십시오. 애플리케이션이 채널 3로 비디오를 전송하는 경우, 해당 메타데이터를 채널 3의 메타데이터 포트로 전송하십시오.
비디오 포트는 RTP H.264(페이로드 유형 96), H.265(98) 또는 JPEG(26, GStreamer rtpjpegpay가 전송하는 RFC 2435 형식)를 받습니다. 모든 RTP 패킷은 4096바이트 이하로 유지하십시오. JPEG의 경우 rtpjpegpay mtu=를 4096 이하로 설정하십시오. JPEG 프레임은 메타데이터와 같은 WebRTC 연결을 통해 브라우저에 전달되므로 추가 포트가 필요하지 않습니다.
SDK 포트 매핑
Neat 개발 환경에서 SDK 컨테이너가 포트를 재매핑할 수 있습니다. Insight는 사용 가능한 경우 SDK 포트 매핑 구성을 읽어 UI 링크가 브라우저에서 접근 가능한 호스트 포트를 가리키도록 합니다.
이는 특히 비디오 뷰어에 중요합니다. 내부 기본 뷰어 포트는 8081이지만, SDK가 videoUI를 다른 호스트 포트에 매핑하는 경우 브라우저에 표시되는 포트가 다를 수 있습니다.
Insight UI의 시스템 정보를 사용하여 URL이 잘못되었다고 가정하기 전에 실제 노출된 포트를 확인하십시오.
선택적 브라우저 연결 구성
호스팅 환경에서는 페어링된 DevKit이 사용하는 주소와 외부 브라우저에 알리는 주소를 분리할 수 있습니다. Insight는 시작 시에만 적용되는 다음 두 개의 선택적 파일을 읽습니다.
| 파일 | 용도 |
|---|---|
/home/docker/.insight-config/browser-ice-address | vf 뷰어와 MediaMTX WHIP 엔드포인트가 모두 알리는, 브라우저에서 접근 가능한 단일 IPv4 주소입니다. |
/home/docker/.insight-config/launch-url | 신뢰할 수 있는 하나의 절대 HTTP 또는 HTTPS 시작 URL입니다. Insight는 이 URL의 오리진을 사용하여 뷰어, WHIP 및 HTTP MJPEG URL을 생성합니다. |
browser-ice-address가 없으면 Insight는 기존 CONTAINER_HOST_IP 동작을 유지합니다. launch-url이 없으면 생성된 브라우저 URL은 계속 요청 호스트와 SDK 포트 맵을 사용합니다. 따라서 두 파일은 호스팅 환경 동작을 독립적으로 활성화하며 일반적인 로컬 또는 DevKit 설치에는 영향을 주지 않습니다.
browser-ice-address는 vf 또는 MediaMTX가 시작되기 전에 검증됩니다. 비어 있거나 잘못된 브라우저 주소가 있으면 접근할 수 없는 주소를 조용히 알리는 대신 Insight가 준비 상태가 되지 않습니다. launch-url은 권고 설정입니다. Insight는 경로, 쿼리 또는 프래그먼트가 포함된 ASCII 호스트 이름의 전체 URL을 허용하지만 HTTP(S) 오리진만 사용합니다. 잘못된 시작 URL은 경고를 기록하고 기존 요청 호스트/포트 맵 URL 생성을 유지합니다. 파일을 원자적으로 교체하고 insight-admin restart를 실행한 다음 /api/health를 확인하여 새 프로세스에 주소와 공개 오리진이 적용되었는지 확인하십시오.
브라우저 ICE 주소는 로컬 네트워크 인터페이스에 할당될 필요가 없습니다. 퍼블릭 클라우드 IPv4 주소는 일반적으로 1:1 NAT를 통해 호스트에 도달합니다. 그래도 WebRTC 및 webrtcWhipIce UDP 포트는 게시되어야 하며 주변 네트워크 정책에서 허용되어야 합니다.
포트 맵을 사용하여 애플리케이션을 구성합니다.
애플리케이션 위치를 기준으로 기본 컨테이너 포트 또는 SDK 호스트에서 노출된 포트를 사용할지 결정합니다.
| 애플리케이션 위치 | Insight에서 제공하는 RTSP 입력 | 비디오/메타데이터를 Insight로 출력합니다. |
|---|---|---|
| SDK 컨테이너 내부 | rtsp://127.0.0.1:8554/srcN | 127.0.0.1:9000 + channel 및 127.0.0.1:9100 + channel |
| DevKit 또는 다른 외부 장치에서 | rtsp://<sdk-host-ip>:<rtsp.tcp hostPortStart>/srcN | <sdk-host-ip>:<videoUDP hostPortStart + channel> 및 <sdk-host-ip>:<metadataUDP hostPortStart + channel> |
HTTP MJPEG 소스는 주 Insight UI/API 포트를 사용합니다. SDK에서 해당 URL에 대해 neat --json의 mainUI 호스트 포트를 사용하십시오.
예를 들어, neat --json에서 다음과 같이 보고하는 경우:
{"name": "rtsp.tcp", "hostPortStart": 18554, "protocol": "tcp"}
{"name": "videoUDP", "hostPortStart": 19000, "hostPortEnd": 19079, "protocol": "udp"}
{"name": "metadataUDP", "hostPortStart": 19100, "hostPortEnd": 19179, "protocol": "udp"}
그러면 DevKit에서 실행되는 애플리케이션은 다음을 사용해야 합니다.
RTSP source src1: rtsp://<sdk-host-ip>:18554/src1
video channel 0: <sdk-host-ip>:19000
metadata channel 0: <sdk-host-ip>:19100
video channel 3: <sdk-host-ip>:19003
metadata channel 3: <sdk-host-ip>:19103
애플리케이션과 Insight가 동일한 SDK 컨테이너에서 실행되는 경우 기본 로컬 포트를 사용하세요.
SDK 직접 접속과 공유 프록시
/home/docker/.insight-config/url-routing에서 URL 라우팅을 명시적으로 선택합니다. 한 줄에 direct 또는 proxy를 쓰고 변경 후 Insight를 다시 시작하세요. 비어 있거나 잘못된 값이면 시작에 실패합니다. 파일이 없으면 기존 호스팅 환경을 유지하기 위해 proxy를 사용합니다.
proxy 모드에서는 포트 번호와 관계없이 launch-url이 뷰어, WHIP, HTTP MJPEG URL의 공유 오리진을 제공합니다. 프록시는 각 경로를 해당 서비스로 전달해야 합니다. direct 모드에서도 SDK 시작 기능은 launch-url을 사용할 수 있지만, Insight의 공개 오리진으로는 사용하지 않습니다. 생성된 URL은 요청 호스트 이름과 각 서비스에 설정된 포트를 사용합니다. 뷰어는 SDK 포트 맵의 videoUI 포트를 사용하고, 설정이 없으면 8081을 사용합니다. 브라우저 ICE 주소 설정은 이 설정과 독립적입니다.
https://127.0.0.1:9900/ 같은 시작 URL을 지정한 로컬 SDK에서는 url-routing을 direct로 설정하세요. 시작 URL 재정의가 필요 없다면 launch-url을 삭제해도 됩니다. insight-admin restart로 다시 시작하고 /api/health를 확인하세요. 직접 라우팅에서는 network.public_origin: null이 표시됩니다. 프록시 포트가 SDK의 mainUI 포트와 같아도 프록시 오리진은 변경되지 않습니다.
관련 도구
- Neat 개발 환경은 컨테이너화된 빌드 및 실행 환경을 제공하며, 여기에서 Insight가 함께 제공됩니다.
- Neat 라이브러리는 비전 워크로드를 구축하고 실행하는 데 사용되는 애플리케이션 API를 제공합니다.
- sima-cli는 Insight 패키지와 기타 Neat 아티팩트를 설치하고 업그레이드합니다.
- 모델 컴파일러 및 LLiMa는 모델 결과물을 생성하며, 사용자는 작업 공간을 통해 이러한 결과물을 검토하고, Insight와 함께 실행되는 애플리케이션을 통해 유효성을 확인할 수 있습니다.