feat: 接通后台渲染异常上报与响应契约校验

This commit is contained in:
que01 committed 2026-10-21 11:43:41 +08:00
1 parent 330d67adc1
commit adcaa12970
22 files changed
+845 -33

No files matched your search

+23
View File
@@ -0,0 +1,23 @@
import { IsOptional, IsString, Matches, MaxLength, MinLength } from "class-validator";
/** 后台渲染异常上报:只接受白名单字段,避免把任意浏览器数据写进日志。 */
export class CreateClientErrorDto {
@IsString()
@Matches(/^[A-Za-z0-9._-]{4,128}$/, { message: "errorId 格式不正确" })
errorId!: string;
@IsString()
@MinLength(1, { message: "message 不能为空" })
@MaxLength(2000, { message: "message 过长" })
message!: string;
@IsString()
@Matches(/^\//, { message: "route 必须以 / 开头" })
@MaxLength(500, { message: "route 过长" })
route!: string;
@IsOptional()
@IsString()
@MaxLength(20000, { message: "componentStack 过长" })
componentStack?: string;
}
@@ -0,0 +1,36 @@
import { AdminBrand } from "../../admin-auth.decorators.js";
import { Body, Controller, Post, Req } from "@nestjs/common";
import type { FastifyRequest } from "fastify";
import { AdminAccessService } from "../../admin-access.service.js";
import { CreateClientErrorDto } from "../../client-error.dto.js";
import { AdminClientErrorService } from "./admin-client-error.service.js";
@AdminBrand()
@Controller("admin/client-errors")
export class AdminClientErrorController {
constructor(
private readonly access: AdminAccessService,
private readonly errors: AdminClientErrorService,
) {}
@Post()
async create(
@Req() request: FastifyRequest,
@Body() body: CreateClientErrorDto,
): Promise<{ received: true; duplicate: boolean }> {
const identity = await this.access.requireBrand(request);
return this.errors.record({
subject: identity.subject,
brandId: identity.brandId,
errorId: body.errorId,
message: body.message,
route: body.route,
componentStack: body.componentStack,
requestId:
(request as FastifyRequest & { requestId?: string }).requestId ??
request.headers["x-request-id"]?.toString() ??
null,
userAgent: request.headers["user-agent"]?.toString().slice(0, 300) ?? null,
});
}
}
@@ -0,0 +1,91 @@
import { HttpException, Injectable } from "@nestjs/common";
const RATE_WINDOW_MS = 60_000;
const RATE_LIMIT = 10;
const DEDUPE_TTL_MS = 10 * 60_000;
const DEDUPE_CAPACITY = 500;
const LOG_STACK_LIMIT = 4000;
export interface ClientErrorReport {
subject: string;
brandId: string;
errorId: string;
message: string;
route: string;
componentStack?: string | undefined;
requestId: string | null;
userAgent: string | null;
}
export interface ClientErrorReceipt {
received: true;
duplicate: boolean;
}
/**
* 后台渲染异常去重与限流。
* 当前生产为单实例 PM2,因此使用进程内窗口;扩成多实例前需要换成共享存储。
*/
@Injectable()
export class AdminClientErrorService {
private readonly recentErrorIds = new Map<string, number>();
private readonly windows = new Map<string, number[]>();
record(report: ClientErrorReport): ClientErrorReceipt {
const now = Date.now();
this.prune(now);
const dedupeKey = `${report.subject}:${report.errorId}`;
if (this.recentErrorIds.has(dedupeKey)) {
return { received: true, duplicate: true };
}
this.assertWithinRate(report.subject, now);
this.recentErrorIds.set(dedupeKey, now);
this.trimDedupe();
console.error("admin client error", {
errorId: report.errorId,
message: report.message,
route: report.route,
subject: report.subject,
brandId: report.brandId,
requestId: report.requestId,
userAgent: report.userAgent,
componentStack: report.componentStack?.slice(0, LOG_STACK_LIMIT) ?? null,
});
return { received: true, duplicate: false };
}
private assertWithinRate(subject: string, now: number): void {
const recent = (this.windows.get(subject) ?? []).filter(
(timestamp) => now - timestamp < RATE_WINDOW_MS,
);
if (recent.length >= RATE_LIMIT) {
this.windows.set(subject, recent);
throw new HttpException("客户端错误上报过于频繁,请稍后再试", 429);
}
recent.push(now);
this.windows.set(subject, recent);
}
private prune(now: number): void {
for (const [key, timestamp] of this.recentErrorIds) {
if (now - timestamp >= DEDUPE_TTL_MS) this.recentErrorIds.delete(key);
}
for (const [subject, timestamps] of this.windows) {
const recent = timestamps.filter((timestamp) => now - timestamp < RATE_WINDOW_MS);
if (recent.length === 0) this.windows.delete(subject);
else this.windows.set(subject, recent);
}
}
private trimDedupe(): void {
while (this.recentErrorIds.size > DEDUPE_CAPACITY) {
const oldest = this.recentErrorIds.keys().next();
if (oldest.done) return;
this.recentErrorIds.delete(oldest.value);
}
}
}
@@ -2,6 +2,8 @@ import { Module } from "@nestjs/common";
import { BookingModule } from "../booking.module.js";
import { InfrastructureModule } from "../infrastructure.module.js";
import { AdminBookingController } from "./admin-booking.controller.js";
import { AdminClientErrorController } from "./admin-client-error.controller.js";
import { AdminClientErrorService } from "./admin-client-error.service.js";
import { AdminBrandConfigService } from "./admin-brand-config.service.js";
import { AdminConfigController } from "./admin-config.controller.js";
import { AdminLocalUploadController } from "./admin-local-upload.controller.js";
@@ -32,6 +34,7 @@ import { AdminTemplatePreviewAssetsService } from "./admin-template-preview-asse
AdminBookingController,
AdminTemplatePackageController,
TemplateOperationMetricsController,
AdminClientErrorController,
],
providers: [
AdminBrandConfigService,
@@ -44,6 +47,7 @@ import { AdminTemplatePreviewAssetsService } from "./admin-template-preview-asse
AdminTemplatePreviewService,
AdminTemplatePreviewAssetsService,
TemplateOperationMetricsService,
AdminClientErrorService,
],
})
export class AdminModule {}
@@ -0,0 +1,55 @@
import assert from "node:assert/strict";
import { test } from "node:test";
import { HttpException } from "@nestjs/common";
import { AdminClientErrorService } from "../src/modules/admin/admin-client-error.service.js";
function report(errorId: string, subject = "admin:user-1") {
return {
subject,
brandId: "brand-1",
errorId,
message: "boom",
route: "/admin/trust",
requestId: "req-1",
userAgent: "test-agent",
};
}
test("首次上报记录,相同 errorId 在窗口内按管理员去重", () => {
const service = new AdminClientErrorService();
assert.deepEqual(service.record(report("admin-error-1")), {
received: true,
duplicate: false,
});
assert.deepEqual(service.record(report("admin-error-1")), {
received: true,
duplicate: true,
});
// 不同管理员使用相同 errorId 时互不影响
assert.deepEqual(service.record(report("admin-error-1", "admin:user-2")), {
received: true,
duplicate: false,
});
});
test("同一管理员 60 秒内最多接受 10 条不同错误", () => {
const service = new AdminClientErrorService();
for (let index = 0; index < 10; index += 1) {
assert.deepEqual(service.record(report(`admin-rate-${index}`)), {
received: true,
duplicate: false,
});
}
try {
service.record(report("admin-rate-overflow"));
assert.fail("应当触发限流");
} catch (error) {
assert.ok(error instanceof HttpException);
assert.equal(error.getStatus(), 429);
}
// 另一个管理员不受影响
assert.deepEqual(service.record(report("admin-rate-other", "admin:user-2")), {
received: true,
duplicate: false,
});
});
+36
View File
@@ -1892,6 +1892,42 @@ async function request(url, options = {}) {
});
}
test("admin client error reports are authenticated, validated, and deduplicated", async () => {
await assertProtectedRouteBoundary("/admin/client-errors", {
method: "POST",
payload: { errorId: "admin-boundary-check", message: "boom", route: "/admin/publication" },
});
const login = await request("/admin/session/login", {
method: "POST",
payload: { username: "admin", password: process.env.SEED_ADMIN_PASSWORD },
});
assert.equal(login.statusCode, 201);
const headers = { authorization: `Bearer ${sessionToken(login)}` };
const errorId = `admin-it-${Date.now().toString(36)}`;
const payload = {
errorId,
message: "Cannot read properties of null (reading 'type')",
route: "/admin/trust?tab=1",
componentStack: "at TrustContentPage",
};
const first = await request("/admin/client-errors", { method: "POST", headers, payload });
assert.equal(first.statusCode, 201);
assert.deepEqual(JSON.parse(first.body), { received: true, duplicate: false });
const duplicate = await request("/admin/client-errors", { method: "POST", headers, payload });
assert.equal(duplicate.statusCode, 201);
assert.deepEqual(JSON.parse(duplicate.body), { received: true, duplicate: true });
const invalid = await request("/admin/client-errors", {
method: "POST",
headers,
payload: { errorId: "bad", message: "", route: "no-slash" },
});
assert.equal(invalid.statusCode, 400);
});
async function assertProtectedRouteBoundary(url, options = {}) {
const { method = "GET", payload, forbiddenRole = "customer", headers = {} } = options;
const requestOptions = payload === undefined ? { method, headers } : { method, headers, payload };
+7
View File
@@ -657,6 +657,13 @@ export const ROUTE_COVERAGE: RouteCoverage[] = [
authorizationTest: null,
successTest: "wechat login creates a customer session for the requested brand",
},
{
method: "POST",
path: "/admin/client-errors",
auth: "brand",
authorizationTest: "admin client error reports are authenticated, validated, and deduplicated",
successTest: "admin client error reports are authenticated, validated, and deduplicated",
},
{
method: "PUT",
path: "/admin/uploads/local",