Apache ShardingSphere-JDBC 运行模式（Mode）的官方 YAML 配置文档-优快云博客

Apache ShardingSphere-JDBC 运行模式（Mode）的官方 YAML 配置文档，这是理解其核心架构的关键。以下是对该文档的深度解析与补充说明，结合核心概念和实战经验：

一、模式配置（`mode`）的核心作用

mode:
  type: Cluster  # 或 Standalone
  repository:
    type: ZooKeeper  # 注册中心类型
    props:
      namespace: governance_db
      server-lists: "localhost:2181"
      max-retries: 3
      operation-timeout-milliseconds: 5000
  overwrite: false  # 首次初始化必须设为 true！

功能定位：

定义 ShardingSphere-JDBC 实例的运行方式和配置管理机制，直接影响：

配置存储位置（本地文件 vs 注册中心）
配置生效方式（重启生效 vs 动态推送）
集群治理能力（故障转移、弹性扩缩容）

二、两种模式深度对比

1. 单机模式 (`Standalone`)

mode:
  type: Standalone
  repository:
    type: File  # 仅支持文件存储
    props:
      path: /config/sharding.yaml  # 本地配置路径

特点：
- 📁 配置存储在 应用本地 YAML 文件
- 🔌 修改配置需重启应用
- 🚫 无动态治理能力（如熔断、禁用数据源）
适用场景：
- 开发测试环境
- 小型单体应用
- 无需动态变更的稳定分片规则

2. 集群模式 (`Cluster`)

mode:
  type: Cluster
  repository:
    type: ZooKeeper  # 支持 Nacos/Etcd/ZK
    props:
      namespace: production_db  # 环境隔离
      server-lists: "zk1:2181,zk2:2181"  # 集群地址
      retry-interval-milliseconds: 500   # 容错参数
      time-to-live-seconds: 60           # 临时节点存活时间
  overwrite: false  # 生产环境必须为 false！

核心机制：
- 🧠 配置存储在 注册中心（ZK/Nacos/Etcd）
- ⚡ 动态生效：修改注册中心配置 → 秒级同步到所有实例
- 🛡️ 启用治理中心：支持数据源熔断、禁用、分片变更等高级功能
生产环境必选：
- 微服务架构下的多实例部署
- 需要动态调整分片策略（如扩容分片数）
- 高可用需求（自动故障转移）

三、关键配置项解析

1. `repository.type`：注册中心类型

类型	特点	适用场景
`ZooKeeper`	强一致性，可靠性高	金融/传统企业生产环境
`Nacos`	易用性强，支持配置管理	云原生/K8s 环境
`Etcd`	高并发性能好	大规模分布式系统

2. `overwrite`：配置覆盖策略

值	含义	使用场景
`true`	强制覆盖注册中心配置（用本地配置替换）	首次启动初始化配置
`false`	保护模式：只读取注册中心配置，忽略本地配置	生产环境常规运行

⚠️ 致命陷阱：生产环境若误设为 true，会导致集群配置被本地文件覆盖！

3. 注册中心参数优化

props:
  max-retries: 5                      # 注册中心连接重试次数
  operation-timeout-milliseconds: 3000 # 操作超时时间（毫秒）
  retry-interval-milliseconds: 500    # 重试间隔
  time-to-live-seconds: 30            # 临时节点存活时间（影响故障检测速度）

四、集群模式工作流程（核心）

五、最佳实践与避坑指南

环境隔离：

props:
  namespace: dev_shop_db  # 开发环境
  # namespace: prod_payment_db  # 生产环境

用 namespace 隔离不同环境的配置，避免互相污染

首次启动流程：

# 步骤1：设置 overwrite=true 初始化配置
sharding:
  mode:
    overwrite: true

# 步骤2：启动应用 → 配置写入注册中心

# 步骤3：改为 overwrite=false 重启应用
sharding:
  mode:
    overwrite: false  # 进入生产运行模式

动态扩展示例：
- 场景：从 2 个分库扩容到 4 个
- 操作：
  1. 在注册中心修改分片规则 sharding-count: 2 → 4
  2. 无需重启应用 → 所有实例自动加载新规则
  3. 注意：需提前完成数据迁移！

注册中心高可用配置：

props:
  server-lists: "zk1:2181,zk2:2181,zk3:2181"  # 至少3节点集群
  max-retries: 10  # 网络波动时增加重试

六、与治理中心的联动

当启用 Cluster 模式时，自动激活 治理中心能力：

# 示例：动态禁用问题数据源
POST /governance/datasource/disable
{
  "schemaName": "sharding_db",
  "dataSourceName": "ds_slave_0",
  "duration": 300  # 禁用300秒
}

治理功能包括：

数据源熔断/禁用
动态分片规则修改
SQL 日志审计
分布式锁管理

总结：

Standalone = 简单但静态，适合非核心场景
Cluster = 复杂但强大，生产环境必选
overwrite 是安全关键：首次 true → 后续永远 false
注册中心选型：ZK 适合强一致，Nacos 适合云原生

建议在测试环境完成 Cluster 模式的全链路验证（配置推送 → 动态修改 → 故障转移）后再上生产。

Apache ShardingSphere-JDBC 运行模式（Mode）的官方 YAML 配置文档

一、模式配置（mode）的核心作用

二、两种模式深度对比

1. 单机模式 (Standalone)

2. 集群模式 (Cluster)