Feat(docs): Update versioned docs (#137)

* feat(docs): update versioned docs Signed-off-by: xuanyuan300 <[email protected]> * feat(docs): update versioned docs Signed-off-by: xuanyuan300 <[email protected]>
database-mesh · Jun 27, 2022 · 30998dd · 30998dd
1 parent b71c8ff
commit 30998dd
Show file tree

Hide file tree

Showing 30 changed files with 1,840 additions and 9 deletions.
diff --git a/docs/docs/Features/readwritesplitting.md b/docs/docs/Features/readwritesplitting.md
@@ -27,11 +27,11 @@ sidebar_position: 3
 Pisa-Proxy 支持两种类型的读写分离方案：
 - 静态读写分离
 
-`指无动态感知后端数据库角色变更。配置说明[请见](#读写分离配置)`
+指无动态感知后端数据库角色变更。配置说明[请见](#读写分离配置)。
 
 - 动态读写分离(目前还不支持)
 
-`指能够感知后端数据库角色变更。`
+指能够感知后端数据库角色变更。
 
 目前，两种方案都需要配置[读写分离规则](#读写分离规则说明)。
 
@@ -72,7 +72,7 @@ TargetInstnce: 指由 LoadBalance 模块选出的节点。
 | 属性 | 值类型 | 是否依赖 | 默认值 | 含义 |
 |-----|-------|---------|-------|-----|
 | defaultTarget | [enum](#targetrole-enum-值) |  否     |  无   | 默认路由的 TargetRole 组 |
-| rules | [array\<rule\>](#读写分离规则说明)| 是    |  无   | 读写分离规则|
+| rules | [array[rule]](#读写分离规则说明)| 是    |  无   | 读写分离规则|
 
 ***defaultTarget 值在真实场景中要配置成 `readwrite`***
 
@@ -87,7 +87,7 @@ TargetInstnce: 指由 LoadBalance 模块选出的节点。
 |-----|-------|---------|-------|-----|
 |name | string|  是     |  无   | 规则名称|
 |type | string| 是      |  无   | 路由类型为正则类型，此处值为 `regex`|
-|regex| array\<string\>| 是 | 无  | 具体的正则，将通过这些正则去匹配 SQL 语句|
+|regex| array[string]| 是 | 无  | 具体的正则，将通过这些正则去匹配 SQL 语句|
 |target| [enum](#targetrole-enum-值)| 是     | 无    | 路由到的 TargetRole 组，对应 DatabaseEndpoint CRD 的Annotation 属性中 `database-mesh.io/role` 的 值|
 |algorithName| [enum](#algorithname-enum-值)| 是| 无   | 负载均衡算法的名称，将作用与路由到的 `role` 组中的机器列表|
 

diff --git a/docs/docs/UseCases/kubernetes.md b/docs/docs/UseCases/kubernetes.md
@@ -119,6 +119,7 @@ helm uninstall pisa-controller -n <your namespace>
 ### DatabaseEndpoint
 
 Spec 配置说明
+
 | Name       | Description          |
 | ---------- | -------------------- |
 | `database` | 后端的数据源类型     |

diff --git a/docs/docs/UseCases/standalone.md b/docs/docs/UseCases/standalone.md
@@ -48,7 +48,7 @@ Pisa-Proxy 在本地作为单独部署启动的时候需要以下配置文件：
 # Http IP 地址
 host = "0.0.0.0"
 # api 端口
-port = "5591"
+port = 5591
 # 日志级别
 log_level = "INFO"
 

diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js
@@ -27,6 +27,15 @@ const config = {
 			({
 				docs: {
 					sidebarPath: require.resolve("./sidebars.js"),
+          showLastUpdateAuthor: true,
+          showLastUpdateTime: true,
+          includeCurrentVersion: true,
+          lastVersion: 'current',
+          versions: {
+            current: {
+              label: 'latest',
+            },
+          },
 				},
 				blog: {
 					showReadingTime: true,
@@ -48,10 +57,10 @@ const config = {
 					src: "img/logo.svg",
 				},
 				items: [
-					//TODO: enable this when 1.1 released
-					// {
-					//   type: 'docsVersionDropdown',
-					// },
+					{
+					  type: 'docsVersionDropdown',
+						position: "right",
+					},
 					{
 						type: "localeDropdown",
 						position: "right",

diff --git a/docs/versioned_docs/version-v0.1.0/Features/_category_.json b/docs/versioned_docs/version-v0.1.0/Features/_category_.json
@@ -0,0 +1,4 @@
+{
+  "label": "特性",
+  "position": 3
+}
diff --git a/docs/versioned_docs/version-v0.1.0/Features/loadbalancer.md b/docs/versioned_docs/version-v0.1.0/Features/loadbalancer.md
@@ -0,0 +1,51 @@
+---
+sidebar_position: 1
+---
+
+# 负载均衡
+
+负载均衡模块为 Pisa-Proxy 代理后端节点时，新建链接时对后端节点选取策略的实现。
+
+## 已支持负载均衡策略
+- [x] Random
+- [x] RoundRobin
+
+## 配置示例
+
+若需要在代理中启用负载均衡，则需要配置 `simple_loadbalance` 块.
+```
+[proxy.config.simple_loadbalance]
+balance_type = "roundrobin"
+nodes = ["ds001","ds002"]
+```
+其中 balance_type: 可选值为 random，roundrobin，默认值为 random；nodes: 选取后端数据源中定义的 `name`.
+
+后端数据源配置：
+```
+[[mysql.node]]
+name = "ds001"
+user = "root"
+password = "12345678"
+db = "test"
+host = "127.0.0.1"
+port = 3306
+
+[[mysql.node]]
+name = "ds002"
+user = "root"
+password = "12345678"
+db = "test"
+host = "127.0.0.1"
+port = 3307
+```
+
+## 模块设计
+
+该模块定义了一个负载均衡的 Trait，封装了在 Pisa-Proxy 中对于负载均衡的构建方式。以及定义了 Random 和 RoundRobin 两种负载均衡策略所要实现的具体方法。
+
+### 代码结构
+	FILES IN THIS DIRECTORY (loadbalance/src)
+		balance.rs               - 负载均衡 Trait，定义了负载均衡方法和构建负载均衡模块
+		random_weighted.rs       - random weighted 负载均衡策略
+		roundrobin_weighted.rs   - roundrobin weighted 负载均衡策略
+
diff --git a/docs/versioned_docs/version-v0.1.0/Features/mysql-protocol.md b/docs/versioned_docs/version-v0.1.0/Features/mysql-protocol.md
@@ -0,0 +1,51 @@
+---
+sidebar_position: 2
+---
+# MySQL 协议 
+
+此功能主要为 Pisa-Proxy MySQL 代理的核心组件, 依据 [MySQL 协议](https://dev.mysql.com/doc/internals/en/client-server-protocol.html) 进行实现。该功能主要使用 Rust 生态的 [Tokio](https://github.com/tokio-rs/tokio) 异步运行时框架。其中对网络数据包的读写、协议的编码等操作都通过 Tokio 提供的工具集实现。
+
+
+## 已支持命令
+- [x] COM_INIT_DB
+- [x] COM_QUERY
+- [x] COM_FIELD_LIST
+- [x] COM_QUIT
+- [x] COM_PING
+- [x] COM_STMT_PREPARE
+- [x] COM_STMT_EXECUTE
+- [x] COM_STMT_CLOSE
+- [x] COM_STMT_RESET 
+
+## 支持认证方式
+- [x] mysql_native_password
+- [ ] sha256_password
+- [ ] caching_sha2_password 
+
+## 设计说明
+
+本模块共由3部分组成,对应 Pisa-Proxy 中作为客户端和服务端两部分。在 `server` 目录中主要定义了 Pisa-Proxy 作为服务端对客户端请求的处理逻辑。也包含了在 TCP 层的网络数据包的读写操作。在 `client` 目录中定义了 Pisa-Proxy 作为客户端对 MySQL 数据库的建立链接、握手认证和发送客户端命令等操作。
+
+### 代码结构
+
+	FILES IN THIS DIRECTORY (protocol/mysql/src/client)
+		auth.rs          - 对 MySQL 登陆认证
+		codec.rs         - 对 MySQL 协议的解码
+		conn.rs          - 对 MySQL 发起链接、握手及命令处理
+		err.rs           - MySQL Error 类型定义
+		resultset.rs     - 一些 MySQL ResultSet 结果处理方法
+		stmt.rs          - 对 MySQL Prepare Statement 处理方法
+		stream.rs        - 对 Tokio TcpSteam 封装
+
+	FILES IN THIS DIRECTORY (protocol/mysql/src/server)
+		conn.rs          - 和客户端建链、握手认证处理
+		packet.rs        - 网络数据包的读写操作
+		stream.rs        - 对底层 Tcp 流的封装
+		tls.rs           - MySQL TLS 链接封装
+
+	FILES IN THIS DIRECTORY (protocol/mysql/src)
+		charset.rs       - MySQL 字符集声明
+		err.rs           - 协议解析错误处理定义
+		mysql_const.rs。 - 常量定义
+		util.rs          - 一些通用函数的实现
+
diff --git a/docs/versioned_docs/version-v0.1.0/Features/observability.md b/docs/versioned_docs/version-v0.1.0/Features/observability.md
@@ -0,0 +1,17 @@
+---
+sidebar_position: 5
+---
+
+# 可观测性 
+
+Pisanix 目前在 Pisa-Proxy 处理 SQL 命令的时候采集相关指标，并以 `/metrics` 路径进行暴露。
+
+## 已支持指标
+- SQL_PROCESSED_TOTAL: 统计所有执行的 SQL 数量
+- SQL_PROCESSED_DURATION: 统计所有 SQL 的执行时间
+
+测试效果如下图：
+
+![grafana](/img/grafana.jpg)
+
+下一步将支持更多标签和指标，如 SQL 语句类型、延迟、错误率、TopK、运行时资源等。
diff --git a/...ned_docs/version-v0.1.0/Features/sql-circuit-breaker-and-concurrency-control.md b/...ned_docs/version-v0.1.0/Features/sql-circuit-breaker-and-concurrency-control.md
@@ -0,0 +1,55 @@
+---
+sidebar_position: 4
+---
+
+# 断路和并发控制 
+
+目前实现了两个默认插件 `SQL 断路` 和 `SQL 并发控制`。
+
+### SQL 断路
+
+禁止运行匹配正则的语句。
+
+#### 示例配置
+如：不允许执行` SELECT *`
+
+``` toml
+[[proxy.config.plugin.circuit_break]]
+regex = "SELECT \\*"
+```
+> 注：可以有多个规则
+
+### SQL 限流
+
+限流规则表示在 `duration` 秒内并发运行匹配正则的 SQL 语句只能有 `max_concurrency` 条，
+
+#### 示例配置
+如：不允许100秒内并发执行多于1条 `SELECT *`
+
+``` toml
+[[proxy.config.plugin.concurrency_control]]
+regex = "SELECT \\*"    
+max_concurrency = 1
+duration = 100
+```
+
+> 注：可以有多个规则
+
+
+## 设计说明
+
+目前运行中间件的方式参考了[ Tower-rs ](https://github.com/tower-rs/tower.git)，可以很好的满足未来扩展的需求。
+
+其中有两个概念:
+> Layer:  是对 `Service` 的包装，每个 `Service` 可以有多个不同的中间件。
+
+> Service: 指 `Pisanix` 内部允许执行中间件的服务或者是某个功能函数，可以运行一些自定义的逻辑，如 `Metrics` 收集。
+
+实现[伪代码](https://play.rust-lang.org/?version=stable&mode=debug&edition=2018&gist=0db8ca6f72096c7a74682085a66e3270)。
+
+注意 
+
+- 限流规则表示在 `duration` 秒内并发运行匹配正则的 sql 语句只能有 `max_concurrency` 条，从第一次匹配到开始计时，如果超过 `duration` 时间，则限流失效，重新开始下一次匹配。
+- 目前由于不能动态生效限流规则，因此规则的生效时间是从第一次匹配到的时间开始，持续 `duration` 时间，超过后继续下次循环，没有失效情况，在未来支持动态生效后，规则失效有两种情况：
+    -  `duration` 的时间将从获取到开启动作的时间开始，持续 `duration` 时间，规则失效。
+    -  等到获取到关闭动作时，规则失效。
diff --git a/docs/versioned_docs/version-v0.1.0/Features/sql-parser.md b/docs/versioned_docs/version-v0.1.0/Features/sql-parser.md
@@ -0,0 +1,37 @@
+---
+sidebar_position: 3
+---
+
+# SQL 解析
+
+Pisanix 除了理解 SQL 协议外, 能读懂 SQL 语句也是一个很重要的功能，读写分离，分片等功能也都依赖 SQL 解析，在 Pisanix 中占着举足轻重的作用。
+由于 Pisanix 支持多种数据源，因此在 Pisanix 中，每种不同的数据源都要实现各自对应的 SQL 解析，未来我们会支持不同数据源使用SQL 之间的转换，以实现快速支持新的数据源。
+
+## 已支持语句
+- [x] SELECT
+- [x] INSERT
+- [x] UPDATE
+- [x] DELETE
+- [x] PREPARE
+- [x] EXECUTE
+- [x] BEGIN
+- [x] SET
+- [ ] SHOW
+- [ ] CREATE
+
+
+## 设计说明
+目前 Pisanix 只实现了对 MySQL 的语法的解析。
+
+### MySQL 语法
+为了最大的程度的兼容原生的 MySQL 语法，Pisanix 采用原生的[ MySQL 语法文件](https://github.com/mysql/mysql-server/blob/8.0/sql/sql_yacc.yy)，基于 `Grmtools` 实现了 SQL 语法解析。
+ `Grmtools` 是一个用 Rust 写的兼容 `Yacc` 的语法解析工具，详细信息请参考[ Github ](https://github.com/softdevteam/grmtools.git)。
+
+### AST 说明
+Pisanix 中的 SQL 解析不会为所有表达式都生成 AST，只会为 Pisanix 感兴趣的部分生成 AST。
+详细信息请参考[ Github ](https://github.com/database-mesh/pisanix/tree/master/pisa-proxy/parser/mysql/src/ast)。
+
+### 测试
+目前使用了 MySQL test 框架中能正常运行的 SQL 语句作为测试集来测试。目前只测试了 `SELECT` 语句，有`98%`的语句能成功解析, 还在不断完善中。
+
+
diff --git a/docs/versioned_docs/version-v0.1.0/UseCases/_category_.json b/docs/versioned_docs/version-v0.1.0/UseCases/_category_.json
@@ -0,0 +1,4 @@
+{
+  "label": "使用场景",
+  "position": 4
+}