前言
企业智能知识库系统采用微服务架构,由 9 个独立服务组成。
服务之间需要频繁通信:文档发布后要触发 AI 索引和图谱构建、用户操作要写入统计数据、审核状态变更要推送通知消息。这些通信场景对一致性、延迟、可用性的要求各不相同。
本系统采用同步 Feign + 异步 RabbitMQ 双通道通信架构:
- 同步通道(Feign):适合查询类操作(获取文档内容、验证 Token),调用方需要立即获得响应
- 异步通道(RabbitMQ):适合事件通知类操作(审核通知、统计写入、操作日志),不阻塞主流程
- 网关通道(Spring Cloud Gateway):统一外部入口,路由分发到后端服务
- 服务发现(Nacos):动态注册与发现,支持多开发者实例隔离
本文将从网关层到消息队列层,逐层拆解这套通信架构。
1. 一次跨服务调用走完发生了什么
用户在前端点击"发布文档",系统启动一条完整的跨服务通信链:
用户点击"发布文档" → 前端 POST /api/document/documents/{id}/publish
→ Gateway: /api/document/** → lb://kb-document
→ kb-document DocumentController.publishDocument()
├── 同步调用(Feign):
│ ├── → kb-search: POST /index/document — 写入 ES 索引
│ ├── → kb-ai: POST /rag/reindex/{docId} — 触发 RAG 异步重建
│ └── → kb-ai: POST /kag/build/{docId} — 触发 KAG 异步重建
│
├── 异步消息(RabbitMQ):
│ └── → kb.notification.exchange — 发审核提交事件
│ routingKey: notification.review.{id}.submitted
│
└── 返回发布成功 → 前端收到 200 OK
Nacos 后台(并行运行):
├── kb-search 从 Nacos 获取 kb-document 的 IP
├── kb-ai 从 Nacos 获取 kb-graph 的 IP(KAG 构建时调用)
└── kb-foundation 监听 review 队列,消费审核事件 → 推送通知2. 服务拓扑:9 个服务,一张网
2.1 服务清单
| 服务 | 端口 | Nacos 服务名 | 角色 |
|---|---|---|---|
| kb-gateway | 8080 | kb-gateway | API 统一入口 |
| kb-user-auth | 8081 | kb-user-auth | 认证授权中心 |
| kb-document | 8082 | kb-document | 文档 CRUD、审核 |
| kb-search | 8083 | kb-search | 全文搜索 (ES) |
| kb-file | 8084 | kb-file | 文件存储、转码 |
| kb-statistics | 8085 | kb-statistics | 统计采集与查询 |
| kb-ai | 8086 | kb-ai | RAG、KAG、LLM |
| kb-graph | 8088 | kb-graph | 知识图谱查询 (Neo4j) |
| kb-foundation | 8089 | kb-foundation | 通知、WebSocket、操作日志 |
2.2 服务间依赖全景

2.3 通信模式总览
| 通信方向 | 通道 | 典型场景 | 涉及服务 |
|---|---|---|---|
| 外部 → 服务 | HTTP (Gateway) | 所有用户请求 | 全部 |
| 服务 → 服务(同步) | Feign (HTTP) | 获取文档内容、验证Token、触发索引重建 | 5 个 Feign 客户端 |
| 服务 → 服务(异步) | RabbitMQ | 审核通知、统计采集、操作日志、文件转码 | 7 个 Exchange、10 个 Queue |
| 服务 → 浏览器 | WebSocket | 通知实时推送 | kb-foundation → 浏览器 |
3. 服务注册与发现:Nacos
3.1 注册配置
每个服务通过 application.yml 注册到 Nacos:
# kb-document/src/main/resources/application.yml
spring:
cloud:
nacos:
discovery:
server-addr: 117.72.88.11:8848
namespace: knowledge # 命名空间隔离
group: ${COMPUTER_ID:${USER:default}} # 多开发者分组隔离
username: nacos
password: susan123
ip: 127.0.0.1 # 强制注册本地 IP
config:
server-addr: 117.72.88.11:8848
namespace: knowledge
group: KNOWLEDGE_BASE
file-extension: yaml
config:
import: optional:nacos:kb-document-dev.yaml # 拉取外部化配置3.2 Nacos 分组隔离

关键设计:group: ${COMPUTER_ID:${USER:default}} 使每个开发者的服务实例注册到不同的 Nacos 分组。A 电脑上的 kb-document 通过 lb://kb-document 负载均衡时,只会发现同组内的实例,不会调用到 B 电脑的服务。
3.3 设计考量
| 维度 | 选择 | 理由 |
|---|---|---|
| 注册中心 | Nacos | 同时支持服务发现和配置管理,阿里云生态成熟 |
| 分组隔离 | COMPUTER_ID / USER 环境变量 | 无需修改配置,自动按机器隔离 |
| 强制 IP | ip: 127.0.0.1 | 避免多网卡时注册错误 IP |
| 配置外部化 | optional:nacos: | 配置未就绪时使用本地默认值,不阻塞启动 |
4. API 网关:Spring Cloud Gateway
4.1 路由表
所有外部请求统一从 :8080 进入,网关按路径前缀路由到对应的后端服务:
| 路由 ID | 路径断言 | 目标 | StripPrefix |
|---|---|---|---|
| kb-user-auth | /api/auth/** | lb://kb-user-auth | 2 |
| kb-document | /api/document/** | lb://kb-document | 2 |
| kb-file | /api/file/** | lb://kb-file | 2 |
| kb-ai | /api/ai/** | lb://kb-ai | 2 |
| kb-graph | /api/graph/** | lb://kb-graph | 2 |
| kb-search | /api/search/** | lb://kb-search | 2 |
| kb-statistics | /api/statistics/** | lb://kb-statistics | 1 |
| kb-foundation | /api/notifications/**, /api/config/**, /api/logs/**, /api/dicts/** | lb://kb-foundation | 1 |
| kb-foundation-ws | /ws/** | lb:ws://kb-foundation | 0 |
StripPrefix 说明:前端请求 /api/document/documents,Gateway 去掉 /api/document 前缀后转发为 lb://kb-document/documents。
4.2 路由配置
# kb-gateway/src/main/resources/application.yml
spring:
cloud:
gateway:
discovery:
locator:
enabled: true
lower-case-service-id: true
routes:
- id: kb-document
uri: lb://kb-document
predicates:
- Path=/api/document/**
filters:
- StripPrefix=2
- id: kb-foundation-ws
uri: lb:ws://kb-foundation
predicates:
- Path=/ws/**
filters:
- StripPrefix=0 # WebSocket 不截断路径
httpclient:
pool:
max-connections: 500
max-idle-time: 30s
max-life-time: 60s
connect-timeout: 3000
response-timeout: 120s4.3 认证白名单
Gateway 的 AuthFilter(GlobalFilter, order = -100)对所有请求进行认证拦截,但以下路径直接放行:
白名单:
/api/auth/auth/login — 登录
/api/auth/auth/register — 注册
/api/auth/auth/refresh — 刷新 Token
/api/document/share/** — 文档分享(公开访问)
/api/files/** — 文件访问(公开 URL)
/api/ai/** — AI 接口(内部鉴权)
/api/config/public — 公开配置
/ws/** — WebSocket 握手
/swagger-resources, /v3/api-docs — API 文档4.4 CORS 配置
spring:
cloud:
gateway:
globalcors:
cors-configurations:
'[/**]':
allowed-origins: "*"
allowed-methods: "*"
allowed-headers: "*"
max-age: 36005. 同步通信:Feign 声明式 RPC
5.1 Feign 客户端清单

| 调用方 | Feign 接口 | 目标服务 | 用途 |
|---|---|---|---|
| kb-document | KAGFeignClient | kb-ai | 触发 KAG 图谱构建 |
| kb-document | RagFeignClient | kb-ai | 触发 RAG 索引重建 |
| kb-document | GraphFeignClient | kb-graph | 删除/清理图谱数据 |
| kb-document | SearchIndexFeignClient | kb-search | 写入/删除 ES 索引 |
| kb-document | FileServiceFeignClient | kb-file | 文件上传 |
| kb-ai | DocumentFeignClient | kb-document | 获取文档内容 |
| kb-ai | GraphFeignClient | kb-graph | 清理图谱缓存 |
| kb-search | RagSearchFeignClient | kb-ai | 混合检索 (RAG) |
| kb-foundation | UserAuthFeignClient | kb-user-auth | Token 验证、角色查询 |
5.2 Feign 客户端实现示例
// kb-document/.../feign/KAGFeignClient.java
@FeignClient(
name = "kb-ai",
path = "/kag/build",
url = "${kb-ai.url:#{null}}",
contextId = "kagFeignClient"
)
public interface KAGFeignClient {
@PostMapping("/{docId}")
Result<String> buildGraph(@PathVariable("docId") Long docId);
@DeleteMapping("/{docId}")
Result<Void> deleteGraph(@PathVariable("docId") Long docId);
}// kb-ai/.../client/DocumentFeignClient.java
@FeignClient(
name = "kb-document",
url = "${kb-document.url:#{null}}",
configuration = InternalFeignConfig.class // 添加 X-User-Id: 0 绕过认证
)
public interface DocumentFeignClient {
@GetMapping("/documents/{documentId}")
Result<Map<String, Object>> getDocument(
@PathVariable("documentId") Long documentId
);
@GetMapping("/documents/page")
Result<Map<String, Object>> pageDocuments(
@RequestParam("current") Long current,
@RequestParam("size") Long size,
@RequestParam("status") Integer status
);
}5.3 Feign 配置
# kb-document/src/main/resources/application.yml
feign:
client:
config:
default:
connectTimeout: 5000 # 连接超时 5 秒
readTimeout: 30000 # 读取超时 30 秒
loggerLevel: basic
kb-file: # 文件上传特殊配置
connectTimeout: 10000
readTimeout: 600000 # 上传最大等待 10 分钟
loggerLevel: basic
circuitbreaker:
enabled: false # 不使用熔断(降级逻辑在 FallbackFactory 中)5.4 Feign 拦截器
// kb-common/.../feign/FeignInterceptorConfig.java
@Configuration
@ConditionalOnClass(RequestInterceptor.class)
public class FeignInterceptorConfig {
@Bean
public RequestInterceptor requestInterceptor() {
return requestTemplate -> {
// 标记为内部服务间调用
requestTemplate.header("INNER-REQUEST", "true");
// 传递当前 JWT Token
String token = UserContextUtil.getToken();
if (token != null && !token.isEmpty()) {
requestTemplate.header("Authorization", "Bearer " + token);
}
// 兜底传递用户 ID
Long userId = UserContextUtil.getUserId();
if (userId != null) {
requestTemplate.header("X-User-Id", String.valueOf(userId));
}
};
}
}// kb-ai/.../config/InternalFeignConfig.java
// 用于 kb-ai 内部调用 kb-document 和 kb-graph
// 绕过 JWT 认证过滤器
public class InternalFeignConfig {
@Bean
public RequestInterceptor internalRequestInterceptor() {
return template -> {
template.header("X-User-Id", "0"); // 系统用户标识
};
}
}5.5 Fallback 降级工厂
// kb-document/.../feign/FileServiceFallbackFactory.java
@Component
public class FileServiceFallbackFactory implements FallbackFactory<FileServiceFeignClient> {
@Override
public FileServiceFeignClient create(Throwable cause) {
log.error("文件服务 Feign 调用失败", cause);
return new FileServiceFeignClient() {
@Override
public Result<String> uploadFile(...) {
return null; // 返回 null,调用方按"上传失败"处理
}
};
}
}6. 异步通信:RabbitMQ 事件驱动
6.1 交换机与队列全景

6.2 完整交换机和队列清单
| Exchange | 类型 | 声明者 | Queue | 路由键模式 | 消费者 |
|---|---|---|---|---|---|
kb.notification.exchange | Topic | kb-document, kb-foundation | kb.notification.review.queue.{id} | notification.review.{id}.* | kb-foundation ReviewNotificationListener |
kb.notification.exchange | Topic | kb-foundation | kb.notification.queue.{id} | notification.{id}.# | kb-foundation(预留) |
kb.statistics.exchange | Topic | kb-statistics | kb.statistics.view.queue.{id} | statistics.view.{id}.* | kb-statistics StatisticsMQListener |
kb.statistics.exchange | Topic | kb-statistics | kb.statistics.like.queue.{id} | statistics.like.{id}.* | kb-statistics StatisticsMQListener |
kb.statistics.exchange | Topic | kb-statistics | kb.statistics.comment.queue.{id} | statistics.comment.{id}.* | kb-statistics StatisticsMQListener |
rag.reindex.exchange | Topic | kb-ai | rag.reindex.queue.{id} | rag.reindex.{id}.{all/by_ids/delete} | kb-ai ReindexConsumer |
kag.graph.exchange | Topic | kb-ai | kag.graph.build.queue.{id} | kag.graph.build.{id}.{all/by_ids} / kag.graph.delete.{id} | kb-ai KAGReindexConsumer |
transcode.exchange | Direct | kb-file | transcode.queue.{id} | transcode.{id} | kb-file TranscodeConsumer |
kb.operationlog.exchange | Topic | kb-foundation | kb.operationlog.queue.{id} | operationlog.{id}.# | kb-foundation OperationLogMQListener |
kb.config.exchange | Direct | kb-foundation | kb.config.queue.{id} | config.{id}.update | kb-foundation(预留) |
{id} = InstanceIdentifier.getId() 的实际值,如 MacBook-Pro。
6.3 生产者代码
// kb-document/.../service/impl/DocumentReviewServiceImpl.java
@Resource
private RabbitTemplate rabbitTemplate;
@Resource
private InstanceIdentifier instanceIdentifier;
private static final String REVIEW_EXCHANGE = "kb.notification.exchange";
// 构建实例隔离的路由键
private String reviewRoutingKey(String eventType) {
return "notification.review." + instanceIdentifier.getId() + "." + eventType;
}
// 发送审核事件
public void publishReviewEvent(ReviewEventDTO event) {
CorrelationData correlationData = new CorrelationData(UUID.randomUUID().toString());
rabbitTemplate.convertAndSend(
REVIEW_EXCHANGE,
reviewRoutingKey("submitted"), // 例:notification.review.MacBook-Pro.submitted
event,
correlationData
);
log.info("已发布审核事件:documentId={}, routingKey={}",
event.getDocumentId(), reviewRoutingKey("submitted"));
}6.4 消费者代码
// kb-foundation/.../mq/ReviewNotificationListener.java
@Component
@Slf4j
public class ReviewNotificationListener {
@RabbitListener(queues = "#{@reviewNotificationQueue.name}")
public void handleReviewEvent(ReviewEventDTO event) {
// 根据事件类型分发处理
switch (event.getEventType()) {
case "SUBMITTED" -> handleSubmitted(event);
case "APPROVED" -> handleApproved(event);
case "REJECTED" -> handleRejected(event);
}
}
}#{@reviewNotificationQueue.name} 是 Spring SpEL 表达式,运行时从 Spring 容器中获取名为 reviewNotificationQueue 的 Queue Bean,动态获取其实际队列名。
6.5 手动 ACK 与死信
// kb-ai/.../mq/KAGReindexConsumer.java
@RabbitListener(queues = "#{@kagGraphBuildQueue.name}", ackMode = "MANUAL")
public void handleBuild(
KAGReindexMessage message,
Channel channel,
@Header(AmqpHeaders.DELIVERY_TAG) long deliveryTag) throws IOException {
try {
// 执行图谱构建...
graphBuildService.buildBatch(message.getDocumentIds());
// 构建成功,手动确认
channel.basicAck(deliveryTag, false);
} catch (Exception e) {
log.error("KAG 构建失败:taskId={}", message.getTaskId(), e);
// 不重新入队(requeue=false),进入死信队列
channel.basicNack(deliveryTag, false, false);
}
}6.6 Publisher Confirms 与 Mandatory
// kb-document/.../config/RabbitMQConfig.java
@Bean
public RabbitTemplate rabbitTemplate(ConnectionFactory connectionFactory,
Jackson2JsonMessageConverter converter) {
RabbitTemplate template = new RabbitTemplate(connectionFactory);
template.setMessageConverter(converter);
// 发布确认:消息到达交换机后回调
template.setConfirmCallback((correlationData, ack, cause) -> {
if (!ack) {
log.error("消息发送到交换机失败:id={}, cause={}",
correlationData.getId(), cause);
}
});
// Mandatory:消息无法路由到队列时回调
template.setMandatory(true);
template.setReturnsCallback(returned -> {
log.error("消息未路由到任何队列:exchange={}, routingKey={}, replyText={}",
returned.getExchange(), returned.getRoutingKey(),
returned.getReplyText());
});
return template;
}6.7 消息传输保证
| 保证级别 | 机制 |
|---|---|
| 持久化 | Exchange durable=true,Queue durable=true,Message deliveryMode=2 |
| 生产者确认 | setConfirmCallback — 交换机接收到消息时回调 |
| 路由确认 | setMandatory(true) + ReturnsCallback — 消息找不到队列时回调 |
| 消费确认 | ackMode="MANUAL" — 处理成功后 basicAck,失败后 basicNack |
| 死信处理 | x-dead-letter-exchange — 失败消息进入 DLQ,不丢失 |
| 消息幂等 | CorrelationData UUID 唯一标识 + taskId 业务去重 |
7. 消息序列化与类型安全
7.1 Jackson2JsonMessageConverter
所有 RabbitMQ 消息通过 Jackson2JsonMessageConverter 序列化为 JSON。每个服务配置自己的 DefaultClassMapper 白名单:
// kb-document/.../config/RabbitMQConfig.java
@Bean
public Jackson2JsonMessageConverter jackson2JsonMessageConverter() {
ObjectMapper objectMapper = new ObjectMapper();
objectMapper.registerModule(new JavaTimeModule());
Jackson2JsonMessageConverter converter = new Jackson2JsonMessageConverter(objectMapper);
DefaultClassMapper classMapper = new DefaultClassMapper();
classMapper.setTrustedPackages(
"com.knowledge.base.common.event", // ReviewEventDTO, StatisticsEventDTO
"com.knowledge.base.document.dto",
"java.util",
"java.lang"
);
converter.setClassMapper(classMapper);
return converter;
}关键安全设计:DefaultClassMapper 限制反序列化类型白名单,防止反序列化漏洞。消费者只会反序列化来自受信包下的类。
7.2 消息类目
| 消息类型 | 包路径 | 声明处 | 消费处 |
|---|---|---|---|
| ReviewEventDTO | kb-common/.../event/ | kb-document | kb-foundation |
| StatisticsEventDTO | kb-common/.../event/ | kb-document | kb-statistics |
| OperationLogEventDTO | kb-common/.../event/ | kb-common (AOP) | kb-foundation |
| ReindexMessage | kb-ai/.../mq/ | kb-ai | kb-ai |
| KAGReindexMessage | kb-ai/.../mq/ | kb-ai | kb-ai |
| TranscodeMessage | kb-file/.../consumer/ | kb-file | kb-file |
7.3 公共事件传输对象
// kb-common/.../event/ReviewEventDTO.java
public class ReviewEventDTO implements Serializable {
private String eventType; // SUBMITTED / APPROVED / REJECTED
private Long documentId;
private String documentTitle;
private Long authorId;
private String authorName;
private Long reviewerId;
private String reviewerName;
private String reviewComment;
private LocalDateTime timestamp;
}
// kb-common/.../event/StatisticsEventDTO.java
public class StatisticsEventDTO implements Serializable {
private String eventType; // VIEW / LIKE / FAVORITE / COMMENT / CREATE
private Long userId;
private String userName;
private Long documentId;
private String documentTitle;
private String ipAddress;
private String userAgent;
private LocalDateTime timestamp;
}
// kb-common/.../event/OperationLogEventDTO.java
public class OperationLogEventDTO implements Serializable {
private String module; // 操作模块
private String operationType; // CREATE / UPDATE / DELETE / QUERY
private String operationDesc; // 操作描述
private String requestMethod; // GET / POST / PUT / DELETE
private String requestUrl;
private String requestParams;
private Long userId;
private String username;
private String ipAddress;
private String userAgent;
private Long executeTime; // 执行耗时(毫秒)
private Integer status; // 1=成功 0=失败
private String errorMsg;
}8. 多开发者实例隔离
8.1 隔离策略
本系统从三个层面实现多开发者环境隔离:
| 层面 | 机制 | 隔离粒度 |
|---|---|---|
| Nacos 服务发现 | group: ${COMPUTER_ID} | 服务调用不跨开发者 |
| RabbitMQ 队列 | 队列名 + 路由键附带 InstanceIdentifier.getId() | 消息不跨开发者 |
| 数据库 | 每个开发者本地 MySQL | 数据不跨开发者 |
8.2 InstanceIdentifier
// kb-common/.../config/InstanceIdentifier.java
@Component
public class InstanceIdentifier implements InitializingBean {
@Value("${app.instance.id:}")
private String configuredId;
@Getter
private String id;
@Override
public void afterPropertiesSet() {
this.id = resolve();
log.info("当前实例标识(instanceId):{}", this.id);
}
private String resolve() {
// 1. 优先使用配置值(如 app.instance.id=zhangsan)
if (configuredId != null && !configuredId.trim().isEmpty()) {
return sanitize(configuredId.trim());
}
// 2. 降级使用主机名(如 MacBook-Pro)
try {
String hostname = InetAddress.getLocalHost().getHostName();
// ... 去掉域名后缀
return sanitize(hostname);
} catch (Exception e) {
log.warn("获取主机名失败:{}", e.getMessage());
}
// 3. 兜底使用随机 UUID
return "local-" + UUID.randomUUID().toString().substring(0, 8);
}
}8.3 隔离效果示意
开发者 A (MacBook-Pro) 提交文档:
→ MQ 路由键:notification.review.MacBook-Pro.submitted
→ 队列:kb.notification.review.queue.MacBook-Pro
→ 消费者:A 的 kb-foundation(只消费 MacBook-Pro 队列)
→ ✅ A 收到通知
开发者 B (ThinkPad) :
→ 不受 A 的任何消息影响
→ ✅ B 不收 A 的通知9. 容错与降级
9.1 降级层级

9.2 各通道容错机制
| 通道 | 故障场景 | 降级行为 |
|---|---|---|
| Feign | 目标服务不可达 | FallbackFactory 返回 null / 空列表 |
| Feign | 连接超时 | 5 秒超时,记录错误日志 |
| RabbitMQ | Broker 不可达 | 降级为同步执行(如 KAG 构建直接调用 buildForDocument) |
| RabbitMQ | 交换机不存在 | Publisher Confirm 回调记录错误 |
| RabbitMQ | 路由失败 | Mandatory ReturnsCallback 记录错误日志 |
| RabbitMQ | 消费失败 | basicNack → 死信队列 DLQ |
| Gateway | 后端不可达 | Spring Cloud Gateway 返回 503 |
9.3 KAG 构建的同步降级
// kb-ai/.../kag/graph/impl/GraphBuildServiceImpl.java
public String publishBuildTask(Long docId) {
KAGReindexMessage message = buildMessage(List.of(docId));
try {
rabbitTemplate.convertAndSend(
KAGRabbitConfig.EXCHANGE,
"kag.graph.build." + instanceIdentifier.getId() + ".by_ids",
message
);
return message.getTaskId();
} catch (Exception e) {
// 降级:RabbitMQ 不可用时同步执行
log.warn("RabbitMQ 发送失败,降级为同步构建:docId={}", docId, e);
buildForDocument(docId);
return "sync-" + message.getTaskId();
}
}总结
- 双通道互补:Feign 用于需要即时响应的查询(获取文档内容、验证Token),RabbitMQ 用于异步事件通知(审核、统计、日志)。两类通信场景各得其所。
- Nacos 配置中心:所有服务的核心配置(数据库连接、RabbitMQ 地址、LLM API Key)通过
optional:nacos:外部化,配置变更无需重启。 - 零代码多开发者隔离:InstanceIdentifier 三阶降级(配置 > hostname > UUID) + Nacos 分组 + MQ 动态队列/路由键,新开发者 clone 代码即可启动,无需任何配置修改。
- 消息传输可靠:持久化 + Publisher Confirms + Mandatory + 手动 ACK + 死信队列,五道防线确保消息不丢失。
- 类型安全反序列化:DefaultClassMapper 白名单防止反序列化漏洞,每个服务仅反序列化自己信任的包。
- 优雅降级:Feign 有 FallbackFactory 返回降级结果,MQ 发布失败有同步兜底,Gateway 有白名单放行关键路径。
- Gateway WebSocket 支持:
lb:ws://kb-foundation路由 +StripPrefix=0,WebSocket 长连接通过 Gateway 无感透传。
适用场景
此跨服务通信架构适用于:
- 中等规模微服务:9 个服务,服务间有明确依赖关系
- 同步+异步混合场景:既有即时查询也有异步事件通知
- 多开发者并行开发:需要环境隔离且零配置启动
- 对消息可靠性有要求:审核、统计等数据不能丢失