VoceSpace QuickStart#

本文档说明如何使用提供的自动化脚本来部署 VoceSpace。

支持一键部署 VoceSpace + LiveKit Server + Redis。

文件说明#

• vocespace_deploy.sh - Linux/macOS 自动化部署脚本
• vocespace_deploy.bat - Windows 自动化部署脚本
• README.md - 本说明文档

功能特性#

• ✅ 自动检测系统架构和宿主机IP
• ✅ 支持自定义配置文件
• ✅ 一键安装和启动所有必要组件
• ✅ 智能处理已存在的服务
• ✅ 详细的状态检查和日志输出
• ✅ 支持强制重装和跳过组件

使用方法#

Linux/macOS#

1# 基本使用 - 使用默认配置
2./vocespace_deploy.sh
3
4# 使用自定义配置文件
5./vocespace_deploy.sh --config ./my-config.json
6
7# 指定宿主机IP
8./vocespace_deploy.sh --host-ip 192.168.1.100
9
10# 强制重新安装所有组件
11./vocespace_deploy.sh --force
12
13# 跳过某些组件的安装
14./vocespace_deploy.sh --skip-redis --skip-livekit
15
16# 组合使用
17./vocespace_deploy.sh --config ./config.json --host-ip 192.168.1.100 --force

Windows#

1REM 基本使用 - 使用默认配置
2vocespace_deploy.bat
3
4REM 使用自定义配置文件
5vocespace_deploy.bat --config ./my-config.json
6
7REM 指定宿主机IP
8vocespace_deploy.bat --host-ip 192.168.1.100
9
10REM 强制重新安装所有组件
11vocespace_deploy.bat --force
12
13REM 跳过某些组件的安装
14vocespace_deploy.bat --skip-redis --skip-livekit

命令行参数#

配置文件格式#

脚本支持 JSON 格式的配置文件，默认配置文件示例：

1{
2  "livekit": {
3    "key": "devkey",
4    "secret": "secret",
5    "url": "ws://YOUR_IP:7880"
6  },
7  "codec": "vp9",
8  "resolution": "1080p",
9  "maxBitrate": 3000000,
10  "maxFramerate": 30,
11  "priority": "medium",
12  "redis": {
13    "enabled": true,
14    "host": "YOUR_IP",
15    "port": 6379,
16    "password": "vocespace",
17    "db": 0
18  },
19  "server_url": "localhost"
20}

注意: 脚本会自动将配置文件中的 YOUR_IP 替换为实际的宿主机IP地址。

部署流程#

脚本会按以下顺序执行部署：

1. 环境检查

   • 检测操作系统和架构
   • 检查 Docker 安装和运行状态
   • 自动检测或验证宿主机IP

2. 配置处理

   • 验证配置文件存在性和格式
   • 自动创建默认配置（如未指定）
   • 更新配置中的IP地址

3. 组件安装

   • 安装 Redis (可跳过)
   • 安装 LiveKit Server (可跳过)

4. 镜像和服务

   • 拉取对应架构的 VoceSpace Docker 镜像
   • 启动 Redis 服务
   • 启动 LiveKit Server
   • 启动 VoceSpace 容器

5. 状态检查

   • 验证所有服务运行状态
   • 显示访问地址和管理命令

服务端口#

部署完成后，以下端口将被使用：

故障排除#

常见问题#

1. Docker 未启动

   ❌ Docker 未运行，请启动 Docker 服务
   • Linux: sudo systemctl start docker
   • macOS/Windows: 启动 Docker Desktop

2. 端口冲突

   Error response from daemon: port is already allocated
   • 检查端口占用: lsof -i :3000
   • 停止冲突服务或使用 --force 参数

3. 配置文件格式错误

   ❌ 配置文件JSON格式错误
   • 使用 JSON 验证工具检查格式
   • 确保没有多余的逗号或引号

4. IP地址检测失败

   ❌ 无法检测到宿主机IP
   • 手动指定IP: --host-ip YOUR_IP
   • 检查网络连接状态

日志查看#

• VoceSpace 容器日志: docker logs vocespace
• LiveKit Server 日志: tail -f livekit-server.log
• Redis 日志: tail -f redis.log

服务管理#

• 停止 VoceSpace: docker stop vocespace

• 停止 LiveKit: pkill -f livekit-server

• 停止 Redis: pkill -f redis-server

• 重启 VoceSpace: docker restart vocespace

• 查看容器状态: docker ps

系统要求#

最低要求#

• CPU: 2核心
• 内存: 4GB RAM
• 磁盘: 10GB 可用空间
• 网络: 稳定的互联网连接

支持的系统#

• Linux: Ubuntu 18.04+, CentOS 7+, Debian 10+
• macOS: 10.14+
• Windows: Windows 10/11 (需要 WSL2 或 Docker Desktop)