0. 前言

在将微服务架构升级到 Spring Boot 3.5.0 和 Spring Cloud Alibaba 2025.0.0.0 时，集成 Apache Seata 2.5.0 会遇到许多版本兼容性导致的“幽灵报错”。本文记录了从服务端启动到客户端配置的全过程坑点及解决方案。

1. 依赖冲突：新旧坐标之争

坑点描述： 启动时报错 Annotation-specified bean name 'sagaAsyncThreadPoolProperties' conflicts。
原因： spring-cloud-starter-alibaba-seata 默认可能引入了旧版 io.seata，而手动引入了 org.apache.seata，导致 Bean 定义冲突。

解决方案：
在根 POM 中强力排除旧包，统一使用 Apache 官方新坐标。

<dependency>
    <groupId>com.alibaba.cloud</groupId>
    <artifactId>spring-cloud-starter-alibaba-seata</artifactId>
    <exclusions>
        <exclusion>
            <groupId>io.seata</groupId>
            <artifactId>*</artifactId>
        </exclusion>
    </exclusions>
</dependency>
<dependency>
    <groupId>org.apache.seata</groupId>
    <artifactId>seata-spring-boot-starter</artifactId>
    <version>2.5.0</version>
</dependency>

2. Seata Server (服务端) 启动闪退

坑点描述： 双击 seata-server.bat 瞬间关闭，或报 Could not resolve placeholder 'console.user.username'。
原因： Seata 2.x 引入了严格的安全加固，强制要求在 application.yml 中配置控制台用户、JWT 密钥和日志路径。

保姆级 conf/application.yml 配置：

server:
  port: 7091                   # 控制台端口（避开网关的8080）
spring:
  application:
    name: seata-server
logging:
  file:
    path: logs/seata.log        # 必须指定，否则报错
  config: classpath:logback-spring.xml
console:
  user:
    username: seata            # 必须配置
    password: seata
seata:
  security:
    secretKey: "your_random_secret_key_here" # 必须配置，用于JWT签名
    tokenValidityInMilliseconds: 86400000
  store:
    mode: db                   # 推荐使用db模式
    db:
      driver-class-name: com.mysql.cj.jdbc.Driver
      url: jdbc:mysql://127.0.0.1:3306/seata?useUnicode=true&characterEncoding=utf-8
      user: root
      password: your_password
  registry:
    type: nacos
    nacos:
      server-addr: 127.0.0.1:8848
      group: SEATA_GROUP
      namespace: your_namespace_id

3. 客户端配置：vgroupMapping 找不到

坑点描述： 微服务启动报错 service.vgroupMapping.default_tx_group configuration item is required。
原因：

1. 加载顺序：Spring Boot 3.x 加载配置太晚，Seata 引擎初始化时还没读到嵌套在 spring.cloud 下的属性。
2. 默认值：Seata 引擎默认寻找 default_tx_group，若本地配置没对上则报错。

解决方案（顶级属性注入）：
在微服务的 application-dev.yml 中，将 seata: 配置提升为 顶级配置，不嵌套在 spring: 下。

spring:
  cloud:
# 顶级配置，确保启动初期就能被读到
seata:
  enabled: true
  application-id: ${spring.application.name}
  tx-service-group: default_tx_group # 建议直接使用默认名
  service:
    vgroup-mapping:
      default_tx_group: default      # 强制映射到seata-server的cluster名
  registry:
    type: nacos
    nacos:
      server-addr: 127.0.0.1:8848
      group: SEATA_GROUP
      namespace: your_namespace_id
  config:
    type: file                       # 建议先用file模式，避开Nacos格式解析问题
  data-source-proxy-mode: AT

4. Nacos 配置中心的“格式陷阱”

坑点描述： 在 Nacos 创建了 seata.properties 却不生效。
原因： Nacos 配置文件的 Config Type 必须选择 Properties。如果选成 Text，Seata 无法将其解析为 Map。

正确配置方式：

• Data ID: seata.properties

• Group: SEATA_GROUP

• Format: Properties

• Content:

  service.vgroupMapping.default_tx_group=default
  service.default.grouplist=127.0.0.1:8091