> 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/roboflow-cloud/cloud-streaming/install-a-connector.md).

# Connector 설치

macOS, Linux, Windows 또는 Docker에서 Roboflow Video Connector를 설치하고 실행하세요.

Roboflow Video Connector는 컴퓨터 또는 로컬 네트워크에 연결된 카메라를 Cloud Streaming에 연결합니다. 카메라에 연결할 수 있고 카메라를 사용하는 동안 계속 온라인 상태를 유지할 수 있는 컴퓨터에서 실행하세요. 모델 추론은 커넥터가 아니라 Roboflow 클라우드에서 실행됩니다.

설치한 후 [소스 연결](https://docs.roboflow.com/deployment/ko/roboflow-cloud/cloud-streaming/connect-a-source.md).

## 시작하기 전에

"Deployments", "Cloud Streaming", "Add Video Source", "Connect a Camera" 순서로 엽니다. 작업 공간에 커넥터가 이미 있으면 "Add a new connector"를 클릭합니다. 운영체제 탭을 선택하고 "Copy Command"를 클릭한 다음 명령을 실행합니다. 명령에 작업 공간 API 키가 포함되어 있습니다. 키를 채팅, 소스 제어 또는 스크린샷에 붙여넣지 마세요.

네이티브 아카이브는 x86-64 및 ARM64 아키텍처의 macOS와 Linux, x86-64 아키텍처의 Windows를 지원합니다. Linux에는 glibc 2.28 이상과 GnuTLS가 필요합니다(`libgnutls30` 또는 `gnutls`).

). 세 운영체제 모두에서 커넥터가 USB 카메라를 찾습니다. Linux에서는 V4L2 장치만 찾습니다.

## CLI

### macOS 또는 Linux에 설치

공개 설치 프로그램을 실행합니다.

```sh
curl --proto =https --proto-redir =https -fsSL https://repo.roboflow.com/rfv-connector/latest/install.sh | sh
~/.rfv-connector/rfv-connector --version
```

설치 프로그램은 운영체제와 아키텍처를 감지한 다음 설치 전에 선택한 릴리스의 체크섬을 확인합니다. 실행 파일은 `~/.rfv-connector/rfv-connector`; `~/.rfv-connector` 만으로는 디렉터리입니다.

설치 프로그램은 실행 파일을 PATH에 추가하지 않습니다. 현재 터미널에서 짧은 명령을 사용하려면 다음을 실행하세요.

```sh
export PATH="$HOME/.rfv-connector:$PATH"
rfv-connector --version
```

이 export 명령을 셸의 시작 파일(예: `~/.zshrc`)에 추가하면 이후 터미널에서도 사용할 수 있습니다.

EU 다운로드 미러도 사용할 수 있습니다.

```sh
curl --proto =https --proto-redir =https -fsSL https://repo.roboflow.eu/rfv-connector/latest/install.sh | RFV_DOWNLOAD_BASE=https://repo.roboflow.eu/rfv-connector sh
```

이 설정은 설치 파일을 다운로드하는 위치만 변경합니다. 처리 리전을 선택하거나 API 엔드포인트를 변경하지는 않습니다.

### Windows에 설치

PowerShell에서 설치 프로그램을 실행한 다음 버전을 확인합니다.

```powershell
irm https://repo.roboflow.com/rfv-connector/latest/install.ps1 | iex
& "$env:USERPROFILE\.rfv-connector\current\rfv-connector.exe" --version
```

설정 대화상자의 "Windows" 탭에서 "Download Installer"를 클릭해 `roboflow-connector.bat`을 다운로드할 수도 있습니다. 파일을 두 번 클릭하면 커넥터가 설치되고 시작됩니다.

ZIP 아카이브에서 설치하려면 다음 단계를 따르세요.

1. 공개 [릴리스 버전 포인터](https://repo.roboflow.com/rfv-connector/latest/LATEST_VERSION.txt).
2. 에서 버전을 선택합니다. `rfv-connector_windows_amd64.zip` 과 `checksums.txt` 를 동일한 버전 디렉터리에서 다운로드합니다. `https://repo.roboflow.com/rfv-connector/<VERSION>/`. 포인터에 지정된 버전을 사용하되 `v` 접두사를 포함해야 합니다(예: `v0.11.0`).
3. ). PowerShell에서 아카이브의 체크섬을 계산합니다.

```powershell
Get-FileHash .\rfv-connector_windows_amd64.zip -Algorithm SHA256
```

4. 정확한 ZIP 파일 이름의 SHA256을 다음에서 확인하세요. `checksums.txt`에 기록된 값과 비교하세요. 체크섬이 없거나 일치하지 않으면 아카이브를 실행하지 마세요.
5. 아카이브 전체를 영구 폴더에 압축 해제하세요. 다음 항목을 실행 파일과 함께 보관하세요. `ffmpeg.exe`, 소스 파일 및 고지 사항

릴리스에는 코드 서명이 되어 있지 않으므로 macOS 또는 Windows에서 경고가 표시될 수 있습니다. 조직에서 허용하는 경우 macOS에서는 "개인정보 보호 및 보안"에서 "그래도 열기"를 클릭하고, Windows에서는 "자세한 정보"를 클릭한 다음 "그래도 실행"을 선택하세요.

### 커넥터 시작 및 구성

설정 대화상자에서 명령을 실행하거나, 작업 공간 키를 다음 환경 변수에 설정한 뒤 `ROBOFLOW_API_KEY` 커넥터를 시작하세요.

```sh
~/.rfv-connector/rfv-connector --api-key "$ROBOFLOW_API_KEY"
```

Windows에서는 PowerShell에서 실행하세요.

```powershell
& "$env:USERPROFILE\.rfv-connector\current\rfv-connector.exe" --api-key "$env:ROBOFLOW_API_KEY"
```

ZIP 아카이브에서 설치한 경우, 대신 압축을 푼 폴더에서 `.\rfv-connector.exe` 를 실행하세요.

시작할 때 RTSP 카메라를 추가하려면 카메라별로 `--rtsp "name=rtsp://..."` 를 추가하세요. 앱에서 나중에 카메라를 추가할 수도 있습니다.

커넥터는 다음 주소에서 로컬 페이지도 실행합니다. `http://127.0.0.1:8070` 이 페이지에서 키를 설정하고, 소스를 켜거나 끄고, RTSP 카메라를 추가할 수 있습니다. 이 기능을 끄려면 `--no-ui` 를 추가하세요.

운영체제에서 요청하면 커넥터를 실행하는 애플리케이션 또는 터미널에 카메라 접근 권한을 허용하세요. Linux에서는 커넥터를 실행하는 사용자가 카메라 캡처 장치를 읽을 수 있어야 합니다. 모든 장치를 쓰기 가능하게 설정하지 말고 시스템의 장치 접근 정책을 사용하세요.

설정 대화상자로 돌아가 커넥터가 연결되었는지 확인하세요. 이미 온라인 상태인 커넥터가 있다면, 해당 커넥터에서 새 카메라가 나타날 때 대화상자에 확인 메시지가 표시됩니다. 그러면 해당 카메라가 소스 목록에 나타납니다. 다음으로 [소스 설정](https://docs.roboflow.com/deployment/ko/roboflow-cloud/cloud-streaming/connect-a-source.md).

<figure><img src="https://1826078061-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-891a6980b60e4b2db8de7e19117ee9619ea1f59a%2Fcloud-streaming-shot02-connector-connected.png?alt=media" alt="Connector setup dialog with its API key redacted and a successful connection."><figcaption><p>으로 진행하세요.</p></figcaption></figure>

### 커넥터를 실행하고 연결 확인 메시지가 나타날 때까지 기다리세요.

계속 실행 상태로 유지

## 터미널을 닫거나 컴퓨터가 절전 모드로 전환되면 커넥터가 중지됩니다. 시스템 서비스 또는 Docker로 실행하고, 한 번에 하나의 복사본만 실행하세요.

Docker

```sh
릴리스 태그를 고정하세요. 다음 예시에서는 이름이 지정된 볼륨에 커넥터의 식별 정보를 보관합니다.
  docker run -d --name rfv-connector \
  --restart unless-stopped \
  -v rfv-connector-state:/state \
  repo.roboflow.com/rfv-connector:0.11.0 \
```

\--api-key "$ROBOFLOW\_API\_KEY" `설정` 명령을 실행하기 전에 ROBOFLOW\_API\_KEY를 설정하세요. "배포"로 돌아간 다음 "클라우드 스트리밍"을 선택해 커넥터가 연결되었는지 확인하고 [카메라를 추가하세요.](https://docs.roboflow.com/deployment/ko/roboflow-cloud/cloud-streaming/connect-a-source.md#rtsp-and-onvif-cameras).

Docker의 브리지 네트워크에서는 ONVIF 검색으로 LAN을 찾을 수 없습니다. RTSP URL로 카메라를 추가하거나, Linux에서 `--network host` 를 사용하고 `--ui-addr=127.0.0.1:8070`.

을 지정하세요. `Linux USB 카메라의 경우 장치를 전달하세요(예:`--device /dev/video0

). macOS용 Docker에서는 호스트 웹캠을 사용할 수 없습니다. 계속 실행 상태로 유지하세요. `/state` 영구 스토리지에 저장하세요. 디렉터리만 마운트하고 `connector.json`만 마운트하지 마세요. 동시에 실행되는 설치본에 동일한 상태 볼륨을 할당하지 마세요.

## 업데이트할 때 상태 유지

설치 디렉터리에는 바이너리가 들어 있습니다. 데이터 디렉터리에는 구성과 ID가 별도로 저장됩니다.

<table data-search="false"><thead><tr><th>설치 환경</th><th>기본 데이터 디렉터리</th></tr></thead><tbody><tr><td>macOS</td><td>~/Library/Application Support/rf-video-connector</td></tr><tr><td>Linux</td><td>$XDG_STATE_HOME/rf-video-connector 또는 ~/.local/state/rf-video-connector</td></tr><tr><td>Windows</td><td>%LOCALAPPDATA%/rf-video-connector</td></tr><tr><td>터미널을 닫거나 컴퓨터가 절전 모드로 전환되면 커넥터가 중지됩니다. 시스템 서비스 또는 Docker로 실행하고, 한 번에 하나의 복사본만 실행하세요.</td><td>/state</td></tr></tbody></table>

`--data-dir` 는 `RFV_DATA_DIR` 와 기본값을 재정의합니다. `--config` 를 사용하면 별도의 구성 파일을 지정할 수 있습니다. 데이터 디렉터리 전체와 별도 구성 파일을 모두 백업하고, 키와 카메라 비밀번호가 포함될 수 있으므로 백업을 비공개로 보관하세요.

1. 업그레이드하기 전에 클라우드 작업과 기존 커넥터를 중지하세요.
2. 데이터 디렉터리(또는 Docker `/state` 볼륨)를 유지하세요. 이전 컨테이너는 구성 파일 외부에 ID를 저장할 수도 있으므로 컨테이너를 교체하기 전에 확인하세요.
3. 네이티브 설치 프로그램을 다시 실행하거나, 검증된 Windows 릴리스를 압축 해제하거나, 변경할 수 없는 새 Docker 버전을 선택하세요. 영구 상태를 덮어쓰거나 삭제하지 마세요.
4. 커넥터 하나를 시작하고 카메라가 동일한 커넥터 아래에 계속 표시되는지 확인하세요.

이전 Linux 설치에서는 USB 소스 이름이 `usb:videoN`입니다. 업그레이드하기 전에 `rfv-connector --list-usb` 를 실행하고 구성의 `usbSourceAliases` 를 사용해 이전 이름을 새 ID에 매핑하세요.

커넥터를 제거하려면 먼저 중지한 다음 "Cloud Streaming"의 해당 커넥터 페이지에서 "커넥터 제거"를 클릭하세요. 새 커넥터로 시작하려는 경우에만 데이터 디렉터리를 삭제하세요.

## 네트워크 요구 사항

커넥터는 Roboflow API와 지정된 미디어 대상에 아웃바운드 연결을 엽니다. 카메라에 연결하기 위해 인터넷에서 접근 가능한 인바운드 포트를 포워딩할 필요는 없습니다. 다만 커넥터를 실행하는 컴퓨터는 카메라의 RTSP 또는 ONVIF 서비스에 로컬로 접근할 수 있어야 하며, HTTPS API 연결 외에도 미디어에 아웃바운드로 접근할 수 있어야 합니다.

네트워크 카메라는 TCP 포트 8554의 RTSP를 통해 전달됩니다. USB 카메라와 파일은 UDP 또는 TCP를 사용하는 WebRTC(WHIP)를 통해 전송됩니다. ONVIF 검색은 로컬 멀티캐스트를 사용하므로 VLAN 간에 전달되지 않을 수 있습니다.

커넥터는 온라인 상태인데 카메라나 동영상이 보이지 않는다면 [문제 해결](https://docs.roboflow.com/deployment/ko/roboflow-cloud/cloud-streaming/troubleshooting.md).
