ShardingSphere-Proxy 是 Apache ShardingSphere 的接入端之一，其定位為透明化的資料庫代理。ShardingSphere-Proxy 實現了資料庫協議，理論上可以被任何使用或相容 MySQL / PostgreSQL / openGauss 協議的客戶端訪問。相比 ShardingSphere-JDBC，ShardingSphere-Proxy 的優勢在於對異構語言的支援，以及為 DBA 提供資料庫叢集的可操作入口。

![](http://img.blog.itpub.net/blog/2022/06/28/2983af4c539ef12a.png?x-oss-process=style/bb)

與 ShardingSphere 的 SQL 解析模組相似，ShardingSphere-Proxy 對資料庫協議的支援度也是一個長期積累的過程，需要開發者不斷去完善 ShardingSphere-Proxy 的資料庫協議實現。

本篇將給大家介紹資料庫協議開發過程中常用的工具，並以一次 ShardingSphere-Proxy MySQL 協議問題的排查過程作為本文工具使用的案例。

## 1 使用 Wireshark 分析網路協議

Wireshark 是一個常用的網路協議分析工具，其內建了對數百種協議的解析支援（包括本文相關的 MySQL / PostgreSQL 協議），能夠讀取多種不同型別的抓包格式。

Wireshark 的完整功能、安裝等內容可以參考 Wireshark 官方文件[1]。

### 1.1 使用 Wireshark 或 tcpdump 等工具抓包

#### 1.1.1 使用 Wireshark 抓包

Wireshark 本身具備抓包能力，如果連線 ShardingSphere-Proxy 的環境可以執行 Wireshark，可以直接使用 Wireshark 抓包。

Wireshark 啟動後，首先選擇正確的網路卡。

以本地執行 ShardingSphere-Proxy 為例，客戶端透過 `127.0.0.1` 埠 `3307` 連線 ShardingSphere-Proxy，流量都經過 Loopback 網路卡，因此選擇 Loopback 作為抓包物件。

![](http://img.blog.itpub.net/blog/2022/06/28/8b0f4cc4a31481f7.png?x-oss-process=style/bb)

選擇網路卡後，Wireshark 即開始抓包。由於網路卡中可能會有很多其他程式的流量，需要過濾出指定埠的流量：

```
tcp.port == 3307`
```

![](http://img.blog.itpub.net/blog/2022/06/28/e045cf4b8d40274f.png?x-oss-process=style/bb)

#### 1.1.2 使用 tcpdump 抓包

在 ShardingSphere-Proxy 部署線上上環境，或其他我們無法使用 Wireshark 抓包的情況下，可以考慮使用 tcpdump 或其他工具抓包。

對網路卡 `eth0` 抓包，過濾 TCP 埠 3307，並將抓包結果寫入到 `/path/to/dump.cap`。示例命令：

```
tcpdump -i eth0 -w /path/to/dump.cap tcp port 3307
```

tcpdump 的使用方式可以透過 man tcpdump 檢視，本文不再贅述。tcpdump 的抓包結果檔案可以透過 Wireshark 開啟。

#### 1.1.3 抓包注意事項

客戶端連線 MySQL，可能會自動啟用 SSL 加密，抓包結果無法直接解析出協議內容。使用 MySQL 命令列客戶端可以指定引數禁用 SSL，命令如下：

```
mysql --ssl-mode=disable
```

使用 JDBC 可以增加引數，引數如下：

```
jdbc:mysql://127.0.0.1:3306/db?useSSL=false
```

### 1.2 使用 Wireshark 讀取抓包內容

Wireshark 支援讀取多種抓包檔案格式，包括 tcpdump 的抓包格式。

Wireshark 預設會把 `3306` 埠解碼 MySQL 協議、`5432` 埠解碼為 PostgreSQL 協議。對於 ShardingSphere-Proxy 可能使用不同埠的情況，可以在 `Decode As...` 中為指定埠配置協議。

例如，ShardingSphere-Proxy MySQL 使用了 `3307` 埠，可以按照以下步驟把 `3307` 埠解碼為 MySQL 協議：

![](http://img.blog.itpub.net/blog/2022/06/28/a461bad0666bb971.png?x-oss-process=style/bb)

![](http://img.blog.itpub.net/blog/2022/06/28/51aefe70c8941044.png?x-oss-process=style/bb)

當 Wirekshark 能夠解析出 MySQL 協議後，我們可以增加過濾條件，只顯示 MySQL 協議資料：

```
tcp.port == 3307 and mysql
```

![](http://img.blog.itpub.net/blog/2022/06/28/0849f54e3389fcd8.png?x-oss-process=style/bb)

為指定埠選擇正確的協議後，可以在 Wireshark 視窗看到協議的內容。

示例，客戶端與服務端建立 TCP 連線後，MySQL 服務端主動向客戶端傳送 Greeting，協議如下圖所示：

![](http://img.blog.itpub.net/blog/2022/06/28/8dd1d198e029c6dd.png?x-oss-process=style/bb)

示例，客戶端執行 SQL select version()，協議如下圖所示：

![](http://img.blog.itpub.net/blog/2022/06/28/5d10db0a85d5ddee.png?x-oss-process=style/bb)

## 2 協議問題排查案例——讓 ShardingSphere-Proxy MySQL 支援超長資料包

### 2.1 問題描述

使用 MySQL Connector/J 8.0.28 作為客戶端連線 ShardingSphere-Proxy 5.1.1 執行批次插入報錯，更換驅動 MySQL Connector/J 5.1.38 後問題解決。

```
[INFO ] 2022-05-21 17:32:22.375 [main] o.a.s.p.i.BootstrapInitializer - Database name is `MySQL`, version is `8.0.28`
[INFO ] 2022-05-21 17:32:22.670 [main] o.a.s.p.frontend.ShardingSphereProxy - ShardingSphere-Proxy start success
[ERROR] 2022-05-21 17:37:57.925 [Connection-143-ThreadExecutor] o.a.s.p.f.c.CommandExecutorTask - Exception occur: 
java.lang.IllegalArgumentException: Sequence ID of MySQL command packet must be `0`.
 at com.google.common.base.Preconditions.checkArgument(Preconditions.java:142)
 at org.apache.shardingsphere.db.protocol.mysql.packet.command.MySQLCommandPacketTypeLoader.getCommandPacketType(MySQLCommandPacketTypeLoader.java:38)
 at org.apache.shardingsphere.proxy.frontend.mysql.command.MySQLCommandExecuteEngine.getCommandPacketType(MySQLCommandExecuteEngine.java:50)
 at org.apache.shardingsphere.proxy.frontend.mysql.command.MySQLCommandExecuteEngine.getCommandPacketType(MySQLCommandExecuteEngine.java:46)
 at org.apache.shardingsphere.proxy.frontend.command.CommandExecutorTask.executeCommand(CommandExecutorTask.java:95)
 at org.apache.shardingsphere.proxy.frontend.command.CommandExecutorTask.run(CommandExecutorTask.java:72)
 at java.base/java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1128)
 at java.base/java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:628)
 at java.base/java.lang.Thread.run(Thread.java:834)
[ERROR] 2022-05-21 17:44:24.926 [Connection-317-ThreadExecutor] o.a.s.p.f.c.CommandExecutorTask - Exception occur: 
java.lang.IllegalArgumentException: Sequence ID of MySQL command packet must be `0`.
 at com.google.common.base.Preconditions.checkArgument(Preconditions.java:142)
 at org.apache.shardingsphere.db.protocol.mysql.packet.command.MySQLCommandPacketTypeLoader.getCommandPacketType(MySQLCommandPacketTypeLoader.java:38)
 at org.apache.shardingsphere.proxy.frontend.mysql.command.MySQLCommandExecuteEngine.getCommandPacketType(MySQLCommandExecuteEngine.java:50)
 at org.apache.shardingsphere.proxy.frontend.mysql.command.MySQLCommandExecuteEngine.getCommandPacketType(MySQLCommandExecuteEngine.java:46)
 at org.apache.shardingsphere.proxy.frontend.command.CommandExecutorTask.executeCommand(CommandExecutorTask.java:95)
 at org.apache.shardingsphere.proxy.frontend.command.CommandExecutorTask.run(CommandExecutorTask.java:72)
 at java.base/java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1128)
 at java.base/java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:628)
 at java.base/java.lang.Thread.run(Thread.java:834)
```

### 2.2 詳細排查過程

報錯處於 Proxy 前端，可以排除後端 JDBC Driver 的原因，與協議實現有關。

#### 2.2.1 問題分析

原始碼中直接判斷如果 sequence ID 不等於 0 就直接報錯。

```
public final class MySQLCommandPacketTypeLoader {
    
    /**
     * Get command packet type.
     *
     * @param payload packet payload for MySQL
     * @return command packet type for MySQL
     */
    public static MySQLCommandPacketType getCommandPacketType(final MySQLPacketPayload payload) {
        Preconditions.checkArgument(0 == payload.readInt1(), "Sequence ID of MySQL command packet must be `0`.");
        return MySQLCommandPacketType.valueOf(payload.readInt1());
    }
}
```

程式碼連結：[https://github.com/apache/shardingsphere/blob/d928165ea4f6ecf2983b2a3a8670ff66ffe63647/shardingsphere-db-protocol/shardingsphere-db-protocol-mysql/src/main/java/org/apache/shardingsphere/db/protocol/mysql/packet/command/MySQLCommandPacketTypeLoader.java#L38](https://github.com/apache/shardingsphere/blob/d928165ea4f6ecf2983b2a3a8670ff66ffe63647/shardingsphere-db-protocol/shardingsphere-db-protocol-mysql/src/main/java/org/apache/shardingsphere/db/protocol/mysql/packet/command/MySQLCommandPacketTypeLoader.java#L38)

結合 MySQL 協議文件，考慮什麼情況下 sequence ID 會不等於 0[2]：

* 服務端響應多個訊息給客戶端；

* 客戶端傳送多個連續的訊息；

* ……

其中，MySQL Packet 的訊息頭由 3 位元組長度 + 1 位元組 Sequence ID 組成[3]，因此 Payload 部分最大長度為 16 MB - 1。結合問題描述，報錯是在批次插入的時候產生，考慮問題可能是：客戶端傳送的資料超過單個 MySQL Packet 的長度上限，拆分為多個連續的 MySQL Packet，但 Proxy 無法處理。

#### 2.2.2 嘗試重現問題

使用 `longtext` 型別欄位。本來設想的是構造一條長度超過 16 MB 的 SQL。但無意中發現，SQL 長度超過 8 MB 的情況下也報錯了，復現程式碼如下：

```
try (Connection connection = DriverManager.getConnection("jdbc:mysql://127.0.0.1:13306/bmsql", "root", "root")) {
    try (Statement statement = connection.createStatement()) {
        statement.execute("drop table if exists foo");
        statement.execute("create table foo (id bigint primary key, str0 longtext)");
        long id = ThreadLocalRandom.current().nextLong();
        String str0 = RandomStringUtils.randomAlphanumeric(1 << 23);
        String sql = "insert into foo (id, str0) values (" + id + ", '" + str0 + "')";
        System.out.println(sql.length());
        statement.execute(sql);
    }
}
```

執行報錯如下：

![](http://img.blog.itpub.net/blog/2022/06/28/8e9832c5cf049c83.png?x-oss-process=style/bb)

Wireshark 抓包結果顯示，資料包長度 0x80003C == 8388668，只有一個 MySQL Packet，sequence ID 也只有 0，如下圖：

![](http://img.blog.itpub.net/blog/2022/06/28/4348920bc9a91225.png?x-oss-process=style/bb)

除錯程式碼發現，Proxy 所使用的 readMediumLE() 方法是有符號數，Packet 長度讀取為負數了。

![](http://img.blog.itpub.net/blog/2022/06/28/e55db6abac298cbd.png?x-oss-process=style/bb)

該問題比較好修復，更換對應的 `readUnsignedMediumLE()` 方法即可。

雖然該問題報錯資訊和問題描述的現象一致，但還沒有解決根本問題。

長度溢位問題修復後，繼續排查問題。使用以下程式碼，向 ShardingSphere-Proxy 傳送約 64 MB 的資料：

```
try (Connection connection = DriverManager.getConnection("jdbc:mysql://127.0.0.1:13306/bmsql", "root", "root")) {
    try (Statement statement = connection.createStatement()) {
        statement.execute("drop table if exists foo");
        statement.execute("create table foo (id bigint primary key, str0 longtext)");
        long id = ThreadLocalRandom.current().nextLong();
        String str0 = RandomStringUtils.randomAlphanumeric(1 << 26);
        String sql = "insert into foo (id, str0) values (" + id + ", '" + str0 + "')";
        statement.execute(sql);
    }
}
```

發生錯誤：

![](http://img.blog.itpub.net/blog/2022/06/28/636caef511a80fdc.png?x-oss-process=style/bb)

分析抓包結果：

![](http://img.blog.itpub.net/blog/2022/06/28/8f3456afa542593f.png?x-oss-process=style/bb)

![](http://img.blog.itpub.net/blog/2022/06/28/0426cb639346b6aa.png?x-oss-process=style/bb)

抓包結果顯示，客戶端傳送了多個 16 MB 的資料包。Wireshark 沒能正常解析出 MySQL 的超長資料包，但我們可以透過搜尋功能定位到 MySQL 的 Packet Header。

再結合 ShardingSphere-Proxy MySQL 的解碼邏輯：

```
int payloadLength = in.markReaderIndex().readUnsignedMediumLE();
int remainPayloadLength = SEQUENCE_LENGTH + payloadLength;
if (in.readableBytes() < remainPayloadLength) {
    in.resetReaderIndex();
    return;
}
out.add(in.readRetainedSlice(SEQUENCE_LENGTH + payloadLength));
```

問題基本明確：由於 ShardingSphere-Proxy 沒有對資料包進行聚合，多個資料包被 Proxy 當成多個命令分別解析，由於後續資料包 Sequence ID 大於 0，Proxy 內部對 Sequence ID 的斷言邏輯報錯。

### 2.3 排查及修復

經排查，報錯原因為：

* （直接原因）ShardingSphere-Proxy MySQL 協議解包邏輯沒有正確處理長度符號[4]；

* （根本原因）ShardingSphere-Proxy MySQL 沒有對超過 16 MB 的資料包進行聚合[5]。

首先要了解 MySQL 協議對超長資料包的處理方式[6]：

* 當資料總長度超過 16 MB - 1，協議會將資料拆分為多個長度為 16 MB - 1 的 Packet，直到最後資料長度小於 16 MB - 1，如下圖所示：

![](http://img.blog.itpub.net/blog/2022/06/28/4c0e098043a79a85.png?x-oss-process=style/bb)

* 當資料長度恰好等於 16 MB - 1 或其倍數，在傳送一個或多個長度為 16 MB - 1 的資料包後，還會接一個長度為 0 的資料包，如下圖所示：

![](http://img.blog.itpub.net/blog/2022/06/28/4faa36090b0442ce.png?x-oss-process=style/bb)

**解決思路**：為了讓 ShardingSphere-Proxy MySQL 的協議實現能夠不關心超長資料包的處理方式，決定在資料解碼邏輯對資料包進行聚合。

在 ShardingSphere-Proxy 的前端 Netty 解碼邏輯中，當遇到長度為 0xFFFFFF 的資料 Packet，則透過 CompositeByteBuf 對多個 MySQL Packet 的 Payload 部分進行聚合。

具體程式碼見參考文件的 Pull Request。

目前已修復以下問題：

* 正確處理資料包長度數值符號[7]；

* MySQL 協議解碼邏輯支援超過 16 MB 資料包[8]。

後續需要解決的潛在問題，包括但不限於：

* MySQL 協議編碼邏輯不支援響應超過 16 MB 的資料包。

## 3 ShardingSphere-Proxy 前端協議排查方法總結

對於協議類問題排查，首先需要熟悉對應的協議，熟悉資料庫協議的方式包括但不限於：

* 透過抓包工具觀察客戶端直接連線資料庫的協議；

* 根據資料庫協議文件；
 
* 閱讀資料庫官方客戶端（例如 JDBC Driver）的協議編碼邏輯原始碼。

基本掌握抓包工具與協議後，就可以開始排查 ShardingSphere-Proxy 前端協議的問題了。

ShardingSphere-Proxy 與客戶端建立連線的程式碼入口在 
`org.apache.shardingsphere.proxy.frontend.netty.ServerHandlerInitializer`
[9]，可以以此作為起點排查問題。

另外，本文案例中問題的修復已隨 Apache ShardingSphere 5.1.2 釋出[10]，歡迎大家下載使用！

參考文件
[1] [https://www.wireshark.org/](https://www.wireshark.org/)

[2] [https://dev.mysql.com/doc/internals/en/sequence-id.html](https://dev.mysql.com/doc/internals/en/sequence-id.html)

[3] [https://dev.mysql.com/doc/internals/en/mysql-packet.html](https://dev.mysql.com/doc/internals/en/mysql-packet.html)

[4] [https://github.com/apache/shardingsphere/issues/17891](https://github.com/apache/shardingsphere/issues/17891)

[5] [https://github.com/apache/shardingsphere/issues/17907](https://github.com/apache/shardingsphere/issues/17907)

[6] [https://dev.mysql.com/doc/internals/en/sending-more-than-16mbyte.html](https://dev.mysql.com/doc/internals/en/sending-more-than-16mbyte.html)

[7] [https://github.com/apache/shardingsphere/pull/17898](https://github.com/apache/shardingsphere/pull/17898)

[8] [https://github.com/apache/shardingsphere/pull/17914](https://github.com/apache/shardingsphere/pull/17914)

[9][https://github.com/apache/shardingsphere/blob/2c9936497214b8a654cb56d43583f62cd7a6b76b/shardingsphere-proxy/shardingsphere-proxy-frontend/shardingsphere-proxy-frontend-core/src/main/java/org/apache/shardingsphere/proxy/frontend/netty/ServerHandlerInitializer.java](https://github.com/apache/shardingsphere/blob/2c9936497214b8a654cb56d43583f62cd7a6b76b/shardingsphere-proxy/shardingsphere-proxy-frontend/shardingsphere-proxy-frontend-core/src/main/java/org/apache/shardingsphere/proxy/frontend/netty/ServerHandlerInitializer.java)

[10] [https://shardingsphere.apache.org/document/current/cn/downloads/](https://shardingsphere.apache.org/document/current/cn/downloads/)

作者
吳偉傑，Apache ShardingSphere PMC，SphereEx 基礎設施研發工程師。專注於 Apache ShardingSphere 接入端及 ShardingSphere 子專案 ElasticJob 的研發。

歡迎點選連結，瞭解更多內容：

Apache ShardingSphere 官網：[https://shardingsphere.apache.org/](https://shardingsphere.apache.org/)

Apache ShardingSphere GitHub 地址：[https://github.com/apache/shardingsphere](https://github.com/apache/shardingsphere)

SphereEx 官網：[https://www.sphere-ex.com](https://www.sphere-ex.com)

歡迎新增社群經理微信（ss_assistant_1）加入交流群，與眾多 ShardingSphere 愛好者一同交流。

ShardingSphere-Proxy 前端協議問題排查方法及案例

相關文章