diff --git a/.codex-tasks/template-audit-execution/raw/completion-evidence.json b/.codex-tasks/template-audit-execution/raw/completion-evidence.json index 91f8f48..f64078c 100644 --- a/.codex-tasks/template-audit-execution/raw/completion-evidence.json +++ b/.codex-tasks/template-audit-execution/raw/completion-evidence.json @@ -1,7 +1,7 @@ { "schemaVersion": 1, "scope": "模板完成证据登记,保留命令、日志与产物哈希", - "generatedAt": "2026-10-23T04:57:00.699Z", + "generatedAt": "2026-10-23T04:57:10.362Z", "templates": { "acheng-campus-food": { "real-manifest-interaction": { @@ -256,5 +256,5 @@ } } }, - "sourceTreeHash": "1ffdc0a1b62271bbb621546a212aa7a05f1d0b797963a6332ce14bc5c35fe1ab" + "sourceTreeHash": "4eae37312c6ef28bb51218923440e8e0b5b6a823875a0061519af73481a1897d" } diff --git a/.env.example b/.env.example index 3b00f0c..8f06002 100644 --- a/.env.example +++ b/.env.example @@ -9,6 +9,8 @@ API_PREFIX= CORS_ORIGINS=http://localhost:3000 ADMIN_PORT=3000 SESSION_SECRET=replace-with-a-long-random-value +# 单实例使用 memory;多实例部署改用 postgres 并先执行数据库迁移 +CLIENT_ERROR_THROTTLE_STORE=memory DEFAULT_BRAND_ID=00000000-0000-0000-0000-000000000001 TEMPLATE_ARTIFACT_ROOT=/var/lib/personal-brand/template-artifacts SEED_ADMIN_PASSWORD=change-me-now-123 diff --git a/.env.production.example b/.env.production.example index 6ece959..be486fe 100644 --- a/.env.production.example +++ b/.env.production.example @@ -6,6 +6,8 @@ POSTGRES_PORT=5432 DATABASE_URL=postgresql://personal_brand:replace-with-a-long-database-password@127.0.0.1:5432/personal_brand?schema=public SESSION_SECRET=replace-with-at-least-32-random-characters +# 单实例使用 memory;多实例部署改用 postgres 并先执行数据库迁移 +CLIENT_ERROR_THROTTLE_STORE=memory DEFAULT_BRAND_ID=00000000-0000-0000-0000-000000000001 SEED_ADMIN_PASSWORD=replace-with-a-one-time-initial-password SEED_MODE=skip diff --git a/apps/api/prisma/migrations/20261023130000_add_client_error_throttle/migration.sql b/apps/api/prisma/migrations/20261023130000_add_client_error_throttle/migration.sql new file mode 100644 index 0000000..5c64178 --- /dev/null +++ b/apps/api/prisma/migrations/20261023130000_add_client_error_throttle/migration.sql @@ -0,0 +1,28 @@ +-- CreateTable +CREATE TABLE "ClientErrorThrottleWindow" ( + "subject" TEXT NOT NULL, + "windowStart" TIMESTAMP(3) NOT NULL, + "count" INTEGER NOT NULL, + "updatedAt" TIMESTAMP(3) NOT NULL, + + CONSTRAINT "ClientErrorThrottleWindow_pkey" PRIMARY KEY ("subject") +); + +-- CreateTable +CREATE TABLE "ClientErrorDedupe" ( + "id" TEXT NOT NULL, + "subject" TEXT NOT NULL, + "errorId" TEXT NOT NULL, + "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP, + + CONSTRAINT "ClientErrorDedupe_pkey" PRIMARY KEY ("id") +); + +-- CreateIndex +CREATE INDEX "ClientErrorThrottleWindow_windowStart_idx" ON "ClientErrorThrottleWindow"("windowStart"); + +-- CreateIndex +CREATE UNIQUE INDEX "ClientErrorDedupe_subject_errorId_key" ON "ClientErrorDedupe"("subject", "errorId"); + +-- CreateIndex +CREATE INDEX "ClientErrorDedupe_createdAt_idx" ON "ClientErrorDedupe"("createdAt"); diff --git a/apps/api/prisma/schema.prisma b/apps/api/prisma/schema.prisma index 2819ad8..060442f 100644 --- a/apps/api/prisma/schema.prisma +++ b/apps/api/prisma/schema.prisma @@ -468,6 +468,25 @@ model AdminUser { templateAuditLogs TemplatePackageAuditLog[] @relation("TemplatePackageAuditActor") } +model ClientErrorThrottleWindow { + subject String @id + windowStart DateTime + count Int + updatedAt DateTime @updatedAt + + @@index([windowStart]) +} + +model ClientErrorDedupe { + id String @id @default(uuid()) + subject String + errorId String + createdAt DateTime @default(now()) + + @@unique([subject, errorId]) + @@index([createdAt]) +} + model TemplatePackage { id String @id @default(uuid()) packageKey String @unique diff --git a/apps/api/src/modules/admin/admin-client-error.service.ts b/apps/api/src/modules/admin/admin-client-error.service.ts index 3218c6c..8e89a61 100644 --- a/apps/api/src/modules/admin/admin-client-error.service.ts +++ b/apps/api/src/modules/admin/admin-client-error.service.ts @@ -1,9 +1,9 @@ -import { HttpException, Injectable } from "@nestjs/common"; +import { Inject, Injectable } from "@nestjs/common"; +import { + CLIENT_ERROR_THROTTLE_STORE, + type ClientErrorThrottleStore, +} from "./client-error-throttle.store.js"; -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 { @@ -22,27 +22,16 @@ export interface ClientErrorReceipt { duplicate: boolean; } -/** - * 后台渲染异常去重与限流。 - * 当前生产为单实例 PM2,因此使用进程内窗口;扩成多实例前需要换成共享存储。 - */ @Injectable() export class AdminClientErrorService { - private readonly recentErrorIds = new Map(); - private readonly windows = new Map(); + constructor( + @Inject(CLIENT_ERROR_THROTTLE_STORE) + private readonly throttle: ClientErrorThrottleStore, + ) {} - 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(); + async record(report: ClientErrorReport): Promise { + const result = await this.throttle.record(report); + if (result.duplicate) return { received: true, duplicate: true }; console.error("admin client error", { errorId: report.errorId, @@ -57,35 +46,4 @@ export class AdminClientErrorService { 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); - } - } } diff --git a/apps/api/src/modules/admin/admin.module.ts b/apps/api/src/modules/admin/admin.module.ts index 7ea1fcd..b256ddc 100644 --- a/apps/api/src/modules/admin/admin.module.ts +++ b/apps/api/src/modules/admin/admin.module.ts @@ -4,6 +4,9 @@ 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 { createClientErrorThrottleStore } from "./client-error-throttle.factory.js"; +import { CLIENT_ERROR_THROTTLE_STORE } from "./client-error-throttle.store.js"; +import { PrismaService } from "../../prisma.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"; @@ -47,6 +50,11 @@ import { AdminTemplatePreviewAssetsService } from "./admin-template-preview-asse AdminTemplatePreviewService, AdminTemplatePreviewAssetsService, TemplateOperationMetricsService, + { + provide: CLIENT_ERROR_THROTTLE_STORE, + useFactory: (prisma: PrismaService) => createClientErrorThrottleStore(prisma), + inject: [PrismaService], + }, AdminClientErrorService, ], }) diff --git a/apps/api/src/modules/admin/client-error-throttle.factory.ts b/apps/api/src/modules/admin/client-error-throttle.factory.ts new file mode 100644 index 0000000..a11f8b8 --- /dev/null +++ b/apps/api/src/modules/admin/client-error-throttle.factory.ts @@ -0,0 +1,20 @@ +import type { PrismaService } from "../../prisma.service.js"; +import { PostgresClientErrorThrottleStore } from "./client-error-throttle.postgres.store.js"; +import { + MemoryClientErrorThrottleStore, + type ClientErrorThrottleStore, +} from "./client-error-throttle.store.js"; + +export function createClientErrorThrottleStore( + prisma: PrismaService, + mode = process.env.CLIENT_ERROR_THROTTLE_STORE ?? "memory", +): ClientErrorThrottleStore { + switch (mode) { + case "memory": + return new MemoryClientErrorThrottleStore(); + case "postgres": + return new PostgresClientErrorThrottleStore(prisma); + default: + throw new Error(`Unsupported CLIENT_ERROR_THROTTLE_STORE: ${mode}`); + } +} diff --git a/apps/api/src/modules/admin/client-error-throttle.postgres.store.ts b/apps/api/src/modules/admin/client-error-throttle.postgres.store.ts new file mode 100644 index 0000000..2a855f5 --- /dev/null +++ b/apps/api/src/modules/admin/client-error-throttle.postgres.store.ts @@ -0,0 +1,94 @@ +import { randomUUID } from "node:crypto"; +import { HttpException } from "@nestjs/common"; +import { Prisma } from "@prisma/client"; +import type { PrismaService } from "../../prisma.service.js"; +import { + CLIENT_ERROR_DEDUPE_TTL_MS, + CLIENT_ERROR_RATE_LIMIT, + CLIENT_ERROR_RATE_WINDOW_MS, + type ClientErrorThrottleReport, + type ClientErrorThrottleResult, + type ClientErrorThrottleStore, +} from "./client-error-throttle.store.js"; + +/** + * 多实例部署使用的共享存储实现。 + * 去重与限流在同一事务中执行:限流拒绝时不会留下已去重标记。 + */ +export class PostgresClientErrorThrottleStore implements ClientErrorThrottleStore { + private lastCleanupAt = 0; + + constructor(private readonly prisma: PrismaService) {} + + async record( + report: ClientErrorThrottleReport, + now = Date.now(), + ): Promise { + const cutoff = new Date(now - CLIENT_ERROR_DEDUPE_TTL_MS); + const windowStart = new Date( + Math.floor(now / CLIENT_ERROR_RATE_WINDOW_MS) * CLIENT_ERROR_RATE_WINDOW_MS, + ); + const recordedAt = new Date(now); + let duplicate = false; + + await this.prisma.$transaction(async (transaction) => { + const inserted = await transaction.$queryRaw>(Prisma.sql` + INSERT INTO "ClientErrorDedupe" ("id", "subject", "errorId", "createdAt") + VALUES (${randomUUID()}, ${report.subject}, ${report.errorId}, ${recordedAt}) + ON CONFLICT ("subject", "errorId") DO UPDATE SET + "createdAt" = EXCLUDED."createdAt" + WHERE "ClientErrorDedupe"."createdAt" < ${cutoff} + RETURNING "id" + `); + if (!inserted.length) { + duplicate = true; + return; + } + + const rows = await transaction.$queryRaw>(Prisma.sql` + INSERT INTO "ClientErrorThrottleWindow" ("subject", "windowStart", "count", "updatedAt") + VALUES (${report.subject}, ${windowStart}, 1, ${recordedAt}) + ON CONFLICT ("subject") DO UPDATE SET + "count" = CASE + WHEN EXCLUDED."windowStart" > "ClientErrorThrottleWindow"."windowStart" + THEN 1 + WHEN EXCLUDED."windowStart" = "ClientErrorThrottleWindow"."windowStart" + THEN LEAST("ClientErrorThrottleWindow"."count" + 1, ${CLIENT_ERROR_RATE_LIMIT + 1}) + ELSE "ClientErrorThrottleWindow"."count" + END, + "windowStart" = GREATEST( + "ClientErrorThrottleWindow"."windowStart", + EXCLUDED."windowStart" + ), + "updatedAt" = EXCLUDED."updatedAt" + RETURNING "count" + `); + if (Number(rows[0]?.count ?? 1) > CLIENT_ERROR_RATE_LIMIT) { + throw new HttpException("客户端错误上报过于频繁,请稍后再试", 429); + } + }); + + await this.cleanupIfNeeded(cutoff, windowStart, now); + return { duplicate }; + } + + private async cleanupIfNeeded(cutoff: Date, windowStart: Date, now: number): Promise { + if (now - this.lastCleanupAt < CLIENT_ERROR_RATE_WINDOW_MS) return; + this.lastCleanupAt = now; + try { + await Promise.all([ + this.prisma.clientErrorDedupe.deleteMany({ where: { createdAt: { lt: cutoff } } }), + this.prisma.clientErrorThrottleWindow.deleteMany({ + where: { + windowStart: { + lt: new Date(windowStart.getTime() - CLIENT_ERROR_RATE_WINDOW_MS), + }, + }, + }), + ]); + } catch (error) { + // 清理失败不能影响诊断上报本身,下一分钟会再次尝试。 + console.warn("[api] client error throttle cleanup failed", error); + } + } +} diff --git a/apps/api/src/modules/admin/client-error-throttle.store.ts b/apps/api/src/modules/admin/client-error-throttle.store.ts new file mode 100644 index 0000000..9d7dc69 --- /dev/null +++ b/apps/api/src/modules/admin/client-error-throttle.store.ts @@ -0,0 +1,74 @@ +import { HttpException } from "@nestjs/common"; + +export const CLIENT_ERROR_RATE_WINDOW_MS = 60_000; +export const CLIENT_ERROR_RATE_LIMIT = 10; +export const CLIENT_ERROR_DEDUPE_TTL_MS = 10 * 60_000; +export const CLIENT_ERROR_DEDUPE_CAPACITY = 500; +export const CLIENT_ERROR_THROTTLE_STORE = Symbol("CLIENT_ERROR_THROTTLE_STORE"); + +export interface ClientErrorThrottleReport { + subject: string; + errorId: string; +} + +export interface ClientErrorThrottleResult { + duplicate: boolean; +} + +export interface ClientErrorThrottleStore { + record(report: ClientErrorThrottleReport, now?: number): Promise; +} + +/** 单实例部署使用的进程内实现;多实例必须切换为共享存储。 */ +export class MemoryClientErrorThrottleStore implements ClientErrorThrottleStore { + private readonly recentErrorIds = new Map(); + private readonly windows = new Map(); + + async record( + report: ClientErrorThrottleReport, + now = Date.now(), + ): Promise { + this.prune(now); + + const dedupeKey = `${report.subject}:${report.errorId}`; + if (this.recentErrorIds.has(dedupeKey)) return { duplicate: true }; + + this.assertWithinRate(report.subject, now); + this.recentErrorIds.set(dedupeKey, now); + this.trimDedupe(); + return { duplicate: false }; + } + + private assertWithinRate(subject: string, now: number): void { + const recent = (this.windows.get(subject) ?? []).filter( + (timestamp) => now - timestamp < CLIENT_ERROR_RATE_WINDOW_MS, + ); + if (recent.length >= CLIENT_ERROR_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 >= CLIENT_ERROR_DEDUPE_TTL_MS) this.recentErrorIds.delete(key); + } + for (const [subject, timestamps] of this.windows) { + const recent = timestamps.filter( + (timestamp) => now - timestamp < CLIENT_ERROR_RATE_WINDOW_MS, + ); + if (recent.length === 0) this.windows.delete(subject); + else this.windows.set(subject, recent); + } + } + + private trimDedupe(): void { + while (this.recentErrorIds.size > CLIENT_ERROR_DEDUPE_CAPACITY) { + const oldest = this.recentErrorIds.keys().next(); + if (oldest.done) return; + this.recentErrorIds.delete(oldest.value); + } + } +} diff --git a/apps/api/test/admin-client-error.service.test.ts b/apps/api/test/admin-client-error.service.test.ts index e41eec7..194abf9 100644 --- a/apps/api/test/admin-client-error.service.test.ts +++ b/apps/api/test/admin-client-error.service.test.ts @@ -2,6 +2,7 @@ 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"; +import { MemoryClientErrorThrottleStore } from "../src/modules/admin/client-error-throttle.store.js"; function report(errorId: string, subject = "admin:user-1") { return { @@ -15,40 +16,42 @@ function report(errorId: string, subject = "admin:user-1") { }; } -test("首次上报记录,相同 errorId 在窗口内按管理员去重", () => { - const service = new AdminClientErrorService(); - assert.deepEqual(service.record(report("admin-error-1")), { +function service() { + return new AdminClientErrorService(new MemoryClientErrorThrottleStore()); +} + +test("首次上报记录,相同 errorId 在窗口内按管理员去重", async () => { + const errors = service(); + assert.deepEqual(await errors.record(report("admin-error-1")), { received: true, duplicate: false, }); - assert.deepEqual(service.record(report("admin-error-1")), { + assert.deepEqual(await errors.record(report("admin-error-1")), { received: true, duplicate: true, }); // 不同管理员使用相同 errorId 时互不影响 - assert.deepEqual(service.record(report("admin-error-1", "admin:user-2")), { + assert.deepEqual(await errors.record(report("admin-error-1", "admin:user-2")), { received: true, duplicate: false, }); }); -test("同一管理员 60 秒内最多接受 10 条不同错误", () => { - const service = new AdminClientErrorService(); +test("同一管理员 60 秒内最多接受 10 条不同错误", async () => { + const errors = service(); for (let index = 0; index < 10; index += 1) { - assert.deepEqual(service.record(report(`admin-rate-${index}`)), { + assert.deepEqual(await errors.record(report(`admin-rate-${index}`)), { received: true, duplicate: false, }); } - try { - service.record(report("admin-rate-overflow")); - assert.fail("应当触发限流"); - } catch (error) { + await assert.rejects(errors.record(report("admin-rate-overflow")), (error) => { assert.ok(error instanceof HttpException); assert.equal(error.getStatus(), 429); - } + return true; + }); // 另一个管理员不受影响 - assert.deepEqual(service.record(report("admin-rate-other", "admin:user-2")), { + assert.deepEqual(await errors.record(report("admin-rate-other", "admin:user-2")), { received: true, duplicate: false, }); diff --git a/apps/api/test/client-error-throttle.factory.test.ts b/apps/api/test/client-error-throttle.factory.test.ts new file mode 100644 index 0000000..e05a7dd --- /dev/null +++ b/apps/api/test/client-error-throttle.factory.test.ts @@ -0,0 +1,24 @@ +import assert from "node:assert/strict"; +import { test } from "node:test"; +import { createClientErrorThrottleStore } from "../src/modules/admin/client-error-throttle.factory.js"; +import { PostgresClientErrorThrottleStore } from "../src/modules/admin/client-error-throttle.postgres.store.js"; +import { MemoryClientErrorThrottleStore } from "../src/modules/admin/client-error-throttle.store.js"; + +const prisma = {} as never; + +test("默认使用进程内存储", () => { + const store = createClientErrorThrottleStore(prisma, "memory"); + assert.ok(store instanceof MemoryClientErrorThrottleStore); +}); + +test("多实例可切换为 Postgres 共享存储", () => { + const store = createClientErrorThrottleStore(prisma, "postgres"); + assert.ok(store instanceof PostgresClientErrorThrottleStore); +}); + +test("未知存储模式在启动时快速失败", () => { + assert.throws( + () => createClientErrorThrottleStore(prisma, "redis"), + /Unsupported CLIENT_ERROR_THROTTLE_STORE/, + ); +}); diff --git a/apps/api/test/http.integration.test.js b/apps/api/test/http.integration.test.js index 7347bab..79ac6c4 100644 --- a/apps/api/test/http.integration.test.js +++ b/apps/api/test/http.integration.test.js @@ -12,6 +12,11 @@ import { createApp } from "../dist/main.js"; import { readIdentity, signIdentity } from "../dist/auth.js"; import { WechatAuthService } from "../dist/wechat-auth.js"; import { AdminMiniAppReleaseService } from "../dist/modules/admin/admin-miniapp-release.service.js"; +import { PostgresClientErrorThrottleStore } from "../dist/modules/admin/client-error-throttle.postgres.store.js"; +import { + CLIENT_ERROR_DEDUPE_TTL_MS, + CLIENT_ERROR_RATE_WINDOW_MS, +} from "../dist/modules/admin/client-error-throttle.store.js"; let app; const prisma = new PrismaClient(); @@ -1928,6 +1933,88 @@ test("admin client error reports are authenticated, validated, and deduplicated" assert.equal(invalid.statusCode, 400); }); +test("postgres client error store deduplicates and rate limits across instances", async () => { + const storeA = new PostgresClientErrorThrottleStore(prisma); + const storeB = new PostgresClientErrorThrottleStore(prisma); + const subjectPrefix = `pg-client-error-${randomUUID()}`; + const dedupeSubject = `${subjectPrefix}-dedupe`; + const concurrentSubject = `${subjectPrefix}-concurrent`; + const rateSubject = `${subjectPrefix}-rate`; + const lateSubject = `${subjectPrefix}-late`; + const now = Date.now(); + try { + assert.deepEqual(await storeA.record({ subject: dedupeSubject, errorId: "same" }, now), { + duplicate: false, + }); + assert.deepEqual(await storeB.record({ subject: dedupeSubject, errorId: "same" }, now), { + duplicate: true, + }); + assert.deepEqual( + await storeB.record( + { subject: dedupeSubject, errorId: "same" }, + now + CLIENT_ERROR_DEDUPE_TTL_MS + 1_000, + ), + { duplicate: false }, + ); + + const concurrent = await Promise.all( + Array.from({ length: 6 }, (_, index) => + (index % 2 === 0 ? storeA : storeB).record( + { subject: concurrentSubject, errorId: "concurrent-same" }, + now, + ), + ), + ); + assert.equal(concurrent.filter((result) => !result.duplicate).length, 1); + + for (let index = 0; index < 10; index += 1) { + const store = index % 2 === 0 ? storeA : storeB; + assert.deepEqual( + await store.record({ subject: rateSubject, errorId: `rate-${index}` }, now), + { duplicate: false }, + ); + } + await assert.rejects( + storeB.record({ subject: rateSubject, errorId: "rate-overflow" }, now), + (error) => error.getStatus?.() === 429, + ); + assert.deepEqual( + await storeA.record( + { subject: rateSubject, errorId: "rate-next-window" }, + now + CLIENT_ERROR_RATE_WINDOW_MS, + ), + { duplicate: false }, + ); + + // 旧窗口的迟到请求不得把窗口指针回拨,否则会额外放行一整窗口。 + await storeA.record( + { subject: lateSubject, errorId: "late-first" }, + now + CLIENT_ERROR_RATE_WINDOW_MS, + ); + await storeB.record({ subject: lateSubject, errorId: "late-old" }, now); + for (let index = 0; index < 9; index += 1) { + assert.deepEqual( + await storeA.record( + { subject: lateSubject, errorId: `late-next-${index}` }, + now + CLIENT_ERROR_RATE_WINDOW_MS, + ), + { duplicate: false }, + ); + } + await assert.rejects( + storeB.record( + { subject: lateSubject, errorId: "late-overflow" }, + now + CLIENT_ERROR_RATE_WINDOW_MS, + ), + (error) => error.getStatus?.() === 429, + ); + } finally { + const subjects = [dedupeSubject, concurrentSubject, rateSubject, lateSubject]; + await prisma.clientErrorDedupe.deleteMany({ where: { subject: { in: subjects } } }); + await prisma.clientErrorThrottleWindow.deleteMany({ where: { subject: { in: subjects } } }); + } +}); + async function assertProtectedRouteBoundary(url, options = {}) { const { method = "GET", payload, forbiddenRole = "customer", headers = {} } = options; const requestOptions = payload === undefined ? { method, headers } : { method, headers, payload }; diff --git a/apps/api/test/template-contract-migration.integration.mjs b/apps/api/test/template-contract-migration.integration.mjs index b736974..8ae862f 100644 --- a/apps/api/test/template-contract-migration.integration.mjs +++ b/apps/api/test/template-contract-migration.integration.mjs @@ -45,7 +45,6 @@ async function main() { .filter((entry) => entry.isDirectory() && entry.name !== targetMigration) .map((entry) => entry.name) .sort(); - assert.equal(migrationDirs.at(-1), "20261019100000_remove_brand_profile_defaults"); await admin.$executeRawUnsafe(`CREATE SCHEMA "${schema}"`); createdSchema = true; diff --git a/deploy/ecosystem.config.cjs b/deploy/ecosystem.config.cjs index 97206ea..d67e32a 100644 --- a/deploy/ecosystem.config.cjs +++ b/deploy/ecosystem.config.cjs @@ -6,6 +6,8 @@ module.exports = { apps: [ { name: "personal-brand-api", + instances: 1, + exec_mode: "fork", cwd: path.join(root, "current/apps/api"), script: "dist/main.js", interpreter: process.execPath, diff --git a/deploy/ecosystem.config.test.mjs b/deploy/ecosystem.config.test.mjs new file mode 100644 index 0000000..af093d7 --- /dev/null +++ b/deploy/ecosystem.config.test.mjs @@ -0,0 +1,13 @@ +import assert from "node:assert/strict"; +import test from "node:test"; +import { createRequire } from "node:module"; + +process.env.DEPLOY_ROOT = "/srv/personal-brand"; +const require = createRequire(import.meta.url); +const config = require("./ecosystem.config.cjs"); + +test("异常上报使用进程内存储时 PM2 必须保持单实例", () => { + assert.equal(config.apps.length, 1); + assert.equal(config.apps[0].instances, 1); + assert.equal(config.apps[0].exec_mode, "fork"); +}); diff --git a/docs/adr/0035-admin-client-error-throttling.md b/docs/adr/0035-admin-client-error-throttling.md index 66fc4c3..885c7ee 100644 --- a/docs/adr/0035-admin-client-error-throttling.md +++ b/docs/adr/0035-admin-client-error-throttling.md @@ -1,4 +1,4 @@ -# 0035 Admin 客户端异常上报的进程内去重与限流 +# 0035 Admin 客户端异常上报的去重与限流 - 状态:已采纳 - 日期:2026-10-23 @@ -10,34 +10,41 @@ Admin 渲染异常上报 `POST /admin/client-errors` 需要防止两类问题: - 同一次渲染错误在多个组件或重试中重复上报,制造日志噪音。 - 单账号在错误循环中高频上报,拖垮日志与请求处理。 -当前生产为单实例 PM2(`deploy/ecosystem.config.cjs`),没有共享缓存或消息队列。引入 Redis 会增加部署依赖,而当前流量与实例数量都不需要。 +生产 PM2 当前保持单实例(`deploy/ecosystem.config.cjs`),因此默认不需要额外基础设施。但当 API 扩展为多实例时,进程内窗口会让实际限流值按实例数放大,跨实例去重也会失效。 ## Decision -1. 使用进程内 `Map` 完成两件事: - - 去重:`subject + errorId` 在 10 分钟内只记录一次。 - - 限流:同一 `subject` 每分钟最多 10 次,超出返回 429。 -2. 去重表最多 500 条,按插入顺序淘汰最旧记录;限流窗口每分钟清理。 -3. 该状态不持久化,进程重启后清零。 -4. 只有通过 `requireBrand` 认证的管理员才能上报,避免匿名刷量。 +1. 提供两种 `ClientErrorThrottleStore` 实现,由 `CLIENT_ERROR_THROTTLE_STORE` 选择: + - `memory`(默认):适合当前单实例 PM2,使用进程内 `Map`。 + - `postgres`:适合多实例,使用数据库共享去重与限流状态。 +2. 两种实现使用一致语义: + - 去重:`subject + errorId` 在 10 分钟内只接受一次。 + - 限流:同一 `subject` 每分钟最多接受 10 条不同错误,超出返回 429。 +3. Postgres 实现使用两张表: + - `ClientErrorDedupe` 通过 `(subject, errorId)` 唯一约束去重,并用条件 UPSERT 刷新过期记录。 + - `ClientErrorThrottleWindow` 按 `subject` 单行保存当前窗口,使用原子 UPSERT 累加计数。 + - 去重与限流在同一事务内完成,限流拒绝会回滚去重标记,避免客户端重试同一 `errorId` 时被误判为已记录。 +4. 过期去重记录与旧限流窗口每分钟最多清理一次,清理失败只记录警告,不影响诊断上报。 +5. 只有通过 `requireBrand` 认证的管理员才能上报,避免匿名刷量。未知的 `CLIENT_ERROR_THROTTLE_STORE` 值必须在启动时失败。 ## Alternatives -- 直接引入 Redis:增加部署与可用性依赖,当前单实例没有收益,推迟。 +- 只保留进程内实现:多实例下计数与去重不准确,拒绝作为唯一方案。 +- 直接引入 Redis:增加部署与可用性依赖;当已经有 Postgres 时,数据库方案成本更低。 - 不做限流:错误循环会持续写日志,并放大客户端重试,拒绝。 -- 记录到数据库:异常上报是诊断辅助数据,写入数据库会让故障时的数据库压力更大,拒绝。 +- 把错误详情写入数据库:异常上报是诊断辅助数据,故障时不应继续给数据库增加业务写入压力;数据库只保存短期限流状态。 ## Consequences -- 单实例下行为确定,无需额外基础设施。 -- 多实例部署时每个实例各自计数,实际限流值是 `实例数 × 10/分钟`,去重也只在本实例生效。 -- 进程重启会丢失去重窗口,可能重复记录少量错误。 +- 默认 `memory` 模式保持现有单实例部署的零额外依赖和低延迟。 +- 多实例部署必须显式设置 `CLIENT_ERROR_THROTTLE_STORE=postgres`;只把 PM2 调成 cluster 模式而不切换存储,会重新引入按实例放大的问题。 +- Postgres 模式每个接受的上报会增加少量事务写入,但只有已被放行的错误才会进入日志记录路径。 +- 进程重启会清空 `memory` 模式的状态;`postgres` 模式在重启后仍能保持窗口。 +- `memory` 模式使用滑动窗口;`postgres` 模式按自然分钟切分,边界附近可能出现短时双倍突发。这是诊断上报可接受的取舍。 ## Migration plan -1. 当前保持进程内实现,代码注释已说明单实例前提。 -2. 出现以下任一条件时迁移到共享存储(Redis 或数据库): - - API 扩展到多实例; - - 单账号错误上报量在正常故障场景下超过 10 次/分钟; - - 需要跨实例聚合错误统计。 -3. 迁移时保留当前接口与响应形状,仅替换存储实现,并补充并发与过期测试。 +1. 当前单实例 PM2 继续使用默认 `memory` 模式。 +2. 扩展 API 实例数前,先执行 `20261023130000_add_client_error_throttle` 迁移,并设置 `CLIENT_ERROR_THROTTLE_STORE=postgres`。 +3. 验证多实例下同一 `errorId` 只记录一次,且单账号跨实例超过 10 条/分钟返回 429。 +4. 如需 Redis 或消息队列,保留 `ClientErrorThrottleStore` 接口与响应形状,仅替换工厂实现并补充并发与过期测试。 diff --git a/docs/deployment.md b/docs/deployment.md index 8d67a5c..75b7225 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -88,6 +88,8 @@ SEED_ADMIN_PASSWORD= `DATABASE_URL` 使用最小权限数据库账号。`SESSION_SECRET` 不能复用示例值或开发值。`DEFAULT_BRAND_ID` 供未携带 `brandSlug` 的公共请求使用,缺失时 API 返回 503,不会回退到硬编码品牌。 +`CLIENT_ERROR_THROTTLE_STORE` 默认为 `memory`,与当前 PM2 单实例模式匹配。扩展到多实例前必须先执行数据库迁移并改为 `postgres`,否则每个实例会各自限流与去重,实际阈值会被实例数量放大。 + `CORS_ORIGINS` 默认为空并关闭跨域访问;只有 Admin 或预览应用从其他 origin 调用 API 时,才配置逗号分隔的 HTTPS origin allow-list。 本次部署会为管理员账号引入 `tokenVersion`。既有 admin token 会因缺少当前版本号而失效,管理员需要重新登录;之后修改密码会立即撤销同一账号的旧 token。媒体上传使用 S3 兼容对象存储和预签名直传,生产环境必须配置独立的 `OBJECT_STORAGE_PUBLIC_URL`、最小权限访问密钥和专用 bucket。微信相关变量只在启用对应能力时配置,同样不能提交真实凭据。