Apache ShardingSphere 配置参数详解

目标：逐项详解 Apache ShardingSphere-Proxy 5.5.3 的两类配置文件——全局配置 global.yaml（mode、authority、props 三段）与逻辑库配置 database-sharding.yaml（dataSources、rules 分片规则与 INLINE 算法），覆盖每个配置项的含义、取值、生效方式与实测验证。示例配置均在 Ubuntu 22.04 真实环境实测通过。

一、环境信息

操作系统：Ubuntu 22.04（x86_64）
Apache ShardingSphere-Proxy：5.5.3（/opt/shardingsphere）
Java：OpenJDK 17.0.20.1
配置目录：/opt/shardingsphere/conf/（global.yaml、database-sharding.yaml、logback.xml）
监听端口：3307
管理账号：root / q1w2e3r4
后端数据源：H2 文件库 ds_0 / ds_1（/opt/shardingsphere/data/）
元数据存储：Standalone + JDBC（H2 内存库）

二、前置条件

ShardingSphere-Proxy 5.5.3 已安装（安装过程见《Apache ShardingSphere 安装指南》）。
mysql 客户端已安装（运行态查看参数时使用）。
了解 5.5.x 配置文件命名：global.yaml 即旧版（5.4.x 及之前）的 server.yaml；database-sharding.yaml 即旧版的 config-sharding.yaml。

三、参数查看与修改方式

3.1 配置文件位置与加载时机

文件	位置	加载时机
`global.yaml`	`/opt/shardingsphere/conf/global.yaml`	进程启动时加载一次
`database-*.yaml`	`/opt/shardingsphere/conf/database-sharding.yaml` 等	进程启动时按文件名逐个加载，一个文件一个逻辑库
`logback.xml`	`/opt/shardingsphere/conf/logback.xml`	日志框架初始化时加载

3.2 修改与生效方式

直接编辑 conf/ 下的 YAML 文件，然后重启进程生效：

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

active

⚠️ ShardingSphere-Proxy 不做配置文件热加载，改完配置必须重启；重启是否成功以 logs/stdout.log 中 started successfully 行为准。

3.3 运行态查看（RQL 查询）

配置落库后的运行态可通过 mysql 客户端执行 RQL（Refactor Query Language）查看：

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 SHARDING TABLE NODES t_order;"

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

💡 RQL 必须先 USE 逻辑库（或 -D 指定）才能执行，否则报 ERROR 1046 (3D000): No database selected。更多 RQL 命令与回显见《Apache ShardingSphere 常用 CLI 命令与工具详解》。

四、参数总览

5.5.3 的参数分布在两个文件、五个段中：

文件	段	作用
`global.yaml`	`mode`	运行模式与元数据持久化仓库
`global.yaml`	`authority`	前端登录账号、密码与权限
`global.yaml`	`props`	全局属性项（SQL 日志、端口、fetch-size 等）
`database-*.yaml`	`dataSources`	后端物理数据源与连接池
`database-*.yaml`	`rules`	分片、读写分离等规则（本文以 `!SHARDING` 为例）

五、global.yaml 详解

本节逐项解释实测生效的 global.yaml 全文：

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

5.1 mode.type：运行模式

Standalone（本指南实测值）：单实例运行，元数据存本地仓库，适合单机部署与演示。
Cluster：多实例组网，元数据存集中式仓库（如 ZooKeeper），实例间感知配置变更，生产多实例场景使用。
默认值：Standalone。

5.2 mode.repository：元数据持久化仓库

键	实测值	说明
`type`	`JDBC`	通过 JDBC 驱动把元数据存入数据库；Standalone 模式默认即 JDBC + H2 内存库
`props.provider`	`H2`	JDBC 仓库的数据库类型，发行包 `lib/` 自带 `h2-2.2.224.jar`，零依赖
`props.jdbc_url`	`jdbc:h2:mem:config;DB_CLOSE_DELAY=-1;MODE=MySQL`	H2 内存库；`DB_CLOSE_DELAY=-1` 保持库常开；`MODE=MySQL` 必带，否则建表 DDL 的内联索引语法报 `Unknown data type: "IDX_KEY"`
`props.username`	`sa`	H2 默认账号
`props.password`	空	H2 默认无密码

⚠️ 两个实测结论：元数据 jdbc_url 不能省 ;MODE=MySQL；不要改用 jdbc:h2:file: 文件库——5.5.3 重启加载文件库元数据会报 NumberFormatException: For input string: ""。Standalone 用内存库即可，重启后元数据由 YAML 重建，业务数据不受影响。

5.3 authority.users：登录账号

键	实测值	说明
`user`	`root@%`	格式为 `用户名@允许登录的主机`，`%` 表示任意主机；这是客户端连接 Proxy 的账号，与后端数据源账号无关
`password`	`q1w2e3r4`	明文密码，连接 3307 时使用
`admin`	`true`	管理员标记；可执行 RAL/RQL 全部管理命令并可查看全部逻辑库

users 是列表，可配置多个账号；不同账号可通过 privilege 差异化授权。

5.4 authority.privilege：权限类型

ALL_PERMITTED（实测值）：所配账号拥有全部权限，演示与内部工具场景最常用。
需要按库/表细粒度授权时，参考官方文档 authority 章节配置受限权限类型。

5.5 props：全局属性项

实测使用的三个属性：

属性	实测值	说明
`sql-show`	`true`	在 `logs/stdout.log` 打印每条 SQL 的 Logic SQL 与路由后的 Actual SQL；默认 `false`，生产按需开启
`proxy-backend-query-fetch-size`	`1000`	后端查询 fetch size；默认 `-1` 表示按 MySQL 流式约定下发 `Integer.MIN_VALUE`，后端为 H2 时会报 `Invalid value "-2147483648"`，必须显式设为正数
`proxy-default-port`	`3307`	前端监听端口默认值；`bin/start.sh 3307` 命令行参数优先级更高

其他常用属性（默认值取自官方 props 配置项列表，按需选用）：

属性	默认值	说明
`check-table-metadata-enabled`	`false`	是否在启动/刷新时校验实际表结构与元数据一致性
`proxy-frontend-max-connections`	`0`	前端最大连接数，0 表示不限制
`proxy-frontend-executor-size`	`0`	前端执行器线程数，0 表示按 CPU 核数自动计算
`proxy-backend-executor-suitable`	`OLTP`	后端执行器类型，OLTP/OLAP 二选一
`proxy-frontend-ssl-enabled`	`false`	前端是否启用 SSL/TLS（实测启动日志输出 `Proxy frontend SSL/TLS is disabled.` 与默认值一致）

六、database-sharding.yaml 详解

本节逐项解释实测生效的 database-sharding.yaml 全文：

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}

6.1 databaseName：逻辑库名

实测值 sharding_db，客户端 SHOW DATABASES 看到的库名，与 USE sharding_db 对应。
一个 database-*.yaml 文件对应一个逻辑库；多逻辑库就写多个文件。

6.2 dataSources：数据源与连接池

每个数据源（ds_0、ds_1，名称自定义）的键：

键	实测值	说明
`url`	`jdbc:h2:file:/opt/shardingsphere/data/ds_0;MODE=MySQL;DB_CLOSE_DELAY=-1`	后端 JDBC URL；H2 文件库加 `MODE=MySQL` 以兼容 MySQL 语法；生产换成 `jdbc:mysql://<主机>:3306/<库名>` 形态即可，驱动 jar 放 `ext-lib/`
`username` / `password`	`sa` / 空	后端数据库账号，与 5.3 的前端账号互不相干
`connectionTimeoutMilliseconds`	`30000`	获取连接超时 30 秒
`idleTimeoutMilliseconds`	`60000`	空闲连接回收 60 秒
`maxLifetimeMilliseconds`	`1800000`	连接最长存活 30 分钟
`maxPoolSize`	`10`	每数据源最大连接数（Hikari 风格池参数）
`minPoolSize`	`1`	最小保持连接数

6.3 rules-!SHARDING tables：分片规则

键	实测值	说明
`t_order`	—	逻辑表名，客户端建表/查询都用该名字
`actualDataNodes`	`ds_${0..1}.t_order`	真实表分布：`ds_0.t_order`、`ds_1.t_order` 两个真实库
`databaseStrategy.standard.shardingColumn`	`order_id`	库级分片键
`databaseStrategy.standard.shardingAlgorithmName`	`t_order_inline`	指向 6.4 定义的算法名
`tableStrategy`	未配置	表级分片未用时留空；需要单库内再分表时配置 `tableStrategy.standard` 并指定真实表表达式

6.4 shardingAlgorithms：分片算法

键	实测值	说明
`t_order_inline`	—	算法名称，被 6.3 的 `shardingAlgorithmName` 引用
`type`	`INLINE`	行内表达式算法，语法简单、无需额外依赖，适合取模/前缀类路由
`props.algorithm-expression`	`ds_${order_id % 2}`	对分片键求模决定目标库：order_id 偶数路由 ds_0、奇数路由 ds_1（实测路由日志与该表达式一致）

6.5 行内表达式语法

ds_${0..1}：范围枚举，展开为 ds_0、ds_1，用于 actualDataNodes。
ds_${order_id % 2}：对分片键计算的表达式，% 为取模运算，可用于库/表表达式。
INLINE 算法可选属性 allow-range-query-with-inline-sharding（默认 false）：默认情况下不带分片键的范围查询会全路由（实测 SELECT COUNT(*) 同时下发 ds_0 与 ds_1），开启后范围查询也走表达式计算。

七、生产配置模板

适用场景：4 核 16GB 内存、SSD 磁盘、OLTP 分片业务；2 个 MySQL 库作为后端；多实例组网用 Cluster + ZooKeeper 管理元数据。以下为按官方文档整理的生产参考模板（JVM 堆仍按 256-512MB 限定，后端账号密码以实际为准）：

# global.yaml（生产：Cluster 模式 + ZooKeeper 元数据）
mode:
  type: Cluster
  repository:
    type: ZooKeeper
    props:
      namespace: governance_ds
      server-lists: 10.0.0.21:2181,10.0.0.22:2181,10.0.0.23:2181
      retryIntervalMilliseconds: 500
      timeToLiveSeconds: 60
      maxRetries: 3
      operationTimeoutMilliseconds: 500

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

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

# database-sharding.yaml（生产：双 MySQL 库）
databaseName: sharding_db

dataSources:
  ds_0:
    url: jdbc:mysql://10.0.0.11:3306/demo_ds_0?useSSL=false&characterEncoding=utf8
    username: root
    password: q1w2e3r4
    connectionTimeoutMilliseconds: 30000
    idleTimeoutMilliseconds: 60000
    maxLifetimeMilliseconds: 1800000
    maxPoolSize: 50
    minPoolSize: 5
  ds_1:
    url: jdbc:mysql://10.0.0.12:3306/demo_ds_1?useSSL=false&characterEncoding=utf8
    username: root
    password: q1w2e3r4
    connectionTimeoutMilliseconds: 30000
    idleTimeoutMilliseconds: 60000
    maxLifetimeMilliseconds: 1800000
    maxPoolSize: 50
    minPoolSize: 5

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}

⚠️ MySQL 驱动 jar 不在 lib/ 默认清单中时，放入 ext-lib/ 再启动；连接池按业务峰值调大 maxPoolSize（示例 50）。

八、常见问题

8.1 元数据 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 兼容模式支持。

解决：mode.repository.props.jdbc_url 结尾加 ;MODE=MySQL。

8.2 元数据改 H2 文件库后重启崩溃

错误回显：

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；需要元数据集中管理时改用 Cluster + ZooKeeper 而非 H2 文件库。

8.3 建表或查询报 Invalid value "-2147483648" for parameter "rows"

错误回显：

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

定位：proxy-backend-query-fetch-size 默认 -1 按 MySQL 流式约定下发 Integer.MIN_VALUE，H2 驱动拒绝负值。

解决：props 显式配置 proxy-backend-query-fetch-size: 1000。

8.4 修改 props 后行为没变化

定位：global.yaml 仅在进程启动时加载。

解决：systemctl restart shardingsphere-proxy 后以 logs/stdout.log 的 started successfully 为准，再连接执行对应 RQL 核对（如 SHOW SHARDING TABLE RULES;）。

8.5 不确定当前生效的配置

用 RQL 查运行态：SHOW SHARDING TABLE RULES; 看分片规则与算法表达式，SHOW STORAGE UNITS; 看数据源连接池参数，SHOW SHARDING ALGORITHMS; 看算法清单（命令与完整回显见《Apache ShardingSphere 常用 CLI 命令与工具详解》）。

九、参考链接

官方文档（5.5.3 中文）mode/authority/props：https://shardingsphere.apache.org/document/5.5.3/cn/user-manual/shardingsphere-proxy/yaml-config/
行内表达式与内置分片算法：https://shardingsphere.apache.org/document/5.5.3/cn/features/sharding/
官方 GitHub 仓库：https://github.com/apache/shardingsphere