184 lines
5.1 KiB
Markdown
Executable File
184 lines
5.1 KiB
Markdown
Executable File
# Mixly 3.0 服务器部署手册 (Debian VPS)
|
||
|
||
本项目已实现单仓库镜像化部署，包含所有前端资源、板卡配置及 250+ 常用 Arduino 扩展库。
|
||
|
||
## 1. 前置依赖安装
|
||
|
||
在 Debian/Ubuntu 上执行：
|
||
|
||
```bash
|
||
# 更新系统
|
||
sudo apt update && sudo apt upgrade -y
|
||
|
||
# 安装 Git, Node.js (建议 18+), Python3
|
||
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
|
||
sudo apt install -y git nodejs python3 python3-pip python3-serial
|
||
|
||
# 串口访问权限设置 (非常重要：否则无法烧录/上传)
|
||
sudo usermod -a -G dialout $USER
|
||
# 或者临时给予权限
|
||
# sudo chmod 666 /dev/ttyUSB*
|
||
```
|
||
|
||
## 2. 一键部署流程
|
||
|
||
```bash
|
||
# 1. 克隆全量仓库
|
||
git clone https://gitea.1806999.xyz/18069996051/mixly3-server.git
|
||
cd mixly3-server
|
||
|
||
# 2. 安装依赖并初始化运行环境
|
||
npm install
|
||
|
||
# 3. 自动安装 Linux 版 Arduino 编译器 (自动重置为 Linux 二进制)
|
||
npm run arduino:install
|
||
|
||
# 4. 生成 SSL 证书
|
||
npm run cert:generate
|
||
|
||
# 5. 生成生产构建
|
||
npm run build:prod
|
||
|
||
# 6. 正式启动 (开发模式)
|
||
npm start
|
||
```
|
||
|
||
## 4. 生产环境建议 (进程守护与反代)
|
||
|
||
### 4.1 使用 pm2 管理进程
|
||
为了保证服务器断开连接后 Mixly 依然运行，建议使用 `pm2`:
|
||
|
||
```bash
|
||
sudo npm install -g pm2
|
||
pm2 start dist/bundle.cjs --name "mixly3"
|
||
pm2 save
|
||
pm2 startup
|
||
|
||
#### PM2 常用管理命令
|
||
- **查看状态**: `pm2 status` 或 `pm2 list`
|
||
- **重启服务**: `pm2 reload mixly3`
|
||
- **停止服务**: `pm2 stop mixly3`
|
||
- **查看日志**: `pm2 logs mixly3`
|
||
- **实时监控**: `pm2 monit`
|
||
```
|
||
|
||
### 4.2 使用 Nginx 反代 (推荐)
|
||
|
||
#### 步骤 1: 安装 Nginx 和 Certbot
|
||
```bash
|
||
apt update && apt install -y nginx certbot python3-certbot-nginx
|
||
```
|
||
|
||
#### 步骤 2: 创建 Nginx 配置文件
|
||
```bash
|
||
cat > /etc/nginx/sites-available/mixly << 'EOF'
|
||
server {
|
||
listen 80;
|
||
server_name 你的域名;
|
||
|
||
# 主站点反代
|
||
location / {
|
||
proxy_pass https://127.0.0.1:7100;
|
||
proxy_ssl_verify off;
|
||
proxy_set_header Host $host;
|
||
proxy_set_header X-Real-IP $remote_addr;
|
||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||
proxy_set_header X-Forwarded-Proto $scheme;
|
||
client_max_body_size 100M;
|
||
}
|
||
|
||
# WebSocket 反代 (关键配置)
|
||
location /mixly-socket/ {
|
||
proxy_pass https://127.0.0.1:7100/socket.io/;
|
||
proxy_ssl_verify off;
|
||
proxy_http_version 1.1;
|
||
proxy_set_header Upgrade $http_upgrade;
|
||
proxy_set_header Connection "upgrade";
|
||
proxy_set_header Host $host;
|
||
proxy_set_header X-Real-IP $remote_addr;
|
||
proxy_read_timeout 86400s;
|
||
}
|
||
}
|
||
EOF
|
||
```
|
||
> **注意**：将 `你的域名` 替换为实际域名，如 `mixly.example.com`
|
||
|
||
#### 步骤 3: 启用配置并测试
|
||
```bash
|
||
# 创建软链接启用配置
|
||
ln -sf /etc/nginx/sites-available/mixly /etc/nginx/sites-enabled/
|
||
|
||
# 删除默认站点 (可选)
|
||
rm -f /etc/nginx/sites-enabled/default
|
||
|
||
# 测试配置语法
|
||
nginx -t
|
||
|
||
# 重启 Nginx
|
||
systemctl restart nginx
|
||
```
|
||
|
||
#### 步骤 4: 自动申请 SSL 证书 (Let's Encrypt)
|
||
```bash
|
||
# 将 your-email@example.com 替换为你的邮箱
|
||
certbot --nginx -d 你的域名 --non-interactive --agree-tos -m your-email@example.com
|
||
```
|
||
|
||
Certbot 会自动修改 Nginx 配置并启用 HTTPS (443 端口)。
|
||
|
||
#### 步骤 5: 设置证书自动续期
|
||
```bash
|
||
# 测试自动续期
|
||
certbot renew --dry-run
|
||
|
||
# 证书默认每 90 天过期，certbot 会自动配置定时任务续期
|
||
```
|
||
|
||
#### Nginx 常用管理命令
|
||
```bash
|
||
# 查看状态
|
||
systemctl status nginx
|
||
|
||
# 重载配置 (不中断服务)
|
||
systemctl reload nginx
|
||
|
||
# 查看错误日志
|
||
tail -f /var/log/nginx/error.log
|
||
```
|
||
|
||
## 5. 跨平台特性说明
|
||
|
||
- **路径自动适配**：本项目已重构 `config.js`，部署时会自动识别 Linux 路径，无需手动修改 `config.json`。
|
||
- **库文件全内置**：`arduino-libs` 已包含在 Git 仓库中，`git clone` 后即可直接编译带库的工程。
|
||
|
||
## 7. 日常维护与热更新
|
||
|
||
如果你在本地对代码进行了修改并不想重新执行全量部署，可以通过以下步骤快速同步：
|
||
|
||
```bash
|
||
# 进入服务端目录
|
||
cd mixly3-server
|
||
|
||
# 1. 拉取最新代码 (包含核心逻辑修复或板卡库更新)
|
||
git pull
|
||
|
||
# 2. 重新构建生产代码 (非常重要：只要有 src 目录的改动就必须执行)
|
||
npm run build:prod
|
||
|
||
# 3. 重启服务
|
||
# 如果你是用 npm start 运行的，先 Ctrl+C 中断再运行即可。
|
||
# 如果你是用 pm2 管理的，执行：
|
||
pm2 reload mixly3
|
||
```
|
||
|
||
## 8. 常见问题排查
|
||
|
||
- **HTTPS 访问**：默认运行在 `https://你的IP:7100`。
|
||
- **反向代理配置**：如果使用 Nginx 反代，请务必处理好的 WebSocket (Upgrade) 头，否则页面无法连接。
|
||
- **上传报错**：如果提示权限不足，请确认当前用户是否在 `dialout` 组，或尝试 `root` 运行（不推荐）。
|
||
- **Python 命令**：系统必须能识别 `python3` 命令。
|
||
- **没有“添加设备”按钮**：这是因为 WebSocket 连接失败。
|
||
1. 检查 NPM 中是否勾选了 **Websockets Support**。
|
||
2. 检查 NPM Advanced 配置中是否添加了 `proxy_ssl_verify off;` (关键)。
|
||
3. 尝试重启服务端：`pm2 reload mixly3`。
|