# LiveKit 외부 IP 접속 가이드

> 작성일: 2026-07-19 · 한글 복구: 2026-09-07
> 서버 버전: 1.13.4. 아래 IP 및 상태는 기존 점검 기록이며 현재 접속 상태를 의미하지 않습니다.

## 1. 요약

| 질문 | 답변 |
|------|------|
| 외부에서 IP로 접속할 수 있나요? | 서버 바인딩, node-ip, 방화벽 및 포트 설정이 맞으면 가능합니다. |
| WebSocket 연결만 성공하면 통화도 되나요? | 미디어 연결은 별도입니다. node-ip가 127.0.0.1이면 외부 미디어 연결이 실패합니다. |
| 기록된 외부 URL | `ws://125.131.238.28:7880` |
| 로컬 URL | `ws://127.0.0.1:7880` 또는 `ws://localhost:7880` |
| 도메인 WSS | `wss://meet.dev.tictechtoeai.com:7443` (Caddy 필요) |

## 2. 머신 네트워크 점검 기록

| 항목 | 값 | 비고 |
|------|-----|------|
| 공인 IPv4 | `125.131.238.28` | 당시 인터페이스에서도 같은 IPv4 확인 |
| LiveKit HTTP/WS | TCP 7880 | `--bind 0.0.0.0`으로 모든 인터페이스에서 수신 |
| LiveKit RTC TCP | TCP 7881 | TCP 미디어 연결 |
| ICE UDP 범위 | UDP 50000-60000 | 기존 기본 설정 기준 |
| Windows 방화벽 | LiveKit 관련 인바운드 허용 규칙 존재 | livekit-server, LiveKit_UDP_50000 등 |
| Caddy | 80/443/7443 | 도메인 HTTPS/WSS에는 실행 필요 |

공인 IP는 회선에 따라 바뀔 수 있습니다. 실제 실행 전에 확인합니다.

```powershell
Invoke-RestMethod -Uri 'https://api.ipify.org' -TimeoutSec 5
Get-NetIPAddress -AddressFamily IPv4 | Where-Object { $_.IPAddress -notlike '127.*' }
```

## 3. node-ip가 중요한 이유

LiveKit은 클라이언트에 미디어 연결에 사용할 주소를 알려 줍니다.

| 기동 옵션 | 결과 |
|-----------|------|
| `--node-ip 127.0.0.1` | 외부 클라이언트가 자기 자신의 루프백 주소로 미디어 연결을 시도하게 됨 |
| `--node-ip 125.131.238.28` | 해당 공인 IP를 미디어 연결 주소로 알림 |
| 자동 감지 | 네트워크 환경에 따라 선택된 주소가 달라지므로 로그 확인 필요 |

시그널링(WebSocket)과 미디어(WebRTC)는 별도 연결입니다. 방 입장 UI가 보여도 미디어 주소가 잘못되면 영상과 음성이 나오지 않을 수 있습니다.

## 4. 외부 IP로 기동하는 방법

### 공인 IP 명시

아래 IP는 기존 기록의 예시입니다. 현재 공인 IP로 바꿔 실행합니다.

```powershell
cd C:\Developments\LivekitDev\livekit
.\bin\livekit-server.exe --config config.yaml --bind 0.0.0.0 --node-ip 125.131.238.28
```

### 로컬 전용

```powershell
.\bin\livekit-server.exe --config config.yaml --bind 0.0.0.0 --node-ip 127.0.0.1
```

이 옵션은 외부 미디어 접속용으로 사용하지 않습니다.

### 기동 확인

```powershell
Get-NetTCPConnection -State Listen -LocalPort 7880,7881
.\bin\livekit-server.exe --version
```

기존 외부 접속 설정의 로그 예시:

```text
nodeIP: "125.131.238.28"
bindAddresses: ["0.0.0.0"]
portHttp: 7880
version: "1.13.4"
```

### 개발용 config.yaml

```yaml
logging:
  level: info
keys:
  devkey: secret
```

기존 점검에서는 짧은 secret에 대한 경고가 기록되었습니다. 외부 운영 시에는 개발 키를 교체하고, 토큰은 서버에서 발급합니다.

## 5. 클라이언트 접속 값

| 필드 | 로컬 | 외부 IP 예시 |
|------|------|--------------|
| Server URL | `ws://127.0.0.1:7880` | `ws://125.131.238.28:7880` |
| Room | `my-room` | `my-room` |
| API Key / Secret | `devkey` / `secret` | 동일한 개발 설정 |

브라우저 외부 접속에는 HTTPS 페이지와 `wss://meet.dev.tictechtoeai.com:7443`을 사용합니다.

Avatar Bot이 서버와 같은 머신에서 실행된다면 로컬 주소를 사용할 수 있습니다. 의존성이 준비된 환경에서 실행합니다.

```powershell
$env:LIVEKIT_URL = "ws://127.0.0.1:7880"
$env:LIVEKIT_API_KEY = "devkey"
$env:LIVEKIT_API_SECRET = "secret"
$env:ROOM_NAME = "my-room"
cd C:\Developments\LivekitDev\avatar_bot
uv run python avatar_bot.py
```

외부 참가자도 봇과 같은 방 이름으로 접속합니다.

## 6. 열어야 하는 포트

| 포트 | 프로토콜 | 용도 |
|------|----------|------|
| 7880 | TCP | HTTP API 및 WebSocket 시그널링 |
| 7881 | TCP | RTC over TCP |
| 50000-60000 | UDP | ICE 및 미디어 |

Windows 방화벽 규칙이 없을 때 관리자 PowerShell에서 추가하는 예시입니다.

```powershell
New-NetFirewallRule -DisplayName "LiveKit-7880" -Direction Inbound -Protocol TCP -LocalPort 7880 -Action Allow
New-NetFirewallRule -DisplayName "LiveKit-7881" -Direction Inbound -Protocol TCP -LocalPort 7881 -Action Allow
New-NetFirewallRule -DisplayName "LiveKit-UDP-ICE" -Direction Inbound -Protocol UDP -LocalPort 50000-60000 -Action Allow
```

공유기나 클라우드 보안 그룹이 있다면 같은 포트의 전달 및 인바운드 허용도 확인합니다. 기존 점검에서는 공인 IP가 NIC에 직접 설정되어 있어 호스트 방화벽이 주요 확인 대상이었습니다.

## 7. 브라우저와 HTTPS 제약

| 환경 | 카메라와 마이크 |
|------|----------------|
| `http://localhost` | 로컬 개발 예외로 사용 가능 |
| 공인 IP의 일반 HTTP | 보안 컨텍스트가 아니므로 getUserMedia 사용 불가 |
| 신뢰할 수 있는 인증서의 HTTPS 도메인 | 권한 허용 후 사용 가능 |

외부 PC나 모바일 브라우저에서는 HTTPS 페이지와 WSS 연결을 함께 사용합니다. 네이티브 클라이언트의 일반 WS 연결 가능 여부와 브라우저의 카메라 권한은 별개입니다.

## 8. 시나리오별 확인

| 시나리오 | 조건 |
|----------|------|
| 같은 PC에서 localhost 연결 | 서버 실행 |
| 같은 PC에서 공인 IP 연결 | node-ip, 방화벽 및 네트워크의 루프백 경로 확인 |
| 외부 PC의 WS 시그널링 | 서버 실행 및 TCP 7880 접근 허용 |
| 외부의 실제 영상·음성 | 외부에서 도달 가능한 node-ip 및 미디어 포트 |
| 외부 브라우저 카메라 | HTTPS 페이지, 유효한 인증서, 사용자 권한 |
| 도메인 WSS 7443 | Caddy 실행 및 LiveKit 프록시 설정 |

## 9. 보안 주의

- 공인 IP의 7880 포트 개방은 LiveKit 서버를 인터넷에 노출합니다.
- `devkey` / `secret`은 개발 예시이며 외부 상시 서비스용으로 사용하지 않습니다.
- 운영 환경에서는 클라이언트에 secret을 넣지 않고 서버에서 토큰을 발급합니다.
- 테스트 종료 후 필요 없는 외부 접근 규칙을 정리합니다.

## 10. 체크리스트

- [ ] LiveKit 실행 및 `--bind 0.0.0.0` 확인
- [ ] node-ip가 실제 공인 IP 또는 외부에서 도달 가능한 주소인지 확인
- [ ] TCP 7880/7881 및 UDP 50000-60000 설정 확인
- [ ] 외부 장치에서 시그널링과 실제 미디어를 각각 테스트
- [ ] 브라우저는 Caddy를 통한 HTTPS/WSS 사용
- [ ] 외부 운영 전 개발 키 교체

## 11. 관련 경로

| 경로 | 설명 |
|------|------|
| `livekit/bin/livekit-server.exe` | 서버 실행 파일 |
| `livekit/config.yaml` | 서버 설정 |
| `livekit_video_call/` | Flutter 클라이언트 |
| `avatar_bot/` | 상주 아바타 봇 |
| `Caddyfile` | HTTPS 및 WSS 프록시 |
| `start_all.bat` | 기존 일괄 실행기. D 드라이브 경로 확인 필요 |

관련 문서: [시작 가이드](/guides/getting-started/), [HTTPS 오류 해결](/guides/meet-getusermedia-https/), [서버 업데이트](/updates/livekit-v1-13-4/).