266 lines
10 KiB
TypeScript
266 lines
10 KiB
TypeScript
import type { TokenPayload } from '../../lib/jwt.js';
|
||
import { assertAdmin } from '../../lib/authz/index.js';
|
||
import { getReleaseProgress, setReleaseProgress } from './release-progress.js';
|
||
import { Transform } from 'node:stream';
|
||
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 {
|
||
return path.join(env.serverRoot, '..', 'data', CLIENT_RELEASE_DIR);
|
||
}
|
||
|
||
function releaseDir(version: string): string {
|
||
if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(version) || version.includes('..'))
|
||
throw ApiError.badRequest('版本号不是安全路径段');
|
||
return path.join(releaseRoot(), version);
|
||
}
|
||
|
||
function releaseFilePath(version: string, fileName: string): string {
|
||
if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(fileName) || fileName.includes('..'))
|
||
throw ApiError.badRequest('文件名不是安全路径段');
|
||
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');
|
||
}
|
||
|
||
/** 仅检查缓存文件和当前登记,不创建目录或修改记录。 */
|
||
export async function inspectClientRelease(
|
||
actor: TokenPayload,
|
||
input: RegisterClientReleaseInput,
|
||
requireFile = false,
|
||
) {
|
||
assertAdmin(actor);
|
||
const row = await prisma.clientRelease.findUnique({ where: { version: input.version } });
|
||
const fileName = input.fileName ?? row?.fileName ?? clientReleaseFileName(input.version);
|
||
const file = releaseFilePath(input.version, fileName);
|
||
const exists = fs.existsSync(file);
|
||
if (requireFile && !exists) throw ApiError.badRequest('请先把安装包放入对应版本的客户端缓存目录');
|
||
if (exists && !fs.statSync(file).isFile()) throw ApiError.badRequest('安装包必须是普通文件');
|
||
return {
|
||
version: input.version,
|
||
fileName,
|
||
file: exists ? { size: fs.statSync(file).size, sha256: await sha256Of(file) } : null,
|
||
current: row ? toReleaseDto(row) : null,
|
||
};
|
||
}
|
||
|
||
/** 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(
|
||
actor: TokenPayload,
|
||
input: RegisterClientReleaseInput,
|
||
): Promise<ClientReleaseDto> {
|
||
assertAdmin(actor);
|
||
const userId = actor.sub;
|
||
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(
|
||
actor: TokenPayload,
|
||
input: FetchClientReleaseInput,
|
||
): Promise<ClientReleaseDto> {
|
||
if (['downloading', 'verifying'].includes(getReleaseProgress().stage))
|
||
throw ApiError.conflict('已有安装包正在下载');
|
||
assertAdmin(actor);
|
||
const version = input.version;
|
||
setReleaseProgress({ version, stage: 'downloading', downloadedBytes: 0, totalBytes: 0, error: '' });
|
||
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 {
|
||
setReleaseProgress({ totalBytes: Number(response.headers.get('content-length')) || 0 });
|
||
const counter = new Transform({
|
||
transform(chunk, _encoding, done) {
|
||
setReleaseProgress({ downloadedBytes: getReleaseProgress().downloadedBytes + chunk.length });
|
||
done(null, chunk);
|
||
},
|
||
});
|
||
await pipeline(Readable.fromWeb(response.body as never), counter, fs.createWriteStream(target));
|
||
} catch (error) {
|
||
fs.rmSync(target, { force: true });
|
||
throw ApiError.badRequest(`写入安装包失败:${error instanceof Error ? error.message : String(error)}`);
|
||
}
|
||
|
||
// 落盘后统一走登记:sha256 / 大小 / 落库都在同一处算
|
||
setReleaseProgress({ stage: 'verifying' });
|
||
const release = await registerRelease(actor, { version, fileName });
|
||
setReleaseProgress({ stage: 'ready', downloadedBytes: release.size, totalBytes: release.size });
|
||
return release;
|
||
}
|
||
|
||
/** 删除一份缓存的安装包(元数据 + 磁盘文件) */
|
||
export async function deleteRelease(actor: TokenPayload, version: string): Promise<{ version: string }> {
|
||
assertAdmin(actor);
|
||
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 };
|
||
}
|