Orange API 网关部署安装总结

背景

orange是基于Nginx+lua研发的API网关项目。该项目为国人自研项目，大部分组件参考Kong网关项目。但是项目活跃性不大，文档不够丰富详细（至今官网文档还是0.6.4版本，大量issue状态open），插件缺少详细的说明。另外项目部署自动化较低，文档不够详细，部署有一定困难。

本文在suse系统上部署orange高低版本（0.6.1和0.7.1两个版本）。详细说明的编译部署的过程和注意事项，算是为项目文档做点贡献，用爱发电。

文中讲解了对接Tidb数据的配置注意事项。

第一部分编译安装

编译安装以0.6.4版本为例。

1.1 编译依赖环境安装

为了部署安装OpenResty，需要提前准备编译环境，依赖有：

GCC 编译器

nginx是C语言编写的，编译安装需要安装 gcc和gcc-c++。不同操作系统安装有差异，在线情况较为简单，例如ubuntu使用下面的命令即可：
1
# apt-get install gcc g++ libreadline-dev libncurses5-dev libpcre3-dev libssl-dev perl make build-essential
如果是suse或者centos操作系统：
1
2
# yum install -y gcc
# yum install -y gcc-c++

注：离线安装较为繁琐，例如suse需要离线下载rpm包安装。

1.2 `OpenResty`安装

openResty是一个基于nginx+lua的WEB服务器,所以安装此软件的过程中也会将nginx一并安装好，配置要把http_stub_status_module模块加上。具体安装如下：

1.2.1 安装介质准备

将安装介质上传至/approot1/orangesoft(路径自定义),介质清单：

lor-0.3.4.tar.gz
openresty-1.19.3.1.tar.gz
orange-0.6.4.tar.gz
pcre-8.39.tar.gz
zlib-1.2.11.tar.gz
openssl-1.0.2p.tar.gz

使用tar命令将包依次解压。

1.2.2 安装

安装命令：

root@deeplearning:/approot1/orangesoft # tar -zxvf pcre-8.39.tar.gz
root@deeplearning:/approot1/orangesoft # tar -zxvf zlib-1.2.11.tar.gz
root@deeplearning:/approot1/orangesoft # tar -zxvf openssl-1.0.2p.tar.gz
# 
root@deeplearning:/approot1/orangesoft # tar -zxvf openresty-1.19.3.1.tar.gz
root@deeplearning:/approot1/orangesoft # cd openresty-1.19.3.1
root@deeplearning:/approot1/orangesoft/openresty-1.19.3.1 # ./configure --with-luajit --with-http_stub_status_module --with-openssl=/approot1/orangesoft/openssl-1.0.2p --with-zlib=/approot1/orangesoft/zlib-1.2.11 --with-pcre=/approot1/orangesoft/pcre-8.39

注意：

参数：--with-http_stub_status_module，必须依赖，orange启动依赖组件
参数：--prefix=/approot1/openresty，参数可以指定安装目录。这里没有配置，会使用默认的路径：/usr/local/openresty。

配置完成后，开始编译和安装：

1 2	root@deeplearning:/approot1/orangesoft/openresty-1.19.3.1 # make root@deeplearning:/approot1/orangesoft/openresty-1.19.3.1 # make install

1.2.3 配置环境变量

配置环境变量，在/etc/profile文件中最佳下面的配置：

1 2	export PATH=$PATH:/usr/local/openresty/nginx/sbin export PATH=$PATH:/usr/local/openresty/bin

最后当前shell中生效环境变量（或者重新开一个shell）：

1	# source /etc/profile

1.2.4 验证

验证nginx：

1 2	# nginx -v nginx version: openresty/1.19.3.1

验证openresty：

# resty -v
resty 0.27
nginx version: openresty/1.19.3.1
built by gcc 4.8.5 (SUSE Linux) 
built with OpenSSL 1.0.2p  14 Aug 2018
TLS SNI support enabled
configure arguments: --prefix=/usr/local/openresty/nginx --with-cc-opt=-O2 --add-module=../ngx_devel_kit-0.3.1 --add-module=../echo-nginx-module-0.62 --add-module=../xss-nginx-module-0.06 --add-module=../ngx_coolkit-0.2 --add-module=../set-misc-nginx-module-0.32 --add-module=../form-input-nginx-module-0.12 --add-module=../encrypted-session-nginx-module-0.08 --add-module=../srcache-nginx-module-0.32 --add-module=../ngx_lua-0.10.19 --add-module=../ngx_lua_upstream-0.07 --add-module=../headers-more-nginx-module-0.33 --add-module=../array-var-nginx-module-0.05 --add-module=../memc-nginx-module-0.19 --add-module=../redis2-nginx-module-0.15 --add-module=../redis-nginx-module-0.3.7 --add-module=../rds-json-nginx-module-0.15 --add-module=../rds-csv-nginx-module-0.09 --add-module=../ngx_stream_lua-0.0.9 --with-ld-opt=-Wl,-rpath,/usr/local/openresty/luajit/lib --with-http_stub_status_module --with-openssl=/approot1/orange/soft/openssl-1.0.2p --with-zlib=/approot1/orange/soft/zlib-1.2.11 --with-pcre=/approot1/orange/soft/pcre-8.39 --with-openssl-opt=-g --with-pcre-opt=-g --with-zlib-opt=-g --with-stream --with-stream_ssl_module --with-stream_ssl_preread_module --with-http_ssl_module

openresty 组件安装成功。

1.3 安装`lor`

1.3.1 介质准备

加压安装包：

1 2	root@deeplearning:/approot1/orangesoft # tar -zxvf lor-0.3.4.tar.gz root@deeplearning:/approot1/orangesoft # cd lor-0.3.4

执行编译安装：

root@deeplearning:/approot1/orangesoft/lor-0.3.4 # make install 
install lor runtime files to /usr/local/lor
lor runtime files installed.
install lord cli to /usr/local/bin/
lord cli installed.
lor framework installed successfully.

1.4 安装orange

4.1 介质准备

1 2	root@deeplearning:/approot1/orangesoft # tar -zxvf orange-0.6.4.tar.gz root@deeplearning:/approot1/orangesoft # cd orange-0.6.4

4.2 编译安装

1	root@deeplearning:/approot1/orangesoft/orange-0.6.4 # make install

默认安装目录为/usr/local/orange：

root@deeplearning:/usr/local # cd orange/
root@deeplearning:/usr/local/orange # ll
total 52
drwxrwxr-x 2 sysop  root 4096 May 16  2017 api
drwxrwxr-x 5 sysop  root 4096 May 16  2017 bin
drwx------ 2 nobody root 4096 Jun  4 01:25 client_body_temp
drwxrwxr-x 2 sysop  root 4096 Jun  4 01:25 conf
drwxrwxr-x 7 sysop  root 4096 May 16  2017 dashboard
drwx------ 2 nobody root 4096 Jun  4 01:25 fastcgi_temp
drwxrwxr-x 2 sysop  root 4096 May 16  2017 install
drwxr-xr-x 2 sysop  root 4096 Jun  4 01:25 logs
drwxrwxr-x 6 sysop  root 4096 May 16  2017 orange
drwx------ 2 nobody root 4096 Jun  4 01:25 proxy_temp
drwx------ 2 nobody root 4096 Jun  4 01:25 scgi_temp
drwxr-xr-x 2 sysop  root 4096 Jun  4 01:25 tmp
drwx------ 2 nobody root 4096 Jun  4 01:25 uwsgi_temp

4.3 配置连接`mysql`或`Tidb`

4.3.1 更新`mysql`依赖包

主要使用最新版本的包替换旧版本的包：

1	# /usr/local/openresty/lualib/resty/mysql.lua

注意文件的大小检查：

1	-rw-r--r-- 1 root bin 34779 Mar 3 07:47 mysql.lua

4.3.2 配置连接`mysql`或`Tidb`的连接信息

更新conf/orange.conf配置文件中mysql的相关配置：

1	root@deeplearning:/usr/local/orange/conf # vi orange.conf

主要有配置：

"store": "mysql",
"store_mysql": {
    "timeout": 5000,
    "connect_config": {
        "host": "192.169.8.8",
        "port": 4001,
        "database": "orange",
        "user": "orange",
        "password": "orange",
        "max_packet_size": 1048576,
        "charset": "utf8mb4"
    },
    "pool_config": {
        "max_idle_timeout": 10000,
        "pool_size": 3
    },
    "desc": "mysql configuration"
},

特别注意的参数是：

字符集，"charset": "utf8mb4"为新增字符集参数，适配tidb使用；

4.3.3 数据库初始化

数据库的初始化sql文件如下，提前通过mysql客户端多数据库进行初始化：

1 2	root@deeplearning:/approot1/orangesoft/orange-0.6.4/install # ll orange-v0.6.4.sql -rw-rw-r-- 1 root root 10406 May 16 2017 orange-v0.6.4.sql

数据库初始化：

# CREATE DATABASE orange;
# CREATE USER 'orange'@'%' IDENTIFIED BY 'orange';
# GRANT ALL PRIVILEGES ON orange.* TO 'orange'@'%';
# FLUSH PRIVILEGES; 
然后初始化表：
# mysql -uorange -porange  orange < orange-v0.6.4.sql

4.3.4 配置用户认证

"dashboard": {
        "auth": true,
        "session_secret": "y0ji4pdj61aaf3f11c2e65cd2263d3e7e5",
        "whitelist": [
            "^/auth/login$",
            "^/error/$"
        ]
    },

其中参数"auth": true为开启权限认证。默认用户名密钥如下，初次登陆可以修改，并新增用户。

1 2	用户名： admin 密钥： orange_admin

4.4 启动orange

安装完成后，orange执行文件在/usr/local/bin/orange，所用使用下面的命令：

root@deeplearning:/usr/local/orange/conf # orange help
Orange v0.6.4, OpenResty/Nginx API Gateway.

Usage: orange COMMAND [OPTIONS]

The commands are:
 
stop	Stop current Orange
help	Show help tips
restart	Restart Orange
version	Show the version of Orange
reload	Reload the config of Orange
start	Start the Orange Gateway
store	Init/Update/Backup Orange store

使用下面命令启动：

1	root@deeplearning:/usr/local/orange/conf # orange start

4.5 验证

启动后orange的前端监听端口在9999，浏览器使用下面的地址验证界面：

1	http://192.168.31.3:9999

第二部分高版本安装

前面的编译安装主要针对低版本的0.6.4，对于高版本的0.7.1版本，由于引入了较多的第三方插件，所以在安装orange前需要补充安装一些依赖包。

openresty自带包管理工具opm，新版本建议使用新的包管理工具luarocks。

2.1 安装`luarocks`

首先配置，安装在/usr/local/luarocks。

root@deeplearning:/approot1/orange/soft/luarocks-3.0.3 # ./configure --with-lua=/usr/local/openresty/luajit --prefix=/usr/local/luarocks

Configuring LuaRocks version 3.0.3...

Lua version detected: 5.1
Lua interpreter found: /usr/local/openresty/luajit/bin/luajit
lua.h found: /usr/local/openresty/luajit/include/luajit-2.1/lua.h
unzip found in PATH: /usr/bin

Done configuring.

LuaRocks will be installed at......: /usr/local/luarocks
LuaRocks will install rocks at.....: /usr/local/luarocks
LuaRocks configuration directory...: /usr/local/luarocks/etc/luarocks
Using Lua from.....................: /usr/local/openresty/luajit

* Type make and make install:
  to install to /usr/local/luarocks as usual.
* Type make bootstrap:
  to install LuaRocks into /usr/local/luarocks as a rock.

然后安装：

1	root@deeplearning:/approot1/orange/soft/luarocks-3.0.3 # make && make install

2.2 依赖包安装

orange高版本引入多个第三方包，这些包依赖如下，需要在线环境进行安装。

root@deeplearning:/usr/local/orange/logs # luarocks install luafilesystem
# ...
root@deeplearning:/usr/local/orange/logs # luarocks list
Rocks installed for Lua 5.1
---------------------------
binaryheap
   0.4-1 (installed) - /usr/local/luarocks/lib/luarocks/rocks-5.1
lrandom
   20180729-1 (installed) - /usr/local/luarocks/lib/luarocks/rocks-5.1
lua-resty-dns-client
   1.0.0-1 (installed) - /usr/local/luarocks/lib/luarocks/rocks-5.1
lua-resty-http
   0.13-0 (installed) - /usr/local/luarocks/lib/luarocks/rocks-5.1
lua-resty-jwt
   0.2.0-0 (installed) - /usr/local/luarocks/lib/luarocks/rocks-5.1
lua-resty-timer
   1.1.0-1 (installed) - /usr/local/luarocks/lib/luarocks/rocks-5.1
luafilesystem
   1.8.0-1 (installed) - /usr/local/luarocks/lib/luarocks/rocks-5.1
luasocket
   3.0rc1-2 (installed) - /usr/local/luarocks/lib/luarocks/rocks-5.1
penlight
   1.5.4-1 (installed) - /usr/local/luarocks/lib/luarocks/rocks-5.1

2.3 依赖配置

依赖包安装的路径需要添加到rerquire搜索路径中。更新conf/nginx.conf配置文件中下面两个参数：

1
2
3

#----------------------------Orange configuration----------------------------
lua_package_cpath '/usr/local/luarocks/lib/lua/5.1/?.so;/usr/local/luarocks/lib/lua/5.1/socket/?.so;/usr/local/luarocks/lib/lua/5.1/mime/?.so;;';
lua_package_path './lualib/?.lua;./lualib/resty/?.lua;/usr/local/orange/?.lua;/usr/local/lor/?.lua;/usr/local/luarocks/share/lua/5.1/?.lua;/usr/local/luarocks/share/lua/5.1/resty/?.lua;;';

完成以上依赖配置后，参考低版本部署orange即可。

orange_install

2.4 注意事项

2.4.1 高版本`sql`文件缺失

在部署高版本0.7.1时候，数据库表初始化sql文件orange-v0.7.0.sql中缺失组件headers表的初始化语句，可以在版本0.8.1中的初始化文件orange-v0.8.1.sql中获取。

说明项目的版本管理较为混乱。

2.4.2 `lua-resty-mysql`版本问题

orange项目和mysql或者tidb交互使用的是依赖包lua-resty-mysql。版本差异有：

0.6.4版本使用0.19版本
0.7.1版本使用0.23版本

经过测试目前0.23版本兼容tidb，而低版本0.19版本不兼容。所以在部署低版本orange的时候注意替换和安装新版lua-resty-mysql包。

依赖包的位置，可以直接替换文件生效。

1	/usr/local/openresty/lualib/resty/mysql.lua

第三部分 `docker`安装

另外orange项目组也制作了docker镜像，项目地址为：syhily/orange。需要注意的是该镜像中orange版本为0.6.4版本，详细可以参考项目的Dockerfile文件。

2.1 部署`mysql`容器

1	# docker run --name orange-database -e MYSQL_ROOT_PASSWORD=root -e MYSQL_DATABASE=orange -p 3306:3306 mysql:5.7

2.2 部署`orange`集群

启动主节点：

# docker run -d --name orange \
    --link orange-database:orange-database \
    -p 7777:7777 \
    -p 8888:8888 \
    -p 9999:9999 \
    --security-opt seccomp:unconfined \
    -e ORANGE_DATABASE=orange \
    -e ORANGE_HOST=orange-database \
    -e ORANGE_PORT=3306 \
    -e ORANGE_USER=root \
    -e ORANGE_PWD=root \
    syhily/orange

启动从节点：

# docker run -d --name orange \
    -p 7777:7777 \
    -p 8888:8888 \
    -p 9999:9999 \
    --security-opt seccomp:unconfined \
    -e ORANGE_DATABASE=orange \
    -e ORANGE_HOST=192.168.31.3 \
    -e ORANGE_PORT=4000 \
    -e ORANGE_USER=root \
    syhily/orange

注意：官网的镜像配置中映射的api端口为8888，但是启动配置是80，这是错误配置。本文在这里进行了纠正。

第四部分总结

5.1 非编译安装

前面的过程都是编译安装的，特别是组件openresty编译过程比较漫长。如果测试环境已经编译完成，只需要将部署目录整体拷贝至生产环境后即可（注意环境变量），不再赘述。

5.2 集群部署

orange网关启动后将所有配置信息加载在内存中，mysql或者Tidb数据库只是作为配置的持久化保存。所有可以启动多个orange网关共用一套数据库，架构上组成集群模式。维护中需要注意的是：

同步配置

在集群部署模式下，一台网关应用服务器调整配置，需要及时手动同步配置到数据库持久化，另外其他网关节点需要手动同步将数据库中最新配置加载至网关内存。
研发配置自动同步组件

集群中每个节点登记注册加入，其中一台节点更新了配置，自动将登记的节点集合中所有配置自动刷新。
数据库故障

网关集群中，数据库只是配置的持久化。若短时间数据库故障不可访问，并不影响网关的对外服务。

5.3 动态调整

低版本orange项目还不支持动态upstream配置功能。需要通过在nginx配置文件中新增。新增完成后需要使用下面的命令动态加载：

1	# orange reload

高版本中有Dynamic Upstream组件实现动态upstream配置功能。

5.4 域名问题

在实际生产线上环境，orange背后的持久化数据库对外地址通常是高可用的域名模式，另外网关代理的API地址通常也是内部域名。操作系统配置的DNS并不会被nginx读取，本地hosts是有效的。

这时候就需要将内部DNS地址配置在conf/nginx.conf文件中，例如：

1	resolver 192.168.12.1 192.168.12.2 ipv6=off;

上面两个DNS地址以轮询方式请求，解析间隔默认是3600秒。

写在最后

期望orange项目组未来能投入更多的精力继续演进项目。尽快发布新版本，丰富文档，答复issue。否则项目有荒凉的风险呀。

参考文献及资料

[1] OpenResty官网，链接：http://openresty.org/cn/download.html

[2] orange 使用文档，链接：http://orange.sumory.com/docs/guides/usages/

[3] orange官网，链接：http://orange.sumory.com/

目录

背景

第一部分 编译安装