Skip to content

市场应用生命周期 ​

ClassIntra 市场应用是独立于官方内置应用的第三方应用包。班管负责安装、更新和卸载,班级成员通过实时同步获得统一的应用状态。

先读开发指南

本页讲生命周期、管控与发布。写应用本身(三种形态、兼容红线、令牌、context.*)请看 第三方应用开发;存量项目迁入见 存量项目迁入指南;包格式规范全文见 应用包格式开放规范。

相关仓库 ​

用户如何获取应用 ​

用户不需要克隆或下载整个 market 仓库,也不需要 ClassIntra 官方提供一台公共服务器。运行 ClassIntra 的班级服务器会直接读取 GitHub Raw 上的 catalog,并按应用文件清单逐个下载:

text
https://raw.githubusercontent.com/ClassIntra/market/main/index.json
https://raw.githubusercontent.com/ClassIntra/market/main/apps/gomoku/manifest.json

catalog 读取接口(GET /api/market/catalog)自 v1.3.0 起需要登录——由服务端代拉并自动附带 Bearer Token,客户端无需额外处理。

应用文件下载到班级服务器的本地运行时目录后,前端和后端都从本地加载。GitHub 只承担公开文件托管和版本来源,ClassIntra 负责安装、缓存、更新和卸载。

安装流程 ​

  1. 市场目录从 Local 或 GitHub source 读取 index.json。
  2. 服务端校验应用名、manifest、文件路径、文件数量和文件大小。
  3. 服务端校验 sdk 版本、能力声明、角色白名单与布局偏好(详见下节)。
  4. 应用先写入临时目录,再原子替换运行时目录。
  5. 服务端热挂载应用后端路由。
  6. 客户端刷新市场注册表和动态路由。
  7. 应用出现在桌面入口,并可按需加载前端脚本和样式。

安装不要求重启服务。

安装限制与文件白名单 ​

安装校验对包体有硬性上限(防误装巨型包拖垮班级服务器):

限制默认值部署端覆盖环境变量
单应用文件数300MARKET_MAX_FILES
单文件大小60MBMARKET_MAX_FILE_MB
单应用总大小80MBMARKET_MAX_TOTAL_MB

扩展名走白名单(Web 资源 + 多语言源码与工程文件,如 .py / .go / .rs 等,供独立端口服务形态携带任意语言实现)——.vue 不在白名单内(市场应用不参与构建)。

安装前校验:能力披露与约束 ​

ClassIntra 采开放模型——不设沙箱,不拦截能力调用。但安装前仍会做四类校验,目的是把问题说清楚而不是静默失败。

校验项行为
sdk 版本高于当前系统主版本 → 阻断安装,提示升级 ClassIntra
capabilities未知能力名 → 警告(不阻断),披露不准确但不影响运行
visibleRoles未知角色名 → 阻断安装(会产生「谁都看不到」的静默 bug)
layout.mode不在枚举中 → 阻断安装

能力披露展示 ​

capabilities 字段用于在安装确认页向班管展示「这个应用会用到什么」。它是披露,不是权限申请——不声明也能调用,只是审核与信任链会缺一环。

十六项已知能力清单见 第三方应用开发 § capabilities。

角色可见性 ​

visibleRoles 控制哪些角色能看到该应用:

json
{ "visibleRoles": ["classAdmin", "officer"] }

合法值:classAdmin(班管)/ admin(系统管理员)/ officer(班干部)/ student(学生)。空数组 = 全部可见。

未知角色名会阻断安装

写错角色名(如 "teacher")会导致应用对所有人不可见,且不报错——所以在安装阶段就拦截。合法值只有上面四个。

提交前预检与静态审查 ​

装前预检与静态审查是发布前的两道闸:

bash
# 从 ClassIntra 主仓库根目录运行

# 装前预检:与安装时同一校验器 + 文件完整性 + 路由冲突(覆盖 market-apps/ 与本地市场源 ../market/apps/)
node scripts/diag.js market <应用名>

# 静态审查:五组规则扫描源码
node scripts/market-review.mjs <应用目录>

# 机器可读输出
node scripts/market-review.mjs market-apps/gomoku --json

脚本按五组检查:

组检查内容
A. manifest必填字段、路由前缀、sdk 版本、能力/角色合法性
B. Chrome 80 语法const/let/箭头函数/模板字符串/?./??/class/async
C. CSS 兼容flex gap、:is()、aspect-ratio、transition: all、布局属性过渡、自造圆角与曲线
D. 危险 APIeval、new Function、innerHTML 直插、document.write
E. 资源回收用了监听器/定时器/实时订阅却未调 context.app.onDestroy

输出示例:

text
市场应用静态审查: market-apps/gomoku
============================================================

能力披露(安装页将向班管展示)
------------------------------------------------------------
  · data.http
  · data.realtime
  · data.storage
  · ui.toast
  · ui.modal
  · app.storage
布局模式: fullscreen
所需 SDK: v1

============================================================
错误 0 项,警告 0 项
未发现问题。

这是审查辅助,不是运行时隔离

脚本只做静态扫描。它帮你在提交前发现问题,不在运行期拦截任何行为。同页面自由模型下,最终责任在开发者。

本地开发与双仓同步 ​

market-apps 前端是直出型:服务器从 /market-static/<name>/ 以 no-cache 头直接下发源码文件,没有构建步骤——保存后刷新浏览器即生效。因此本地开发循环非常短:

bash
# 边改边查:自动跑 Chrome 80 兼容 lint,文件变化时重跑并提示刷新(防抖 300ms)
node scripts/build-app.js my-app --watch

# backend/ 有改动时单独提示需重启服务器(或用 CLASSINTRA_HOT_RELOAD=1 启动实现后端热重载)

完整的开发循环(生成骨架 → 直出调试 → 静态审查 → 双仓同步)见 第三方应用开发 § 开发循环速查。

双仓模型(市场维护者)

主仓 .gitignore 忽略 plugins/ 与 market-apps/,插件与市场应用文件只进 market 仓。在主仓工作区开发后必须用 .\scripts\sync-market.ps1 -App <name> [-Commit "msg"] 镜像同步到 market 仓 apps/<name>/(robocopy /MIR,退出码 0–7 视为成功),再推 market 仓发布 catalog。命令详见 CLI 工具 § 市场双仓同步。

运行时协议 ​

市场前端入口通过全局 SDK 注册定义:

javascript
window.ClassIntraMarket.define({
  name: 'example',
  mount: function(container, context) {
    container.textContent = 'Hello ClassIntra';
  },
  unmount: function(container) {
    container.replaceChildren();
  }
});

context 按能力域分层(app / data / ui / system / device / theme / router),完整签名见 SDK 参考 § 运行时 context。

应用必须实现可重复挂载和可安全卸载。所有监听器、定时器与实时订阅必须在 context.app.onDestroy 中回收——卸载后的残留会直接表现为界面卡顿。

动态路由与直接访问 ​

市场应用注册是异步过程。直接访问尚未注册的市场路由时,Vue Router 可能先命中通配路由。入口会保存浏览器初始路径,在市场 registry 刷新并注册动态路由后恢复原始路径。

因此下面的访问方式都应进入应用运行时:

text
http://127.0.0.1:5174/gomoku

运行时加载失败时显示统一的加载或错误状态,并提供重试和返回桌面操作。

图标与静态资源代理 ​

市场安装的应用/插件,其 manifest.icon 与静态资源路径不走源站直连:安装时市场服务会把相对路径统一改写为 /api/market/asset?source=<源>&path=<路径> 格式,由 ClassIntra 服务器中转下发。

  • 开发者在 manifest 里照常写相对路径(如 icon.png),无需感知代理细节
  • 好处:图标与应用安装包同源校验、避免浏览器相对路径解析导致的 404、路径穿越防护与 SVG CSP 均在服务端统一收口
  • 图标加载失败时桌面显示占位拼图图标,不会留空白色块

班级统一管控 ​

启用/禁用是班级统一状态。班管修改状态后,服务端广播:

json
{
  "type": "market_app_control_changed",
  "appName": "gomoku",
  "enabled": false,
  "updatedBy": "999999"
}

客户端收到事件后刷新:

  • 市场 registry;
  • 动态路由;
  • 桌面布局;
  • Dock;
  • 文件夹;
  • 小组件;
  • 当前运行实例。

正在使用被禁用应用的成员会自动返回桌面。普通成员不需要自行安装或维护应用包。

更新与卸载 ​

更新使用相同的 manifest 和文件校验,并进行原子替换;成功后重新加载新版本 JS/CSS,不重启服务,且保留启用状态与本地数据。

更新失败会回滚(2026-10 起) ​

更新不再「先删旧版再放新版」,而是:

  1. 旧目录先挪成 .bak-<name>-<时间戳>;
  2. 新版本就位、后端热挂载成功;
  3. 只有全部成功才删除备份。

任何一步失败(下载中断、文件写入失败、后端挂载失败),都会自动把备份挪回去,并返回 安装后初始化失败,已回滚到上一版本。同一应用同时只允许一个安装/更新流程, 两个班管同时点「更新」不会再互相清目录。

卸载时清理:

  • 当前运行实例;
  • 动态后端路由;
  • 前端脚本;
  • 前端样式;
  • 桌面、Dock、文件夹和小组件入口;
  • 动态路由映射。

已卸载应用的 API 返回 JSON 404,而不是前端 index.html。

生命周期:谁负责清什么 ​

「卸载即无痕」是平台承诺,但需要应用履行自己的那一半义务:

阶段平台自动完成应用义务
安装文件落盘 market-apps/<name>/、app_control 登记、后端热挂载、广播—
启用/停用app_control 即时生效、前端路由与悬浮层同步摘挂—
更新重装最新版(保留启用状态与本地数据)—
卸载执行 cleanup.js → 删 app_control/app_config → 删目录 → 前端卸载 script/style/DOMcleanup.js 清干净自建表与 kv;onDestroy 退订全部 realtime/eventBus
卸载(客户端)清 ci:app:<name>:* localStorage、SDK 登记表、模块注册表、路由墓碑存储只经 context.data.storage(前缀强制,才能被清到)

cleanup.js 钩子契约(卸载时、删目录前执行,失败会中止卸载保留现场)见 第三方应用开发 § 卸载清理钩子。

发布前可用生命周期探针完整回归一遍:

bash
node scripts/market-lifecycle-probe.mjs   # 需本地服务器运行中(默认 http://127.0.0.1:9001)

探针用一次性应用完整走「安装 → 使用 → 卸载 → 重装 → 再卸载」,逐项断言数据库表、app_control、目录、API 全部无残留。

自建市场源(第三方独立分发) ​

默认市场源是官方的 Gitee / GitHub / 本地目录三家。自 2026-10 起,班级可以添加任意自建源, 第三方不必等官方合仓才能被安装:

方式配置适用
管理端添加市场页 → 来源栏「源」→ 填 id / 显示名 / index.json 所在目录一次性、图形化
环境变量MARKET_SOURCES='[{"id":"my","label":"我的市场","base":"https://example.com/market/main/"}]'部署时固化,可写 id|label|base 逗号分隔简写

约束:

  • 内置三源不可删除;环境变量声明的源只能改 .env(管理端会明确报错)
  • 自定义源不套官方 ed25519 公钥验签(它通常有自己的信任体系),市场页显示「自建源」徽章
  • 自定义源不跨源回退——避免私有市场的应用去官方仓找同名包
  • 服务端会代拉该地址的 index.json 与安装包,等同于管理员主动信任该 URL;内网地址可用

应用健康度 ​

管理端市场页的「已安装」列表会显示每个应用的使用人数/次数与错误数(来自本班服务器本地记账)。 第三方排查「没人用」还是「坏了」不再靠猜。接口与字段见 第三方应用开发 § 应用健康度。

发布到市场源 ​

市场源是一个 Git 仓库(Gitee 默认 / GitHub / 本地目录),根目录 index.json 列出全部包:

json
{ "version": 1, "apps": [ { "name": "my-app", "label": "示例", "version": "1.0.0",
  "files": ["apps/my-app/manifest.json", "apps/my-app/frontend/entry.js"] } ] }

在市场源仓库根目录完成三步:

bash
node scripts/market-index-gen.mjs          # 1. 生成 index.json(files 清单 + 逐文件 sha256)
node scripts/market-sign.mjs --genkey      # 2.(首次)生成 ed25519 发布密钥对
node scripts/market-sign.mjs               # 3. 每次发布:对 index.json 签名 → index.json.sig

# 发布:把 apps/<name>/(或 themes/<id>/、plugins/<name>/)+ index.json + index.json.sig 推到市场仓库

说明:

  • 能力清单自动带入:market-index-gen.mjs 会把 manifest.capabilities 写进目录条目。 以前这一步靠手填,漏一次详情页的「会用到什么」就永远是空的,班管看不到真实披露。

  • 运营字段由维护者手填、生成器原样保留:

    字段作用示例
    screenshots详情页截图(仓库相对路径)["apps/my-app/screenshots/01-overview.png"]
    changelog更新日志(版本 + 说明)[{ "version": "1.0.0", "notes": "首个版本" }]
    group市场页分类(game / tool / life)"game"

    截图规范:1043×787(校园平板横屏),深浅主题各一张更好;放进 apps/<name>/screenshots/ 后再跑生成器, 截图会自动进入 files 与 hashes(安装时一并校验)。

  • market-index-gen.mjs 扫描市场源的 apps/ / plugins/ / themes/ 三段并合并回 index.json,files 清单不再手工维护;screenshots / changelog 等运营字段原样保留。--check 可只校验不写入

  • 本地源目录默认 <项目根>/../market,可用 MARKET_LOCAL_DIR 覆盖;班级服务器装好后即从市场源拉取安装

完整性链路(防篡改) ​

两层保护,发布者按需启用:

  1. 逐文件哈希:market-index-gen.mjs 自动在 index.json 每个条目写入 hashes(sha256),安装时服务端逐文件比对,不匹配即中止——防镜像损坏与半更新,零配置默认生效。
  2. 目录签名(可选启用):market-sign.mjs 用 ed25519 私钥对 index.json 原始字节签名;部署端配置 MARKET_SIGNING_PUBLIC_KEY(PEM 文本或文件路径)后,http 源(gitee/github)的目录必须验签通过才可用(篡改/缺签 → 拉取失败并在市场页显示明确错误),本地源按文件系统信任跳过。市场页目录区显示「已验签 / 未验签 / 本地源」徽章。

密钥纪律

私钥(server/.market-signing-key.pem)绝不入仓、不入市场仓库;轮换密钥时先发新公钥到部署端、再用新私钥重签目录。

市场主题包 ​

市场里除应用与插件外,还有一类纯数据 JSON 包——主题。没有任何脚本执行(CSP 友好),安装后出现在全班成员的主题选择里:

text
themes/<id>/
  manifest.json   # { id, name, type: 'light'|'dark', version, description, author, tokens: './tokens.json' }
  tokens.json     # TOKENS 数据对象(与内置主题导出结构同构)
  icon.svg        # 可选

硬性约束:

  • id 必须与目录名一致,且不能是 light/dark(内置主题不可覆盖)
  • tokens 必须指向 ./tokens.json(纯 JSON;市场主题不支持 .js)
  • 安装时服务端原子写入 market-themes/<id>/ 并合成 pack.json,客户端一次取全注册;卸载时正在使用的用户自动回退浅色

脚手架:node scripts/create.mjs theme <id> --type light|dark(生成基于内置主题的完整 tokens 副本,改 color 组值即可生效)。令牌体系见 主题开发。

五子棋示例 ​

五子棋应用位于 market/apps/gomoku,manifest 包含:

json
{
  "name": "gomoku",
  "version": "1.0.0",
  "frontend": {
    "route": "/gomoku",
    "entry": "./frontend/entry.js",
    "style": "./frontend/style.css"
  },
  "backend": {
    "mountPath": "/api/gomoku",
    "entry": "./backend/routes.js"
  }
}

接口:

方法路径说明
GET/api/gomoku/state查询 15×15 棋盘状态
POST/api/gomoku/move使用 row、col 落子
POST/api/gomoku/reset重置棋局

错误状态包括非法坐标 400、重复落子或结束棋局 409、禁用/卸载后的 404。

验证 ​

服务端:

bash
cd server
pnpm test

客户端:

bash
cd client
pnpm run build

浏览器验收至少包括:直接访问、棋盘渲染、落子、重开、离开、启用、禁用、更新、卸载,以及卸载后的 API/静态资源 404。

致谢与来源 ​

五子棋市场应用的游戏方向、交互参考和部分实现思路来自 MoyuZJ912/iFlyCompass。感谢 iFlyCompass 提供的开源代码和产品探索,为 ClassIntra 第三方应用生态建设提供了有价值的参考。

ClassIntra 的市场协议、市场目录、动态运行时、班级统一管控和生命周期实现由 ClassIntra 项目独立完成。使用或再分发相关代码时,请遵守各自仓库的许可证和署名要求。

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