Apache ShardingSphere 常用 CLI 命令与工具详解

目标：详解 Apache ShardingSphere-Proxy 5.5.3 的常用命令行工具——bin/start.sh 与 bin/stop.sh 启停脚本、mysql 客户端连接与 RQL 查询（SHOW SHARDING 系列、SHOW STORAGE UNITS 等）、进程与端口核验、systemd 服务管理、stdout.log 日志运维。所有命令与回显均为真实环境实测。

一、环境信息

操作系统：Ubuntu 22.04（x86_64）
Apache ShardingSphere-Proxy：5.5.3
安装目录：/opt/shardingsphere（脚本 /opt/shardingsphere/bin/）
监听端口：3307
示例账号：root / q1w2e3r4
mysql 客户端：8.0.46（default-mysql-client）
Java：OpenJDK 17.0.20.1（jps 可用）
日志文件：/opt/shardingsphere/logs/stdout.log

二、工具概览

工具/文件	位置	用途
`start.sh`	`/opt/shardingsphere/bin/`	后台启动 Proxy，支持端口/配置目录/JVM 参数
`stop.sh`	`/opt/shardingsphere/bin/`	停止脚本拉起的 Proxy 进程
`mysql`	系统命令	连接 3307 管理逻辑库、执行 RQL 查询与业务 SQL
`jps`	JDK 自带	查看 Java 进程与 JVM 参数生效值
`netstat`	`net-tools` 包	校验 3307 端口监听
`systemctl`	系统自带	systemd 托管启停与状态查看
`stdout.log`	`/opt/shardingsphere/logs/`	启动日志、SQL 路由日志与排障第一现场

三、前置条件

ShardingSphere-Proxy 5.5.3 已安装并完成基础配置（conf/global.yaml 与 conf/database-sharding.yaml，见《Apache ShardingSphere 安装指南》）。
已安装 openjdk-17-jdk-headless（含 jps）、net-tools、default-mysql-client。

四、工具详解

4.1 start.sh 启动脚本

查看用法：

/opt/shardingsphere/bin/start.sh -h

完整回显（实测）：

usage:
start.sh [port] [config_dir]
  port: proxy listen port, default is 3307
  config_dir: proxy config directory, default is 'conf'

start.sh [-a addresses] [-p port] [-c /path/to/conf] [-g] [-s /path/to/socket]
The options are unordered.
-a  Bind addresses, can be IPv4, IPv6, hostname. In
    case more than one address is specified in a
    comma-separated list. The default value is '0.0.0.0'.
-p  Bind port, default is '3307', which could be changed in global.yaml
-c  Path to config directory of ShardingSphere-Proxy, default is 'conf'

要点：

两种形态：位置参数 start.sh [port] [config_dir]，或无序选项 -a（绑定地址，默认 0.0.0.0）、-p（端口，默认 3307）、-c（配置目录，默认 conf）。
JVM 堆：脚本内置默认 -Xmx2g -Xms2g -Xmn1g，用环境变量 JAVA_MEM_COMMON_OPTS 覆盖；Java 17 时脚本自动追加 -XX:+SegmentedCodeCache -XX:+AggressiveHeap。

启动示例（覆盖堆为 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

4.2 stop.sh 停止脚本

/opt/shardingsphere/bin/stop.sh

回显（实测）：

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

⚠️ stop.sh 只停止通过 start.sh 拉起的进程；systemd 托管场景请用 systemctl stop shardingsphere-proxy（其 ExecStop 同样调用 stop.sh）。

4.3 mysql 客户端连接与管理

连接 Proxy（MySQL 协议，端口 3307）：

mysql -h127.0.0.1 -P3307 -uroot -pq1w2e3r4

查看逻辑库与建表（实测回显）：

mysql> SHOW DATABASES;
+-------------+
| Database    |
+-------------+
| sharding_db |
+-------------+

mysql> USE sharding_db;
mysql> SHOW TABLES;
+-----------------------+
| Tables_in_sharding_db |
+-----------------------+
| t_order               |
+-----------------------+

免交互执行（-e 适合脚本巡检）：

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 客户端对命令行明文密码的常规提醒，不影响结果。）

4.4 RQL 查询命令（SHOW 系列）

RQL（Refactor Query Language）用于查询运行态元数据，必须在已选择逻辑库的前提下执行（交互式先 USE sharding_db;，或命令行加 -D sharding_db）。

查看分片表规则全量：

mysql -h127.0.0.1 -P3307 -uroot -pq1w2e3r4 --table -D sharding_db -e "SHOW SHARDING TABLE RULES;"

回显（--table 表格输出，实测）：

+---------+--------------------+---------------------+------------------------+--------------------------+----------------------------------+-----------------------------------------------+---------------------+-----------------------+-------------------------------+--------------------------------+---------------------+--------------------+---------------------+---------------+--------------------+
| table   | actual_data_nodes  | actual_data_sources | database_strategy_type | database_sharding_column | database_sharding_algorithm_type | database_sharding_algorithm_props             | table_strategy_type | table_sharding_column | table_sharding_algorithm_type | table_sharding_algorithm_props | key_generate_column | key_generator_type | key_generator_props | auditor_types | allow_hint_disable |
+---------+--------------------+---------------------+------------------------+--------------------------+----------------------------------+-----------------------------------------------+---------------------+-----------------------+-------------------------------+--------------------------------+---------------------+--------------------+---------------------+---------------+--------------------+
| t_order | ds_${0..1}.t_order |                     | STANDARD               | order_id                 | INLINE                           | {"algorithm-expression":"ds_${order_id % 2}"} |                     |                       |                               |                                |                     |                    |                     |               |                    |
+---------+--------------------+---------------------+------------------------+--------------------------+----------------------------------+-----------------------------------------------+---------------------+-----------------------+-------------------------------+--------------------------------+---------------------+--------------------+---------------------+---------------+--------------------+

查看单表规则（列结构同上，仅返回指定表一行）：

mysql -h127.0.0.1 -P3307 -uroot -pq1w2e3r4 --table -D sharding_db -e "SHOW SHARDING TABLE RULE t_order;"

回显（实测）：返回 t_order 一行，各列取值与 SHOW SHARDING TABLE RULES; 中 table = t_order 行完全一致（actual_data_nodes 为 ds_${0..1}.t_order、database_strategy_type 为 STANDARD、分片列 order_id、算法 INLINE 及其表达式）。

查看逻辑表的分片节点：

mysql -h127.0.0.1 -P3307 -uroot -pq1w2e3r4 --table -D sharding_db -e "SHOW SHARDING TABLE NODES t_order;"

回显（实测）：

+---------+----------------------------+
| name    | nodes                      |
+---------+----------------------------+
| t_order | ds_0.t_order, ds_1.t_order |
+---------+----------------------------+

查看分片算法清单：

mysql -h127.0.0.1 -P3307 -uroot -pq1w2e3r4 --table -D sharding_db -e "SHOW SHARDING ALGORITHMS;"

回显（实测）：

+----------------+--------+-----------------------------------------------+
| name           | type   | props                                         |
+----------------+--------+-----------------------------------------------+
| t_order_inline | INLINE | {"algorithm-expression":"ds_${order_id % 2}"} |
+----------------+--------+-----------------------------------------------+

查看存储单元（数据源连接信息，列较多，实测节选主要列）：

mysql -h127.0.0.1 -P3307 -uroot -pq1w2e3r4 --table -D sharding_db -e "SHOW STORAGE UNITS;"

回显（节选 name/type/host/port/db 列）：

+------+------+------+------+------+
| name | type | host | port | db   |
+------+------+------+------+------+
| ds_0 | H2   |      | -1   | ds_0 |
| ds_1 | H2   |      | -1   | ds_1 |
+------+------+------+------+------+

（完整输出还有 connection_timeout_milliseconds、idle_timeout_milliseconds、max_lifetime_milliseconds、max_pool_size、min_pool_size、read_only、other_attributes 列；实测 read_only 均为 false，other_attributes 含 Hikari 池参数与 {"model":"file:"} 查询属性。）

4.5 进程与端口核验

确认 JVM 进程与堆生效值（实测）：

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

确认 3307 监听（实测）：

netstat -tlnp | grep 3307

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

4.6 systemd 服务管理

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

systemctl restart shardingsphere-proxy  # 重启
systemctl stop shardingsphere-proxy     # 停止（ExecStop 调用 stop.sh，回显同 4.2）

4.7 日志运维（logs/stdout.log）

启动成功关键行（实测）：

grep -E "started successfully|Instance id" /opt/shardingsphere/logs/stdout.log | tail -2

[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

sql-show: true 时查看 SQL 路由明细（Logic SQL 与 Actual SQL）：

grep "org.apache.shardingsphere.sql" /opt/shardingsphere/logs/stdout.log | tail -3

[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
[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

实时跟踪与错误检索：

tail -f /opt/shardingsphere/logs/stdout.log       # 实时跟踪
grep -n "ERROR" /opt/shardingsphere/logs/stdout.log   # 检索错误

💡 启动失败（如 Hive SPI 类缺失、H2 元数据建表失败）的第一现场都在 stdout.log，排障路径见《Apache ShardingSphere 安装指南》常见问题 9.1-9.5。

五、注意事项

start.sh 后台拉起 JVM 后立即返回，退出码 0 不代表启动成功；以 stdout.log 的 started successfully 与 3307 监听为准。
RQL 命令必须先选择逻辑库，未选库直接报 ERROR 1046 (3D000): No database selected（见 FAQ 6.1）。
--table 仅改变 mysql 客户端的展示格式，便于人读与截图核对，结果内容一致。
sql-show: true 会为每条 SQL 输出两行日志，生产环境长期开启会显著增大日志量，排障期开启即可。
systemd 托管与脚本启动不要混用：stop.sh 只认 start.sh 记录的进程，systemd 场景统一用 systemctl。

六、常见问题

6.1 执行 SHOW SHARDING ALGORITHMS 报 No database selected

错误回显（实测）：

ERROR 1046 (3D000) at line 1: No database selected

定位：RQL 属于逻辑库上下文内的查询，未选择逻辑库时无法确定查询目标。

解决：交互式会话先执行 USE sharding_db;，或命令行加 -D sharding_db。

6.2 start.sh 正常返回但 3307 未监听

排查路径：

tail -50 /opt/shardingsphere/logs/stdout.log

定位：首因通常是两类——lib/ 中 Hive 连接器 jar 缺依赖导致 SPI 初始化即崩（回显与解决见《Apache ShardingSphere 安装指南》9.1），或 global.yaml 元数据 H2 缺 ;MODE=MySQL 建表失败（见同篇 9.2/9.3）。

解决：按对应 FAQ 移除问题 jar 或修正 jdbc_url 后重新启动。

6.3 mysql 客户端连接 3307 被拒绝

排查顺序：

systemctl is-active shardingsphere-proxy
netstat -tlnp | grep 3307
tail -5 /opt/shardingsphere/logs/stdout.log

定位：is-active 非 active 说明服务未运行；端口未监听说明启动失败（走 6.2）；端口正常仍被拒则核对 global.yaml 中 authority.users 的账号密码与连接命令一致。

七、参考链接

官方文档（5.5.3 中文）Proxy DistSQL/RQL：https://shardingsphere.apache.org/document/5.5.3/cn/reference/distsql/syntax/rlql/
官方 GitHub 仓库：https://github.com/apache/shardingsphere
相关篇：《Apache ShardingSphere 安装指南》《Apache ShardingSphere 配置参数详解》