mingxi_platform/docs/明析平台-软件重构设计文档.md

明析平台 软件重构设计文档

版本：v2.0 · 日期：2026-05-24
项目：基于机器视觉的图像识别技术应用平台——明析
参赛：梅州市2026年新一代电子信息暨人工智能产业创新创业大赛 · 初创企业（创客）组

---

1. 重构背景

1.1 现有代码概况

当前仓库 yolo_classification_system 是一套通用YOLO推理系统，实现了：

模块	现状
后端	Django 4 + DRF，JWT鉴权，支持图片/视频/摄像头三种推理模式
推理	inference.py 封装 ultralytics YOLO，模型缓存，结果落库
数据模型	UserProfile、YoloResult、SceneNews、SystemLog、YoloStatsDaily
前端	Vue 3 + Vite，开发/生产环境分离，API代理配置完整
演示模型	驾驶员疲劳检测（driver-drowsiness-detection/best.pt）

1.2 重构目标

将通用系统改造为PCB线路板缺陷检测专用平台（明析），在不改动客户现有硬件的前提下，通过算法叠加实现AI视觉质检能力升级。

---

2. 系统物理架构

2.1 两台机器部署

┌─────────────────────────────────┐     局域网      ┌──────────────────────────────────────┐
│         前置机（工业PC）          │ ─────────────→ │           推理服务器（Linux+GPU）        │
│                                 │                │                                      │
│  相机 ──USB3──→ mingxi-capture   │                │  mingxi-vision   :8001  (FastAPI)    │
│               （PyQt5桌面程序）   │                │  mingxi-backend  :8000  (Django)     │
│               Win7 SP1+ 工业机   │                │  mingxi-frontend :80    (Vue3)       │
└─────────────────────────────────┘                └──────────────────────────────────────┘

角色	机器	操作系统	运行软件
前置机	工厂现有工业PC（USB3.0）	Windows 7 SP1 及以上	mingxi-capture.exe
推理服务器	团队配置（RTX 4060 或以上）	Linux	mingxi-vision + mingxi-backend + mingxi-frontend

2.2 数据流

操作工（点击按钮）或 PLC触发信号
        │
        ▼
  mingxi-capture（前置机）
        │
        ├─① 同步 POST 图像 ──────────────→ mingxi-vision（推理服务器:8001）
        │                                        │ 推理完成
        │       ←── 返回标注图+缺陷列表+结论 ──────┘
        │
        ├─ 立即在桌面程序展示结果（操作工可见）
        │   · 合格 / 不合格 结论
        │   · 标注了缺陷位置的图像
        │   · 每个缺陷的类型、等级、置信度
        │
        └─② 异步队列 POST 结果 ──────────→ mingxi-backend（:8000）
                                                 │ 存入 SQLite
             若失败 → 本地SQLite重试队列           │
                                                 ▼
                                          管理员/组长/厂长
                                          通过浏览器查看
                                         （短轮询，1-2秒延迟）

2.3 端口分配

服务	端口	调用方
mingxi-vision	8001	mingxi-capture（同步推理）
mingxi-backend	8000	mingxi-capture（存档）、浏览器前端
mingxi-frontend	80	浏览器

---

3. 子项目拆分方案

3.1 项目总览

mingxi-capture/      Python 3.8 · PyQt5 · Windows桌面程序（前置机运行）
mingxi-vision/       Python 3.8 · FastAPI · PCB缺陷推理服务（推理服务器运行）
mingxi-backend/      Python 3.8 · Django 4 · 业务后端（推理服务器运行）
mingxi-frontend/     Vue 3.0 · 管理后台（推理服务器运行，浏览器访问）

3.2 代码迁移决策

现有文件/模块	处置方式	说明
yolo8/models.py → UserProfile	直接复用	JWT鉴权体系完整，扩展 role 字段
yolo8/models.py → SystemLog	直接复用	日志结构通用
yolo8/jwt_utils.py	直接复用	token版本机制保留
yolo8/models.py → YoloResult	重构为 DefectResult	增加PCB专用字段：缺陷等级、产线
yolo8/models.py → SceneNews	删除	与PCB业务无关
yolo8/models.py → YoloStatsDaily	重构为 ProductionStat	改为产线维度统计
yolo8/inference.py → run_image_inference	迁移至 mingxi-vision	推理服务核心，增加ONNX支持
yolo8/inference.py → run_camera_inference	删除	由 mingxi-capture 海康SDK替代
yolo8/inference.py → _copy_to_ascii_temp_input	删除	改为内存读图，彻底消除中文路径问题
yolo8/views.py → 鉴权相关视图	直接复用	auth_*、user_* 无需改动
yolo8/views.py → yolo_task_image	重构为 detect_pcb	简化，接收capture推送
frontend/	重构	删除通用YOLO页面，改为管理后台

---

4. mingxi-capture（前置采集程序）

4.1 定位

运行在前置机（工厂工业PC）上的 Windows 原生桌面程序。操作工唯一的交互界面，负责连接相机、触发检测、展示结果，并将结果异步上报至后台。

4.2 技术栈

语言：Python 3.8
GUI：PyQt5（支持 Windows 7 SP1 及以上，系统托盘、对话框完整支持）
相机：MvImport（海康威视MVS Python SDK，随MVS安装包提供）
本地存储：SQLite（通过 Python 内置 sqlite3）
网络：requests（同步调用vision）+ threading（异步队列推送backend）
打包：PyInstaller → 单文件 .exe 或目录，客户解压即用
最低系统：Windows 7 SP1 x64

4.3 目录结构

mingxi-capture/
├── camera/
│   ├── hik_camera.py        # 海康相机封装（MvImport，Phase 2接入）
│   └── mock_camera.py       # 模拟模式（读本地图片文件夹，Demo/开发用）
├── ui/
│   ├── main_window.py       # 主窗口：触发按钮 + 图像展示 + 缺陷列表
│   ├── config_dialog.py     # 配置弹窗：服务器地址、端口、相机参数
│   └── tray_icon.py         # 系统托盘图标：显示/隐藏主窗口、退出
├── core/
│   ├── capture_worker.py    # 拍图+调推理（在QThread中执行，不阻塞UI）
│   ├── upload_queue.py      # 异步上报队列（本地SQLite缓存+重试）
│   └── settings.py          # 读写 config.ini 配置文件
├── assets/
│   └── tray_icon.png        # 托盘图标
├── config.ini               # 默认配置（首次运行生成）
├── queue.db                 # 本地重试队列（SQLite，运行时生成）
├── main.py                  # 程序入口
├── requirements.txt
└── mingxi-capture.spec      # PyInstaller打包配置

4.4 主窗口功能

┌─────────────────────────────────────────┐
│  明析采集程序  [最小化到托盘] [×]         │
├─────────────┬───────────────────────────┤
│             │  ┌───────────────────────┐│
│  [手动检测] │  │                       ││
│             │  │   标注图显示区域       ││
│  状态: 就绪 │  │   (检测后显示)        ││
│             │  │                       ││
│  结论:      │  └───────────────────────┘│
│  ██ 不合格  │                           │
│             │  缺陷列表:                │
│  共 3 处    │  类型      等级  置信度   │
│  最高: 致命 │  断路      致命  0.94     │
│             │  短路      致命  0.88     │
│             │  毛刺      轻微  0.72     │
└─────────────┴───────────────────────────┘

4.5 配置弹窗（系统托盘右键→设置）

推理服务地址:  [192.168.1.100]  端口: [8001]
后台服务地址:  [192.168.1.100]  端口: [8000]
相机序列号:    [自动检测 ▼]
模拟模式:      [✓] 启用    图片目录: [C:\test_images\  浏览]
置信度阈值:    [0.45]
[保存]  [取消]

配置持久化至 config.ini，程序启动时自动读取。

4.6 异步上报队列

# core/upload_queue.py 逻辑

# 1. capture_worker 推理成功后，将结果插入本地 SQLite queue.db
# 2. 后台线程每 5 秒扫描一次 queue.db 中状态为 pending 的记录
# 3. 尝试 POST 到 mingxi-backend
#    成功 → 标记为 sent
#    失败 → retry_count + 1，超过 10 次标记为 failed（不再重试）
# 4. 队列表结构:
#    id, image_base64, result_json, created_at, status, retry_count, last_error

4.7 mock_camera 模拟模式

Phase 1（路演）无真实相机时，从配置目录中按序读取 .jpg/.png 文件，接口与 hik_camera.py 完全一致，上层代码无感知切换。

4.8 打包部署

pyinstaller mingxi-capture.spec
# 输出：dist/mingxi-capture/（目录模式）或 dist/mingxi-capture.exe（单文件）
# 客户端：解压后双击 mingxi-capture.exe 即可运行
# 随安装包附带：海康 MVS Runtime DLL（如需相机功能）

4.9 触发模式（阶段支持）

触发方式	Phase 1	Phase 2
手动点击按钮	✅	✅
PLC/传感器信号（串口/数字IO）	—	✅
定时自动（固定频率）	—	✅

---

5. mingxi-vision（推理服务）

5.1 职责

• 接收图像（来自 mingxi-capture）
• 调用明析平台（YOLOv8/ONNX）执行PCB缺陷检测
• 返回缺陷列表（位置、类别、置信度、等级）+ 标注图（可选）
• 支持模型热重载（管理员通过后台切换模型时调用）

5.2 技术栈

语言：Python 3.8
框架：FastAPI + uvicorn（workers=1，单进程，GPU不跨进程共享）
推理：ultralytics YOLOv8（开发阶段）/ ONNX Runtime（生产部署）
并发：asyncio.Lock（推理串行化，防止GPU冲突）
GPU：CUDA 11.x + cuDNN

5.3 并发处理：推理锁

# engine/loader.py
import asyncio

_inference_lock = asyncio.Lock()
_engine: Optional[BaseInferenceEngine] = None

def get_inference_lock() -> asyncio.Lock:
    return _inference_lock

# api/detect.py
async def detect(image: UploadFile, conf: float = 0.45, ...):
    raw = await image.read()
    img = cv2.imdecode(np.frombuffer(raw, np.uint8), cv2.IMREAD_COLOR)

    async with get_inference_lock():        # 请求自动排队，GPU串行执行
        result = engine.detect(img, conf)

    return build_response(result)

• 并发请求不会崩溃，自动排队等待
• RTX 4060，YOLOv8s，PCB图：约 2040ms/张 → 2550 fps
• Windows / Linux 行为完全一致（asyncio 事件循环原语，无OS依赖）

5.4 模型热重载接口

POST /api/model/reload
Body: { "model_path": "/opt/mingxi/models/pcb_v2.onnx" }
Response: { "status": "ok", "model_version": "pcb_v2", "warmup_ms": 312 }

热重载流程：

1. 管理员在浏览器上传新模型并点击"切换"
2. mingxi-backend 保存文件、更新数据库，调用此接口
3. mingxi-vision 获取推理锁（等待当前推理完成），卸载旧模型，加载新模型，执行 warmup
4. 释放锁，返回成功

5.5 目录结构

mingxi-vision/
├── api/
│   ├── detect.py            # POST /api/detect
│   ├── model.py             # POST /api/model/reload
│   └── health.py            # GET /api/health, /api/health/gpu
├── engine/
│   ├── base.py              # DefectBox, DetectResult, BaseInferenceEngine
│   ├── loader.py            # 单例 + asyncio.Lock + init_engine()
│   ├── ultralytics_adapter.py
│   ├── onnx_adapter.py
│   ├── annotator.py         # 标注图生成（按severity着色）
│   └── defect_classes.py    # HRIPCB 6类 + 扩展4类
├── models/                  # .pt 和 .onnx 文件（gitignored）
├── scripts/
│   ├── export_onnx.py       # pt → onnx 导出脚本
│   └── benchmark.py
├── tests/
├── schema.py                # Pydantic 响应模型
├── config.py                # BaseSettings（读 .env）
├── main.py                  # FastAPI lifespan + app
└── requirements.txt

5.6 推理接口

POST /api/detect
Content-Type: multipart/form-data
Fields:
  image: <图像文件>
  conf: float (default: 0.45)
  return_annotated: bool (default: false)

Response 200:
{
  "task_id": "uuid",
  "duration_ms": 38,
  "verdict": "fail",                      // pass / fail
  "defect_count": 2,
  "max_severity": "fatal",
  "avg_confidence": 0.89,
  "defects": [
    {
      "class_id": 2,
      "class_name": "open_circuit",
      "class_name_zh": "断路",
      "confidence": 0.94,
      "severity": "fatal",
      "box_xyxy": [120, 45, 198, 123]
    }
  ],
  "annotated_image_base64": "..."         // 仅 return_annotated=true 时返回
}

5.7 缺陷类别与等级映射

DEFECT_CLASSES = {
    # HRIPCB 数据集原始6类
    0: {"name": "missing_hole",    "zh": "缺孔",    "severity": "fatal"},
    1: {"name": "mouse_bite",      "zh": "鼠咬",    "severity": "major"},
    2: {"name": "open_circuit",    "zh": "断路",    "severity": "fatal"},
    3: {"name": "short_circuit",   "zh": "短路",    "severity": "fatal"},
    4: {"name": "spur",            "zh": "毛刺",    "severity": "minor"},
    5: {"name": "spurious_copper", "zh": "余铜",    "severity": "major"},
    # 扩展类（Phase 2 标注后训练）
    6: {"name": "oxidation",       "zh": "氧化",    "severity": "minor"},
    7: {"name": "solder_ball",     "zh": "锡珠",    "severity": "rework"},
    8: {"name": "scratch",         "zh": "划痕",    "severity": "minor"},
    9: {"name": "label_error",     "zh": "标签错贴","severity": "rework"},
}

---

6. mingxi-backend（业务后端）

6.1 职责

• 接收 mingxi-capture 推送的检测结果，持久化至 SQLite
• 提供 REST API 给浏览器管理后台
• 用户管理、三级权限控制
• 模型文件管理（上传、备份、切换、触发vision热重载）
• 系统参数配置

6.2 技术栈

语言：Python 3.8
框架：Django 4.0 + django-rest-framework
数据库：SQLite（内网单服务器部署，无高并发写入，SQLite足够）
认证：JWT（从现有系统直接复用）

初期不引入 Celery/Redis，保持部署简单。告警推送（Phase 2）再评估是否引入。

6.3 用户权限设计

角色	检测记录可见范围	其他权限
操作工	仅自己触发的记录	无
组长	本组所有成员的记录	查看本组统计
管理员	全部记录	用户管理、系统配置、模型管理、查看所有统计

# UserProfile 扩展
class UserProfile(models.Model):
    user     = models.OneToOneField(User)
    role     = models.CharField(choices=[
                 ("operator", "操作工"),
                 ("leader",   "组长"),
                 ("admin",    "管理员"),
               ], default="operator")
    group    = models.ForeignKey("WorkGroup", null=True)  # 操作工和组长属于某个工组

class WorkGroup(models.Model):
    name     = models.CharField(max_length=100)
    leader   = models.ForeignKey(UserProfile, null=True, related_name="led_group")

6.4 模型管理设计

class ModelRegistry(models.Model):
    """模型版本注册表"""
    name         = models.CharField(max_length=100)        # 文件名（含扩展名）
    runtime      = models.CharField(choices=["pt", "onnx"])
    file_path    = models.CharField(max_length=500)        # 服务器本地路径
    file_size    = models.IntegerField()                   # 字节数
    is_active    = models.BooleanField(default=False)      # 当前生效模型
    uploaded_by  = models.ForeignKey(UserProfile)
    uploaded_at  = models.DateTimeField(auto_now_add=True)
    notes        = models.TextField(blank=True)

模型管理规则：

• 同时只有一个 is_active=True
• 最多保留 10 个版本，超出时自动删除最早上传的非活跃版本及其文件
• 切换模型时：更新 is_active → 调用 POST http://localhost:8001/api/model/reload

6.5 管理员可配置参数

参数类别	具体参数
推理参数	置信度阈值、IOU阈值、图像输入尺寸
模型管理	上传模型、切换活跃模型、查看备份列表
产线配置	产线名称、前置机IP（仅记录，不主动通信）
用户管理	新增/停用账号、分配角色、分配工组
告警规则	Phase 2，预留接口

6.6 数据模型设计

class DefectResult(models.Model):
    """单次检测记录"""
    operator        = models.ForeignKey(UserProfile, null=True)
    line_id         = models.CharField(max_length=50, blank=True)
    source_image    = models.ImageField(upload_to="originals/")
    annotated_image = models.ImageField(upload_to="annotated/", null=True)
    verdict         = models.CharField(choices=["pass", "fail"])
    defect_count    = models.IntegerField(default=0)
    max_severity    = models.CharField(choices=["none","rework","minor","major","fatal"])
    detections_json = models.TextField()       # 完整缺陷列表JSON
    avg_confidence  = models.FloatField()
    duration_ms     = models.IntegerField()
    model_version   = models.CharField(max_length=100)
    created_at      = models.DateTimeField(auto_now_add=True)


class ProductionStat(models.Model):
    """每日产线统计（聚合）"""
    stat_date       = models.DateField()
    line_id         = models.CharField(max_length=50)
    total_count     = models.IntegerField(default=0)
    pass_count      = models.IntegerField(default=0)
    fail_count      = models.IntegerField(default=0)
    defect_dist     = models.TextField()       # 各缺陷类型数量JSON


class SysConfig(models.Model):
    """系统参数键值存储"""
    key             = models.CharField(max_length=100, unique=True)
    value           = models.TextField()
    updated_at      = models.DateTimeField(auto_now=True)

6.7 API 接口设计

# 认证（直接复用现有代码）
POST   /api/auth/login
POST   /api/auth/refresh
POST   /api/auth/logout
GET    /api/user/me

# 检测结果（capture推送入口）
POST   /api/detect/result/              # capture 上报推理结果
GET    /api/detect/results/             # 列表（按角色自动过滤）
GET    /api/detect/results/{id}/

# 统计
GET    /api/stats/overview/             # 今日合格率、缺陷总数
GET    /api/stats/trend/                # 近N天趋势
GET    /api/stats/defect-dist/          # 缺陷类型分布

# 模型管理（管理员）
GET    /api/admin/models/               # 模型列表（最多10条）
POST   /api/admin/models/upload/        # 上传新模型
POST   /api/admin/models/{id}/activate/ # 切换活跃模型（触发vision热重载）
DELETE /api/admin/models/{id}/          # 手动删除某个备份

# 系统配置（管理员）
GET    /api/admin/config/
PATCH  /api/admin/config/

# 用户管理（管理员）
GET    /api/admin/users/
POST   /api/admin/users/
PATCH  /api/admin/users/{id}/
GET    /api/admin/groups/
POST   /api/admin/groups/

# 系统日志（直接复用）
GET    /api/admin/logs/

---

7. mingxi-frontend（管理后台）

7.1 定位

纯管理后台，供组长、厂长、管理员通过浏览器使用。操作工不通过浏览器操作（操作工使用前置机桌面程序）。

7.2 技术栈

框架：Vue 3 + Vite + TypeScript（保持现有配置不变）
UI：Element Plus（复用现有）
图表：ECharts（统计报表）
实时：短轮询（每1秒请求一次最新记录，满足1-2秒延迟要求，无需WebSocket）

短轮询而非 WebSocket：部署简单，Django 无需 Channels，延迟满足要求。

7.3 页面规划

路由	页面	可见角色	现有/新增
/login	登录	全部	复用
/dashboard	实时监控看板	组长、管理员	新增
/history	检测历史记录	全部（按权限过滤）	新增
/stats	统计报表	组长、管理员	新增
/admin/models	模型管理	管理员	新增
/admin/config	系统配置	管理员	新增
/admin/users	用户管理	管理员	复用改造

7.4 实时监控看板（/dashboard）

• 最新检测结果卡片（标注图缩略图 + 结论）
• 今日合格率仪表盘
• 缺陷类型分布饼图
• 近10条记录时间线
• 每1秒轮询 /api/detect/results/?limit=1&ordering=-created_at

7.5 需删除的现有页面

SceneNews 相关页面
通用YOLO视频/摄像头检测页面
驾驶员疲劳检测相关组件

---

8. 系统间通信

8.1 完整通信图

前置机（Windows）                      推理服务器（Linux）
┌──────────────────────┐              ┌──────────────────────┐
│   mingxi-capture     │              │   mingxi-vision      │
│                      │──① POST─────→│   /api/detect        │
│   QThread推理线程     │←─ 结果返回──│   asyncio.Lock串行   │
│                      │              └──────────────────────┘
│   主线程展示结果      │
│                      │              ┌──────────────────────┐
│   upload_queue线程   │──② 异步────→│   mingxi-backend     │
│   （失败则重试）      │              │   /api/detect/result │
└──────────────────────┘              │                      │
                                      │   SQLite存档         │
                                      └──────────┬───────────┘
                                                 │ REST API
                                      ┌──────────▼───────────┐
                                      │   mingxi-frontend    │
                                      │   浏览器短轮询        │
                                      └──────────────────────┘
                                      管理员/组长/厂长 浏览器访问

8.2 关键通信约定

通信路径	协议	格式	备注
capture → vision	HTTP POST	multipart/form-data（图像二进制）	同步，等待结果
vision → capture	HTTP Response	JSON（含 base64 标注图）	一次请求一次响应
capture → backend	HTTP POST	JSON（推理结果）	异步，本地队列保障
browser → backend	HTTP REST	JSON	短轮询 + 增删改查
backend → vision（热重载）	HTTP POST	JSON	仅管理员切换模型时触发

8.3 前置机配置两个地址

前置机桌面程序配置界面中填写：

• 推理服务地址：http://192.168.x.x:8001（vision）
• 后台服务地址：http://192.168.x.x:8000（backend）

两个服务通常在同一台服务器上，填写相同IP、不同端口。

---

9. 硬件集成（相机配置）

9.1 推荐型号

阶段	型号	分辨率	接口	用途
Demo/POC	MV-CS060-10GM	600万像素	USB3.0	算法验证，接工业PC
产线部署	MV-CA060-10GM	600万像素	GigE	稳定产线，线长100m
大板检测	MV-CA120-10GM	1200万像素	GigE	视野≥200mm的PCB

9.2 分辨率选型计算

视野：100mm × 75mm（单次拍摄区域）
最小缺陷：0.1mm（针孔、断路）
像素尺寸 ≤ 0.1mm ÷ 3 = 0.033mm/pixel
所需分辨率：100 ÷ 0.033 ≈ 3030 pixels（水平）
结论：600万像素（3072×2048）满足需求 ✓

9.3 配套清单（单工位 Demo 版）

器材	型号/规格	估价
工业相机	MV-CS060-10GM	1800-2500元
镜头	16mm C口定焦（1/1.8"靶面）	500-800元
LED环形光源	同轴/低角度，直径120mm	400-600元
USB3.0线缆	≤3m，锁扣式	80-150元
简易支架光箱	铝型材，可调高度	200-400元
合计		约 3000-4450元

---

10. 开发阶段划分

Phase 1：Demo版（目标：2026年6月中旬决赛前）

路演方式： 预先准备好的PCB图片，模拟模式演示完整流程，约5分钟。

核心展示： 操作工点击→检测→标注图展示→管理后台历史记录。

P0（必须完成，路演核心）：
  [ ] mingxi-vision：图片推理API + asyncio.Lock + 启动warmup
  [ ] mingxi-capture：PyQt5桌面程序，Mock模式，结果展示界面
  [ ] mingxi-backend：接收capture推送，DefectResult落库，基础REST API
  [ ] mingxi-frontend：登录 + 检测历史列表 + 详情页
  [ ] mingxi-backend：三级权限（操作工/组长/管理员）

P1（有时间做，加分项）：
  [ ] mingxi-frontend：实时监控看板（短轮询）
  [ ] mingxi-backend：模型管理（上传/备份/切换）
  [ ] mingxi-frontend：统计报表页
  [ ] mingxi-capture：系统托盘图标

Phase 2：POC版（目标：2026年Q3，接入真实相机）

  [ ] mingxi-capture：接入海康MVS SDK，对接 MV-CS060-10GM
  [ ] mingxi-capture：PLC触发接口（串口/数字IO）
  [ ] mingxi-vision：ONNX Runtime部署（export_onnx.py导出）
  [ ] mingxi-vision：模型热重载接口完善
  [ ] mingxi-backend：告警规则引擎（连续不良数、缺陷率阈值）
  [ ] 完成1家PCB厂POC试用

Phase 3：产线版（目标：2026年Q4，首单签约）

  [ ] 多相机支持（多条产线并发采集）
  [ ] 模型迁移学习（基于客户真实样本微调）
  [ ] 告警推送（企业微信/短信）
  [ ] MES/ERP对接接口
  [ ] 边缘部署探索（Jetson Orin，脱离大型服务器）
  [ ] 软件著作权申请

---

11. 开发环境搭建

11.1 各项目启动命令

# mingxi-vision（推理服务器，Linux）
cd mingxi-vision
pip install -r requirements.txt
uvicorn main:app --host 0.0.0.0 --port 8001 --workers 1

# mingxi-backend（推理服务器，Linux）
cd mingxi-backend
pip install -r requirements.txt
python manage.py migrate
python manage.py runserver 0.0.0.0:8000

# mingxi-frontend（推理服务器，Linux）
cd mingxi-frontend
npm install
npm run build   # 生产：dist/ 由 nginx 托管
npm run dev     # 开发：localhost:5173

# mingxi-capture（前置机，Windows，开发阶段）
cd mingxi-capture
pip install -r requirements.txt
python main.py  # 启动桌面程序，自动进入Mock模式（若配置了图片目录）

11.2 环境变量

# mingxi-vision/.env
MODEL_PATH=./models/pcb_defect_v1.pt
RUNTIME=ultralytics          # 或 onnx
DEVICE=cuda                  # 或 cpu
CONF_THRESHOLD=0.45

# mingxi-backend/.env
SECRET_KEY=...
DATABASE_PATH=./db.sqlite3
VISION_SERVICE_URL=http://127.0.0.1:8001
CORS_ALLOWED_ORIGINS=http://localhost:5173
MODEL_STORAGE_DIR=/opt/mingxi/models
MODEL_MAX_BACKUPS=10

11.3 开发联调注意事项

• mingxi-capture 在 Windows 开发机上运行，配置 vision/backend 为开发机局域网IP
• mingxi-vision 和 mingxi-backend 建议在同一台机器（或WSL2）上启动
• SQLite 文件在 mingxi-backend/ 目录下，无需额外数据库服务

---

12. 参考资料

资料	路径/来源
创业技术书	梅州创新创业大赛/创业技术书v1.3.docx
明析vision架构详细设计	梅州创新创业大赛/mingxi-vision-架构设计.md
现有后端代码	yolo_classification_system/
PCB缺陷检测调研	梅州创新创业大赛/pcb缺陷检测初步方案.md
海康MVS SDK	随MVS安装包提供，路径：C:\Program Files (x86)\MVS\Development\
HRIPCB数据集	公开学术数据集，CC BY 4.0，6类缺陷，10,000+样本
PyQt5文档	https://doc.qt.io/qtforpython-5/
PyInstaller文档	https://pyinstaller.org/en/stable/