feat: 支持多实例客户端异常限流

This commit is contained in:
que01 committed 2026-10-23 12:57:06 +08:00
1 parent 4cd3749806
commit 2fe108d66a
18 files changed
+432 -90

No files matched your search

@@ -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"
}
+2
View File
@@ -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
+2
View File
@@ -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
@@ -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");
+19
View File
@@ -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
@@ -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<string, number>();
private readonly windows = new Map<string, number[]>();
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<ClientErrorReceipt> {
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);
}
}
}
@@ -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,
],
})
@@ -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}`);
}
}
@@ -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<ClientErrorThrottleResult> {
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<Array<{ id: string }>>(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<Array<{ count: number }>>(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<void> {
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);
}
}
}
@@ -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<ClientErrorThrottleResult>;
}
/** 单实例部署使用的进程内实现;多实例必须切换为共享存储。 */
export class MemoryClientErrorThrottleStore implements ClientErrorThrottleStore {
private readonly recentErrorIds = new Map<string, number>();
private readonly windows = new Map<string, number[]>();
async record(
report: ClientErrorThrottleReport,
now = Date.now(),
): Promise<ClientErrorThrottleResult> {
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);
}
}
}
@@ -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,
});
@@ -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/,
);
});
+87
View File
@@ -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 };
@@ -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;
+2
View File
@@ -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,
+13
View File
@@ -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");
});
+26 -19
View File
@@ -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` 接口与响应形状,仅替换工厂实现并补充并发与过期测试。
+2
View File
@@ -88,6 +88,8 @@ SEED_ADMIN_PASSWORD=<first-boot-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。微信相关变量只在启用对应能力时配置,同样不能提交真实凭据。