Skip to content

About

EduGate standalone classroom edition for teacher PCs

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

EduGate - Local AI Teaching Gateway

EduGate 单机课堂版

中文 · English

EduGate 在教师的 64 位 Windows 电脑或 Apple 芯片 Mac 上运行,面向单教师、单节课或小型课堂。教师用 Web 控制台配置模型、知识库和课堂策略;学生通过局域网课堂链接加入。管理数据、课堂记录和知识库保存在教师电脑中。

它也可以作为教室内的 AI 中转站:为后端应用提供 OpenAI-compatible API,为学习单和网页课件提供带学生会话隔离的流式接口。

v2.4.1:便携课堂、完整 AI 试问与界面对齐

  • Windows 使用“便携文件夹+一个 EXE+网页操作”,换电脑携带完整文件夹;支持目录隔离、安全退出和保留资料的程序升级。
  • 教师端统一为“控制、记录、资源、系统”;资源与系统按任务分组选项卡。
  • “资源 → 黑名单与试问”可直接生成学生会收到的最终回答,沿用已保存的模型、教学策略、资料范围及黑名单,并展示检查结果和引用。支持连续追问及新一轮试问,不写入学生课堂记录,课前也能使用。
  • 2.4.1 补齐卡片标题、选择框、按钮及备份/升级双栏的对齐;两级导航随滚动贴合,试问显示模型名称,长提问可折叠展开。见视觉检查记录。
  • 本次提供 Windows x64 Release。macOS 源码继续维护,本次不提供新的 macOS 二进制包。

历史发行包与代码演进见 2.3 → 2.4 过程归档。历史运行源码按发行包核验还原,并明确标注补录日期和范围。

现在的边界

  • 只有一个教师管理员账号,不提供多教师账号和策略 API。
  • 学生使用课堂令牌换取各自的学生会话,不接触教师令牌。
  • 默认 ALLOW_LAN_ADMIN=false:教师管理页、登录和管理 API 只允许教师本机访问。平板管理需同时启用局域网管理并把设备 IP 加入 ADMIN_ALLOWED_IPS。
  • 学生页面可在同一局域网访问;课堂令牌持久保存,开课、下课和程序重启都不改变链接。下课会撤销当前学生会话,主动换链才会淘汰旧链接。
  • 源码要求 Python 3.10+;打包版自带运行环境,不要求教师电脑安装 Python。
  • 学生 Python 在学生浏览器的独立 Worker 中执行,离线运行环境随项目分发;教师服务器只下发策略和接收标明“不可信上报”的结果,不再执行学生代码。
  • 下游后端使用独立平台密钥;浏览器网页只能用课堂令牌换取学生会话,不能接触平台密钥。
  • 教师可在系统页上传 HTML/ZIP 并发布为正式学生入口;内置 IP 学习单仅为 Demo,课堂未开始时两类页面都不能使用课堂服务。

快速开始

打包版

  1. Windows:解压完整 EduGate-Standalone 文件夹,不要只复制 EXE;双击 EduGate-Standalone.exe。
  2. Apple 芯片 Mac:解压 ZIP,可把 EduGate.app 拖入“应用程序”;首次启动时按住 Control 点击应用并选择“打开”。
  3. 在“系统 → 模型服务”添加供应商并保存接口配置,再获取并导入模型;配置和密钥会保存在本机文件中,下次打开自动恢复。
  4. 正式教学可在“系统 → 网页发布”上传 HTML/ZIP;不上传时入口使用内置 Demo 测试页。
  5. 保存教学策略、课堂范围与黑名单后,先在“资源 → 黑名单与试问”生成回答并核对引用;确认后点击“开始课堂”,再把链接或二维码发给学生。
  6. 下课点击“结束课堂”;携带 U 盘离开时使用“结束课堂并退出”,等待保存完成确认。

打包版初始账号为 admin、密码为 edugate。本机默认自动进入,首次使用后仍建议修改密码。Windows 数据位于程序同目录的 config 和 data;macOS 数据位于 ~/Library/Application Support/EduGate。迁移前先创建备份,再点击“结束课堂并退出”,等待退出确认后安全弹出 U 盘。

macOS 为支持本机备份和迁移,模型密钥使用可迁移的便携格式保存;目录权限限制为当前用户访问。不要共享整个 EduGate 数据目录,也不要把它上传到公开网盘或代码仓库。

当前 macOS Release 支持 macOS 11+ 的 Apple Silicon(arm64),不支持 Intel Mac。发布包采用 ad-hoc 签名,未使用 Apple Developer ID 公证,因此首次启动需要使用上面的 Control 点击打开方式。

源码版

安装 64 位 Python 3.10 或更高版本。Windows 可运行:

desktop\install_backend_deps.bat
desktop\run_standalone.bat

macOS 可运行:

python3 -m venv runtime/venv
runtime/venv/bin/python -m pip install -r backend/requirements.txt
runtime/venv/bin/python desktop/edugate_standalone.py

学生如何分发

教师登录后即可复制固定课堂链接;点击“开始课堂”才会开放该入口。未发布自定义网页时使用内置 Demo 测试页:

http://教师电脑局域网IP:端口/student.html#class_token=...

发布正式教学网页后,入口自动变为:

http://教师电脑局域网IP:端口/published.html#class_token=...&page=...

链接由教师电脑局域网 IP 和持久课堂令牌共同定位一台 EduGate。只要没有主动点击“换一个链接”,同一链接可跨课次、跨班级和程序重启复用,适合提前嵌入课件。每次“开始课堂”仍会创建新的课堂记录批次;“结束课堂”会暂停入口并撤销当前学生会话,下次开课时原链接恢复可用。

点击“复制链接”,通过班级群、教学平台或投屏发给学生;也可以直接使用控制页生成的二维码。二维码同样包含课堂令牌,不应放到公开网站或公开群组。

学生无需填写姓名或电脑名。浏览器会生成稳定设备标识,服务据此创建设备标签和独立学生会话。详细流程见 使用手册 和 架构与安全边界。

局域网地址从已连接的非虚拟 IPv4 网卡中自动选择,避免把 VPN/TUN 地址作为入口。多网卡时可在“系统 → 高级设置 → 学生入口 IP”选择或填写 LAN_ADVERTISE_IP,保存并重启。该项只决定分发地址,不改变监听地址或教师 IP 白名单。

下游接口与网页嵌入

教师端“系统 → 接入配置”提供可复制配置和代码:

  • 后端程序:GET /v1/models、POST /v1/chat/completions,使用 Authorization: Bearer <平台密钥>;Base URL 为 http://教师IP:端口/v1,稳定模型名为 edugate。
  • 教学网页:加载 assets/edugate-client.js,用持久 class_token 换取独立 X-Student-Token,再调用 /chat/stream 获取 SSE 流式回答。
  • 托管教学网页:在系统页上传 HTML/ZIP,EduGate 通过隔离沙箱发布,并向网页提供 EduGate.ask() 流式桥接;控制页链接和二维码自动切换到活动网页。
  • Python:外部网页使用 EduGateClient.runPython(),托管网页使用 EduGate.runPython();均在学生设备内执行。旧 /run_python、/run_python/stream 在鉴权后返回 410 Gone,接入方需迁移。

edugate 会执行教师当前选择的上游模型、提示词和知识库,下游无需在教师调整策略后修改代码。固定平台密钥保存在 data/secrets.json,可在教师端显示或复制,重启不更换;新生成的密钥共 25 字符,已有密钥保持原样。平台密钥只能放在可信后端。教学网页默认推荐通过 EduGate 发布,复制嵌入代码即可接入,无需额外 SDK 或跨域设置;只有放在其他网站时才需配置 CORS_ORIGINS 并重启。完整示例见 下游接口与网页嵌入。

角色、权限与鉴权

flowchart LR
    subgraph roles["访问角色"]
        teacher["教师管理员<br/>唯一管理账号"]
        student["学生浏览器<br/>每台浏览器独立会话"]
        platform["平台集成<br/>可选 OpenAI-compatible 客户端"]
        anonymous["未认证访问者<br/>仅公共状态与静态页面"]
    end

    subgraph gateway["EduGate 权限边界"]
        admin_api["教师管理范围<br/>模型与供应商、课堂策略、知识库<br/>网页发布、课堂启停与记录、备份和系统设置"]
        classroom_api["学生课堂范围<br/>打开活动网页、加入课堂、AI 对话<br/>获取 Python 策略、上报结果"]
        platform_api["平台接口范围<br/>/v1/models、/v1/chat/completions"]
        public_surface["公共范围<br/>/health、/auth/status、学生静态页"]
    end

    teacher -->|"本机或精确 IP 白名单<br/>X-Admin-Token 教师会话"| admin_api
    student -->|"教师 IP + 持久 class_token<br/>换取 X-Student-Token"| classroom_api
    student --> browser_python["学生设备内<br/>隔离 Worker 执行 Python<br/>无教师文件系统或凭证桥接"]
    platform -->|"Authorization: Bearer PLATFORM_API_KEY"| platform_api
    anonymous -->|"无鉴权;不包含管理能力"| public_surface

    admin_api --> local_data["教师电脑本地数据<br/>SQLite、知识库、运行配置、密钥"]
    classroom_api --> default_policy["唯一 default 课堂策略"]
    platform_api --> default_policy
    default_policy --> upstream["模型供应商 API"]
Loading
角色 权限范围 鉴权方式 默认网络范围
教师管理员 模型供应商、课堂策略、知识库、教学网页发布、课堂启停、课堂记录、备份和系统设置 登录或本机自动登录后使用 X-Admin-Token;管理 API 同时校验来源 IP 默认仅教师电脑;平板管理需设置 ALLOW_LAN_ADMIN=true 和精确 ADMIN_ALLOWED_IPS 白名单
学生 打开当前活动教学网页、加入课堂、AI 对话;浏览器内运行 Python 并上报结果 教师 IP 定位服务;持久 class_token 换取绑定课次的 X-Student-Token 结束/重开/换链撤销旧会话并取消旧 AI 请求;旧 Python 结果不得写入新课次;浏览器本地计算不代表服务器权限
平台集成 查询虚拟模型并调用 /v1/chat/completions,执行当前教师策略 Authorization: Bearer PLATFORM_API_KEY 取决于服务监听地址;单机首次自动初始化固定密钥,可在系统页关闭;密钥不得嵌入网页
未认证访问者 健康状态、初始化状态和允许公开的静态资源 无 教师管理页、API 文档和管理接口仍受来源与会话保护

IP 白名单是局域网准入控制,不是可替代密码的身份认证:设备 IP 可能因 DHCP 变化,也可能在不可信网络中被冒用。因此白名单设备仍需教师账号和 X-Admin-Token,建议给管理平板设置 DHCP 地址保留。

class_token、X-Student-Token、X-Admin-Token 和 PLATFORM_API_KEY 都属于 Bearer 凭证,应避免写入公开日志、截图或公开二维码服务。持久课堂令牌保存在 data/secrets.json,随完整备份和便携目录迁移。

关闭平台接口会持久保存“禁用”状态,即使环境中仍有 PLATFORM_API_KEY,重启或迁移后也不会自动恢复;需主动保存或生成新密钥。已发出的上游请求无法追溯撤回,关闭影响后续平台请求。

代码结构

EduGate-standalone/
├─ backend/
│  ├─ app/
│  │  ├─ main.py                # FastAPI 装配、中间件、路由注册和静态页面挂载
│  │  ├─ config.py              # 环境变量和浏览器 Python 策略配置
│  │  ├─ state.py               # 应用生命周期及共享服务实例
│  │  ├─ dependencies.py        # 教师、学生和平台接口鉴权依赖
│  │  ├─ schemas.py             # Pydantic 请求、响应和持久化模型
│  │  ├─ runtime_config.py      # 模型目录与唯一 default 课堂策略
│  │  ├─ chat_service.py        # 模型路由、知识检索、普通及流式对话
│  │  ├─ classroom_tasks.py     # 课次撤销、排队取消与流式任务生命周期
│  │  ├─ network.py             # 本机网卡枚举和学生入口 IP 选择
│  │  ├─ published_pages.py     # 教学网页校验、存储、活动入口和资源约束
│  │  ├─ api_docs.py            # OpenAPI 标签和接口说明
│  │  ├─ core.py                # 旧导入路径兼容门面;不承载新业务
│  │  ├─ routers/
│  │  │  ├─ auth.py             # 教师初始化、登录、退出和改密
│  │  │  ├─ classroom.py        # 课堂启停、学生加入和课堂记录
│  │  │  ├─ chat.py             # 学生对话及平台兼容接口
│  │  │  ├─ config.py           # 当前课堂模型和策略配置
│  │  │  ├─ knowledge.py        # 知识库来源、文件和索引管理
│  │  │  ├─ models.py           # 模型供应商、发现、导入和删除
│  │  │  ├─ python.py           # 浏览器执行策略、结果上报及运行环境资源
│  │  │  ├─ publishing.py       # 教学网页上传、切换、删除和学生读取
│  │  │  └─ system.py           # 状态、日志、备份、恢复和服务控制
│  │  ├─ db.py                  # SQLite 管理状态、请求日志和课堂记录
│  │  ├─ knowledge.py           # 本地资料解析、切片和检索
│  │  ├─ litellm_client.py      # OpenAI-compatible 上游 HTTP 客户端
│  │  ├─ security.py            # 会话、课堂令牌和限流基础设施
│  │  └─ system_ops.py          # 备份、恢复、目录与高级设置
│  ├─ tests/                    # 后端、权限、分发和回归测试
│  ├─ requirements.txt          # 运行依赖
│  └─ requirements-dev.txt      # 开发与测试依赖
├─ frontend/
│  ├─ admin.html                # 教师控制台
│  ├─ student.html              # 内置 Demo 测试页
│  ├─ published.html            # 教学网页安全包装页和流式桥接
│  ├─ assets/edugate-client.js  # AI 流式与浏览器 Python 接入 SDK
│  ├─ assets/edugate-python.js  # 浏览器执行控制、实时输出、超时和停止
│  ├─ assets/python-sandbox.js # 无同源权限 iframe 内的 Worker 控制器
│  ├─ assets/vendor/pyodide/    # 固定版本的离线 Python/WASM 和许可说明
│  └─ assets/brand/             # EduGate 图标和横向标识
├─ desktop/
│  ├─ edugate_standalone.py     # Windows / macOS 后台监督启动器
│  ├─ run_standalone.bat        # 源码日常启动
│  ├─ install_backend_deps.bat  # Python 3.10+ 依赖环境安装
│  ├─ build_windows.bat         # Windows 便携目录打包
│  └─ build_macos.sh            # macOS Apple Silicon 应用打包
├─ docs/                        # 使用、安装、安全和开发文档
├─ samples/                     # 示例资料
└─ .github/workflows/           # Python 3.10 / 3.12 回归测试

app/core.py 只保留旧导入路径兼容;新增功能应放入对应服务或路由模块。

Windows 打包版首次运行后会在 EXE 旁创建 config/ 和 data/;macOS 打包版使用 ~/Library/Application Support/EduGate。这些目录包含密码设置、数据库、知识库、教学网页、模型密钥和课堂记录,不属于源码目录,也不应提交到 GitHub。

知识库索引使用相对路径;升级时将可识别的旧绝对路径转换为当前知识库目录内的路径。复制后的程序只操作自己的资料,拒绝越界路径和目录链接。无法安全转换的异常历史索引会报错,不会访问原位置。

开发验证

知识库使用本地 LanceDB + FastEmbed 中文混合检索,保留教材章节/页码,并支持课堂文件、版本和章节范围。教师可在“资源 → 黑名单与试问”设置禁答话题;规则同时覆盖普通、流式和兼容接口,检查失败时暂不作答。详见知识库与课堂黑名单及升级验收记录。

python -m pytest -q -p no:cacheprovider -m "not e2e" --basetemp=.pytest-tmp --cov=backend/app --cov-branch --cov-report=term --cov-fail-under=85
python -m compileall -q backend\app

Windows 打包运行 desktop\build_windows.bat,输出位于新的 dist/releases/版本-时间/ 目录,并生成可用于网页升级的 ZIP。Apple Silicon Mac 使用 Python 3.10–3.12 运行 EDUGATE_VERSION=2.4.1 desktop/build_macos.sh,保持 macOS 11 兼容目标。打包脚本会准备并包含本地语义模型。

文档

英文概览见 README.en.md。

U 盘运行与保留数据升级

日常只需双击完整便携目录内的 EXE。换电脑时携带整个文件夹;“结束课堂并退出”会保存并关闭后台,Windows 在进程完全退出后给出确认。程序升级在“系统 → 备份与升级”选择发布 ZIP,保留 config、data,并保存原程序副本。详细流程、目录隔离和验证边界见 便携运行与升级。

About

EduGate standalone classroom edition for teacher PCs

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages