docs: 替换官方 README，提供完整的跨平台部署与 NPM 反代指南
This commit is contained in:
yczpf2019
127
README.md
127
README.md
@@ -1,22 +1,133 @@
|
|||||||
## Mixly3.0 服务端
|
# Mixly 3.0 服务器部署手册 (Debian VPS)
|
||||||
|
|
||||||
1.安装依赖
|
本项目已实现单仓库镜像化部署，包含所有前端资源、板卡配置及 250+ 常用 Arduino 扩展库。
|
||||||
|
|
||||||
|
## 1. 前置依赖安装
|
||||||
|
|
||||||
|
在 Debian/Ubuntu 上执行：
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
npm install
|
# 更新系统
|
||||||
|
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
|
||||||
|
|
||||||
|
# 串口访问权限设置 (非常重要：否则无法烧录/上传)
|
||||||
|
sudo usermod -a -G dialout $USER
|
||||||
|
# 或者临时给予权限
|
||||||
|
# sudo chmod 666 /dev/ttyUSB*
|
||||||
```
|
```
|
||||||
|
|
||||||
2.脚本执行
|
## 2. 一键部署流程
|
||||||
|
|
||||||
- 调试
|
|
||||||
|
|
||||||
```bash
|
```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
|
npm start
|
||||||
```
|
```
|
||||||
|
|
||||||
- 针对生产环境打包
|
## 4. 生产环境建议 (进程守护与反代)
|
||||||
|
|
||||||
|
### 4.1 使用 pm2 管理进程
|
||||||
|
为了保证服务器断开连接后 Mixly 依然运行，建议使用 `pm2`:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
npm run build:prod
|
sudo npm install -g pm2
|
||||||
|
pm2 start dist/bundle.cjs --name "mixly3"
|
||||||
|
pm2 save
|
||||||
|
pm2 startup
|
||||||
```
|
```
|
||||||
|
|
||||||
|
### 4.2 使用 Nginx 反代 (推荐)
|
||||||
|
|
||||||
|
#### A. 传统 Nginx 配置 (命令行)
|
||||||
|
如果你使用原生 Nginx，请参考以下配置：
|
||||||
|
|
||||||
|
```nginx
|
||||||
|
server {
|
||||||
|
listen 80;
|
||||||
|
server_name 你的域名;
|
||||||
|
return 301 https://$host$request_uri;
|
||||||
|
}
|
||||||
|
|
||||||
|
server {
|
||||||
|
listen 443 ssl;
|
||||||
|
server_name 你的域名;
|
||||||
|
|
||||||
|
ssl_certificate /path/to/your/cert.pem;
|
||||||
|
ssl_certificate_key /path/to/your/key.pem;
|
||||||
|
|
||||||
|
# 核心配置：处理 WebSocket 和大文件上传
|
||||||
|
location / {
|
||||||
|
proxy_pass https://127.0.0.1:7100;
|
||||||
|
proxy_http_version 1.1;
|
||||||
|
proxy_set_header Upgrade $http_upgrade;
|
||||||
|
proxy_set_header Connection "upgrade";
|
||||||
|
proxy_set_header Host $host;
|
||||||
|
|
||||||
|
client_max_body_size 100M;
|
||||||
|
proxy_read_timeout 3600s;
|
||||||
|
}
|
||||||
|
|
||||||
|
# 处理 Socket.io 特殊路径
|
||||||
|
location /mixly-socket/ {
|
||||||
|
proxy_pass https://127.0.0.1:7100;
|
||||||
|
proxy_http_version 1.1;
|
||||||
|
proxy_set_header Upgrade $http_upgrade;
|
||||||
|
proxy_set_header Connection "upgrade";
|
||||||
|
proxy_set_header Host $host;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### B. Nginx Proxy Manager (NPM) 配置 (可视化)
|
||||||
|
如果你使用的是 NPM，请按以下步骤配置：
|
||||||
|
|
||||||
|
1. **Details 选项卡**：
|
||||||
|
* **Domain Names**: `你的域名`
|
||||||
|
* **Scheme**: `https`
|
||||||
|
* **Forward Hostname/IP**: `127.0.0.1`
|
||||||
|
* **Forward Port**: `7100`
|
||||||
|
* **Websockets Support**: **必须勾选 (ON)**
|
||||||
|
2. **Custom Locations 选项卡**：
|
||||||
|
* 点击 **Add Location**:
|
||||||
|
* **Define Location**: `/mixly-socket/`
|
||||||
|
* **Forward Scheme**: `https`
|
||||||
|
* **Forward Hostname/IP**: `127.0.0.1`
|
||||||
|
* **Forward Port**: `7100`
|
||||||
|
* 点击内置的齿轮图标或进入 **Advanced**，确保有以下配置（通常勾选 Websockets Support 后 NPM 会自动处理，但建议检查）：
|
||||||
|
```nginx
|
||||||
|
proxy_set_header Upgrade $http_upgrade;
|
||||||
|
proxy_set_header Connection "upgrade";
|
||||||
|
```
|
||||||
|
3. **Advanced 选项卡** (可选)：
|
||||||
|
* 建议添加：`client_max_body_size 100M;` 以支持大文件。
|
||||||
|
|
||||||
|
## 5. 跨平台特性说明
|
||||||
|
|
||||||
|
- **路径自动适配**：本项目已重构 `config.js`，部署时会自动识别 Linux 路径，无需手动修改 `config.json`。
|
||||||
|
- **库文件全内置**：`arduino-libs` 已包含在 Git 仓库中，`git clone` 后即可直接编译带库的工程。
|
||||||
|
|
||||||
|
## 6. 常见问题排查
|
||||||
|
|
||||||
|
- **HTTPS 访问**：默认运行在 `https://你的IP:7100`。
|
||||||
|
- **反向代理配置**：如果使用 Nginx 反代，请务必处理好的 WebSocket (Upgrade) 头，否则页面无法连接。
|
||||||
|
- **上传报错**：如果提示权限不足，请确认当前用户是否在 `dialout` 组，或尝试 `root` 运行（不推荐）。
|
||||||
|
- **Python 命令**：系统必须能识别 `python3` 命令。
|
||||||
|
|||||||
133
README_VPS.md
133
README_VPS.md
@@ -1,133 +0,0 @@
|
|||||||
# 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
|
|
||||||
|
|
||||||
# 串口访问权限设置 (非常重要：否则无法烧录/上传)
|
|
||||||
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
|
|
||||||
```
|
|
||||||
|
|
||||||
### 4.2 使用 Nginx 反代 (推荐)
|
|
||||||
|
|
||||||
#### A. 传统 Nginx 配置 (命令行)
|
|
||||||
如果你使用原生 Nginx，请参考以下配置：
|
|
||||||
|
|
||||||
```nginx
|
|
||||||
server {
|
|
||||||
listen 80;
|
|
||||||
server_name 你的域名;
|
|
||||||
return 301 https://$host$request_uri;
|
|
||||||
}
|
|
||||||
|
|
||||||
server {
|
|
||||||
listen 443 ssl;
|
|
||||||
server_name 你的域名;
|
|
||||||
|
|
||||||
ssl_certificate /path/to/your/cert.pem;
|
|
||||||
ssl_certificate_key /path/to/your/key.pem;
|
|
||||||
|
|
||||||
# 核心配置：处理 WebSocket 和大文件上传
|
|
||||||
location / {
|
|
||||||
proxy_pass https://127.0.0.1:7100;
|
|
||||||
proxy_http_version 1.1;
|
|
||||||
proxy_set_header Upgrade $http_upgrade;
|
|
||||||
proxy_set_header Connection "upgrade";
|
|
||||||
proxy_set_header Host $host;
|
|
||||||
|
|
||||||
client_max_body_size 100M;
|
|
||||||
proxy_read_timeout 3600s;
|
|
||||||
}
|
|
||||||
|
|
||||||
# 处理 Socket.io 特殊路径
|
|
||||||
location /mixly-socket/ {
|
|
||||||
proxy_pass https://127.0.0.1:7100;
|
|
||||||
proxy_http_version 1.1;
|
|
||||||
proxy_set_header Upgrade $http_upgrade;
|
|
||||||
proxy_set_header Connection "upgrade";
|
|
||||||
proxy_set_header Host $host;
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### B. Nginx Proxy Manager (NPM) 配置 (可视化)
|
|
||||||
如果你使用的是 NPM，请按以下步骤配置：
|
|
||||||
|
|
||||||
1. **Details 选项卡**：
|
|
||||||
* **Domain Names**: `你的域名`
|
|
||||||
* **Scheme**: `https`
|
|
||||||
* **Forward Hostname/IP**: `127.0.0.1`
|
|
||||||
* **Forward Port**: `7100`
|
|
||||||
* **Websockets Support**: **必须勾选 (ON)**
|
|
||||||
2. **Custom Locations 选项卡**：
|
|
||||||
* 点击 **Add Location**:
|
|
||||||
* **Define Location**: `/mixly-socket/`
|
|
||||||
* **Forward Scheme**: `https`
|
|
||||||
* **Forward Hostname/IP**: `127.0.0.1`
|
|
||||||
* **Forward Port**: `7100`
|
|
||||||
* 点击内置的齿轮图标或进入 **Advanced**，确保有以下配置（通常勾选 Websockets Support 后 NPM 会自动处理，但建议检查）：
|
|
||||||
```nginx
|
|
||||||
proxy_set_header Upgrade $http_upgrade;
|
|
||||||
proxy_set_header Connection "upgrade";
|
|
||||||
```
|
|
||||||
3. **Advanced 选项卡** (可选)：
|
|
||||||
* 建议添加：`client_max_body_size 100M;` 以支持大文件。
|
|
||||||
|
|
||||||
## 5. 跨平台特性说明
|
|
||||||
|
|
||||||
- **路径自动适配**：本项目已重构 `config.js`，部署时会自动识别 Linux 路径，无需手动修改 `config.json`。
|
|
||||||
- **库文件全内置**：`arduino-libs` 已包含在 Git 仓库中，`git clone` 后即可直接编译带库的工程。
|
|
||||||
|
|
||||||
## 6. 常见问题排查
|
|
||||||
|
|
||||||
- **HTTPS 访问**：默认运行在 `https://你的IP:7100`。
|
|
||||||
- **反向代理配置**：如果使用 Nginx 反代，请务必处理好的 WebSocket (Upgrade) 头，否则页面无法连接。
|
|
||||||
- **上传报错**：如果提示权限不足，请确认当前用户是否在 `dialout` 组，或尝试 `root` 运行（不推荐）。
|
|
||||||
- **Python 命令**：系统必须能识别 `python3` 命令。
|
|
||||||
Reference in New Issue
Block a user