# ColdBreeze Chat 部署文档

ColdBreeze Chat 是一个完全私有化的聊天系统，支持文字聊天、语音/视频通话和屏幕共享。

## 部署架构

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

## 组件说明

| 组件 | 部署位置 | 作用 |
|------|----------|------|
| VoceChat | NAS (192.168.1.122:3009) | 聊天服务器、Web 管理面板 |
| LiveKit | VPS (xxxxx) | 语音/视频通话 SFU 服务器 |
| Caddy | VPS | TLS 终止、反向代理（可选） |

## 快速开始

### 1. 部署 LiveKit

参考 [LiveKit 部署指南](livekit-deploy.md)

### 2. 部署 VoceChat

参考 [VoceChat 部署指南](vocechat-deploy.md)

### 3. 配置 VoceChat 连接 LiveKit

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

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

## 端口汇总

| 端口 | 协议 | 服务 | 用途 |
|------|------|------|------|
| 3009 | TCP | VoceChat | Web 客户端 + API（内网） |
| 4443 | TCP | Caddy | HTTPS 访问（可选） |
| 80 | TCP | Caddy/LiveKit | HTTP |
| 443 | TCP/UDP | Caddy/LiveKit | HTTPS + HTTP/3 |
| 7880 | TCP | LiveKit | 信令 |
| 7881 | TCP | LiveKit | WebRTC over TCP |
| 50000-50100 | UDP | LiveKit | WebRTC 媒体流 |

## 防火墙规则

### NAS（VoceChat）

```bash
# 如果需要公网访问 VoceChat
ufw allow 3009/tcp
```

### VPS（LiveKit）

```bash
ufw allow 80,443/tcp
ufw allow 50000:50100/udp
```

## 常见问题

### 视频通话无法连接

1. 检查 LiveKit URL 是否正确（`wss://` 前缀）
2. 检查 API Key/Secret 是否一致
3. 检查 VPS 防火墙是否开放 UDP 50000-50100
4. 浏览器控制台查看错误信息

### 语音/视频按钮灰色不可用

1. 检查 LiveKit 是否在管理后台启用
2. 检查 LiveKit URL 是否可访问
3. 浏览器需要 HTTPS 或 localhost 才能调用 `navigator.mediaDevices`

### NAS 面板无法访问

检查 `trim_nginx` 服务是否正常运行：

```bash
systemctl status trim_nginx.service
```

## 文件结构

```
deploy-docs/
├── README.md              # 本文档
├── livekit-deploy.md      # LiveKit 部署指南
└── vocechat-deploy.md     # VoceChat 部署指南
```