ColdBreeze-chat-server-rust/DEPLOY_LIVEKIT.md

ColdBreeze Chat + LiveKit 部署指南

架构

浏览器 ──HTTPS──> VoceChat (3000) ──> 聊天/管理
     └──WS/HTTP──> LiveKit  (7880) ──> 音视频信令
     └──UDP──────> LiveKit  (50000-50100) ──> WebRTC 媒体流

VoceChat 负责聊天和管理，LiveKit 负责音视频通话和屏幕共享。两者通过 Docker Compose 一键部署。

前置条件

• Rust 工具链（用于编译服务端）
• Docker + Docker Compose
• 端口开放：3000、7880、7881、50000-50100/udp

快速启动

0. 编译服务端二进制（或使用 Docker 多阶段构建）

NAS 上无需安装 Rust。docker compose build 会在 Docker 内自动编译。

如需本地编译：

cd ColdBreeze-chat-server-rust
cargo build --release
cp target/release/vocechat-server .

0.5 构建 Web 客户端

cd ColdBreeze-chat-web
pnpm install
REACT_APP_BUILD_TIME=$(date +%s) GENERATE_SOURCEMAP=false node scripts/build.js

将 build/ 目录内容上传到 NAS 的 /vol1/docker/coldbreeze/web-client/。

1. 生成 API Key / Secret

cd deploy
bash generate-keys.sh

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

keys:
  <你的API_KEY>: <你的API_SECRET>

2. 启动服务

cd deploy
docker compose build
docker compose up -d

3. 初始化 VoceChat

浏览器访问 http://你的NAS_IP:3009，完成管理员注册。

4. 配置 LiveKit

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

字段	值
Enable	✅
LiveKit URL	ws://你的NAS_IP:7880
API Key	同 livekit.yaml 中的 key
API Secret	同 livekit.yaml 中的 secret

点击保存。

5. 测试

进入任意频道，点击语音/视频按钮，确认能正常加入 LiveKit 房间。

端口说明

端口	协议	用途
3009	TCP	VoceChat Web 客户端 + API
7880	TCP	LiveKit 信令（WebSocket）
7881	TCP	WebRTC over TCP fallback
50000-50100	UDP	WebRTC 媒体流（音视频数据）

IPv6 / 动态公网

如果需要公网访问：

1. 确保路由器开启了 IPv6，并给 NAS 分配了公网 IPv6 地址
2. DNS AAAA 记录指向 NAS 的公网 IPv6
3. 防火墙放行上述端口
4. VoceChat 管理后台 → 设置 → 域名，填入你的域名
5. LiveKit URL 改为 ws://你的域名:7880

如果 LiveKit 需要从公网可达，确保 UDP 50000-50100 端口未被运营商封锁。

常用命令

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

# 重启
docker compose restart

# 停止
docker compose down

# 重新生成 key 后更新配置
# 1. 修改 livekit.yaml 中的 keys
# 2. 重启 LiveKit
docker compose restart livekit-server
# 3. 在 VoceChat 管理后台更新对应的 key/secret

LiveKit 配置参考

livekit.yaml 完整配置项：

port: 7880              # 信令端口

rtc:
  port_range_start: 50000   # UDP 媒体端口范围
  port_range_end: 50100
  tcp_port: 7881            # TCP fallback
  use_external_ip: false    # 内网部署保持 false

keys:
  your_api_key: your_api_secret

logging:
  level: info    # debug / info / warn / error

room:
  auto_create: true     # 自动创建房间
  empty_timeout: 300    # 空房间 5 分钟后关闭
  max_participants: 0   # 不限制

注意事项

• LiveKit 走内网 HTTP，不加密。如果浏览器通过 HTTPS 访问 VoceChat，可能需要在浏览器设置中允许混合内容（或使用内网 HTTP 直接访问）。
• UDP 端口 50000-50100 是 WebRTC 媒体流必需的，如果音视频不通，优先检查防火墙和路由器是否放行了这些端口。
• NAS 重启后 Docker 会自动拉起服务（restart: unless-stopped）。