From 2fc8e2e7d000e0a4c2f955be0575a2231d560ccc Mon Sep 17 00:00:00 2001
From: yczpf2019 <yczpf2019@outlook.com>
Date: Sat, 24 Jan 2026 16:23:24 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=20Debian=20VPS=20?=
 =?UTF-8?q?=E8=AF=A6=E7=BB=86=E9=83=A8=E7=BD=B2=E6=89=8B=E5=86=8C?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README_VPS.md | 66 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 66 insertions(+)
 create mode 100644 README_VPS.md

diff --git a/README_VPS.md b/README_VPS.md
new file mode 100644
index 00000000..3b186d91
--- /dev/null
+++ b/README_VPS.md
@@ -0,0 +1,66 @@
+# 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
+```
+
+## 3. 生产环境建议 (进程守护)
+
+为了保证服务器断开连接后 Mixly 依然运行，建议使用 `pm2`:
+
+```bash
+sudo npm install -g pm2
+pm2 start dist/bundle.cjs --name "mixly3"
+pm2 save
+pm2 startup
+```
+
+## 4. 跨平台特性说明
+
+-   **路径自动适配**：本项目已重构 `config.js`，部署时会自动识别 Linux 路径，无需手动修改 `config.json`。
+-   **库文件全内置**：`arduino-libs` 已包含在 Git 仓库中，`git clone` 后即可直接编译带库的工程。
+
+## 5. 常见问题排查
+
+-   **HTTPS 访问**：默认运行在 `https://你的IP:7100`。
+-   **上传报错**：如果提示权限不足，请确认当前用户是否在 `dialout` 组，或尝试 `root` 运行（不推荐）。
+-   **Python 命令**：系统必须能识别 `python3` 命令。