中文 · English
EduGate 在教师的 64 位 Windows 电脑或 Apple 芯片 Mac 上运行,面向单教师、单节课或小型课堂。教师用 Web 控制台配置模型、知识库和课堂策略;学生通过局域网课堂链接加入。管理数据、课堂记录和知识库保存在教师电脑中。
它也可以作为教室内的 AI 中转站:为后端应用提供 OpenAI-compatible API,为学习单和网页课件提供带学生会话隔离的流式接口。
- 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,课堂未开始时两类页面都不能使用课堂服务。
- Windows:解压完整
EduGate-Standalone文件夹,不要只复制 EXE;双击EduGate-Standalone.exe。 - Apple 芯片 Mac:解压 ZIP,可把
EduGate.app拖入“应用程序”;首次启动时按住 Control 点击应用并选择“打开”。 - 在“系统 → 模型服务”添加供应商并保存接口配置,再获取并导入模型;配置和密钥会保存在本机文件中,下次打开自动恢复。
- 正式教学可在“系统 → 网页发布”上传 HTML/ZIP;不上传时入口使用内置 Demo 测试页。
- 保存教学策略、课堂范围与黑名单后,先在“资源 → 黑名单与试问”生成回答并核对引用;确认后点击“开始课堂”,再把链接或二维码发给学生。
- 下课点击“结束课堂”;携带 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"]
| 角色 | 权限范围 | 鉴权方式 | 默认网络范围 |
|---|---|---|---|
| 教师管理员 | 模型供应商、课堂策略、知识库、教学网页发布、课堂启停、课堂记录、备份和系统设置 | 登录或本机自动登录后使用 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\appWindows 打包运行 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。
日常只需双击完整便携目录内的 EXE。换电脑时携带整个文件夹;“结束课堂并退出”会保存并关闭后台,Windows 在进程完全退出后给出确认。程序升级在“系统 → 备份与升级”选择发布 ZIP,保留 config、data,并保存原程序副本。详细流程、目录隔离和验证边界见 便携运行与升级。