# LiveKit 部署指南

## 概述

LiveKit 是开源的 WebRTC SFU 服务器，为 ColdBreeze Chat 提供语音、视频通话和屏幕共享功能。

本文档将 LiveKit 部署在独立的 VPS 上，VoceChat 部署在 NAS 上，通过公网 WSS 连接。

## 架构

```
浏览器 ←→ VoceChat (NAS:3009)    -- 生成 LiveKit JWT token
浏览器 ←→ LiveKit (VPS:443)      -- WebSocket 信令 (WSS)
浏览器 ←→ LiveKit (VPS UDP)       -- WebRTC 媒体流
```

## 前置条件

- VPS（Linux x86_64，建议 2C2G）
- Docker + Docker Compose
- 公网 IP（IPv4 或 IPv6）
- 域名（如 `livekit.binbim.top`）
- SSL 证书（Let's Encrypt 或自签）

## 快速部署

### 1. 准备目录

```bash
mkdir -p /root/livekit/certs
cd /root/livekit
```

### 2. 创建 `livekit.yaml`

```yaml
port: 7880

rtc:
  port_range_start: 50000
  port_range_end: 50100
  tcp_port: 7881
  use_external_ip: true    # VPS 部署必须设为 true

keys:
  <YOUR_API_KEY>: <YOUR_API_SECRET>

logging:
  level: info
  json: false

room:
  auto_create: true
  empty_timeout: 300
  max_participants: 0
```

### 3. 生成 API Key/Secret

```bash
docker run --rm livekit/livekit-server generate-keys
```

将输出的 key 和 secret 填入 `livekit.yaml` 的 `keys` 部分。

**重要**：VoceChat 管理后台配置的 key/secret 必须与此处完全一致。

### 4. 创建 `docker-compose.yaml`

```yaml
services:
  livekit-server:
    image: livekit/livekit-server:v1.13.3
    container_name: livekit-server
    restart: unless-stopped
    command:
      - --bind
      - 0.0.0.0
      - --config
      - /etc/livekit.yaml
    volumes:
      - ./livekit.yaml:/etc/livekit.yaml:ro
    ports:
      - "7880:7880"           # 信令 (HTTP/WS)
      - "7881:7881"           # WebRTC over TCP fallback
      - "50000-50100:50000-50100/udp"  # WebRTC 媒体流
    networks:
      - livekit-net

  caddy:
    image: caddy:2-alpine
    container_name: caddy-livekit
    restart: unless-stopped
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - ./certs:/certs:ro
      - caddy_data:/data
    ports:
      - "80:80"
      - "443:443"
    networks:
      - livekit-net
    depends_on:
      - livekit-server

networks:
  livekit-net:
    driver: bridge

volumes:
  caddy_data:
```

### 5. 创建 `Caddyfile`

```
{
    auto_https off
}

livekit.binbim.top {
    tls /certs/livekit.pem /certs/livekit.key

    handle {
        reverse_proxy livekit-server:7880
    }
}
```

### 6. 准备 SSL 证书

将证书放到 `certs/` 目录：

```bash
cp /path/to/livekit.pem certs/livekit.pem
cp /path/to/livekit.key certs/livekit.key
```

或使用 Let's Encrypt：

```bash
# 使用 Caddy 自动证书（去掉 auto_https off 即可）
```

### 7. 启动服务

```bash
docker compose up -d
```

### 8. 验证

```bash
# 检查 LiveKit 状态
curl -s http://localhost:7880/

# 检查 HTTPS
curl -sk https://livekit.binbim.top/
```

## VoceChat 配置

在 VoceChat 管理后台 → 设置 → video（LiveKit）：

| 字段 | 值 |
|------|-----|
| Enable | ✅ |
| LiveKit URL | `wss://livekit.binbim.top` |
| API Key | 同 livekit.yaml 中的 key |
| API Secret | 同 livekit.yaml 中的 secret |

## 端口说明

| 端口 | 协议 | 用途 |
|------|------|------|
| 80 | TCP | HTTP（Caddy 自动重定向到 HTTPS） |
| 443 | TCP/UDP | HTTPS + HTTP/3 |
| 7880 | TCP | LiveKit 信令（被 Caddy 反代） |
| 7881 | TCP | WebRTC over TCP fallback |
| 50000-50100 | UDP | WebRTC 媒体流 |

## 防火墙

确保以下端口开放：

```bash
# TCP
ufw allow 80,443,7881/tcp

# UDP（WebRTC 媒体流，必须开放）
ufw allow 50000:50100/udp
```

## 常用命令

```bash
# 查看日志
docker compose logs -f livekit-server

# 重启
docker compose restart livekit-server

# 更新配置后重启
docker compose down && docker compose up -d
```

## 注意事项

- `use_external_ip: true` 在 VPS 部署中必须设为 true
- UDP 端口 50000-50100 是 WebRTC 媒体流必需的
- API Key/Secret 必须与 VoceChat 管理后台配置完全一致
- LiveKit 服务器和 VoceChat 服务器之间不需要直接通信，浏览器通过 token 连接