Apache Seata 2.6 常用 CLI 命令与工具详解

详解 Apache Seata 2.6.0 命令行工具与运维手段：seata-server.sh 启动参数与 stop 优雅停机、JVM 参数脚本、日志文件排查、进程端口验证、TC 数据库表查询、config-center 推送脚本与 namingserver 控制台 REST API 实测

Apache SeataSeata分布式事务Java2026/10/15

Apache Seata 2.6 常用 CLI 命令与工具详解

目标：汇总 Apache Seata 2.6.0 日常运维会碰到的全部命令行工具——seata-server.sh 的启动参数与 stop 优雅停机、JVM 参数脚本、日志文件与排查命令、进程端口验证、TC 数据库表查询、配置中心推送脚本、namingserver 控制台 REST API。所有命令与回显均实测于 Ubuntu 22.04 + OpenJDK 17。

一、环境信息

  • 操作系统：Ubuntu 22.04（x86_64）
  • Java：OpenJDK 17（seata-server）；namingserver 需 JDK 25+（实测用 Eclipse Temurin JRE 25.0.4.1_1）
  • Seata 版本：2.6.0（安装目录 /opt/seata/seata-server，namingserver 目录 /opt/seata/seata-namingserver）
  • 日志目录：/root/logs/seata
  • 端口：8091（TC RPC）、9898（Prometheus 指标）、8081（namingserver 控制台）
  • 数据库：MySQL 8，地址 seata-db:3306，库名 seata，账号 root/q1w2e3r4

二、工具概览

工具/手段路径用途
seata-server.sh/opt/seata/seata-server/bin/seata-server.sh启动 TC、传参覆盖端口/存储模式、stop 优雅停机
seata-setup.sh/opt/seata/seata-server/bin/seata-setup.shJVM 参数集中地（堆内存、GC 日志、调试参数）
日志文件/root/logs/seata/all/error/warn 三级日志 + GC 日志，排障主入口
ps / ss系统命令进程与端口验证
mysql系统命令查询 TC 五表（global_table 等）与业务库 undo_log
config-center 脚本/opt/seata/seata-server/script/config-center/向 nacos/consul/etcd3/apollo/zk 批量推送服务端配置
建表脚本/opt/seata/seata-server/script/server/db/7 种数据库的 TC 建表 SQL
namingserver/opt/seata/seata-namingserver/bin/seata-namingserver.sh控制台与 REST API（集群监控、命名服务）

三、前置条件

ls /opt/seata/seata-server/bin/
ps -ef | grep '[s]eata-server.jar' | wc -l

实测输出（TC 运行中返回 1，未启动返回 0）：

seata-server.bat  seata-server.sh  seata-setup.sh
1

注意：Ubuntu 22.04 自带 ss 命令（iproute2 包）。若是最小化安装，执行 apt-get install -y iproute2 mysql-client 补齐端口验证与数据库查询工具。

四、各工具详解

4.1 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

启动（db 模式、显式指定堆与注册 IP）：

export JVM_XMS=512m JVM_XMX=512m
cd /opt/seata/seata-server
nohup bash bin/seata-server.sh -p 8091 -h 172.23.0.2 > /tmp/seata-start.log 2>&1 &
sleep 12
grep -E 'Server started|started in' /root/logs/seata/seata-server.8091.all.log | tail -2

实测输出：

2026-10-15 01:43:55.740  INFO --- [main] [org.apache.seata.core.rpc.netty.NettyServerBootstrap] [start] []: Server started, service listen port: 8091
2026-10-15 01:43:56.188  INFO --- [main] [org.apache.seata.server.ServerRunner] [run] []: seata server started in 1122 millSeconds

优雅停机（脚本会向进程发 shutdown 请求）：

bash /opt/seata/seata-server/bin/seata-server.sh stop

实测输出：

JMX disabled
The seata-server(5967) is running...
Send shutdown request to seata-server(5967) OK

stop 输出中的括号内数字即 TC 进程 PID。等待 3~5 秒后用 ps -ef | grep '[s]eata-server.jar' 确认已退出。

4.2 seata-setup.sh：JVM 参数集中地

堆内存、GC 日志等 JVM 参数全部在这个脚本里设置，优先级为显式环境变量 > 按内存自动计算 > 默认 2048m。1GB 内存机器实测自动计算：

[INFO] Auto set JVM heap to 716m (total memory: 1024MB, heap%: 70%)

固定堆大小并验证（-Xmx512m -Xms512m 出现在进程参数里即生效）：

export JVM_XMS=512m JVM_XMX=512m
nohup bash /opt/seata/seata-server/bin/seata-server.sh -p 8091 > /tmp/seata-start.log 2>&1 &
sleep 12
ps -ef | grep '[s]eata-server.jar' | grep -o '\-Xmx[0-9a-z]*'

实测输出：

-Xmx512m

脚本默认还注入了 GC 日志参数（截取自实际进程命令行）：

-Xlog:gc*:file=/root/logs/seata/seata_gc.log:time,tags:filecount=10,filesize=10M -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/root/logs/seata/java_heapdump.hprof

即 GC 日志滚动保留 10 个文件、单个 10MB；OOM 时自动堆转储到 /root/logs/seata/java_heapdump.hprof。需要调整时直接编辑 bin/seata-setup.sh。

4.3 日志文件与排查命令

日志目录（logging.file.path 默认值 ${log.home:${user.home}/logs/seata}，root 用户即 /root/logs/seata）：

ls -la /root/logs/seata/

实测输出：

total 352
drwxr-xr-x 2 root root   4096 Oct 15 01:05 .
drwxr-xr-x 3 root root   4096 Oct 15 00:32 ..
-rw-r--r-- 1 root root  17144 Oct 15 01:03 seata-namingserver.8081.all.log
-rw-r--r-- 1 root root    704 Oct 15 01:03 seata-namingserver.8081.error.log
-rw-r--r-- 1 root root   7250 Oct 15 01:01 seata-namingserver.8081.warn.log
-rw-r--r-- 1 root root 140613 Oct 15 01:05 seata-server.8091.all.log
-rw-r--r-- 1 root root  79356 Oct 15 01:04 seata-server.8091.error.log
-rw-r--r-- 1 root root  21114 Oct 15 01:03 seata-server.8091.warn.log
-rw-r--r-- 1 root root  11737 Oct 15 01:40 seata_gc.log
-rw-r--r-- 1 root root   3748 Oct 15 01:04 seata_gc.log.0

文件命名规则：<应用名>.<端口>.<级别>.log，GC 日志按 seata_gc.log + 序号滚动。

常用排查命令（全部实测）：

# 启动是否成功
grep -E 'Server started|started in' /root/logs/seata/seata-server.8091.all.log | tail -2

# 存储模式是否生效
grep 'store mode' /root/logs/seata/seata-server.8091.all.log | tail -1

# 全局事务生命周期（begin/branch register/rollback）
grep -E 'begin|register|rollback' /root/logs/seata/seata-server.8091.all.log | tail -5

# 错误与告警
tail -20 /root/logs/seata/seata-server.8091.error.log

实测输出（最后一例，回滚场景）：

2026-10-15 01:02:41.954  INFO --- [ServerHandlerThread_1_500] [org.apache.seata.server.coordinator.DefaultCoordinator] [doGlobalRollback] []: Rollback global transaction successfully, xid = 172.23.0.2:8091:2863554176196188165

GC 日志首行确认 JVM 版本与处理器数：

head -3 /root/logs/seata/seata_gc.log

实测输出：

[2026-10-15T01:05:03.070+0000][gc] Using Serial
[2026-10-15T01:05:03.071+0000][gc,init] Version: 17.0.20.1+1-22.04-Ubuntu (release)
[2026-10-15T01:05:03.075+0000][gc,init] CPUs: 12 total, 12 available

4.4 进程与端口验证

进程命令行验证（同时确认 JVM 参数与启动参数）：

ps -ef | grep '[s]eata-server.jar'

实测输出（节选）：

root        5967       1  2 01:05 ?        00:00:47 /usr/bin/java -Dlog.home=/root/logs/seata -server -Dloader.path=/opt/seata/seata-server/lib -Xmx512m -Xms512m ... -jar /opt/seata/seata-server/target/seata-server.jar -p 8091 -h 172.23.0.2

端口监听验证：

ss -lntp | grep -E ':8091|:9898|:8081'

实测输出：

LISTEN 0      3                  *:9898             *:*    users:(("java",pid=5967,fd=279))
LISTEN 0      100                *:8081             *:*    users:(("java",pid=5472,fd=147))
LISTEN 0      1024               *:8091             *:*    users:(("java",pid=5967,fd=366))

三条监听分别对应：9898 Prometheus 指标（即使未开启 metrics 也默认占用）、8081 namingserver 控制台、8091 TC RPC。

4.5 TC 数据库表查询（db 存储模式）

TC 五张核心表的状态直接反映事务运行情况：

mysql -h seata-db -uroot -pq1w2e3r4 seata -e "SHOW TABLES;"

实测输出：

Tables_in_seata
branch_table
distributed_lock
global_table
lock_table
vgroup_table

查询全局事务（空库时）：

mysql -h seata-db -uroot -pq1w2e3r4 seata -e "SELECT xid, application_id, transaction_service_group, status FROM global_table;"

实测输出：

Empty set (0.00 sec)

global_table.status 对应 Seata 的 GlobalStatus 枚举，排查时按值判断（关键值经 javap 反编译 seata-all 包实测核对）：

status含义运维含义
0UnKnown未知
1Begin事务进行中
2Committing提交中
3CommitRetrying提交重试中
4Rollbacking回滚中（实测确认）
5RollbackRetrying回滚重试中
6TimeoutRollbacking超时回滚中
7TimeoutRollbackRetrying超时回滚重试中
8AsyncCommitting异步提交中
9Committed已提交
10Rollbacked已回滚（实测确认）
11TimeoutRollbacked超时已回滚
12Finished终态

长时间停留在 1（Begin）的事务要关注业务是否卡住；停留在 4/5（回滚中）超过 1 分钟通常是分支回滚失败，到 seata-server.8091.error.log 找分支异常。恢复线程约每秒（server.recovery.*-retry-period: 1000）扫描一次这些状态并自动推进，一般无需手工 UPDATE。

业务库侧查回滚日志表（AT 模式）：

mysql -h seata-db -uroot -pq1w2e3r4 seata_demo -e "SELECT COUNT(*) FROM undo_log;"

实测输出（事务结束后 undo_log 清理干净）：

COUNT(*)
0

4.6 config-center 脚本：批量推送服务端配置

当 seata.config.type 使用配置中心时，用发行包自带脚本把 config.txt 平铺键一键推送：

ls /opt/seata/seata-server/script/config-center/

实测输出：

README.md  apollo  config.txt  consul  etcd3  nacos  zk

nacos 推送脚本用法（-h 帮助实测）：

bash /opt/seata/seata-server/script/config-center/nacos/nacos-config.sh -h

实测输出：

 USAGE OPTION: /opt/seata/seata-server/script/config-center/nacos/nacos-config.sh [-h host] [-p port] [-g group] [-t tenant] [-u username] [-w password]

典型用法（先改 config.txt 中的键值，再推送）：

cd /opt/seata/seata-server/script/config-center/nacos
bash nacos-config.sh -h 127.0.0.1 -p 8848 -g SEATA_GROUP -t public -u nacos -w nacos

consul/zk/etcd3/apollo 目录下有同款 *-config.sh 与 *-config-interactive.sh（交互式逐键确认），用法一致。config.txt 本身就是服务端全部平铺键的官方模板，修改前建议备份。

4.7 建表脚本清单（script/server）

ls /opt/seata/seata-server/script/server/db/

实测输出：

dm.sql  kingbase.sql  mysql.sql  oracle.sql  oscar.sql  postgresql.sql  sqlserver.sql

除 MySQL 外官方还提供达梦、人大金仓、Oracle、PostgreSQL、SQLServer、Oscar 的建表脚本。同目录还有 docker-compose/、helm/、kubernetes/ 三种容器化部署模板。

4.8 namingserver 控制台与 REST API

启动（需 JDK 25+）：

cd /opt/seata/seata-namingserver
JAVA_HOME=/opt/jre25 PATH=/opt/jre25/bin:$PATH nohup bash bin/seata-namingserver.sh > /tmp/ns.log 2>&1 &
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8081/

实测输出：

200

控制台账号在 seata-namingserver/conf/application.yml 的 console.user 下（本文设为 admin/q1w2e3r4）。登录获取 Token（实测注意：必须 JSON body，用 URL 参数传会报 400）：

curl -s -X POST http://127.0.0.1:8081/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"q1w2e3r4"}'

实测输出（data 字段即 Bearer Token）：

{"code":"200","message":"success","data":"Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhZG1pbiIsImF1dGgiOiIiLCJleHAiOjE3OTIwMzAzNjN9.S8BS3UgftbBUJiiCAeBYwTVJV-rZaddzEZdoMcXy7j8","success":true}

带 Token 查询集群实例列表（等价于控制台首页的集群视图）：

TOKEN=$(curl -s -X POST http://127.0.0.1:8081/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"q1w2e3r4"}' \
  | sed 's/.*"data":"\([^"]*\)".*/\1/')
curl -s "http://127.0.0.1:8081/api/v1/naming/clusters?namespace=public" -H "Authorization: $TOKEN"

实测输出（节选，可见已注册 TC 实例的健康状态与版本）：

[{"clusterName":"default","clusterType":"default","vGroupMapping":[],"unitData":[{"unitName":"f5247167-18ab-4f6d-8378-8952019eec67","namingInstanceList":[{"control":{"host":"172.23.0.2","port":8091},"transaction":{"host":"172.23.0.2","port":8091},"internal":null,"weight":1.0,"healthy":true,"group":null,"role":"MEMBER","version":"2.6.0","metadata":{"vGroup":{},"cluster-type":"default"},"term":1792026308014,"unit":"f5247167-18ab-4f6d-8378-8952019eec67"}]}]}]

命名空间接口（实测）：

curl -s "http://127.0.0.1:8081/api/v1/naming/namespace" -H "Authorization: $TOKEN"

{"code":"200","message":"success","data":{"public":{"clusters":["default"],"vgroups":[]}},"success":true}

主要 REST API 一览（前缀 /api/v1/naming，实测自 jar 包内接口定义）：

接口用途
POST /register、/batchRegister、/unregisterTC 实例注册/批量注册/注销（服务端间调用）
GET /clusters?namespace=public集群与实例监控
GET /clusterData集群数据
GET /discovery客户端服务发现
POST /addGroup、/changeGroup事务组增改
GET /namespace命名空间列表
GET /watch、/watchList变更监听
POST /api/v1/auth/login控制台登录（JSON body）

浏览器访问 http://<host>:8081/ 即控制台 UI，用同一账号登录后可视化管理集群与事务组。

五、注意事项

  1. 必须用 bash 执行脚本：sh bin/seata-server.sh 在 Ubuntu（dash 解释器）下报 bin/seata-server.sh: 34: Bad substitution，脚本用了 bash 特有语法。
  2. -h 不是 help：2.6.0 中 -h/--host 指定注册 IP，打印帮助要用 --help；不带值运行 -h 会报 Error: Host value is required。
  3. stop 优于 kill：seata-server.sh stop 发优雅停机请求；kill -9 会跳过清理，好在 TC 重启后恢复线程会根据 global_table 残留记录继续推进（重试死信由 retry-dead-threshold: 70000 毫秒兜底），但生产仍应优先 stop。
  4. 单机多实例的端口：除 8091 外，9898（指标）同样默认占用，两个实例同时启动会失败一个；生产每机单实例，多节点走集群部署。
  5. 日志路径跟随运行用户：默认 ${user.home}/logs/seata，以 root 运行就是 /root/logs/seata；systemd 托管时用非 root 用户运行，日志会落到该用户家目录，巡检脚本要对应调整。
  6. namingserver 与 seata-server 的 JDK 要求不同：前者需 JDK 25+（class 版本 69.0），后者 JDK 8~17 即可；用 JDK 17 启动 namingserver 会直接抛 UnsupportedClassVersionError。

六、常见问题（FAQ）

Q1：seata-server.sh stop 后进程还在？

stop 是发 shutdown 请求异步等待。若 5 秒后进程仍在（多见于卡在回滚恢复线程），按 PID 兜底清理后重启：

ps -ef | grep '[s]eata-server.jar' | awk '{print $2}' | xargs -r kill
sleep 3
ps -ef | grep '[s]eata-server.jar' | wc -l

实测输出：

0

Q2：启动失败但日志没有明显报错？

先看 stdout 重定向文件与 error 日志两处：tail -30 /tmp/seata-start.log 和 tail -30 /root/logs/seata/seata-server.8091.error.log。常见原因是端口被残留进程占用（报 seata server start failed，9898/8091 冲突），用 ss -lntp | grep -E ':8091|:9898' 定位占用进程。

Q3：控制台登录接口返回 400？

登录接口只接受 JSON body。直接把账号密码拼在 URL 上（如 ?username=admin&password=q1w2e3r4）实测返回 400 Bad Request，必须加 -H 'Content-Type: application/json' 并用 -d '{"username":"admin","password":"q1w2e3r4"}' 传参。

Q4：jps 命令不存在？

openjdk-17-jre-headless 不含 jps。改用 ps -ef | grep '[s]eata-server.jar' 验证进程，或改装 apt-get install -y openjdk-17-jdk-headless。

Q5：如何确认某次配置修改真的生效了？

三个证据点任取其一：日志确认（grep 'store mode' /root/logs/seata/seata-server.8091.all.log 显示 store mode: db）、进程命令行确认（ps -ef 里的 -p 8091 等参数）、端口监听确认（ss -lntp）。日志里的 seata server started in 1122 millSeconds 表示本次是新进程而非旧进程残留。

Q6：mysql 查询 global_table 提示表不存在？

db 模式必须先导入建表脚本：mysql -h seata-db -uroot -pq1w2e3r4 seata < /opt/seata/seata-server/script/server/db/mysql.sql，且库要提前创建（官方 SQL 无建库语句）。

七、参考链接