feat: implement monitoring and security features in Node.js backend, including request tracing, metrics monitoring, and API rate limiting with Redis support

Author: erweixin

backend-nodejs/README.md

@@ -13,6 +13,7 @@
 - [项目结构](#-项目结构)
 - [架构设计](#-架构设计)
 - [开发指南](#-开发指南)
+- [监控和安全](#-监控和安全)
 - [与 Go 后端的关系](#-与-go-后端的关系)
 
 ---
@@ -515,6 +516,68 @@ pnpm test:watch
 
 ---
 
+## 📊 监控和安全
+
+### 功能概览
+
+系统已集成以下监控和安全功能：
+
+- ✅ **请求追踪**：自动生成 TraceID/RequestID，支持分布式追踪
+- ✅ **Metrics 监控**：Prometheus 格式指标，支持 QPS、延迟、错误率监控
+- ✅ **API 限流**：基于 Redis 的限流保护，防止恶意请求
+
+### 快速使用
+
+#### 1. 请求追踪（自动启用）
+
+```bash
+# 发送请求，自动获得追踪信息
+curl -v http://localhost:8081/api/tasks
+
+# 响应头包含：
+# X-Trace-Id: 550e8400-e29b-41d4-a716-446655440000
+# X-Request-Id: 660e8400-e29b-41d4-a716-446655440001
+```
+
+#### 2. Metrics 监控
+
+```bash
+# 访问 Metrics 端点
+curl http://localhost:8081/metrics
+
+# 集成 Prometheus（prometheus.yml）
+scrape_configs:
+  - job_name: 'backend-nodejs'
+    static_configs:
+      - targets: ['localhost:8081']
+```
+
+#### 3. API 限流
+
+```bash
+# 测试登录限流（每分钟最多 5 次）
+for i in {1..6}; do
+  curl -X POST http://localhost:8081/api/auth/login \
+    -H "Content-Type: application/json" \
+    -d '{"email":"test@example.com","password":"wrong"}'
+done
+# 第 6 次会返回 429 Too Many Requests
+```
+
+### 详细文档
+
+- 📖 [完整使用文档](docs/MONITORING_AND_SECURITY.md) - 详细的使用说明和配置
+- 🚀 [快速参考](docs/QUICK_START_MONITORING.md) - 快速上手指南
+- 💡 [使用示例](docs/USAGE_EXAMPLES.md) - 实际使用场景和代码示例
+- 🧪 [测试脚本](scripts/test-monitoring.sh) - 自动化测试脚本
+
+### 已应用的限流策略
+
+- **登录接口**：每分钟最多 5 次（防止暴力破解）
+- **注册接口**：每小时最多 3 次（防止批量注册）
+
+---
+
 ## 🔗 与 Go 后端的关系
 
 ### 共享资源

backend-nodejs/cmd/server/main.ts

@@ -91,7 +91,7 @@ async function main() {
     task: container.taskHandlerDeps,
     user: container.userHandlerDeps,
     auth: container.authHandlerDeps,
-  }, container.authMiddleware);
+  }, container.authMiddleware, redis);
 
   // 9. 启动服务器
   const address = `http://${config.server.host}:${config.server.port}`;

backend-nodejs/domains/auth/http/router.ts

@@ -4,6 +4,7 @@
  */
 
 import type { FastifyInstance } from 'fastify';
+import type { RedisClientType } from 'redis';
 import type { HandlerDependencies } from '../handlers/dependencies.js';
 import type { RegisterRequest, LoginRequest, RefreshTokenRequest } from './dto/auth.js';
 import {
@@ -14,18 +15,32 @@ import {
 import { registerHandler } from '../handlers/register.handler.js';
 import { loginHandler } from '../handlers/login.handler.js';
 import { refreshTokenHandler } from '../handlers/refresh_token.handler.js';
+import {
+  createLoginRateLimitMiddleware,
+  createRegisterRateLimitMiddleware,
+} from '../../../infrastructure/middleware/ratelimit.js';
 
 /**
  * 注册 Auth 路由
+ * 
+ * @param app Fastify 实例
+ * @param deps Handler 依赖
+ * @param redis Redis 客户端（可选，用于限流）
  */
 export function registerAuthRoutes(
   app: FastifyInstance,
-  deps: HandlerDependencies
+  deps: HandlerDependencies,
+  redis: RedisClientType | null = null
 ): void {
-  // POST /api/auth/register - 用户注册
+  // 创建限流中间件
+  const loginRateLimit = createLoginRateLimitMiddleware(redis);
+  const registerRateLimit = createRegisterRateLimitMiddleware(redis);
+
+  // POST /api/auth/register - 用户注册（限流：每小时最多 3 次）
   app.post<{ Body: RegisterRequest }>(
     '/api/auth/register',
     {
+      preHandler: [registerRateLimit],
       schema: {
         body: RegisterRequestSchema,
       },
@@ -35,10 +50,11 @@ export function registerAuthRoutes(
     }
   );
 
-  // POST /api/auth/login - 用户登录
+  // POST /api/auth/login - 用户登录（限流：每分钟最多 5 次）
   app.post<{ Body: LoginRequest }>(
     '/api/auth/login',
     {
+      preHandler: [loginRateLimit],
       schema: {
         body: LoginRequestSchema,
       },
@@ -48,7 +64,7 @@ export function registerAuthRoutes(
     }
   );
 
-  // POST /api/auth/refresh - 刷新 Token
+  // POST /api/auth/refresh - 刷新 Token（不需要限流，因为需要有效的 refresh token）
   app.post<{ Body: RefreshTokenRequest }>(
     '/api/auth/refresh',
     {

backend-nodejs/infrastructure/bootstrap/server.ts

@@ -12,6 +12,9 @@ import type { RedisClientType } from 'redis';
 import { checkHealth } from '../monitoring/health/health.js';
 import type { AuthMiddleware } from '../middleware/types.js';
 import { isDomainError } from '../../shared/errors/errors.js';
+import { tracingMiddleware } from '../middleware/tracing.js';
+import { metricsMiddleware, metricsResponseHook } from '../middleware/metrics.js';
+import { register } from '../monitoring/metrics/metrics.js';
 
 /**
  * 创建 Fastify 服务器
@@ -40,11 +43,20 @@ export function createServer(config: Config): FastifyInstance {
  * 注册全局中间件
  */
 export async function registerMiddleware(fastify: FastifyInstance): Promise<void> {
+  // 请求追踪（必须在最前面，确保所有请求都有 TraceID/RequestID）
+  fastify.addHook('onRequest', tracingMiddleware);
+
   // CORS
   await fastify.register(cors, {
     origin: true,
   });
 
+  // Metrics 中间件（记录请求开始时间）
+  fastify.addHook('onRequest', metricsMiddleware);
+  
+  // Metrics 响应 Hook（记录请求指标）
+  fastify.addHook('onResponse', metricsResponseHook);
+
   // Security headers (手动实现，因为 @fastify/helmet 不支持 Fastify 5)
   fastify.addHook('onRequest', async (_request: FastifyRequest, reply: FastifyReply) => {
     reply.header('X-Content-Type-Options', 'nosniff');
@@ -111,6 +123,12 @@ export function registerRoutes(
     return reply.code(statusCode).send(health);
   });
 
+  // Prometheus Metrics 端点
+  fastify.get('/metrics', async (_request: unknown, reply) => {
+    reply.type('text/plain');
+    return register.metrics();
+  });
+
   // 根路径
   fastify.get('/', async (_request: unknown, reply) => {
     return reply.send({
@@ -128,7 +146,8 @@ export function registerRoutes(
 export async function registerDomainRoutes(
   fastify: FastifyInstance,
   handlerDeps: Record<string, unknown>,
-  authMiddleware: AuthMiddleware
+  authMiddleware: AuthMiddleware,
+  redis: RedisClientType | null = null
 ): Promise<void> {
   // 动态导入并注册 Task 路由
   if (handlerDeps.task) {
@@ -153,7 +172,11 @@ export async function registerDomainRoutes(
   // 动态导入并注册 Auth 路由（不需要认证中间件）
   if (handlerDeps.auth) {
     const authRouter = await import('../../domains/auth/http/router.js');
-    authRouter.registerAuthRoutes(fastify, handlerDeps.auth as Parameters<typeof authRouter.registerAuthRoutes>[1]);
+    authRouter.registerAuthRoutes(
+      fastify,
+      handlerDeps.auth as Parameters<typeof authRouter.registerAuthRoutes>[1],
+      redis
+    );
   }
 }
 

backend-nodejs/infrastructure/middleware/auth.ts

@@ -7,10 +7,13 @@ import type { FastifyRequest, FastifyReply } from 'fastify';
 import type { JWTService } from '../../domains/auth/service/jwt_service.js';
 
 // 扩展 FastifyRequest 类型，添加 user_id 和 email
+// 注意：traceId 和 requestId 在 tracing.ts 中定义
 declare module 'fastify' {
   interface FastifyRequest {
     userId?: string;
     email?: string;
+    traceId?: string;
+    requestId?: string;
   }
 }
 

backend-nodejs/infrastructure/middleware/metrics.ts

@@ -0,0 +1,57 @@
+/**
+ * Metrics 中间件
+ * 记录 HTTP 请求的指标（QPS、延迟、错误率）
+ */
+
+import type { FastifyRequest, FastifyReply } from 'fastify';
+import { httpRequestCounter, httpRequestDuration } from '../monitoring/metrics/metrics.js';
+
+/**
+ * Metrics 中间件
+ * 记录每个请求的指标
+ * 使用 Fastify 的 onRequest hook 记录开始时间，onResponse hook 记录指标
+ */
+export async function metricsMiddleware(
+  request: FastifyRequest,
+  _reply: FastifyReply
+): Promise<void> {
+  // 在请求对象上存储开始时间
+  (request as any).metricsStartTime = Date.now();
+}
+
+/**
+ * Metrics 响应 Hook
+ * 在响应发送后记录指标
+ */
+export async function metricsResponseHook(
+  request: FastifyRequest,
+  reply: FastifyReply
+): Promise<void> {
+  const startTime = (request as any).metricsStartTime;
+  if (!startTime) {
+    return; // 如果没有开始时间，跳过
+  }
+
+  const duration = (Date.now() - startTime) / 1000; // 转换为秒
+  const method = request.method;
+  // 获取路由路径（如果没有 routerPath，使用 URL 路径）
+  const route = (request as any).routerPath || request.url.split('?')[0]; // 移除查询参数
+  const statusCode = reply.statusCode;
+
+  // 记录请求计数
+  httpRequestCounter.inc({
+    method,
+    route,
+    status: statusCode.toString(),
+  });
+
+  // 记录请求延迟
+  httpRequestDuration.observe(
+    {
+      method,
+      route,
+    },
+    duration
+  );
+}
+