emcp/document/在RK3568设备上系统部署及使用说明.md

# RK3568 设备上系统部署及使用说明

## 1. 文档目的

本文档用于说明如何在 `RK3568 + Ubuntu 20.04` 设备上部署 `EMCP` 电气量测控平台的前后端系统，并完成以下目标：

- 部署后端 `FastAPI + Uvicorn` 服务
- 部署前端静态页面
- 配置前后端开机自动启动
- 登录桌面后自动打开浏览器并访问主页面
- 给出现场快速设置和日常使用说明

---

## 2. 适用范围

适用对象：

- 硬件平台：`RK3568`
- 操作系统：`Ubuntu 20.04`
- 部署模式：前后端均部署在同一台设备本机

当前工程实际情况：

- 后端运行端口：`8000`
- 前端访问地址建议使用：`http://127.0.0.1:5173/`
- 前端默认请求后端地址：`http://127.0.0.1:8000/api`
- 前端默认请求头中携带：`X-API-Token: admin123`
- 默认安全校验密码：`admin123`
- 后端默认启用模拟采集：`use_mock_device = True`
- 后端项目声明支持的 Python 版本：`>=3.8`
- 当前设备资源较紧张：根分区剩余约 `2.8G`，物理内存约 `1.9G`，无 `Swap`
- 最终部署方案：不创建虚拟环境，直接使用系统 `Python 3.10.12`

说明：

- 当前前端代码默认调用本机 `127.0.0.1:8000` 的后端接口，因此推荐前后端部署在同一台 RK3568 设备上
- 推荐发布方式为：前端在开发机执行 `npm run build`，服务器只上传并发布 `dist/` 静态文件
- 当前设备属于嵌入式一体机，推荐采用“最小化部署”方案，避免在设备上保留前端源码、`node_modules`、开发工具和大体积缓存
- 当前文档以下步骤均按“直接使用系统 `python3`，不创建 `.venv`”编写
- 如果后续需要将前后端拆分到不同设备，需要同步调整前端接口配置

---

## 3. 部署建议

推荐目录规划如下：

```text
/userdata/emcp/
├── backend/
├── frontend/
│   └── dist/
├── scripts/
└── data/
```

建议使用以下方式部署：

- 后端：`systemd` 托管 `uvicorn`
- 前端：开发机完成 `npm run build` 后，仅将 `dist/` 上传到设备，再用轻量静态服务对 `dist/` 目录发布
- 浏览器自启动：使用桌面自动启动项 `~/.config/autostart/*.desktop`
- 数据目录、报警数据库、备份目录统一放在 `/userdata`，减少根分区占用
- 不在服务器安装 `Node.js/npm`
- 不在服务器安装前端源码依赖，不安装后端开发依赖 `.[dev]`

### 3.1 低资源设备优化原则

- 优先使用 `/userdata` 分区存放程序和运行数据，尽量不占用根分区
- 后端安装依赖时使用 `pip --no-cache-dir`，避免留下 `pip` 缓存
- 前端只上传 `dist/`，不上传 `src/`、`node_modules/`、`.git/`
- 后端直接使用系统 `python3.10.12`，不创建虚拟环境，进一步减少磁盘占用
- 生产环境只启动一个 `uvicorn` 进程，不开启 `--reload`
- 尽量复用系统已有浏览器，不额外安装多个浏览器
- 日志通过 `journalctl` 查看，不另外输出到大日志文件

---

## 4. 环境准备

### 4.1 安装系统依赖

在 RK3568 设备终端执行：

```bash
sudo apt update
sudo apt install -y python3.10-venv python3-pip
```

说明：

- 当前服务器已安装 `Python 3.10.12`，本项目后端 `requires-python = ">=3.8"`，因此可直接使用 `Python 3.10.12` 部署
- 建议先执行 `python3.10 --version`，确认输出为 `Python 3.10.12`
- 如果设备上的 `python3.10-venv` 尚未安装，可通过上面的命令补齐
- 当前推荐方案下，RK3568 服务器无需安装 `Node.js` 或 `npm`
- `Node.js/npm` 仅在开发机或构建机执行前端打包时需要
- 如果代码是通过 `scp`、`rsync` 或 U 盘拷贝，服务器也无需安装 `git`
- 若现场需要临时下载文件，再按需安装 `curl` 或 `git`

### 4.2 安装浏览器

如果设备带图形桌面，建议至少安装一个浏览器：

```bash
sudo apt install -y chromium-browser
```

如果系统仓库没有 `chromium-browser`，也可以使用：

```bash
sudo apt install -y firefox
```

低资源建议：

- 如果系统已经自带可用浏览器，则不要重复安装第二个浏览器
- 通常只保留一个浏览器即可，减少磁盘占用

### 4.3 拷贝项目代码

将工程目录拷贝到设备，例如：

```bash
sudo mkdir -p /userdata/emcp
sudo chown -R $USER:$USER /userdata/emcp
```

然后将项目复制到：

```text
/userdata/emcp/backend
/userdata/emcp/frontend/dist
```

推荐目录示例：

```text
/userdata/emcp/
├── backend/
├── frontend/
│   └── dist/
├── scripts/
└── data/
```

如果确实需要兼容历史脚本中的 `/opt/emcp` 路径，可以建立软链接：

```bash
sudo ln -sfn /userdata/emcp /opt/emcp
```

如果后端通过 `git` 拉取，也可以在 `/userdata` 下执行：

```bash
git clone <你的仓库地址> /userdata/emcp
```

前端发布建议：

- 开发机执行 `npm install`、`npm run build`
- 只将打包产物 `frontend/dist/` 复制到服务器 `/userdata/emcp/frontend/dist`
- 服务器无需保留前端源码、`node_modules`、`package.json`
- 如需进一步节省空间，可将 `backend/` 打包为压缩包后再上传，上传后立即删除压缩包

---

## 5. 后端部署

### 5.1 确认系统 Python 版本

```bash
python3 --version
```

期望输出：

```text
Python 3.10.12
安装pip3
curl -sS https://bootstrap.pypa.io/get-pip.py -o get-pip.py && python3 get-pip.py && rm get-pip.py 
```

### 5.2 安装后端依赖

```bash
cd /userdata/emcp/backend
 
python3 -m pip install --no-cache-dir -e .
```

生产环境不建议安装测试或调试工具，避免额外占用磁盘空间。

如确实需要测试或调试工具，再安装：

```bash
python3 -m pip install --no-cache-dir -e .[dev]
```

补充说明：

- 当前项目在本地开发阶段使用过 `Python 3.8` 虚拟环境，但部署到 RK3568 服务器时直接使用系统 `Python 3.10.12` 即可
- 当前部署方案不创建 `.venv`，Python 依赖直接安装到系统环境
- `--no-cache-dir` 可以避免在 `~/.cache/pip` 中留下额外缓存文件
- 安装完成后如需进一步清理，可执行 `rm -rf ~/.cache/pip`
- 如需保留当前依赖快照，可执行 `python3 -m pip freeze > /userdata/emcp/backend/requirements.lock.txt`

### 5.3 配置运行数据目录

建议将报警数据库、备份目录等运行时数据统一放到 `/userdata/emcp/data`：

```bash
mkdir -p /userdata/emcp/data/backups
```

在 `/userdata/emcp/backend/.env` 中写入：

```env
EMCP_DATA_DIR=/userdata/emcp/data
EMCP_ALARM_DB_PATH=/userdata/emcp/data/alarm.db
EMCP_BACKUP_DIR=/userdata/emcp/data/backups
```

说明：

- 这样即使根分区空间较紧张，报警数据库和备份文件也不会继续占用 `/`
- 如果将来需要清理历史数据，也只需处理 `/userdata/emcp/data`

### 5.4 手动启动后端验证

```bash
cd /userdata/emcp/backend
python3 -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --no-access-log
```

验证方式：

- 本机健康检查：`http://127.0.0.1:8000/`
- 接口文档：`http://127.0.0.1:8000/docs`

如果能正常返回服务信息，说明后端部署成功。

---

## 6. 前端部署

### 6.1 在开发机打包前端

以下步骤在开发机执行，不在 RK3568 服务器执行：

```bash
cd /path/to/EMCP/frontend
npm install
npm run build
```

构建完成后会生成：

```text
frontend/dist
```

### 6.2 上传 dist 到 RK3568 服务器

将打包好的 `dist/` 目录复制到服务器：

```text
/userdata/emcp/frontend/dist
```

可根据现场情况使用 `scp`、`rsync`、U 盘或其他方式拷贝。

### 6.3 手动启动前端验证

推荐使用 Python 内置静态服务快速发布：

```bash
cd /userdata/emcp/frontend
python3 -m http.server 5173 --directory dist --bind 0.0.0.0
```

验证地址：

- 前端页面：`http://127.0.0.1:5173/`

说明：

- 当前前端默认调用本机后端 `http://127.0.0.1:8000/api`
- 因此前端页面只要在设备本机打开，即可直接访问后端服务
- 当前发布方案中，服务器只负责托管静态文件，不参与前端构建

---

## 7. 首次联调检查

建议按以下顺序进行：

1. 先启动后端
2. 再启动前端静态服务
3. 浏览器打开 `http://127.0.0.1:5173/`
4. 检查实时数据、设备状态、报警历史等页面是否能正常进入

当前项目已打通页面包括：

- 实时数据
- 设备状态
- 设备配置
- 通道配置
- 报警设置
- 报警历史
- 控制指令
- 系统设置

补充说明：

- `设备状态` 页面支持刷新
- `报警历史` 页面支持分页和刷新
- 配置保存前会弹出安全校验密码输入框
- 当前默认安全校验密码为 `admin123`
- 交付到现场后，建议尽快修改 `device.json` 中的设备密码，避免继续使用默认密码

---

## 8. 配置开机自动启动

推荐使用 `systemd` 管理前后端服务。

### 8.1 配置后端服务

创建文件：

```text
/etc/systemd/system/emcp-backend.service
```

内容如下：

```ini
[Unit]
Description=EMCP Backend Service
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=ubuntu
WorkingDirectory=/userdata/emcp/backend
Environment=PYTHONDONTWRITEBYTECODE=1
Environment=PYTHONUNBUFFERED=1
EnvironmentFile=-/userdata/emcp/backend/.env
ExecStart=/usr/bin/python3 -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --no-access-log
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target
```

说明：

- `User=ubuntu` 需要替换为设备实际登录用户名
- 如需切换真实采集设备，可结合 `.env` 或配置文件调整后端参数
- 当前服务直接调用系统 `python3`
- `--no-access-log` 可减少日志输出和磁盘写入
- `PYTHONDONTWRITEBYTECODE=1` 可避免生成额外的 `.pyc` 文件

### 8.2 配置前端服务

创建文件：

```text
/etc/systemd/system/emcp-frontend.service
```

内容如下：

```ini
[Unit]
Description=EMCP Frontend Static Service
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=ubuntu
WorkingDirectory=/userdata/emcp/frontend
ExecStart=/usr/bin/python3 -m http.server 5173 --directory /userdata/emcp/frontend/dist --bind 0.0.0.0
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target
```

### 8.3 启用开机自启

需要给linaro授权

sudo chown -R linaro:linaro /userdata/emcp/data
sudo chown -R linaro:linaro /userdata/emcp/backend/config



执行：

```bash
sudo systemctl daemon-reload
sudo systemctl enable emcp-backend.service
sudo systemctl enable emcp-frontend.service
sudo systemctl start emcp-backend.service
sudo systemctl start emcp-frontend.service
```

查看状态：

```bash
sudo systemctl status emcp-backend.service
sudo systemctl status emcp-frontend.service
```

查看日志：

```bash
journalctl -u emcp-backend.service -f
journalctl -u emcp-frontend.service -f
```

---

## 9. 开机自动打开浏览器访问主页面

本功能依赖图形桌面环境。若设备只启动命令行、不进入桌面，则无法自动弹出浏览器。

### 9.1 前置条件

建议提前确认以下两项：

- 设备已安装浏览器
- 设备已启用桌面自动登录，或现场人员上电后会手动登录桌面

说明：

- 只有在用户登录图形桌面后，自动启动项才会执行
- 如果希望“上电后无需人工登录就自动打开页面”，需要同时开启系统自动登录

### 9.2 创建浏览器启动脚本

创建目录：

```bash
mkdir -p /userdata/emcp/scripts
```

创建脚本文件：

```text
/userdata/emcp/scripts/start-emcp-browser.sh
```

内容如下：

```bash
#!/bin/bash
sleep 8

URL="http://127.0.0.1:5173/"

if command -v chromium-browser >/dev/null 2>&1; then
  chromium-browser --start-fullscreen --no-first-run --disk-cache-size=10485760 "$URL" >/dev/null 2>&1 &
elif command -v firefox >/dev/null 2>&1; then
  firefox "$URL" >/dev/null 2>&1 &
else
  xdg-open "$URL" >/dev/null 2>&1 &
fi
```

赋予执行权限：

```bash
chmod +x /userdata/emcp/scripts/start-emcp-browser.sh
```

说明：

- `sleep 8` 用于等待前后端服务启动完成
- 如果设备性能较低，可改为 `sleep 10` 或 `sleep 15`
- 如需全屏显示，优先使用 `chromium-browser --start-fullscreen`
- 对低资源设备，浏览器缓存建议尽量缩小

### 9.3 配置桌面自动启动项

创建目录：

```bash
mkdir -p ~/.config/autostart
```

创建文件：

```text
~/.config/autostart/emcp-browser.desktop
```

内容如下：

```ini
[Desktop Entry]
Type=Application
Name=EMCP Browser Autostart
Exec=/userdata/emcp/scripts/start-emcp-browser.sh
X-GNOME-Autostart-enabled=true
Terminal=false
```

配置完成后，用户每次登录桌面时都会自动打开浏览器并访问：

```text
http://127.0.0.1:5173/
```

---

## 10. 快捷设置说明

这一节适合现场交付时快速操作。

### 10.1 一次性完成部署

按以下顺序操作即可：

1. 拷贝项目到 `/userdata/emcp`
2. 如需兼容旧路径，建立 `/opt/emcp -> /userdata/emcp` 软链接
3. 使用系统 `python3` 安装后端依赖
4. 在开发机执行前端 `npm install` 和 `npm run build`
5. 将 `dist/` 上传到服务器 `/userdata/emcp/frontend/dist`
6. 创建 `/userdata/emcp/backend/.env`，将运行数据目录指向 `/userdata/emcp/data`
7. 创建两个 `systemd` 服务
8. 创建浏览器自动启动脚本
9. 创建 `~/.config/autostart/emcp-browser.desktop`
10. 执行 `systemctl enable` 完成开机自启

资源紧张时，优先保证以下三点：

- 服务器只保留 `backend/` 和 `frontend/dist/`
- 不安装 `Node.js/npm`，不安装 `.[dev]`
- 运行数据放在 `/userdata/emcp/data`
- 后端直接使用系统 `python3.10.12`，不创建虚拟环境

### 10.2 最常用检查命令

检查后端状态：

```bash
sudo systemctl status emcp-backend.service
```

检查前端状态：

```bash
sudo systemctl status emcp-frontend.service
```

重启后端：

```bash
sudo systemctl restart emcp-backend.service
```

重启前端：

```bash
sudo systemctl restart emcp-frontend.service
```

重新打开浏览器主页：

```bash
/userdata/emcp/scripts/start-emcp-browser.sh
```

### 10.3 修改主页地址

如果前端端口改为其他端口，例如 `8080`，需要同步修改以下两处：

- `/userdata/emcp/scripts/start-emcp-browser.sh` 中的 `URL`
- 前端静态服务端口或访问地址

如果修改了前端源码，需要在开发机重新构建并重新上传新的 `dist/` 目录，服务器本机不需要执行 `npm install`

### 10.4 修改登录后自动打开行为

如果不希望每次登录都自动打开浏览器，可以删除或重命名：

```text
~/.config/autostart/emcp-browser.desktop
```

---

## 11. 日常使用说明

### 11.1 启动后访问方式

当设备开机完成并进入桌面后，系统会自动：

- 启动后端服务
- 启动前端静态服务
- 打开浏览器访问主页

默认主页地址：

```text
http://127.0.0.1:5173/
```

### 11.2 页面使用提示

- 实时数据页：查看模拟或采集到的实时数据
- 设备状态页：支持手动刷新状态
- 报警历史页：支持分页和刷新
- 配置类页面：保存前需要输入安全校验密码

当前默认安全校验密码：

```text
admin123
```

建议交付后尽快修改为现场正式密码。

---

## 12. 常见问题

### 12.1 浏览器没有自动打开

请检查：

- 是否进入了图形桌面
- `~/.config/autostart/emcp-browser.desktop` 是否存在
- `/userdata/emcp/scripts/start-emcp-browser.sh` 是否有执行权限
- 浏览器是否已安装

### 12.2 浏览器打开了，但页面访问失败

请检查：

- 前端服务是否启动成功
- `5173` 端口是否被其他程序占用
- `/userdata/emcp/frontend/dist` 是否已经构建生成

### 12.3 页面能打开，但接口不通

请检查：

- 后端服务是否启动成功
- `8000` 端口是否正常监听
- 前端默认接口地址是否仍为 `http://127.0.0.1:8000/api`

### 12.4 页面保存时报权限或校验失败

请检查：

- 默认请求头 `X-API-Token` 是否被修改
- 输入的安全校验密码是否正确
- 当前默认密码是否仍为 `admin123`

### 12.5 修改代码后页面没有变化

请检查是否已经在开发机重新执行前端构建并重新上传新的 `dist/`：

```bash
cd /path/to/EMCP/frontend
npm run build
```

上传完成后，在服务器执行：

```bash
sudo systemctl restart emcp-frontend.service
```

后端代码修改后则需要重启后端服务：

```bash
sudo systemctl restart emcp-backend.service
```

---

## 13. 推荐交付方式

建议现场交付时采用以下方式：

- 设备开机自动进入桌面
- 后端和前端均使用 `systemd` 自启动
- 浏览器自动全屏打开主页
- 保留一个终端窗口或 SSH 方式用于维护
- 程序与运行数据优先放在 `/userdata/emcp`

如需进一步增强生产部署能力，后续可继续补充：

- `Nginx` 托管前端静态资源
- 反向代理后端接口
- HTTPS 证书
- 真实硬件采集驱动接入
- 自动备份配置与报警数据库