用户文档 on Apache Dubbo

快速开始

Mon, 01 Jan 0001 00:00:00 +0000

让我们从将 HTTP 请求转换为 Dubbo2 请求的案例来快速展示 Pixiu 的能力。

用例

Pixiu 将 Client 的 HTTP 请求转换为 Dubbo2 请求，然后转发给背后的 Dubbo Server，然后将 Dubbo Server 的响应转换为 HTTP 响应，最后返回给 Client。

架构图

案例

案例路径请查看 /samples/http/simple/http-http

Dubbo Server 实现和启动

Dubbo Server 提供用户增删改查的相关接口，其具体的代码实现见案例路径下的 server

Dubbo Server 的配置如下所示，注册了 Dubbo2 协议的 interface com.dubbogo.pixiu.UserService。

dubbo:
 registries:
 zk:
 protocol: zookeeper
 timeout: 3s
 address: 127.0.0.1:2181
 protocols:
 dubbo:
 name: dubbo
 port: 20000
 provider:
 registry-ids: zk
 services:
 UserProvider:
 group: test
 version: 1.0.0
 cluster: test_dubbo
 serialization: hessian2
 interface: com.dubbogo.pixiu.UserService

Pixiu 配置和启动

为了用例的场景，Pixiu 需要启动对应的 HTTP Listener 进行 HTTP 请求的监听，所以就会使用到 httpconnectionmanager。然后因为要将 HTTP 请求转换为 Dubbo请求，所以需要使用 dgp.filter.http.dubboproxy，这里我们将其auto_resolve 设置为true，表示开启 HTTP to Dubbo 默认转换协议(具体定义请看附录)。

启动 dubbo-go-pixiu

Mon, 01 Jan 0001 00:00:00 +0000

Start

如何启动 dubbo-go-pixiu

1 cd samples dir

cd samples/dubbo/simple

我们可以使用 start.sh 快速运行示例。如需更多信息，请执行以下命令获取帮助

./start.sh [action] [project]
./start.sh help

下面我们分步运行 body 示例

2 准备配置文件和 docker 环境

prepare 命令会准备 dubbo-server 和 pixiu 的配置文件，并启动所需的 docker 容器

./start.sh prepare body

如果手动准备配置文件，请注意：

将 conf.yaml 中的 $PROJECT_DIR 修改为你电脑中的绝对路径

3 启动 dubbo 或 http 服务器

./start.sh startServer body

4 启动 pixiu

./start.sh startPixiu body

如果手动运行 pixiu，请使用以下命令

 go run cmd/pixiu/*.go gateway start -c /[absolute-path]/dubbo-go-pixiu/samples/dubbo/simple/body/pixiu/conf.yaml

5. 尝试发送请求

使用 curl 尝试或运行单元测试

API 模型介绍

Mon, 01 Jan 0001 00:00:00 +0000

Api

API 模型介绍，建议在为 api_config.yaml 自定义 API 之前阅读。

Api Gateway

API 是 dubbo-go-pixiu 的关键特性。通过此特性，您可以将 dubbo 服务暴露为 HTTP 服务。

Configuration

Sample:

name: api name
description: api description
resources:
 - path: '/'
 type: restful
 description: resource documentation
 methods:
 - httpVerb: GET
 enable: true
 inboundRequest:
 requestType: http
 queryStrings:
 - name: id
 required: false
 integrationRequest:
 requestType: dubbo
 mappingParams:
 - name: queryStrings.id
 mapTo: 1
 applicationName: "BDTService"
 interface: "com.ikurento.user.UserProvider"
 method: "GetUser"
 clusterName: "test_dubbo"

definitions:
 - name: modelDefinition
 schema: >-
 {
 "type" : "object",
 "properties" : {
 "id" : {
 "type" : "integer"
 },
 "type" : {
 "type" : "string"
 },
 "price" : {
 "type" : "number"
 }
 }
 }

name :

配置文件

Mon, 01 Jan 0001 00:00:00 +0000

Config

Pixiu 支持使config用参数 -c 指定本地配置文件，您可以在那些样本的 pixiu 目录中找到它。 Pixiu 使用类似于 envoy 的配置抽象，如 listener、filter、route 和 cluster。此外，pixiu 提供了另一个特定于 dubbo 的配置名为 api_config，通过它 dubbo-filter 可以将 http 请求转换为 dubbo 泛化调用。您也可以在那些样本的 pixiu 目录中找到它。文档 Api 模型提供了关于 pixiu 配置抽象的 api_config 规范。本文档主要描述 pixiu 配置抽象，以下是一个示例：


static_resources:
 listeners:
 - name: "net/http"
 protocol_type: "HTTP"
 address:
 socket_address:
 address: "0.0.0.0"
 port: 8888
 filter_chains:
 filters:
 - name: dgp.filter.httpconnectionmanager
 config:
 route_config:
 routes:
 - match:
 prefix: "/user"
 route:
 cluster: "user"
 cluster_not_found_response_code: 505
 http_filters:
 - name: dgp.filter.http.httpproxy
 config:
 - name: dgp.filter.http.response
 config:
 clusters:
 - name: "user"
 lb_policy: "lb"
 endpoints:
 - id: 1
 socket_address:
 address: 127.0.0.1
 port: 1314

更多细节可以在 pkg/model/bootstrap.go 中找到

启动和配置

Mon, 01 Jan 0001 00:00:00 +0000

Pixiu 启动命令

Pixiu 分为两个形态 Gateway 和 Sidecar，目前 Pixiu 可执行程序的命令如下所示，其中 pixiu 是可执行文件名称。注意，-c 后是本地配置文件的绝对路径。

pixiu gateway start -c /config/conf.yaml

配置详解

Pixiu 接受 yaml 格式的文件作为其主配置文件，其中对 Pixiu 的各类组件进行配置。我们以快速开始中的配置文件为例，详细讲解其中的组成部分，并且列出可能的扩展。

static_resources:
 listeners:
 - name: "net/http"
 protocol_type: "HTTP"
 address:
 socket_address:
 address: "0.0.0.0"
 port: 8883
 filter_chains:
 filters:
 - name: dgp.filter.httpconnectionmanager
 config:
 route_config:
 routes:
 - match:
 prefix: "*"
 http_filters:
 - name: dgp.filter.http.dubboproxy
 config:
 dubboProxyConfig:
 auto_resolve: true
 registries:
 "zookeeper":
 protocol: "zookeeper"
 timeout: "3s"
 address: "127.0.0.1:2181"
 username: ""
 password: ""

首先，类似 envoy的配置，static_resources 表示如下都是静态配置。在静态配置中包括 Listener，NetworkFilter，Route，HttpFilter等组件，它们之间并不是完全独立的。

部署操作

Mon, 01 Jan 0001 00:00:00 +0000

一、Docker镜像部署

注：首先确认本机已经安装好docker并且启动

1、从docker hub 拉取 pixiu 镜像

docker pull phial3/dubbo-go-pixiu:latest

2、按照需求准备pixiu配置

pixiu配置参数详解

准备 log.yml 和 conf.yaml 配置文件，将这两个配置文件在pixiu启动的时候挂在到本地

3、启动 pixiu

前台启动：，可方便查看服务信息运行是否正常

docker run --name dubbo-go-pixiu -p 8883:8883 \
 -v /yourpath/conf.yaml:/etc/pixiu/conf.yaml \
 -v /yourpath/log.yml:/etc/pixiu/log.yml \
 apache/dubbo-go-pixiu:latest

后台启动：

docker run -itd --name dubbo-go-pixiu -p 8883:8883 \
 -v /yourpath/conf.yaml:/etc/pixiu/conf.yaml \
 -v /yourpath/log.yml:/etc/pixiu/log.yml \
 apache/dubbo-go-pixiu:latest

注：

(1) --name命令后面的dubbo-go-pixiu为你的pixiu实例的名称，可自行修改

(2)命令中的/yourpath/**路径为你本地存放pixiu配置文件的绝对路径

4、查看 pixiu 实例

docker ps | grep dubbo-go-pixiu 正在运行的pixiu实例

docker exec -it dubbo-go-pixiu /bin/bash 进入pixiu