929 lines
35 KiB
Markdown
929 lines
35 KiB
Markdown
|
# 边缘智能终端模型同步功能设计
|
|||
|
|
|
|||
|
|
## 一、概述
|
|||
|
|
|
|||
|
|
### 1.1 系统架构
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
┌──────────────────────────────────────────────────────────────────┐
|
|||
|
|
│ 云端服务器 (Cloud) │
|
|||
|
|
│ ┌──────────┐ ┌────────────┐ ┌───────────┐ ┌──────────────┐ │
|
|||
|
|
│ │ 认证服务 │ │ 心跳服务 │ │ 版本管理 │ │ 模型下载服务 │ │
|
|||
|
|
│ │ (Token) │ │ (Heartbeat)│ │ (Version) │ │ (Download) │ │
|
|||
|
|
│ └────┬─────┘ └─────┬──────┘ └─────┬─────┘ └──────┬───────┘ │
|
|||
|
|
│ │ │ │ │ │
|
|||
|
|
│ ┌────┴──────────────┴───────────────┴───────────────┴──────┐ │
|
|||
|
|
│ │ REST API + WebSocket │ │
|
|||
|
|
│ └──────────────────────────┬───────────────────────────────┘ │
|
|||
|
|
│ │ │
|
|||
|
|
│ ┌──────────────────────────┴───────────────────────────────┐ │
|
|||
|
|
│ │ Django REST Framework + Channels (ASGI) │ │
|
|||
|
|
│ │ MinIO 对象存储 (archived-model / trained-model) │ │
|
|||
|
|
│ └──────────────────────────────────────────────────────────┘ │
|
|||
|
|
└──────────────────────────────────────────────────────────────────┘
|
|||
|
|
│
|
|||
|
|
HTTPS / WSS（公网/内网）
|
|||
|
|
│
|
|||
|
|
┌─────────────────────────────┴────────────────────────────────────┐
|
|||
|
|
│ 边缘智能终端 (Edge Device) │
|
|||
|
|
│ ┌──────────┐ ┌────────────┐ ┌───────────┐ ┌──────────────┐ │
|
|||
|
|
│ │ Token管理 │ │ 心跳上报 │ │ 版本检查 │ │ 模型下载更新 │ │
|
|||
|
|
│ │ (每日刷新)│ │ (30s/次) │ │ (定时轮询) │ │ (差量更新) │ │
|
|||
|
|
│ └──────────┘ └────────────┘ └───────────┘ └──────────────┘ │
|
|||
|
|
│ │
|
|||
|
|
│ ┌──────────────────────────────────────────────────────────┐ │
|
|||
|
|
│ │ Edge Runtime (Python 模拟程序 / 边缘盒子固件) │ │
|
|||
|
|
│ │ 本地模型目录: /opt/edge/models/ │ │
|
|||
|
|
│ │ 本地配置目录: /opt/edge/config/ │ │
|
|||
|
|
│ └──────────────────────────────────────────────────────────┘ │
|
|||
|
|
└──────────────────────────────────────────────────────────────────┘
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 1.2 核心数据模型
|
|||
|
|
|
|||
|
|
基于已有数据表 `ai_smart_terminal`，核心字段如下：
|
|||
|
|
|
|||
|
|
| 字段 | 类型 | 说明 |
|
|||
|
|
|------|------|------|
|
|||
|
|
| `stcd` | CharField(40) | 终端唯一编码，边缘设备与云端一一对应 |
|
|||
|
|
| `stnm` | CharField(255) | 终端名称 |
|
|||
|
|
| `model_id` | CharField(40) | 已部署模型ID（关联 AiAlgorithmModels） |
|
|||
|
|
| `model_name` | CharField(200) | 已部署模型文件名 |
|
|||
|
|
| `model_version` | CharField(64) | 云端当前发布的模型版本 |
|
|||
|
|
| `model_path` | CharField(600) | 模型文件 MinIO 存储路径 |
|
|||
|
|
| `model_publish_time` | DateTimeField | 模型发布时间 |
|
|||
|
|
| `edge_model_version` | CharField(64) | 边缘端当前运行的模型版本 |
|
|||
|
|
| `edge_update_time` | DateTimeField | 边缘端最后一次模型更新时间 |
|
|||
|
|
| `last_heartbeat_time` | DateTimeField | 边缘端最后心跳时间 |
|
|||
|
|
| `online_status` | SmallIntegerField | 在线状态：0=离线 1=在线 |
|
|||
|
|
| `sync_check_interval` | IntegerField | 同步检查间隔（单位：分钟） |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 二、云端服务功能设计
|
|||
|
|
|
|||
|
|
### 2.1 设备接入认证（Token 生成）
|
|||
|
|
|
|||
|
|
**接口**: `POST /server/terminal/auth/`
|
|||
|
|
|
|||
|
|
**功能说明**:
|
|||
|
|
- 边缘设备使用设备编码（stcd）向云端申请认证 Token
|
|||
|
|
- Token 有效期 1 天（24小时），基于 JWT 机制
|
|||
|
|
- Token 中携带 `stcd` ，区别于用户 Token
|
|||
|
|
|
|||
|
|
**请求参数**:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"stcd": "DEVICE001"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**响应示例**:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"code": 200,
|
|||
|
|
"data": {
|
|||
|
|
"access_token": "eyJhbGciOiJIUzI1NiIs...",
|
|||
|
|
"token_type": "bearer",
|
|||
|
|
"expires_in": 86400,
|
|||
|
|
"stcd": "DEVICE001"
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**认证中间件**:
|
|||
|
|
- 所有边缘设备 API 使用 `EdgeDeviceAuthentication` 认证类
|
|||
|
|
- 验证 Token 中的 `stcd` 与请求参数/URL 中的 `stcd` 一致
|
|||
|
|
- Token 过期返回 401，设备端触发重新认证流程
|
|||
|
|
|
|||
|
|
**JWT Token 生成逻辑**:
|
|||
|
|
```python
|
|||
|
|
from rest_framework_simplejwt.tokens import AccessToken
|
|||
|
|
from datetime import timedelta
|
|||
|
|
|
|||
|
|
def generate_device_token(stcd: str) -> str:
|
|||
|
|
token = AccessToken()
|
|||
|
|
token['stcd'] = stcd
|
|||
|
|
token['type'] = 'device'
|
|||
|
|
token.set_exp(lifetime=timedelta(days=1))
|
|||
|
|
return str(token)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 2.2 心跳时间更新
|
|||
|
|
|
|||
|
|
**接口**: `PUT /server/terminal/heartbeat/`（已有，需增强认证）
|
|||
|
|
|
|||
|
|
**功能说明**:
|
|||
|
|
- 边缘设备定时调用（建议 30 秒/次）
|
|||
|
|
- 更新 `last_heartbeat_time` 为当前时间
|
|||
|
|
- 更新 `online_status` 为 1（在线）
|
|||
|
|
- 若设备首次接入，同时设置 `dtin=1` 和 `dtin_tm`
|
|||
|
|
|
|||
|
|
**请求参数**:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"stcd": "DEVICE001"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**请求头**:
|
|||
|
|
```
|
|||
|
|
Authorization: Bearer <device_token>
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**响应示例**:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"code": 200,
|
|||
|
|
"data": {
|
|||
|
|
"stcd": "DEVICE001",
|
|||
|
|
"last_heartbeat_time": "2026-07-25T15:30:00Z",
|
|||
|
|
"online_status": 1
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 2.3 离线状态检测（定时任务）
|
|||
|
|
|
|||
|
|
**实现方式**: Django Management Command + Celery Beat / APScheduler / 系统 Cron
|
|||
|
|
|
|||
|
|
**执行频率**: 每 30 秒执行一次
|
|||
|
|
|
|||
|
|
**检测逻辑**:
|
|||
|
|
1. 查询所有 `online_status=1` 且 `last_heartbeat_time` 不为空的终端
|
|||
|
|
2. 计算 `now() - last_heartbeat_time`
|
|||
|
|
3. 若差值 > 5 分钟（300秒），则将 `online_status` 更新为 0
|
|||
|
|
4. 通过 WebSocket 向前端管理页面推送离线通知
|
|||
|
|
|
|||
|
|
**核心代码逻辑**:
|
|||
|
|
```python
|
|||
|
|
# management/commands/check_terminal_offline.py
|
|||
|
|
from django.core.management.base import BaseCommand
|
|||
|
|
from django.utils.timezone import now
|
|||
|
|
from datetime import timedelta
|
|||
|
|
from apps.core.models import AiSmartTerminal
|
|||
|
|
from asgiref.sync import async_to_sync
|
|||
|
|
from channels.layers import get_channel_layer
|
|||
|
|
|
|||
|
|
|
|||
|
|
class Command(BaseCommand):
|
|||
|
|
help = '检测超时心跳的终端并标记为离线'
|
|||
|
|
|
|||
|
|
def handle(self, *args, **options):
|
|||
|
|
threshold = now() - timedelta(minutes=5)
|
|||
|
|
offline_terminals = AiSmartTerminal.objects.filter(
|
|||
|
|
online_status=1,
|
|||
|
|
last_heartbeat_time__lt=threshold,
|
|||
|
|
)
|
|||
|
|
count = offline_terminals.update(online_status=0)
|
|||
|
|
|
|||
|
|
if count > 0:
|
|||
|
|
# WebSocket 推送离线通知到前端
|
|||
|
|
channel_layer = get_channel_layer()
|
|||
|
|
offline_list = list(
|
|||
|
|
offline_terminals.values('stcd', 'stnm')
|
|||
|
|
)
|
|||
|
|
async_to_sync(channel_layer.group_send)(
|
|||
|
|
"terminal_status",
|
|||
|
|
{
|
|||
|
|
"type": "terminal.status",
|
|||
|
|
"data": {
|
|||
|
|
"event": "offline",
|
|||
|
|
"count": count,
|
|||
|
|
"terminals": offline_list,
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
)
|
|||
|
|
self.stdout.write(f"标记 {count} 个终端为离线")
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**WebSocket 前端订阅**:
|
|||
|
|
- 前端管理页面连接 WebSocket: `ws://host/ws/terminal/status/`
|
|||
|
|
- 收到 `online_status=0` 消息时，实时更新终端列表中的在线状态标识
|
|||
|
|
- 可触达前端消息提示（如 ElNotification）
|
|||
|
|
|
|||
|
|
### 2.4 模型版本检查
|
|||
|
|
|
|||
|
|
**接口**: `GET /server/terminal/checkVersion/`
|
|||
|
|
|
|||
|
|
**功能说明**:
|
|||
|
|
- 边缘设备定期调用，检查云端是否有新版本模型
|
|||
|
|
- 对比 `edge_model_version`（边缘当前版本）与 `model_version`（云端发布版本）
|
|||
|
|
- 返回是否需要更新
|
|||
|
|
|
|||
|
|
**请求参数**:
|
|||
|
|
```
|
|||
|
|
GET /server/terminal/checkVersion/?stcd=DEVICE001&edge_version=v1.0
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**响应示例（有新版本）**:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"code": 200,
|
|||
|
|
"data": {
|
|||
|
|
"having_newmodel": 1,
|
|||
|
|
"model_name": "model-001.onnx",
|
|||
|
|
"model_version": "v2.0",
|
|||
|
|
"model_publish_time": "2026-07-25T12:00:00Z",
|
|||
|
|
"sync_check_interval": 30
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**响应示例（已是最新）**:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"code": 200,
|
|||
|
|
"data": {
|
|||
|
|
"having_newmodel": 0,
|
|||
|
|
"model_version": "v1.0",
|
|||
|
|
"sync_check_interval": 30
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**版本对比逻辑**:
|
|||
|
|
- 若 `edge_model_version` 为空（首次同步），`having_newmodel=1`
|
|||
|
|
- 若 `edge_model_version != model_version`，`having_newmodel=1`
|
|||
|
|
- 若 `edge_model_version == model_version`，`having_newmodel=0`
|
|||
|
|
- 返回 `sync_check_interval` 供边缘端动态调整检查频率
|
|||
|
|
|
|||
|
|
### 2.5 模型下载
|
|||
|
|
|
|||
|
|
**接口**: `GET /server/terminal/downloadModel/`（已有，需增强）
|
|||
|
|
|
|||
|
|
**功能说明**:
|
|||
|
|
- 边缘设备下载最新 ONNX 模型文件
|
|||
|
|
- 支持断点续传（通过 Range 请求头）
|
|||
|
|
- 返回文件流，`Content-Disposition` 包含文件名
|
|||
|
|
- 下载完成后，边缘端调用回调接口更新 `edge_model_version` 和 `edge_update_time`
|
|||
|
|
|
|||
|
|
**请求参数**:
|
|||
|
|
```
|
|||
|
|
GET /server/terminal/downloadModel/?stcd=DEVICE001&format=onnx
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**请求头**:
|
|||
|
|
```
|
|||
|
|
Authorization: Bearer <device_token>
|
|||
|
|
Range: bytes=0-1048576 （可选，断点续传）
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**响应**:
|
|||
|
|
```
|
|||
|
|
HTTP/1.1 200 OK
|
|||
|
|
Content-Type: application/octet-stream
|
|||
|
|
Content-Disposition: attachment; filename="model-001.onnx"
|
|||
|
|
Content-Length: 10485760
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**下载完成回调接口**: `PUT /server/terminal/updateModelVersion/`
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"stcd": "DEVICE001",
|
|||
|
|
"edge_model_version": "v2.0"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 三、边缘设备端设计（模拟程序）
|
|||
|
|
|
|||
|
|
### 3.1 目录结构
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
edge_simulator/
|
|||
|
|
├── config/
|
|||
|
|
│ ├── config.json # 配置文件（设备编码、云端地址等）
|
|||
|
|
│ └── token.json # 缓存的认证 Token
|
|||
|
|
├── models/ # 模型存储目录
|
|||
|
|
│ ├── current/ # 当前运行模型
|
|||
|
|
│ └── backup/ # 历史版本备份
|
|||
|
|
├── logs/
|
|||
|
|
│ └── edge.log
|
|||
|
|
├── main.py # 主入口，调度各模块
|
|||
|
|
├── auth.py # Token 管理与刷新
|
|||
|
|
├── heartbeat.py # 心跳上报模块
|
|||
|
|
├── version_check.py # 版本检查与下载
|
|||
|
|
└── requirements.txt
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 3.2 配置文件 (config/config.json)
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"stcd": "DEVICE001",
|
|||
|
|
"cloud_base_url": "http://192.168.1.60:8000",
|
|||
|
|
"heartbeat_interval_sec": 30,
|
|||
|
|
"version_check_interval_min": null,
|
|||
|
|
"model_dir": "./models/current",
|
|||
|
|
"backup_dir": "./models/backup",
|
|||
|
|
"token_file": "./config/token.json",
|
|||
|
|
"log_level": "INFO",
|
|||
|
|
"retry_count": 3,
|
|||
|
|
"retry_delay_sec": 5
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 3.3 模块详细设计
|
|||
|
|
|
|||
|
|
#### 3.3.1 Token 管理模块 (auth.py)
|
|||
|
|
|
|||
|
|
**功能**:
|
|||
|
|
- 每日定时获取新 Token（每天 00:00:00 执行）
|
|||
|
|
- 首次启动时立即获取 Token
|
|||
|
|
- 缓存 Token 到本地文件，记录过期时间
|
|||
|
|
- 每次 API 调用前检查 Token 是否有效
|
|||
|
|
|
|||
|
|
**流程**:
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
开始
|
|||
|
|
│
|
|||
|
|
├── 检查本地 token.json 是否存在
|
|||
|
|
│ ├── 存在 → 检查是否过期
|
|||
|
|
│ │ ├── 未过期 → 直接使用
|
|||
|
|
│ │ └── 已过期 → 调用认证接口获取新 Token
|
|||
|
|
│ └── 不存在 → 调用认证接口获取新 Token
|
|||
|
|
│
|
|||
|
|
└── 保存 Token 到 token.json
|
|||
|
|
└── 记录 expires_at 时间戳
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**token.json 格式**:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"access_token": "eyJhbGciOiJIUzI1NiIs...",
|
|||
|
|
"token_type": "bearer",
|
|||
|
|
"expires_at": "2026-07-26T00:00:00Z",
|
|||
|
|
"stcd": "DEVICE001"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### 3.3.2 心跳上报模块 (heartbeat.py)
|
|||
|
|
|
|||
|
|
**功能**:
|
|||
|
|
- 定时 30 秒调用云端心跳接口
|
|||
|
|
- 携带设备 Token 进行认证
|
|||
|
|
- 失败重试 3 次（间隔 2 秒）
|
|||
|
|
- 记录心跳日志
|
|||
|
|
|
|||
|
|
**流程**:
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
定时触发 (每30秒)
|
|||
|
|
│
|
|||
|
|
├── 获取本地 Token
|
|||
|
|
├── PUT /server/terminal/heartbeat/
|
|||
|
|
│ Headers: Authorization: Bearer <token>
|
|||
|
|
│ Body: {"stcd": "DEVICE001"}
|
|||
|
|
│
|
|||
|
|
├── 响应码 = 200 → 成功，记录日志
|
|||
|
|
├── 响应码 = 401 → Token 过期，触发 Token 刷新 → 重试
|
|||
|
|
├── 响应码 = 其他 / 超时 → 重试（最多3次）
|
|||
|
|
│
|
|||
|
|
└── 3次失败 → 记录错误日志，等待下次触发
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### 3.3.3 版本检查与模型下载模块 (version_check.py)
|
|||
|
|
|
|||
|
|
**功能**:
|
|||
|
|
- 根据 `sync_check_interval` 定时检查云端模型版本
|
|||
|
|
- 若有新版本，下载模型文件到本地（支持断点续传）
|
|||
|
|
- 验证下载文件的 MD5/SHA256 完整性
|
|||
|
|
- 备份旧版本模型
|
|||
|
|
- 更新 `edge_model_version` 到云端
|
|||
|
|
|
|||
|
|
**流程**:
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
定时触发 (根据 sync_check_interval，默认从云端获取)
|
|||
|
|
│
|
|||
|
|
├── 读取本地当前模型版本 (从本地 version.txt)
|
|||
|
|
├── GET /server/terminal/checkVersion/
|
|||
|
|
│ ?stcd=DEVICE001
|
|||
|
|
│ &edge_version=v1.0
|
|||
|
|
│
|
|||
|
|
├── 响应 having_newmodel = 0 → 无更新，等待下次检查
|
|||
|
|
│
|
|||
|
|
├── 响应 having_newmodel = 1
|
|||
|
|
│ │
|
|||
|
|
│ ├── 更新本地 sync_check_interval
|
|||
|
|
│ │
|
|||
|
|
│ ├── 备份旧模型: models/current/ → models/backup/model-{version}/
|
|||
|
|
│ │
|
|||
|
|
│ ├── GET /server/terminal/downloadModel/
|
|||
|
|
│ │ ?stcd=DEVICE001
|
|||
|
|
│ │ &format=onnx
|
|||
|
|
│ │ 支持断点续传 (Range 请求头)
|
|||
|
|
│ │
|
|||
|
|
│ ├── 下载完成 → 验证文件完整性
|
|||
|
|
│ │ 验证方式: 响应头 X-File-SHA256 与实际文件对比
|
|||
|
|
│ │
|
|||
|
|
│ ├── 保存到 models/current/{model_filename}
|
|||
|
|
│ ├── 更新本地 version.txt
|
|||
|
|
│ │
|
|||
|
|
│ └── PUT /server/terminal/updateModelVersion/
|
|||
|
|
│ {"stcd": "DEVICE001", "edge_model_version": "v2.0"}
|
|||
|
|
│ → 更新 edge_model_version 和 edge_update_time
|
|||
|
|
│
|
|||
|
|
└── 记录更新日志
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### 3.3.4 主调度程序 (main.py)
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
"""
|
|||
|
|
边缘智能终端模拟程序 - 主入口
|
|||
|
|
"""
|
|||
|
|
import json
|
|||
|
|
import logging
|
|||
|
|
import os
|
|||
|
|
import signal
|
|||
|
|
import sys
|
|||
|
|
import threading
|
|||
|
|
import time
|
|||
|
|
from datetime import datetime
|
|||
|
|
|
|||
|
|
import requests
|
|||
|
|
|
|||
|
|
|
|||
|
|
class EdgeDeviceSimulator:
|
|||
|
|
"""边缘智能终端模拟器"""
|
|||
|
|
|
|||
|
|
def __init__(self, config_path: str = "./config/config.json"):
|
|||
|
|
self.config = self._load_config(config_path)
|
|||
|
|
self.stcd = self.config["stcd"]
|
|||
|
|
self.secret = self.config["secret"]
|
|||
|
|
self.base_url = self.config["cloud_base_url"]
|
|||
|
|
self.running = True
|
|||
|
|
|
|||
|
|
self._setup_logging()
|
|||
|
|
self._setup_signal_handlers()
|
|||
|
|
|
|||
|
|
self.token = None
|
|||
|
|
self.token_refreshed_at = None
|
|||
|
|
|
|||
|
|
self.heartbeat_interval = self.config.get("heartbeat_interval_sec", 30)
|
|||
|
|
self.version_check_interval = None # 从云端获取
|
|||
|
|
self.last_version_check = None
|
|||
|
|
|
|||
|
|
# ── 配置与日志 ──────────────────────────────
|
|||
|
|
|
|||
|
|
def _load_config(self, path: str) -> dict:
|
|||
|
|
with open(path, "r", encoding="utf-8") as f:
|
|||
|
|
return json.load(f)
|
|||
|
|
|
|||
|
|
def _setup_logging(self):
|
|||
|
|
logging.basicConfig(
|
|||
|
|
level=getattr(logging, self.config.get("log_level", "INFO")),
|
|||
|
|
format="%(asctime)s [%(levelname)s] %(message)s",
|
|||
|
|
handlers=[
|
|||
|
|
logging.FileHandler("./logs/edge.log", encoding="utf-8"),
|
|||
|
|
logging.StreamHandler(sys.stdout),
|
|||
|
|
],
|
|||
|
|
)
|
|||
|
|
self.logger = logging.getLogger("EdgeDevice")
|
|||
|
|
|
|||
|
|
def _setup_signal_handlers(self):
|
|||
|
|
signal.signal(signal.SIGINT, self._graceful_shutdown)
|
|||
|
|
signal.signal(signal.SIGTERM, self._graceful_shutdown)
|
|||
|
|
|
|||
|
|
def _graceful_shutdown(self, signum, frame):
|
|||
|
|
self.logger.info("收到退出信号，正在安全关闭...")
|
|||
|
|
self.running = False
|
|||
|
|
|
|||
|
|
# ── Token 管理 ───────────────────────────────
|
|||
|
|
|
|||
|
|
def _load_token_from_file(self) -> dict | None:
|
|||
|
|
token_file = self.config["token_file"]
|
|||
|
|
if not os.path.exists(token_file):
|
|||
|
|
return None
|
|||
|
|
with open(token_file, "r", encoding="utf-8") as f:
|
|||
|
|
data = json.load(f)
|
|||
|
|
expires_at = datetime.fromisoformat(data["expires_at"])
|
|||
|
|
if datetime.now() >= expires_at:
|
|||
|
|
self.logger.info("本地 Token 已过期")
|
|||
|
|
return None
|
|||
|
|
return data
|
|||
|
|
|
|||
|
|
def _save_token_to_file(self, token_data: dict):
|
|||
|
|
with open(self.config["token_file"], "w", encoding="utf-8") as f:
|
|||
|
|
json.dump(token_data, f, indent=2)
|
|||
|
|
|
|||
|
|
def ensure_token(self) -> str:
|
|||
|
|
"""确保 Token 有效，过期则重新获取"""
|
|||
|
|
token_data = self._load_token_from_file()
|
|||
|
|
if token_data:
|
|||
|
|
return token_data["access_token"]
|
|||
|
|
|
|||
|
|
self.logger.info("获取新的设备 Token...")
|
|||
|
|
resp = requests.post(
|
|||
|
|
f"{self.base_url}/server/terminal/auth/",
|
|||
|
|
json={"stcd": self.stcd, "secret": self.secret},
|
|||
|
|
timeout=10,
|
|||
|
|
)
|
|||
|
|
resp.raise_for_status()
|
|||
|
|
result = resp.json()
|
|||
|
|
token_data = result["data"]
|
|||
|
|
self._save_token_to_file(token_data)
|
|||
|
|
self.logger.info(f"Token 获取成功, 有效期至 {token_data['expires_at']}")
|
|||
|
|
return token_data["access_token"]
|
|||
|
|
|
|||
|
|
# ── 心跳上报 ──────────────────────────────────
|
|||
|
|
|
|||
|
|
def _send_heartbeat(self):
|
|||
|
|
"""发送一次心跳"""
|
|||
|
|
try:
|
|||
|
|
token = self.ensure_token()
|
|||
|
|
resp = requests.put(
|
|||
|
|
f"{self.base_url}/server/terminal/heartbeat/",
|
|||
|
|
json={"stcd": self.stcd},
|
|||
|
|
headers={"Authorization": f"Bearer {token}"},
|
|||
|
|
timeout=5,
|
|||
|
|
)
|
|||
|
|
if resp.status_code == 200:
|
|||
|
|
self.logger.debug("心跳上报成功")
|
|||
|
|
return True
|
|||
|
|
elif resp.status_code == 401:
|
|||
|
|
self.logger.warning("Token 认证失败，清除本地 Token 缓存")
|
|||
|
|
os.remove(self.config["token_file"])
|
|||
|
|
else:
|
|||
|
|
self.logger.warning(f"心跳上报失败: {resp.status_code}")
|
|||
|
|
except requests.RequestException as e:
|
|||
|
|
self.logger.error(f"心跳上报异常: {e}")
|
|||
|
|
return False
|
|||
|
|
|
|||
|
|
def _heartbeat_loop(self):
|
|||
|
|
"""心跳上报定时循环"""
|
|||
|
|
self.logger.info(f"心跳上报模块启动, 间隔 {self.heartbeat_interval} 秒")
|
|||
|
|
while self.running:
|
|||
|
|
self._send_heartbeat()
|
|||
|
|
time.sleep(self.heartbeat_interval)
|
|||
|
|
|
|||
|
|
# ── 版本检查与模型更新 ─────────────────────────
|
|||
|
|
|
|||
|
|
def _check_version(self) -> dict | None:
|
|||
|
|
"""检查云端模型版本"""
|
|||
|
|
local_version = self._get_local_version()
|
|||
|
|
try:
|
|||
|
|
token = self.ensure_token()
|
|||
|
|
resp = requests.get(
|
|||
|
|
f"{self.base_url}/server/terminal/checkVersion/",
|
|||
|
|
params={"stcd": self.stcd, "edge_version": local_version or ""},
|
|||
|
|
headers={"Authorization": f"Bearer {token}"},
|
|||
|
|
timeout=10,
|
|||
|
|
)
|
|||
|
|
resp.raise_for_status()
|
|||
|
|
return resp.json()["data"]
|
|||
|
|
except requests.RequestException as e:
|
|||
|
|
self.logger.error(f"版本检查失败: {e}")
|
|||
|
|
return None
|
|||
|
|
|
|||
|
|
def _get_local_version(self) -> str | None:
|
|||
|
|
"""获取本地当前运行的模型版本"""
|
|||
|
|
version_file = os.path.join(self.config["model_dir"], "version.txt")
|
|||
|
|
if os.path.exists(version_file):
|
|||
|
|
with open(version_file, "r") as f:
|
|||
|
|
return f.read().strip()
|
|||
|
|
return None
|
|||
|
|
|
|||
|
|
def _backup_current_model(self):
|
|||
|
|
"""备份当前模型"""
|
|||
|
|
model_dir = self.config["model_dir"]
|
|||
|
|
backup_dir = self.config["backup_dir"]
|
|||
|
|
local_version = self._get_local_version()
|
|||
|
|
if not os.path.exists(model_dir) or not local_version:
|
|||
|
|
return
|
|||
|
|
version_backup = os.path.join(backup_dir, f"model-{local_version}")
|
|||
|
|
os.makedirs(version_backup, exist_ok=True)
|
|||
|
|
for f in os.listdir(model_dir):
|
|||
|
|
src = os.path.join(model_dir, f)
|
|||
|
|
dst = os.path.join(version_backup, f)
|
|||
|
|
if os.path.isfile(src):
|
|||
|
|
import shutil
|
|||
|
|
shutil.copy2(src, dst)
|
|||
|
|
self.logger.info(f"旧模型已备份到 {version_backup}")
|
|||
|
|
|
|||
|
|
def _download_model(self, model_name: str) -> str | None:
|
|||
|
|
"""下载模型文件，支持断点续传"""
|
|||
|
|
model_dir = self.config["model_dir"]
|
|||
|
|
os.makedirs(model_dir, exist_ok=True)
|
|||
|
|
save_path = os.path.join(model_dir, model_name)
|
|||
|
|
|
|||
|
|
try:
|
|||
|
|
token = self.ensure_token()
|
|||
|
|
url = f"{self.base_url}/server/terminal/downloadModel/"
|
|||
|
|
params = {"stcd": self.stcd, "format": "onnx"}
|
|||
|
|
headers = {"Authorization": f"Bearer {token}"}
|
|||
|
|
|
|||
|
|
self.logger.info(f"开始下载模型: {model_name}")
|
|||
|
|
resp = requests.get(
|
|||
|
|
url, params=params, headers=headers,
|
|||
|
|
stream=True, timeout=300,
|
|||
|
|
)
|
|||
|
|
resp.raise_for_status()
|
|||
|
|
|
|||
|
|
total_size = int(resp.headers.get("Content-Length", 0))
|
|||
|
|
downloaded = 0
|
|||
|
|
with open(save_path, "wb") as f:
|
|||
|
|
for chunk in resp.iter_content(chunk_size=8192):
|
|||
|
|
f.write(chunk)
|
|||
|
|
downloaded += len(chunk)
|
|||
|
|
if total_size:
|
|||
|
|
progress = downloaded / total_size * 100
|
|||
|
|
if downloaded % (1024 * 1024 * 10) < 8192: # 每10MB打印
|
|||
|
|
self.logger.info(
|
|||
|
|
f"下载进度: {progress:.1f}% "
|
|||
|
|
f"({downloaded}/{total_size})"
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
self.logger.info(f"模型下载完成, 保存至 {save_path}")
|
|||
|
|
return save_path
|
|||
|
|
except Exception as e:
|
|||
|
|
self.logger.error(f"模型下载失败: {e}")
|
|||
|
|
return None
|
|||
|
|
|
|||
|
|
def _update_edge_version(self, new_version: str):
|
|||
|
|
"""通知云端已更新到新版本"""
|
|||
|
|
try:
|
|||
|
|
token = self.ensure_token()
|
|||
|
|
resp = requests.put(
|
|||
|
|
f"{self.base_url}/server/terminal/updateModelVersion/",
|
|||
|
|
json={"stcd": self.stcd, "edge_model_version": new_version},
|
|||
|
|
headers={"Authorization": f"Bearer {token}"},
|
|||
|
|
timeout=10,
|
|||
|
|
)
|
|||
|
|
if resp.status_code == 200:
|
|||
|
|
self.logger.info(f"边缘模型版本已更新: {new_version}")
|
|||
|
|
return True
|
|||
|
|
except Exception as e:
|
|||
|
|
self.logger.error(f"云端版本更新通知失败: {e}")
|
|||
|
|
return False
|
|||
|
|
|
|||
|
|
def _version_check_loop(self):
|
|||
|
|
"""版本检查与更新定时循环"""
|
|||
|
|
self.logger.info("版本检查模块启动")
|
|||
|
|
while self.running:
|
|||
|
|
result = self._check_version()
|
|||
|
|
if result and result.get("having_newmodel") == 1:
|
|||
|
|
model_name = result["model_name"]
|
|||
|
|
new_version = result["model_version"]
|
|||
|
|
self.logger.info(f"发现新版本: {new_version}, 模型: {model_name}")
|
|||
|
|
|
|||
|
|
# 备份旧模型
|
|||
|
|
self._backup_current_model()
|
|||
|
|
|
|||
|
|
# 下载新模型
|
|||
|
|
saved = self._download_model(model_name)
|
|||
|
|
if saved:
|
|||
|
|
# 更新本地版本记录
|
|||
|
|
version_file = os.path.join(
|
|||
|
|
self.config["model_dir"], "version.txt"
|
|||
|
|
)
|
|||
|
|
with open(version_file, "w") as f:
|
|||
|
|
f.write(new_version)
|
|||
|
|
|
|||
|
|
# 通知云端
|
|||
|
|
self._update_edge_version(new_version)
|
|||
|
|
|
|||
|
|
# 更新检查间隔
|
|||
|
|
if result.get("sync_check_interval"):
|
|||
|
|
self.version_check_interval = result["sync_check_interval"]
|
|||
|
|
|
|||
|
|
# 等待下次检查
|
|||
|
|
interval = self.version_check_interval or 60 # 默认60分钟
|
|||
|
|
self.logger.debug(f"下次版本检查: {interval} 分钟后")
|
|||
|
|
time.sleep(interval * 60)
|
|||
|
|
|
|||
|
|
# ── 主入口 ────────────────────────────────────
|
|||
|
|
|
|||
|
|
def run(self):
|
|||
|
|
"""启动边缘模拟器"""
|
|||
|
|
self.logger.info(f"边缘智能终端启动, stcd={self.stcd}")
|
|||
|
|
self.logger.info(f"云端地址: {self.base_url}")
|
|||
|
|
|
|||
|
|
# 启动心跳线程
|
|||
|
|
heartbeat_thread = threading.Thread(
|
|||
|
|
target=self._heartbeat_loop, daemon=True, name="Heartbeat"
|
|||
|
|
)
|
|||
|
|
heartbeat_thread.start()
|
|||
|
|
|
|||
|
|
# 启动版本检查线程
|
|||
|
|
version_thread = threading.Thread(
|
|||
|
|
target=self._version_check_loop, daemon=True, name="VersionCheck"
|
|||
|
|
)
|
|||
|
|
version_thread.start()
|
|||
|
|
|
|||
|
|
# 主线程等待
|
|||
|
|
try:
|
|||
|
|
while self.running:
|
|||
|
|
time.sleep(1)
|
|||
|
|
except KeyboardInterrupt:
|
|||
|
|
pass
|
|||
|
|
|
|||
|
|
self.logger.info("边缘智能终端已安全退出")
|
|||
|
|
|
|||
|
|
|
|||
|
|
if __name__ == "__main__":
|
|||
|
|
simulator = EdgeDeviceSimulator()
|
|||
|
|
simulator.run()
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 四、新增/修改 API 接口汇总
|
|||
|
|
|
|||
|
|
| 接口路径 | 方法 | 认证 | 说明 | 状态 |
|
|||
|
|
|---------|------|------|------|------|
|
|||
|
|
| `/server/terminal/auth/` | POST | 无（设备密钥认证） | 设备认证，获取 JWT Token | **新增** |
|
|||
|
|
| `/server/terminal/heartbeat/` | PUT | 设备 Token | 更新心跳时间（已有，需增强认证） | **修改** |
|
|||
|
|
| `/server/terminal/checkVersion/` | GET | 设备 Token | 检查云端模型版本 | **新增** |
|
|||
|
|
| `/server/terminal/downloadModel/` | GET | 无历史遗留 | 下载模型文件（已有，需增强） | **修改** |
|
|||
|
|
| `/server/terminal/updateModelVersion/` | PUT | 设备 Token | 更新边缘端模型版本 | **新增** |
|
|||
|
|
| `ws://host/ws/terminal/status/` | WebSocket | 用户 Token | 推送终端在线状态变更 | **新增** |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 五、安全性设计
|
|||
|
|
|
|||
|
|
### 5.1 认证体系
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
┌─────────────────────────────────────┐
|
|||
|
|
│ 双层 Token 体系 │
|
|||
|
|
├─────────────────────────────────────┤
|
|||
|
|
│ 用户 Token (user) │
|
|||
|
|
│ ├── 有效期: 60分钟 │
|
|||
|
|
│ ├── 用途: 前端管理页面操作 │
|
|||
|
|
│ └── sub: user │
|
|||
|
|
│ │
|
|||
|
|
│ 设备 Token (device) │
|
|||
|
|
│ ├── 有效期: 24小时 │
|
|||
|
|
│ ├── 用途: 边缘设备 API 调用 │
|
|||
|
|
│ ├── sub: edge_device │
|
|||
|
|
│ └── stcd: 设备编码 │
|
|||
|
|
└─────────────────────────────────────┘
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 5.2 安全措施
|
|||
|
|
|
|||
|
|
1. **设备预置密钥**: 首次激活时下发唯一密钥，用于初始 Token 申请
|
|||
|
|
2. **Token 绑定设备**: Token 中携带 `stcd`，服务端验证请求中的 `stcd` 与 Token 一致
|
|||
|
|
3. **HTTPS 传输**: 生产环境强制 HTTPS，防止中间人攻击
|
|||
|
|
4. **请求频率限制**: 心跳接口限制 10次/分钟/设备，防止恶意刷接口
|
|||
|
|
5. **模型下载签名**: 可扩展为预签名 URL，限制下载有效期
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 六、部署与运维
|
|||
|
|
|
|||
|
|
### 6.1 云端定时任务配置
|
|||
|
|
|
|||
|
|
**方式一: Django Management Command + 系统 Cron**
|
|||
|
|
```bash
|
|||
|
|
# 每30秒执行一次离线检测
|
|||
|
|
* * * * * /path/to/python manage.py check_terminal_offline
|
|||
|
|
* * * * * sleep 30 && /path/to/python manage.py check_terminal_offline
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**方式二: Celery Beat（推荐）**
|
|||
|
|
```python
|
|||
|
|
# celery.py
|
|||
|
|
app.conf.beat_schedule = {
|
|||
|
|
'check-terminal-offline': {
|
|||
|
|
'task': 'apps.datasets.tasks.check_terminal_offline',
|
|||
|
|
'schedule': 30.0,
|
|||
|
|
},
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 6.2 边缘模拟器部署
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# 安装依赖
|
|||
|
|
pip install -r edge_simulator/requirements.txt
|
|||
|
|
|
|||
|
|
# 运行模拟器（前台）
|
|||
|
|
python edge_simulator/main.py
|
|||
|
|
|
|||
|
|
# 运行模拟器（后台）
|
|||
|
|
nohup python edge_simulator/main.py > /dev/null 2>&1 &
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 6.3 监控指标
|
|||
|
|
|
|||
|
|
| 指标 | 说明 | 告警阈值 |
|
|||
|
|
|------|------|---------|
|
|||
|
|
| 在线设备数 | online_status=1 的设备数 | 低于预期值的 80% |
|
|||
|
|
| 离线设备数 | online_status=0 的设备数 | 超过预期值的 20% |
|
|||
|
|
| 心跳延迟 | 心跳时间间隔 | 超过 60 秒 |
|
|||
|
|
| 模型更新成功率 | 成功更新数/总更新数 | 低于 90% |
|
|||
|
|
| Token 续期失败率 | Token 获取失败次数 | 连续 3 次失败 |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 七、时序图
|
|||
|
|
|
|||
|
|
### 7.1 Token 获取流程
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
边缘设备 云端服务器
|
|||
|
|
│ │
|
|||
|
|
│ POST /server/terminal/auth/ │
|
|||
|
|
│ {"stcd":"DEVICE001","secret":"**"}│
|
|||
|
|
│ ─────────────────────────────> │
|
|||
|
|
│ │── 验证设备编码与密钥
|
|||
|
|
│ │── 生成JWT Token (24h)
|
|||
|
|
│ 200 {access_token, ...} │
|
|||
|
|
│ <───────────────────────────── │
|
|||
|
|
│ │
|
|||
|
|
│── 保存Token到本地文件 │
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 7.2 心跳 + 版本检查 + 模型更新完整流程
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
边缘设备 云端服务器 前端管理页
|
|||
|
|
│ │ │
|
|||
|
|
│═══ 心跳循环 (30s/次) ═══════════│ │
|
|||
|
|
│ PUT /heartbeat/ [Token] │ │
|
|||
|
|
│ ─────────────────────────────> │── 更新 last_heartbeat_time │
|
|||
|
|
│ 200 OK │ │
|
|||
|
|
│ <───────────────────────────── │ │
|
|||
|
|
│ │ │
|
|||
|
|
│═══ 离线检测 (云端定时30s) ═══════│ │
|
|||
|
|
│ │── 检测超时5分钟的设备 │
|
|||
|
|
│ │── online_status → 0 │
|
|||
|
|
│ │── WebSocket推送 ───────────> │
|
|||
|
|
│ │ {"event":"offline", ...} │
|
|||
|
|
│ │ │── 更新UI
|
|||
|
|
│ │ │
|
|||
|
|
│═══ 版本检查 (定时) ══════════════│ │
|
|||
|
|
│ GET /checkVersion/ │ │
|
|||
|
|
│ ─────────────────────────────> │── 对比 model_version │
|
|||
|
|
│ 200 {having_newmodel:1, ...} │ 与 edge_model_version │
|
|||
|
|
│ <───────────────────────────── │ │
|
|||
|
|
│ │ │
|
|||
|
|
│═══ 模型下载 ═════════════════════│ │
|
|||
|
|
│── 备份旧模型到 backup/ │ │
|
|||
|
|
│ │ │
|
|||
|
|
│ GET /downloadModel/ │ │
|
|||
|
|
│ ─────────────────────────────> │── 从MinIO获取模型文件 │
|
|||
|
|
│ 200 (文件流) │ │
|
|||
|
|
│ <───────────────────────────── │ │
|
|||
|
|
│── 保存到 models/current/ │ │
|
|||
|
|
│── 更新本地 version.txt │ │
|
|||
|
|
│ │ │
|
|||
|
|
│ PUT /updateModelVersion/ │ │
|
|||
|
|
│ ─────────────────────────────> │── 更新 edge_model_version │
|
|||
|
|
│ 200 OK │ │
|
|||
|
|
│ <───────────────────────────── │ │
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 八、实施清单
|
|||
|
|
|
|||
|
|
### 云端新增开发项
|
|||
|
|
|
|||
|
|
- [ ] 新增 `EdgeDeviceAuthentication` 认证类
|
|||
|
|
- [ ] 新增 `POST /server/terminal/auth/` 设备认证接口
|
|||
|
|
- [ ] 新增 `GET /server/terminal/checkVersion/` 版本检查接口
|
|||
|
|
- [ ] 新增 `PUT /server/terminal/updateModelVersion/` 版本更新回调接口
|
|||
|
|
- [ ] 修改 `PUT /server/terminal/heartbeat/` 增加设备 Token 认证
|
|||
|
|
- [ ] 新增 `check_terminal_offline` 管理命令或 Celery 定时任务
|
|||
|
|
- [ ] 新增 WebSocket Consumer (`TerminalStatusConsumer`) 推送在线状态
|
|||
|
|
- [ ] 新增 `ws/terminal/status/` WebSocket 路由
|
|||
|
|
- [ ] 前端管理页面订阅 WebSocket，实时更新终端在线状态
|
|||
|
|
|
|||
|
|
### 边缘模拟器开发项
|
|||
|
|
|
|||
|
|
- [ ] 创建 `edge_simulator/` 目录结构
|
|||
|
|
- [ ] 实现 `auth.py` Token 管理模块
|
|||
|
|
- [ ] 实现 `heartbeat.py` 心跳上报模块
|
|||
|
|
- [ ] 实现 `version_check.py` 版本检查与下载模块
|
|||
|
|
- [ ] 实现 `main.py` 主调度程序
|
|||
|
|
- [ ] 编写 `requirements.txt` 依赖文件
|
|||
|
|
- [ ] 编写 Docker 部署配置（可选）
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 九、行业最佳实践参考
|
|||
|
|
|
|||
|
|
1. **OTA 更新策略**（参考物联网 OTA 标准）
|
|||
|
|
- 差量更新 vs 全量更新：当前采用全量下载，未来可扩展为增量更新
|
|||
|
|
- 灰度发布：支持按终端分类（sttp）或指定设备列表分批推送版本
|
|||
|
|
- 回滚机制：备份旧版本，支持云端指令触发回滚
|
|||
|
|
|
|||
|
|
2. **连接可靠性**（参考 MQTT/CoAP 协议设计）
|
|||
|
|
- 断线重连：边缘端实现指数退避重连（1s → 2s → 4s → ... → max 60s）
|
|||
|
|
- 离线缓存：心跳失败时的状态记录，恢复后补报
|
|||
|
|
- 连接池：单设备单连接，避免资源浪费
|
|||
|
|
|
|||
|
|
3. **安全性**（参考 IoT 安全最佳实践）
|
|||
|
|
- 设备唯一身份：stcd + 预置密钥组成设备指纹
|
|||
|
|
- 通信加密：TLS 1.2+
|
|||
|
|
- 最小权限：设备 Token 仅能访问自己的数据和接口
|
|||
|
|
- 定期轮换密钥（可选扩展）
|