运行环境报告

勘察日期：2026-09-08

目标主机：192.168.31.130（Jetson Orin Nano 实训台，主机名 ld-desktop）

勘察方式：SSH 只读远程采集，未做任何改动

文档位置：/Users/ido/ido2026/101.Business/Dev/python/VisualTechLab/

一、硬件环境

外接实训硬件（从软件栈与设备节点推断）

这是一台 AI 机器人视觉实训台，包含以下外接硬件：

容器运行时已直通 USB 总线（--device /dev/bus/usb），勘察时可见：

• /dev/video0、/dev/video1（2 路摄像头）
• /dev/ttyACM0（USB 串口，灵巧手/PLC 控制器）
• /dev/dri/card0/1、renderD128/129（GPU/显示渲染节点）

二、软件环境

2.1 宿主机（ld-desktop）

2.2 宿主机 Python 关键包

Flask                 2.2.5
Flask-SocketIO        5.6.1
python-socketio       5.16.3
docker                7.1.0          # 通过 Docker SDK 启停容器
opencv-contrib-python 4.11.0.86
opencv-python         4.11.0.86
torch                 2.8.0
torchaudio            2.8.0
torchvision           0.23.0

注意：宿主机跑门户和设备演示，不直接跑深度学习推理（推理在容器里）。

2.3 当前运行的实验容器

容器内环境：

容器内服务端口映射（宿主机→容器）：

容器挂载：

2.4 本地镜像列表

Docker 资源占用：镜像 23.1 GB、容器 61 MB、无命名卷、无 Build Cache。

三、业务架构

3.1 整体架构图

学生浏览器（Chrome）
    │  http://192.168.31.130:8080  ← Flask 门户首页 /login
    ▼
┌────────────────────────────────────────────────────────────┐
│  宿主机门户：/opt/device_app/web.py （Flask + SocketIO）   │
│  监听 0.0.0.0:8080，root 运行                              │
│  账号：user1 / user2，密码均为 123456（见 config.py）      │
│                                                             │
│  登录后 → 选实验 → 点"启动实验" → SocketIO 异步：          │
│    1) 停掉当前用户正在跑的容器（stop_all_containers）      │
│    2) 拷贝实验模板：/opt/device_data/<实验>/                │
│              → /data/docker4bd/private/<user>/<实验>/      │
│    3) docker run 新容器：                                  │
│       - nvidia runtime, privileged, --device /dev/bus/usb  │
│       - 内存 6G，CPU 4 核                                   │
│       - 环境变量 EXPERIMENT_LD, USERNAME_LD, VNC_PASSWORD  │
│    4) 返回 noVNC URL + JupyterLab URL 给前端               │
│                                                             │
│  状态文件：/opt/device_data/<user>_docker.txt（JSON）       │
│  容器编排配置：/opt/device_app/docker_supervise/config/     │
│                default.xml                                  │
└────────────────────────────────────────────────────────────┘
    │  32772~32775 端口转发
    ▼
┌────────────────────────────────────────────────────────────┐
│  实验容器（每学生/每实验一个，同时只跑一个）                │
│  - 中文桌面（Xtigervnc + noVNC）                           │
│  - JupyterLab 3.6（/data/personal 为工作目录）             │
│  - SSHD（root/123456）                                     │
│  - Python 3.10 + CUDA 12.2 + 全套 AI 库                   │
│  - 学生通过浏览器 noVNC 桌面或 JupyterLab 做实验           │
└────────────────────────────────────────────────────────────┘
    │  USB/串口/Dri 直通
    ▼
实训硬件（相机/灵巧手/PLC/传送带/机械臂/语音模块）

3.2 宿主机目录结构

/opt/
├── device_app/         211 MB   ← Flask 门户（主程序 web.py，20 KB）
│   ├── web.py                   Flask 路由与容器编排逻辑
│   ├── config.py                账号、镜像地址、模式（offline/online）
│   ├── run.sh                   启动脚本（PYTHONPATH 注入）
│   ├── device_app.service       systemd 单元
│   ├── docker_supervise/        Docker SDK 封装（common / sections / config）
│   │   └── config/default.xml   容器创建参数模板（端口、挂载、镜像）
│   ├── projects/                早期 12 个实验模板（与 device_data 重复）
│   ├── static/ templates/       门户前端
│   ├── toolsutil.py             工具函数
│   └── desktop.png              桌面快捷方式图标
│
├── device_data/        203 MB   ← 18 个实验模板库（当前版本）
│   ├── <实验目录>/               每个实验 = PDF + main_ui.py + .ipynb + 辅助模块
│   ├── resource/                 公共资源（images/、json/）
│   └── user1_docker.txt          当前 user1 的容器状态 JSON
│
├── device_demo/         45 MB   ← 设备演示 Web（web.py 44 KB）
│   ├── web.py                    直接操控传送带/相机/色块/机械臂/语音训练
│   ├── belt_operator.py          PLC 传送带控制
│   ├── camera.py                 大恒相机封装（gxipy）
│   ├── color_block.py            色块识别
│   ├── uart_assist.py            串口舵机/灵巧手控制
│   └── ...（train_*.py 训练脚本等）
│
├── pyorbbecsdk/                 ← 奥比中光深度相机 SDK（Python 绑定）
├── uhandclient/                 ← 灵巧手客户端
├── plcclient/                   ← PLC 客户端
├── Galaxy_Linux-*/              ← 大恒工业相机 GigE SDK
├── OrbbecViewer_*/              ← 奥比中光 Viewer 工具
├── yolov/ voice_model/          ← YOLOv、语音模型
├── desktopMonitor/              ← 桌面监控程序
├── installfile/                 ← 系统安装文件
├── nvidia/                      ← NVIDIA JetPack/L4T 相关
└── myblockly-*.AppImage          ← 图形化编程

/data/
├── docker/            43 GB     ← Docker 数据根目录（镜像、容器层）
├── docker4bd/        764 KB     ← 实验工作区（宿主机侧）
│   ├── public/                  公共资源挂载点（空）
│   ├── project/                 项目挂载点（空）
│   └── private/
│       └── user1/
│           └── voicecommand/    ← 语音指令实验（当前运行中，含 PDF + main_ui.py + voice.wav）
└── tee/                         ← TEE 安全目录

3.3 Flask 门户路由清单（web.py）

启动参数从 config.py + docker_supervise/config/default.xml 合并而来。

3.4 外呼依赖连通性

当前 config.py 配置 mode_type = "offline"，所以外呼失败不影响使用（镜像已本地存在，课件已在 device_data 中）。

四、实验清单：共 18 个实验

每个实验目录位于 /opt/device_data//，结构统一：

<实验名>/
├── <hash>.pdf              实验指导书（PDF，10-20MB）
├── main_ui.py              实验主程序（Tkinter 桌面 UI）
├── *.ipynb                 Jupyter Notebook（教学讲解）
├── *_assist.py             硬件辅助模块（串口/相机/语音）
├── tool_util.py / tools_util.py  工具函数
├── images/ Log/            图片素材/日志
└── requriment.txt          依赖声明（拼写错误，原作者笔误）

4.1 按主题分类

共 18 个有效实验 + 1 个公共资源目录，合计 约 203 MB。

4.2 视觉类实验普遍偏大的原因

• 每个都捆绑一份 PDF 实验指导书（8-18 MB）
• 多数含 .ipynb notebook 讲解
• 部分含预训练模型/样例图片（如 facedetector 的 Orbbec SDK 二进制是原作者误放）

4.3 硬件抽象层（HAL）现状

原作者已把硬件调用封装成独立的 Python 类，业务逻辑不直接碰底层——这是后续做模拟（Mock）教学环境的有利条件：

注：uart_assist.py 和 tools_util.py 在多个实验目录下各有一份副本（代码有细微差别），不是单例共享模块。

五、默认账号与密码（⚠️ 教学默认值，勿暴露公网）

六、监听端口一览

七、可行性评估：拉到本地 & 模拟教学环境

7.1 各部分内容的可迁移性

7.2 核心结论

1. 纯文档/代码级别复刻（460 MB）：rsync 几分钟完成，适合备课、改课件、离线阅读 notebook。

2. 完整 GPU 实验环境：只能在另一台 Jetson 设备（Orin/Xavier/Nano，JetPack 6.x + nvidia-container-toolkit）上还原；Mac/x86 Ubuntu 都跑不了那个 23 GB 镜像。

3. 模拟教学环境（Hardware-in-the-Loop Mock）：完全可行，且代码结构支持——只需在硬件抽象层之上加一套 Mock 驱动实现，让学生发"传送带启动/手势张开"等指令时，Mock 返回预设状态和数据。

八、模拟教学环境建设方案（讨论方向）

8.1 为什么可行

原作者已将所有硬件调用封装在独立驱动类（UartAssist、BeltOperator、Camera、SipeedMicRecorder、mycobot_stack）中，业务代码（实验 main_ui.py、notebook、AI 识别）通过这些类的方法签名间接访问硬件。这意味着：

按相同类名、相同方法签名实现一套"假驱动"，业务代码一行不改即可在普通 Ubuntu 上运行；由配置开关切换 real / mock 模式。

8.2 三层模拟深度

8.3 推荐路线

1. 第一步：拉代码 —— rsync 把 /opt/device_app、/opt/device_data、/opt/device_demo（共 ~460 MB）同步到本地 VisualTechLab/ 目录

2. 第二步：单实验打样 —— 建议选 voicecommand（最简单，验证架构）或 intelligentsorting（传送带+相机+机械臂全链路，最能暴露问题）

3. 第三步：抽出 HAL 层 —— 建 hal/real/ 与 hal/mock/ 两套实现，一个全局 SIMULATION_MODE 开关

4. 第四步：逐个实验适配 —— 18 个实验复用同一套 HAL，打样完成后其余实验适配成本快速下降

5. 第五步（可选）：数字孪生可视化 + 故障注入（模拟丢包/设备离线/识别失败）

8.4 模拟覆盖度估算

• 可完整模拟（无需硬件）：语音类 3 个、视觉识别类 8-10 个（用回数据/预置模型）、条码/二维码/车牌识别 —— 约 13-14 个实验
• 可部分模拟（算法可跑，但硬件交互需简化）：双手加法、猜拳、智能分拣、机器人码垛 —— 约 4 个
• 无法纯软件模拟（必须真机）：相机焦距标定、深度测量、机械臂碰撞/公差、硬件接线故障排查 —— 约 2-3 个

总体模拟覆盖率约 75-80%，足以支撑课前预习、课下复习、算法反复练习、批量学生无设备自学等场景。

8.5 模拟环境不需要 23GB Jetson 镜像

在普通 Ubuntu（x86_64 或 arm64 Mac）上所需的只是：

• Python 3.10
• CPU 版 torch / onnxruntime / opencv-python / flask / flask-socketio / pyserial / pyzbar / faster-whisper
• 课件代码（~460 MB）
• 预置模型 + 回放素材（按需下载）

总磁盘占用预计 < 3 GB（不含模型）。

九、建议的后续动作（待讨论确认）

• [ ] 用 rsync 把 /opt/device_app、/opt/device_data、/opt/device_demo 同步到本地 VisualTechLab/remote/
• [ ] 选定第一个 Mock 打样实验（voicecommand 或 intelligentsorting）
• [ ] 在本地 VisualTechLab/simulator/ 搭建 HAL 框架，接入 Mock 实现
• [ ] 跑通第一个闭环实验后，批量适配其余实验
• [ ] （可选）数字孪生可视化页面
• [ ] （可选）镜像离线备份：docker save 出 23GB 镜像归档存移动硬盘，以防设备故障

附录：勘察时使用的非侵入式命令（仅读）

# 连通性
ping 192.168.31.130
nc -zv 192.168.31.130 22

# 硬件/系统
lscpu; free -h; df -hT; lsblk; ip -brief addr; dmidecode -s system-product-name

# Docker
docker ps -a; docker images; docker volume ls; docker network ls; docker system df;
docker inspect jovial_brown; docker exec jovial_brown bash -c '...'

# 业务目录
ls -la /opt/device_app; ls -la /opt/device_data; ls -la /data/docker4bd;
grep -n "@app.route" /opt/device_app/web.py; ss -tlnp

所有采集均通过 SSH 以只读查询为主，未在对端写入或修改任何文件（除之前按你指示配置了 dev 账号的 SSH 公钥与 sudo NOPASSWD）。

十、二次验证补充信息（Workbody P0验证）

以下信息来自 Workbody 自动化探测脚本的二次验证，对首次勘察结果进行补充确认。

10.1 Docker 远程 API 可达性

• Docker daemon 监听 tcp://192.168.31.130:13486（首次勘察已记录）
• P0 验证确认：从远端 Python 容器通过 TCP 访问该端口可成功调用 Docker API（list_containers、list_images 等接口均正常返回）
• 这意味着 liveservice 容器有两种方式管理宿主机 Docker：

1. 挂载 /var/run/docker.sock（推荐，更安全、不暴露 TCP 端口）
2. 通过 TCP 连接 192.168.31.130:13486（已验证可行，但需确保端口仅内网访问）

10.2 容器内 Docker sock 访问

• P0 验证确认：容器内挂载 /var/run/docker.sock 后，可正常调用 Docker SDK 管理宿主机容器，包括：

1. 启动 / 停止实验容器
2. 查询容器状态
3. 获取容器日志
4. 动态端口映射

• 验证方式：在 Python 测试容器内安装 docker 包，挂载 sock 后成功 list / containers / create / start

10.3 离线环境确认

• 服务器无法访问外部网络：39.101.211.60:5000（私有 Harbor 仓库）不可达；192.168.31.10（教案 / 文件服务器）不可达；公网不通（无 Internet 连接）
• 部署影响：不能依赖 docker pull 或 apt install 从外网获取资源，必须采用"本地 build → docker save → scp 传输 → docker load"的离线部署流程
• 好消息：实验镜像 jetson-orin-nano-gpu:v1（23GB）已在本地，PostgreSQL 镜像可以在本地 Mac（arm64）pull 后一起打包传输

10.4 磁盘资源余量确认

• 根分区 233GB，已用 51GB（23%），剩余 171GB 可用
• Docker 数据目录 /data/docker 占 43GB（镜像 23GB + 容器层）
• 新增 PostgreSQL 数据预计占用 < 1GB；新增 liveservice 镜像预计 < 500MB；学生数据（代码 + 成绩 + 日志）预计一学期 < 5GB
• 磁盘余量充足，无需额外扩容

10.5 Python 与 pip 环境

• 宿主机 Python 3.10.12，pip 可用；但离线环境下 pip install 无法从 PyPI 下载包
• 进一步确认全 Docker 化部署的必要性：所有 Python 依赖打包进 Docker 镜像，不需要在宿主机 pip install
• 本地 Mac（arm64）build 镜像 → 传输到 Jetson → 直接运行，零依赖

10.6 原厂容器参数模板确认

• /opt/device_app/docker_supervise/config/default.xml 包含完整的容器创建参数：镜像名、runtime、CPU/内存限制、端口映射范围、设备直通、环境变量、工作目录挂载
• 该模板可被 liveservice 直接读取或复刻，确保容器启动参数与原厂完全一致
• 原厂容器启动逻辑位于 /opt/device_app/web.py 的 start_docker 路由函数中

10.7 systemd 服务状态补充

• device_app.service systemd 单元文件存在，但勘察时服务状态为 inactive
• 实际的 Flask 门户进程（pid 5048/5050）由 /opt/device_app/run.sh 直接拉起，未通过 systemd 管理
• 部署影响：liveservice 部署时需要决定如何处理原厂 web.py 进程（停掉并由 liveservice 替代，或改端口共存）