ShardingSphere-Proxy——配置手册与Docker镜像-京东云开发者社区

# 概述

## 简介

ShardingSphere-Proxy 是 Apache ShardingSphere 的第二个产品。
它定位为透明化的数据库代理端，提供封装了数据库二进制协议的服务端版本，用于完成对异构语言的支持。
目前提供 MySQL 和 PostgreSQL 版本，它可以使用任何兼容 MySQL/PostgreSQL 协议的访问客户端(如：MySQL Command Client, MySQL Workbench, Navicat 等)操作数据，对 DBA 更加友好。

* 向应用程序完全透明，可直接当做 MySQL/PostgreSQL 使用。
* 适用于任何兼容 MySQL/PostgreSQL 协议的的客户端。

![ShardingSphere-Proxy Architecture](https://shardingsphere.apache.org/document/current/img/shardingsphere-proxy-brief.png)

## 对比

|           | *ShardingSphere-JDBC* | *ShardingSphere-Proxy*  | *ShardingSphere-Sidecar* |
| --------- | --------------------- | ----------------------- | ------------------------ |
| 数据库     | 任意                  | `MySQL/PostgreSQL`      | MySQL/PostgreSQL          |
| 连接消耗数 | 高                    | `低`                     | 高                        |
| 异构语言   | 仅Java                | `任意`                   | 任意                      |
| 性能       | 损耗低                | `损耗略高`                | 损耗低                    |
| 无中心化   | 是                    | `否`                     | 是                        |
| 静态入口   | 无                    | `有`                     | 无                        |

ShardingSphere-Proxy 的优势在于对异构语言的支持，以及为 DBA 提供可操作入口。
# 配置手册
配置是 ShardingSphere-Proxy 中唯一与开发者交互的模块，通过它可以快速清晰的理解 ShardingSphere-Proxy 所提供的功能。

本节是 ShardingSphere-Proxy 的配置参考手册，需要时可当做字典查阅。

ShardingSphere-Proxy 只提供基于 YAML 的配置方式。 通过配置，应用开发者可以灵活的使用数据分片、读写分离、数据加密、影子库等功能，并且能够叠加使用。

规则配置部分与 ShardingSphere-JDBC 的 YAML 配置完全一致。
## 数据源配置

### 配置项说明

```yaml
schemaName: # 逻辑数据源名称

dataSources: # 数据源配置，可配置多个 <data-source-name>
  <data-source-name>: # 与 ShardingSphere-JDBC 配置不同，无需配置数据库连接池
    url: #数据库 URL 连接
    username: # 数据库用户名
    password: # 数据库密码
    connectionTimeoutMilliseconds: # 连接超时毫秒数
    idleTimeoutMilliseconds: # 空闲连接回收超时毫秒数
    maxLifetimeMilliseconds: # 连接最大存活时间毫秒数
    maxPoolSize: 50 # 最大连接数
    minPoolSize: 1  # 最小连接数

rules: # 与 ShardingSphere-JDBC 配置一致
  # ...
```

更多的数据源配置参数详见[HikariCP](https://github.com/brettwooldridge/HikariCP) 。
## 权限配置

用于执行登录 Sharding Proxy 的权限验证。
配置用户名、密码、可访问的数据库后，必须使用正确的用户名、密码才可登录。

```yaml
authentication:
  users:
    root: # 自定义用户名
      password: root # 自定义密码
    sharding: # 自定义用户名
      password: sharding # 自定义密码
      authorizedSchemas: sharding_db, replica_query_db # 该用户授权可访问的数据库，多个用逗号分隔。缺省将拥有 root 权限，可访问全部数据库。
```
## 属性配置

### 简介

Apache ShardingSphere 提供属性配置的方式配置系统级配置。

### 配置项说明

| *名称*                             | *数据类型*   | *说明*                                                                                                                                                                                  | *默认值*  |
| ---------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| sql-show (?)                       | boolean     | 是否在日志中打印 SQL。 <br /> 打印 SQL 可以帮助开发者快速定位系统问题。日志内容包含：逻辑 SQL，真实 SQL 和 SQL 解析结果。<br /> 如果开启配置，日志将使用 Topic `ShardingSphere-SQL`，日志级别是 INFO。 | false    |
| sql-simple (?)                     | boolean     | 是否在日志中打印简单风格的 SQL。                                                                                                                                                           | false    |
| acceptor-size (?)                  | int         | 用于设置接收 TCP 请求线程池的大小。                                                                                                                                                        | CPU * 2  |
| executor-size (?)                  | int         | 用于设置任务处理线程池的大小。每个 ShardingSphereDataSource 使用一个独立的线程池，同一个 JVM 的不同数据源不共享线程池。                                                                           | infinite |
| max-connections-size-per-query (?) | int         | 一次查询请求在每个数据库实例中所能使用的最大连接数。                                                                                                                                          | 1        |
| check-table-metadata-enabled (?)   | boolean     | 是否在程序启动和更新时检查分片元数据的结构一致性。                                                                                                                                            | false    |
| query-with-cipher-column (?)       | boolean     | 是否使用加密列进行查询。在有原文列的情况下，可以使用原文列进行查询。                                                                                                                            | true     |
| proxy-frontend-flush-threshold (?) | int         | 在 ShardingSphere-Proxy 中设置传输数据条数的 IO 刷新阈值。                                                                                                                                  | 128      |
| proxy-transaction-type (?)         | String      | ShardingSphere-Proxy 中使用的默认事务类型。包括：LOCAL、XA 和 BASE。                                                                                                                         | LOCAL    |
| proxy-opentracing-enabled (?)      | boolean     | 是否允许在 ShardingSphere-Proxy 中使用 OpenTracing。                                                                                                                                       | false    |
| proxy-hint-enabled (?)             | boolean     | 是否允许在 ShardingSphere-Proxy 中使用 Hint。使用 Hint 会将 Proxy 的线程处理模型由 IO 多路复用变更为每个请求一个独立的线程，会降低 Proxy 的吞吐量。                                                 | false    |
| xa-transaction-manager-type (?)    | String      | XA 事务管理器类型。列如：Atomikos，Narayana，Bitronix。                                                                                                                                     | Atomikos  |
## YAML 语法说明
`!!` 表示实例化该类

`!` 表示自定义别名

`-` 表示可以包含一个或多个

`[]` 表示数组，可以与减号相互替换使用
# DOCKER 镜像
## 拉取官方 Docker 镜像

```bash
docker pull apache/shardingsphere-proxy
```

## 手动构建 Docker 镜像（可选）

```bash
git clone https://github.com/apache/shardingsphere
mvn clean install
cd shardingsphere-distribution/shardingsphere-proxy-distribution
mvn clean package -Prelease,docker
```

## 配置 ShardingSphere-Proxy

在 `/${your_work_dir}/conf/` 创建 `server.yaml` 和 `config-xxx.yaml` 文件，进行服务器和分片规则配置。
配置规则，请参考[配置手册](/cn/user-manual/shardingsphere-proxy/configuration/)。
配置模板，请参考[配置模板](https://github.com/apache/shardingsphere/tree/master/shardingsphere-proxy/shardingsphere-proxy-bootstrap/src/main/resources/conf)

## 运行 Docker

```bash
docker run -d -v /${your_work_dir}/conf:/opt/shardingsphere-proxy/conf -e PORT=3308 -p13308:3308 apache/shardingsphere-proxy:latest
```

**说明**

* 可以自定义端口 `3308` 和 `13308`。`3308` 表示 docker 容器端口, `13308` 表示宿主机端口。
* 必须挂载配置路径到 /opt/shardingsphere-proxy/conf。

```bash
docker run -d -v /${your_work_dir}/conf:/opt/shardingsphere-proxy/conf -e JVM_OPTS="-Djava.awt.headless=true" -e PORT=3308 -p13308:3308 apache/shardingsphere-proxy:latest
```

**说明**

* 可以自定义JVM相关参数到环境变量 `JVM_OPTS` 中。

```bash
docker run -d -v /${your_work_dir}/conf:/opt/shardingsphere-proxy/conf -v /${your_work_dir}/ext-lib:/opt/shardingsphere-proxy/ext-lib -p13308:3308 apache/shardingsphere-proxy:latest
```

**说明**

* 如需使用外部 jar 包，可将其所在目录挂载到 /opt/shardingsphere-proxy/ext-lib。

## 访问 ShardingSphere-Proxy

与连接 PostgreSQL 的方式相同。

```bash
psql -U ${your_user_name} -h ${your_host} -p 13308
```

## FAQ

问题1：I/O exception (java.io.IOException) caught when processing request to {}->unix://localhost:80: Connection refused？

回答：在构建镜像前，请确保 docker daemon 进程已经运行。

问题2：启动时报无法连接到数据库错误？

回答：请确保 /${your_work_dir}/conf/config-xxx.yaml 配置文件中指定的 PostgreSQL 数据库的 IP 可以被 Docker 容器内部访问到。

问题3：如何使用后端数据库为 MySQL 的 ShardingSphere-Proxy？

回答：将 `mysql-connector.jar` 所在目录挂载到 /opt/shardingsphere-proxy/ext-lib。

问题4：如何使用自定义分片算法？

回答：实现对应的分片算法接口，将编译出的分片算法 jar 所在目录挂载到 /opt/shardingsphere-proxy/ext-lib。