feat(permissions,clients,ai,system,server,web,client,shared)!: 权限组 + 客户端设备远控与自动更新 + 大模型助手 + 系统诊断(1.3.0)
功能级准入改为「权限键」,`requireRole` 退成默认模板。 权限组 - 权限目录(39 键:键 / 中文名 / 分类 / 默认角色)收口到 shared,路由挂 requirePermission / requireAnyPermission - 有效权限每请求实时算,改完分组立刻生效:ADMIN 全集且 permission:manage、system:manage 不可剥夺; CLASS_DEVICE 空集(不受分组影响);有分组 = 并集(因此也能用来**收回**权限);无分组 = 角色默认模板 - 新增「权限组」页:组增删改、成员分配、生效权限预览 - 班级维度的科目规则(assertCanManageSubjectContent)故意不可被权限组覆盖 客户端设备(ClassHelper 桌面端) - 设备身份是 deviceKey(首次启动生成的 UUID,saveConfig 拒绝改写、退出登录也保留) - 心跳走「DB 记状态 + 客户端定时拉」,不引入新的长连接:30 秒一次,在线窗口 90 秒 - 远控命令 shutdown / restart / logoff / lock:服务端有效期 10 分钟,客户端弹默认选中「取消」的对话框、 60 秒未确认按取消处理,执行后必须回执(重复回执幂等),同一台机器同一条命令只弹一次 - 新增「客户端设备」页:版本一览、一键推送更新、下发远控 客户端安装包由服务端下载并缓存(教室机常常没有外网,浏览器也受 CSP 限制) - POST /api/update/client/fetch 由服务端下载到 data/client-releases/<版本>/ 并登记 sha256 + size - 自动安装三条护栏:没有 sha256 就拒收、必须等到非上课且主窗口隐藏满 5 分钟、冒烟模式永不安装 大模型助手:只解析、不落库 - POST /api/ai/interpret 返回**待确认**的结构化动作(建作业 / 发通知 / 叫人), 真正落库仍调既有端点 —— 权限断言、上课时段紧急通知保护、ClassIsland 推送全部自动复用 - 模型给的 params 用与手动入口**同一份** zod 再校验(模型输出不可信) - API Key 走 AES-256-GCM(密钥由 JWT_SECRET 经 scrypt 派生)加密存 AppSetting,只进不出 - provider=mock 是离线确定性解析,自动化验收一律用它;每次解析写一条 AiAudit(不含密钥) 系统与运维 - 开发者模式(服务端内存缓存开关,热路径不查库;开启后 500 才附 error.stack)、运行诊断(绝不回传密钥) - 开机自启动运行期可改:Windows 改 HKCU\...\Run、Linux systemctl enable/disable, **非安装形态一律返回 supported:false**,不往开发机的注册表里写自启项 - 服务端侧栏折叠只用 CSS 收拢(不重建 DOM),关怀模式只放大字号与控件、不动任何几何令牌 客户端 - 崩溃自愈:渲染进程挂掉 / 超 10 秒无响应先静默重建主窗口(10 分钟最多 3 次), 未捕获异常只在「没在上课、没人看着」时才重启进程;冒烟模式绝不重启(会杀掉验证实例) - 上线补弹离线期间收到的消息只做一次:起点只在「可达 → 不可达」的边界写,恢复时取最近 5 条按时间升序推 发布内容批量 - POST /notifications/bulk、POST /homeworks/bulk:**单班失败不影响整批**,逐班返回结果 - 作业的科目名跨班**按名匹配**已有课程,找不到就整班记失败,绝不自动建课 (自动建课会把创建者写成任课老师,等于越权改任教关系) - 通知与作业同口径按「所属日期」归档,新增 /notifications/days 与 /notifications/creators BREAKING CHANGE: 能不能做某件事不再看角色名,而是看权限键(GET /api/permissions/me)。 未分组的账号按角色默认模板生效,行为与 1.2.0 一致;分组之后生效集合只由组的并集决定。 服务端首次启动会自动应用 1 个数据库迁移(权限组 3 表 / AppSetting / 客户端设备·命令·安装包 / AiAudit / Notification.assignDate / User.careMode,历史通知按本地日期回填),升级前请先备份。
This commit is contained in:
1 parent
e51879667a
commit
817af02357
131 files changed
+12995
-538
No files matched your search
@@ -0,0 +1,220 @@
|
||||
import crypto from 'node:crypto';
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
import { Readable } from 'node:stream';
|
||||
import { pipeline } from 'node:stream/promises';
|
||||
import {
|
||||
API_PREFIX,
|
||||
CLIENT_RELEASE_DIR,
|
||||
clientReleaseDownloadUrl,
|
||||
clientReleaseFileName,
|
||||
compareVersions,
|
||||
type ClientReleaseDto,
|
||||
type ClientUpdateInfoDto,
|
||||
} from '@classhelper/shared';
|
||||
import { env } from '../../config/env.js';
|
||||
import { prisma } from '../../lib/db.js';
|
||||
import { ApiError } from '../../lib/http.js';
|
||||
import { logger } from '../../lib/logger.js';
|
||||
import type { FetchClientReleaseInput, RegisterClientReleaseInput } from './update.schemas.js';
|
||||
|
||||
/**
|
||||
* 客户端安装包在服务端的缓存。
|
||||
*
|
||||
* 为什么要有这一层:教室机器常常**没有外网**,而"统一下发客户端更新"必须能落到
|
||||
* 那些机器上。于是服务端替它们代下(或由管理员手工放一份)并缓存到
|
||||
* `data/client-releases/<版本>/`,客户端再从 `GET /api/update/client/download/:version` 拉。
|
||||
*
|
||||
* 两个入口都**不传二进制**(服务端没有 multipart,也不打算为这一件事加):
|
||||
* - `fetch`:服务端自己去 GitHub Releases 下(Web 端受 CSP 约束不能直连 GitHub,见 §5 第 52 条);
|
||||
* - `register`:文件已由管理员放进磁盘(内网分发、U 盘、CI 产物),服务端只算 sha256 并登记。
|
||||
*/
|
||||
|
||||
/** 代下大文件时的超时(安装包约 100MB,机房线路慢要留足) */
|
||||
const FETCH_TIMEOUT_MS = 10 * 60 * 1000;
|
||||
|
||||
type ReleaseRow = {
|
||||
id: string;
|
||||
version: string;
|
||||
fileName: string;
|
||||
sha256: string;
|
||||
size: number;
|
||||
notes: string;
|
||||
createdAt: Date;
|
||||
updatedAt: Date;
|
||||
};
|
||||
|
||||
function releaseRoot(): string {
|
||||
// 与 database 模块的备份目录同口径:<serverRoot>/../data
|
||||
const dir = path.join(env.serverRoot, '..', 'data', CLIENT_RELEASE_DIR);
|
||||
fs.mkdirSync(dir, { recursive: true });
|
||||
return dir;
|
||||
}
|
||||
|
||||
function releaseDir(version: string): string {
|
||||
return path.join(releaseRoot(), version);
|
||||
}
|
||||
|
||||
function releaseFilePath(version: string, fileName: string): string {
|
||||
return path.join(releaseDir(version), fileName);
|
||||
}
|
||||
|
||||
function toReleaseDto(row: ReleaseRow): ClientReleaseDto {
|
||||
return {
|
||||
version: row.version,
|
||||
fileName: row.fileName,
|
||||
size: row.size,
|
||||
sha256: row.sha256,
|
||||
notes: row.notes,
|
||||
fileReady: fs.existsSync(releaseFilePath(row.version, row.fileName)),
|
||||
createdAt: row.createdAt.toISOString(),
|
||||
updatedAt: row.updatedAt.toISOString(),
|
||||
};
|
||||
}
|
||||
|
||||
async function sha256Of(file: string): Promise<string> {
|
||||
const hash = crypto.createHash('sha256');
|
||||
await pipeline(fs.createReadStream(file), hash);
|
||||
return hash.digest('hex');
|
||||
}
|
||||
|
||||
/** GET /api/update/client/releases - 已缓存的安装包(按版本从新到旧) */
|
||||
export async function listReleases(): Promise<ClientReleaseDto[]> {
|
||||
const rows = (await prisma.clientRelease.findMany()) as unknown as ReleaseRow[];
|
||||
return rows
|
||||
.sort((a, b) => compareVersions(b.version, a.version))
|
||||
.map((row) => toReleaseDto(row));
|
||||
}
|
||||
|
||||
/** 服务端缓存的**最新**版本(推送更新时省略 version 就用它) */
|
||||
export async function latestReleaseVersion(): Promise<string> {
|
||||
const rows = (await prisma.clientRelease.findMany()) as unknown as ReleaseRow[];
|
||||
const ready = rows.filter((row) => fs.existsSync(releaseFilePath(row.version, row.fileName)));
|
||||
ready.sort((a, b) => compareVersions(b.version, a.version));
|
||||
return ready[0]?.version ?? '';
|
||||
}
|
||||
|
||||
/**
|
||||
* 某个版本的下载信息(心跳响应里带给客户端)。
|
||||
* 文件不在磁盘上时返回 null —— 客户端据此提示"服务端还没有这份安装包"。
|
||||
*/
|
||||
export async function resolveUpdateInfo(version: string): Promise<ClientUpdateInfoDto | null> {
|
||||
const wanted = version.trim();
|
||||
if (!wanted) return null;
|
||||
const row = (await prisma.clientRelease.findUnique({ where: { version: wanted } })) as ReleaseRow | null;
|
||||
if (!row) return null;
|
||||
if (!fs.existsSync(releaseFilePath(row.version, row.fileName))) return null;
|
||||
return {
|
||||
version: row.version,
|
||||
fileName: row.fileName,
|
||||
size: row.size,
|
||||
sha256: row.sha256,
|
||||
notes: row.notes,
|
||||
// 含 /api 前缀:客户端用「服务器地址 + 它」直接下载
|
||||
url: `${API_PREFIX}/update/client/download/${encodeURIComponent(row.version)}`,
|
||||
};
|
||||
}
|
||||
|
||||
/** 绝对路径(下载路由用);文件不存在返回 null */
|
||||
export async function resolveReleaseFile(version: string): Promise<{ file: string; fileName: string } | null> {
|
||||
const row = (await prisma.clientRelease.findUnique({ where: { version } })) as ReleaseRow | null;
|
||||
if (!row) return null;
|
||||
const file = releaseFilePath(row.version, row.fileName);
|
||||
if (!fs.existsSync(file)) return null;
|
||||
return { file, fileName: row.fileName };
|
||||
}
|
||||
|
||||
/** 登记一份已经在磁盘上的安装包:算 sha256 / 大小后落库(可重复登记,会覆盖) */
|
||||
export async function registerRelease(
|
||||
userId: string,
|
||||
input: RegisterClientReleaseInput,
|
||||
): Promise<ClientReleaseDto> {
|
||||
const version = input.version;
|
||||
// 文件名默认走发布命名约定(与 GitHub Release、官网兜底直链一致)
|
||||
const known = (await prisma.clientRelease.findUnique({ where: { version } })) as ReleaseRow | null;
|
||||
const fileName = input.fileName ?? known?.fileName ?? clientReleaseFileName(version);
|
||||
const file = releaseFilePath(version, fileName);
|
||||
|
||||
if (!fs.existsSync(file)) {
|
||||
throw ApiError.badRequest(
|
||||
`没找到安装包文件「${fileName}」,请先把它放进 data/${CLIENT_RELEASE_DIR}/${version}/ 再登记`,
|
||||
);
|
||||
}
|
||||
|
||||
const stat = fs.statSync(file);
|
||||
const sha256 = await sha256Of(file);
|
||||
const row = (await prisma.clientRelease.upsert({
|
||||
where: { version },
|
||||
create: {
|
||||
version,
|
||||
fileName,
|
||||
sha256,
|
||||
size: stat.size,
|
||||
notes: input.notes?.trim() ?? '',
|
||||
createdBy: userId,
|
||||
},
|
||||
update: {
|
||||
fileName,
|
||||
sha256,
|
||||
size: stat.size,
|
||||
...(input.notes !== undefined ? { notes: input.notes.trim() } : {}),
|
||||
},
|
||||
})) as ReleaseRow;
|
||||
|
||||
logger.info(`登记客户端安装包 v${version}(${fileName},${stat.size} 字节,sha256=${sha256.slice(0, 12)}…)`);
|
||||
return toReleaseDto(row);
|
||||
}
|
||||
|
||||
/** 让服务端从 GitHub 拉一份安装包并登记(教室无外网时由服务端代下) */
|
||||
export async function fetchReleaseFromGithub(
|
||||
userId: string,
|
||||
input: FetchClientReleaseInput,
|
||||
): Promise<ClientReleaseDto> {
|
||||
const version = input.version;
|
||||
const fileName = clientReleaseFileName(version);
|
||||
const url = clientReleaseDownloadUrl(version);
|
||||
const target = releaseFilePath(version, fileName);
|
||||
|
||||
fs.mkdirSync(releaseDir(version), { recursive: true });
|
||||
logger.info(`开始从 GitHub 拉取客户端安装包 v${version}:${url}`);
|
||||
|
||||
let response: Response;
|
||||
try {
|
||||
response = await fetch(url, {
|
||||
redirect: 'follow',
|
||||
signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
|
||||
headers: { 'User-Agent': 'ClassHelper-Server' },
|
||||
});
|
||||
} catch (error) {
|
||||
throw ApiError.badRequest(
|
||||
`下载失败:${error instanceof Error ? error.message : String(error)}。` +
|
||||
`可以把安装包手工放进 data/${CLIENT_RELEASE_DIR}/${version}/ 再点「登记」`,
|
||||
);
|
||||
}
|
||||
|
||||
if (!response.ok || !response.body) {
|
||||
throw ApiError.badRequest(
|
||||
`GitHub 上没有 v${version} 的客户端安装包(HTTP ${response.status},文件名应为 ${fileName})`,
|
||||
);
|
||||
}
|
||||
|
||||
try {
|
||||
await pipeline(Readable.fromWeb(response.body as never), fs.createWriteStream(target));
|
||||
} catch (error) {
|
||||
fs.rmSync(target, { force: true });
|
||||
throw ApiError.badRequest(`写入安装包失败:${error instanceof Error ? error.message : String(error)}`);
|
||||
}
|
||||
|
||||
// 落盘后统一走登记:sha256 / 大小 / 落库都在同一处算
|
||||
return registerRelease(userId, { version, fileName });
|
||||
}
|
||||
|
||||
/** 删除一份缓存的安装包(元数据 + 磁盘文件) */
|
||||
export async function deleteRelease(version: string): Promise<{ version: string }> {
|
||||
const row = (await prisma.clientRelease.findUnique({ where: { version } })) as ReleaseRow | null;
|
||||
if (!row) throw ApiError.notFound('服务端没有这个版本的安装包');
|
||||
await prisma.clientRelease.delete({ where: { version } });
|
||||
fs.rmSync(releaseDir(version), { recursive: true, force: true });
|
||||
logger.info(`删除客户端安装包 v${version}(${row.fileName})`);
|
||||
return { version };
|
||||
}
|
||||
@@ -1,8 +1,17 @@
|
||||
import { Router } from 'express';
|
||||
import { sendOk } from '../../lib/http.js';
|
||||
import { authenticate, getAuthUser } from '../../middleware/auth.js';
|
||||
import { sendCreated, sendOk, ApiError } from '../../lib/http.js';
|
||||
import { authenticate, getAuthUser, requirePermission } from '../../middleware/auth.js';
|
||||
import { validate, validatedBody, validatedParams } from '../../middleware/validate.js';
|
||||
import { defineModule } from '../module.types.js';
|
||||
import * as clientReleases from './client-releases.service.js';
|
||||
import * as updateService from './update.service.js';
|
||||
import {
|
||||
clientReleaseVersionParamSchema,
|
||||
fetchClientReleaseSchema,
|
||||
registerClientReleaseSchema,
|
||||
type FetchClientReleaseInput,
|
||||
type RegisterClientReleaseInput,
|
||||
} from './update.schemas.js';
|
||||
|
||||
const router = Router();
|
||||
router.use(authenticate());
|
||||
@@ -25,6 +34,86 @@ router.get('/check', async (req, res) => {
|
||||
sendOk(res, await updateService.checkForUpdates({ force }), '更新检查完成');
|
||||
});
|
||||
|
||||
/* ------------------------------- 客户端安装包的服务端缓存(统一下发更新的基础) */
|
||||
|
||||
/**
|
||||
* GET /api/update/client/releases - 服务端已缓存了哪些客户端版本
|
||||
*
|
||||
* 教室机器没有外网,所以"统一推送更新"必须有这一层中继:服务端替它们把安装包拉下来,
|
||||
* 客户端再从 `/client/download/:version` 取。
|
||||
*/
|
||||
router.get('/client/releases', requirePermission('client:manage'), async (_req, res) => {
|
||||
sendOk(res, await clientReleases.listReleases(), '获取安装包列表成功');
|
||||
});
|
||||
|
||||
/**
|
||||
* POST /api/update/client/fetch - 让服务端从 GitHub 下载某个版本的客户端安装包并登记
|
||||
*
|
||||
* 服务端(Node)不受浏览器 CSP 约束,这是唯一能"一键代下"的地方;
|
||||
* 下不动(学校出口没有外网)时退回 `POST /client/releases` 手工登记。
|
||||
*/
|
||||
router.post(
|
||||
'/client/fetch',
|
||||
requirePermission('client:update-push'),
|
||||
validate({ body: fetchClientReleaseSchema }),
|
||||
async (req, res) => {
|
||||
const user = getAuthUser(req);
|
||||
const input = validatedBody<FetchClientReleaseInput>(req);
|
||||
sendCreated(res, await clientReleases.fetchReleaseFromGithub(user.sub, input), '安装包已下载并登记');
|
||||
},
|
||||
);
|
||||
|
||||
/**
|
||||
* POST /api/update/client/releases - 登记一份已经放进磁盘的安装包
|
||||
*
|
||||
* 文件要求放在 `<serverRoot>/../data/client-releases/<版本>/` 下(文件名默认按发布约定推导)。
|
||||
* 这条路径也是自动化验收用的:不需要外网、不需要传 100MB 二进制。
|
||||
*/
|
||||
router.post(
|
||||
'/client/releases',
|
||||
requirePermission('client:update-push'),
|
||||
validate({ body: registerClientReleaseSchema }),
|
||||
async (req, res) => {
|
||||
const user = getAuthUser(req);
|
||||
const input = validatedBody<RegisterClientReleaseInput>(req);
|
||||
sendCreated(res, await clientReleases.registerRelease(user.sub, input), '安装包已登记');
|
||||
},
|
||||
);
|
||||
|
||||
/** DELETE /api/update/client/releases/:version - 删除缓存(元数据 + 磁盘文件) */
|
||||
router.delete(
|
||||
'/client/releases/:version',
|
||||
requirePermission('client:update-push'),
|
||||
validate({ params: clientReleaseVersionParamSchema }),
|
||||
async (req, res) => {
|
||||
const { version } = validatedParams<{ version: string }>(req);
|
||||
sendOk(res, await clientReleases.deleteRelease(version), '安装包已删除');
|
||||
},
|
||||
);
|
||||
|
||||
/**
|
||||
* GET /api/update/client/download/:version - 下载安装包(客户端自动更新走它)
|
||||
*
|
||||
* **故意不挂权限键**:下载方是教室里的班级端会话(角色 CLASS_DEVICE,权限集为空),
|
||||
* 它代表那个班;真正的保护是"必须已登录 + 限流中间件"。
|
||||
* `res.download` 自带 Content-Length / Range 支持,不需要另写流式助手。
|
||||
*/
|
||||
router.get(
|
||||
'/client/download/:version',
|
||||
validate({ params: clientReleaseVersionParamSchema }),
|
||||
async (req, res) => {
|
||||
const { version } = validatedParams<{ version: string }>(req);
|
||||
const found = await clientReleases.resolveReleaseFile(version);
|
||||
if (!found) throw ApiError.notFound('服务端没有缓存这个版本的安装包');
|
||||
res.download(found.file, found.fileName, (error) => {
|
||||
if (error) {
|
||||
// 客户端中途取消下载也会走到这里,只记日志,不要往已发出的响应里再写东西
|
||||
res.locals.downloadError = error instanceof Error ? error.message : String(error);
|
||||
}
|
||||
});
|
||||
},
|
||||
);
|
||||
|
||||
export const updateModule = defineModule({
|
||||
name: 'update',
|
||||
basePath: '/update',
|
||||
|
||||
@@ -0,0 +1,41 @@
|
||||
import { z } from 'zod';
|
||||
|
||||
/**
|
||||
* 安装包文件名/版本号只允许这些字符。
|
||||
*
|
||||
* 它们会被拼进磁盘路径(`data/client-releases/<版本>/<文件名>`),
|
||||
* 所以必须挡住 `..`、`/`、`\` —— 否则一个 `version=../../` 就能写到仓库外面去。
|
||||
*/
|
||||
const SAFE_SEGMENT = /^[0-9A-Za-z._-]+$/;
|
||||
|
||||
export const clientReleaseVersionSchema = z
|
||||
.string()
|
||||
.trim()
|
||||
.min(1, '请输入版本号')
|
||||
.max(40, '版本号最多 40 个字符')
|
||||
.refine((value) => SAFE_SEGMENT.test(value), {
|
||||
message: '版本号只能包含字母、数字、点、下划线与短横线',
|
||||
});
|
||||
|
||||
/** `POST /api/update/client/fetch`:让服务端替教室机器从 GitHub 拉一份安装包 */
|
||||
export const fetchClientReleaseSchema = z.object({
|
||||
version: clientReleaseVersionSchema,
|
||||
});
|
||||
|
||||
/** `POST /api/update/client/releases`:登记一份已经放进磁盘的安装包(手工兜底与自动化用) */
|
||||
export const registerClientReleaseSchema = z.object({
|
||||
version: clientReleaseVersionSchema,
|
||||
fileName: z
|
||||
.string()
|
||||
.trim()
|
||||
.min(1)
|
||||
.max(120)
|
||||
.refine((value) => SAFE_SEGMENT.test(value), { message: '文件名只能包含字母、数字、点、下划线与短横线' })
|
||||
.optional(),
|
||||
notes: z.string().trim().max(500).optional(),
|
||||
});
|
||||
|
||||
export const clientReleaseVersionParamSchema = z.object({ version: clientReleaseVersionSchema });
|
||||
|
||||
export type FetchClientReleaseInput = z.infer<typeof fetchClientReleaseSchema>;
|
||||
export type RegisterClientReleaseInput = z.infer<typeof registerClientReleaseSchema>;
|
||||
Reference in new issue
Block a user