Seata：超详细部署与使用教程

Apache Seata（incubating，原名 Fescar，Simple Extensible Autonomous Transaction Architecture）是一款开源的分布式事务解决方案，致力于为微服务架构提供高性能且简单易用的分布式事务服务，提供 AT、TCC、SAGA、XA 四种事务模式。它由阿里巴巴与蚂蚁金服联合贡献，2023 年 10 月进入 Apache 孵化器。

目录

• 一、项目概述
• 二、环境要求
• 三、部署方式
• 四、使用方法
• 五、常见问题排查（FAQ）
• 六、部署注意事项与最佳实践
• 七、参考资料

一、项目概述

1.1 项目定位

在传统单体应用中，多个业务模块共享一个本地数据源，数据一致性由本地事务（ACID）保证。而在微服务架构下，「下单→扣库存→扣账户」这类业务被拆到三个服务、三个独立数据库中，每个服务的本地事务只能保证自己内部一致，跨服务的整体一致性就需要分布式事务框架来解决。

Seata 就是为解决这个问题而生的：它定义了一套「全局事务」框架，把一批本地事务组合成一个全局事务，由协调器统一驱动全局提交或回滚。其技术渊源包括阿里巴巴的 TXC/GTS 与蚂蚁金服的 XTS/DTX，2019 年以 Fescar 开源、后改名 Seata，2023 年 10 月进入 Apache 孵化器（Apache Seata (incubating)）。

1.2 核心功能

• AT 模式（Automatic Transaction）：无侵入的自动补偿模式。一阶段拦截业务 SQL、反向生成回滚日志（undolog）并提交本地事务；二阶段全局提交时异步清理 undolog，全局回滚时用 undolog 反向恢复数据。适合绝大多数关系型数据库、业务无侵入场景。
• TCC 模式（Try-Confirm-Cancel）：业务侧自己实现 Try（资源预留）、Confirm（确认）、Cancel（取消）三个接口，Seata 负责二阶段调度。适合对性能要求高、需要精细控制资源的场景。
• SAGA 模式：长事务/编排模式，每个参与者本地事务正向提交，失败时按反向补偿顺序执行。适合跨多团队、流程长的业务编排（官方提供 Saga 设计器）。
• XA 模式：基于数据库 XA 协议的强一致两阶段提交，依赖数据库驱动支持（MySQL XA 等）。
• 三种核心角色：TC（Transaction Coordinator，事务协调器，独立部署的 Seata Server）、TM（Transaction Manager，管理全局事务的开始/提交/回滚）、RM（Resource Manager，管理分支本地事务的资源管理器）。
• 多存储模式：TC 的会话存储支持 file（单机）、db（MySQL）、redis、raft（集群高可用）。
• 注册中心与配置中心集成：支持 Nacos、Eureka、Consul、ZooKeeper、Redis、Etcd 等（以官方文档为准）。
• 微服务框架生态：Spring Cloud、Dubbo、Motan、gRPC 等均有适配；Go 语言客户端 seata-go。

1.3 技术架构

下图是 Seata 官方文档给出的架构：Business 服务作为 TM 发起全局事务；Stock / Order / Account 三个服务作为 RM，各自管理分支本地事务；所有分支事务向右侧的 TC 注册并受其调度。

一个典型的分布式事务生命周期（官方文档描述）：

1. TM 向 TC 请求开启一个新的全局事务，TC 生成代表全局事务的 XID；
2. XID 随微服务调用链传递下去；
3. 各 RM 将本地事务注册为该 XID 对应全局事务的分支事务；
4. TM 请求 TC 提交或回滚该 XID 的全局事务；
5. TC 驱动该全局事务下的所有分支完成提交或回滚。

下图是 AT 模式官方示例：tx1 先拿本地锁+全局锁执行 UPDATE 并本地提交、释放本地锁；tx2 的 SELECT ... FOR UPDATE 请求全局锁时被阻塞重试，直到 tx1 全局回滚释放全局锁后拿到——AT 模式通过全局锁写隔离。

二、环境要求

注意：file 模式仅用于测试，全局事务会话存储在单节点内存，重启丢失且无法高可用；生产必须使用 db 模式 + 多节点，或 raft 集群模式。

三、部署方式

Seata 部署分两部分：① Server（TC）端部署；② 业务客户端集成。下面给出：Server 压缩包直接部署（file 模式最快上手）→ db 模式生产部署 → Docker 部署 → 客户端 Spring Boot 集成。

3.1 方式一：Server 压缩包直接部署（file 模式，最快上手）

步骤 1：下载 Server 压缩包

从官方 Release 页下载：github.com/apache/incubator-seata/releases，最新版本 v2.6.0（以实际 release 为准），产物形如 seata-server-2.6.0.tar.gz。

cd /opt
wget https://github.com/apache/incubator-seata/releases/download/v2.6.0/seata-server-2.6.0.tar.gz
tar zxvf seata-server-2.6.0.tar.gz
cd seata-server

步骤 2：（可选）修改配置

file 模式无需改动即可启动。配置文件位于 conf/application.yml（2.x 版本；1.x 版本为 registry.conf，以官方文档为准）。

步骤 3：启动 Server

按官方「部署指南-新人文档」给出的标准启动命令：

sh bin/seata-server.sh -h 127.0.0.1 -p 8091 -m file

参数说明：

Windows 下使用 bin/seata-server.bat。

步骤 4：验证启动成功

# 查看日志，出现 Server started 相关信息即成功
tail -f logs/seata_server.log

# 端口监听确认
netstat -tlnp | grep 8091

3.2 方式二：db 模式生产部署（MySQL + Nacos）

步骤 1：初始化全局事务表

Seata Server 自身的会话存储需要数据库。官方提供建表脚本（在 script/server/db/ 目录或官方文档「部署」章节给出，MySQL 版本），在专用库中执行：

CREATE DATABASE seata DEFAULT CHARACTER SET utf8mb4;
USE seata;
-- 执行官方 mysql.sql 建表脚本（global_table / branch_table / lock_table / distributed_lock）
SOURCE mysql.sql;

具体表名与脚本位置以官方文档 v2.6「部署 → 直接部署」为准。

步骤 2：修改 application.yml

编辑 conf/application.yml，将存储模式改为 db，并复制 conf/application.example.yml 中的 store.db 配置段到 application.yml：

store:
  mode: db
  db:
    datasource: druid
    db-type: mysql
    driver-class-name: com.mysql.cj.jdbc.Driver
    url: jdbc:mysql://127.0.0.1:3306/seata?useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai
    user: root
    password: 你的数据库密码

同时在 application.yml 中配置注册中心（Nacos），让客户端能自动发现 Server：

registry:
  type: nacos
  nacos:
    server-addr: 127.0.0.1:8848
    application: seata-server
    # group / namespace 等以官方文档为准

步骤 3：启动多节点

每台 Server 节点均执行：

sh bin/seata-server.sh -h 0.0.0.0 -p 8091 -m db

db 模式下多节点共享同一个 MySQL 存储，天然支持高可用；也可使用官方 raft 集群模式（有专门部署文档）。

3.3 方式三：Docker 部署

官方提供 Docker 镜像（详见官方文档「部署 → Docker 部署」，镜像名以官方为准）：

docker run --name seata-server \
  -p 8091:8091 \
  -e SEATA_IP=127.0.0.1 \
  -e SEATA_PORT=8091 \
  -e STORE_MODE=file \
  seataio/seata-server:latest

生产环境建议固定 tag（对应具体 release 版本），并通过挂载 -v 替换 application.yml，或用环境变量覆盖存储/注册配置（以官方文档为准）。

3.4 方式四：业务客户端 Spring Boot 集成

步骤 1：引入依赖（官方 README 给出，2.x 坐标）

<properties>
  <seata.version>2.5.0</seata.version>
</properties>

<dependencies>
  <!-- Spring Boot 项目直接使用 starter（已包含 seata-all） -->
  <dependency>
    <groupId>org.apache.seata</groupId>
    <artifactId>seata-spring-boot-starter</artifactId>
    <version>${seata.version}</version>
  </dependency>
</dependencies>

注意：进入 Apache 孵化器后，groupId 由 io.seata 变为 org.apache.seata；1.x 老版本为 io.seata:seata-all。客户端版本需与 Server 版本匹配（以官方版本兼容说明为准）。

步骤 2：配置 application.yml

seata:
  enabled: true
  # 事务分组名，需与 TC 端配置的 vgroup-mapping 对应
  tx-service-group: my_test_tx_group
  service:
    vgroup-mapping:
      my_test_tx_group: default   # 事务分组映射到集群名 default
  registry:
    type: nacos
    nacos:
      server-addr: 127.0.0.1:8848
  # AT 模式自动代理数据源
  enable-auto-data-source-proxy: true
  data-source-proxy-mode: AT

步骤 3：发起全局事务

在需要跨服务一致性的方法上加 @GlobalTransactional：

@Service
public class OrderService {

    @GlobalTransactional(name = "create-order-tx", rollbackFor = Exception.class)
    public void createOrder(Order order) {
        // 1. 本地建单
        orderDao.insert(order);
        // 2. 远程扣库存（Feign/Dubbo），XID 自动随调用链传递
        stockClient.deduct(order.getSku(), order.getCount());
        // 3. 远程扣账户余额
        accountClient.debit(order.getUserId(), order.getMoney());
        // 任何一步抛异常，整个全局事务自动回滚
    }
}

3.5 验证部署成功（通用）

1. Seata Server 日志出现 Server started，8091 端口监听正常；
2. 客户端启动日志中能看到注册到 Nacos 的 seata-server，并打印 Seata began 类信息；
3. 调用 @GlobalTransactional 方法后人为让第三阶段抛异常，检查三个服务的数据库：订单、库存、账户数据均被回滚到执行前状态。

3.6 关键配置说明

四、使用方法

4.1 基础用法

最简单的上手就是：启动 Seata Server（file 模式）→ 业务应用引入 starter 并配置事务分组 → 在跨服务入口方法加 @GlobalTransactional。XID 通过 RPC 上下文自动在调用链中传递，各分支 RM 自动向 TC 注册。

4.2 常用 API / 注解

全局事务注解

@GlobalTransactional(
    name = "order-service-tx",
    timeoutMills = 60000,        // 全局事务超时
    rollbackFor = Exception.class // 回滚异常范围
)
public void businessMethod() { ... }

TCC 模式接口定义

@LocalTCC
public interface AccountTccService {
    @TwoPhaseBusinessAction(name = "debitTcc", commitMethod = "commitTcc", rollbackMethod = "cancelTcc")
    boolean debitTry(BusinessActionContext ctx, @BusinessActionContextParameter(paramName = "userId") String userId,
                     @BusinessActionContextParameter(paramName = "money") BigDecimal money);

    boolean commitTcc(BusinessActionContext ctx);
    boolean cancelTcc(BusinessActionContext ctx);
}

4.3 进阶功能

• 四种模式选型：普通业务库写入默认 AT；高并发、需显式资源预留选 TCC；长流程编排选 SAGA（官方提供 Saga 设计器可视化编排）；要求数据库层强一致选 XA。
• 事务分组：通过 tx-service-group + vgroup-mapping 实现多套事务环境隔离（dev/test/prod 映射到不同 TC 集群）。
• 高可用部署：db 模式多节点共享 MySQL，或 raft 集群模式（官方专门文档）。
• 客户端隔离：@GlobalLock 控制 AT 模式的写隔离行为；防悬挂、空回滚问题由框架自动处理。
• 控制台：2.x 提供 Seata 控制台（官方文档「控制台」章节），可查看全局事务/分支事务状态。
• Seata CLI：官方提供 seata-ctl 运维命令行工具。

4.4 适用场景

• 微服务跨库业务一致性（下单-扣库存-扣款）；
• 金融级要求最终一致的支付、账务流程（TCC/SAGA）；
• 数据强一致要求的报表、对账场景（XA）；
• 替换传统两阶段提交、降低业务侵入的分布式事务治理。

五、常见问题排查（FAQ）

Q1：客户端启动报 no available service 'default' found - 原因：tx-service-group 映射的集群名在 TC 注册中心里不存在，或客户端/Server 注册中心配置不一致（namespace、group、cluster 名对不上）。 - 解决：对齐 Nacos 中的 namespace、group；确认 vgroup-mapping 的 value 与 Server 注册的 cluster 名一致。

Q2：AT 模式回滚时报 Branch Rollback Failed / 反向 SQL 失败 - 原因：一阶段本地提交后，业务表被其他事务修改，导致 undolog 无法反向恢复（脏写）。 - 解决：检查并发写入；官方建议业务表有主键并保持 AT 全局锁隔离；查看 undo_log 表数据。

Q3：file 模式重启后正在进行的全局事务丢失 - 原因：file 模式会话在内存，这是测试模式的限制。 - 解决：生产切 db 模式（MySQL 持久化）或 raft 集群模式。

Q4：远程调用方没有回滚，本地回滚了（XID 未传递） - 原因：RPC 框架（Feign/Dubbo）没有集成 Seata 传递拦截器，或自定义线程池导致 XID 上下文丢失。 - 解决：确认使用官方对应框架的适配 starter；异步/线程池场景使用 RootContext.bind 手动传递 XID。

Q5：启动报 Could not open JDBC Connection 或建表脚本缺失 - 原因：db 模式未在 Server 库执行官方建表脚本。 - 解决：按官方文档执行 global_table / branch_table / lock_table / distributed_lock 建表脚本。

Q6：全局事务长时间不结束，分支挂起 - 原因：全局事务超时时间设置过长，或某分支服务宕机未注册完成。 - 解决：查看 Seata 控制台中全局事务状态；合理设置 timeoutMills；检查 TC 与 RM 网络连通性。

Q7：Maven 依赖找不到 org.apache.seata - 原因：老版本坐标是 io.seata。 - 解决：2.x 孵化器版本用 org.apache.seata:seata-spring-boot-starter；1.x 老项目仍用 io.seata。

六、部署注意事项与最佳实践

1. 生产禁用 file 模式：必须 db（MySQL）或 raft 集群；Server 节点至少 2 个。
2. 版本对齐：TC 与客户端 seata-spring-boot-starter 版本尽量一致；跨大版本升级先读官方「版本升级指南」。
3. 事务分组规划：按环境（dev/test/prod）配置不同 tx-service-group 映射到不同 TC 集群，避免互相污染。
4. AT 模式要求：业务表必须有主键；开启 enable-auto-data-source-proxy；undolog 表会自动生成（官方 AT 拦截）。
5. 超时与回滚范围：@GlobalTransactional(timeoutMills) 按业务链路 RT 合理设置；rollbackFor = Exception.class 避免只回滚 RuntimeException。
6. 监控与告警：接入 Seata 提供的 Metrics（官方「应用性能监控」文档），关注失败分支数。
7. 数据库账号权限：db 模式下 Seata 库账号需有建表/读写权限；业务库账号需有对应业务权限。
8. 不要在公网暴露 8091：Seata Server 是内部协调组件，只允许内网业务应用访问。

七、参考资料

• GitHub 仓库（原）：https://github.com/seata/seata
• GitHub 仓库（Apache 孵化器）：https://github.com/apache/incubator-seata
• 官方文档首页：https://seata.apache.org/zh-cn/docs/overview/what-is-seata
• 新手部署指南：https://seata.apache.org/zh-cn/docs/ops/deploy-guide-beginner
• 直接部署（db/redis）：https://seata.apache.org/zh-cn/docs/ops/deploy-server
• Docker / K8s / Helm 部署：官方文档「部署」章节
• Release 下载：https://github.com/apache/incubator-seata/releases
• Go 客户端：https://github.com/apache/incubator-seata-go
• 示例工程：https://github.com/apache/incubator-seata-samples
• Seata 术语表：https://seata.apache.org/zh-cn/docs/overview/seata-atom