Skip to content

About

开放课堂

Resources

Security policy

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

88 Commits

Folders and files

Repository files navigation

OpenClass-Box

面向课堂教学一体机的开源运维工具箱(Windows 桌面端)。

场景很具体:教室一体机被学生装乱了、投屏断了、触摸失灵、白板闪退、老师上课前发现没声音 —— 电教委员要在最短时间里判断问题、修好它,最好还能远程看一眼。 OpenClass-Box 把这些事收进一个绿色便携的程序里:插上就能用,不装服务、不注册、离线可用。

当前版本 0.1.5 Beta。版本号的唯一来源是 version.json, 由 python scripts/sync_version.py 同步到各处(打包时会自动执行)。


功能一览

模块 说明
系统状态 CPU / 内存 / 磁盘 / 网速实时曲线、公网 IP(手动触发)、硬件快照
硬件信息 CPU、显卡(含核显,虚拟显示适配器自动过滤)、内存条、硬盘健康与温度、主板、BIOS
机房管理 A 端=服务端(管理端)· B 端=本体(被管理端):设备列表、批量下发体检 / 修复 / 清理 / 消息 / 文件 / 换壁纸、远程电源控制、定时下发
维护 课堂检测(投影 / 触摸 / 无线投屏 / 教学软件 / 还原环境)· 一键体检 · 一键修复 · 磁盘清理 · 网络诊断 · 诊断包 · 学期模式 · 便携急救盘
工具箱 工具网格 + 分类筛选 + 关键词搜索;插件市场(JSON 索引 + 一键安装 + 离线导入)
手机 Web 控制台 同一 WiFi 下手机浏览器打开就能看状态、跑体检、远程修复,零安装、不连外网
A 端远程管理(Web) 通过内网穿透在教室外管理整个机房:设备列表 / 下发指令 / 电源控制 / 文件下发 / 操作审计
内网穿透套件 cloudflared / frp / ngrok / 自定义命令,自动抓公网地址,参数本地保存
临时传输 局域网内"用完即走"的聊天与文件互传(房间码 + 可选密码,退出即清空)
定时任务 命令 / 脚本(bat、cmd、ps1、vbs)/ 程序,支持每天、每周、一次性、开机后
安全 风险网址检测、剪贴板与浏览器行为监测、五项系统防护(浏览器篡改 / USB / 自启动 / 弹窗 / 高占用)、密码保护
音乐 本地曲库 + 在线搜索到本地缓存后播放,播放队列 / 进度 / 音量 / 循环
壁纸 静态图片(含位置与缩放)+ 动图 / 视频(mpv 渲染到桌面层)+ 导入管理
兼容性知识库 内置常见问题条目 + 按本机环境自动匹配 + 记录经验 + 导出问题报告
设置 主题、系统集成(自启 / 托盘 / 关闭行为 / 启动行为)、被链接(B 端)、远程管理、局域网放行、存储位置与保存诊断、更新检测

技术栈

层 选型
界面渲染 WebView2(Windows 系统组件;安装包内附固定版本运行时兜底)
前端 React 18 + TypeScript + Vite + Fluent UI v9
宿主 Python 3.13 + pywebview
系统监测 psutil + WMI(PowerShell CIM)+ 注册表 + 系统命令
局域网 纯标准库 ThreadingHTTPServer + UDP 发现 + 长轮询
打包 PyInstaller(--onedir)+ Inno Setup 6

业务逻辑全在 Python 侧;工具与插件一律独立进程启动,崩溃不会拖垮主界面。


快速开始

pip install -r requirements.txt

cd frontend
npm install
npm run build

cd ..
python main.py            # 加载 frontend/dist
python main.py --dev      # 连接 vite 开发服务器(配合 npm run dev)
python main.py --debug    # 开启 WebView 调试
python main.py --role=a   # 以 A 端(服务端)启动;--role=b 为 B 端

健康检查(不启动界面):

python scripts/smoke.py

打包与安装包:

python pack.py                    # PyInstaller 打包(自动同步版本号、清理旧产物)
iscc OpenClass.iss                # B 端安装包
iscc /DRoleNum=1 OpenClass.iss    # A 端安装包(不含大体积第三方工具)

目录结构

OpenClass/
├── main.py                  # 开发态入口
├── pack.py                  # 打包脚本(版本同步 / 启动自检 / 清理旧产物)
├── OpenClass.iss            # Inno Setup 安装包脚本(A/B 共用,靠 /DRoleNum 区分)
├── version.json             # 版本号唯一来源
├── SIGNING.md               # 代码签名与供应链验证(sigstore / SignPath)
├── RELEASE_NOTES.md         # 发布说明
├── backend/
│   ├── main.py              # pywebview 宿主:窗口、托盘、启动流程
│   ├── api.py               # 前端 ⇄ Python 的唯一边界
│   ├── core/                # 业务模块(配置、路径、监测、体检、修复、安全、插件、任务…)
│   ├── net/                 # 局域网协同(协议、发现、服务端、客户端、指令)
│   └── system/              # 托盘、开机自启、文件关联、单实例
├── frontend/
│   └── src/
│       ├── app/ 组件/ 页面/ 样式
│       ├── api.ts           # 后端调用封装(内置 mock,可脱离宿主预览界面)
│       └── pages/           # 各功能页面
├── plugins/                 # 示例插件(课堂计时器 / 随机点名)+ 索引 index.json
├── scripts/
│   ├── smoke.py             # 冒烟检查
│   └── sync_version.py      # 版本号同步与校验
├── docs/                    # 文档(含 ROADMAP)
└── tools/                   # 工具与插件目录(体积大,不入库;首次运行自动创建)

tools/ 不随仓库分发:里面是第三方二进制(OpenOffice / VLC / mpv 等)与用户插件。 运行后目录会自动创建;安装包在打包时把需要的组件一并带上。


插件机制

在 tools/(或从插件市场安装到)一个文件夹,放入 tool.json 与入口文件即可,无需改任何代码:

{
  "id": "classroom-timer",
  "name": "课堂计时器",
  "description": "倒计时 / 正计时,空格开始、F 全屏",
  "category": "classroom",
  "version": "1.0.0",
  "author": "OpenClass",
  "entry": "index.html"
}

支持的入口:.exe / .bat / .cmd / .ps1 / .py / .html(网页类插件直接用默认浏览器打开)。

插件市场只做三件事:读 JSON 索引 → 下载 → 校验 sha256 后解压。 安装过程额外做了防目录穿越、解压总量限制、只允许 https;卸载只删 tools/ 下带 tool.json 的目录。


安全与签名

  • 代码签名:发布包由 GitHub Actions 做 sigstore 无密钥签名,签名与证书写入 Rekor 透明日志, 任何人可用一条命令验证"文件确实出自本仓库 CI 且未被篡改"。详见 SIGNING.md。
  • Windows Authenticode:已按 SignPath Foundation 的要求准备申请材料(同一份文档第四节)。
  • 远程管理:默认关闭;访问码强制 ≥8 位、失败锁定、默认只接受内网来源; 危险动作(电源)二次确认 + 延迟执行 + 全程审计;电源只下发给 B 端,A 端自身永不执行。 演示或培训可设 OPENCLASS_SAFE_TEST=1,此时电源操作只记录、不执行。
  • 数据主权:所有配置与运行时数据都写在程序目录(或用户目录)的 data/ 下,不上传任何服务器。

设计取舍

  • 便携优先:数据跟随程序目录,整个文件夹可以拷进 U 盘;装到 Program Files 这类受保护位置时 自动改用用户目录 —— 避免"管理员与普通用户看到的不是同一份配置"。
  • 离线可用:除公网 IP、更新检测、插件市场外无网络依赖;教室没外网时功能不打折。
  • 如实反馈:拿不到的数值一律显示"不可用"而不是编一个;失败要给出可读原因(DNS / 超时 / 限流 / 权限)。
  • 进程隔离:工具之间、工具与主程序互不影响。
  • 配置可靠:配置采用原子写 + 失败自动回退,设置页可直接看到"最近一次保存"的结果。

已知限制

  • WinPE 急救盘需微软 ADK 与数 GB 镜像,当前以 USB 便携急救盘覆盖大部分场景
  • 离线 AI 诊断解读暂缓(本地小模型会使包体增加数百 MB)
  • 动态壁纸依赖 tools/mpv/,且不同 Windows 版本的桌面承载窗口(WorkerW)结构有差异,已在代码里做四级兜底
  • 部分功能需要管理员权限并触发 UAC(结束进程、网络重置、创建还原点等)
  • 局域网相关功能需要防火墙放行(设置页提供一键放行)

许可证

MIT License. 见 LICENSE。随包分发的第三方组件各自保留原许可证(清单见 SIGNING.md 第 4.3 节)。

About

开放课堂

Resources

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages