zhengsl/emcp

Fork 0

root f6499daf87 提交修改内容

2026-05-26 16:13:35 +08:00

17 KiB

Raw Blame History

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. 部署建议

推荐目录规划如下：

/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 设备终端执行：

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 安装浏览器

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

sudo apt install -y chromium-browser

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

sudo apt install -y firefox

低资源建议：

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

4.3 拷贝项目代码

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

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

然后将项目复制到：

/userdata/emcp/backend
/userdata/emcp/frontend/dist

推荐目录示例：

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

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

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

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

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

前端发布建议：

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

5. 后端部署

5.1 确认系统 Python 版本

python3 --version

期望输出：

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 安装后端依赖

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

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

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

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：

mkdir -p /userdata/emcp/data/backups

在 /userdata/emcp/backend/.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 手动启动后端验证

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 服务器执行：

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

构建完成后会生成：

frontend/dist

6.2 上传 dist 到 RK3568 服务器

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

/userdata/emcp/frontend/dist

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

6.3 手动启动前端验证

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

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. 首次联调检查

建议按以下顺序进行：

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

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

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

补充说明：

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

8. 配置开机自动启动

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

8.1 配置后端服务

创建文件：

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

内容如下：

[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 配置前端服务

创建文件：

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

内容如下：

[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

执行：

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

查看状态：

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

查看日志：

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

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

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

9.1 前置条件

建议提前确认以下两项：

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

说明：

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

9.2 创建浏览器启动脚本

创建目录：

mkdir -p /userdata/emcp/scripts

创建脚本文件：

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

内容如下：

#!/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

赋予执行权限：

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

说明：

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

9.3 配置桌面自动启动项

创建目录：

mkdir -p ~/.config/autostart

创建文件：

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

内容如下：

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

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

http://127.0.0.1:5173/

10. 快捷设置说明

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

10.1 一次性完成部署

按以下顺序操作即可：

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

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

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

10.2 最常用检查命令

检查后端状态：

sudo systemctl status emcp-backend.service

检查前端状态：

sudo systemctl status emcp-frontend.service

重启后端：

sudo systemctl restart emcp-backend.service

重启前端：

sudo systemctl restart emcp-frontend.service

重新打开浏览器主页：

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

10.3 修改主页地址

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

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

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

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

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

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

11. 日常使用说明

11.1 启动后访问方式

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

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

默认主页地址：

http://127.0.0.1:5173/

11.2 页面使用提示

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

当前默认安全校验密码：

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/：

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

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

sudo systemctl restart emcp-frontend.service

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

sudo systemctl restart emcp-backend.service

13. 推荐交付方式

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

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

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

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

17 KiB Raw Blame History Unescape Escape

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

1. 文档目的

2. 适用范围

3. 部署建议

3.1 低资源设备优化原则

4. 环境准备

4.1 安装系统依赖

4.2 安装浏览器

4.3 拷贝项目代码

5. 后端部署

5.1 确认系统 Python 版本

5.2 安装后端依赖

5.3 配置运行数据目录

5.4 手动启动后端验证

6. 前端部署

6.1 在开发机打包前端

6.2 上传 dist 到 RK3568 服务器

6.3 手动启动前端验证

7. 首次联调检查

8. 配置开机自动启动

8.1 配置后端服务

8.2 配置前端服务

8.3 启用开机自启

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

9.1 前置条件

9.2 创建浏览器启动脚本

9.3 配置桌面自动启动项

10. 快捷设置说明

10.1 一次性完成部署

10.2 最常用检查命令

10.3 修改主页地址

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

11. 日常使用说明

11.1 启动后访问方式

11.2 页面使用提示

12. 常见问题

12.1 浏览器没有自动打开

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

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

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

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

13. 推荐交付方式

17 KiB

Raw Blame History