feat: 完成模板目录导入与生命周期管理
This commit is contained in:
1 parent
553a07c4ec
commit
413413efda
25 files changed
+1313
-24
No files matched your search
@@ -0,0 +1,463 @@
|
||||
import {
|
||||
BadRequestException,
|
||||
ConflictException,
|
||||
Injectable,
|
||||
PayloadTooLargeException,
|
||||
} from "@nestjs/common";
|
||||
import { validateTemplatePackageManifest } from "@personal-brand/config";
|
||||
import { Prisma } from "@prisma/client";
|
||||
import type { FastifyRequest } from "fastify";
|
||||
import { createHash } from "node:crypto";
|
||||
import { execFile } from "node:child_process";
|
||||
import { promises as fs } from "node:fs";
|
||||
import path from "node:path";
|
||||
import { promisify } from "node:util";
|
||||
import { PrismaService } from "../../prisma.service.js";
|
||||
|
||||
const execFileAsync = promisify(execFile);
|
||||
const MAX_ARCHIVE_BYTES = 50 * 1024 * 1024;
|
||||
const MAX_EXTRACTED_BYTES = 200 * 1024 * 1024;
|
||||
const MAX_FILES = 5_000;
|
||||
const PACKAGE_KEY_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
|
||||
|
||||
type Manifest = {
|
||||
packageKey: string;
|
||||
version: string;
|
||||
displayName: string;
|
||||
visualTemplateKey?: string;
|
||||
};
|
||||
|
||||
type ChecksumFile = {
|
||||
formatVersion: string;
|
||||
packageKey: string;
|
||||
version: string;
|
||||
contentChecksum: string;
|
||||
files: Array<{ path: string; bytes: number; sha256: string }>;
|
||||
};
|
||||
|
||||
function sha256(value: Buffer | string): string {
|
||||
return createHash("sha256").update(value).digest("hex");
|
||||
}
|
||||
|
||||
function canonical(value: unknown): unknown {
|
||||
if (Array.isArray(value)) return value.map(canonical);
|
||||
if (!value || typeof value !== "object") return value;
|
||||
return Object.fromEntries(
|
||||
Object.entries(value)
|
||||
.sort(([left], [right]) => left.localeCompare(right))
|
||||
.map(([key, item]) => [key, canonical(item)]),
|
||||
);
|
||||
}
|
||||
|
||||
function jsonObject(value: unknown, label: string): Record<string, unknown> {
|
||||
if (!value || typeof value !== "object" || Array.isArray(value))
|
||||
throw new BadRequestException(`${label} 必须是 JSON 对象`);
|
||||
return value as Record<string, unknown>;
|
||||
}
|
||||
|
||||
function safeEntryName(input: string): string {
|
||||
if (!input || input.includes("\\") || input.startsWith("/") || /^[A-Za-z]:/.test(input))
|
||||
throw new BadRequestException("模板包包含不安全的文件路径");
|
||||
const withoutTrailingSlash = input.endsWith("/") ? input.slice(0, -1) : input;
|
||||
const normalized = path.posix.normalize(withoutTrailingSlash);
|
||||
if (!withoutTrailingSlash || normalized !== withoutTrailingSlash || normalized === ".")
|
||||
throw new BadRequestException("模板包包含不安全的文件路径");
|
||||
if (normalized.split("/").some((segment) => segment === ".." || segment === "."))
|
||||
throw new BadRequestException("模板包包含不安全的文件路径");
|
||||
return normalized;
|
||||
}
|
||||
|
||||
async function listArchiveEntries(archivePath: string): Promise<string[]> {
|
||||
let list: string;
|
||||
let verbose: string;
|
||||
try {
|
||||
({ stdout: list } = await execFileAsync("tar", ["-tzf", archivePath], {
|
||||
maxBuffer: 4 * 1024 * 1024,
|
||||
}));
|
||||
({ stdout: verbose } = await execFileAsync("tar", ["-tvzf", archivePath], {
|
||||
maxBuffer: 4 * 1024 * 1024,
|
||||
}));
|
||||
} catch {
|
||||
throw new BadRequestException("模板包不是有效的 gzip tar archive");
|
||||
}
|
||||
const entries = list
|
||||
.split("\n")
|
||||
.map((item) => item.trimEnd())
|
||||
.filter(Boolean)
|
||||
.map(safeEntryName);
|
||||
if (!entries.length || entries.length > MAX_FILES)
|
||||
throw new BadRequestException("模板包文件数量超出限制");
|
||||
const typeLines = verbose
|
||||
.split("\n")
|
||||
.map((item) => item.trimEnd())
|
||||
.filter(Boolean);
|
||||
if (
|
||||
typeLines.length !== entries.length ||
|
||||
typeLines.some((line) => !["-", "d"].includes(line[0] ?? ""))
|
||||
)
|
||||
throw new BadRequestException("模板包只允许包含普通文件和目录,不允许链接或特殊文件");
|
||||
if (new Set(entries).size !== entries.length) throw new BadRequestException("模板包包含重复路径");
|
||||
return entries;
|
||||
}
|
||||
|
||||
async function walkFiles(
|
||||
directory: string,
|
||||
relative = "",
|
||||
): Promise<Array<{ path: string; bytes: number }>> {
|
||||
const result: Array<{ path: string; bytes: number }> = [];
|
||||
for (const entry of await fs.readdir(directory, { withFileTypes: true })) {
|
||||
const current = relative ? `${relative}/${entry.name}` : entry.name;
|
||||
const absolute = path.join(directory, entry.name);
|
||||
if (entry.isSymbolicLink()) throw new BadRequestException("模板包解压后包含符号链接");
|
||||
if (entry.isDirectory()) result.push(...(await walkFiles(absolute, current)));
|
||||
else if (entry.isFile()) result.push({ path: current, bytes: (await fs.stat(absolute)).size });
|
||||
else throw new BadRequestException("模板包包含不支持的文件类型");
|
||||
}
|
||||
return result;
|
||||
}
|
||||
|
||||
@Injectable()
|
||||
export class AdminTemplatePackageService {
|
||||
constructor(private readonly prisma: PrismaService) {}
|
||||
|
||||
async list(page = 1, pageSize = 20) {
|
||||
const [total, versions] = await this.prisma.$transaction([
|
||||
this.prisma.templatePackageVersion.count(),
|
||||
this.prisma.templatePackageVersion.findMany({
|
||||
orderBy: { importedAt: "desc" },
|
||||
skip: (page - 1) * pageSize,
|
||||
take: pageSize,
|
||||
select: {
|
||||
id: true,
|
||||
packageKey: true,
|
||||
version: true,
|
||||
displayName: true,
|
||||
visualTemplateKey: true,
|
||||
status: true,
|
||||
contentChecksum: true,
|
||||
archiveChecksum: true,
|
||||
validationReport: true,
|
||||
importedAt: true,
|
||||
updatedAt: true,
|
||||
templatePackage: { select: { id: true } },
|
||||
importedBy: { select: { id: true, username: true, displayName: true } },
|
||||
},
|
||||
}),
|
||||
]);
|
||||
return {
|
||||
items: versions.map(({ templatePackage, ...version }) => ({
|
||||
...version,
|
||||
templatePackageId: templatePackage.id,
|
||||
})),
|
||||
page,
|
||||
pageSize,
|
||||
total,
|
||||
};
|
||||
}
|
||||
|
||||
async importArchive(request: FastifyRequest, actorId: string) {
|
||||
const part = await request.file({ limits: { files: 1, fileSize: MAX_ARCHIVE_BYTES } });
|
||||
if (!part) throw new BadRequestException("请上传模板 archive 文件");
|
||||
if (part.fieldname !== "archive") throw new BadRequestException("上传字段必须是 archive");
|
||||
const chunks: Buffer[] = [];
|
||||
let bytes = 0;
|
||||
let storedArtifactPath: string | null = null;
|
||||
try {
|
||||
for await (const chunk of part.file) {
|
||||
const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
|
||||
bytes += buffer.length;
|
||||
if (bytes > MAX_ARCHIVE_BYTES) throw new PayloadTooLargeException("模板包超过 50 MB 限制");
|
||||
chunks.push(buffer);
|
||||
}
|
||||
} catch (error) {
|
||||
if (error instanceof PayloadTooLargeException) throw error;
|
||||
throw new BadRequestException("读取模板 archive 失败");
|
||||
}
|
||||
if (part.file.truncated) throw new PayloadTooLargeException("模板包超过 50 MB 限制");
|
||||
const archive = Buffer.concat(chunks);
|
||||
const archiveChecksum = sha256(archive);
|
||||
const temporaryRoot = await fs.mkdtemp(path.join(process.cwd(), ".template-import-"));
|
||||
const archivePath = path.join(temporaryRoot, "package.tar.gz");
|
||||
const extractedRoot = path.join(temporaryRoot, "extracted");
|
||||
try {
|
||||
await fs.writeFile(archivePath, archive, { mode: 0o600 });
|
||||
const entries = await listArchiveEntries(archivePath);
|
||||
const roots = new Set(entries.map((entry) => entry.split("/")[0]));
|
||||
if (roots.size !== 1) throw new BadRequestException("模板包必须只有一个根目录");
|
||||
const rootName = [...roots][0];
|
||||
if (
|
||||
!rootName ||
|
||||
entries.some((entry) => entry !== rootName && !entry.startsWith(`${rootName}/`))
|
||||
)
|
||||
throw new BadRequestException("模板包根目录结构无效");
|
||||
await fs.mkdir(extractedRoot, { recursive: true });
|
||||
try {
|
||||
await execFileAsync(
|
||||
"tar",
|
||||
[
|
||||
"-xzf",
|
||||
archivePath,
|
||||
"--directory",
|
||||
extractedRoot,
|
||||
"--no-same-owner",
|
||||
"--no-same-permissions",
|
||||
],
|
||||
{ maxBuffer: 4 * 1024 * 1024 },
|
||||
);
|
||||
} catch {
|
||||
throw new BadRequestException("模板包解压失败");
|
||||
}
|
||||
const packageRoot = path.join(extractedRoot, rootName);
|
||||
const files = await walkFiles(packageRoot);
|
||||
if (files.length > MAX_FILES) throw new BadRequestException("模板包文件数量超出限制");
|
||||
if (files.reduce((total, file) => total + file.bytes, 0) > MAX_EXTRACTED_BYTES)
|
||||
throw new PayloadTooLargeException("模板包解压后超过 200 MB 限制");
|
||||
const manifest = (await this.readJson(
|
||||
path.join(packageRoot, "template.json"),
|
||||
"template.json",
|
||||
)) as Manifest;
|
||||
const packageJson = jsonObject(
|
||||
await this.readJson(path.join(packageRoot, "package.json"), "package.json"),
|
||||
"package.json",
|
||||
) as { name?: unknown; version?: unknown };
|
||||
const checksums = jsonObject(
|
||||
await this.readJson(path.join(packageRoot, "checksums.json"), "checksums.json"),
|
||||
"checksums.json",
|
||||
) as unknown as ChecksumFile;
|
||||
this.validateManifest(manifest, packageJson, checksums);
|
||||
await this.validateChecksums(packageRoot, files, checksums);
|
||||
const packageKey = manifest.packageKey;
|
||||
const existingPackage = await this.prisma.templatePackage.findUnique({
|
||||
where: { packageKey },
|
||||
});
|
||||
const existingVersion = existingPackage
|
||||
? await this.prisma.templatePackageVersion.findUnique({
|
||||
where: {
|
||||
templatePackageId_version: {
|
||||
templatePackageId: existingPackage.id,
|
||||
version: manifest.version,
|
||||
},
|
||||
},
|
||||
})
|
||||
: null;
|
||||
if (existingVersion) {
|
||||
if (existingVersion.contentChecksum === checksums.contentChecksum)
|
||||
return {
|
||||
imported: false,
|
||||
idempotent: true,
|
||||
version: this.publicVersion(existingVersion),
|
||||
};
|
||||
throw new ConflictException(`${packageKey}@${manifest.version} 已存在不同内容的版本`);
|
||||
}
|
||||
const artifactRoot = path.resolve(
|
||||
process.env.TEMPLATE_ARTIFACT_ROOT ??
|
||||
path.join(process.cwd(), "storage", "template-artifacts"),
|
||||
);
|
||||
const artifactPath = path.join(
|
||||
artifactRoot,
|
||||
packageKey,
|
||||
manifest.version,
|
||||
`${archiveChecksum}.tar.gz`,
|
||||
);
|
||||
await fs.mkdir(path.dirname(artifactPath), { recursive: true });
|
||||
await fs.copyFile(archivePath, artifactPath);
|
||||
storedArtifactPath = artifactPath;
|
||||
const version = await this.prisma.$transaction(async (tx) => {
|
||||
const packageRecord =
|
||||
existingPackage ?? (await tx.templatePackage.create({ data: { packageKey } }));
|
||||
const created = await tx.templatePackageVersion.create({
|
||||
data: {
|
||||
templatePackageId: packageRecord.id,
|
||||
packageKey,
|
||||
version: manifest.version,
|
||||
displayName: manifest.displayName,
|
||||
visualTemplateKey: manifest.visualTemplateKey ?? null,
|
||||
manifestSnapshot: manifest as unknown as Prisma.InputJsonValue,
|
||||
validationReport: {
|
||||
formatVersion: "1",
|
||||
errors: [],
|
||||
fileCount: files.length,
|
||||
extractedBytes: files.reduce((total, file) => total + file.bytes, 0),
|
||||
} as Prisma.InputJsonValue,
|
||||
contentChecksum: checksums.contentChecksum,
|
||||
archiveChecksum,
|
||||
artifactPath,
|
||||
importedById: actorId,
|
||||
},
|
||||
});
|
||||
await tx.templatePackageAuditLog.create({
|
||||
data: {
|
||||
templatePackageVersionId: created.id,
|
||||
actorId,
|
||||
action: "imported",
|
||||
toStatus: "imported",
|
||||
metadata: {
|
||||
contentChecksum: checksums.contentChecksum,
|
||||
archiveChecksum,
|
||||
},
|
||||
},
|
||||
});
|
||||
return created;
|
||||
});
|
||||
return { imported: true, idempotent: false, version: this.publicVersion(version) };
|
||||
} catch (error) {
|
||||
if (storedArtifactPath) await fs.rm(storedArtifactPath, { force: true });
|
||||
throw error;
|
||||
} finally {
|
||||
await fs.rm(temporaryRoot, { recursive: true, force: true });
|
||||
}
|
||||
}
|
||||
|
||||
async publish(id: string, actorId: string, requestId?: string) {
|
||||
return this.transition(id, actorId, "published", requestId);
|
||||
}
|
||||
|
||||
async retire(id: string, actorId: string, requestId?: string) {
|
||||
return this.transition(id, actorId, "retired", requestId);
|
||||
}
|
||||
|
||||
async audit(id: string) {
|
||||
const version = await this.prisma.templatePackageVersion.findUnique({ where: { id } });
|
||||
if (!version) throw new BadRequestException("模板版本不存在");
|
||||
return this.prisma.templatePackageAuditLog.findMany({
|
||||
where: { templatePackageVersionId: id },
|
||||
orderBy: { createdAt: "asc" },
|
||||
include: { actor: { select: { id: true, username: true, displayName: true } } },
|
||||
});
|
||||
}
|
||||
|
||||
private async transition(
|
||||
id: string,
|
||||
actorId: string,
|
||||
target: "published" | "retired",
|
||||
requestId?: string,
|
||||
) {
|
||||
const version = await this.prisma.templatePackageVersion.findUnique({ where: { id } });
|
||||
if (!version) throw new BadRequestException("模板版本不存在");
|
||||
if (version.status === target) return { changed: false, version: this.publicVersion(version) };
|
||||
const valid =
|
||||
target === "published" ? version.status === "imported" : version.status === "published";
|
||||
if (!valid) throw new ConflictException(`模板版本当前状态为 ${version.status},不能执行此操作`);
|
||||
const updated = await this.prisma.$transaction(async (tx) => {
|
||||
const changed = await tx.templatePackageVersion.updateMany({
|
||||
where: { id, status: version.status },
|
||||
data: { status: target },
|
||||
});
|
||||
if (changed.count !== 1) {
|
||||
const current = await tx.templatePackageVersion.findUnique({ where: { id } });
|
||||
if (current?.status === target) return { next: current, changed: false };
|
||||
throw new ConflictException("模板版本状态已被其他操作修改,请刷新后重试");
|
||||
}
|
||||
const next = await tx.templatePackageVersion.findUniqueOrThrow({ where: { id } });
|
||||
await tx.templatePackageAuditLog.create({
|
||||
data: {
|
||||
templatePackageVersionId: id,
|
||||
actorId,
|
||||
action: target,
|
||||
fromStatus: version.status,
|
||||
toStatus: target,
|
||||
...(requestId ? { requestId } : {}),
|
||||
},
|
||||
});
|
||||
return { next, changed: true };
|
||||
});
|
||||
return { changed: updated.changed, version: this.publicVersion(updated.next) };
|
||||
}
|
||||
|
||||
private async readJson(filePath: string, label: string): Promise<unknown> {
|
||||
try {
|
||||
return JSON.parse(await fs.readFile(filePath, "utf8")) as unknown;
|
||||
} catch {
|
||||
throw new BadRequestException(`${label} 不是有效的 JSON 文件`);
|
||||
}
|
||||
}
|
||||
|
||||
private validateManifest(
|
||||
manifest: Manifest,
|
||||
packageJson: { name?: unknown; version?: unknown },
|
||||
checksums: ChecksumFile,
|
||||
) {
|
||||
if (!manifest || typeof manifest !== "object")
|
||||
throw new BadRequestException("template.json 无效");
|
||||
if (!PACKAGE_KEY_PATTERN.test(manifest.packageKey))
|
||||
throw new BadRequestException("模板 packageKey 无效");
|
||||
if (typeof manifest.version !== "string" || !manifest.version.trim())
|
||||
throw new BadRequestException("模板 version 无效");
|
||||
if (typeof manifest.displayName !== "string" || !manifest.displayName.trim())
|
||||
throw new BadRequestException("模板 displayName 无效");
|
||||
if (packageJson.name !== `@personal-brand/template-${manifest.packageKey}`)
|
||||
throw new BadRequestException("package.json name 与 template.json packageKey 不一致");
|
||||
if (packageJson.version !== manifest.version)
|
||||
throw new BadRequestException("package.json version 与 template.json version 不一致");
|
||||
let errors: string[];
|
||||
try {
|
||||
errors = validateTemplatePackageManifest(manifest as never);
|
||||
} catch {
|
||||
throw new BadRequestException("template.json 不符合模板契约");
|
||||
}
|
||||
if (errors.length)
|
||||
throw new BadRequestException(`template.json 不符合模板契约:${errors.join(";")}`);
|
||||
if (
|
||||
checksums.formatVersion !== "1" ||
|
||||
checksums.packageKey !== manifest.packageKey ||
|
||||
checksums.version !== manifest.version
|
||||
)
|
||||
throw new BadRequestException("checksums.json 元数据不一致");
|
||||
}
|
||||
|
||||
private async validateChecksums(
|
||||
packageRoot: string,
|
||||
files: Array<{ path: string; bytes: number }>,
|
||||
checksums: ChecksumFile,
|
||||
) {
|
||||
if (!Array.isArray(checksums.files) || checksums.files.length !== files.length - 1)
|
||||
throw new BadRequestException("checksums.json 文件清单不完整");
|
||||
const comparePath = (left: { path: string }, right: { path: string }) =>
|
||||
left.path < right.path ? -1 : left.path > right.path ? 1 : 0;
|
||||
const actualFiles = files.filter((file) => file.path !== "checksums.json").sort(comparePath);
|
||||
const checksumFiles = [...checksums.files].sort(comparePath);
|
||||
if (checksumFiles.some((item, index) => item.path !== actualFiles[index]?.path))
|
||||
throw new BadRequestException("checksums.json 文件清单与 archive 不一致");
|
||||
for (const item of checksumFiles) {
|
||||
safeEntryName(item.path);
|
||||
if (
|
||||
!Number.isSafeInteger(item.bytes) ||
|
||||
item.bytes < 0 ||
|
||||
!/^[a-f0-9]{64}$/.test(item.sha256)
|
||||
)
|
||||
throw new BadRequestException("checksums.json 文件摘要格式无效");
|
||||
const content = fs.readFile(path.join(packageRoot, item.path));
|
||||
if (item.bytes !== actualFiles.find((file) => file.path === item.path)?.bytes)
|
||||
throw new BadRequestException("模板文件大小校验失败");
|
||||
if (sha256(await content) !== item.sha256)
|
||||
throw new BadRequestException("模板文件摘要校验失败");
|
||||
}
|
||||
const expected = sha256(JSON.stringify(canonical(checksumFiles)));
|
||||
if (checksums.contentChecksum !== expected || !/^[a-f0-9]{64}$/.test(checksums.contentChecksum))
|
||||
throw new BadRequestException("模板内容摘要校验失败");
|
||||
}
|
||||
|
||||
private publicVersion(version: {
|
||||
id: string;
|
||||
packageKey: string;
|
||||
version: string;
|
||||
displayName: string;
|
||||
visualTemplateKey: string | null;
|
||||
status: string;
|
||||
contentChecksum: string;
|
||||
archiveChecksum: string;
|
||||
importedAt: Date;
|
||||
}) {
|
||||
return {
|
||||
id: version.id,
|
||||
packageKey: version.packageKey,
|
||||
version: version.version,
|
||||
displayName: version.displayName,
|
||||
visualTemplateKey: version.visualTemplateKey,
|
||||
status: version.status,
|
||||
contentChecksum: version.contentChecksum,
|
||||
archiveChecksum: version.archiveChecksum,
|
||||
importedAt: version.importedAt,
|
||||
};
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user