Apache ShardingSphere 安装指南

目标：在真实 Ubuntu 22.04 服务器上从零安装 Apache ShardingSphere 5.5.3 Proxy（MySQL 协议的分布式数据库代理端），覆盖 JDK 前置、官方下载解压、global.yaml 与 database-sharding.yaml 分片配置、bin/start.sh 启动、mysql 客户端验证分片路由、systemd 托管与实测踩坑排障。以下命令与回显均在 Ubuntu 22.04 真实环境逐步实测。

一、环境信息

操作系统：Ubuntu 22.04（x86_64）
Java：OpenJDK 17.0.20.1（openjdk-17-jre-headless + openjdk-17-jdk-headless，后者含 jps）
Apache ShardingSphere：5.5.3（apache-shardingsphere-5.5.3-shardingsphere-proxy-bin.tar.gz，140222158 字节）
安装目录：/opt/shardingsphere
代理监听端口：3307
管理账号：root / q1w2e3r4
后端数据源：H2 文件库 ds_0 / ds_1（发行包内置 h2-2.2.224.jar，演示用零依赖方案）
元数据存储：Standalone 模式 + JDBC（H2 内存库）
mysql 客户端：8.0.46（default-mysql-client，ShardingSphere-Proxy 兼容 MySQL 协议，可直接连接）

二、前置条件

一台 Ubuntu 22.04 服务器，root 权限。
可访问 Apache 官方下载站 dlcdn.apache.org（或对应镜像站）。
依赖软件包：openjdk-17-jre-headless、openjdk-17-jdk-headless（含 jps）、wget、net-tools（含 netstat）、procps、curl、unzip、default-mysql-client。

💡 说明：ShardingSphere-Proxy 前端是 MySQL 协议服务端，任何 MySQL 客户端（含 mysql 命令行）都可直接连接使用，无需额外驱动。

三、版本选型说明

组件	推荐版本	说明
Apache ShardingSphere-Proxy	5.5.3	当前官方版本目录 `dlcdn.apache.org/shardingsphere/` 下唯一在维护的版本
OpenJDK	17	5.5.3 发行包按 Java 17 运行，启动脚本自动追加 `-XX:+SegmentedCodeCache -XX:+AggressiveHeap`
mysql 客户端	8.0.x	用于连接 Proxy 的 3307 端口并执行验证 SQL

5.5.3 官方发行包清单（版本目录下全部文件）：

发行包	大小	用途
`apache-shardingsphere-5.5.3-shardingsphere-proxy-bin.tar.gz`	134M	Proxy 代理端二进制包（本指南安装对象）
`apache-shardingsphere-5.5.3-shardingsphere-jdbc-bin.tar.gz`	15M	JDBC 接入端（应用内嵌，无需独立进程）
`apache-shardingsphere-5.5.3-shardingsphere-agent-bin.tar.gz`	45M	可观测性 Agent（链路追踪/指标插件）
`apache-shardingsphere-5.5.3-src.zip`	21M	源码包

⚠️ 5.5.x 发行包的配置文件名已与旧版不同：global.yaml 取代旧名 server.yaml，database-sharding.yaml 取代旧名 config-sharding.yaml。网上多数旧教程使用旧名，照抄会找不到文件。

四、部署步骤

4.1 安装基础依赖与 JDK

apt-get update -qq
DEBIAN_FRONTEND=noninteractive apt-get install -y openjdk-17-jre-headless openjdk-17-jdk-headless wget net-tools procps curl unzip default-mysql-client

验证版本回显：

# java -version
openjdk version "17.0.20.1" 2026-08-18
OpenJDK Runtime Environment (build 17.0.20.1+1-1-22.04-Ubuntu)
OpenJDK 64-Bit Server VM (build 17.0.20.1+1-1-22.04-Ubuntu, mixed mode, sharing)

# mysql --version
mysql  Ver 8.0.46-0ubuntu0.22.04.4 for Linux on x86_64 ((Ubuntu))

4.2 下载发行包

cd /opt && wget https://dlcdn.apache.org/shardingsphere/5.5.3/apache-shardingsphere-5.5.3-shardingsphere-proxy-bin.tar.gz

确认文件大小：

# ls -l apache-shardingsphere-5.5.3-shardingsphere-proxy-bin.tar.gz
-rw-r--r-- 1 root root 140222158 Feb 23  2026 apache-shardingsphere-5.5.3-shardingsphere-proxy-bin.tar.gz

4.3 解压与目录布局

tar -xzf apache-shardingsphere-5.5.3-shardingsphere-proxy-bin.tar.gz
mv apache-shardingsphere-5.5.3-shardingsphere-proxy-bin shardingsphere

解压后目录结构：

# ls shardingsphere/
LICENSE  NOTICE  README.txt  agent  bin  conf  lib  licenses

关键子目录：

目录/文件	说明
`conf/`	配置目录（见 4.5/4.6 编写内容）
`bin/`	`start.sh / stop.sh / start.bat` 三个启停脚本
`lib/`	357 个 jar，含 `h2-2.2.224.jar`（后端可直接用 H2）及 mysql-connector 相关包（打包为 `shardingsphere-*-mysql-5.5.3.jar`）
`agent/`	可观测性 Agent 目录
`logs/`	首次启动后生成，`stdout.log` 为运行日志

conf/ 目录发行包自带文件（5.5.3 新命名）：

database-encrypt.yaml / database-mask.yaml / database-readwrite-splitting.yaml /
database-shadow.yaml / database-sharding.yaml / global.yaml / logback.xml

4.4 预处理发行包缺失依赖的扩展 jar

5.5.3 发行包存在两处实测踩坑：lib/ 内的 Hive 连接器 jar 缺失 hive-jdbc 依赖导致首次启动即崩（见「九、常见问题」9.1）；Seata AT 事务 jar 缺失 seata-core 导致首条 SQL 报错（见 9.4）。不使用 Hive 与 Seata 时，先把这两个 jar 移出 lib/ 目录：

mkdir -p /opt/shardingsphere/lib.disabled
mv /opt/shardingsphere/lib/shardingsphere-database-connector-hive-5.5.3.jar /opt/shardingsphere/lib.disabled/
mv /opt/shardingsphere/lib/shardingsphere-transaction-base-seata-at-5.5.3.jar /opt/shardingsphere/lib.disabled/

💡 之后若确实需要 Hive 或 Seata，把 jar 移回 lib/ 并补齐对应依赖即可；演示与常规分片场景用不到它们。

4.5 移除演示配置并编写 global.yaml

conf/ 下除 global.yaml、logback.xml 外的 database-*.yaml 均为官方演示配置（引用不存在的 MySQL 数据源），不删除会随启动一并加载而报错：

cd /opt/shardingsphere/conf
rm -f database-encrypt.yaml database-mask.yaml database-readwrite-splitting.yaml database-shadow.yaml database-sharding.yaml

编辑 /opt/shardingsphere/conf/global.yaml，全文如下（Standalone 模式 + JDBC 元数据存储 + root 管理账号）：

mode:
  type: Standalone
  repository:
    type: JDBC
    props:
      provider: H2
      jdbc_url: jdbc:h2:mem:config;DB_CLOSE_DELAY=-1;MODE=MySQL
      username: sa
      password: ""

authority:
  users:
    - user: root@%
      password: q1w2e3r4
      admin: true
  privilege:
    type: ALL_PERMITTED

props:
  sql-show: true
  proxy-backend-query-fetch-size: 1000
  proxy-default-port: 3307

⚠️ 元数据 jdbc_url 结尾的 ;MODE=MySQL 不能省：JDBC 元数据仓库建表 DDL 使用了 INDEX idx_key(...) 内联索引语法，仅 H2 的 MySQL 兼容模式支持，缺省即启动失败（见 9.2）。

⚠️ 元数据存储不要用 H2 文件库（jdbc:h2:file:...）：5.5.3 重启加载版本节点内容为空会直接崩溃（见 9.3），Standalone 模式用 H2 内存库即可——重启后元数据由 YAML 重建，业务数据在数据源文件库中不受影响。

4.6 编写 database-sharding.yaml 并创建数据目录

编辑 /opt/shardingsphere/conf/database-sharding.yaml，全文如下（逻辑库 sharding_db，双 H2 文件数据源，t_order 按 order_id 取模分片）：

databaseName: sharding_db

dataSources:
  ds_0:
    url: jdbc:h2:file:/opt/shardingsphere/data/ds_0;MODE=MySQL;DB_CLOSE_DELAY=-1
    username: sa
    password: ""
    connectionTimeoutMilliseconds: 30000
    idleTimeoutMilliseconds: 60000
    maxLifetimeMilliseconds: 1800000
    maxPoolSize: 10
    minPoolSize: 1
  ds_1:
    url: jdbc:h2:file:/opt/shardingsphere/data/ds_1;MODE=MySQL;DB_CLOSE_DELAY=-1
    username: sa
    password: ""
    connectionTimeoutMilliseconds: 30000
    idleTimeoutMilliseconds: 60000
    maxLifetimeMilliseconds: 1800000
    maxPoolSize: 10
    minPoolSize: 1

rules:
- !SHARDING
  tables:
    t_order:
      actualDataNodes: ds_${0..1}.t_order
      databaseStrategy:
        standard:
          shardingColumn: order_id
          shardingAlgorithmName: t_order_inline
  shardingAlgorithms:
    t_order_inline:
      type: INLINE
      props:
        algorithm-expression: ds_${order_id % 2}

创建 H2 文件库所在目录：

mkdir -p /opt/shardingsphere/data

4.7 调整 JVM 堆内存并启动

启动脚本默认堆为 -Xmx2g -Xms2g -Xmn1g（脚本内 DEFAULT_JAVA_MEM_COMMON_OPTS），通过环境变量 JAVA_MEM_COMMON_OPTS 覆盖为 256-512MB 并启动，监听 3307：

cd /opt/shardingsphere && JAVA_MEM_COMMON_OPTS=" -Xms256m -Xmx512m -Xmn128m " bin/start.sh 3307

启动回显：

we find java version: java17, full_version=17.0.20.1, full_path=/usr/bin/java
The port is 3307
The classpath is /opt/shardingsphere/conf:.:/opt/shardingsphere/lib/*:/opt/shardingsphere/ext-lib/*
main class org.apache.shardingsphere.proxy.Bootstrap 3307 /opt/shardingsphere/conf 0.0.0.0
Starting the ShardingSphere-Proxy ... PID: 5412
Please check the STDOUT file: /opt/shardingsphere/logs/stdout.log

⚠️ start.sh 后台拉起 JVM 后立即返回，命令退出码 0 不代表启动成功；务必检查 3307 监听与 logs/stdout.log（成功标志见 4.8）。

4.8 验证端口、进程与启动日志

netstat -tlnp | grep 3307

tcp6   0   0 :::3307   :::*   LISTEN   5412/java

确认 JVM 堆覆盖已生效（应看到 -Xms256m -Xmx512m -Xmn128m）：

ps -ef | grep [j]ava

root  5412  1 23 02:37 ? 00:00:08 /usr/bin/java -Djava.awt.headless=true -server -Xms256m -Xmx512m -Xmn128m -Xss1m -XX:AutoBoxCacheMax=4096 -XX:+UseNUMA -XX:+DisableExplicitGC -XX:LargePageSizeInBytes=128m -XX:+SegmentedCodeCache -XX:+AggressiveHeap -Dio.netty.leakDetection.level=DISABLED -classpath /opt/shardingsphere/conf:.:/opt/shardingsphere/lib/*:/opt/shardingsphere/ext-lib/* org.apache.shardingsphere.proxy.Bootstrap 3307 /opt/shardingsphere/conf 0.0.0.0

jps -v | grep Bootstrap

5412 Bootstrap -Djava.awt.headless=true -Xms256m -Xmx512m -Xmn128m -Xss1m -XX:AutoBoxCacheMax=4096 -XX:+UseNUMA -XX:+DisableExplicitGC -XX:LargePageSizeInBytes=128m -XX:+SegmentedCodeCache -XX:+AggressiveHeap -Dio.netty.leakDetection.level=DISABLED

启动成功标志（logs/stdout.log 中三行关键日志，实测如下）：

[INFO ] 2026-10-12 02:57:10.158 [main] com.cedarsoftware.util.MultiKeyMap - MultiKeyMap stripe configuration: 32 locks for 12 cores
[INFO ] 2026-10-12 02:57:11.175 [main] o.a.s.p.v.ShardingSphereProxyVersion - Database type is `H2`, version is `2.2.224 (2023-09-17)`, database name is `sharding_db`
[INFO ] 2026-10-12 02:57:11.460 [main] o.a.s.p.frontend.ShardingSphereProxy - ShardingSphere-Proxy Standalone mode started successfully
[INFO ] 2026-10-12 02:57:11.460 [main] o.a.s.p.frontend.ShardingSphereProxy - Instance id: 8264f283-f24e-499b-8f4f-60feeb30bfea, IP: 172.17.0.3, port: 3307

五、配置说明

5.1 conf 目录文件职责

文件	职责
`global.yaml`	全局配置：运行模式与元数据存储（mode）、前端登录账号与权限（authority）、属性项（props）
`database-sharding.yaml`	逻辑库配置：数据源（dataSources）与分片规则（rules）；每个逻辑库一个 `database-*.yaml` 文件
`logback.xml`	日志输出格式与级别

💡 5.5.x 中 global.yaml 即旧版 server.yaml，database-sharding.yaml 即旧版 config-sharding.yaml，参数逐项详解见《Apache ShardingSphere 配置参数详解》。

5.2 JVM 堆内存（256-512MB）

脚本启动：用环境变量覆盖，cd /opt/shardingsphere && JAVA_MEM_COMMON_OPTS=" -Xms256m -Xmx512m -Xmn128m " bin/start.sh 3307（脚本内默认值 DEFAULT_JAVA_MEM_COMMON_OPTS=" -Xmx2g -Xms2g -Xmn1g " 位于 bin/start.sh，Java 17 时脚本自动追加 -XX:+SegmentedCodeCache -XX:+AggressiveHeap）。
systemd 托管：在单元文件中用 Environment=JAVA_MEM_COMMON_OPTS=" -Xms256m -Xmx512m -Xmn128m " 注入（见「七、systemd 托管」）。
生效验证：ps -ef | grep [j]ava 或 jps -v | grep Bootstrap，确认输出含 -Xms256m -Xmx512m -Xmn128m（实测回显见 4.8）。

5.3 端口与日志

监听端口：三处可指定，优先级为 bin/start.sh 3307 命令行参数 > global.yaml 中 props.proxy-default-port > 默认 3307。
运行日志：/opt/shardingsphere/logs/stdout.log（启动失败的第一现场也在这里，见常见问题）。
sql-show: true 时每条 SQL 的 Logic SQL / Actual SQL 路由明细都写入该日志（见 6.3）。

六、mysql 客户端验证分片

6.1 连接并查看逻辑库

mysql -h127.0.0.1 -P3307 -uroot -pq1w2e3r4 -e "SHOW DATABASES;"

mysql: [Warning] Using a password on the command line interface can be insecure.
+-------------+
| Database    |
+-------------+
| sharding_db |
+-------------+

（首行 Warning 是 mysql 客户端对命令行明文密码的常规提醒，不影响结果。）

6.2 建表

mysql -h127.0.0.1 -P3307 -uroot -pq1w2e3r4

mysql> USE sharding_db;
mysql> CREATE TABLE t_order (order_id BIGINT NOT NULL, user_id INT NOT NULL, status VARCHAR(50) NOT NULL, PRIMARY KEY (order_id));
mysql> SHOW TABLES;
+-----------------------+
| Tables_in_sharding_db |
+-----------------------+
| t_order               |
+-----------------------+

6.3 写入数据并验证分片路由

mysql> INSERT INTO t_order (order_id, user_id, status) VALUES (1, 100, 'NEW');
mysql> INSERT INTO t_order (order_id, user_id, status) VALUES (2, 101, 'NEW');
mysql> INSERT INTO t_order (order_id, user_id, status) VALUES (3, 102, 'PAID');
mysql> INSERT INTO t_order (order_id, user_id, status) VALUES (4, 103, 'PAID');
mysql> INSERT INTO t_order (order_id, user_id, status) VALUES (5, 104, 'DONE');
mysql> INSERT INTO t_order (order_id, user_id, status) VALUES (6, 105, 'DONE');

sql-show: true 时，logs/stdout.log 记录 Logic SQL 与按 ds_${order_id % 2} 路由后的 Actual SQL（实测节选，摘录 order_id=4/5/6 的路由行）：

[INFO ] 2026-10-12 02:44:59.122 [ShardingSphere-Command-0] org.apache.shardingsphere.sql - Logic SQL: CREATE TABLE t_order (order_id BIGINT NOT NULL, user_id INT NOT NULL, status VARCHAR(50) NOT NULL, PRIMARY KEY (order_id))
[INFO ] 2026-10-12 02:45:10.485 [ShardingSphere-Command-0] org.apache.shardingsphere.sql - Logic SQL: INSERT INTO t_order (order_id, user_id, status) VALUES (1, 100, "NEW")
[INFO ] 2026-10-12 02:45:10.519 [ShardingSphere-Command-0] org.apache.shardingsphere.sql - Actual SQL: ds_0 ::: INSERT INTO t_order (order_id, user_id, status) VALUES (4, 103, 'PAID')
[INFO ] 2026-10-12 02:45:10.533 [ShardingSphere-Command-0] org.apache.shardingsphere.sql - Actual SQL: ds_1 ::: INSERT INTO t_order (order_id, user_id, status) VALUES (5, 104, 'DONE')
[INFO ] 2026-10-12 02:45:10.544 [ShardingSphere-Command-0] org.apache.shardingsphere.sql - Actual SQL: ds_0 ::: INSERT INTO t_order (order_id, user_id, status) VALUES (6, 105, 'DONE')

（order_id 为偶数路由 ds_0、奇数路由 ds_1，与 ds_${order_id % 2} 表达式一致。）

6.4 查询与路由验证

分片键点查只路由单库：

mysql> SELECT * FROM t_order WHERE order_id = 1;
+----------+---------+--------+
| ORDER_ID | USER_ID | STATUS |
+----------+---------+--------+
|        1 |     100 | NEW    |
+----------+---------+--------+

对应日志（实测：点查 order_id=1 仅路由 ds_1）：

[INFO ] 2026-10-12 02:45:15.476 [ShardingSphere-Command-1] org.apache.shardingsphere.sql - Actual SQL: ds_1 ::: SELECT * FROM t_order WHERE order_id = 1

无分片键的聚合全路由双库并归并结果：

mysql> SELECT COUNT(*) AS cnt FROM t_order;
+------+
| cnt  |
+------+
|    6 |
+------+

对应日志（实测：COUNT 全路由 ds_0 与 ds_1）：

[INFO ] 2026-10-12 02:45:15.530 [ShardingSphere-Command-1] org.apache.shardingsphere.sql - Actual SQL: ds_0 ::: SELECT COUNT(*) AS cnt FROM t_order
[INFO ] 2026-10-12 02:45:15.531 [ShardingSphere-Command-1] org.apache.shardingsphere.sql - Actual SQL: ds_1 ::: SELECT COUNT(*) AS cnt FROM t_order

数据已落盘到 H2 文件库（/opt/shardingsphere/data 下可见 ds_0.mv.db、ds_1.mv.db）。

七、systemd 托管

7.1 停止脚本实例并编写单元文件

先停掉 4.7 用脚本启动的实例：

/opt/shardingsphere/bin/stop.sh

Stopping the ShardingSphere-Proxy ....OK!
PID: 6575

创建 /etc/systemd/system/shardingsphere-proxy.service，内容如下：

[Unit]
Description=Apache ShardingSphere-Proxy 5.5.3
After=network.target

[Service]
Type=forking
Environment=JAVA_MEM_COMMON_OPTS=" -Xms256m -Xmx512m -Xmn128m "
ExecStart=/opt/shardingsphere/bin/start.sh 3307
ExecStop=/opt/shardingsphere/bin/stop.sh
Restart=on-failure
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target

7.2 启用与启动

systemctl daemon-reload
systemctl enable shardingsphere-proxy

Created symlink /etc/systemd/system/multi-user.target.wants/shardingsphere-proxy.service → /etc/systemd/system/shardingsphere-proxy.service.

systemctl start shardingsphere-proxy
systemctl is-active shardingsphere-proxy

active

查看运行状态：

systemctl status shardingsphere-proxy --no-pager -l

● shardingsphere-proxy.service - Apache ShardingSphere-Proxy 5.5.3
     Loaded: loaded (/etc/systemd/system/shardingsphere-proxy.service; enabled; vendor preset: enabled)
     Active: active (running) since Mon 2026-10-12 02:49:57 UTC; 20s ago
    Process: 6388 ExecStart=/opt/shardingsphere/bin/start.sh 3307 (code=exited, status=0/SUCCESS)
   Main PID: 6436 (java)
      Tasks: 34 (limit: 5753)
     Memory: 313.3M
        CPU: 9.522s

7.3 重启验证与数据校验

systemctl restart shardingsphere-proxy
systemctl is-active shardingsphere-proxy

active

重启后再次查询，业务数据保留（元数据由 YAML 重建，H2 文件库数据未丢）：

mysql -h127.0.0.1 -P3307 -uroot -pq1w2e3r4 -D sharding_db -e "SELECT COUNT(*) AS cnt FROM t_order;"

+------+
| cnt  |
+------+
|    6 |
+------+

八、注意事项

元数据 jdbc_url 必须带 ;MODE=MySQL 且使用 H2 内存库（jdbc:h2:mem:），原因见 9.2/9.3。
shardingsphere-database-connector-hive-5.5.3.jar 与 shardingsphere-transaction-base-seata-at-5.5.3.jar 在不使用 Hive/Seata 时保持移出状态，放回即复现 9.1/9.4。
start.sh 是后台启动脚本，判断启动成功以 logs/stdout.log 的 started successfully 行与 3307 监听为准，不以命令退出码为准。
H2 文件库是零依赖的演示后端，生产环境应将 dataSources 指向真实 MySQL 并配套修改连接池参数。
从 5.4.x 升级到 5.5.x 时，先把 server.yaml 更名 global.yaml、config-sharding.yaml 更名 database-sharding.yaml，再对照新参数名调整。

九、常见问题

9.1 首次启动失败：Hive SPI 类缺失

错误回显（logs/stdout.log）：

Exception in thread "main" java.util.ServiceConfigurationError: org.apache.shardingsphere.database.connector.core.jdbcurl.parser.ConnectionPropertiesParser: org.apache.shardingsphere.database.connector.hive.jdbcurl.HiveConnectionPropertiesParser Unable to get public no-arg constructor
Caused by: java.lang.NoClassDefFoundError: org/apache/hive/jdbc/ZooKeeperHiveClientException

定位：lib/ 内 shardingsphere-database-connector-hive-5.5.3.jar 注册了 Hive URL 解析器，但发行包未携带 hive-jdbc 依赖；JVM 启动时 SPI 全量迭代到该 jar 即崩，与是否使用 Hive 后端无关。

解决：不使用 Hive 时执行 mkdir -p /opt/shardingsphere/lib.disabled && mv /opt/shardingsphere/lib/shardingsphere-database-connector-hive-5.5.3.jar /opt/shardingsphere/lib.disabled/（见 4.4），重新启动即可。

9.2 元数据 H2 建表失败：Unknown data type: "IDX_KEY"

错误回显：

Exception in thread "main" org.h2.jdbc.JdbcSQLNonTransientException: Unknown data type: "IDX_KEY"; SQL statement:
CREATE TABLE IF NOT EXISTS `repository`(id varchar(36) PRIMARY KEY, `key` TEXT, `value` TEXT, parent TEXT, INDEX idx_key(`key`), INDEX idx_value(`value`)) [50004-224]

定位：JDBC 元数据仓库建表 DDL 使用 INDEX idx_key(...) 内联索引语法，仅 H2 的 MySQL 兼容模式支持。

解决：global.yaml 中元数据 jdbc_url 结尾必须加 ;MODE=MySQL（见 4.5）。

9.3 元数据用 H2 文件库时重启即崩：NumberFormatException

错误回显：

Exception in thread "main" java.lang.NumberFormatException: For input string: ""
    at org.apache.shardingsphere.mode.metadata.persist.version.VersionPersistService.loadContent(VersionPersistService.java:89)

定位：5.5.3 Standalone 模式把元数据持久化到 H2 文件后，版本节点内容为空，重启加载即失败。

解决：元数据改用内存库 jdbc:h2:mem:config;DB_CLOSE_DELAY=-1;MODE=MySQL（重启后由 YAML 重建元数据，业务数据仍在数据源文件库，实测重启后 COUNT 保持 6）。

9.4 首条 SQL 报 Seata 类缺失

错误回显（logs/stdout.log）：

[ERROR] ... o.a.s.p.f.c.CommandExecutorTask - Exception occur:
java.lang.RuntimeException: java.lang.NoClassDefFoundError: org/apache/seata/core/context/RootContext

定位：lib/ 内 shardingsphere-transaction-base-seata-at-5.5.3.jar 存在，但发行包未携带 seata-core 依赖；连接首条 SQL 触发该类的 SPI 扫描即报错。

解决：不使用 Seata AT 事务时执行 mv /opt/shardingsphere/lib/shardingsphere-transaction-base-seata-at-5.5.3.jar /opt/shardingsphere/lib.disabled/（见 4.4）。

9.5 建表报 H2 fetchSize 非法：Invalid value "-2147483648"

错误回显（客户端）：

ERROR 24472 (90008) at line 2: Invalid value "-2147483648" for parameter "rows" [90008-224]

定位：proxy-backend-query-fetch-size 默认 -1 时，Proxy 按 MySQL 流式查询约定向 H2 驱动下发 Integer.MIN_VALUE（-2147483648），H2 驱动的 setFetchSize 拒绝负值。

解决：global.yaml 的 props 增加 proxy-backend-query-fetch-size: 1000（见 4.5）。

十、卸载方式

systemctl stop shardingsphere-proxy      # 停止服务
systemctl disable shardingsphere-proxy   # 取消开机自启
rm -f /etc/systemd/system/shardingsphere-proxy.service   # 删除单元文件
systemctl daemon-reload
tar -czf /root/shardingsphere-data-backup.tar.gz -C /opt/shardingsphere data   # 可选：备份分片数据文件
rm -rf /opt/shardingsphere               # 删除安装目录（含 lib.disabled、logs、data）
apt-get remove -y openjdk-17-jre-headless openjdk-17-jdk-headless   # 可选：卸载 JDK

十一、参考链接

Apache ShardingSphere 版本目录：https://dlcdn.apache.org/shardingsphere/
Apache ShardingSphere 归档：https://archive.apache.org/dist/shardingsphere/
官方文档（5.5.3 中文）：https://shardingsphere.apache.org/document/5.5.3/cn/overview/
官方 GitHub 仓库：https://github.com/apache/shardingsphere