Apache ShardingSphere Docker Compose 部署指南

目标：使用 Docker Compose 一键部署 Apache ShardingSphere-Proxy 5.5.3 官方镜像（MySQL 协议分布式数据库代理端），通过挂载 conf/data 实现配置与数据持久化，端口 3307 映射到宿主机，JVM 堆限定 256-512MB，并实测验证重启后分片数据保留。全程命令与回显均为实际执行结果。

一、环境信息

宿主机操作系统：Ubuntu 22.04（x86_64）
Docker Compose：v5.5.1（docker compose 子命令形态）
镜像：apache/shardingsphere-proxy:5.5.3（814MB，内置 JDK jdk-25.0.2+10）
Compose 项目目录：/opt/ss-compose（项目名 ss-compose）
配置挂载：./conf → /opt/shardingsphere-proxy/conf
数据挂载：./data → /opt/shardingsphere-proxy/data
映射端口：3307（Proxy 前端，MySQL 协议）
管理账号：root / q1w2e3r4
后端数据源：H2 文件库 ds_0 / ds_1（镜像内置 H2，演示用零依赖方案）
mysql 客户端：8.0.46（用于连接验证）

二、镜像选型说明

镜像	说明
`apache/shardingsphere-proxy:5.5.3`	官方发布镜像，本指南采用；开箱即用，无需自建
自构建镜像（tar 包 + Dockerfile）	仅当内网无法访问 Docker Hub 时考虑，需自行维护 JDK 与发行包版本

官方镜像 apache/shardingsphere-proxy:5.5.3 内置行为（实测确认）：

项	值
安装路径	`/opt/shardingsphere-proxy`
内置 JDK	`jdk-25.0.2+10`（`/opt/java/openjdk`）
`IS_DOCKER` 标记	`true`（启动脚本据此读取 `CGROUP_MEM_OPTS` 计算堆参数）
入口命令	`/bin/sh -c` 调用 `start.sh`，未显式指定端口时默认 3307
`lib/` 目录	已不含 hive connector 与 seata-at 两个问题 jar（二进制发行包在裸装时会因缺依赖导致启动失败，镜像中不存在该缺陷，详见《Apache ShardingSphere 安装指南》常见问题 9.1/9.4）

三、前置条件

装有 Docker 与 Docker Compose 的服务器，root 权限。
能拉取 apache/shardingsphere-proxy:5.5.3 镜像（内网可先配置镜像加速器，见 FAQ 11.1）。
宿主机 3307 端口未被占用。
准备 mysql 客户端用于连接验证。

四、部署步骤

4.1 创建目录结构

mkdir -p /opt/ss-compose/conf /opt/ss-compose/data
cd /opt/ss-compose

4.2 编写 conf/global.yaml

创建 /opt/ss-compose/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 且使用 H2 内存库（jdbc:h2:mem:）：内联索引建表 DDL 仅 H2 MySQL 兼容模式支持；H2 文件库做元数据在 5.5.3 重启会崩溃。两个问题的详细排障见《Apache ShardingSphere 安装指南》常见问题 9.2/9.3。

4.3 编写 conf/database-sharding.yaml

创建 /opt/ss-compose/conf/database-sharding.yaml，全文如下（数据源为挂载到 ./data 的 H2 文件库，注意路径是镜像内路径 /opt/shardingsphere-proxy/data/）：

databaseName: sharding_db

dataSources:
  ds_0:
    url: jdbc:h2:file:/opt/shardingsphere-proxy/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-proxy/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}

4.4 编写 docker-compose.yml

创建 /opt/ss-compose/docker-compose.yml，全文如下（实测生效版）：

services:
  shardingsphere-proxy:
    image: apache/shardingsphere-proxy:5.5.3
    container_name: shardingsphere-proxy
    restart: unless-stopped
    mem_limit: 1g
    ports:
      - "3307:3307"
    environment:
      CGROUP_MEM_OPTS: " -Xms256m -Xmx512m -Xmn128m "
    volumes:
      - ./conf:/opt/shardingsphere-proxy/conf
      - ./data:/opt/shardingsphere-proxy/data

4.5 启动

docker compose up -d

回显（实测）：

 Network ss-compose_default Created
 Container shardingsphere-proxy Creating
 Container shardingsphere-proxy Created
 Container shardingsphere-proxy Starting
 Container shardingsphere-proxy Started

4.6 查看状态与启动日志

docker compose ps

NAME                   IMAGE                               COMMAND                   SERVICE                CREATED        STATUS                  PORTS
shardingsphere-proxy   apache/shardingsphere-proxy:5.5.3   "/bin/sh -c '${LOCAL…"   shardingsphere-proxy   1 second ago   Up Less than a second   0.0.0.0:3307->3307/tcp, [::]:3307->3307/tcp

docker compose logs shardingsphere-proxy

启动成功标志（实测节选）：

... ShardingSphere-Proxy Standalone mode started successfully
... Instance id: c69ef0f9-9831-455f-9091-b280e17ea9c4, IP: 192.168.192.2, port: 3307

💡 IP: 192.168.192.2 是 Compose 内部网络分配给该服务的地址，外部访问一律走宿主机映射端口 3307。

4.7 远程客户端连接验证

从另一台机器（或宿主机网关地址）连接 3307：

mysql -h172.17.0.1 -P3307 -uroot -pq1w2e3r4

实测验证结果：

SHOW DATABASES; 输出逻辑库 sharding_db；
CREATE TABLE t_order (order_id BIGINT NOT NULL, user_id INT NOT NULL, status VARCHAR(50) NOT NULL, PRIMARY KEY (order_id)); 建表成功；
向 t_order 写入 4 条记录；
SELECT COUNT(*) FROM t_order; 返回 4。

五、数据持久化说明

配置持久化：./conf 挂载为镜像内 /opt/shardingsphere-proxy/conf，global.yaml、database-sharding.yaml 均落在宿主机 /opt/ss-compose/conf/，修改后 docker compose restart 生效。
数据持久化：两个 H2 文件库落在宿主机 /opt/ss-compose/data/（ds_0.mv.db、ds_1.mv.db）。
实测：建表并写入 4 条记录后执行 docker compose down && docker compose up -d，重建完成再次查询 SELECT COUNT(*) 仍为 4，./data 卷持久化生效。
元数据（Standalone JDBC H2 内存库）不落盘，重启后由 YAML 配置重建，无需备份；业务数据在 ./data，需要备份时直接打包该目录。

六、常用环境变量表

环境变量	默认值	说明
`CGROUP_MEM_OPTS`	`-XX:InitialRAMPercentage=80.0 -XX:MinRAMPercentage=80.0 -XX:MaxRAMPercentage=80.0`	镜像内启动脚本按可用内存百分比自动计算堆；生产建议像本指南一样覆盖为固定堆（256-512MB）
`JAVA_MEM_COMMON_OPTS`	`-Xmx2g -Xms2g -Xmn1g`（脚本内置默认）	启动脚本堆参数字段；`CGROUP_MEM_OPTS` 显式设置时以 `CGROUP_MEM_OPTS` 为准
`PORT`	3307	入口命令传给 `start.sh` 的监听端口，一般不动，改端口优先用端口映射

七、常用配置参数说明

compose 参数	实测取值	说明
`image`	`apache/shardingsphere-proxy:5.5.3`	官方 5.5.3 镜像，814MB
`container_name`	`shardingsphere-proxy`	固定实例名，便于 `docker exec` 与日志检索
`restart`	`unless-stopped`	异常退出自动拉起，手动停止不拉起
`mem_limit`	`1g`	实例内存上限；堆 256-512MB + 堆外/元数据开销，1g 留足余量
`ports`	`3307:3307`	前端 MySQL 协议端口映射，客户端连宿主机 3307
`environment.CGROUP_MEM_OPTS`	`" -Xms256m -Xmx512m -Xmn128m "`	JVM 堆限定 256-512MB，值前后空格保留脚本拼接习惯
`volumes`	`./conf`、`./data`	配置与数据持久化（见第五、八章）

八、配置文件持久化（conf 挂载）

挂载关系：宿主机 /opt/ss-compose/conf/ → 镜像内 /opt/shardingsphere-proxy/conf/；启动脚本 classpath 中 conf 目录优先于镜像内置默认配置。
镜像内置默认 conf/ 只含空的 global.yaml 模板，挂载后以宿主机文件为准，database-sharding.yaml 等逻辑库文件按文件名逐个加载。
修改配置流程：编辑宿主机 /opt/ss-compose/conf/*.yaml → docker compose restart shardingsphere-proxy → docker compose logs -f shardingsphere-proxy 确认 started successfully。
校验配置生效：连接后执行 SHOW SHARDING TABLE RULES;、SHOW STORAGE UNITS;（命令与回显见《Apache ShardingSphere 常用 CLI 命令与工具详解》）。

九、等价 docker run 运行方式

不用 Compose 时，以下单条 docker run 与 4.4 的 docker-compose.yml 完全等价：

docker run -d \
  --name shardingsphere-proxy \
  --restart unless-stopped \
  --memory 1g \
  -p 3307:3307 \
  -e CGROUP_MEM_OPTS=" -Xms256m -Xmx512m -Xmn128m " \
  -v /opt/ss-compose/conf:/opt/shardingsphere-proxy/conf \
  -v /opt/ss-compose/data:/opt/shardingsphere-proxy/data \
  apache/shardingsphere-proxy:5.5.3

十、常用运维命令

docker compose ps                                   # 查看服务状态
docker compose logs -f shardingsphere-proxy         # 跟踪启动与运行日志
docker compose exec shardingsphere-proxy sh         # 进入实例排障
docker compose restart shardingsphere-proxy         # 重启（配置修改后生效）
docker compose stop shardingsphere-proxy            # 停止
docker compose start shardingsphere-proxy           # 启动
docker compose down                                 # 删除实例（保留 ./conf 与 ./data）
docker compose down -v                              # 删除实例与网络（本项目用 bind mount，数据仍在宿主机）

实例内验证 JVM 堆生效值（实测回显，节选）：

docker exec shardingsphere-proxy sh -c 'ps -ef | grep [j]ava'

root   7   1  30 02:55 ?  00:00:07 /opt/java/openjdk/bin/java -Djava.awt.headless=true -server -Xms256m -Xmx512m -Xmn128m -Xss1m ...

（应看到 -Xms256m -Xmx512m -Xmn128m，说明 CGROUP_MEM_OPTS 覆盖生效。）

十一、常见问题（FAQ）

11.1 拉取镜像慢或超时

现象：docker compose up -d 卡在 Pulling shardingsphere-proxy 或报 TLS 超时。

解决：在 /etc/docker/daemon.json 配置镜像加速器后重启 Docker 再拉取（实测环境即通过镜像加速完成 814MB 镜像拉取）。加速器地址以各加速服务提供的为准，配置后用 docker info 确认 Registry Mirrors 生效。

11.2 启动后 3307 未监听

现象：docker compose ps 状态 Up，但 SHOW DATABASES 连不上。

排查：docker compose logs shardingsphere-proxy 看启动日志。常见原因有二：一是 conf/ 中残留官方演示 database-*.yaml（引用不存在的数据源，加载即报错），conf/ 内只保留 global.yaml 与本指南的 database-sharding.yaml 即可；二是 global.yaml 元数据 jdbc_url 缺 ;MODE=MySQL。

11.3 修改配置不生效

定位：配置是 ./conf 挂载进实例的，编辑宿主机文件后不会热加载。

解决：docker compose restart shardingsphere-proxy 后查看日志确认 started successfully，再连接执行 SHOW SHARDING TABLE RULES; 核对。

11.4 JVM 堆参数未生效

排查：docker exec shardingsphere-proxy sh -c 'ps -ef | grep [j]ava'（回显见第十章）。若仍是 -Xmx2g，检查 CGROUP_MEM_OPTS 是否拼写正确、值两侧空格是否保留，以及 docker compose up -d 是否为修改 compose 文件之后重新执行（改 compose 后需 up -d 重建而非仅 restart）。

11.5 down 之后数据会丢吗

不会。本项目数据在宿主机 bind mount 目录 ./data（ds_0.mv.db、ds_1.mv.db），docker compose down 只删实例与内部网络，不触碰挂载目录；实测 down 后重新 up -d，记录数不变（见第五章）。只有手动删除 ./data 才会丢业务数据。

十二、参考链接

Docker Hub 官方镜像：https://hub.docker.com/r/apache/shardingsphere-proxy
Apache ShardingSphere 官方文档（5.5.3 中文）：https://shardingsphere.apache.org/document/5.5.3/cn/overview/
官方 GitHub 仓库：https://github.com/apache/shardingsphere
裸装对照篇：《Apache ShardingSphere 安装指南》