跳到主要内容

seata-client.yaml

seata-client.yaml 用于配置 Seata 2.0.0 分布式事务客户端，让业务微服务找到 Seata Server，完成跨服务事务的提交和回滚。

一、需要修改的配置​

部署时主要核对 Nacos 注册信息和事务组映射。重试、锁、回滚日志及线程参数通常保留交付值，无需逐项调整。

配置位置需要填写或核对的内容
seata.registry.nacos.server-addrSeata Server 注册使用的实际 Nacos 地址，例如 192.168.1.10:8848
seata.registry.nacos.username、password访问该 Nacos 环境的实际账号和密码
seata.registry.nacos.namespace与 Seata Server 所在 Namespace 一致；public 使用空字符串，自定义环境填写 Namespace ID
seata.registry.nacos.group与 Seata Server 注册的 Group 一致；沿用交付配置时为 SEATA_GROUP
seata.registry.nacos.application与 Nacos 中 Seata Server 的注册服务名一致；沿用交付配置时为 seata-server
seata.tx-service-group业务事务组名称；沿用交付配置时保留 shop-group
seata.service.vgroup-mapping.shop-group键名与上方事务组一致，值与 Seata Server 的 TC 集群名称一致；沿用交付配置时为 default

如果事务组从 shop-group 改为其他名称，vgroup-mapping 下的键也要同步修改。Nacos Group、业务事务组和 TC 集群名称是不同配置，不要混用。

application-id 保留应用名称占位符，由各服务自动生成；AT 模式还需确认参与事务的业务库已初始化 undo_log 表。此文件配置的是业务客户端，不能代替 Seata Server 自身的注册和存储配置。

二、配置示例​

seata:
  enabled: true
  application-id: ${spring.application.name}-seata
  tx-service-group: shop-group
  enable-auto-data-source-proxy: true
  client:
    rm:
      report-success-enable: true
      table-meta-check-enable: false
      report-retry-count: 5
      async-commit-buffer-limit: 10000
      lock:
        retry-interval: 10
        retry-times: 30
        retry-policy-branch-rollback-on-conflict: true
    tm:
      commit-retry-count: 3
      rollback-retry-count: 3
    undo:
      data-validation: true
      log-serialization: jackson
      log-table: undo_log
  log:
    exception-rate: 100
  service:
    vgroup-mapping:
      shop-group: default
    enable-degrade: false
    disable-global-transaction: false
  transport:
    shutdown:
      wait: 3
    thread-factory:
      boss-thread-prefix: NettyBoss
      worker-thread-prefix: NettyServerNIOWorker
      server-executor-thread-prefix: NettyServerBizHandler
      share-boss-worker: false
      client-selector-thread-prefix: NettyClientSelector
      client-selector-thread-size: 1
      client-worker-thread-prefix: NettyClientWorkerThread
    type: TCP
    server: NIO
    heartbeat: true
    serialization: seata
    compressor: none
    enable-client-batch-send-request: true
  registry:
    type: nacos
    nacos:
      application: seata-server
      server-addr: shoptnt-nacos:8848
      group: SEATA_GROUP
      namespace: ""
      username: "Nacos用户名"
      password: "Nacos密码"

shoptnt-nacos:8848 是容器网络内的地址示例。使用源码部署或跨服务器部署时，应替换为业务服务能够访问的实际 Nacos 地址，并填写实际账号和密码。

三、启用事务与应用标识​

配置项示例值说明
enabledtrue启用 Seata 客户端自动配置
application-id${spring.application.name}-seata客户端应用标识，例如商品服务为 goods-service-seata
tx-service-groupshop-group业务事务组名称，用于查找该组对应的 TC 集群
enable-auto-data-source-proxytrue启用 Seata 数据源自动代理；AT 模式需要业务 SQL 通过相应的数据源代理执行

启用客户端并不等于所有业务操作都会自动成为全局事务，实际事务范围还取决于程序中的事务入口和调用链路。

四、事务组与 TC 集群映射​

seata:
  tx-service-group: shop-group
  service:
    vgroup-mapping:
      shop-group: default

这段配置表示：业务服务使用事务组 shop-group，该事务组映射到名为 default 的 TC 集群。

配置位置对应关系
tx-service-group 的值必须与 vgroup-mapping 下的键一致，本例均为 shop-group
vgroup-mapping.shop-group 的值必须与 Seata Server 注册到 Nacos 时使用的集群名称一致，本例为 default
registry.nacos.application必须与 Seata Server 在 Nacos 中注册的服务名一致，本例为 seata-server

各应用可以共用同一个事务组，也可以使用不同事务组。使用不同名称时，需要为每个事务组配置对应映射；不能只修改 tx-service-group 而保留原映射键。

事务组、TC 集群和 Nacos Group 是三个不同概念：

  • shop-group：业务事务组。
  • default：事务组映射的 TC 集群名称。
  • SEATA_GROUP：Seata Server 在 Nacos 中注册服务使用的 Group。

映射查找过程可参考 Seata 事务分组说明。

服务开关​

配置项示例值说明
service.enable-degradefalse保留当前交付配置；不要将其等同于 Sentinel 的熔断降级规则
service.disable-global-transactionfalse不禁用全局事务；设置为 true 表示禁用全局事务

五、通过 Nacos 查找 Seata Server​

seata:
  registry:
    type: nacos
    nacos:
      application: seata-server
      server-addr: shoptnt-nacos:8848
      group: SEATA_GROUP
      namespace: ""
      username: "Nacos用户名"
      password: "Nacos密码"
配置项说明修改要求
typeSeata 注册中心类型当前使用 nacos
applicationTC 在 Nacos 中注册的服务名与 Seata Server 实际注册名称一致
server-addrNacos 地址替换为实际主机与端口
groupTC 注册服务所属的 Group与 Seata Server 注册信息一致，本例为 SEATA_GROUP
namespaceTC 注册服务所属的 Namespace ID空字符串表示 public；自定义环境填写实际 Namespace ID，不是显示名称
username、password访问 Nacos 的账号和密码使用有权读取对应服务信息的实际账号

此处是 Seata 查找 TC 使用的注册信息，不会因为 common.yaml 中配置过 Nacos 就自动省略。客户端与 Seata Server 的注册中心地址、Namespace、Group、服务名和集群名称应相互对应。

通过 Nacos 找到实例后，业务服务还需要能够访问 TC 的实际事务通信地址。Nacos 的 8848 端口不是 TC 的事务通信端口，网络检查时应同时确认 TC 实例返回的地址与端口可达。

六、RM 与全局锁​

RM（资源管理器）负责管理业务数据库等事务资源，以及分支事务的注册、提交和回滚。

分支事务与元数据​

以下参数位于 seata.client.rm 下：

配置项示例值说明
report-success-enabletrue是否向 TC 上报一阶段分支事务执行成功的状态
table-meta-check-enablefalse表结构元数据检查开关，按交付配置设置；数据库表结构变更后应检查缓存元数据是否已更新
report-retry-count5分支事务一阶段结果向 TC 上报失败时的重试次数
async-commit-buffer-limit10000异步提交缓冲队列容量，影响 AT 模式二阶段异步提交清理任务的积压能力

全局锁重试​

以下参数位于 seata.client.rm.lock 下：

配置项示例值说明
retry-interval10校验或获取全局锁时的重试间隔，单位毫秒
retry-times30校验或获取全局锁时的重试次数
retry-policy-branch-rollback-on-conflicttrue与其他全局回滚事务发生锁冲突时，优先释放本地锁，使对方回滚有机会完成

这些参数控制锁冲突时的等待与重试，不是业务请求的整体超时时间，也不会自动解决长期持锁或高并发热点带来的冲突。

七、TM 提交与回滚重试​

TM（事务管理器）负责发起全局事务，并请求 TC 执行全局提交或回滚。

以下参数位于 seata.client.tm 下：

配置项示例值说明
commit-retry-count3向 TC 发起全局提交请求失败时的重试次数
rollback-retry-count3向 TC 发起全局回滚请求失败时的重试次数

这里的重试不是重新执行整笔业务，也不代表可以无限重试业务接口。重试次数应结合事务超时和实际网络情况调整。

八、回滚日志与异常日志​

Undo Log​

以下参数位于 seata.client.undo 下，主要用于 AT 模式：

配置项示例值说明
data-validationtrue二阶段回滚时进行数据镜像校验，检查是否存在与预期不一致的数据变化
log-serializationjacksonUndo Log 数据的序列化方式
log-tableundo_log业务数据库中用于保存回滚日志的表名

参与 AT 分支事务的业务数据库需要包含与当前 Seata 版本匹配的 undo_log 表。仅填写表名不会自动建表，部署前应检查初始化脚本是否已执行。

业务库里的 undo_log 与 TC 自身的事务存储表用途不同，不能只初始化 Seata Server 的数据库就认为业务库已具备回滚条件。

异常堆栈采样​

seata:
  log:
    exception-rate: 100

该参数用于 Seata 特定异常堆栈的采样输出。按当前 2.0.0 实现，100 对应约 1/100 的堆栈输出概率，不表示 100%，也不是所有应用日志的统一输出开关。

九、通信与线程参数​

通信协议​

以下参数位于 seata.transport 下：

配置项示例值说明
typeTCP客户端与 TC 的通信类型
serverNIO网络通信实现类型
heartbeattrue启用心跳检测
serializationseata通信消息序列化方式，应与服务端兼容
compressornone不启用消息压缩
enable-client-batch-send-requesttrue启用客户端请求批量合并发送配置
shutdown.wait3通信模块关闭时的等待时间，单位秒

线程工厂​

以下参数位于 seata.transport.thread-factory 下：

配置项示例值说明
boss-thread-prefixNettyBossBoss 线程名称前缀
worker-thread-prefixNettyServerNIOWorker服务端 NIO Worker 线程名称前缀
server-executor-thread-prefixNettyServerBizHandler服务端业务处理线程名称前缀
share-boss-workerfalse不共享 Boss 和 Worker 线程资源
client-selector-thread-prefixNettyClientSelector客户端 Selector 线程名称前缀
client-selector-thread-size1客户端 Selector 线程数量
client-worker-thread-prefixNettyClientWorkerThread客户端 Worker 线程名称前缀

线程前缀主要用于识别日志和线程信息。服务端相关参数在客户端配置中保留，不代表需要启动额外的 Seata Server。常规部署可沿用交付值，无需因修改数据库地址而一并调整。

十、发布与验证​

  1. 在当前业务环境对应的 Nacos Namespace、Group 中修改并发布 seata-client.yaml，确认需要使用事务的服务加载了该配置。
  2. 在 Nacos 服务列表中确认 seata-server 已注册，核对其 Namespace、Group、集群名称及实际通信地址。
  3. 确认 tx-service-group 与映射键一致，映射值与 TC 集群名称一致。
  4. 检查需要参与 AT 事务的业务库中是否已创建正确的 undo_log 表，并确认数据源代理正常工作。
  5. 调整注册信息、事务组或数据源代理配置后，重启受影响的业务服务，检查是否存在 TC 查找失败、连接失败、分支注册失败等日志。
  6. 在测试环境验证跨服务业务的正常提交与异常回滚，确认相关业务数据符合预期；服务能启动、能注册到 Nacos 不等于分布式事务已验证通过。