前言

企业智能知识库系统是一个由 9 个微服务组成的分布式系统。

服务间通信如果全部使用同步 HTTP 调用(Feign),会导致紧耦合、级联故障、用户体验下降 —— 比如用户提交文档审核,如果同步等待 ES 索引写入、RAG 向量构建、图谱更新、通知持久化、WebSocket 推送全部完成才返回,响应时间将以秒甚至十秒计,这在生产环境是不可接受的。

本系统采用 事件驱动架构(Event-Driven Architecture),以 RabbitMQ 为消息中枢,通过 6 个 TopicExchange + 11 个队列 + 15 条消息路由 实现了 6 大事件流:审核通知、操作日志、统计计数、文件转码、RAG 向量索引重建、KAG 知识图谱构建。每条事件流都是异步的 —— 生产者只管发消息,消费者各自消费、互不感知。

同时,系统通过 InstanceIdentifier 实现了多开发者本地环境的 MQ 资源隔离,让同一台 RabbitMQ 上跑的多套开发实例互不干扰。对于必须同步调用的场景(如 ES 关键词索引),则通过 Feign 声明式 HTTP 客户端完成,并通过 FeignInterceptorConfig 统一注入内部调用标识头。

完成这套事件驱动架构的关键组件有 7 个:InstanceIdentifier 实例隔离器、Jackson2JsonMessageConverter 消息序列化器、DefaultClassMapper 类型映射、RabbitTemplate 消息模板、@RabbitListener 消费者、CorrelationData 发布确认、x-dead-letter-exchange 死信队列。以下逐层展开。

1. 先结论:一条事件消息从产生到消费走了什么链路

以用户提交文档审核为例,完整的事件驱动链路如下:

用户在 CreateDocumentPage 点击"提交审核"
  → POST /documents (kb-document:8082) 写入 kb_document 表
  → DocumentReviewServiceImpl.submitForReview()
       ├── 创建 kb_document_review 审核记录
       ├── 更新文档状态 status → 1 (审核中)
       ├── 【异步】CompletableFuture.runAsync() {
       │     ├── Feign: kb-search → ES kb_document 索引同步
       │     ├── Feign: kb-ai     → RAG 向量索引重建
       │     └── Feign: kb-ai     → KAG 知识图谱构建
       │   }
       └── 【同步】构建 ReviewEventDTO {
             eventType: "SUBMITTED",
             documentId: 123,
             authorId: 1001,
             ...
           }
           → rabbitTemplate.convertAndSend(
               "kb.notification.exchange",
               "notification.review.{instanceId}.submitted",
               event,
               correlationData  ← 携带发布确认ID
             )
  → RabbitMQ Broker 根据 routingKey 匹配绑定
       └── 路由到队列 kb.notification.review.queue.{instanceId}
  → kb-foundation 的 ReviewNotificationListener
       ├── @RabbitListener(queues = "#{@reviewNotificationQueue.name}")
       └── handleReviewEvent(event)
             ├── eventType = "SUBMITTED"
             │     ├── Feign: kb-user-auth → 查询 ROLE_REVIEWER 用户ID列表
             │     │     └── 找不到 REVIEWER → 降级查 ADMIN → 再降级 SUPER_ADMIN
             │     └── for each reviewerId:
             │           ├── 持久化到 kb_notification 表 (JDBC)
             │           └── WebSocket convertAndSendToUser(reviewerId, payload)
             └── 完成后 ack 确认 → RabbitMQ 删除消息

这条链路涉及 4 个微服务(kb-document → RabbitMQ → kb-foundation → kb-user-auth)、1 次 MQ 异步发送、3 次 Feign 异步调用、1 次 Feign 同步查询。

从用户点击到审核员收到 WebSocket 实时通知,端到端 99% 的工作都是异步的。


2. 消息基础设施总览

2.1 交换机、队列、绑定全景

整个系统共有 7 个交换机、11 个队列、15 条绑定,分布在 6 个模块的 RabbitMQ 配置类中:

模块交换机类型队列数绑定数DLQ
kb-documentkb.notification.exchangeTopicExchange11无
kb-foundationkb.notification.exchangeTopicExchange22无
kb-foundationkb.config.exchangeDirectExchange11无
kb-foundationkb.operationlog.exchangeTopicExchange11无
kb-filetranscode.exchangeDirectExchange11无
kb-airag.reindex.exchangeTopicExchange13有
kb-aikag.graph.exchangeTopicExchange13有
kb-statisticskb.statistics.exchangeTopicExchange33无

注意:kb.notification.exchange\_ 在 kb-document 和 kb-foundation 中各声明一次,这是设计上的有意冗余 —— 确保生产者和消费者都能独立启动,不依赖对方的启动顺序。Spring AMQP 的 \_TopicExchange(..., true, false)\_ 声明是幂等的,重复声明不会报错。\_

2.2 架构全景图

图片.png

2.3 6 大事件流速览

#事件流交换消息 DTO生产者消费者消费结果
1审核通知kb.notification.exchangeReviewEventDTODocumentReviewServiceImplReviewNotificationListener持久化通知 + WebSocket 推送
2操作日志kb.operationlog.exchangeOperationLogEventDTOOperationLogAspectOperationLogMQListener写入 kb\_operation\_log
3浏览统计kb.statistics.exchangeStatisticsEventDTOStatisticsEventPublisherStatisticsMQListenerkb\_view\_history + Redis 计数
4点赞统计kb.statistics.exchangeStatisticsEventDTOStatisticsEventPublisherStatisticsMQListenerRedis 计数
5评论统计kb.statistics.exchangeStatisticsEventDTOStatisticsEventPublisherStatisticsMQListenerRedis 计数
6文件转码transcode.exchangeTranscodeMessageFileServiceImplTranscodeConsumerFFmpeg HLS 转码
7RAG 索引rag.reindex.exchangeReindexMessageReindexServiceImplReindexConsumer文档分块→嵌入→向量索引
8KAG 图谱kag.graph.exchangeKAGReindexMessageGraphBuildServiceImplKAGReindexConsumerNeo4j 知识图谱构建

3. InstanceIdentifier:多开发者环境的 MQ 资源隔离

3.1 为什么需要实例隔离

微服务开发环境下,多位开发者各自在本地启动完整的服务集群(kb-document、kb-foundation、kb-search 等),但它们连接的是同一台开发 RabbitMQ 服务器。如果没有隔离措施:

  • 开发者 A 提交了一条文档审核 → 消息被开发者 B 的 foundation 服务消费
  • 开发者 B 的数据库中根本没有这条文档 → 处理失败,消息丢失
  • 多人同时触发全量 RAG 重建 → 服务器 OOM

3.2 三级取值策略

// kb-common/.../config/InstanceIdentifier.java

@Component
public class InstanceIdentifier implements InitializingBean {

    @Value("${app.instance.id:}")
    private String configuredId;         // 级别 1:显式配置

    @Getter
    private String id;                  // 最终标识

    @Override
    public void afterPropertiesSet() {
        this.id = resolve();
        log.info("当前实例标识(instanceId):{}", this.id);
    }

    private String resolve() {
        // 1. 显式配置(最高优先级)
        if (configuredId != null && !configuredId.trim().isEmpty()) {
            return sanitize(configuredId.trim());
        }

        // 2. 本机 hostname
        try {
            String hostname = InetAddress.getLocalHost().getHostName();
            if (hostname != null && !hostname.isBlank()) {
                int dotIndex = hostname.indexOf('.');
                if (dotIndex > 0) hostname = hostname.substring(0, dotIndex);
                return sanitize(hostname);
            }
        } catch (Exception e) {
            log.warn("获取本机 hostname 失败:{}", e.getMessage());
        }

        // 3. 随机 UUID 兜底
        return "local-" + UUID.randomUUID().toString().substring(0, 8);
    }

    private String sanitize(String raw) {
        return raw.replaceAll("[^a-zA-Z0-9._-]", "-");
    }
}
优先级来源示例值适用场景
1app.instance.id 配置项zhangsan开发者显式指定自己的标识
2本机 hostnameMacBook-Pro自动检测,无需配
3随机 UUID 前 8 位local-a3f8b2c1所有方式都失败时兜底

sanitize() 方法将 hostname 中的非法字符替换为 -,确保标识只包含 [a-zA-Z0-9._-],符合 RabbitMQ 队列名和路由键的字符要求。

3.3 隔离机制

每一条队列名和路由键都嵌入了 instanceId:

队列名:    kb.notification.review.queue.{instanceId}
路由键:    notification.review.{instanceId}.submitted
绑定模式:  notification.review.{instanceId}.*

图片.png

\_关键点:交换机全局共享,队列与路由键实例隔离。同一 TopicExchange 下,路由键 *.MacBook-Pro-A.*\_ 只匹配队列 *.queue.MacBook-Pro-A\_,不同开发者的消息天然隔离。\_


4. 消息序列化与可靠投递

4.1 序列化链路

图片.png

Spring Boot 默认使用 SimpleMessageConverter(Java 原生序列化),这会导致两个问题:

  1. 消息不可读 — RabbitMQ 管理界面看到的是二进制乱码
  2. 跨服务兼容性差 — 必须共享完全一致的类定义

本系统全部覆盖为 Jackson2JsonMessageConverter,配合 DefaultClassMapper 和 JavaTimeModule。

4.2 统一的 MessageConverter 配置

// kb-document/.../config/RabbitMQConfig.java(其他模块同理)

@Bean
public Jackson2JsonMessageConverter jackson2JsonMessageConverter() {
    ObjectMapper objectMapper = new ObjectMapper();
    // 注册 JavaTimeModule,支持 LocalDateTime 序列化
    objectMapper.registerModule(new JavaTimeModule());

    Jackson2JsonMessageConverter converter = new Jackson2JsonMessageConverter(objectMapper);

    // DefaultClassMapper:在消息头中添加 __TypeId__,
    // 消费者据此反序列化为正确的 DTO 类型
    DefaultClassMapper classMapper = new DefaultClassMapper();
    classMapper.setTrustedPackages(
            "com.knowledge.base.common.event",   // 共享 DTO
            "com.knowledge.base.document.dto",   // 模块私有 DTO
            "java.util",
            "java.lang"
    );
    converter.setClassMapper(classMapper);
    return converter;
}
配置项作用问题(如果没有)
Jackson2JsonMessageConverterJSON 格式序列化二进制 Java 序列化,消息不可读
JavaTimeModuleLocalDateTime 不序列化成数组timestamp 字段反序列化报错
DefaultClassMapper + __TypeId__消费者识别目标类型ClassNotFoundException 或类型转换异常
setTrustedPackages()安全白名单,防止反序列化攻击任意类反序列化漏洞

4.3 发布确认与退回回调

// kb-document/.../config/RabbitMQConfig.java

@Bean
public RabbitTemplate rabbitTemplate(ConnectionFactory connectionFactory,
                                      Jackson2JsonMessageConverter messageConverter) {
    RabbitTemplate rabbitTemplate = new RabbitTemplate(connectionFactory);
    rabbitTemplate.setMessageConverter(messageConverter);

    // 发布确认回调:消息是否到达交换机
    rabbitTemplate.setConfirmCallback((correlationData, ack, cause) -> {
        if (!ack && correlationData != null) {
            log.error("消息发送到交换机失败:id={}, cause={}", correlationData.getId(),
                    cause != null ? cause : "交换机不存在或不可达");
        }
    });

    // Mandatory 模式 + 退回回调:消息是否路由到队列
    rabbitTemplate.setMandatory(true);
    rabbitTemplate.setReturnsCallback(returned -> {
        log.error("消息未路由到任何队列:exchange={}, routingKey={}, replyCode={}, replyText={}",
                returned.getExchange(), returned.getRoutingKey(),
                returned.getReplyCode(), returned.getReplyText());
    });

    return rabbitTemplate;
}

设计决策:confirmCallback\_ 和 \_returnsCallback\_ 采用 "log-and-forget" 策略,记录错误日志后不重试。原因是:① 在审核/统计等场景下,消息丢失的影响可控(可人工补发或定时补偿);② 避免 RabbitTemplate 层面无限重试导致线程阻塞或 OOM。后续版本可引入本地消息表 + 定时任务实现最终一致性的可靠投递。\_

4.4 OperationLogAspect 的 send() 用法

OperationLogAspect 不走 convertAndSend(),而是直接调用 rabbitTemplate.send() 并手动构建 Message 对象:

// kb-common/.../aspect/OperationLogAspect.java

private void publishEvent(OperationLogEventDTO event) {
    try {
        String json = JSON.toJSONString(event);               // fastjson2
        byte[] body = json.getBytes(StandardCharsets.UTF_8);
        String routingKey = "operationlog." + instanceIdentifier.getId() + ".record";
        rabbitTemplate.send(OPERATION_LOG_EXCHANGE, routingKey,
                new Message(body, new MessageProperties() {{
                    setContentType("application/json");
                    setHeader("__TypeId__",
                            "com.knowledge.base.common.event.OperationLogEventDTO");
                }}));
    } catch (Exception e) {
        log.error("发布操作日志事件失败:module={}, operation={}, error={}",
                event.getModule(), event.getOperationType(), e.getMessage());
    }
}

设计原因:OperationLogAspect\_ 位于 kb-common\_ 模块,该模块被所有微服务依赖。如果声明 Jackson2JsonMessageConverter\_ Bean,可能与各服务自己的 Converter Bean 冲突。使用 \_send()\_ + fastjson2 手动序列化,不依赖 Spring 注入的 Converter,彻底避免 Bean 覆盖问题。\_


5. 审核通知事件流(跨服务)

5.1 业务流程

审核通知是系统中最核心的事件流,涉及 kb-document(发布)和 kb-foundation(消费),通过 RabbitMQ 解耦审核逻辑与通知推送。

5.2 ReviewEventDTO 事件体

// kb-common/.../event/ReviewEventDTO.java

@Data @Builder @NoArgsConstructor @AllArgsConstructor
public class ReviewEventDTO implements Serializable {
    private static final long serialVersionUID = 1L;

    private String eventType;        // SUBMITTED / APPROVED / REJECTED
    private Long documentId;
    private String documentTitle;
    private Long authorId;           // 文档作者ID
    private String authorName;       // 文档作者名(冗余,减少 Feign 调用)
    private Long reviewerId;         // 审核员ID
    private String reviewerName;     // 审核员名
    private Integer reviewRound;     // 审核轮次
    private Integer reviewLevel;     // 审核级别(预留多级审核扩展)
    private String reviewComment;    // 审核意见(驳回时必填)
    private LocalDateTime timestamp;
}

5.3 生产者:DocumentReviewServiceImpl

// kb-document/.../service/impl/DocumentReviewServiceImpl.java

private void publishReviewEvent(String eventType, Document document, ...) {
    ReviewEventDTO event = ReviewEventDTO.builder()
            .eventType(eventType)
            .documentId(document.getId())
            .documentTitle(document.getTitle())
            .authorId(document.getAuthorId())
            .authorName(document.getAuthorName())
            .reviewerId(reviewerId)
            .reviewerName(reviewerName)
            .reviewRound(reviewRound)
            .reviewLevel(1)
            .reviewComment(reviewComment)
            .timestamp(LocalDateTime.now())
            .build();

    String routingKey = "notification.review." + instanceIdentifier.getId() + "." + eventType.toLowerCase();
    CorrelationData correlationData = new CorrelationData(UUID.randomUUID().toString());

    rabbitTemplate.convertAndSend(
            REVIEW_EXCHANGE,     // "kb.notification.exchange"
            routingKey,
            event,
            correlationData      // 发布确认追踪
    );
}

生产者负责 3 种事件 的发布:

事件类型触发时机通知接收人路由键后缀
SUBMITTED用户提交文档审核审核员(降级:管理员→超级管理员).submitted
APPROVED审核员通过审核文档作者.approved
REJECTED审核员驳回审核文档作者.rejected

5.4 消费者:ReviewNotificationListener

// kb-foundation/.../mq/ReviewNotificationListener.java

@RabbitListener(queues = "#{@reviewNotificationQueue.name}")
public void handleReviewEvent(ReviewEventDTO event) {
    if (event == null || event.getEventType() == null) {
        log.warn("收到空的审核事件,忽略");
        return;
    }

    try {
        switch (event.getEventType()) {
            case "SUBMITTED" -> handleSubmitted(event, type, link);
            case "APPROVED"  -> handleApproved(event, type, link);
            case "REJECTED"  -> handleRejected(event, type, link);
            default -> log.warn("未知的审核事件类型:{}", event.getEventType());
        }
    } catch (Exception e) {
        log.error("处理审核事件失败:eventType={}, documentId={}, error={}",
                event.getEventType(), event.getDocumentId(), e.getMessage(), e);
        // 捕获所有异常,避免死循环重试
    }
}

5.5 审核员三级降级查找

SUBMITTED 事件需要通知审核员,查找策略分三级降级:

① 查询 ROLE_REVIEWER 角色用户
     → 有人:逐个推送通知
     → 无人:降级
② 查询 ROLE_ADMIN 角色用户
     → 有人:逐个推送通知
     → 无人:再降级
③ 查询 ROLE_SUPER_ADMIN 角色用户
     → 有人:逐个推送通知
     → 无人:兜底通知文档作者本人
// ReviewNotificationListener.findReviewerUserIds()

private List<Long> findReviewerUserIds() {
    try {
        // 1. 优先查询审核员
        Result<List<Long>> result = userAuthFeignClient.getUserIdsByRole("ROLE_REVIEWER");
        if (result != null && result.getData() != null && !result.getData().isEmpty()) {
            return result.getData();
        }

        // 2. 降级:查询 ROLE_ADMIN
        Result<List<Long>> adminResult = userAuthFeignClient.getUserIdsByRole("ROLE_ADMIN");
        if (adminResult != null && adminResult.getData() != null && !adminResult.getData().isEmpty()) {
            return adminResult.getData();
        }

        // 3. 最终降级:查询 ROLE_SUPER_ADMIN
        Result<List<Long>> superAdminResult = userAuthFeignClient.getUserIdsByRole("ROLE_SUPER_ADMIN");
        if (superAdminResult != null && superAdminResult.getData() != null && !superAdminResult.getData().isEmpty()) {
            return superAdminResult.getData();
        }

        return List.of();
    } catch (Exception e) {
        log.error("Feign查询审核员失败:{}", e.getMessage());
        return List.of();
    }
}

5.6 持久化 + WebSocket 双写

// ReviewNotificationListener.persistAndPush()

private void persistAndPush(Long userId, String type, String title,
                             String content, String link, Long documentId) {
    // 1. 持久化到数据库(始终执行,保证离线用户也能看到通知)
    NotificationDTO dto = new NotificationDTO();
    dto.setUserId(userId);
    dto.setNotificationType(type);
    dto.setTitle(title);
    dto.setContent(content);
    dto.setLink(link);
    dto.setRelatedType("document");
    dto.setRelatedId(documentId);
    dto.setIsRead(0);
    try {
        notificationService.sendNotification(dto);
    } catch (Exception e) {
        log.error("通知持久化失败:userId={}, error={}", userId, e.getMessage(), e);
        // 持久化失败不影响 WebSocket 推送(仍可尝试实时通知)
    }

    // 2. WebSocket 点对点推送(仅在 websocket.enabled=true 时)
    if (!isWebSocketEnabled()) return;

    Map<String, Object> payload = new LinkedHashMap<>();
    payload.put("notificationType", type);
    payload.put("title", title);
    payload.put("content", content);
    payload.put("link", link);
    payload.put("documentId", documentId);
    messagingTemplate.convertAndSendToUser(
            String.valueOf(userId), "/queue/notifications", payload);
}

容错设计:持久化失败不阻塞 WebSocket 推送,WebSocket 未启用不影响持久化。两者解耦,一个挂了另一个照常工作。


6. 操作日志事件流(全局切面)

6.1 设计思路

操作日志的需求是**记录所有标注了 **@OperationLog** 注解的 Controller 方法的请求信息**。如果每个 Controller 方法都手动写日志记录代码,重复度极高且容易遗漏。

本系统通过 Spring AOP 环绕切面 实现零侵入的操作日志采集,将日志事件通过 RabbitMQ 异步发送到 kb-foundation 持久化。

6.2 OperationLogEventDTO 事件体

// kb-common/.../event/OperationLogEventDTO.java

@Data @Builder @NoArgsConstructor @AllArgsConstructor
public class OperationLogEventDTO implements Serializable {
    private String module;           // 模块名称
    private String operationType;    // 操作类型
    private String operationDesc;    // 操作描述
    private String requestMethod;    // HTTP 方法
    private String requestUrl;       // 请求 URL
    private String requestParams;    // 请求参数(JSON)
    private Long userId;             // 用户ID
    private String username;         // 用户名
    private String ipAddress;        // IP地址
    private String userAgent;        // 用户代理
    private Integer executeTime;     // 执行时长(毫秒)
    private Integer status;          // 1-成功,0-失败
    private String errorMsg;         // 错误信息
}

6.3 生产者:OperationLogAspect

// kb-common/.../aspect/OperationLogAspect.java

@Aspect
@Component
@ConditionalOnWebApplication(type = ConditionalOnWebApplication.Type.SERVLET)
public class OperationLogAspect {

    @Around("@annotation(operationLog)")
    public Object around(ProceedingJoinPoint joinPoint, OperationLog operationLog) throws Throwable {
        long startTime = System.currentTimeMillis();
        OperationLogEventDTO event = buildBaseEvent(joinPoint, operationLog);

        try {
            Object result = joinPoint.proceed();                    // 执行原方法
            long executeTime = System.currentTimeMillis() - startTime;

            event.setExecuteTime((int) executeTime);
            event.setStatus(1);                                     // 成功
            publishEvent(event);

            return result;
        } catch (Throwable e) {
            long executeTime = System.currentTimeMillis() - startTime;

            event.setExecuteTime((int) executeTime);
            event.setStatus(0);                                     // 失败
            event.setErrorMsg(truncate(e.getMessage(), 500));
            publishEvent(event);

            throw e;                                                // 原异常继续抛出
        }
    }
}

关键设计:不管是正常返回还是抛出异常,日志事件都会发布。throw e\_ 确保即使记录日志成功,原始异常也不会被吞掉。\_

6.4 参数安全过滤

// OperationLogAspect.filterArg()

private Object filterArg(Object arg) {
    if (arg == null) return null;
    if (arg instanceof MultipartFile f) {
        return Map.of(
                "type", "MultipartFile",
                "originalFilename", f.getOriginalFilename() != null ? f.getOriginalFilename() : "unknown",
                "size", f.getSize()
        );
    }
    if (arg instanceof HttpServletRequest)  return "[HttpServletRequest]";
    if (arg instanceof HttpServletResponse) return "[HttpServletResponse]";
    if (arg instanceof InputStream)         return "[InputStream]";
    if (arg instanceof OutputStream)        return "[OutputStream]";
    return arg;
}

防止将文件流、Request/Response 对象直接 JSON 序列化 —— 那会导致 OOM 或无限递归。截断策略:requestParams\_ 最长 1000 字符,errorMsg\_ 最长 500 字符,userAgent\_ 最长 500 字符。\_

6.5 消费者:OperationLogMQListener

// kb-foundation/.../mq/OperationLogMQListener.java

@RabbitListener(queues = "#{@operationLogQueue.name}")
public void handleOperationLogEvent(OperationLogEventDTO event) {
    try {
        long id = SnowflakeIdGenerator.getInstance().nextId();
        jdbcTemplate.update(
                "INSERT INTO kb_operation_log " +
                "(id, module, operation_type, operation_desc, request_method, request_url, " +
                "request_params, user_id, username, ip_address, user_agent, " +
                "execute_time, status, error_msg, created_at) " +
                "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, NOW())",
                id, event.getModule(), event.getOperationType(), event.getOperationDesc(),
                event.getRequestMethod(), event.getRequestUrl(), event.getRequestParams(),
                event.getUserId(), event.getUsername(), event.getIpAddress(),
                event.getUserAgent(), event.getExecuteTime(), event.getStatus(), event.getErrorMsg()
        );
    } catch (Exception e) {
        log.error("处理操作日志事件失败:module={}, operationType={}, error={}",
                event.getModule(), event.getOperationType(), e.getMessage(), e);
        // 不抛出异常,避免消息无限重试
    }
}

7. 统计事件流(异步解耦)

7.1 设计思路

浏览、点赞、评论三类统计操作有以下特点:

  1. 高频 — 浏览事件远多于创建/更新操作
  2. 非关键路径 — 统计计数器掉几个数不影响核心业务
  3. 独立数据源 — Redis 计数器 + MySQL 浏览历史表

因此,统计事件的发布完全异步(CompletableFuture.runAsync()),写入 Redis/MySQL 也在消费者侧独立处理。

7.2 StatisticsEventDTO 事件体

// kb-common/.../event/StatisticsEventDTO.java

@Data @Builder @NoArgsConstructor @AllArgsConstructor
public class StatisticsEventDTO implements Serializable {
    private String eventType;        // VIEW / LIKE / FAVORITE / COMMENT / CREATE
    private Long userId;             // 未登录时为 null
    private String userName;
    private Long documentId;
    private String documentTitle;
    private String ipAddress;
    private String userAgent;
    private LocalDateTime timestamp;
}

7.3 生产者:StatisticsEventPublisher

// kb-document/.../event/StatisticsEventPublisher.java

@Component
public class StatisticsEventPublisher {

    private static final String STATISTICS_EXCHANGE = "kb.statistics.exchange";

    @Resource private RabbitTemplate rabbitTemplate;
    @Resource private ThreadPoolTaskExecutor asyncTaskExecutor;
    @Resource private InstanceIdentifier instanceIdentifier;

    public void publishViewEvent(Long userId, String userName,
                                  Long documentId, String documentTitle) {
        CompletableFuture.runAsync(() -> {
            try {
                StatisticsEventDTO event = buildEvent("VIEW", userId, userName,
                        documentId, documentTitle);
                rabbitTemplate.convertAndSend(STATISTICS_EXCHANGE,
                        viewRoutingKey(), event);
            } catch (Exception e) {
                log.error("发布浏览事件失败:documentId={}, error={}", documentId, e.getMessage());
            }
        }, asyncTaskExecutor);
    }
    // publishLikeEvent() 和 publishCommentEvent() 同理
}

设计决策:CompletableFuture.runAsync()\_ 完全不阻塞 HTTP 请求线程。即使 RabbitMQ 不可达,\_catch\_ 只记日志,不影响用户浏览/点赞/评论的 HTTP 响应。\_

7.4 消费者:StatisticsMQListener(三队列独立消费)

// kb-statistics/.../mq/StatisticsMQListener.java

@Component
public class StatisticsMQListener {

    @RabbitListener(queues = "#{@statisticsViewQueue.name}")
    public void handleViewEvent(StatisticsEventDTO event) {
        // 1. 写入 kb_view_history 表(长期留存)
        long recordId = SnowflakeIdGenerator.getInstance().nextId();
        jdbcTemplate.update(
                "INSERT INTO kb_view_history (id, user_id, user_name, document_id, " +
                "document_title, ip_address, user_agent, created_at) " +
                "VALUES (?, ?, ?, ?, ?, ?, ?, NOW())",
                recordId, event.getUserId(), event.getUserName(),
                event.getDocumentId(), event.getDocumentTitle(),
                event.getIpAddress(), event.getUserAgent()
        );

        // 2. 更新 Redis 实时计数器(今日浏览数,48h TTL)
        String todayKey = "stats:counter:view:" + event.getDocumentId() + ":" + LocalDate.now();
        redisTemplate.opsForValue().increment(todayKey);
        redisTemplate.expire(todayKey, 48, TimeUnit.HOURS);
    }

    @RabbitListener(queues = "#{@statisticsLikeQueue.name}")
    public void handleLikeEvent(StatisticsEventDTO event) {
        String todayKey = "stats:counter:like:" + event.getDocumentId() + ":" + LocalDate.now();
        redisTemplate.opsForValue().increment(todayKey);
        redisTemplate.expire(todayKey, 48, TimeUnit.HOURS);
    }

    @RabbitListener(queues = "#{@statisticsCommentQueue.name}")
    public void handleCommentEvent(StatisticsEventDTO event) {
        String todayKey = "stats:counter:comment:" + event.getDocumentId() + ":" + LocalDate.now();
        redisTemplate.opsForValue().increment(todayKey);
        redisTemplate.expire(todayKey, 48, TimeUnit.HOURS);
    }
}
事件类型独立队列消费行为
VIEWkb.statistics.view.queue.{instanceId}MySQL kb_view_history + Redis stats:counter:view:{id}:{date}
LIKEkb.statistics.like.queue.{instanceId}Redis stats:counter:like:{id}:{date}
COMMENTkb.statistics.comment.queue.{instanceId}Redis stats:counter:comment:{id}:{date}

7.5 三队列分拆的设计理由

三种事件分三个队列而非合并为一个队列的原因:① VIEW 事件频率远高于 LIKE/COMMENT,合在一起会因 VIEW 积压导致 LIKE/COMMENT 被阻塞;② VIEW 有 MySQL 写入,LIKE/COMMENT 仅 Redis,处理速度不同,混在一起会互相拖慢。分拆后各队列独立消费、互不干扰。


8. 文件转码事件流(自产自消)

8.1 业务场景

用户上传视频文件 → 异步转为 HLS(HTTP Live Streaming)格式 → 生成多分辨率分片(360p/720p/1080p)+ 缩略图。转码是典型的 CPU/IO 密集型任务,不能阻塞上传接口的 HTTP 响应。

8.2 自产自消模式

文件转码的特殊之处在于 生产者和消费者在同一个服务内(kb-file),使用 DirectExchange + 单队列:

// kb-file/.../config/RabbitMQConfig.java

public static final String TRANSCODE_EXCHANGE = "transcode.exchange";

@Bean public DirectExchange transcodeExchange() {
    return new DirectExchange(TRANSCODE_EXCHANGE, true, false);
}

@Bean public Queue transcodeQueue() {
    return new Queue("transcode.queue." + instanceIdentifier.getId(),
            true, false, false);
}

@Bean public Binding transcodeBinding() {
    return BindingBuilder.bind(transcodeQueue())
            .to(transcodeExchange())
            .with("transcode." + instanceIdentifier.getId());
}

8.3 生产者:FileServiceImpl

// kb-file/.../service/impl/FileServiceImpl.java

rabbitTemplate.convertAndSend(
    RabbitMQConfig.TRANSCODE_EXCHANGE,
    "transcode." + instanceIdentifier.getId(),
    new TranscodeMessage(fileId, "hls")  // fileId: 文件ID, targetFormat: "hls"
);

8.4 消费者:TranscodeConsumer

// kb-file/.../consumer/TranscodeConsumer.java

@RabbitListener(queues = "#{@transcodeQueue.name}")
public void handleTranscodeMessage(TranscodeMessage message) {
    // 1. 查询文件记录
    // 2. 调用 FFmpeg 转码为 HLS (360p/720p/1080p)
    // 3. 生成缩略图
    // 4. 更新文件状态(转码中 → 已完成/失败)
}

设计决策:虽然自产自消可以直接使用异步线程池,但选择 MQ 的原因有两个:① MQ 自带持久化和重试机制,服务重启后消息不丢失;② 未来可以将消费者拆到独立的转码 Worker 实例,只需改队列绑定,不需要改代码。


9. RAG 与 KAG 索引构建事件流(带 DLQ)

9.1 为什么这俩需要死信队列

RAG 向量索引重建和 KAG 知识图谱构建是系统中最重的任务 —— 可能需要调用 LLM Embedding API(RAG)或 Neo4j 图数据库写入(KAG),其中:

  • LLM API 可能限流、返回 429
  • Neo4j 可能连接超时
  • 大文档分块可能 OOM

如果使用 Spring AMQP 的默认自动重试(无限制),异常消息会被无限投递 → 无限重试 → 无限失败 → CPU 空转。DLQ(Dead Letter Queue) 是标准解法:当消息被 reject/nack 或 TTL 过期后,自动路由到死信交换机,保留消息体供人工排查。

9.2 RAG 的 DLQ 配置

// kb-ai/.../config/RabbitConfig.java

@Configuration
@ConditionalOnProperty(name = "rag.enabled", havingValue = "true", matchIfMissing = true)
public class RabbitConfig {

    public static final String EXCHANGE = "rag.reindex.exchange";

    @Bean
    public Queue ragReindexQueue() {
        return QueueBuilder.durable(ragReindexQueueName())
                .withArgument("x-dead-letter-exchange", EXCHANGE + ".dlx")
                // ↑ 声明 DLX,nack/reject 的消息自动路由到 rag.reindex.exchange.dlx
                .build();
    }

    @Bean public TopicExchange ragReindexExchange() {
        return new TopicExchange(EXCHANGE);
    }

    @Bean
    public Binding ragReindexAllBinding() {
        return BindingBuilder.bind(ragReindexQueue())
                .to(ragReindexExchange())
                .with(ragReindexRoutingKeyAll());
    }
    // ... 还有 by_ids 和 delete 两个绑定,共享同一个队列
}

9.3 KAG 的 DLQ 配置(同理)

// kb-ai/.../config/KAGRabbitConfig.java

@Configuration
@ConditionalOnProperty(name = "kag.enabled", havingValue = "true", matchIfMissing = true)
public class KAGRabbitConfig {

    public static final String EXCHANGE = "kag.graph.exchange";

    @Bean
    public Queue kagGraphBuildQueue() {
        return QueueBuilder.durable(kagGraphBuildQueueName())
                .withArgument("x-dead-letter-exchange", EXCHANGE + ".dlx")
                .build();
    }
    // ... bindings for all, by_ids, delete
}

9.4 三种任务类型共享一个队列

RAG 和 KAG 各自只有 一个队列,但通过不同的 routingKey 区分任务类型:

路由键任务类型业务含义
rag.reindex.{id}.allALL全量重建索引(例如系统冷启动)
rag.reindex.{id}.by_idsBY\_DOC\_IDS按文档ID列表增量重建
rag.reindex.{id}.deleteDELETE\_BY\_DOC\_IDS删除指定文档的向量索引

9.5 消费者:手动 ACK

// kb-ai/.../mq/ReindexConsumer.java

@RabbitListener(queues = "#{@ragReindexQueue.name}", ackMode = "MANUAL")
public void handleReindex(ReindexMessage message, Channel channel,
                           @Header(AmqpHeaders.DELIVERY_TAG) long deliveryTag) {
    try {
        switch (message.getType()) {
            case ALL              -> handleRebuildAll(message);
            case BY_DOC_IDS       -> handleRebuildByIds(message);
            case DELETE_BY_DOC_IDS -> handleDeleteByIds(message);
        }
        channel.basicAck(deliveryTag, false);    // 成功:手动确认
    } catch (Exception e) {
        log.error("RAG重建任务处理失败:taskId={}, type={}, error={}",
                message.getTaskId(), message.getType(), e.getMessage(), e);
        try {
            channel.basicNack(deliveryTag, false, false);
            // ↓ requeue=false → 消息不重新入队,直接进入 DLX
        } catch (Exception ex) {
            log.error("nack 失败:{}", ex.getMessage());
        }
    }
}

\_为什么用 ackMode="MANUAL"\_ 而非默认的 AUTO?RAG 重建任务可能需要几分钟才能完成(大文档分块 + LLM Embedding API 调用 + 写入向量库),AUTO 模式在方法返回时自动 ack,但如果 LLM API 在方法执行中抛异常,消息就已 auto-ack 无法重试。MANUAL 模式下,只有所有 Embedding API 调用成功并且向量索引写入完成,才手动 ack。任何一个环节失败,basicNack 不重新入队(requeue=false\_),消息进入 DLQ。\_

9.6 Feign 触发链路

RAG 和 KAG 的构建通过 Feign 触发,Feign 成功后由 MQ 异步执行:

文档发布/更新
  → kb-document 调用 RagFeignClient.reindexDocument(docId)
       POST /rag/reindex/{docId} (Feign: kb-document → kb-ai)
  → kb-ai ReindexServiceImpl 收到请求
       → 构建 ReindexMessage(type=BY_DOC_IDS, docIds=[docId])
       → rabbitTemplate.convertAndSend("rag.reindex.exchange", "rag.reindex.{id}.by_ids", message)
  → ReindexConsumer 消费
       → 查询文档全文
       → 按 ## 标题分块
       → 调用 Qwen text-embedding-v3 API 生成 1024d 向量
       → 写入向量库
       → channel.basicAck()  ← 全部成功后才确认

9.7 DLQ 消息处置策略

图片.png

当前版 DLQ 采用运维手动处置策略。后续迭代可引入 DLQ 消费监控告警(钉钉/邮件通知),并支持一键重发功能。

10. 总结

1. 服务解耦彻底

审核通知、操作日志、统计计数、文件转码、索引重建全部通过 RabbitMQ 异步解耦。生产者完全不知道消费者是谁,消费者也完全不关心消息来自哪个服务。新增一个统计维度(比如收藏),只需在 StatisticsEventDTO 加一个 eventType、多绑定一个队列,不需要修改任何已有代码。

2. InstanceIdentifier 设计精巧

三级取值(配置 → hostname → UUID)覆盖了所有开发场景:正式环境显式指定、本地开发自动检测、CI 环境随机兜底。sanitize() 方法将任意 hostname 转为合法 MQ 标识符,简单且鲁棒。所有队列名和路由键嵌入 instanceId,多开发者的消息天然隔离,从零配置。

3. 消息序列化链路统一

所有模块统一用 Jackson2JsonMessageConverter + DefaultClassMapper + JavaTimeModule,消息在 RabbitMQ 管理界面中是人类可读的 JSON,排查问题方便。DefaultClassMapper 的 __TypeId__ 头确保消费者能正确反序列化,避免了 ClassCastException。

4. 容错设计层层递进

  • Producer 层面:confirmCallback + returnsCallback 检测交换机和队列问题
  • Consumer 层面:RAG/KAG 带 DLQ 防止死循环重试,其他 Consumer 捕获所有异常不 re-throw
  • 关键路径:通知双写(DB + WebSocket),一边挂了另一边照常
  • 非关键路径:统计事件异步 CompletableFuture,MQ 不可达不影响用户请求

5. Feign + MQ 配合合理

系统没有"一切皆 MQ"的教条 —— ES 关键词索引同步使用 Feign(需要同步拿到结果),而通知、日志、统计、转码、索引重建全部用 MQ(不需要等待结果)。同一种通信模式内也有区分:操作日志在 MQ 中走 send() 手动序列化(避免 Bean 冲突),审核通知走 convertAndSend() 自动序列化。

6. DLQ 的精确应用

只为 RAG 和 KAG 配置了 DLQ,而不是一刀切全局启用。原因是只有这两个 Consumer 的执行时间不可预测(LLM API 调用、Neo4j 写入),其他 Consumer(通知写入、日志写入、Redis 计数)都是快速数据库操作,基本不会失败。DLQ 的开销(额外的交换机和队列)只加在需要的地方。

7. AOP 零侵入操作日志

@OperationLog 注解 + OperationLogAspect 切面,Controller 方法只需一个注解,所有请求信息(URL、参数、IP、耗时、状态)自动采集并通过 MQ 异步写入。参数安全过滤(MultipartFile → 文件名+大小)避免了 OOM。

最后修改:2026 年 10 月 24 日
如果觉得我的文章对你有用,请随意赞赏