Apache Seata 2.6 配置参数详解
详解 Apache Seata 2.6.0 服务端 application.yml 与客户端全部配置参数：config/registry/server/store/metrics/transport 六大板块逐键说明默认值，附生产 db 模式配置模板与常见问题排查
Apache SeataSeata分布式事务Java2026/10/15
Apache Seata 2.6 配置参数详解
目标：逐键讲清 Apache Seata 2.6.0 的全部配置项——服务端
conf/application.yml的 config、registry、server、store、metrics、transport 六大板块，以及客户端（seata-spring-boot-starter）的事务组、undo_log、重试等核心参数。所有默认值均取自发行包内的application.example.yml与script/config-center/config.txt实测文件，配置生效方式均经真实启动验证。
一、环境信息
- 操作系统：Ubuntu 22.04（x86_64）
- Java：OpenJDK 17（seata-server 主程序支持 JDK 8~17；namingserver 控制台需 JDK 25+）
- Seata 版本：2.6.0（孵化器发行包
apache-seata-2.6.0-incubating-bin.tar.gz） - 安装目录：
/opt/seata/seata-server - 配置文件：
/opt/seata/seata-server/conf/application.yml - 数据库（db 存储模式）：MySQL 8，地址
seata-db:3306，库名seata，账号root/q1w2e3r4 - 端口：8091（TC 服务）、9898（Prometheus 指标导出，默认占用）
二、前置条件
本文是配置详解篇，默认你已按《Ubuntu 22.04 安装 Apache Seata 2.6 指南》完成安装。若尚未安装，先确认以下最小环境即可继续阅读并逐段实操：
ls /opt/seata/seata-server/conf/
java -version 2>&1 | head -1
实测输出：
application.example.yml application.raft.example.yml application.yml logback logback-spring.xml
openjdk version "17.0.13" 2024-10-15
三、参数查看与修改方式
3.1 配置文件的加载位置
seata-server 的 JVM 参数集中在 bin/seata-setup.sh 与 bin/seata-server.sh 两个脚本中。查看启动脚本如何指定配置文件：
grep -n 'spring.config' /opt/seata/seata-server/bin/seata-server.sh
实测输出：
JAVA_OPT="${JAVA_OPT} -Dspring.config.additional-location=${BASEDIR}/conf/ -Dspring.config.location=${BASEDIR}/conf/application.yml -Dlogging.config=${BASEDIR}/conf/logback-spring.xml -Dproduction.deploy.output=true"
即服务端固定读取 /opt/seata/seata-server/conf/application.yml（BASEDIR 由脚本自动解析为安装目录）。conf 目录下三个文件的作用：
| 文件 | 作用 |
|---|---|
application.yml | 生效配置，服务端启动唯一读取的配置文件 |
application.example.yml | 官方参数样例，覆盖 config/registry/server/store/metrics/transport 全部键及默认值 |
application.raft.example.yml | raft 存储模式专用样例，含 seata.store.raft 完整键 |
3.2 启动命令行参数（覆盖少量高频项）
seata-server.sh 支持命令行参数覆盖端口与存储模式。查看帮助：
bash /opt/seata/seata-server/bin/seata-server.sh --help
实测输出：
apm-skywalking not enabled
[INFO] Auto set JVM heap to 716m (total memory: 1024MB, heap%: 70%)
JMX disabled
Usage: sh seata-server.sh(for linux and mac) or cmd seata-server.bat(for
windows) [options]
Options:
--host, -h
The ip to register to registry center.
--port, -p
The port to listen.
Default: 0
--storeMode, -m
log store mode : file, db, redis
--serverNode, -n
server node id, such as 1, 2, 3.it will be generated according to the
snowflake by default
--seataEnv, -e
The name used for multi-configuration isolation.
--sessionStoreMode, -ssm
session log store mode : file, db, redis
--lockStoreMode, -lsm
lock log store mode : file, db, redis
--help
参数说明：
| 参数 | 说明 | 实测注意 |
|---|---|---|
-h, --host | 注册到注册中心使用的 IP（多网卡时必填） | 不带值直接运行 -h 会报 Error: Host value is required 并打印上述 usage |
-p, --port | TC 监听端口，覆盖 seata.server.service-port | Default: 0 表示不指定时回落到 server.port（8091） |
-m, --storeMode | 存储模式 file/db/redis，覆盖 seata.store.mode | raft 模式不支持命令行指定，须改 yml |
-n, --serverNode | 节点 ID，不指定时按雪花算法生成 | TC 集群多节点时建议显式指定 1/2/3 |
-e, --seataEnv | 多环境配置隔离名 | 加载 application-{env}.yml |
-ssm, --sessionStoreMode | 会话存储模式，覆盖 seata.store.session.mode | 与 -lsm 配合实现会话/锁分开存储 |
-lsm, --lockStoreMode | 锁存储模式，覆盖 seata.store.lock.mode | 同上 |
--help | 打印用法 | 旧文档写的 -h 打印帮助在 2.6.0 已不成立（-h 是 host） |
命令行参数优先级高于 application.yml，但仅覆盖端口与存储模式这几项，其余参数一律以 yml 为准。
3.3 JVM 堆内存参数
JVM 参数同样集中在 bin/seata-setup.sh。堆内存的取值优先级为：显式环境变量 > 按内存自动计算 > 默认 2048m。实测在 1GB 内存机器上启动时脚本自动计算并打印：
[INFO] Auto set JVM heap to 716m (total memory: 1024MB, heap%: 70%)
显式指定堆大小（生产推荐，避免自动计算不可控）：
export JVM_XMS=512m JVM_XMX=512m
bash /opt/seata/seata-server/bin/seata-server.sh -p 8091 > /tmp/seata-start.log 2>&1 &
验证生效：
ps -ef | grep '[j]ava' | head -1
实测输出（节选，-Xmx512m -Xms512m 即覆盖生效的证据）：
/usr/bin/java -Dlog.home=/root/logs/seata -server -Dloader.path=/opt/seata/seata-server/lib -Xmx512m -Xms512m -Xss640k -XX:SurvivorRatio=10 -XX:MetaspaceSize=128m -XX:MaxMetaspaceSize=256m -jar /opt/seata/seata-server/target/seata-server.jar -p 8091
3.4 配置中心方式（批量管理服务端参数）
当 seata.config.type 配置为 nacos/consul/apollo/zk/etcd3 时，服务端参数不再写在 yml，而是平铺键（camelCase）存入配置中心。发行包自带键清单与推送脚本：
ls /opt/seata/seata-server/script/config-center/
实测输出：
README.md apollo config.txt consul etcd3 nacos zk
config.txt 即全部平铺键的官方模板（如 store.mode=db、server.recovery.committingRetryPeriod=1000），配合 nacos/nacos-config.sh 等脚本一键推送。平铺键与 yml 键的对应规则：seata.store.mode ↔ store.mode、seata.server.recovery.committingRetryPeriod ↔ server.recovery.committingRetryPeriod，yml 的 kebab-case（max-conn）对应平铺的 camelCase（maxConn）。
3.5 修改生效方式
Seata 服务端无热加载，任何 yml 修改都必须重启进程生效：
ps -ef | grep '[s]eata-server.jar' | awk '{print $2}' | xargs -r kill
sleep 3
export JVM_XMS=512m JVM_XMX=512m
bash /opt/seata/seata-server/bin/seata-server.sh -p 8091 > /tmp/seata-start.log 2>&1 &
重启后从日志确认新配置被应用（以 db 模式为例）：
grep -E 'store mode|Server started' /root/logs/seata/seata-server.8091.all.log | tail -2
实测输出：
[i]o.seata.server.ParameterParser: store mode: db
[main] [rpc.netty.NettyServerBootstrap] [start] : Server started, service listen port: 8091
四、参数总览
服务端 yml 顶层结构为 server + spring + logging + seata 四块，seata 下再分六个板块。按作用端划分总览如下：
| 配置板块 | 作用端 | 核心作用 |
|---|---|---|
server / spring / logging | 仅服务端 | 端口、应用名、日志路径与扩展 appender |
seata.config | 双端 | 配置中心接入方式（file/nacos/consul/apollo/zk/etcd3） |
seata.registry | 双端 | 注册中心接入方式（file/seata/nacos/eureka/redis/zk/consul/etcd3/sofa） |
seata.server | 仅服务端 | 事务协调核心：端口、恢复线程、undo 清理、限流 |
seata.store | 仅服务端 | 事务存储：file/db/redis/raft 四种模式 |
seata.metrics | 仅服务端 | Micrometer 指标与 Prometheus 导出 |
seata.transport | 双端 | Netty RPC 超时、线程池、批量响应 |
seata.client.*（客户端 yml） | 仅客户端 | TM/RM 重试、undo_log、TCC fence |
seata.service.vgroup-mapping 等 | 仅客户端 | 事务组映射与 TC 集群寻址 |
seata.data-source-proxy-mode | 仅客户端 | 数据源代理模式 AT/XA（2.x 新键） |
客户端键写在业务应用的 application.yml（Spring Boot 键风格为 kebab-case，如 tx-service-group；写入配置中心时用平铺 camelCase，如 service.vgroupMapping）。
五、核心参数分类详解
5.1 基础框架参数（server / spring / logging）
| 键 | 默认值 | 说明 |
|---|---|---|
server.port | 8091 | HTTP 端口预留；2.6.0 服务端不再起 web（控制台独立），TC RPC 端口由 seata.server.service-port 决定 |
spring.application.name | seata-server | 应用名 |
spring.main.web-application-type | none | 2.6.0 固定为 none，服务端无内嵌 web |
logging.config | classpath:logback-spring.xml | 日志框架配置 |
logging.file.path | ${log.home:${user.home}/logs/seata} | 日志目录，log.home 未设时落在用户家目录（root 用户即 /root/logs/seata）；启动脚本实测注入 -Dlog.home=/root/logs/seata |
logging.extend.logstash-appender.enabled | false | 日志推送 Logstash |
logging.extend.kafka-appender.enabled | false | 日志推送 Kafka，配套 bootstrap-servers、topic（logback_to_logstash）、producer.acks（0）、linger-ms（1000）、max-block-ms（0） |
logging.extend.metric-appender.enabled | false | 指标日志独立 appender |
5.2 seata.config：配置中心接入
seata:
config:
type: file
type 可选 file、nacos、consul、apollo、zk、etcd3（样例文件注释原文：support: nacos 、 consul 、 apollo 、 zk 、 etcd3）。file 表示配置就在本 yml，其余五种按下表接入：
| 子键 | 默认值 | 说明 |
|---|---|---|
nacos.server-addr | 127.0.0.1:8848 | Nacos 地址 |
nacos.namespace / nacos.group | 空 / SEATA_GROUP | 命名空间与分组 |
nacos.username / nacos.password | 空 | 开源版 Nacos 鉴权 |
nacos.access-key / nacos.secret-key | 空（注释态） | 阿里云 MSE Nacos 专用，与用户名密码互斥 |
nacos.ram-role-name | 空（注释态） | 阿里云 ECS/ACK 免鉴权场景 |
nacos.data-id | seataServer.properties | 服务端参数在 Nacos 中的 dataId |
consul.server-addr / consul.key | 127.0.0.1:8500 / seata.properties | Consul 地址与键名，acl-token 鉴权 |
apollo.appId / apollo-meta / apollo-config-service | seata-server / http://192.168.1.204:8801 / http://192.168.1.204:8080 | Apollo 三要素，namespace: application、cluster: seata |
zk.server-addr / zk.node-path | 127.0.0.1:2181 / /seata/seata.properties | ZooKeeper 地址与配置节点，session-timeout: 6000、connect-timeout: 2000 |
etcd3.server-addr / etcd3.key | http://localhost:2379 / seata.properties | etcd v3 地址与键名 |
5.3 seata.registry：注册中心接入
seata:
registry:
type: file
样例文件注释原文：support: nacos 、 eureka 、 redis 、 zk 、 consul 、 etcd3 、 sofa 、 seata，另有默认 file（客户端直连 grouplist）。两种顶层通用键：
| 键 | 默认值 | 说明 |
|---|---|---|
preferred-networks | 30.240.*（注释态） | 多网卡时指定优先网段，如 192.168.* |
metadata.weight | 100（注释态） | 附带到注册元数据的权重 |
各注册中心子键（均挂在 seata.registry.<type> 下）：
| 类型 | 关键键与默认值 | 说明 |
|---|---|---|
file | 无子键；客户端配合 service.vgroup-mapping + service.grouplist 直连 | 开发/测试最简方式 |
seata（namingserver，2.x 内置） | server-addr: 127.0.0.1:8081、cluster: default、namespace: public、heartbeat-period: 5000、metadata-max-age-ms: 30000、username/password、tokenValidityInMilliseconds: 1740000 | 实测部署时控制台账号 admin/q1w2e3r4；自注册接口存在 401 已知问题，生产建议 nacos |
nacos | application: seata-server、server-addr: 127.0.0.1:8848、group: SEATA_GROUP、namespace、cluster: default、username/password、access-key/secret-key/ram-role-name | 生产首选 |
eureka | service-url: http://localhost:8761/eureka、application: default、weight: 1 | 老微服务体系 |
redis | server-addr: localhost:6379、db: 0、password、cluster: default、timeout: 0 | 基于 Redis 发布订阅 |
zk | server-addr: 127.0.0.1:2181、cluster: default、session-timeout: 6000、connect-timeout: 2000、username/password | ZooKeeper |
consul | server-addr: 127.0.0.1:8500、cluster: default、acl-token | Consul |
etcd3 | server-addr: http://localhost:2379、cluster: default | etcd v3 |
sofa | server-addr: 127.0.0.1:9603、application: default、region: DEFAULT_ZONE、datacenter: DefaultDataCenter、cluster: default、group: SEATA_GROUP、address-wait-time: 3000 | AntFu/SOFARegistry |
5.4 seata.server：事务协调核心参数
| 键 | 默认值 | 说明 |
|---|---|---|
server.service-port | 8091 | TC RPC 监听端口；不配置时取 server.port |
server.max-commit-retry-timeout | -1 | 全局提交重试时限（毫秒），-1 不限；超限事务进入重试死信状态 |
server.max-rollback-retry-timeout | -1 | 全局回滚重试时限（毫秒），-1 不限 |
server.rollback-failed-unlock-enable | false | 回滚失败时是否释放全局锁；false 保守（保留锁防脏写），确认无并发风险可开 true |
server.enable-check-auth | true | 校验客户端访问权限 |
server.enable-parallel-request-handle | true | 并行处理客户端请求 |
server.enable-parallel-handle-branch | false | 二阶段分支并行处理（回滚/提交多分支并行），分支多时可开 |
server.retry-dead-threshold | 70000 | 超过该时长（毫秒）未完成的事务判定为重试死信，不再重试 |
server.xaer-nota-retry-timeout | 60000 | XA 模式 XAER_NOTA 响应的重试时限（毫秒） |
server.applicationDataLimit | 64000 | 客户端业务数据（applicationData）最大字节数 |
server.applicationDataLimitCheck | true | 是否校验上述限制（config.txt 平铺默认 false，yml 样例默认 true，以 yml 为准） |
server.recovery.committing-retry-period | 1000 | 提交中（Committing）状态恢复线程扫描周期（毫秒） |
server.recovery.async-committing-retry-period | 1000 | 异步提交中状态扫描周期 |
server.recovery.rollbacking-retry-period | 1000 | 回滚中（Rollbacking）状态扫描周期 |
server.recovery.end-status-retry-period | 1000 | 终态（Finished）清理扫描周期 |
server.recovery.timeout-retry-period | 1000 | 超时事务检测周期（默认全局事务超时 60s，由客户端 defaultGlobalTransactionTimeout 决定） |
server.undo.log-save-days | 7 | 服务端 undo 日志保留天数 |
server.undo.log-delete-period | 86400000 | 服务端 undo 日志清理任务周期（毫秒，即 1 天） |
server.session.branch-async-queue-size | 5000 | 分支会话异步删除队列长度 |
server.session.enable-branch-async-remove | false | 分支会话异步删除开关，大事务高并发时可开 |
server.ratelimit.enable | false | 服务端限流开关 |
server.ratelimit.bucketTokenNumPerSecond | 999999 | 令牌桶每秒生成令牌数 |
server.ratelimit.bucketTokenMaxNum | 999999 | 桶容量上限 |
server.ratelimit.bucketTokenInitialNum | 999999 | 初始令牌数 |
server.http.filter.xss.keywords | ["<script>", "</script>", "javascript:", "vbscript:"] | 控制台 HTTP 接口 XSS 过滤词 |
实测提示：recovery 五个周期的实测默认值均为 1000ms，全局事务回滚期间 TC 以约 1 秒一次的频率扫描 global_table 中 Status=4（Rollbacking）的记录，与《安装指南》第十章实测回滚日志吻合。
5.5 seata.store：存储参数（file / db / redis / raft）
seata:
store:
mode: file
mode 可选 file、db、redis、raft（样例注释原文：support: file 、 db 、 redis 、 raft）。另有两个独立键可将会话与锁分开存储：
| 键 | 默认值 | 说明 |
|---|---|---|
store.session.mode | file | 会话存储模式，可独立于 store.mode |
store.lock.mode | file | 全局锁存储模式；集群时三者必须一致（除 file 单机） |
file 模式（seata.store.file）
| 键 | 默认值 | 说明 |
|---|---|---|
dir | sessionStore | 存储目录（相对启动目录） |
max-branch-session-size | 16384 | 单条分支会话文件记录上限（字节） |
max-global-session-size | 512 | 单条全局会话文件记录上限（字节） |
file-write-buffer-cache-size | 16384 | 写缓冲区大小（字节） |
session-reload-read-size | 100 | 重启恢复时每次读取行数 |
flush-disk-mode | async | 刷盘模式 async/sync |
db 模式（seata.store.db）
| 键 | 默认值 | 说明 |
|---|---|---|
datasource | druid | 连接池 druid/hikari/dbcp |
db-type | mysql | 数据库类型 |
driver-class-name | com.mysql.jdbc.Driver（样例默认） | MySQL 8 必须改为 com.mysql.cj.jdbc.Driver，实测用旧值会告警且部分场景失败 |
url | jdbc:mysql://127.0.0.1:3306/seata?rewriteBatchedStatements=true | 建议追加 useSSL=false&serverTimezone=Asia/Shanghai |
user / password | mysql / mysql | 数据库账号 |
min-conn / max-conn | 10 / 100 | 连接池上下限；实测小内存机器建议 5/30 |
global-table / branch-table / lock-table / distributed-lock-table / vgroup-table | global_table / branch_table / lock_table / distributed_lock / vgroup_table | 五张核心表名，须与 script/server/db/mysql.sql 导入的一致 |
query-limit | 1000 | 恢复线程单次扫描行数上限 |
max-wait | 5000 | 获取连接最大等待（毫秒） |
druid.time-between-eviction-runs-millis | 120000 | Druid 检测空闲连接周期 |
druid.min-evictable-idle-time-millis | 300000 | 连接最小可驱逐空闲时长 |
druid.test-while-idle / test-on-borrow / keep-alive | true / false / false | 空闲检测、借出检测、保活；生产建议 keep-alive: true |
hikari.idle-timeout / keepalive-time / max-lifetime / validation-timeout | 600000 / 120000 / 1800000 / 5000 | Hikari 连接池对应项 |
redis 模式（seata.store.redis）
| 键 | 默认值 | 说明 |
|---|---|---|
mode | single | single/sentinel |
type | lua | 数据写入方式 lua/pipeline（lua 支持分布式锁原子操作，官方推荐） |
database | 0 | Redis 库号 |
min-conn / max-conn / max-total | 10 / 100 / 100 | 连接池 |
query-limit | 1000 | 单次扫描上限 |
single.host / single.port | 127.0.0.1 / 6379 | 单机地址 |
sentinel.master-name / sentinel.sentinel-hosts / sentinel.sentinel-password | 空 | 哨兵模式三键 |
raft 模式（seata.store.raft，取自 application.raft.example.yml）
raft 模式让 TC 集群摆脱外部数据库依赖（2.x 新特性），样例文件 application.raft.example.yml 中完整键：
| 键 | 默认值 | 说明 |
|---|---|---|
group | default | raft 分组 |
server-addr | 空 | 集群成员列表，如 127.0.0.1:7091,127.0.0.1:7092,127.0.0.1:7093（config.txt 示例值） |
snapshot-interval | 600 | 快照间隔（秒） |
apply-batch | 32 | 批量提交日志条数 |
max-append-bufferSize | 262144 | 复制缓冲区上限（字节） |
max-replicator-inflight-msgs | 256 | 单副本在途消息上限 |
disruptor-buffer-size | 16384 | Disruptor 环形缓冲大小 |
election-timeout-ms | 1000 | 选主超时（config.txt 平铺默认 2000） |
reporter-enabled / reporter-initial-delay | false / 60 | 状态上报开关与延迟（秒） |
serialization / compressor | jackson / none | 日志序列化与压缩 |
sync | true | 日志与快照同步刷盘 |
ssl.enabled | false | 节点间 bolt 通信 TLS；配套 ssl.client.keystore.path（ssl/cbolt.pfx）、ssl.server.keystore.path（ssl/bolt.pfx）、password、type: pkcs12、kmf-algorithm/tmf-algorithm: SunX509 |
raft 集群要求至少 3 节点，且每个节点的 server-addr 列表一致。
5.6 seata.metrics：指标参数
| 键 | 默认值 | 说明 |
|---|---|---|
metrics.enabled | false | 指标总开关 |
metrics.registry-type | compact | 内置精简注册表（固定值） |
metrics.exporter-list | prometheus | 导出器列表，当前支持 prometheus |
metrics.exporter-prometheus-port | 9898 | Prometheus 抓取端口 |
实测注意：即便 metrics.enabled 为 false，2.6.0 启动时也会占用 9898 端口（Prometheus 导出器随进程启动），单机跑多实例时第二个实例会因 9898 被占而报 seata server start failed，见第七章 FAQ。
5.7 seata.transport：传输参数
| 键 | 默认值 | 说明 |
|---|---|---|
transport.rpc-tc-request-timeout | 15000 | 客户端调用 TC 的超时（毫秒） |
transport.enable-tc-server-batch-send-response | false | 服务端批量回包 |
transport.min-http-pool-size / max-http-pool-size | 10 / 100 | HTTP 线程池 |
transport.max-http-task-queue-size | 1000 | HTTP 任务队列长度 |
transport.http-pool-keep-alive-time | 500 | HTTP 线程保活（秒） |
transport.shutdown.wait | 3 | 优雅停机等待（秒） |
transport.thread-factory.boss-thread-prefix | NettyBoss | Netty 线程名前缀 |
transport.thread-factory.worker-thread-prefix | NettyServerNIOWorker | Netty worker 线程名前缀 |
transport.thread-factory.boss-thread-size | 1 | boss 线程数 |
以下双端键未出现在 yml 样例但存在于 script/config-center/config.txt（平铺风格，客户端同样适用）：
| 平铺键 | 默认值 | 说明 |
|---|---|---|
transport.protocol | seata | 通信协议（seata 私有协议） |
transport.heartbeat | true | 心跳 |
transport.serialization | seata | 序列化方式 seata/fastjson 等 |
transport.compressor | none | 压缩 none/zip/7z/bzip2 |
transport.rpcRmRequestTimeout / rpcTmRequestTimeout | 30000 | RM/TM 请求超时（毫秒） |
transport.enableTmClientBatchSendRequest / enableRmClientBatchSendRequest | false / true | 客户端批量发请求 |
transport.enableClientSharedEventLoopGroup | false | 客户端共享 EventLoopGroup |
transport.serverSocketSendBufSize / serverSocketResvBufSize | 153600 | 服务端 socket 缓冲（字节） |
transport.writeBufferHighWaterMark / writeBufferLowWaterMark | 67108864 / 1048576 | Netty 写缓冲高低水位（字节） |
transport.soBackLogSize | 1024 | 监听 backlog |
transport.serverChannelMaxIdleTimeSeconds | 30 | 服务端通道最大空闲时间（秒） |
transport.minServerPoolSize / maxServerPoolSize / maxTaskQueueSize / keepAliveTime | 50 / 500 / 20000 / 500 | 服务端业务线程池 |
5.8 客户端核心参数（seata-spring-boot-starter）
客户端参数写在业务应用 application.yml，以下默认值取自发行包 script/config-center/config.txt 并经真实工程（Spring Boot 3.2.5 + seata-spring-boot-starter 2.6.0）验证。基础接入键：
| Spring Boot 键 | 平铺键 | 默认值 | 说明 |
|---|---|---|---|
seata.enabled | - | true | 总开关 |
seata.application-id | - | 取 spring.application.name | 应用 ID |
seata.tx-service-group | - | 空（必填） | 事务组名，自拟如 demo_tx_group |
seata.service.vgroup-mapping.demo_tx_group | service.vgroupMapping.demo_tx_group | - | 事务组 → TC 集群名映射 |
seata.service.grouplist.default | service.default.grouplist | - | 集群名 → TC 地址（file 注册中心时必填，如 seata-tc:8091） |
seata.service.disable-global-transaction | service.disableGlobalTransaction | false | 全局事务总闸 |
seata.data-source-proxy-mode | - | AT | 数据源代理模式 AT/XA（2.x 新键；TCC/SAGA 不依赖数据源代理） |
seata.registry.type / seata.config.type | - | file | 与服务端同款注册/配置中心接入 |
client.metadataMaxAgeMs | 同左 | 30000 | 客户端元数据刷新周期（毫秒） |
TM 事务管理器参数（seata.client.tm.*）：
| Spring Boot 键 | 平铺键 | 默认值 | 说明 |
|---|---|---|---|
client.tm.commit-retry-count | client.tm.commitRetryCount | 5 | 一阶段提交结果查询重试次数 |
client.tm.rollback-retry-count | client.tm.rollbackRetryCount | 5 | 一阶段回滚结果查询重试次数 |
client.tm.default-global-transaction-timeout | client.tm.defaultGlobalTransactionTimeout | 60000 | 全局事务默认超时（毫秒，@GlobalTransactional 未指定 timeoutMills 时生效） |
client.tm.degrade-check | client.tm.degradeCheck | false | 降级自愈开关（连续失败自动降级为非全局事务） |
client.tm.degrade-check-allow-times / degrade-check-period | 10 / 2000 | 降级判定阈值与检查周期 |
RM 资源管理器参数（seata.client.rm.*）：
| Spring Boot 键 | 平铺键 | 默认值 | 说明 |
|---|---|---|---|
client.rm.async-commit-buffer-limit | client.rm.asyncCommitBufferLimit | 10000 | 异步提交缓冲上限 |
client.rm.lock.retry-interval | client.rm.lock.retryInterval | 10 | 全局锁冲突重试间隔（毫秒） |
client.rm.lock.retry-times | client.rm.lock.retryTimes | 30 | 全局锁冲突重试次数 |
client.rm.lock.retry-policy-branch-rollback-on-conflict | client.rm.lock.retryPolicyBranchRollbackOnConflict | true | 锁冲突时优先回滚分支 |
client.rm.report-retry-count | client.rm.reportRetryCount | 5 | 一阶段结果上报重试次数 |
client.rm.table-meta-check-enable | client.rm.tableMetaCheckEnable | true | 表结构变更检测（AT 二阶段回滚依赖前后镜像，表结构漂移会导致回滚失败，建议开启） |
client.rm.table-meta-checker-interval | client.rm.tableMetaCheckerInterval | 60000 | 表结构检测周期（毫秒） |
client.rm.sql-parser-type | client.rm.sqlParserType | druid | SQL 解析器 druid |
client.rm.report-success-enable | client.rm.reportSuccessEnable | false | 成功结果也上报 TC（排障时可开，有性能损耗） |
client.rm.saga-branch-register-enable / saga-json-parser | - | false / fastjson | SAGA 分支注册与 JSON 解析器 |
undo_log 与 TCC fence 参数：
| Spring Boot 键 | 平铺键 | 默认值 | 说明 |
|---|---|---|---|
client.undo.log-table | client.undo.logTable | undo_log | AT 模式回滚日志表名，每个业务库都要建 |
client.undo.log-serialization | client.undo.logSerialization | jackson | 镜像序列化方式；实测必须引入 jackson-databind 与 jackson-datatype-jsr310，否则运行时报 NoClassDefFoundError |
client.undo.data-validation | client.undo.dataValidation | true | 回滚前校验后镜像与当前数据一致（不一致说明脏写，拒绝回滚） |
client.undo.only-care-update-columns | client.undo.onlyCareUpdateColumns | true | 仅记录变更列（减小 undo_log 体积） |
client.undo.compress.enable / compress.type / compress.threshold | 同左 | true / zip / 64k | 镜像压缩开关、算法、触发阈值 |
tcc.fence.logTableName | 同左 | tcc_fence_log | TCC 防悬挂记录表名 |
tcc.fence.cleanPeriod | 同左 | 1h | fence 记录清理周期 |
tcc.contextJsonParserType | 同左 | fastjson | TCC 上下文解析器 |
log.exceptionRate | 同左 | 100 | 异常日志采样率（1/100） |
实测提醒：undo_log 建表语句在业务库执行（本专栏安装指南实测采用官方 MySQL 版），字段含 branch_id、xid、context、rollback_info（longblob）、log_status、log_created、log_modified，联合主键 (branch_id, xid)。
六、生产配置模板
6.1 生产 db 模式 application.yml 模板（MySQL，4C8G，堆 1~2GB）
以下模板在本专栏实验环境（MySQL 8 + JDK 17）验证过 db 模式启动与 AT 回滚全流程，按 4C8G 生产机调整了连接池与保活参数：
server:
port: 8091
spring:
application:
name: seata-server
main:
web-application-type: none
logging:
config: classpath:logback-spring.xml
file:
path: /var/log/seata
extend:
logstash-appender:
enabled: false
destination: 127.0.0.1:4560
kafka-appender:
enabled: false
bootstrap-servers: 127.0.0.1:9092
topic: logback_to_logstash
producer:
acks: 0
linger-ms: 1000
max-block-ms: 0
metric-appender:
enabled: false
seata:
config:
type: file
registry:
type: nacos
nacos:
application: seata-server
server-addr: 127.0.0.1:8848
group: SEATA_GROUP
cluster: default
username: nacos
password: nacos
server:
service-port: 8091
max-commit-retry-timeout: -1
max-rollback-retry-timeout: -1
rollback-failed-unlock-enable: false
enable-check-auth: true
enable-parallel-request-handle: true
enable-parallel-handle-branch: false
retry-dead-threshold: 70000
xaer-nota-retry-timeout: 60000
applicationDataLimit: 64000
applicationDataLimitCheck: true
recovery:
committing-retry-period: 1000
async-committing-retry-period: 1000
rollbacking-retry-period: 1000
end-status-retry-period: 1000
timeout-retry-period: 1000
undo:
log-save-days: 7
log-delete-period: 86400000
session:
branch-async-queue-size: 5000
enable-branch-async-remove: false
ratelimit:
enable: false
bucketTokenNumPerSecond: 999999
bucketTokenMaxNum: 999999
bucketTokenInitialNum: 999999
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?rewriteBatchedStatements=true&useSSL=false&serverTimezone=Asia/Shanghai
user: root
password: q1w2e3r4
min-conn: 10
max-conn: 100
global-table: global_table
branch-table: branch_table
lock-table: lock_table
distributed-lock-table: distributed_lock
vgroup-table: vgroup_table
query-limit: 1000
max-wait: 5000
druid:
time-between-eviction-runs-millis: 120000
min-evictable-idle-time-millis: 300000
test-while-idle: true
test-on-borrow: false
keep-alive: true
metrics:
enabled: true
registry-type: compact
exporter-list: prometheus
exporter-prometheus-port: 9898
transport:
rpc-tc-request-timeout: 15000
enable-tc-server-batch-send-response: false
min-http-pool-size: 10
max-http-pool-size: 100
max-http-task-queue-size: 1000
http-pool-keep-alive-time: 500
shutdown:
wait: 3
thread-factory:
boss-thread-prefix: NettyBoss
worker-thread-prefix: NettyServerNIOWorker
boss-thread-size: 1
启动时固定堆大小（4C8G 建议堆 1~2GB）：
export JVM_XMS=1024m JVM_XMX=1024m
bash /opt/seata/seata-server/bin/seata-server.sh -p 8091 > /tmp/seata-start.log 2>&1 &
6.2 按场景调整建议
| 场景 | 建议调整 |
|---|---|
| 1C2G 测试机 | 堆 512m（JVM_XMS/JVM_XMX）；store.db.min-conn: 5、max-conn: 30；metrics.enabled: false 减少噪音 |
| 一般生产（4C8G） | 堆 1~2GB；连接池 10/100；druid keep-alive: true 防 MySQL 空闲断连 |
| 高并发大事务 | enable-parallel-handle-branch: true、session.enable-branch-async-remove: true；store.db.query-limit 保持 1000 |
| 单机 2 实例（不推荐） | 端口必须错开（-p 8091/8092），且 9898 指标端口会冲突，仅可用于临时验证 |
| undo 磁盘紧张 | server.undo.log-save-days 调小（如 3）；log-delete-period 保持 1 天 |
| raft 集群（无外部 DB） | 复制 application.raft.example.yml 为 application.yml，填 store.raft.server-addr 三节点列表，堆 1~2GB |
七、常见问题（FAQ）
Q1：修改了 application.yml 重启后不生效？
先确认改的文件路径正确（固定是 conf/application.yml，启动脚本用 -Dspring.config.location 锁定）；再用 ps -ef 检查启动命令是否带了 -p/-m 参数——命令行参数优先级高于 yml，带 -m db 启动时 yml 里写 mode: file 不会生效。最后确认进程真的重启了（ps -ef | grep '[s]eata-server.jar' 的启动时间）。
Q2：db 模式启动报 The driver {com.mysql.cj.jdbc.Driver} cannot be found in the path /opt/seata/seata-server/lib/jdbc
发行包不带 JDBC 驱动。下载 mysql-connector-j 放入即可（实测用 8.4.0）：
wget -P /opt/seata/seata-server/lib/jdbc/ https://repo1.maven.org/maven2/com/mysql/mysql-connector-j/8.4.0/mysql-connector-j-8.4.0.jar
Q3：db 模式启动报 Unknown database 'seata' 或 Table 'seata.global_table' doesn't exist
官方 script/server/db/mysql.sql 不含建库语句，需先建库再导表，且库中必须有 global_table、branch_table、lock_table、distributed_lock、vgroup_table 五张表：
mysql -h seata-db -uroot -pq1w2e3r4 -e "CREATE DATABASE IF NOT EXISTS seata DEFAULT CHARACTER SET utf8mb4;"
mysql -h seata-db -uroot -pq1w2e3r4 seata < /opt/seata/seata-server/script/server/db/mysql.sql
Q4：启动报 seata server start failed，日志显示 9898 端口被占用
2.6.0 的 Prometheus 指标导出器固定绑定 9898。单机残留旧进程（或另一个实例）占着 9898 时新实例启动失败。实测清理方式：
ss -lntp | grep 9898
ps -ef | grep '[s]eata-server' | awk '{print $2}' | xargs -r kill
sleep 3
bash /opt/seata/seata-server/bin/seata-server.sh -p 8091 > /tmp/seata-start.log 2>&1 &
Q5：启动日志打印 Auto set JVM heap to 716m，堆大小不符合预期
这是 seata-setup.sh 按总内存 70% 自动计算的值。显式覆盖即可：
export JVM_XMS=512m JVM_XMX=512m
并用 ps -ef | grep '[j]ava' 确认 -Xmx512m -Xms512m 出现在进程参数里。
Q6：yml 键与 config.txt 平铺键怎么互转
规则：yml 里 seata. 前缀去掉后按下划线合并，kebab-case 转 camelCase。例如 seata.store.max-conn ↔ store.db.maxConn、seata.server.recovery.committing-retry-period ↔ server.recovery.committingRetryPeriod、seata.service.vgroup-mapping.demo_tx_group ↔ service.vgroupMapping.demo_tx_group。注意个别键两端默认值不同（如 applicationDataLimitCheck：yml true、config.txt false），以你实际生效的配置载体为准。
八、参考链接
- Seata 官方参数手册（中文）：https://seata.apache.org/zh-cn/docs/user/configurations/
- 服务端部署文档：https://seata.apache.org/docs/ops/deploy-server/
- 客户端接入（Spring Boot Starter）：https://seata.apache.org/docs/user/quickstart/
- 发行包内参数样例：
/opt/seata/seata-server/conf/application.example.yml、/opt/seata/seata-server/conf/application.raft.example.yml - 配置中心推送键清单：
/opt/seata/seata-server/script/config-center/config.txt - 建表脚本：
/opt/seata/seata-server/script/server/db/mysql.sql
章节目录