diff --git a/README.md b/README.md index 3a57e572..32927f6a 100755 --- a/README.md +++ b/README.md @@ -1,22 +1,133 @@ -## Mixly3.0 服务端 +# Mixly 3.0 服务器部署手册 (Debian VPS) -1.安装依赖 +本项目已实现单仓库镜像化部署，包含所有前端资源、板卡配置及 250+ 常用 Arduino 扩展库。 + +## 1. 前置依赖安装 + +在 Debian/Ubuntu 上执行： ```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 +# 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 -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` 命令。 diff --git a/README_VPS.md b/README_VPS.md deleted file mode 100644 index 32927f6a..00000000 --- a/README_VPS.md +++ /dev/null @@ -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` 命令。