参考手册

端口与数据流

端口清单

核心数据流

1. 终端发现与注册

教师端启动
  └─ communication_module 每 30s 向 ff02::1 发空 UDP

终端上电
  └─ discover_teacher() 后台线程启动
      ├─ 读缓存 .terminal_config（如有）
      ├─ IPv6 多播 ping ff02::1（Win10 不回包，正常）
      ├─ 查邻居表 ip -6 neigh
      ├─ TCP 探测教师端 8790 端口
      └─ 连接成功 → 发注册请求（含 MAC）
          └─ 教师端分配 terminal_id + 计算 IP
          └─ 终端写入 .terminal_config（flush+fsync）
          └─ 注册完成，进入心跳循环

2. 上课流程

教师端点「开始上课」
  └─ 选择模板 VM
  └─ 批量链式克隆（PVE API）
      └─ 每台 VM 绑定对应终端 MAC
      └─ 批量 start VM
  └─ 终端收到桌面就绪信号
      └─ SPICE 连接 PVE VM
      └─ 终端屏幕显示 Windows 启动过程
  └─ VM 内 Guest 程序启动
      └─ guest-service 向教师端发 Guest 心跳

3. 下课流程

教师端点「结束下课」
  └─ 批量 stop VM（PVE API）
  └─ 终端 SPICE 断开，屏幕关闭
  └─ VM 差异盘回收
  └── 课堂环境清除，下节课重新克隆

4. 心跳与状态

终端心跳（终端 → 教师端）
  ├─ 协议：TCP 8790
  ├─ 内容：MAC + terminal_id + 终端状态
  └─ 超时：教师端 60s 未收到 → 标记离线

Guest 心跳（VM 内部 → 教师端）
  ├─ 协议：通过 SPICE 通道或独立 TCP
  ├─ 内容：VM 内部状态
  └─ 超时：60s 未收到 → Guest 状态过期

SPICE 连接状态（PVE API）
  └─ 教师端轮询 PVE ss 输出判断桌面是否接入

五维度独立原则：终端在线 ≠ VM 运行 ≠ SPICE 接入 ≠ Guest 活跃 ≠ VM 存在。详见 终端详情页。

配置文件位置与字段

终端侧

教师端侧

PVE 侧

版本历史与变更

终端程序版本

教师端版本

关键设计决策记录

PVE 官方文档索引

云课堂基于 Proxmox VE 构建。以下 PVE 官方文档在部署和运维中会频繁引用：

机器角色速查