前言

企业智能知识库系统采用微服务架构,由 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-gateway8080kb-gatewayAPI 统一入口
kb-user-auth8081kb-user-auth认证授权中心
kb-document8082kb-document文档 CRUD、审核
kb-search8083kb-search全文搜索 (ES)
kb-file8084kb-file文件存储、转码
kb-statistics8085kb-statistics统计采集与查询
kb-ai8086kb-aiRAG、KAG、LLM
kb-graph8088kb-graph知识图谱查询 (Neo4j)
kb-foundation8089kb-foundation通知、WebSocket、操作日志

2.2 服务间依赖全景

图片.png

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 分组隔离

图片.png

关键设计:group: ${COMPUTER_ID:${USER:default}} 使每个开发者的服务实例注册到不同的 Nacos 分组。A 电脑上的 kb-document 通过 lb://kb-document 负载均衡时,只会发现同组内的实例,不会调用到 B 电脑的服务。

3.3 设计考量

维度选择理由
注册中心Nacos同时支持服务发现和配置管理,阿里云生态成熟
分组隔离COMPUTER_ID / USER 环境变量无需修改配置,自动按机器隔离
强制 IPip: 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-auth2
kb-document/api/document/**lb://kb-document2
kb-file/api/file/**lb://kb-file2
kb-ai/api/ai/**lb://kb-ai2
kb-graph/api/graph/**lb://kb-graph2
kb-search/api/search/**lb://kb-search2
kb-statistics/api/statistics/**lb://kb-statistics1
kb-foundation/api/notifications/**, /api/config/**, /api/logs/**, /api/dicts/**lb://kb-foundation1
kb-foundation-ws/ws/**lb:ws://kb-foundation0

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: 120s

4.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: 3600

5. 同步通信:Feign 声明式 RPC

5.1 Feign 客户端清单

图片.png

调用方Feign 接口目标服务用途
kb-documentKAGFeignClientkb-ai触发 KAG 图谱构建
kb-documentRagFeignClientkb-ai触发 RAG 索引重建
kb-documentGraphFeignClientkb-graph删除/清理图谱数据
kb-documentSearchIndexFeignClientkb-search写入/删除 ES 索引
kb-documentFileServiceFeignClientkb-file文件上传
kb-aiDocumentFeignClientkb-document获取文档内容
kb-aiGraphFeignClientkb-graph清理图谱缓存
kb-searchRagSearchFeignClientkb-ai混合检索 (RAG)
kb-foundationUserAuthFeignClientkb-user-authToken 验证、角色查询

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 交换机与队列全景

图片.png

6.2 完整交换机和队列清单

Exchange类型声明者Queue路由键模式消费者
kb.notification.exchangeTopickb-document, kb-foundationkb.notification.review.queue.{id}notification.review.{id}.*kb-foundation ReviewNotificationListener
kb.notification.exchangeTopickb-foundationkb.notification.queue.{id}notification.{id}.#kb-foundation(预留)
kb.statistics.exchangeTopickb-statisticskb.statistics.view.queue.{id}statistics.view.{id}.*kb-statistics StatisticsMQListener
kb.statistics.exchangeTopickb-statisticskb.statistics.like.queue.{id}statistics.like.{id}.*kb-statistics StatisticsMQListener
kb.statistics.exchangeTopickb-statisticskb.statistics.comment.queue.{id}statistics.comment.{id}.*kb-statistics StatisticsMQListener
rag.reindex.exchangeTopickb-airag.reindex.queue.{id}rag.reindex.{id}.{all/by_ids/delete}kb-ai ReindexConsumer
kag.graph.exchangeTopickb-aikag.graph.build.queue.{id}kag.graph.build.{id}.{all/by_ids} / kag.graph.delete.{id}kb-ai KAGReindexConsumer
transcode.exchangeDirectkb-filetranscode.queue.{id}transcode.{id}kb-file TranscodeConsumer
kb.operationlog.exchangeTopickb-foundationkb.operationlog.queue.{id}operationlog.{id}.#kb-foundation OperationLogMQListener
kb.config.exchangeDirectkb-foundationkb.config.queue.{id}config.{id}.updatekb-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 消息类目

消息类型包路径声明处消费处
ReviewEventDTOkb-common/.../event/kb-documentkb-foundation
StatisticsEventDTOkb-common/.../event/kb-documentkb-statistics
OperationLogEventDTOkb-common/.../event/kb-common (AOP)kb-foundation
ReindexMessagekb-ai/.../mq/kb-aikb-ai
KAGReindexMessagekb-ai/.../mq/kb-aikb-ai
TranscodeMessagekb-file/.../consumer/kb-filekb-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 降级层级

图片.png

9.2 各通道容错机制

通道故障场景降级行为
Feign目标服务不可达FallbackFactory 返回 null / 空列表
Feign连接超时5 秒超时,记录错误日志
RabbitMQBroker 不可达降级为同步执行(如 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();
    }
}

总结

  1. 双通道互补:Feign 用于需要即时响应的查询(获取文档内容、验证Token),RabbitMQ 用于异步事件通知(审核、统计、日志)。两类通信场景各得其所。
  2. Nacos 配置中心:所有服务的核心配置(数据库连接、RabbitMQ 地址、LLM API Key)通过 optional:nacos: 外部化,配置变更无需重启。
  3. 零代码多开发者隔离:InstanceIdentifier 三阶降级(配置 > hostname > UUID) + Nacos 分组 + MQ 动态队列/路由键,新开发者 clone 代码即可启动,无需任何配置修改。
  4. 消息传输可靠:持久化 + Publisher Confirms + Mandatory + 手动 ACK + 死信队列,五道防线确保消息不丢失。
  5. 类型安全反序列化:DefaultClassMapper 白名单防止反序列化漏洞,每个服务仅反序列化自己信任的包。
  6. 优雅降级:Feign 有 FallbackFactory 返回降级结果,MQ 发布失败有同步兜底,Gateway 有白名单放行关键路径。
  7. Gateway WebSocket 支持:lb:ws://kb-foundation 路由 + StripPrefix=0,WebSocket 长连接通过 Gateway 无感透传。

适用场景

此跨服务通信架构适用于:

  • 中等规模微服务:9 个服务,服务间有明确依赖关系
  • 同步+异步混合场景:既有即时查询也有异步事件通知
  • 多开发者并行开发:需要环境隔离且零配置启动
  • 对消息可靠性有要求:审核、统计等数据不能丢失
最后修改:2026 年 10 月 24 日
如果觉得我的文章对你有用,请随意赞赏