refactor: 拆分媒体上传职责并锁定API路由

This commit is contained in:
que01 committed 2026-10-15 14:52:59 +08:00
1 parent 6f18c67315
commit 2ad009f5c0
8 files changed
+375 -171

No files matched your search

@@ -1,23 +1,14 @@
import { BadRequestException, Controller, Put, Query, Req } from "@nestjs/common";
import { mkdir, writeFile } from "node:fs/promises";
import path from "node:path";
import { Controller, Put, Query, Req } from "@nestjs/common";
import type { FastifyRequest } from "fastify";
import { AdminAccessService } from "../../admin-access.service.js";
const allowedExtensions = new Map([
["image/jpeg", ".jpg"],
["image/png", ".png"],
["image/webp", ".webp"],
["image/avif", ".avif"],
]);
import { AdminUploadService } from "./admin-upload.service.js";
@Controller("admin/uploads")
export class AdminLocalUploadController {
constructor(private readonly access: AdminAccessService) {}
private get mediaRoot(): string {
return path.resolve(process.env.LOCAL_MEDIA_ROOT || path.join(process.cwd(), "media"));
}
constructor(
private readonly access: AdminAccessService,
private readonly uploads: AdminUploadService,
) {}
@Put("local")
async upload(
@@ -26,30 +17,11 @@ export class AdminLocalUploadController {
): Promise<{ saved: true }> {
await this.access.requireBrand(request);
const rawKey = key ?? (request.query as { key?: string }).key;
const decodedKey = (rawKey ?? "").includes("%")
? decodeURIComponent(rawKey as string)
: (rawKey ?? "");
if (
!decodedKey ||
decodedKey.includes("..") ||
decodedKey.startsWith("/") ||
!/^\d{4}\//.test(decodedKey)
) {
throw new BadRequestException("上传 key 无效");
}
if (!allowedExtensions.has(request.headers["content-type"] ?? "")) {
throw new BadRequestException("仅支持图片上传");
}
const contentType = allowedExtensions.get(request.headers["content-type"] ?? "");
if (!contentType || !decodedKey.endsWith(contentType)) {
throw new BadRequestException("上传文件类型与 key 不一致");
}
const target = path.join(this.mediaRoot, decodedKey);
if (!target.startsWith(path.resolve(this.mediaRoot))) {
throw new BadRequestException("上传 key 无效");
}
await mkdir(path.dirname(target), { recursive: true });
await writeFile(target, request.body as Buffer);
await this.uploads.saveLocal(
rawKey ?? "",
request.headers["content-type"] ?? "",
request.body as Buffer,
);
return { saved: true };
}
}
@@ -1,145 +1,24 @@
import { BadRequestException, Body, Controller, Get, Post, Req } from "@nestjs/common";
import { HeadBucketCommand, PutObjectCommand, S3Client } from "@aws-sdk/client-s3";
import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
import { createHash, randomUUID } from "node:crypto";
import { mkdir } from "node:fs/promises";
import path from "node:path";
import { Body, Controller, Get, Post, Req } from "@nestjs/common";
import type { FastifyRequest } from "fastify";
import { IsIn, IsOptional, IsString, MaxLength } from "class-validator";
import { AdminAccessService } from "../../admin-access.service.js";
export class PresignUploadDto {
@IsString()
@MaxLength(255)
fileName!: string;
@IsString()
@IsIn(["image/jpeg", "image/png", "image/webp", "image/avif"])
contentType!: string;
@IsOptional()
@IsString()
@MaxLength(64)
scope?: "brand" | "offering" | "trust";
}
class ObjectStorage {
private readonly client = new S3Client({
region: process.env.OBJECT_STORAGE_REGION || "us-east-1",
...(process.env.OBJECT_STORAGE_ENDPOINT
? { endpoint: process.env.OBJECT_STORAGE_ENDPOINT }
: {}),
forcePathStyle: Boolean(process.env.OBJECT_STORAGE_ENDPOINT),
credentials: {
accessKeyId: process.env.OBJECT_STORAGE_ACCESS_KEY || "",
secretAccessKey: process.env.OBJECT_STORAGE_SECRET_KEY || "",
},
});
private get bucket(): string {
const bucket = process.env.OBJECT_STORAGE_BUCKET;
if (!bucket) throw new BadRequestException("媒体上传尚未配置");
return bucket;
}
publicUrl(key: string): string {
const endpoint = process.env.OBJECT_STORAGE_PUBLIC_URL?.replace(/\/$/, "");
return endpoint ? `${endpoint}/${key}` : `/${key}`;
}
get bucketName(): string {
return this.bucket;
}
async presignPut(key: string, contentType: string): Promise<string> {
return getSignedUrl(
this.client,
new PutObjectCommand({ Bucket: this.bucket, Key: key, ContentType: contentType }),
{ expiresIn: 600 },
);
}
async checkBucket(): Promise<"ok" | "unavailable"> {
try {
await this.client.send(new HeadBucketCommand({ Bucket: this.bucket }));
return "ok";
} catch {
return "unavailable";
}
}
}
const allowedExtensions = new Map([
["image/jpeg", ".jpg"],
["image/png", ".png"],
["image/webp", ".webp"],
["image/avif", ".avif"],
]);
import { PresignUploadDto } from "./admin-upload.dto.js";
import { AdminUploadService } from "./admin-upload.service.js";
@Controller("admin/uploads")
export class AdminUploadController {
private readonly storage = new ObjectStorage();
constructor(private readonly access: AdminAccessService) {}
private get localMediaRoot(): string {
return path.resolve(process.env.LOCAL_MEDIA_ROOT || path.join(process.cwd(), "media"));
}
private get localMediaBaseUrl(): string {
return process.env.LOCAL_MEDIA_BASE_URL || "/media";
}
constructor(
private readonly access: AdminAccessService,
private readonly uploads: AdminUploadService,
) {}
@Get("config")
async config() {
const objectStorageConfigured = Boolean(
process.env.OBJECT_STORAGE_BUCKET &&
process.env.OBJECT_STORAGE_ACCESS_KEY &&
process.env.OBJECT_STORAGE_SECRET_KEY,
);
const localMediaConfigured = Boolean(process.env.LOCAL_MEDIA_ROOT);
if (localMediaConfigured) {
return { configured: true, status: "ok", mode: "local" };
}
const configured = Boolean(objectStorageConfigured);
return {
configured,
status: configured ? await this.storage.checkBucket() : "unconfigured",
...(configured ? { bucket: this.storage.bucketName } : {}),
...(configured ? { mode: "object-storage" } : {}),
};
return this.uploads.getConfiguration();
}
@Post("presign")
async presign(@Req() request: FastifyRequest, @Body() body: PresignUploadDto) {
await this.access.requireBrand(request);
const extension = allowedExtensions.get(body.contentType);
if (!extension) throw new BadRequestException("仅支持 JPG、PNG、WebP 或 AVIF 图片");
const cleanName = body.fileName
.toLowerCase()
.replace(/[^a-z0-9._-]+/g, "-")
.slice(-64);
const digest = createHash("sha256")
.update(`${body.scope ?? "brand"}:${cleanName}:${randomUUID()}`)
.digest("hex")
.slice(0, 16);
const key = `${new Date().getFullYear()}/${digest}${extension}`;
const objectStorageEnabled = Boolean(
process.env.OBJECT_STORAGE_BUCKET &&
process.env.OBJECT_STORAGE_ACCESS_KEY &&
process.env.OBJECT_STORAGE_SECRET_KEY,
);
if (objectStorageEnabled) {
const uploadUrl = await this.storage.presignPut(key, body.contentType);
return { uploadUrl, key, publicUrl: this.storage.publicUrl(key) };
}
const target = path.join(this.localMediaRoot, key);
await mkdir(path.dirname(target), { recursive: true });
return {
uploadUrl: `/admin/uploads/local?key=${encodeURIComponent(key)}`,
key,
publicUrl: `${this.localMediaBaseUrl}/${key}`,
mode: "local",
};
return this.uploads.presign(body);
}
}
@@ -0,0 +1,16 @@
import { IsIn, IsOptional, IsString, MaxLength } from "class-validator";
export class PresignUploadDto {
@IsString()
@MaxLength(255)
fileName!: string;
@IsString()
@IsIn(["image/jpeg", "image/png", "image/webp", "image/avif"])
contentType!: string;
@IsOptional()
@IsString()
@MaxLength(64)
scope?: "brand" | "offering" | "trust";
}
@@ -0,0 +1,164 @@
import { BadRequestException, Injectable } from "@nestjs/common";
import { HeadBucketCommand, PutObjectCommand, S3Client } from "@aws-sdk/client-s3";
import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
import { createHash, randomUUID } from "node:crypto";
import { mkdir, writeFile } from "node:fs/promises";
import path from "node:path";
import type { PresignUploadDto } from "./admin-upload.dto.js";
const allowedExtensions = new Map([
["image/jpeg", ".jpg"],
["image/png", ".png"],
["image/webp", ".webp"],
["image/avif", ".avif"],
]);
export interface UploadConfiguration {
configured: boolean;
status: "ok" | "unavailable" | "unconfigured";
bucket?: string;
mode: "local" | "object-storage";
}
export interface PresignedUpload {
uploadUrl: string;
key: string;
publicUrl: string;
mode?: "local";
}
class ObjectStorage {
private readonly client = new S3Client({
region: process.env.OBJECT_STORAGE_REGION || "us-east-1",
...(process.env.OBJECT_STORAGE_ENDPOINT
? { endpoint: process.env.OBJECT_STORAGE_ENDPOINT }
: {}),
forcePathStyle: Boolean(process.env.OBJECT_STORAGE_ENDPOINT),
credentials: {
accessKeyId: process.env.OBJECT_STORAGE_ACCESS_KEY || "",
secretAccessKey: process.env.OBJECT_STORAGE_SECRET_KEY || "",
},
});
private get bucket(): string {
const bucket = process.env.OBJECT_STORAGE_BUCKET;
if (!bucket) throw new BadRequestException("媒体上传尚未配置");
return bucket;
}
publicUrl(key: string): string {
const endpoint = process.env.OBJECT_STORAGE_PUBLIC_URL?.replace(/\/$/, "");
return endpoint ? `${endpoint}/${key}` : `/${key}`;
}
get bucketName(): string {
return this.bucket;
}
async presignPut(key: string, contentType: string): Promise<string> {
return getSignedUrl(
this.client,
new PutObjectCommand({ Bucket: this.bucket, Key: key, ContentType: contentType }),
{ expiresIn: 600 },
);
}
async checkBucket(): Promise<"ok" | "unavailable"> {
try {
await this.client.send(new HeadBucketCommand({ Bucket: this.bucket }));
return "ok";
} catch {
return "unavailable";
}
}
}
@Injectable()
export class AdminUploadService {
private readonly storage = new ObjectStorage();
async getConfiguration(): Promise<UploadConfiguration> {
if (this.localMediaConfigured) {
return { configured: true, status: "ok", mode: "local" };
}
const configured = this.objectStorageConfigured;
return {
configured,
status: configured ? await this.storage.checkBucket() : "unconfigured",
...(configured ? { bucket: this.storage.bucketName } : {}),
mode: "object-storage",
};
}
async presign(body: PresignUploadDto): Promise<PresignedUpload> {
const extension = this.extensionFor(body.contentType);
const cleanName = body.fileName
.toLowerCase()
.replace(/[^a-z0-9._-]+/g, "-")
.slice(-64);
const digest = createHash("sha256")
.update(`${body.scope ?? "brand"}:${cleanName}:${randomUUID()}`)
.digest("hex")
.slice(0, 16);
const key = `${new Date().getFullYear()}/${digest}${extension}`;
if (this.objectStorageConfigured) {
const uploadUrl = await this.storage.presignPut(key, body.contentType);
return { uploadUrl, key, publicUrl: this.storage.publicUrl(key) };
}
const target = path.join(this.localMediaRoot, key);
await mkdir(path.dirname(target), { recursive: true });
return {
uploadUrl: `/admin/uploads/local?key=${encodeURIComponent(key)}`,
key,
publicUrl: `${this.localMediaBaseUrl}/${key}`,
mode: "local",
};
}
async saveLocal(key: string, contentType: string, body: Buffer): Promise<void> {
const decodedKey = key.includes("%") ? decodeURIComponent(key) : key;
if (
!decodedKey ||
decodedKey.includes("..") ||
decodedKey.startsWith("/") ||
!/^\d{4}\//.test(decodedKey)
) {
throw new BadRequestException("上传 key 无效");
}
const extension = this.extensionFor(contentType);
if (!decodedKey.endsWith(extension)) {
throw new BadRequestException("上传文件类型与 key 不一致");
}
const mediaRoot = this.localMediaRoot;
const target = path.join(mediaRoot, decodedKey);
if (!target.startsWith(mediaRoot)) throw new BadRequestException("上传 key 无效");
await mkdir(path.dirname(target), { recursive: true });
await writeFile(target, body);
}
private extensionFor(contentType: string): string {
const extension = allowedExtensions.get(contentType);
if (!extension) throw new BadRequestException("仅支持 JPG、PNG、WebP 或 AVIF 图片");
return extension;
}
private get objectStorageConfigured(): boolean {
return Boolean(
process.env.OBJECT_STORAGE_BUCKET &&
process.env.OBJECT_STORAGE_ACCESS_KEY &&
process.env.OBJECT_STORAGE_SECRET_KEY,
);
}
private get localMediaConfigured(): boolean {
return Boolean(process.env.LOCAL_MEDIA_ROOT);
}
private get localMediaRoot(): string {
return path.resolve(process.env.LOCAL_MEDIA_ROOT || path.join(process.cwd(), "media"));
}
private get localMediaBaseUrl(): string {
return process.env.LOCAL_MEDIA_BASE_URL || "/media";
}
}
@@ -11,6 +11,7 @@ import { AdminMiniAppReleaseService } from "./admin-miniapp-release.service.js";
import { AdminMiniAppSettingsService } from "./admin-miniapp-settings.service.js";
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";
@Module({
@@ -29,6 +30,7 @@ import { AdminUploadController } from "./admin-upload.controller.js";
AdminMiniAppBuildService,
AdminMiniAppSettingsService,
AdminMiniAppUploadService,
AdminUploadService,
],
})
export class AdminModule {}
@@ -0,0 +1,83 @@
import assert from "node:assert/strict";
import { mkdtemp, readFile, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import path from "node:path";
import { test } from "node:test";
import { BadRequestException } from "@nestjs/common";
import { AdminUploadService } from "../src/modules/admin/admin-upload.service.js";
const environmentKeys = [
"OBJECT_STORAGE_BUCKET",
"OBJECT_STORAGE_ACCESS_KEY",
"OBJECT_STORAGE_SECRET_KEY",
"LOCAL_MEDIA_ROOT",
"LOCAL_MEDIA_BASE_URL",
] as const;
test("local mode reports configuration and returns a relative local upload URL", async () => {
const original = saveEnvironment();
const mediaRoot = await mkdtemp(path.join(tmpdir(), "personal-brand-uploads-"));
process.env.LOCAL_MEDIA_ROOT = mediaRoot;
process.env.LOCAL_MEDIA_BASE_URL = "/uploads";
try {
const service = new AdminUploadService();
assert.deepEqual(await service.getConfiguration(), {
configured: true,
status: "ok",
mode: "local",
});
const result = await service.presign({
fileName: "case study.png",
contentType: "image/png",
scope: "trust",
});
assert.match(result.key, /^\d{4}\/[a-f0-9]{16}\.png$/);
assert.equal(result.uploadUrl, `/admin/uploads/local?key=${encodeURIComponent(result.key)}`);
assert.equal(result.publicUrl, `/uploads/${result.key}`);
assert.equal(result.mode, "local");
await service.saveLocal(result.key, "image/png", Buffer.from("image-data"));
assert.equal(await readFile(path.join(mediaRoot, result.key), "utf8"), "image-data");
} finally {
await rm(mediaRoot, { recursive: true, force: true });
restoreEnvironment(original);
}
});
test("upload service validates media type and traversal keys before persistence", async () => {
const original = saveEnvironment();
const mediaRoot = await mkdtemp(path.join(tmpdir(), "personal-brand-uploads-"));
process.env.LOCAL_MEDIA_ROOT = mediaRoot;
try {
const service = new AdminUploadService();
await assert.rejects(
() => service.presign({ fileName: "document.pdf", contentType: "application/pdf" }),
BadRequestException,
);
await assert.rejects(
() => service.saveLocal("../2026/evil.png", "image/png", Buffer.from("evil")),
BadRequestException,
);
await assert.rejects(
() => service.saveLocal("2026/photo.jpg", "image/png", Buffer.from("mismatch")),
BadRequestException,
);
await assert.rejects(
() => service.saveLocal("2026/photo.png", "application/pdf", Buffer.from("mismatch")),
BadRequestException,
);
} finally {
await rm(mediaRoot, { recursive: true, force: true });
restoreEnvironment(original);
}
});
function saveEnvironment(): Record<(typeof environmentKeys)[number], string | undefined> {
return Object.fromEntries(environmentKeys.map((key) => [key, process.env[key]]));
}
function restoreEnvironment(values: Record<string, string | undefined>): void {
for (const key of environmentKeys) {
if (values[key] === undefined) delete process.env[key];
else process.env[key] = values[key];
}
}
+87
View File
@@ -0,0 +1,87 @@
import assert from "node:assert/strict";
import { test } from "node:test";
import "reflect-metadata";
import { RequestMethod } from "@nestjs/common";
import { MetadataScanner } from "@nestjs/core";
import { AppModule } from "../src/app.module.js";
import { AdminUploadController } from "../src/modules/admin/admin-upload.controller.js";
import { AdminLocalUploadController } from "../src/modules/admin/admin-local-upload.controller.js";
import { AdminWorkspacePreviewController } from "../src/modules/workspace/admin-workspace-preview.controller.js";
import { AdminTemplateController } from "../src/modules/workspace/admin-template.controller.js";
import { AdminCapabilityController } from "../src/modules/workspace/admin-capability.controller.js";
import { AdminOfferingController } from "../src/modules/workspace/admin-offering.controller.js";
import { AdminInquiryController } from "../src/modules/workspace/admin-inquiry.controller.js";
const expectedRoutes = new Set([
"GET /admin/workspace",
"GET /admin/workspace/preview",
"POST /admin/workspace/install",
"GET /admin/workspace/template/preview",
"POST /admin/workspace/template/upgrade",
"POST /admin/workspace/template/rollback",
"GET /admin/workspace/capabilities",
"GET /admin/workspace/sample-content/preview",
"POST /admin/workspace/sample-content/import",
"PATCH /admin/workspace/capabilities/:key",
"GET /admin/workspace/offerings",
"POST /admin/workspace/offerings",
"PATCH /admin/workspace/offerings/:id",
"DELETE /admin/workspace/offerings/:id",
"POST /admin/workspace/fields",
"PATCH /admin/workspace/fields/:id",
"DELETE /admin/workspace/fields/:id",
"GET /admin/workspace/forms",
"GET /admin/workspace/submissions",
"PATCH /admin/workspace/submissions/:id",
"POST /admin/workspace/forms",
"PATCH /admin/workspace/forms/:id",
"GET /admin/uploads/config",
"POST /admin/uploads/presign",
"PUT /admin/uploads/local",
]);
test("refactored admin controllers preserve their declared API routes", () => {
const controllers = [
AdminWorkspacePreviewController,
AdminTemplateController,
AdminCapabilityController,
AdminOfferingController,
AdminInquiryController,
AdminUploadController,
AdminLocalUploadController,
];
const scanner = new MetadataScanner();
const routes = controllers.flatMap((controller) =>
scanner.scanFromPrototype(controller, controller.prototype, (methodName) => {
const handler = controller.prototype[methodName];
const method = Reflect.getMetadata("method", handler);
assert.ok(
method !== undefined,
`Missing HTTP method metadata on ${controller.name}.${methodName}`,
);
const httpMethod = RequestMethod[method];
const controllerPath = Reflect.getMetadata("path", controller);
const handlerPath = Reflect.getMetadata("path", handler);
const routePath = `/${controllerPath}/${handlerPath ?? ""}`
.replace(/\/+$/, "")
.replace(/\/$/, "");
return `${httpMethod} ${routePath}`;
}),
);
assert.deepEqual([...routes].sort(), [...expectedRoutes].sort());
});
test("root module composes bounded feature modules only", () => {
const imports = Reflect.getMetadata("imports", AppModule) ?? [];
const names = imports.map((item) => item.name);
assert.deepEqual(names, [
"InfrastructureModule",
"PublicModule",
"CustomerModule",
"SessionModule",
"TenantModule",
"WorkspaceModule",
"AdminModule",
"HealthModule",
]);
});
+3 -2
View File
@@ -5,7 +5,7 @@ import path from "node:path";
import test from "node:test";
test("upload presign DTO rejects unsupported media type and oversized names", async () => {
const { PresignUploadDto } = await import("../dist/modules/admin/admin-upload.controller.js");
const { PresignUploadDto } = await import("../dist/modules/admin/admin-upload.dto.js");
const validator = await import("class-validator");
const invalid = new PresignUploadDto();
invalid.fileName = "x".repeat(256);
@@ -23,6 +23,7 @@ test("upload presign DTO rejects unsupported media type and oversized names", as
test("local upload presign targets the API route and requires brand access", async () => {
const { AdminUploadController } =
await import("../dist/modules/admin/admin-upload.controller.js");
const { AdminUploadService } = await import("../dist/modules/admin/admin-upload.service.js");
const mediaRoot = await mkdtemp(path.join(os.tmpdir(), "personal-brand-upload-"));
const previousRoot = process.env.LOCAL_MEDIA_ROOT;
const previousBucket = process.env.OBJECT_STORAGE_BUCKET;
@@ -34,7 +35,7 @@ test("local upload presign targets the API route and requires brand access", asy
delete process.env.OBJECT_STORAGE_ACCESS_KEY;
delete process.env.OBJECT_STORAGE_SECRET_KEY;
try {
const controller = new AdminUploadController(access);
const controller = new AdminUploadController(access, new AdminUploadService());
const result = await controller.presign(
{},
{ fileName: "portrait.jpg", contentType: "image/jpeg" },