Update md

TarsCloud · Jun 28, 2022 · ac1d412 · ac1d412
1 parent 8d0fe7a
commit ac1d412
Show file tree

Hide file tree

Showing 15 changed files with 50 additions and 26 deletions.
diff --git a/.github/workflows/build-compiler-master.yml b/.github/workflows/build-compiler-master.yml
@@ -23,13 +23,13 @@ jobs:
           docker buildx inspect --bootstrap --builder k8s-framework-builder
       - name: Buildx Gateway
         run: |
-          docker run -v `pwd`:/data --entrypoint "" tarscloud/base-deploy sh -c "cd /data && /usr/bin/create-buildx-dockerfile.sh cpp yaml/gateway.yaml latest Dockerfile.cpp"
+          docker run -v `pwd`:/data --entrypoint "" tarscloud/base-deploy sh -c "cd /data && /usr/bin/create-buildx-dockerfile.sh cpp yaml/gateway.yaml latest dockerfile/Dockerfile.cpp"
       - name: Create Gateway Docker
         run: |
           ./docker-buildx-cloud.sh
       - name: Buildx Web
         run: |
-          docker run -v `pwd`:/data --entrypoint "" tarscloud/base-deploy sh -c "cd /data && /usr/bin/create-buildx-dockerfile.sh nodejs yaml/web.yaml latest Dockerfile.nodejs"
+          docker run -v `pwd`:/data --entrypoint "" tarscloud/base-deploy sh -c "cd /data && /usr/bin/create-buildx-dockerfile.sh nodejs yaml/web.yaml latest dockerfile/Dockerfile.nodejs"
       - name: Create web Docker
         run: |
           ./docker-buildx-cloud.sh

diff --git a/.github/workflows/build-compiler-tag.yml b/.github/workflows/build-compiler-tag.yml
@@ -26,13 +26,13 @@ jobs:
           docker buildx inspect --bootstrap --builder k8s-framework-builder
       - name: Buildx Gateway
         run: |
-          docker run -v `pwd`:/data --entrypoint "" tarscloud/base-deploy sh -c "cd /data && /usr/bin/create-buildx-dockerfile.sh cpp yaml/gateway.yaml ${{ steps.get_version.outputs.VERSION }} Dockerfile.cpp"
+          docker run -v `pwd`:/data --entrypoint "" tarscloud/base-deploy sh -c "cd /data && /usr/bin/create-buildx-dockerfile.sh cpp yaml/gateway.yaml ${{ steps.get_version.outputs.VERSION }} dockerfile/Dockerfile.cpp"
       - name: Create Gateway Docker
         run: |
           ./docker-buildx-cloud.sh
       - name: Buildx Web
         run: |
-          docker run -v `pwd`:/data --entrypoint "" tarscloud/base-deploy sh -c "cd /data && /usr/bin/create-buildx-dockerfile.sh nodejs yaml/web.yaml ${{ steps.get_version.outputs.VERSION }} Dockerfile.nodejs"
+          docker run -v `pwd`:/data --entrypoint "" tarscloud/base-deploy sh -c "cd /data && /usr/bin/create-buildx-dockerfile.sh nodejs yaml/web.yaml ${{ steps.get_version.outputs.VERSION }} dockerfile/Dockerfile.nodejs"
       - name: Create web Docker
         run: |
           ./docker-buildx-cloud.sh

diff --git a/README.en.md b/README.en.md
@@ -1,15 +1,15 @@
-- [中文文档](Gateway.md)
+- [中文文档](README.md)
 
 ## Introduction
 
 TarsGateway system is a set of general API gateway developed based on tar framework. It consists of two services:
 
 - Base/GatewayServer: Actual gateway service.
-- Base/GatewayWebServer: The gateway corresponds to the management platform, which belongs to the extended service of tarsweb. Note >= TarsFramework:v3.0.9 & TarsWeb:v3.0.3 can be used
+- Base/GatewayWebServer: The gateway corresponds to the management platform, which belongs to the extended service of tarsweb. Note  (>=tarscloud/framework:v3.0.10)  can be used
 
 ## Supported
 
-Before < tarsframework:v3.0.9 and < tarsweb:v3.0.3, the gateway management platform was built into tarsweb. In later versions, in order to provide the extensibility of tarsweb, tarsweb supports service plug-in, that is, you can realize the integration of independent web services and tarsweb. Therefore, when each sub module is upgraded, there is no need to upgrade tarsweb. For specific methods, please refer to the relevant tarsweb documents
+Before  tarscloud/framework:v3.0.10 , the gateway management platform was built into tarsweb. In later versions, in order to provide the extensibility of tarsweb, tarsweb supports service plug-in, that is, you can realize the integration of independent web services and tarsweb. Therefore, when each sub module is upgraded, there is no need to upgrade tarsweb. For specific methods, please refer to the relevant tarsweb documents
 
 ## Mysql Configuration description
 
@@ -22,4 +22,4 @@ Please use the same database. Note: database `db_base` and related tables will b
 
 ## Gateway function description
 
-Functions and configuration of the actual gateway service (gatewayserver), [please refer to the documentation](./Gateway.en.md)
+Functions and configuration of the actual gateway service (gatewayserver), [please refer to the documentation](./doc/Gateway.en.md)
diff --git a/README.md b/README.md
@@ -1,11 +1,11 @@
-- [English](Gateway.en.md)
+- [English](README.en.md)
 
 ## 简介
 
 TarsGateway 系统是基于 tars 框架开发的一套通用 api 网关, 它有两个服务组成:
 
 - Base/GatewayServer: 实际的网关服务
-- Base/GatewayWebServer: 网关对应管理平台, 它属于 TarsWeb 的扩展服务, 注意 >= TarsFramework:v3.0.9 & TarsWeb:v3.0.3 才可以使用
+- Base/GatewayWebServer: 网关对应管理平台, 它属于 TarsWeb 的扩展服务, 注意 (>=tarscloud/framework:v3.0.10) 才可以使用
 
 整个系统会依赖 mysql, 主要用于存储网关路由信息(http 转发), GatewayWebServer 启动时会自动创建相关表.
 
@@ -17,7 +17,7 @@ TarsGateway 系统是基于 tars 框架开发的一套通用 api 网关, 它有
 
 ## 安装方式
 
-推荐使用新版本 > TarsFramework:v3.0.9 时, 直接从云市场安装网关服务, 建议以容器方式启动网关, 这样不依赖操作系统 stdc++.so 的版本.
+推荐使用新版本(>=tarscloud/framework:v3.0.10) 时, 直接从云市场安装网关服务, 建议以容器方式启动网关, 这样不依赖操作系统 stdc++.so 的版本.
 
 [容器方式启动业务方式请参考](https://doc.tarsyun.com/#/installation/service-docker.md)
 
@@ -26,10 +26,15 @@ TarsGateway 系统是基于 tars 框架开发的一套通用 api 网关, 它有
 在安装网关系统时, 需要依赖 mysql, 因此在安装注意配置依赖的 mysql 地址
 
 - GatewayServer 请修改`GatewayServer.conf`
+![服务配置](./images/config_server.jpeg)
+
 - GatewayWebServer 请修改`config.json`
+![服务配置](./images/gateway_web.jpeg)
+
+
+数据库请使用同一个, 注意: 数据库`db_base`以及相关的表会被 GatewayWebServer 自动创建出来
 
-数据库请使用同一个, 注意: 数据库`db_base以及相关的表`会被 GatewayWebServer 自动创建出来
 
 ## 网关功能说明
 
-实际的网关服务的功能和配置(GatewayServer), [请参考说明文档](./Gateway.md)
+实际的网关服务的功能和配置(GatewayServer), [请参考说明文档](./doc/Gateway.md)
diff --git a/Gateway.en.md → doc/Gateway.en.md b/Gateway.en.md → doc/Gateway.en.md
@@ -14,13 +14,13 @@ TarsGateway is a general API gateway based on the TARS development framework, su
 
 ## Installation
 
-Before installation, please note that the gateway service depends on MySQL, and the related database and tables[请参考 db_base.sql](./yaml/db_base.sql)
+Before installation, please note that the gateway service depends on MySQL, and the related database and tables[请参考 db_base.sql](../yaml/db_base.sql)
 
 There are two modes to install gateway on tars:
 
 - Install from service market
 
-Please use the latest version of tars framework (>=tarscloud/framework:v3.0.7 or >=K8SFramework:v1.2.5) to install services directly through the service market!
+Please use the latest version of tars framework (>=tarscloud/framework:v3.0.10 or >=K8SFramework:v1.2.5) to install services directly through the service market!
 
 From the top tab of tarsweb, click the service market to enter, then select `base/gatewayserver` in the directory tree on the left, select the corresponding version on the right, and then click Install!
 
@@ -44,7 +44,7 @@ Note that you need to use `db_base.sql` (available for download in the service m
 
 - Install from source
 
-If you want to install the source code, [please refer to](doc/INSTALL_SOURCE_en.md)
+If you want to install the source code, [please refer to](INSTALL_SOURCE_en.md)
 
 Note that DB will be created with one click through the source code installation, and there is no need to create dB in advance
 

diff --git a/Gateway.md → doc/Gateway.md b/Gateway.md → doc/Gateway.md
@@ -6,7 +6,7 @@
 
 TarsGateway 是基于 tars 框架开发的一套通用 api 网关，请求为 http 协议，后端同时支持 tars-tup&tars-tars 协议、tars-json 协议、http 协议。 除了协议转发之外，还支持流量控制，黑白名单等功能。 详细使用文档参考[Tars 文档](https://tarscloud.github.io/TarsDocs/)
 
-更多文档可以参考：[Tars 网关配置使用说明](./doc/operate.md), [服务配置项说明](./doc/config.md)
+更多文档可以参考：[Tars 网关配置使用说明](./operate.md), [服务配置项说明](./config.md)
 
 ## 支持版本说明
 
@@ -18,13 +18,13 @@ TarsGateway 是基于 tars 框架开发的一套通用 api 网关，请求为 ht
 
 ## 安装
 
-在安装之前, 请注意网关服务依赖于 mysql, 相关的库和表[请参考 db_base.sql](./yaml/db_base.sql)
+在安装之前, 请注意网关服务依赖于 mysql, 相关的库和表[请参考 db_base.sql](../yaml/db_base.sql)
 
 在 Tars 上安装网关有两种模式:
 
 - 通过市场安装
 
-请使用最新版本 Tars 框架(tarscloud/framework:v3.0.7 or K8SFramework >= v1.2.5), 直接通过服务市场来安装服务!
+请使用最新版本 Tars 框架( >=tarscloud/framework:v3.0.10 or >=K8SFramework:v1.2.5), 直接通过服务市场来安装服务!
 
 市场从 tarsweb 顶部 tab, 点击服务市场进入, 然后选择左边目录树上的`base/gatewayserver`, 右边选择对应的版本, 然后点击安装!
 
@@ -47,14 +47,16 @@ TarsGateway 是基于 tars 框架开发的一套通用 api 网关，请求为 ht
 </main>
 ```
 
-如果是>framework:v3.1.0, 则不再需要自己创建 db 了, 通过市场安装后, GatewayWebServer 会自动创建数据库表.
+通过市场安装后, GatewayWebServer 会自动创建数据库表.
 
 - 通过源码安装
 
-如果你希望源码安装, [请参考](doc/INSTALL_SOURCE.md)
+如果你希望源码安装, [请参考](INSTALL_SOURCE.md)
 
 注意通过源码安装会一键创建 db, 无须提前创建 db 了.
 
+**建议框架升级到新版本, 且通过市场一键安装!因为源码安装没有发布web管理平台**
+
 ## 功能介绍
 
 ### 1. 代理类型的判断
@@ -84,7 +86,11 @@ TarsGateway 是根据请求 host+url 判断当前请求是什么类型的请求
 
 ### 2. TARS-tup && TARS-tars 协议代理
 
-TARS-tup 协议代理，必须为 post 请求类型，路径为/tup，body 内容为 RequestPacket 包 tars 序列化的内容。TarsGateway 收到包后，去反序列化 body 的内容解析出 RequestPacket 包，然后根据其中的 sServantName 在配置中查找真是的 tars 服务的 obj。如果配置 auto_proxy=1，那么客户端调用时 sServantName 可以填真实的 obj 地址。这里建议：直接对 C 外网暴露的 TarsGateway，建议配置 auto_proxy=0，避免内网的服务都直接对外暴露。另外，proxy 的配置还可以支持 sServerName:sFuncName 的配置，会优先根据, 这种类型配置优先级高于只配置 sServerName 类型的配置。 proxy 配置如下：
+关键点如下: 
+- TARS-tup 协议代理，必须为 post 请求类型，路径为/tup，body 内容为 RequestPacket 包 tars 序列化的内容。
+- TarsGateway 收到包后，去反序列化 body 的内容解析出 RequestPacket 包，然后根据其中的 sServantName 在配置中查找真是的 tars 服务的 obj。
+- 如果配置 auto_proxy=1，那么客户端调用时 sServantName 可以填真实的 obj 地址。这里建议：直接对外网暴露的 TarsGateway，建议配置 auto_proxy=0，避免内网的服务都直接对外暴露。
+- proxy 的配置还可以支持 sServerName:sFuncName 的配置，会优先根据, 这种类型配置优先级高于只配置 sServerName 类型的配置。 proxy 配置如下：
 
 ```
 <main>
@@ -114,7 +120,10 @@ proxy 配置支持接口黑名单策略，即在 proxy 配置的情况下，可
     filterheaders = X-GUID|X-XUA
 ```
 
-调用后端 tars 服务时，TarsGateway 默认采用 tars 自己的缺省轮训负载均衡策略（robin 轮训），也可以通过配置自定义 hash 策略，hash_type 为 1 时，根据客户端请求 id 进行 tarshash 调用; hash_type 为 2 时，根据指定 http 头(配种中的 httpheader)进行 tarshash 调用，比如 http 头中的 X-GUID，注意这里选择 httpheader 需要合理，避免过于集中某个值导致负载均衡过于不均匀的现象； hash_type 为 3 时，则根据客户端的 ip 进行 tarshash 调用。 如果 obj 后面没有配置 hash_type，那么采用 tars 默认轮训调用。配置举例如下：
+调用后端 tars 服务时，TarsGateway 默认采用 tars 自己的缺省轮训负载均衡策略（robin 轮训），也可以通过配置自定义 hash 策略.
+- hash_type 为 1 时，根据客户端请求 id 进行 tarshash 调用; 
+- hash_type 为 2 时，根据指定 http 头(配种中的 httpheader)进行 tarshash 调用，比如 http 头中的 X-GUID，注意这里选择 httpheader 需要合理，避免过于集中某个值导致负载均衡过于不均匀的现象； 
+- hash_type 为 3 时，则根据客户端的 ip 进行 tarshash 调用。 如果 obj 后面没有配置 hash_type，那么采用 tars 默认轮训调用。配置举例如下：
 
 ```
     <proxy>
@@ -146,6 +155,8 @@ TARS-JSON 协议代理，支持两种类型的接口。
     { "rsp": { "otherMsg": [ "1 + 9900989 = 9900990" ], "msg": "succ.", "sum": 9900990, "ret": 0 }, "": 0 }
 ```
 
+**注意req, x, y, rsp, msg等名称和tars协议中定义的接口参与名称要匹配!!!**
+
 - **相关参数都在 http body 中指定：**
 
 必须为 post 请求类型，路径为/json，body 内容为 json 结构。其中必须有 reqid, obj, func, data 四个字段，分别表示请求 id、服务 servant、服务接口、接口参数，对应 RequestPacket 中的 reqid:iRequestId, obj:sServantName, func:sFuncName。data 内容为接口中的参数，key 为参数名，value 为参数内容。除了以上必选四个字段之外，context 为可选字段。回包内容包括 reqid 和 data， data 为接口出参内容，其中 "" 的 key 对应内容为函数返回值。 这里除了这里包格式不一样，其他后面的逻辑都和 TARS-tup 类型一样。请求参数举例如下：
@@ -165,6 +176,9 @@ TARS-JSON 协议代理，支持两种类型的接口。
     }
 ```
 
+**注意req, x, y, rsp, msg等名称和tars协议中定义的接口参与名称要匹配!!!**
+
+
 ### 4. 普通 HTTP 协议代理
 
 普通 HTTP 协议代理，类似 nginx 的反向代理功能，主要功能包括根据 domain 和 url 进行请求转发，后端负载均衡，容错容灾，黑名单屏蔽，流量控制等功能。
@@ -239,7 +253,7 @@ IP 黑名单和流控策略， 同时支持 TarsGateway 的三种协议，所以
 ## 5. 身份鉴权
 
 支持调用后端服务时，在网关层先进行统一身份鉴权，如果鉴权失败，那么给客户端直接返回 401，客户端业务可以根据此情况跳转登陆等操作等。鉴权流程如下：
-![网关身份鉴权](images/pic_verify_01.png)
+![网关身份鉴权](../images/pic_verify_01.png)
 
 ### 网关鉴权配置
 

diff --git a/doc/INSTALL_SOURCE.md b/doc/INSTALL_SOURCE.md
@@ -1,4 +1,4 @@
-- [返回](README.md)
+[返回](./Gateway.md)
 
 ## 安装
 

diff --git a/doc/INSTALL_SOURCE_en.md b/doc/INSTALL_SOURCE_en.md
@@ -1,4 +1,4 @@
--- [Back](README.en.md)
+-- [Back](./Gateway.en.md)
 
 # Installation
 

diff --git a/doc/config.md b/doc/config.md
@@ -1,4 +1,5 @@
 
+[返回](./Gateway.md)
 # 服务配置说明
 
 ```

diff --git a/doc/install.md b/doc/install.md
@@ -1,3 +1,5 @@
+
+[返回](./Gateway.md)
 # 安装
 
 ## 支持一键安装（需要先具备tarscpp编译环境）

diff --git a/doc/operate.md b/doc/operate.md
@@ -1,3 +1,5 @@
+[返回](./Gateway.md)
+
 # Tars网关配置使用说明
 
 ## Tars-Json && Tars-Tup 协议代理配置

diff --git a/Dockerfile.cpp → dockerfile/Dockerfile.cpp b/Dockerfile.cpp → dockerfile/Dockerfile.cpp
diff --git a/Dockerfile.nodejs → dockerfile/Dockerfile.nodejs b/Dockerfile.nodejs → dockerfile/Dockerfile.nodejs
diff --git a/images/config_server.jpeg b/images/config_server.jpeg
diff --git a/images/gateway_web.jpeg b/images/gateway_web.jpeg