有一次在模拟项目X里，订单服务已经调通了，库存服务也独立跑起来了，但联调时我发现一个很要命的现象：订单落库了，库存却没扣掉。等补偿任务处理完，用户那边已经看到超卖。当时第一反应是加本地事务，但一想这是两个独立数据库，本地事务根本管不到另一边。那次之后我就把 Spring Cloud Alibaba 生态里的 Seata + Nacos 这套分布式事务方案完整搭了一遍，从服务端到业务应用端都过了一遍，也踩了不少版本和配置的坑。这篇文章就是这次搭建的过程和经验，适合正在做微服务拆分、准备引入分布式事务的团队参考，也适合自己搭环境练手。
1. 为什么是Seata+Nacos：分布式事务选型的前因后果
1.1 跨服务数据一致性为什么难处理
单体应用时期，订单、库存、账户都在同一个数据库里，一个@Transactional就能保证要么全成功要么全失败。但拆成微服务之后，每个服务都有独立数据库，本地事务只能覆盖自己那一个库。跨库的原子性，从底层就没有天然支持。
我在模拟项目X里遇到的场景很典型：下单接口先插入订单记录，再调用库存服务扣减库存。订单库和库存库的数据一致性，靠链路里任何一方的本地事务都解决不了。订单服务本地事务提交之后，库存服务如果宕机、超时或者业务校验失败，订单数据已经写死了，数据就不一致了。
这种问题不像接口报错那么显眼，它更像“慢性病”：订单多了、库存少了、账对不上，等发现的时候已经积累了一大堆脏数据。所以微服务改造一旦涉及多个写库，分布式事务就是一个绕不开的基建问题。
1.2 主流方案里为什么选了AT模式
当时我对比了几种方案。XA由数据库层面协调，两阶段锁资源，性能损耗大，而且在互联网场景下，一个分布式事务里动辄跨多个库多个服务，数据库自带XA的协调器支持也参差不齐。TCC需要业务侵入式地写Try、Confirm、Cancel三套操作，代码量翻倍，维护成本很高。消息最终一致性对“实时强一致”的场景不适用，下单扣库存这种操作，用户不能接受“稍后重试”。
Seata的AT模式思路不太一样：它通过代理数据源拦截SQL，在执行业务SQL前生成一份“前镜像”，执行后再生成“后镜像”，连同分支事务信息一起写到每个业务库的undo_log表里。如果全局事务需要回滚，就按undo_log里的镜像数据反向补偿，把数据恢复到执行前。业务代码几乎不用改，只需要在事务入口加一个@GlobalTransactional注解。
这种“代理数据源 + 本地业务库反查日志”的做法，对开发团队来说侵入性最低。我在模拟项目X里验证之后，确认它适合大多数中小团队的落地节奏。
1.3 Nacos在整套方案里的角色
Seata本身可以独立部署，但在这套组合里，Nacos承担了三个关键职责。
第一是注册中心。Seata Server需要被客户端发现，Spring Cloud Alibaba的微服务之间也要通过Nacos找到对方。把Seata Server也注册进Nacos，客户端就能通过注册中心拿到TC地址，而不是在每台机器上手工维护一份TC的IP列表。
第二是配置中心。Nacos里可以存放客户端的公共配置和Seata服务端的配置。环境隔离、参数调整都在Nacos上改，不用逐台改文件再重启。Nacos和Spring Cloud Alibaba本来就是一家的产品，和Seata的兼容性也一直在迭代。
第三是统一基础设施。团队里本来就要为微服务部署Nacos，多加一套Nacos做配置和注册的维护成本比引入一个全新的中间件要小得多。
2. 事务分组机制拆解：先看透再动手
2.1 TC、TM、RM和一条全局事务链路
Seata里有三个角色，名字很拗口，但记住分工之后就很好懂。TC是事务协调器，就是部署的Seata Server。TM是事务管理器，业务里加了@GlobalTransactional注解的那个方法会向TC申请全局事务，拿到一个全局唯一的XID。RM是资源管理器，在每个参与事务的业务服务里，代理数据源会把本地事务注册成TC管理下的分支事务，并按TC的指令提交或回滚。
一次完整的调用流程是这样的：订单服务（TM）调用TC开始全局事务，拿到XID。XID通过微服务调用链路传递，订单服务调用库存服务时，Feign调用会自动在请求头里带XID，库存服务（RM）执行本地SQL时，Seata拦截器把XID记录到本地连接上下文，并在undo_log里生成镜像，再向TC注册分支事务。等TM这边的业务方法结束，TC再通知所有分支事务执行二阶段提交或回滚。
这整个链路里最容易忽略的地方是XID的传递。如果这边用了线程池、异步任务、MQ消费，XID不会自动传过去，分支事务就会变成“无主事务”。
2.2 vgroupMapping到底在做什么
这是我第一次搭建时最迷糊的地方，也是配置出错概率最高的点。Seata引入了一个“事务分组”的概念，它用来隔离不同业务线、不同环境，而不是直接把客户端暴露给TC实例。
举个例子。我在模拟项目X里，业务服务的配置是这样的：
spring: cloud: alibaba: seata: tx-service-group: order_tx_group这个order_tx_group就是事务分组名，它并不是TC的地址。它需要映射到一个TC集群名。接着配置：
seata: service: vgroup-mapping: order_tx_group: default grouplist: default: 127.0.0.1:8091这里表达的是：事务分组order_tx_group映射到名为default的TC集群，TC集群的地址是127.0.0.1:8091。如果在Nacos上开启，还可以不写grouplist，改成通过注册中心去发现名为seata-server的服务。
Seata服务端启动时，在registry.conf里也有一个集群名配置，默认也是default。客户端分组要映射到服务端的集群名，两边能对上线，客户端才能通过Nacos服务发现找到TC。我在模拟项目X里第一次就是因为服务端集群名没改，客户端映射到别的集群名，日志里一直在报no available service。
2.3 Nacos里的SEATA_GROUP和seataServer.properties
Nacos里能看到一个叫SEATA_GROUP的配置分组，Seata官方脚本里的config.txt导入以后，会生成一个seataServer.properties文件，里面是超时重试、提交重试、回滚重试等一系列客户端公共参数。
这个不是必须的，缺省不配也能跑起来，所有参数会走客户端 jar 包里的默认值。但等到服务多了，想在Nacos上统一调整重试参数，就会发现把公共配置放到Nacos里更省事。我建议是前期搭环境时可以不开，等确认事务链路通顺之后再把公共参数抽到配置中心。
需要注意SEATA_GROUP只是一个配置分组名称，不是Nacos的命名空间namespace。Nacos的namespace是环境隔离（dev、test、prod），而SEATA_GROUP只是配置文件的group，两者不要混。
3. 服务端部署：Nacos与Seata Server的配置联动
3.1 版本组合先定好，后面少踩一半坑
Seata的坑，至少有一半是版本不一致造成的。很多团队直接继承Spring Cloud Alibaba的依赖管理，结果Seata客户端版本和服务端版本对不上，启动后报协议解析错误、Unknown magic code，或者注册中心找不到服务。
我在模拟项目X里最终选定的组合，以及另外两个我用过较稳的组合，整理如下：
| 组合 | Spring Boot | Spring Cloud | Spring Cloud Alibaba | Seata | Nacos |
|---|---|---|---|---|---|
| 经典稳定组 | 2.3.12.RELEASE | Hoxton.SR12 | 2.2.6.RELEASE | 1.4.2 | 1.4.1 |
| 较新稳定组 | 2.4.13 | 2020.0.5 | 2021.0.1.0 | 1.4.2 | 1.4.2 |
| 高版本组 | 2.7.12 | 2021.0.3 | 2021.0.4.0 | 1.5.2 | 2.2.3 |
我这里重点说第一组：Spring Boot 2.3.12.RELEASE + Spring Cloud Alibaba 2.2.6.RELEASE + Seata 1.4.2 + Nacos 1.4.1。这是当时网上资料最多、社区踩坑记录最全的一套，我按这个组合一天内搭通了，后续换到别的版本也没有出现协议不兼容的问题。
3.2 初始化Seata数据库和业务库undo_log
Seata服务端如果要把事务状态持久化，需要建一个独立的数据库，官方建议命名为seata。在Seata安装目录的script/server/db/下有一个mysql.sql，里面包含三张表：global_table（全局事务表）、branch_table（分支事务表）、lock_table（全局锁表）。执行一遍就行。
业务数据库则每个参与事务的库都要建一张undo_log表，AT模式靠它做回滚。这张表和Seata服务端的表不同，它是放在业务库里的。建表SQL如下：
CREATE TABLE `undo_log` ( `id` bigint(20) NOT NULL AUTO_INCREMENT, `branch_id` bigint(20) NOT NULL, `xid` varchar(100) NOT NULL, `context` varchar(128) NOT NULL, `rollback_info` longblob NOT NULL, `log_status` int(11) NOT NULL, `log_created` datetime NOT NULL, `log_modified` datetime NOT NULL, PRIMARY KEY (`id`), UNIQUE KEY `ux_undo_log` (`xid`,`branch_id`) ) ENGINE=InnoDB AUTO_INCREMENT=1 DEFAULT CHARSET=utf8;我见过有人在两个服务共用一个数据库时，只在其中一个库建了表，结果回滚时另一个分支一直报Table 'undo_log' doesn't exist。只要参与事务，每个库都要建。
3.3 Seata Server的registry.conf和file.conf
Seata 1.4.2服务端的配置主要在两个文件：registry.conf和file.conf。
registry.conf控制注册中心和配置中心。要让Seata Server注册进Nacos，需要这样配置：
registry { type = "nacos" nacos { application = "seata-server" serverAddr = "127.0.0.1:8848" group = "SEATA_GROUP" namespace = "" cluster = "default" username = "nacos" password = "nacos" } } config { type = "file" }这里namespace = ""表示使用Nacos的public命名空间。如果Nacos开了命名空间隔离，比如把Seata放到seata-prod命名空间里，这里就必须填对应的namespace ID，而且后面客户端配置也要指向同一个namespace。
file.conf控制存储模式。默认是file模式，单机临时验证可以，但TC重启后事务状态可能丢。我建议直接配成db模式：
store { mode = "db" db { datasource = "druid" dbType = "mysql" driverClassName = "com.mysql.cj.jdbc.Driver" url = "jdbc:mysql://127.0.0.1:3306/seata?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai" user = "root" password = "root" minConn = 5 maxConn = 100 globalTable = "global_table" branchTable = "branch_table" lockTable = "lock_table" } }配置完启动：
sh bin/seata-server.sh -p 8091 -h 127.0.0.1-h是注册IP，机器多网卡时必须显式指定，否则会注册到一个别人访问不到的IP。
启动后去Nacos控制台服务列表，能看到seata-server服务，说明服务端注册成功。
3.4 服务端用Nacos做配置中心
Seata服务端也可以把配置放到Nacos，config.type改成nacos。这样store.mode、数据库连接等配置都能在Nacos上动态管理。
具体做法是把官方脚本script/config-center/config.txt里的配置项整理成KV，导入Nacos，dataId设为seataServer.properties，groupId设为SEATA_GROUP。导入之后，Seata Server启动时会从Nacos拉这份配置。
但这一步不是必须的。模拟项目X初期我保持config.type = "file"，在本地文件里维护，等基础链路跑通后才切到Nacos配置中心。先跑通再上配置中心，排查问题会简单很多。
4. 业务应用接入：从依赖到数据源代理的一次完整改造
4.1 依赖里最容易踩的内嵌版本坑
业务服务引入Seata时，我们通常会用Spring Cloud Alibaba的starter。但要注意，spring-cloud-starter-alibaba-seata内部引入的seata-spring-boot-starter版本是由Spring Cloud Alibaba版本决定的，和服务端未必一致。
我在模拟项目X里第一次直接引入，没有管版本，结果客户端和服务端都是1.4.2吗？不是，SCA依赖管理里带的是它自己选定的版本，两边版本对不上，事务始终注册不到TC。后来改成排除内嵌版本，手动固定：
<dependency> <groupId>com.alibaba.cloud</groupId> <artifactId>spring-cloud-starter-alibaba-seata</artifactId> <exclusions> <exclusion> <groupId>io.seata</groupId> <artifactId>seata-spring-boot-starter</artifactId> </exclusion> </exclusions> </dependency> <dependency> <groupId>io.seata</groupId> <artifactId>seata-spring-boot-starter</artifactId> <version>1.4.2</version> </dependency>服务端和客户端版本保持一致，是分布式事务排错的第一原则。
4.2 业务服务的关键配置
在业务服务的配置文件里，需要同时有Nacos注册发现、Nacos配置中心、Seata三段配置。我提供一个最小可跑通的示例：
spring: application: name: order-service cloud: nacos: discovery: server-addr: 127.0.0.1:8848 namespace: public group: DEFAULT_GROUP config: server-addr: 127.0.0.1:8848 namespace: public file-extension: yaml alibaba: seata: tx-service-group: order_tx_group seata: enabled: true application-id: ${spring.application.name} service: vgroup-mapping: order_tx_group: default grouplist: default: 127.0.0.1:8091如果业务服务能通过Nacos服务发现找到TC，也可以把grouplist去掉，改为：
seata: registry: type: nacos nacos: application: seata-server server-addr: 127.0.0.1:8848 group: SEATA_GROUP cluster: default两种方式二选一。我更喜欢用grouplist直连，环境简单时排查链路更短。等环境多了再切换成注册中心方式。
4.3 数据源代理是回滚的大前提
客户端配置到位、依赖也对了，但如果数据源没有被Seata代理，undo_log里根本不会生成镜像数据，全局回滚也就无从谈起。
我用的是手动代理方式：
@Configuration public class SeataDataSourceConfig { @Bean @ConfigurationProperties(prefix = "spring.datasource") public DruidDataSource druidDataSource() { return new DruidDataSource(); } @Bean public DataSourceProxy dataSourceProxy(DataSource druidDataSource) { return new DataSourceProxy(druidDataSource); } @Bean public SqlSessionFactory sqlSessionFactory(DataSourceProxy dataSourceProxy) throws Exception { SqlSessionFactoryBean factoryBean = new SqlSessionFactoryBean(); factoryBean.setDataSource(dataSourceProxy); return factoryBean.getObject(); } }同时启动类上要排除原来的数据源自动配置：
@SpringBootApplication(exclude = {DataSourceAutoConfiguration.class}) public class OrderServiceApplication { public static void main(String[] args) { SpringApplication.run(OrderServiceApplication.class, args); } }如果用了dynamic-datasource-spring-boot-starter，就需要用DynamicDataSourceProxy去包装，直接套DataSourceProxy会导致动态数据源失效。这一点很重要，项目里一旦引入多数据源框架，数据源代理的方式要跟着变。
4.4 注解边界和事务入口
整个调用链路上，只有第一个发起全局事务的方法需要加@GlobalTransactional。下游参与方不用加，加了反而会开启新的全局事务，出现嵌套事务的混乱。
我在模拟项目X里的下单入口是这样写的：
@Service public class OrderServiceImpl implements OrderService { @Autowired private OrderMapper orderMapper; @Autowired private StorageFeignClient storageFeignClient; @Override @GlobalTransactional(rollbackFor = Exception.class) public void createOrder(String userId, String productId, Integer count) { Order order = new Order(); order.setUserId(userId); order.setProductId(productId); order.setCount(count); orderMapper.insert(order); storageFeignClient.deduct(productId, count); } }库存服务那边deduct方法只加普通的@Transactional，甚至不加也行，因为Seata的RM会自动接管分支事务。但为了分支本地事务边界清晰，建议保留@Transactional。
5. 一个下单扣库存示例：从正常流程到人为注入故障
5.1 表结构与服务划分
模拟项目X里我拆了两个服务。order-service操作order_db，表结构如下：
CREATE TABLE `t_order` ( `id` int(11) NOT NULL AUTO_INCREMENT, `user_id` varchar(64) DEFAULT NULL, `product_id` varchar(64) DEFAULT NULL, `count` int(11) DEFAULT NULL, PRIMARY KEY (`id`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8;storage-service操作storage_db，表结构如下：
CREATE TABLE `t_storage` ( `id` int(11) NOT NULL AUTO_INCREMENT, `product_id` varchar(64) DEFAULT NULL, `stock` int(11) DEFAULT NULL, PRIMARY KEY (`id`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8;两个库各自建了undo_log表。服务间通过OpenFeign调用，Feign的依赖要引入spring-cloud-starter-openfeign，同时启用@EnableFeignClients。
5.2 正常调用验证
启动Nacos、Seata Server、order-service、storage-service后，先验证正常链路。调用下单接口，传入一个商品ID和数量，然后去两个库查数据。
正常结果应该是：t_order新增一条记录，t_storage中对应商品库存减少。查看Seata Server日志，能看到分支事务提交的记录，类似branch commit或PhaseTwo_Committed的关键词。正常情况下undo_log表是空的，因为分支成功提交后，Seata会清除对应的undo日志。
这步通过，说明基础链路已经通了：Nacos注册没问题，Feign调用可以传递XID，分支事务能正常提交。
5.3 人为注入故障验证回滚
验证完正常提交，一定要验证回滚。我在createOrder里插入了一个故意抛出的异常，模拟“库存扣减完成但订单业务失败”的场景：
@Override @GlobalTransactional(rollbackFor = Exception.class) public void createOrder(String userId, String productId, Integer count) { Order order = new Order(); order.setUserId(userId); order.setProductId(productId); order.setCount(count); orderMapper.insert(order); storageFeignClient.deduct(productId, count); if (count > 2) { throw new RuntimeException("模拟订单服务业务异常"); } }调用这个接口，观察两边数据：t_order里新增的订单数据被回滚删除，t_storage里扣减的库存恢复原值。同时Seata Server日志中出现PhaseTwo_GlobalRollback或branch rollback的记录。
这里有个细节：如果回滚成功，undo_log表里的日志会被自动清理。如果你在回滚后还能在undo_log里看到残留记录，说明不是正常回滚流程走完的，多半是回滚过程中服务被重启、断连，或者TC没有通知到某个分支。
6. 高频踩坑复盘：注册不上、事务不生效、回滚不彻底的排查顺序
6.1 Seata Server注册不上或者客户端找不到TC
Seata Server启动后，Nacos服务列表里没有seata-server。排查顺序我建议是这样：
先看Seata Server日志有没有报Nacos连接失败，网络不通或者鉴权配置不对都会导致注册不上。再检查registry.conf里的serverAddr是否带http://前缀，1.4.2里不需要带，直接写127.0.0.1:8848。然后看namespace是否填了不存在的namespace ID，填了不存在的会注册到找不到的位置。最后看多网卡问题，-h参数必须指定能被客户端访问的IP。
如果Seata Server已经在Nacos里，客户端还是报no available service，那就检查客户端vgroup-mapping映射的集群名和服务端cluster是否一致。两边都叫default就完事，任何一边改了都要同步改。
6.2 全局事务不生效，日志里没有XID
@GlobalTransactional加了，但业务日志里从头到尾看不到XID信息，说明TM压根没有向TC发起全局事务。
优先检查seata.enabled是否为true，默认为true，但有时候配置覆盖会把它关了。然后确认事务注解加在了正确的位置，必须是Service层的public方法，同类内部调用和私有方法都不生效。再检查业务方法是否被Spring代理，如果类没有走Spring代理，注解自然无效。
还有一个场景容易被忽略：Feign调用时XID丢失。正常情况下Spring Cloud Alibaba的Feign集成会自动把XID放入请求头，但如果你在Feign拦截器里改了请求头，或者手动构造了新的Request，XID可能就丢了。排查办法是在库存服务入口的日志里看有没有XID，没有就是传输链路断了。
6.3 回滚不彻底或者根本不回滚
这个问题的排查优先级最高的是数据源是否被代理。很多团队配置都对，但数据源没走DataSourceProxy，SQL根本没被拦截，undo_log没生成镜像，TC想回滚也无从下手。
确认方法很简单，业务服务启动日志里看有没有Seata的数据源代理相关日志，或者在代码里把数据源对象打印出来看类型。另一个确认方式是执行一条会触发分支事务的SQL后，直接去业务库查undo_log表，如果里面没有任何记录，数据源代理基本没生效。
还有一点，分支服务调用如果走了原生的JDBC直连、MyBatis之外的框架，或者自己手动开了新连接，这些连接如果没有走Seata的代理数据源，也不会被纳入全局事务。我在模拟项目X里有一个定时任务就是绕过了代理，直接连库修改数据，结果全局回滚的时候那部分数据纹丝不动。
6.4 Nacos的namespace和group混乱
Nacos的namespace是物理隔离级别的，不同命名空间之间服务和配置互相不可见。Seata Server如果注册在dev命名空间，客户端也在dev，这没问题。但如果客户端是public，服务端是dev，两边不可能互相发现。
group则是在同一namespace内的逻辑分组。Seata相关配置默认放在SEATA_GROUP里，Nacos默认配置分组是DEFAULT_GROUP，两者不一样。我在练习时不小心把seataServer.properties导到了DEFAULT_GROUP，客户端用SEATA_GROUP拉取配置，一直拉不到。解决方式很简单，要么把文件放到正确的group，要么客户端配置里指定同一个group。
这里我整理了一个排查表，按优先级从高到低排列：
| 现象 | 可能性最大的原因 | 确认方式 |
|---|---|---|
| 客户端报no available service | vgroupMapping集群名不一致 | 对比服务端cluster和客户端vgroupMapping值 |
| 全局事务没有XID | 注解不在Spring代理方法上 | 查看入口日志是否有xid打印 |
| 回滚不彻底 | 数据源未被代理 | 查每个业务库undo_log是否有记录 |
| undo_log一直残留 | 回滚过程被中断 | 查TC日志看全局回滚是否完成 |
| 配置拉取不到 | Nacos的group不一致 | 对比配置所在group与客户端配置 |
6.5 版本兼容性问题
Seata各版本之间的客户端协议不完全兼容。常见场景是服务端是1.5.2，客户端还停留在1.4.2，启动后日志报Unknown magic code或者io.seata.common.exception.FrameworkException，这类错误基本都是版本不匹配。
我的习惯是建一个seata.version的Maven属性，在父POM统一维护，所有微服务模块都引用它。升级Seata时先升级服务端，再升级所有客户端的版本，并且跑一遍正常提交和人为回滚两条链路再上线。
版本升级到1.5.x之后，服务端的registry.conf不再是唯一配置方式，Seata 1.5+ 开始支持完全用application.yml配置。如果从1.4.x升上来，配置结构会有些变化，建议先看官方线上升级文档，不要直接用旧配置文件硬跑。
搭建这套东西，我前后调了两天，最大的体会是把事务分组机制先理解透再动手，比瞎配一堆参数有用得多。最后分享一个个人习惯：每次改动配置后不要直接跑业务，先看Nacos服务列表有没有seata-server，再看客户端启动日志里有没有打印加载的配置组和XID。这两条通了，再跑业务成功率高很多。如果你们的团队也是第一次接入，建议用一个模拟项目先练手，把正常提交和异常回滚两种路径都跑通，再上真实业务。分布式事务这东西，链路一旦通了，后面维护反而是顺手的。
