中文

VoceSpace 灵活部署指南

本文档介绍如何在 Ubuntu 服务器上部署 vocespace-client 前端项目，配置 Nginx + HTTPS，安装依赖、使用 PM2 管理服务，并配置 TURN 服务用于 WebRTC。

项目获取与构建 (可选)

实际上您无需自己手动进行项目克隆，我们已经在自动化部署脚本中帮助您进行了处理。

1# 克隆项目
2git clone https://github.com/your-org/vocespace-client.git vocespace-client

安装并配置 Nginx

安装 Nginx 与 Certbot

确保系统更新，并安装所需软件包：

1apt update
2apt install nginx certbot python3-certbot-nginx -y

WARNING

如果你使用的是 CentOS 或其他非 Debian 系发行版，请更换为相应的包管理命令（如 yum 或 dnf）。
certbot 和 python3-certbot-nginx 是用于自动配置 HTTPS 的工具。

配置 `nginx.conf`（全局配置）

路径：/etc/nginx/nginx.conf

1user  nginx;
2worker_processes  auto;
3
4error_log  /var/log/nginx/error.log warn;
5pid        /var/run/nginx.pid;
6
7events {
8    worker_connections  1024;
9}
10
11http {
12    include       /etc/nginx/mime.types;
13    default_type  application/octet-stream;
14
15    log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
16                      '$status $body_bytes_sent "$http_referer" '
17                      '"$http_user_agent" "$http_x_forwarded_for"';
18
19    access_log  /var/log/nginx/access.log  main;
20
21    sendfile        on;
22    keepalive_timeout  65;
23
24    include /etc/nginx/conf.d/*.conf;
25}

NOTE

此为全局配置，通常不需频繁更改。
日志目录建议开启 logrotate，避免磁盘占满。

配置站点文件（虚拟主机配置）

路径建议：/etc/nginx/sites-enabled/livemeet.conf 或 /etc/nginx/conf.d/livemeet.conf

1# HTTP 重定向至 HTTPS
2server {
3    listen 80;
4    listen [::]:80;
5
6    server_name your.server.name;
7
8    location /.well-known/acme-challenge/ {
9        root /var/www/certbot;
10    }
11
12    location / {
13        return 301 https://$host$request_uri;
14    }
15}
16
17# HTTPS 反向代理配置
18server {
19    listen 443 ssl;
20    listen [::]:443 ssl;
21
22    server_name your.server.name;
23
24    ssl_certificate /etc/letsencrypt/live/your.server.name/fullchain.pem;
25    ssl_certificate_key /etc/letsencrypt/live/your.server.name/privkey.pem;
26    include /etc/letsencrypt/options-ssl-nginx.conf;
27    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
28
29    # 应用主服务（例如前端或后端 Web 接口）
30    location / {
31        proxy_pass http://127.0.0.1:3000;
32        proxy_http_version 1.1;
33        proxy_set_header Upgrade $http_upgrade;
34        proxy_set_header Connection "Upgrade";
35        proxy_set_header Host $host;
36        proxy_cache_bypass $http_upgrade;
37    }
38
39    # WebRTC 服务代理（端口和路径视项目而定）
40    location /rtc {
41        proxy_pass http://127.0.0.1:7880;
42        proxy_http_version 1.1;
43        proxy_set_header Upgrade $http_upgrade;
44        proxy_set_header Connection "Upgrade";
45        proxy_set_header Host $host;
46    }
47
48    # Socket.IO 实时通信代理
49    location /socket.io {
50        proxy_pass http://127.0.0.1:3001;  # 请根据实际端口修改
51        proxy_http_version 1.1;
52        proxy_set_header Upgrade $http_upgrade;
53        proxy_set_header Connection "Upgrade";
54        proxy_set_header Host $host;
55        proxy_set_header X-Real-IP $remote_addr;
56        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
57        proxy_set_header X-Forwarded-Proto $scheme;
58        proxy_cache_bypass $http_upgrade;
59    }
60}

WARNING

server_name 必须与你实际申请的证书域名一致。
请确保 /etc/letsencrypt/live/your.server.name/ 中的文件已生成（见下一节）。

启动并检测 Nginx 状态

1# 检测配置是否正确
2nginx -t
3
4# 重载配置（推荐）或重启服务
5systemctl reload nginx
6# 或
7systemctl restart nginx

使用 Certbot 申请 HTTPS 证书

在 DNS 服务商中确保域名已正确解析至服务器 IP。

签发证书命令

1certbot --nginx -d your.server.name --register-unsafely-without-email

NOTE

--nginx：Certbot 将自动修改你的 nginx 配置以启用 HTTPS。
--register-unsafely-without-email：不绑定邮箱。不推荐正式使用，建议加上 --email your@email.com。

验证 Nginx 状态并重启

1nginx -t
2systemctl reload nginx

HTTPS 与证书自动续期（Certbot）

1sudo apt update
2sudo apt install certbot python3-certbot-nginx -y
3
4# 获取并配置证书
5sudo certbot --nginx -d example.com
6
7# 测试自动续期
8sudo certbot renew --dry-run

前端依赖安装与 pm2 管理

我们可以通过使用pm2对VoceSpace项目进行管理

1# 安装 PM2
2pnpm add -g pm2
3
4# 开机自启动
5pm2 startup
6pm2 save

检测pm2状态

1pm2 status

Coturn TURN 服务器部署

用于 WebRTC 通信穿透。

安装 Coturn

1sudo apt install coturn -y

打开服务器时自动启动，您必须修改/etc/default/coturn文件。

1sudo vim /etc/default/coturn

找到以下行并取消注释以将 Coturn 作为自动系统服务守护程序运行。

1TURNSERVER_ENABLED=1

编辑配置文件

编辑 /etc/turnserver.conf：

1server-name=your.server.name
2listening-ip=0.0.0.0
3listening-port=3478
4fingerprint
5lt-cred-mech
6user=username:password
7realm=your.server.name
8external-ip=158.247.198.2
9min-port=49152
10max-port=65535

启动 Coturn

1sudo systemctl enable coturn
2sudo systemctl start coturn
3sudo systemctl restart coturn

测试 TURN 服务

可使用 WebRTC 测试页面如：

https://webrtc.github.io/samples/src/content/peerconnection/trickle-ice/

使用如下配置：

1{
2  "urls": "turn:example.com:3478",
3  "username": "user",
4  "credential": "password"
5}

自动化部署脚本

我们提供了一个完整的自动化部署脚本，当您在服务器上对以上Nginx, Certbot, pm2, Node(pnpm), Coturn(可选)完成安装与配置之后，您可以直接复制我们的自动化部署脚本进行一键部署！

1#!/bin/bash
2
3#=========================================================================#
4# shell script for deploy prod environment
5#=========================================================================#
6
7#=========================================================================#
8# Variables --------------------------------------------------------------#
9#=========================================================================#
10ROOT_PATH="/root/vocespace-client/"
11KIND="prod"
12PKG_NAME="vocespace_prod"
13REPO_URL="https://github.com/Privoce/vocespace-client.git"
14BRANCH="main"
15DEPLOY_NGINX_CONF="vocespace"
16NGINX_CONF="nginx.conf"
17NGINX_AVA_PATH="/etc/nginx/sites-available"
18NGINX_ENABLED_PATH="/etc/nginx/sites-enabled"
19LOG_FILE="deploy_prod.log"
20LOG_SRC="/root/deploy_log"
21LOG_PATH="$LOG_SRC/$LOG_FILE"
22ERROR_FMT="AUTO DEPLOY ERROR: See $LOG_PATH for more details"
23#=========================================================================#
24# clear or create log file -----------------------------------------------#
25#=========================================================================#
26# check or create log src
27if [ ! -d $LOG_SRC ]; then
28    mkdir -p $LOG_SRC
29fi
30# check or create log file
31if [ -f $LOG_PATH ]; then
32    rm $LOG_PATH
33fi
34touch $LOG_PATH
35#=========================================================================#
36# Clone or pull and then do pkg (prod)-------------------------------------#
37#=========================================================================#
38# check if the root path is exist
39if [ ! -d $ROOT_PATH ]; then
40    mkdir -p $ROOT_PATH
41fi
42
43cd $ROOT_PATH
44
45# do clone if vocespace_prod not exist or cd and do pull
46if [ ! -d $ROOT_PATH/$PKG_NAME ]; then
47    git clone --branch $BRANCH $REPO_URL $PKG_NAME
48    if [ $? -ne 0 ]; then
49        echo "clone vocespace_prod from github repo failed!" >> $LOG_PATH
50        echo $ERROR_FMT
51        exit 1
52    fi
53    echo "SYSTEM: clone vocespace_prod from github repo success" >> $LOG_PATH
54    # set remote url for future pull
55    cd $ROOT_PATH/$PKG_NAME
56    git remote set-url origin $REPO_URL
57else
58    cd $ROOT_PATH/$PKG_NAME
59    # set remote url
60    git remote set-url origin $REPO_URL
61    # do fetch and reset
62    git fetch --all
63    if [ $? -ne 0 ]; then
64        echo "fetch from github repo failed!" >> $LOG_PATH
65        echo $ERROR_FMT
66        exit 1
67    fi
68    git reset --hard origin/$BRANCH
69    if [ $? -ne 0 ]; then
70        echo "reset to origin/$BRANCH failed!" >> $LOG_PATH
71        echo $ERROR_FMT
72        exit 1
73    fi
74    echo "SYSTEM: pull vocespace_prod from github repo success" >> $LOG_PATH
75fi
76#=========================================================================#
77# Build environment ------------------------------------------------------#
78#=========================================================================#
79# make a .env file
80# the following is standard .env file content:
81# ```
82# LIVEKIT_API_KEY=devkey
83# LIVEKIT_API_SECRET=secret
84# LIVEKIT_URL=wss://space.voce.chat
85# NODE_ENV=production
86# ```
87# - remove the old .env file and replace with new one
88if [ -f .env ]; then
89    rm .env
90fi
91echo "LIVEKIT_API_KEY=devkey" >> .env
92echo "LIVEKIT_API_SECRET=secret" >> .env
93echo "LIVEKIT_URL=ws://localhost:7880" >> .env
94echo "WEBHOOK=false" >> .env
95#=========================================================================#
96# install dependencies and build -----------------------------------------#
97#=========================================================================#
98# do pnpm install and build
99pnpm install
100if [ $? -ne 0 ]; then
101    echo "pnpm install failed!" >> $LOG_PATH
102    echo $ERROR_FMT
103    exit 1
104fi
105# - set NODE_OPTIONS for build add heap size to 8192
106export NODE_OPTIONS="--max-old-space-size=8192"
107# - build the project
108pnpm build
109if [ $? -ne 0 ]; then
110    echo "pnpm build failed!" >> $LOG_PATH
111    echo $ERROR_FMT
112    exit 1
113fi
114echo "SYSTEM: pnpm install and build success" >> $LOG_PATH
115#=========================================================================#
116# pm2 stop and delete old version then pub--------------------------------#
117#=========================================================================#
118# stop $PKG_NAME
119pm2 stop $PKG_NAME
120# delete $PKG_NAME
121pm2 delete $PKG_NAME
122# start pm2 npm 
123PORT=3000 pm2 start npm --name $PKG_NAME -- start
124# save pm2
125pm2 save
126# sleep 2s for pm2 server to start
127sleep 2
128# netstat -tulnp | grep 3030 to check if the server is running, if have echo success
129if [ $(netstat -tulnp | grep 3000 | wc -l) -gt 0 ]; then
130    echo "pm2 server rebuild success!" >> $LOG_PATH
131else 
132    echo "pm2 server rebuild failed!" >> $LOG_PATH
133    echo $ERROR_FMT
134    exit 1
135fi
136# echo all done
137echo "Deploy Prod: All done! Please check $LOG_PATH for more details to make sure everything is fine."
138exit 0

VoceSpace 灵活部署指南#

项目获取与构建 (可选)#

安装并配置 Nginx#

安装 Nginx 与 Certbot#

配置 nginx.conf（全局配置）#

配置站点文件（虚拟主机配置）#

启动并检测 Nginx 状态#

使用 Certbot 申请 HTTPS 证书#

签发证书命令#

验证 Nginx 状态并重启#

HTTPS 与证书自动续期（Certbot）#

前端依赖安装与 pm2 管理#

检测pm2状态#

Coturn TURN 服务器部署#

安装 Coturn#

编辑配置文件#

启动 Coturn#

测试 TURN 服务#

自动化部署脚本#