Skip to content

Cluss 集成 ​

Cluss 是旁挂在 ClassIntra 之外的同校系统(对话 / 批改 / 写作等,一班一节点)。它不在 ClassIntra 主仓库内,而是作为独立服务与 CI 并存于同一台服务器,通过四条通道与 ClassIntra 集成:

通道代码位置方向用途
/cluss-app 同源反代server/src/routes/cluss-proxy.jsCI → ClussHTTPS 域名下同源内嵌 Cluss 页面
只读联动桥 /api/cluss-bridgeserver/src/routes/cluss-bridge.jsCluss → CI校验账号、取名册、取学生画像
认证联邦server/keys/jwt-public.pemCluss ← CICluss 用 CI 公钥验 token,免密登录
云盘 bot 硬链接转运apps/resource/backend/bot-transfer.jsCI → AstrBot云盘转存不复制字节,由 bot 硬链接原文件

全部只读、零侵入

联动桥对 ClassIntra 现有逻辑零改动:不碰 auth 中间件、不碰用户表写入,只多挂一个路由前缀;四个端点全部只读。

/cluss-app 同源反代 ​

cluss-proxy.js 把 /cluss-app/* 反代到本机 Cluss 服务 http://127.0.0.1:9003,并剥掉 /cluss-app 前缀——Cluss 以为自己仍在根路径。/cluss-app(无尾斜杠)302 到 /cluss-app/,保证资源相对路径解析标准形态。

为什么必须存在:ClassIntra 开 HTTPS 后,「应用壳里 iframe 一个 http://<host>:9003 的 Cluss」会被浏览器按混合内容直接拦掉(HTTPS 页面里的 HTTP iframe 属于 active mixed content,无开关可放行)。同源反代让 iframe 指向 /cluss-app/,浏览器看到的就是同一个 https://<host>,问题从根上消失。

两个关键实现决策:

  • 挂在 HTTPS 实例的 request 监听层(server/src/app-https.js),而不是 app.use:命中 /cluss-app 的请求绕过全部 express 中间件与 SPA 兜底——compression 会包装 res,SSE 长连接(Cluss 的对话 / 批改 / 写作全是 /api/chat/stream 类流式接口)经过它可能被攒着不发;app.get('*') 的 SPA 兜底若在前面也永远轮不到反代。
  • 仅 HTTPS 实例挂载:HTTP 实例(9001)不挂反代,因此该通道仅 HTTPS 域名可用。

与 Cluss 侧的约定:Cluss 前端资源用相对路径(vite base: './')、API 前缀由页面路径推导;Cluss 的 token cookie 名(cluss_token)与 CI 的 token 不同名,同域并存不互相覆盖。

只读联动桥 /api/cluss-bridge ​

让 Cluss 能校验 ClassIntra 账号,实现「CI 用户直接登录 Cluss」。鉴权头 X-Bridge-Secret,值与 RELAY_SECRET 共用同一密钥(刻意不再新增一个要运维同步的密钥);未配置 RELAY_SECRET 时直接拒绝服务(503),密钥比对用时序安全比较。

端点说明
GET /ping存活探测(Cluss 启动时判断联动是否可用)
POST /verify账号口令校验,唯一返回 password_hash 的端点
GET /class-roster取某班名册(year + classNo,SQL 内按 user_id 编码精确限定,结构上不可能带出别的班)
GET /student-profile学生画像素材(逐列脱敏白名单)

/verify 的返回(禁用账号回 200 + data.disabled,便于 Cluss 侧区分「密钥不对」与「账号被禁用」):

json
{
  "code": 200,
  "data": {
    "disabled": false,
    "user": {
      "user_id": "25081801",
      "net_name": "网名",
      "real_name": "姓名",
      "password_hash": "…(供 Cluss 侧离线登录校验,同 relay-verify 既有约定)",
      "is_class_admin": true,
      "is_admin": false
    }
  }
}

is_class_admin / is_admin 班管标志供 Cluss 侧授予管理权。除 /verify 外其余端点不返回任何凭据类字段;手机号 / QQ / 微信 / 住址等隐私列一律不外传。

认证联邦(RS256 公钥) ​

ClassIntra 自 v1.4.0 起 JWT 签发统一为 RS256:私钥不出本机,需要验 CI token 的其他服务拿到的是公钥。Cluss 验 CI 签发的 token 用 server/keys/jwt-public.pem 公钥验签——不再有共享 CI_JWT_SECRET 的说法(旧方案已废弃)。

  • Cluss 侧登录后的会话 token 由 CI 签发、Cluss 用公钥本地验签,免登进入;
  • 跨班 / 离线校验走既有的 POST /api/auth/relay-verify,鉴权头 X-Relay-Secret == RELAY_SECRET(与联动桥同值)。

云盘 bot 硬链接转运 ​

Cluss 的 AstrBot 机器人用 yt-dlp 下载的视频落在 Resources/cloud/botmedia/remote/。学生把这些文件转存进云盘时,ClassIntra(v1.5.0 起)不再复制字节,而是调 AstrBot 插件的转运接口把原文件硬链接进云盘:

学生点「转存云盘」
  → CI apps/resource/backend/bot-transfer.js
  → POST http://127.0.0.1:6200/api/cloud/transfer(AstrBot 插件)
  → bot 把原文件硬链接进 cloud/shared/<hash>(同盘零占用;跨盘回退普通复制)
  → CI 侧只写 DB 记录,物理层归 bot
  • 转运接口不可达时自动回退本地复制,功能不中断;
  • 环境变量(均在 server/.env,不配即走默认值):
变量默认说明
BOT_TRANSFER_URLhttp://127.0.0.1:6200AstrBot 插件 api_server 地址
BOT_TRANSFER_TOKEN空对应插件 api_token;留空 = 插件未开鉴权时不带头部
BOT_TRANSFER_TIMEOUT_MS10000转运超时(本地硬链接是毫秒级操作)

存量治理:历史版本复制产生的重复文件可用 scripts/cloud-bot-relink.mjs 统一重链回收。

第三方实时事件 ​

Cluss 相关的实时事件(班级状态同步等)走 ClassIntra 统一的第三方实时事件通道(自 v1.4.0):WS 优先——上行经核心 WS 发消息 type realtime_publish,下行以 type extension_event 推给在线用户;HTTP 长轮询兜底。机制详见 WebSocket 通信。

基于 MIT 协议 开源 · 加入 QQ 群【ClassIntra】
本项目 LOGO 来源于公共素材库,仅用于非商业教育目的,权利归其各自所有者;与其他项目 LOGO 的相似纯属巧合。
The logo is sourced from a public domain asset library and is used for non-commercial, educational purposes only.