From 99bde59a91028e886f6f08101b57f0c69ffe3447 Mon Sep 17 00:00:00 2001
From: Binbim_ProMax <binbim_promax@163.com>
Date: Sat, 4 Jul 2026 09:17:43 +0800
Subject: [PATCH] Add LiveKit and VoceChat deployment documentation

---
 README.md          | 100 ++++++++++++++++++++
 livekit-deploy.md  | 212 ++++++++++++++++++++++++++++++++++++++++++
 vocechat-deploy.md | 224 +++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 536 insertions(+)
 create mode 100644 README.md
 create mode 100644 livekit-deploy.md
 create mode 100644 vocechat-deploy.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..7d7f395
--- /dev/null
+++ b/README.md
@@ -0,0 +1,100 @@
+# 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 (112.124.10.40) | 语音/视频通话 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 部署指南
+```
diff --git a/livekit-deploy.md b/livekit-deploy.md
new file mode 100644
index 0000000..b4007d5
--- /dev/null
+++ b/livekit-deploy.md
@@ -0,0 +1,212 @@
+# 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 连接
diff --git a/vocechat-deploy.md b/vocechat-deploy.md
new file mode 100644
index 0000000..9112a5e
--- /dev/null
+++ b/vocechat-deploy.md
@@ -0,0 +1,224 @@
+# VoceChat 部署指南
+
+## 概述
+
+VoceChat 是轻量级的私有聊天服务器，支持文字聊天、语音/视频通话、文件传输等功能。
+
+本文档将 VoceChat 部署在 NAS 上，LiveKit 部署在 VPS 上，通过公网 WSS 连接。
+
+## 架构
+
+```
+浏览器 ←→ VoceChat (NAS:3009)    -- 聊天、管理、生成 LiveKit token
+浏览器 ←→ LiveKit (VPS)           -- 语音、视频、屏幕共享
+```
+
+## 前置条件
+
+- NAS 或 Linux 服务器
+- Docker + Docker Compose
+- Rust 工具链（编译服务端，可选）
+
+## 快速部署
+
+### 1. 准备目录
+
+```bash
+mkdir -p /vol1/docker/coldbreeze/server-rust/deploy
+cd /vol1/docker/coldbreeze/server-rust
+```
+
+### 2. 编译服务端（可选，如有预编译二进制可跳过）
+
+```bash
+# 需要安装 Rust
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+source ~/.cargo/env
+
+# 编译
+cargo build --release
+cp target/release/vocechat-server .
+```
+
+### 3. 创建 `deploy/docker-compose.yaml`
+
+```yaml
+services:
+  vocechat-server:
+    build:
+      context: ..
+      dockerfile: deploy/Dockerfile
+    container_name: coldbreeze-server
+    restart: unless-stopped
+    volumes:
+      - vocechat_data:/home/vocechat-server/data
+      - /vol1/docker/coldbreeze/web-client:/home/vocechat-server/data/wwwroot:ro
+    ports:
+      - "3009:3000"           # Web 客户端 + API
+
+volumes:
+  vocechat_data:
+```
+
+### 4. 创建 `deploy/Dockerfile`
+
+```dockerfile
+# Stage 1: Build
+FROM rust:1.82-bookworm AS builder
+WORKDIR /src
+COPY Cargo.toml Cargo.lock ./
+COPY src ./src
+COPY crates ./crates
+COPY migrations ./migrations
+COPY cert ./cert
+RUN cargo build --release && strip target/release/vocechat-server
+
+# Stage 2: Runtime
+FROM debian:bookworm-slim
+RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates && rm -rf /var/lib/apt/lists/*
+COPY --from=builder /src/target/release/vocechat-server /home/vocechat-server/vocechat-server
+COPY config /home/vocechat-server/config
+EXPOSE 3000
+WORKDIR /home/vocechat-server
+CMD ["./vocechat-server"]
+```
+
+### 5. 准备 Web 客户端
+
+```bash
+# 从本地构建目录上传
+scp -r build/ user@nas:/vol1/docker/coldbreeze/web-client/
+```
+
+### 6. 启动服务
+
+```bash
+cd deploy
+docker compose up -d
+```
+
+### 7. 初始化
+
+浏览器访问 `http://<NAS_IP>:3009`，完成管理员注册。
+
+## LiveKit 配置
+
+在 VoceChat 管理后台 → 设置 → video（LiveKit）：
+
+| 字段 | 值 |
+|------|-----|
+| Enable | ✅ |
+| LiveKit URL | `wss://livekit.binbim.top` |
+| API Key | 与 VPS LiveKit 一致 |
+| API Secret | 与 VPS LiveKit 一致 |
+
+## HTTPS 访问
+
+如果需要通过 HTTPS 访问（如从公网），可以使用 Caddy 做反向代理：
+
+### 1. 更新 `deploy/docker-compose.yaml`
+
+```yaml
+services:
+  vocechat-server:
+    build:
+      context: ..
+      dockerfile: deploy/Dockerfile
+    container_name: coldbreeze-server
+    restart: unless-stopped
+    volumes:
+      - vocechat_data:/home/vocechat-server/data
+      - /vol1/docker/coldbreeze/web-client:/home/vocechat-server/data/wwwroot:ro
+    expose:
+      - "3000"
+
+  caddy:
+    image: caddy:2-alpine
+    container_name: coldbreeze-caddy
+    restart: unless-stopped
+    volumes:
+      - ./Caddyfile:/etc/caddy/Caddyfile:ro
+      - /vol1/docker/coldbreeze/certs:/certs:ro
+      - caddy_data:/data
+    ports:
+      - "4443:4443"
+    depends_on:
+      - vocechat-server
+
+volumes:
+  vocechat_data:
+  caddy_data:
+```
+
+### 2. 创建 `deploy/Caddyfile`
+
+```
+{
+    auto_https off
+}
+
+:4443 {
+    tls /certs/vocechat/cert.pem /certs/vocechat/key.pem
+    reverse_proxy vocechat-server:3000
+}
+```
+
+### 3. 启动
+
+```bash
+docker compose up -d
+```
+
+## 端口说明
+
+| 端口 | 协议 | 用途 |
+|------|------|------|
+| 3009 | TCP | HTTP 访问（内网） |
+| 4443 | TCP/UDP | HTTPS 访问（公网） |
+
+## LiveKit API Key/Secret
+
+VoceChat 和 LiveKit 使用相同的 API Key/Secret 进行 JWT 签名验证。
+
+在 VoceChat 管理后台配置的值必须与 VPS 上 `livekit.yaml` 中的 `keys` 完全一致。
+
+生成方法：
+
+```bash
+docker run --rm livekit/livekit-server generate-keys
+```
+
+## 数据持久化
+
+VoceChat 数据存储在 Docker volume `vocechat_data` 中，包含：
+
+- SQLite 数据库
+- 用户头像
+- 上传的文件
+- 消息数据库
+
+备份方法：
+
+```bash
+docker run --rm -v deploy_vocechat_data:/data -v /backup:/backup alpine tar czf /backup/vocechat-backup.tar.gz -C /data .
+```
+
+## 常用命令
+
+```bash
+# 查看日志
+docker compose logs -f vocechat-server
+
+# 重启
+docker compose restart vocechat-server
+
+# 更新 Web 客户端后重启
+docker compose restart vocechat-server
+```
+
+## 注意事项
+
+- Web 客户端需要单独构建（pnpm 构建）
+- 建议在本机临时目录构建 Web 客户端，避免网络盘问题
+- 构建时需要设置 `REACT_APP_RELEASE=true` 以启用 HTTPS 兼容模式
+- LiveKit API Key/Secret 必须与 VPS LiveKit 一致