项目架构设计

环境准备

apt install net-tools

apt update && apt upgrade -y

# 安装 Python 和 pip
apt install -y python3 python3-pip python3-venv

# 安装 Git（如果需要）
apt install -y git

# 创建工作目录
mkdir -p /opt/vpl-backend
cd /opt/vpl-backend

requirements.txt 内容（如果 Cline 没生成，手动创建）：
fastapi==0.104.1
uvicorn[standard]==0.24.0
sqlalchemy==2.0.23
pydantic==2.5.0
pydantic-settings==2.1.0
python-dotenv==1.0.0
paramiko==3.4.0
websockets==12.0
python-multipart==0.0.6
pip install -r requirements.txt

vim /opt/vpl-backend/.env
内容：
# 后端配置
HOST=0.0.0.0
PORT=8000
DATABASE_URL=sqlite:///./data/projects.db

# SSH 默认配置（部署用）
VM_HOST=192.168.x.x # 改为你的虚拟机IP
VM_PORT=22
VM_USERNAME=root
VM_PASSWORD=你的密码
VM_PATH=/opt/executor

#给文件权限
chmod 777 /data/projects.db
chmod 777 /data

# 安装依赖
pip install --upgrade pip
pip install fastapi uvicorn[standard] sqlalchemy pydantic python-dotenv \
paramiko websockets python-multipart aiosqlite asyncssh passlib bcrypt pyjwt \
-i https://pypi.tuna.tsinghua.edu.cn/simple
python3 -m venv venv
source venv/bin/activate
pip install pyjwt
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

# 安装 screen
apt install -y screen

# 启动 screen 会话
screen -S backend

# 在 screen 中启动后端
cd /opt/vpl-backend
source venv/bin/activate
uvicorn app.main:app --host 0.0.0.0 --port 8000

# 按 Ctrl+A+D 退出 screen（后端继续运行）

# 查看运行中的后端
screen -r backend

#暴露后端公网
curl -fsSL "https://natapp.cn/get.sh?authtoken=1e938187ee5adb67" | sh #1e938187ee5adb67 <你的token>
cd /opt/natapp
./run_natapp.sh

#git仓库配置
git config --global user.name "wuxiao"
git config --global user.email "13032540+wu-xiao111@user.noreply.gitee.com"
# 查看配置是否生效
git config --global --list

ssh-keygen -t ed25519 -C "13032540+wu-xiao111@user.noreply.gitee.com"
git remote add origin git@gitee.com:wu-xiao111/mishi.git

# 基于当前已推送成功的master，新建dev分支并切换过去
git checkout -b dev
# 推送提交
git push origin dev

git checkout master
git pull origin master
# 将dev合并到master
git merge dev
git push origin master

1框架设计

mishi/
├── backend/ # 后端服务（Python / FastAPI）
│ ├── requirements.txt # Python 依赖包列表（FastAPI、SQLAlchemy、asyncssh等）
│ ├── app/
│ │ ├── main.py # 应用入口 - 创建 FastAPI 实例、注册路由、CORS配置、健康检查
│ │ │
│ │ ├── api/ # HTTP API 接口层
│ │ │ ├── __init__.py # API 包初始化
│ │ │ ├── auth.py # 用户认证 API - 注册、登录、JWT 令牌、获取用户信息、种子root用户
│ │ │ ├── projects.py # 项目管理 API - 项目的增删改查（基于 JSON 文件存储）
│ │ │ ├── compile.py # 编译 API - 接收前端流程图配置→校验→生成Python代码→保存到服务器
│ │ │ └── deploy.py # 部署 API - 通过 SSH 将编译代码上传到目标设备并执行、WebSocket 实时日志
│ │ │
│ │ ├── models/ # 数据库数据模型层（SQLAlchemy ORM + SQLite）
│ │ │ ├── __init__.py # 数据模型包 - 导出 Project、Base
│ │ │ ├── project.py # 项目数据模型 ORM - 定义 Project 表结构、数据库引擎与会话管理
│ │ │ └── user.py # 用户数据模型 ORM - 定义 User 表结构、密码哈希与验证方法
│ │ │
│ │ ├── schemas/ # Pydantic 数据校验模型（请求/响应结构定义）
│ │ │ ├── __init__.py # Schema 包初始化
│ │ │ ├── auth_schema.py # 认证相关 Schema - RegisterRequest、LoginRequest、UserResponse 等
│ │ │ └── project_schema.py # 项目/编译/部署相关 Schema - CompileRequest、DeployRequest 等
│ │ │
│ │ ├── compiler/ # 编译引擎（流程图→Python代码）
│ │ │ ├── __init__.py # 编译器包初始化
│ │ │ ├── validator.py # 逻辑校验器 - 环路检测、空悬连线检查、重复ID检测、类型兼容性检查
│ │ │ └── generator.py # 代码生成器 - 拓扑排序节点，将 JSON 配置转换为可执行的 Python 脚本
│ │ │
│ │ └── deploy/ # 部署引擎（SSH远程执行）
│ │ ├── __init__.py # 部署包初始化
│ │ ├── ssh_client.py # SSH 客户端 - 异步 SSH 连接管理、远程命令执行、连接检测
│ │ ├── file_transfer.py # 文件传输模块 - 通过 SSH 上传文件到目标设备、远程程序启停
│ │ └── executor.py # 远程执行器 - 代码上传+语法检查+远程执行+日志获取 的高层封装
│ │
│ └── data/ # 数据持久化目录（运行时自动创建）
│ ├── projects.json # 项目数据存储文件（JSON 格式）
│ └── users.json # 用户数据存储文件（JSON 格式）
│
├── frontend/ # 前端应用（React + TypeScript + Vite）
│ ├── index.html # HTML 入口 - 挂载 React 应用的根页面
│ ├── package.json # 前端依赖配置（React、Ant Design、ReactFlow、Zustand 等）
│ ├── package-lock.json # 依赖锁定文件
│ ├── tsconfig.json # TypeScript 编译配置 - 目标 ES2020、React JSX、严格模式
│ ├── tsconfig.node.json # Vite 的 TypeScript 配置文件引用
│ ├── vite.config.ts # Vite 构建配置 - React 插件、开发服务器端口3000、API 代理
│ │
│ └── src/ # 前端源码
│ ├── main.tsx # 应用入口 - 渲染 React 根组件 <App /> 到 DOM
│ ├── App.tsx # 应用主组件 - React Router 路由配置、登录状态恢复、拖拽上下文提供
│ ├── index.css # 全局样式 - CSS 变量、ReactFlow 样式覆盖、自定义节点样式
│ │
│ ├── types/
│ │ └── index.ts # 集中类型定义 - ModulePort、FlowNodeData、CompileResult、DeployConfig 等
│ │
│ ├── utils/
│ │ ├── api.ts # API 工具函数 - 封装 fetch 请求、自动添加 JWT 令牌、authApi / projectApi
│ │ └── relayMapper.ts # 继电器端口映射工具 - 1000个逻辑端口↔125个芯片的地址映射算法
│ │
│ ├── stores/ # Zustand 状态管理
│ │ ├── useAuthStore.ts # 认证状态 - token、用户信息、登录/登出、会话恢复
│ │ ├── useFlowStore.ts # 流程图状态 - 节点/连线CRUD、拓扑排序、JSON导出
│ │ └── levelStore.ts # 分区状态 - 管理4个分区的独立流程图数据（编译时合并）
│ │
│ ├── api/ # API 调用封装层
│ │ ├── compile.ts # 编译 API - compileProject、listGeneratedFiles、downloadFile
│ │ └── deploy.ts # 部署 API - deployToDevice、getDeploymentRecords、getDeploymentLogs
│ │
│ ├── data/ # 模块分类数据（一级分类 + 二级模块定义）
│ │ ├── modules.ts # 模块分类主索引 - 汇总所有16个一级分类的配置数据
│ │ └── categories/
│ │ ├── audio.ts # 🎵 声音输出类 - 蜂鸣器、扬声器、MP3播放、语音合成
│ │ ├── auxiliary.ts # 🔧 特殊辅助类 - 时间戳、看门狗、调试输出
│ │ ├── communication.ts # 📡 通信互联类 - 串口、I2C、SPI、蓝牙、WiFi、LoRa 等
│ │ ├── controlFlow.ts # 🔄 控制流 - 开始、结束等程序结构标记
│ │ ├── display.ts # 🖥️ 输出显示类 - LED、灯带、数码管、OLED、LCD 等
│ │ ├── execution.ts # 📋 执行流程类 - 顺序、并行、分支、循环、子程序
│ │ ├── interaction.ts # 👤 用户交互类 - 按键、触摸、摇杆、指纹、二维码扫描等
│ │ ├── logic.ts # 🧠 逻辑控制类 - 与或非门、锁存器、触发器、比较器
│ │ ├── math.ts # 🔢 数学运算类 - 加减乘除、取模、随机数、滤波器
│ │ ├── motor.ts # ⚡ 动力输出类 - 直流电机、步进电机、伺服电机、风扇
│ │ ├── power.ts # 🔌 电源控制类 - 继电器、可控硅、电源开关、电压检测
│ │ ├── props.ts # 🛠️ 互动道具类 - 推杆、电磁铁、烟雾机、转盘
│ │ ├── security.ts # 🔒 安防报警类 - 门磁、烟雾报警、电控锁
│ │ ├── sensor.ts # 📊 输入检测类 - 红外、霍尔、超声波、温湿度、气体等传感器
│ │ ├── signalTrigger.ts # 📶 信号触发 - 遥控/信号触发占位符
│ │ └── timing.ts # ⏱️ 时序控制类 - 延时器、定时器、计数器、时钟触发
│ │
│ ├── pages/ # 页面级组件
│ │ ├── LoginPage.tsx # 登录/注册页面 - 表单验证、JWT 认证、跳转项目管理
│ │ ├── ProjectListPage.tsx # 项目列表页面 - 本地项目(localStorage)+云端项目、新建/导入/删除/搜索
│ │ └── EditorPage.tsx # 编辑器页面 - 组装工具栏+分区标签+模块面板+流程图+属性面板
│ │
│ └── components/ # UI 组件
│ ├── Toolbar/
│ │ ├── index.tsx # 顶部工具栏 - 新建/保存/导入/编译/部署/清空、用户信息、模块统计
│ │ └── CompileResultModal.tsx # 编译结果弹窗 - 成功时显示代码、失败时显示错误详情
│ │
│ ├── LevelTabs/
│ │ └── index.tsx # 分区切换标签 - 分区1~4，切换时自动保存/加载流程图数据
│ │
│ ├── NodePalette/
│ │ └── index.tsx # 左侧模块面板 - 一级分类菜单（可折叠）+ 可拖拽的二级模块列表
│ │
│ ├── FlowEditor/
│ │ ├── index.tsx # 中央流程图编辑区 - 基于 ReactFlow，支持拖拽、连线、缩放、小地图
│ │ └── CustomNode.tsx # 自定义流程图节点 - 继电器/延时/通用三种节点样式渲染
│ │
│ ├── PropertyPanel/
│ │ └── index.tsx # 右侧属性面板 - 选中模块的参数编辑（数值/开关/选择/滑块）、删除
│ │
│ └── DeployModal/
│ └── index.tsx # 部署配置弹窗 - 设备预设（虚拟机/树莓派/自定义）、SSH 连接信息表单

2联合开发环境配置

用方案1 Gitea + Gerrit.

3数据流

前端流程图 (React Flow)
↓
导出 JSON 配置
↓
发送到后端 API (/api/compile)
↓
后端编译器 (compiler/generator.py)
↓
生成 Python 可执行脚本
↓
通过 SSH 部署到虚拟机执行

4AI视频流处理

单 / 2 路摄像头、树莓派边缘部署：RTSP+OpenCV+YOLO 本地 AI，不用外网、不上传画面、无隐私风险； 多路商用密室、需要稳定告警：海康 SDK 取流，低延迟、断线自动重连。

5后端部署

5.1 在虚拟机中准备环境

# 更新系统
apt update && apt upgrade -y

# 安装 Python 和 pip
apt install -y python3 python3-pip python3-venv

# 安装 Git（如果需要）
apt install -y git

# 创建工作目录
mkdir -p /opt/vpl-backend
cd /opt/vpl-backend
2.2 上传后端代码到虚拟机
方式一：使用 scp（本地直接上传）
# 在本地电脑执行（不是虚拟机）
scp -r ./backend/* root@你的虚拟机IP:/opt/vpl-backend/
方式二：使用 WinSCP/FileZilla
打开 WinSCP

连接你的虚拟机（IP、用户名、密码）

将本地 backend/ 文件夹拖拽到 /opt/vpl-backend/

安装 Python 依赖
cd /opt/vpl-backend

# 创建虚拟环境（推荐）
python3 -m venv venv
source venv/bin/activate

# 安装依赖
pip install -r requirements.txt
requirements.txt 内容（如果 Cline 没生成，手动创建）：
fastapi==0.104.1
uvicorn[standard]==0.24.0
sqlalchemy==2.0.23
pydantic==2.5.0
pydantic-settings==2.1.0
python-dotenv==1.0.0
paramiko==3.4.0
websockets==12.0
python-multipart==0.0.6

5.2 配置环境变量

创建 .env 文件：

vim /opt/vpl-backend/.env
内容：
# 后端配置
HOST=0.0.0.0
PORT=8000
DATABASE_URL=sqlite:///./data/projects.db

# SSH 默认配置（部署用）
VM_HOST=192.168.x.x # 改为你的虚拟机IP
VM_PORT=22
VM_USERNAME=root
VM_PASSWORD=你的密码
VM_PATH=/opt/executor

给文件权限：

chmod 777 /data/projects.db

chmod 777 /data

5.3 启动后端服务

cd /opt/vpl-backend
source venv/bin/activate
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
看到以下输出表示成功：
INFO: Started server process
INFO: Waiting for application startup.
INFO: Application startup complete.
INFO: Uvicorn running on http://0.0.0.0:8000
验证：在虚拟机浏览器访问 http://localhost:8000/docs，能看到 Swagger API 文档。

5.4 保持后端持续运行（使用 screen）

# 安装 screen
apt install -y screen

# 启动 screen 会话
screen -S backend

# 在 screen 中启动后端
cd /opt/vpl-backend
source venv/bin/activate
uvicorn app.main:app --host 0.0.0.0 --port 8000

# 按 Ctrl+A+D 退出 screen（后端继续运行）

# 查看运行中的后端
screen -r backend

🌐第三步：暴露后端到公网（ngrok）

备选方案：

cd /opt/natapp ./opt/natapp/run_natapp.sh

3.1 安装 ngrok

# 下载 ngrok
wget https://bin.equinox.io/c/4VmDzA7iaHb/ngrok-stable-linux-amd64.zip
unzip ngrok-stable-linux-amd64.zip
sudo mv ngrok /usr/local/bin/

# 验证安装
ngrok --version
3.2 注册并获取 Auth Token
访问 https://ngrok.com 注册账号

在 Dashboard 获取你的 Auth Token

在虚拟机中配置：

bash
复制
下载
ngrok config add-authtoken 你的token
3.3 暴露后端服务
bash
复制
下载
# 在虚拟机中启动 ngrok（另开一个 screen）
screen -S ngrok
ngrok http 8000
看到输出：

text
复制
下载
Forwarding https://xxxx.ngrok.io -> http://localhost:8000
记住这个 https://xxxx.ngrok.io 地址，前端需要用到。

按 Ctrl+A+D 退出 screen。

📋 第四步：修改前端 API 地址
4.1 找到前端 API 配置文件
在 frontend/src/ 目录下，找到 API 配置文件（通常是 src/config/index.ts 或 src/api/request.ts）。

4.2 修改为 ngrok 地址
typescript
复制
下载
// 原来
// export const API_BASE_URL = 'http://localhost:8000'

// 改成 ngrok 地址
export const API_BASE_URL = 'https://xxxx.ngrok.io' // 替换为你的 ngrok 地址

4.3 重新打包前端

重启后端 cd /opt/vpl-backend source venv/bin/activate uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

编译前端打包
cd frontend
npm run build
上传到阿里云

scp -r ./dist/* root@123.57.224.65:/var/www/html/
📊 完整架构图

┌─────────────────────────────────────────────────────────────┐
│ 用户浏览器 │
│ 访问 http://123.57.224.65/ │
└─────────────────────────┬───────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 阿里云服务器 (前端) │
│ Nginx 托管静态文件 │
│ 前端调用 ngrok 地址访问后端 │
└─────────────────────────┬───────────────────────────────────┘
│
│ HTTPS (公网)
▼
┌─────────────────────────────────────────────────────────────┐
│ ngrok 内网穿透 │
│ https://xxxx.ngrok.io │
└─────────────────────────┬───────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 本地虚拟机 (后端) │
│ FastAPI :8000 │
│ 编译 + SSH 部署 │
└─────────────────────────┬───────────────────────────────────┘
│
│ SSH (内网)
▼
┌─────────────────────────────────────────────────────────────┐
│ 本地虚拟机 (执行器) │
│ /opt/executor/main.py │
│ 运行生成的程序 │
└─────────────────────────────────────────────────────────────┘

6映射架构：从前端模块到物理继电器

整个对应关系可以分为三层，形成一个清晰的映射表：

层级 描述 示例
1. 逻辑模块层 前端画布上的一个“继电器”节点，是用户操作的单元-4。 继电器1-1、继电器3-2
2. 物理地址层 为每个TPIC6C596芯片及其8个输出通道定义的唯一地址。 级联地址0x00 的 通道0
3. 硬件驱动层 树莓派最终执行的代码，控制真实的GPIO引脚时序，将数据位移到指定地址-7。 shift_out(芯片ID, 通道号, 状态)

7树莓派

7.1基础信息

7.2硬件接口层框架设计

8树莓派上跑模型

由于树莓派没有NPU，纯靠cpu跑性能太差，所以增加了一个 Hailo-8L ，26TPS，可以轻松处理大部分模型。

8.1YOLO模型

YOLO 模型完全可以跑在 Hailo-8L 上，而且效果非常显著，但需要走一套特定的流程，不能直接把标准 YOLO 模型放上去跑。

Hailo-8L 不是通用的 GPU，而是一个专用的 AI 加速芯片。因此，标准的 PyTorch 或 ONNX 格式的 YOLO 模型无法直接在它上面运行。你需要使用 Hailo 提供的工具链，将模型转换为其专用的.hef格式-10。而且，这个模型转换工具（Hailo Dataflow Compiler, DFC）目前不支持在树莓派上直接运行，你通常需要在一台 x86 架构的 Ubuntu 电脑上完成转换。

1. 硬件安装与系统设置

• 将 Hailo-8L 模块安装到树莓派的 M.2 HAT 上-5。

• 确保使用官方电源，保证供电稳定-5。

• 更新系统固件（sudo rpi-eeprom-update），确保固件日期晚于2023年12月6日-8-12。

• 进入raspi-config，在 “Advanced Options” 中将PCIe Speed设置为Gen 3模式，以获得最佳性能-2-5-9。

2. 安装 Hailo 软件栈

• 在树莓派终端执行以下命令，这会一次性安装驱动程序、运行时库（HailoRT）和开发框架（TAPPAS）-2-5-8：

  sudo apt install hailo-all sudo reboot

• 重启后，通过以下命令验证硬件和驱动是否安装成功：

  hailortcli fw-control identify

  如果成功，你会看到关于 Hailo-8L 芯片的详细信息-2-5。

3. 准备并运行 YOLO 模型
这是最核心的一步，因为你需要一个 Hailo 专用的 YOLO 模型文件（.hef格式）。

• 使用官方示例（最简单）：树莓派官方提供了一些示例 JSON 配置文件（如hailo_yolov6_inference.json），可以配合rpicam-apps直接调用。克隆官方仓库后，运行类似下面的命令即可体验-8-11-12：

  rpicam-hello -t 0 --post-process-file ~/rpicam-apps/assets/hailo_yolov6_inference.json --lores-width 640 --lores-height 640

• 转换自己的 YOLO 模型：如果你想运行自己的 YOLOv8 或 YOLOv11 模型，你需要遵循一个标准的转换流程-10：

  1. 导出 ONNX：将 PyTorch 模型导出为 ONNX 格式。

  2. 编译为 HEF：在一台 x86 的 Ubuntu 机器上，使用Hailo Dataflow Compiler (DFC)将 ONNX 模型编译成.hef文件-10。

  3. 部署推理：将生成的.hef文件复制回树莓派，然后使用 Hailo 提供的 Python 示例代码（如run.py）或基于 GStreamer 的管道来加载模型并进行推理

10遇到的问题

failed to fetch

前端IP配置错误，要配置natapp新IP，将后端IP暴露给公网

http://pa49277b.natappfree.cc

本地保存无权限

报错：

保存项目失败: (sqlite3.OperationalError) attempt to write a readonly database [SQL: INSERT INTO projects (id, name, description, data, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?)] [parameters: ('5cfa59e2-cda4-4e2d-9e6c-1c75b95f0dd6', 'wuxiao', '', '{"nodes":[],"edges":[]}', '2026-07-10 15:55:07.767639', '2026-07-10 15:55:07.767643')] (Background on this error at: https://sqlalche.me/e/20/e3q8)

修改：

# 进入后端项目目录 cd /opt/vpl-backend # 查找 .db 文件 find . -name "*.db"

位于data/目录下。

chmod 给权限./data/projects.db"

重启后端即可。

uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

GPIO点不亮

RPi.GPIO 不支持树莓派 5 改用 gpiozero