Use a separate folder to store multi-Language docs

README.md

@@ -108,7 +108,7 @@ API是Gateway的核心概念，我们可以在Gateway的中维护对外的API，
 Routing是一个路由策略，根据HTTP Request中的Cookie，Querystring、Header、Path中的一些信息把流量分发到或者复制到指定的Cluster，通过这个功能，我们可以实现AB Test和线上引流，[更多](./docs/routing.md)。
 
 ## 参与开发
-[更多](./docs/build.md)
+[更多](./docs-cn/build.md)
 
 ## 交流方式-微信
 ![](./images/qr.jpg)

docs-cn/api.md

@@ -0,0 +1,172 @@
+API
+-----------
+API是Gateway的核心概念。可以通过Gateway的API-Server管理API。
+
+# API属性
+## ID
+API的ID，唯一标识一个API。
+
+## Name
+API的名称。
+
+## URLPattern
+URL匹配表达式，Gateway使用该字段来匹配原始请求的URL。该字段必须和`Method`配合使用，同时满足才算这个请求匹配了这个API。
+
+### URLPattern表达式
+定义API的`URL`，使用`/`来分割URL Path的每个部分，每个部分可以这些类型：
+
+* 常量字符串 任意URL合法的字符串，可以使用`*`匹配任何字符串
+* (number):argeName 指定这个部分是一个数字变量
+* (string) 指定这个部分是一个字符串变量
+* (enum:enum1|enum1|enum1) 指定这部分是一个枚举变量，可选的枚举值使用|分割
+* 如果需要使用这些变量（例如在URL Rewrite的时候）可以使用:
+ * (number):id 变量名称为id
+ * (string):name 变量名称为name
+ * (enum:on|off):action 变量名称为action 
+
+一些例子：
+* `/api/v1/product/(number):id`
+* `/api/v1/product/(number):id/(enum:online|offline):action`
+* `/api/v1/*`
+
+## Method（可选）
+匹配请求的`HTTP Method`字段， `*` 匹配所有的HTTP Method（GET,PUT,POST,DELETE）。
+
+## Domain（可选）
+匹配请求的HOST字段。
+
+## MatchRule
+`URLPattern`,`Method`,`Domain`的匹配规则
+* MatchDefault `URLPattern` && (`Method` || `Domain`)
+* MatchAll `URLPattern` && (`Method` && `Domain`)
+* MatchAny `URLPattern` && (`Method` || `Domain`)
+
+## Status
+API 状态枚举, 有2个值组成： `UP` 和 `Down`。只有`UP`状态才能生效。
+
+## IPAccessControl（可选）
+IP的访问控制，有黑白名单2个部门组成。
+
+## DefaultValue（可选）
+API的默认返回值，当后端Cluster无可用Server的时候，Gateway将返回这个默认值，默认值由Code、HTTP Body、Header、Cookie组成。可以用来做Mock或者后端服务故障时候的默认返回。
+
+## 聚合请求
+聚合请求是原始请求转发到多个后端Server，并且把多个返回结果合并成一个JSON返回，并且可以指定每个转发请求的结果在最终JSON对象中的属性名称。多个转发请求可以同时发送，也可以按批次发送(后面请求参数依赖前面请求的返回值)。使用`BatchIndex`来设置每个转发请求的顺序。
+
+例子
+* 原始请求: `/api/v1/aggregation/1`
+* 转发请求: `/api/v1/users/1`，返回：`{"name":"zhangsan"}`，属性名为`user`
+* 转发请求: `/api/v1/accounts/1`，返回：`{"type":"test", "accountId":"123"}`，属性名为`account`
+* 最终返回结果为：`{"user":{"name":"zhangsan"}, "account":{"type":"test", "accountId":"123"}}`
+
+## Nodes
+请求被转发到的后端Cluster。至少设置一个转发Cluster，一个请求可以被同时转发到多个后端Cluster（目前仅支持GET请求设置多个转发）。在转发的时候，针对每一个转发支持以下特性：
+
+### 支持URL重写
+使用URL重写表达式来重构转发到后端Server的真实URL
+
+#### URL重写表达式
+定义重写的`URL`，支持在表达式中使用变量，并且使用运行期用真实的值替换这些变量，变量使用`$()`包裹，用`.`来表示变量的属性
+
+##### origin变量
+origin变量用来提取原始请求的`query string`,`header`,`cookie`,`body`中的数据，对于query中的多个同名参数，不支持独立获取
+
+假设原始请求
+* URL: `/api/v1/users?id=1&name=fagongzi&page=1&pageSize=100`,
+* Header: `x-test-token: token1, x-test-id: 100`
+* Cookie: `x-cookie-token: token2, x-cookie-id: 200`
+* Body: `{"type":1, "value":{"id":100, "name":"zhangsan"}}`
+
+变量例子
+* $(origin.query) = `?id=1&name=fagongzi&page=1&pageSize=100`
+* $(origin.path) = `/api/v1/users`
+* $(origin.query.id) = `1`, $(origin.query.name) = `fagongzi`, $(origin.query.page) = `1`, $(origin.query.pageSize) = `100`
+* $(origin.header.x-test-token) = `token1`, $(origin.header.x-test-id) = `100`
+* $(origin.cookie.x-cookie-token) = `token2`, $(origin.cookie.x-cookie-id) = `200`
+* $(origin.body.type) = `1`, $(origin.body.value.id) = `100`, $(origin.body.value.name) = `zhangsan`
+
+#### param变量
+param变量用来提取API的`URLPattern`中定义的变量
+
+假设:
+* API的`URLPattern`为`/api/v1/users/(number):id/(enum:on|off):action`
+* 请求的URL为`/api/v1/users/100/on`
+
+变量例子
+* $(param.id) = `100`
+* $(param.action) = `on`
+
+#### depend变量
+depend变量用来提取依赖聚合请求返回值中的数据
+
+假设聚合请求有2个,分别为user和account
+* user: {"name":"zhangsan"}
+* account: {"id":"123456"}
+
+变量例子
+* $(depend.user.name) = `zhangsan`
+* $(depend.account.id) = `123456`
+
+#### 一些URL重写的表达式例子
+* `/api/v1/users$(origin.query)`
+* `$(origin.path)?name=$(origin.header.x-user-name)&id=$(origin.body.user.id)`
+* `/api/v1/users?id=$(param.id)&action=$(param.action)`
+* `/api/v1/accounts?id=$(depend.user.accountId)`
+
+### 支持对原始请求的参数校验
+ 支持针对`querystring`、`json body`、`cookie`、`header`、`path value`中的任意属性配置正则表达式的校验规则
+
+### 支持失败重试
+ 可以设置`retryStrategy`指定根据http返回码重试请求，可以设置重试最大次数以及重试间隔。
+
+### 支持API级别的超时时间覆盖全局设置
+ 可以设置`ReadTimeout`和`WriteTimeout`来指定请求的读写超时时间，不设置默认使用全局设置。
+
+## Perms（可选）
+设置访问这个API需要的权限，需要用户自己开发权限检查插件。
+
+## AuthFilter（可选）
+指定该API所使用的Auth插件名称，Auth插件的实现可以借鉴[JWT插件](https://github.com/fagongzi/jwt-plugin)
+
+## RenderTemplate
+使用RenderTemplate可以重新定义返回的数据，包括数据的格式，字段等等。
+
+## UseDefault（可选）
+
+当该值为True且`DefaultValue`存在时，直接使用`DefaultValue`作为返回值。
+
+## MatchRule（可选）
+
+| MatchRule | Logic |
+| - | - |
+| MatchDefault | `Domain` \|\| (`URLPattern` && `Method`) |
+| MatchAll | `Domain` && `URLPattern` && `Method` |
+| MatchAny | `Domain` \|\| `URLPattern` \|\| `Method` |
+
+## Position（可选）
+
+API匹配时按该值的升序匹配，即值越小优先级越高。默认值为0。
+
+## Tags（可选）
+给API加上Tag标签，便于维护和检索。
+
+## WebSocketOptions（可选）
+websocket选项，设置该API为`websocket`，注意：`websocket特性还处于试验阶段，默认关闭，可以使用--websocket启用特性`。网关转发websocket的时候，`Origin`默认使用后端Server的地址，如果需要设置特殊值，可以指定`Origin`参数。
+
+## MaxQPS（可选）
+API能够支持的最大QPS，用于流控。Gateway采用令牌桶算法，根据QPS限制流量，保护后端API被压垮。API的优先级高于`Server`的配置
+
+## CircuitBreaker（可选）
+熔断器，设置后端API的熔断规则，API的优先级高于`Server`的配置。熔断器分为3个状态：
+
+* Open
+
+ Open状态，正常状态，Gateway放入全部流量。当Gateway发现失败的请求比例达到了设置的规则，熔断器会把状态切换到Close状态
+
+* Half
+
+ Half状态，尝试恢复的状态。在这个状态下，Gateway会尝试放入一定比例的流量，然后观察这些流量的请求的情况，如果达到预期就把状态转换为Open状态，如果没有达到预期，恢复成Close状态
+
+* Close
+
+ Close状态，在这个状态下，Gateway禁止任何流量进入这个后端Server，在达到指定的阈值时间后，Gateway自动尝试切换到Half状态，尝试恢复。

docs/apiserver-en.md → docs-cn/apiserver.md

@@ -1,8 +1,8 @@
 ApiServer
 --------------
-ApiServer provides GRPC APIs to manage metadata of Gateway which is Cluster,Server, Routing, and API info.
+ApiServer对外提供GRPC接口，用来管理Gateway的元信息（Cluster、Server、Routing以及API）。
 
-# APIs Exposed
+# 对外开放的接口：
 ```
 // MetaService is a interface for meta manager
 service MetaService {
@@ -32,7 +32,7 @@ service MetaService {
  rpc GetBindServers (GetBindServersReq) returns (GetBindServersRsp) {}
 }
 ```
-The PB is under `pkg/pb/rpcpb`.
+具体的PB在项目的`pkg/pb/rpcpb`目录下
 
-# Client
-For the moment, Gateway supports Go client. Here are [examples](../examples) of Go clients of Gateway which manage metadata.
+# 客户端
+目前Gateway支持GO的客户端，这里以Gateway的GO客户端管理元信息的例子，参见[examples](../examples)

docs/benchmark-en.md → docs-cn/benchmark.md

@@ -1,4 +1,4 @@
-# Non-rigorous Stress Testing Results
+# 非严谨压力测试结果
 
 ## Hardware
 
@@ -59,11 +59,13 @@
 
 ## 备注
 
-- The testing server has two virtual CPUs and 4G dedicated to a KVM instance. So the result is not rigorous
-- All testing result has been posted without filtering.
-- The testing interval is pretty short.
-- nmon testing interval is 0.5.
-- Gateway, wrk and hello world are on different machines. They communicate through a 1000Mb/s router.
+- 测试主机划了两颗虚拟CPU和4G内存给一台KVM虚拟机，所以以下数据可能不是该机器的真实水平；
+- 测试结果未经筛选全部贴上来了，具体哪个是有效数据自行判断；
+- 测试间隔比较短不确定每次测试时主机是否处于最佳状态；
+- nmon采集间隔为0.5秒；
+- 网关、wrk与hello world程序分别放在不同机器上，之间以千兆网线经交换机通信，无法确定网络对测试结果造成的影响；
+- 服务器服役时间略长，小脾气无法预测；
+- ε=ε=ε=┏(゜ロ゜;)┛
 
 ## Benchmark 1
 

docs/build-en.md → docs-cn/build.md

@@ -1,43 +1,43 @@
-Gateway Environment Setup
+搭建Gateway环境
 ------------------------
-This chapter aims to help you set up Gateway environment.
+这个章节帮助你搭建Gateway环境
 
-# Preparation
+# 准备
 ## Etcd
-Gateway currently supports Etcd as the storage of metadata. To set up etcd, please refer to [etcd environment](https://github.com/coreos/etcd)
+Gateway目前支持Etcd作为元数据区的存储，所以需要一个Etcd环境，参考：[etcd environment](https://github.com/coreos/etcd)
 
 
 ## Golang
-If you would like to compile Gateway from source code, you need a [Golang environment](https://github.com/golang/go). Go version `1.11` and above is required.
+如果你希望从源码编译Gateway，你需要一个[golang 环境](https://github.com/golang/go)，必须使用`1.11`及以上的版本。
 
-# Compiling from Source Code
-- Makefile
+# 从源码编译
+- 使用Makefile脚本
 
- The following commands are executed under `$GOPATH/src/github.com/fagongzi/gateway`.
+ 以下命令默认在项目根目录（即`$GOPATH/src/github.com/fagongzi/gateway`）目录下执行。
 
- - Compiling binary file for the current OS.
+ - 编译适合当前系统的二进制文件
 
  ```bash
  make release_version='version string'
  ```
 
- - Compiling binary file for a specific OS
+ - 指定编译的二进制文件类型
 
  ```bash
  # Linux
  make release release_version='version string'
 
- # Darwin(Mac OS X)
+ # Darwin(mac osx)
  make release_darwin release_version='version string'
  ```
 
- - Packaging project into a Docker image
+ - 打包为docker镜像
 
  ```bash
  make docker release_version='version string'
  ```
 
- - Packing project into a Docker image with customized content
+ - 打包为docker镜像，且定制镜像内容
 
  ```bash
  # for demo, including etcd, proxy, apiserver, ui
@@ -53,23 +53,23 @@ If you would like to compile Gateway from source code, you need a [Golang enviro
  make docker release_version='version string' with=apiserver
  ```
 
- - For more information on compiling
+ - 更多使用说明
 
  ```bash
  make help
  ```
 
-# Gateway Component
-Gateway has two components: `ApiServer` and `Proxy`.
+# Gateway组件
+Gateway运行环境包含2个组件：`ApiServer` 和 `Proxy`
 
 * ApiServer
- ApiServer provides APIs to manage metadata.
+ 对外提供API管理元数据。
 
 * Proxy
- Proxy is a stateless API proxy which provides direct access to clients.
+ Proxy是一个无状态的API代理，提供给终端用户直接访问。
 
 ## ApiServer
-ApiServer provides GRPC service to manage Gateway metadata.
+ApiServer 对外提供GRPC的服务，用来管理Gateway的元数据
 
 ```bash
 $ ./apiserver --help
@@ -96,12 +96,12 @@ Usage of ./apiserver:
  The prefix for service name. (default "/services")
 ```
 
-`discovery` option is used to determine whether to use service discovery to publish external APIs provided by ApiServer.
-`namespace` option is used to isolate multiple environments. It has to be consistent with `namespace` in `Proxy`.
+`discovery`参数用来是否使用服务发现的方式发布ApiServer提供的对外接口
+`namespace`参数用来隔离多个环境，这个配置需要和对应的`Proxy`的`namespace`一致
 
 
 ## proxy
-Proxy is the unified entrance of all internal APIs, which is the API access layer.
+Proxy是内部所有API的统一对外入口，也就是API统一接入层。
 
 ```bash
 $ ./proxy --help
@@ -150,20 +150,20 @@ Usage of ./proxy:
  Show version info
 ```
 
-`namespace` option is used to isolate multiple environments. It has to be consistent with `namespace` in `ApiServer`.
+`namespace`参数用来隔离多个环境，这个配置需要和对应的`ApiServer`的`namespace`一致
 
-# Running Environment
-We use 3 etcd servers, 1 ApiServer server, and 3 Proxy servers as an example.
+# 运行环境
+我们以三台etcd、一台ApiServer,三台Proxy的环境为例
 
-## Info
+## 环境信息
 
-|Component|IP|
+|组件|环境|
 | -------------|:-------------:|
-|etcd cluster|192.168.1.100,192.168.1.101,192.168.1.102|
+|etcd集群环境|192.168.1.100,192.168.1.101,192.168.1.102|
 |Proxy|192.168.1.200,192.168.1.201,192.168.1.202|
 |ApiServer|192.168.1.203|
 
-## Starting Proxy
+## 启动Proxy
 ```bash
 ./proxy --addr=192.168.1.200:80 --addr-rpc=192.168.1.200:9091 --addr-store=etcd://192.168.1.100:2379,192.168.1.101:2379,192.168.1.102:2379 --namespace=test
 ```
@@ -176,14 +176,14 @@ We use 3 etcd servers, 1 ApiServer server, and 3 Proxy servers as an example.
 ./proxy --addr=192.168.1.202:80 --addr-rpc=192.168.1.202:9091 --addr-store=etcd://192.168.1.100:2379,192.168.1.101:2379,192.168.1.102:2379 --namespace=test
 ```
 
-API addresses available to users: 192.168.1.201:80, 192.168.1.201:80, 192.168.1.202:80
+用户的API接入地址可以为：192.168.1.201:80、192.168.1.201:80、192.168.1.202:80其中任意一个
 
-## Starting ApiServer
+## 启动ApiServer
 ```bash
 ./apiserver --addr=192.168.1.203:9091 --addr-store=etcd://192.168.1.100:2379,192.168.1.101:2379,192.168.1.102:2379 --discovery --namespace=test
 ```
 
-## Use ApiServer to create metadata
+## 调用ApiServer创建元信息
 [Gateway Restful API](./restful.md)
 
-[Gateway grpc client example](../examples)
+[Gateway grpc客户端例子](../examples)

docs-cn/cluster.md

@@ -0,0 +1,14 @@
+Cluster
+-------
+在Gateway中，Cluster是一个逻辑的概念。它是后端真实Server的一个逻辑组，在同一个组内的后端Server提供相同的服务。
+
+# Cluster属性
+一个Cluster包含2部分信息:
+## ID
+Cluster ID, 全局唯一。
+
+## Name
+Cluster名称
+
+## LoadBalance
+Cluster采取的负载均衡算法。