feat: 完成模板目录导入与生命周期管理

This commit is contained in:
que01 committed 2026-10-16 16:34:24 +08:00
1 parent 553a07c4ec
commit 413413efda
25 files changed
+1313 -24

No files matched your search

+23 -2
View File
@@ -21,9 +21,9 @@ export class AdminAccessService {
if (identity.role !== "admin") throw new ForbiddenException("无管理员权限");
const user = await this.prisma.adminUser.findUnique({
where: { id: identity.subject },
select: { mustChangePassword: true },
select: { mustChangePassword: true, isEnabled: true },
});
if (!user || user.mustChangePassword)
if (!user?.isEnabled || user.mustChangePassword)
throw new ForbiddenException("请先完成初始密码修改后再访问管理后台");
const membership = await this.prisma.brandMembership.findUnique({
where: { adminUserId_brandId: { adminUserId: identity.subject, brandId: identity.brandId } },
@@ -39,4 +39,25 @@ export class AdminAccessService {
}
return true;
}
async requireTemplateAdmin(request: FastifyRequest): Promise<{ subject: string }> {
const token = request.headers.authorization?.replace(/^Bearer\s+/i, "");
if (!token) throw new UnauthorizedException("缺少管理员登录态");
let identity;
try {
identity = readIdentity(token);
} catch {
throw new UnauthorizedException("管理员登录态无效或已过期");
}
if (identity.role !== "admin") throw new ForbiddenException("无管理员权限");
const user = await this.prisma.adminUser.findUnique({
where: { id: identity.subject },
select: { isEnabled: true, mustChangePassword: true, platformTemplateRole: true },
});
if (!user?.isEnabled || user.mustChangePassword)
throw new ForbiddenException("请先完成初始密码修改后再访问管理后台");
if (user.platformTemplateRole !== "template_admin")
throw new ForbiddenException("当前账号没有模板管理权限");
return { subject: identity.subject };
}
}
+8 -1
View File
@@ -10,7 +10,13 @@ export class AdminAuthService {
async login(
username: string,
password: string,
): Promise<{ token: string; displayName: string; mustChangePassword: boolean; role: string }> {
): Promise<{
token: string;
displayName: string;
mustChangePassword: boolean;
role: string;
platformTemplateRole: string;
}> {
const user = await this.prisma.adminUser.findUnique({ where: { username } });
if (!user || !user.isEnabled || !(await bcrypt.compare(password, user.passwordHash))) {
throw new UnauthorizedException("账号或密码错误");
@@ -41,6 +47,7 @@ export class AdminAuthService {
displayName: user.displayName,
mustChangePassword: user.mustChangePassword,
role: activeMembership.role,
platformTemplateRole: user.platformTemplateRole,
};
}
+3
View File
@@ -17,6 +17,9 @@ export class AdminMembershipGuard implements CanActivate {
if (routePath === "admin/session/login") return Promise.resolve(true);
if (routePath === "admin/session/change-password") return Promise.resolve(true);
if (!routePath.startsWith("admin/")) return Promise.resolve(true);
if (routePath === "admin/templates" || routePath.startsWith("admin/templates/")) {
return this.access.requireTemplateAdmin(request).then(() => true);
}
if (
/^admin\/workspace\/(install|capabilities(?:\/|$)|template(?:\/|$)|fields(?:\/|$))/.test(
routePath,
@@ -0,0 +1,43 @@
import { Controller, Get, Param, Post, Query, Req } from "@nestjs/common";
import type { FastifyRequest } from "fastify";
import { AdminAccessService } from "../../admin-access.service.js";
import { ListTemplatePackagesQueryDto } from "./admin-template-package.dto.js";
import { AdminTemplatePackageService } from "./admin-template-package.service.js";
@Controller("admin/templates")
export class AdminTemplatePackageController {
constructor(
private readonly access: AdminAccessService,
private readonly templates: AdminTemplatePackageService,
) {}
@Get()
list(
@Query() query: ListTemplatePackagesQueryDto,
): ReturnType<AdminTemplatePackageService["list"]> {
return this.templates.list(query.page, query.pageSize);
}
@Post("import")
async import(@Req() request: FastifyRequest) {
const { subject } = await this.access.requireTemplateAdmin(request);
return this.templates.importArchive(request, subject);
}
@Post(":id/publish")
async publish(@Req() request: FastifyRequest, @Param("id") id: string) {
const { subject } = await this.access.requireTemplateAdmin(request);
return this.templates.publish(id, subject, request.headers["x-request-id"]?.toString());
}
@Post(":id/retire")
async retire(@Req() request: FastifyRequest, @Param("id") id: string) {
const { subject } = await this.access.requireTemplateAdmin(request);
return this.templates.retire(id, subject, request.headers["x-request-id"]?.toString());
}
@Get(":id/audit")
audit(@Param("id") id: string): ReturnType<AdminTemplatePackageService["audit"]> {
return this.templates.audit(id);
}
}
@@ -0,0 +1,17 @@
import { Type } from "class-transformer";
import { IsInt, IsOptional, Max, Min } from "class-validator";
export class ListTemplatePackagesQueryDto {
@IsOptional()
@Type(() => Number)
@IsInt()
@Min(1)
page = 1;
@IsOptional()
@Type(() => Number)
@IsInt()
@Min(1)
@Max(100)
pageSize = 20;
}
@@ -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,
};
}
}
@@ -13,6 +13,8 @@ import { AdminMiniAppUploadService } from "./admin-miniapp-upload.service.js";
import { AdminReleaseController } from "./admin-release.controller.js";
import { AdminUploadService } from "./admin-upload.service.js";
import { AdminUploadController } from "./admin-upload.controller.js";
import { AdminTemplatePackageController } from "./admin-template-package.controller.js";
import { AdminTemplatePackageService } from "./admin-template-package.service.js";
@Module({
imports: [InfrastructureModule, BookingModule],
@@ -23,6 +25,7 @@ import { AdminUploadController } from "./admin-upload.controller.js";
AdminUploadController,
AdminLocalUploadController,
AdminBookingController,
AdminTemplatePackageController,
],
providers: [
AdminBrandConfigService,
@@ -31,6 +34,7 @@ import { AdminUploadController } from "./admin-upload.controller.js";
AdminMiniAppSettingsService,
AdminMiniAppUploadService,
AdminUploadService,
AdminTemplatePackageService,
],
})
export class AdminModule {}
@@ -29,9 +29,13 @@ export class AdminSessionController {
constructor(private readonly auth: AdminAuthService) {}
@Post("login")
login(
@Body() body: AdminLoginDto,
): Promise<{ token: string; displayName: string; mustChangePassword: boolean; role: string }> {
login(@Body() body: AdminLoginDto): Promise<{
token: string;
displayName: string;
mustChangePassword: boolean;
role: string;
platformTemplateRole: string;
}> {
return this.auth.login(body.username, body.password);
}