前言
企业智能知识库系统是一个由 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-document | kb.notification.exchange | TopicExchange | 1 | 1 | 无 |
| kb-foundation | kb.notification.exchange | TopicExchange | 2 | 2 | 无 |
| kb-foundation | kb.config.exchange | DirectExchange | 1 | 1 | 无 |
| kb-foundation | kb.operationlog.exchange | TopicExchange | 1 | 1 | 无 |
| kb-file | transcode.exchange | DirectExchange | 1 | 1 | 无 |
| kb-ai | rag.reindex.exchange | TopicExchange | 1 | 3 | 有 |
| kb-ai | kag.graph.exchange | TopicExchange | 1 | 3 | 有 |
| kb-statistics | kb.statistics.exchange | TopicExchange | 3 | 3 | 无 |
注意:kb.notification.exchange\_ 在 kb-document 和 kb-foundation 中各声明一次,这是设计上的有意冗余 —— 确保生产者和消费者都能独立启动,不依赖对方的启动顺序。Spring AMQP 的 \_TopicExchange(..., true, false)\_ 声明是幂等的,重复声明不会报错。\_
2.2 架构全景图

2.3 6 大事件流速览
| # | 事件流 | 交换 | 消息 DTO | 生产者 | 消费者 | 消费结果 |
|---|---|---|---|---|---|---|
| 1 | 审核通知 | kb.notification.exchange | ReviewEventDTO | DocumentReviewServiceImpl | ReviewNotificationListener | 持久化通知 + WebSocket 推送 |
| 2 | 操作日志 | kb.operationlog.exchange | OperationLogEventDTO | OperationLogAspect | OperationLogMQListener | 写入 kb\_operation\_log |
| 3 | 浏览统计 | kb.statistics.exchange | StatisticsEventDTO | StatisticsEventPublisher | StatisticsMQListener | kb\_view\_history + Redis 计数 |
| 4 | 点赞统计 | kb.statistics.exchange | StatisticsEventDTO | StatisticsEventPublisher | StatisticsMQListener | Redis 计数 |
| 5 | 评论统计 | kb.statistics.exchange | StatisticsEventDTO | StatisticsEventPublisher | StatisticsMQListener | Redis 计数 |
| 6 | 文件转码 | transcode.exchange | TranscodeMessage | FileServiceImpl | TranscodeConsumer | FFmpeg HLS 转码 |
| 7 | RAG 索引 | rag.reindex.exchange | ReindexMessage | ReindexServiceImpl | ReindexConsumer | 文档分块→嵌入→向量索引 |
| 8 | KAG 图谱 | kag.graph.exchange | KAGReindexMessage | GraphBuildServiceImpl | KAGReindexConsumer | Neo4j 知识图谱构建 |
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._-]", "-");
}
}| 优先级 | 来源 | 示例值 | 适用场景 |
|---|---|---|---|
| 1 | app.instance.id 配置项 | zhangsan | 开发者显式指定自己的标识 |
| 2 | 本机 hostname | MacBook-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}.*
\_关键点:交换机全局共享,队列与路由键实例隔离。同一 TopicExchange 下,路由键 *.MacBook-Pro-A.*\_ 只匹配队列 *.queue.MacBook-Pro-A\_,不同开发者的消息天然隔离。\_
4. 消息序列化与可靠投递
4.1 序列化链路

Spring Boot 默认使用 SimpleMessageConverter(Java 原生序列化),这会导致两个问题:
- 消息不可读 — RabbitMQ 管理界面看到的是二进制乱码
- 跨服务兼容性差 — 必须共享完全一致的类定义
本系统全部覆盖为 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;
}| 配置项 | 作用 | 问题(如果没有) |
|---|---|---|
Jackson2JsonMessageConverter | JSON 格式序列化 | 二进制 Java 序列化,消息不可读 |
JavaTimeModule | LocalDateTime 不序列化成数组 | 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 设计思路
浏览、点赞、评论三类统计操作有以下特点:
- 高频 — 浏览事件远多于创建/更新操作
- 非关键路径 — 统计计数器掉几个数不影响核心业务
- 独立数据源 — 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);
}
}| 事件类型 | 独立队列 | 消费行为 |
|---|---|---|
| VIEW | kb.statistics.view.queue.{instanceId} | MySQL kb_view_history + Redis stats:counter:view:{id}:{date} |
| LIKE | kb.statistics.like.queue.{instanceId} | Redis stats:counter:like:{id}:{date} |
| COMMENT | kb.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}.all | ALL | 全量重建索引(例如系统冷启动) |
rag.reindex.{id}.by_ids | BY\_DOC\_IDS | 按文档ID列表增量重建 |
rag.reindex.{id}.delete | DELETE\_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 消息处置策略

当前版 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。