517 lines
20 KiB
TypeScript
517 lines
20 KiB
TypeScript
import {
|
||
BadRequestException,
|
||
ConflictException,
|
||
Injectable,
|
||
PayloadTooLargeException,
|
||
} from "@nestjs/common";
|
||
import { validateTemplatePackageManifest } from "@personal-brand/config";
|
||
import { validateTemplatePreviewFixtures } from "@personal-brand/validation";
|
||
import type { 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";
|
||
import { recordTemplateOperationFailure } from "./template-operation-failure.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;
|
||
supportedIndustryTemplates?: string[];
|
||
previewFixture?: Prisma.InputJsonValue;
|
||
};
|
||
|
||
type ChecksumFile = {
|
||
formatVersion: string;
|
||
packageKey: string;
|
||
version: string;
|
||
contentChecksum: string;
|
||
files: Array<{ path: string; bytes: number; sha256: string }>;
|
||
};
|
||
|
||
type JsonRecord = Record<string, unknown>;
|
||
|
||
function record(value: unknown): JsonRecord {
|
||
return value && typeof value === "object" && !Array.isArray(value) ? (value as JsonRecord) : {};
|
||
}
|
||
|
||
function array(value: unknown): unknown[] {
|
||
return Array.isArray(value) ? value : [];
|
||
}
|
||
|
||
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,
|
||
manifestSnapshot: true,
|
||
importedAt: true,
|
||
updatedAt: true,
|
||
templatePackage: { select: { id: true } },
|
||
importedBy: { select: { id: true, username: true, displayName: true } },
|
||
},
|
||
}),
|
||
]);
|
||
return {
|
||
items: versions.map(({ templatePackage, manifestSnapshot, ...version }) => ({
|
||
...version,
|
||
templatePackageId: templatePackage.id,
|
||
manifestSummary: {
|
||
runtimeContract:
|
||
typeof record(manifestSnapshot).runtimeContract === "string"
|
||
? (record(manifestSnapshot).runtimeContract as string)
|
||
: "",
|
||
supportedIndustryTemplates: array(
|
||
record(manifestSnapshot).supportedIndustryTemplates,
|
||
).filter((item): item is string => typeof item === "string"),
|
||
requiredCapabilities: array(record(manifestSnapshot).requiredCapabilities).filter(
|
||
(item): item is string => typeof item === "string",
|
||
),
|
||
},
|
||
})),
|
||
page,
|
||
pageSize,
|
||
total,
|
||
};
|
||
}
|
||
|
||
async importArchive(request: FastifyRequest, actorId: string, requestId?: 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;
|
||
let failurePackageKey: string | undefined;
|
||
let failureVersion: string | undefined;
|
||
try {
|
||
for await (const chunk of part.file) {
|
||
const buffer = Buffer.from(chunk as Uint8Array);
|
||
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;
|
||
failurePackageKey = typeof manifest.packageKey === "string" ? manifest.packageKey : undefined;
|
||
failureVersion = typeof manifest.version === "string" ? manifest.version : undefined;
|
||
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,
|
||
validationReport: {
|
||
formatVersion: "1",
|
||
errors: [],
|
||
fileCount: files.length,
|
||
extractedBytes: files.reduce((total, file) => total + file.bytes, 0),
|
||
files: checksums.files.map((file) => ({ ...file })),
|
||
},
|
||
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 });
|
||
await recordTemplateOperationFailure(this.prisma, {
|
||
action: "import",
|
||
error,
|
||
...(requestId ? { requestId } : {}),
|
||
actorId,
|
||
...(failurePackageKey ? { packageKey: failurePackageKey } : {}),
|
||
...(failureVersion ? { version: failureVersion } : {}),
|
||
});
|
||
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) };
|
||
// retired 是目录可见性的终态,但平台管理员可以显式重新发布;品牌安装与历史快照不受影响。
|
||
const valid =
|
||
target === "published"
|
||
? version.status === "imported" || version.status === "retired"
|
||
: 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 (manifest.previewFixture !== undefined) {
|
||
const issues = validateTemplatePreviewFixtures(
|
||
manifest.previewFixture,
|
||
manifest.supportedIndustryTemplates ?? [],
|
||
);
|
||
if (issues.length)
|
||
throw new BadRequestException(
|
||
`previewFixture 不符合预览契约:${issues.map((issue) => `${issue.path}: ${issue.message}`).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,
|
||
};
|
||
}
|
||
}
|