emcp/document/在RK3568设备上系统部署及使用说明.md
2026-05-26 16:13:35 +08:00

707 lines
17 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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 证书
- 真实硬件采集驱动接入
- 自动备份配置与报警数据库