Mixly 3.0 服务器部署手册 (Debian VPS)

本项目已实现单仓库镜像化部署，包含所有前端资源、板卡配置及 250+ 常用 Arduino 扩展库。

1. 前置依赖安装

在 Debian/Ubuntu 上执行：

# 更新系统
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. 一键部署流程

# 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:

sudo npm install -g pm2
pm2 start dist/bundle.cjs --name "mixly3"
pm2 save
pm2 startup

4.2 使用 Nginx 反代 (推荐)

A. 传统 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 会自动处理，但建议检查）：

       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 后即可直接编译带库的工程。

7. 日常维护与热更新

如果你在本地对代码进行了修改并不想重新执行全量部署，可以通过以下步骤快速同步：

# 进入服务端目录
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 命令。