Apache APISIX文档-快速入门指南-如何构建 Apache APISIX

作者: Apache APISIX

如何构建 Apache APISIX

步骤1:安装 Apache APISIX

你可以通过 RPM 仓库、Docker、Helm Chart、源码包、源码包(LTS 版本)等多种方式来安装 Apache APISIX。请在以下选项中选择其中一种执行。
通过 RPM 仓库安装(CentOS 7)

这种安装方式适用于 CentOS 7 操作系统。

如果尚未安装 OpenResty 的官方 RPM 仓库,请使用以下命令自动安装 OpenResty 和 Apache APISIX 的 RPM 仓库。

  
   sudo yum install -y https://repos.apiseven.com/packages/centos/apache-apisix-repo-1.0-1.noarch.rpm

如果已安装 OpenResty 的官方 RPM 仓库,请使用以下命令自动安装 Apache APISIX 的 RPM 仓库。

  
   sudo yum-config-manager --add-repo https://repos.apiseven.com/packages/centos/apache-apisix.repo

请运行以下命令安装 Apache APISIX。

  
    查看仓库中最新的 apisix 软件包的信息
   sudo yum info -y apisix


    显示仓库中现有的 apisix 软件包
   sudo yum --showduplicates list apisix


    安装最新的 apisix 软件包
   sudo yum install apisix


    安装指定版本(本例中为2.10.3版本)的 apisix 软件包
   sudo yum install apisix-2.10.3-0.el7

通过 RPM 包离线安装(CentOS 7)

下载 APISIX 离线 RPM 包到 ./apisix 文件夹

  
   sudo mkdir -p apisix
   sudo yum install -y https://repos.apiseven.com/packages/centos/apache-apisix-repo-1.0-1.noarch.rpm
   sudo yum clean all && yum makecache
   sudo yum install -y --downloadonly --downloaddir=./apisix apisix

拷贝 ./apisix 文件夹到目标主机,使用以下命令安装 Apache APISIX。

  
   sudo yum install ./apisix/*.rpm

通过 Docker 安装

详情请参考:使用 Docker 安装 Apache APISIX
通过 Helm Chart 安装

详情请参考:使用 Helm Chart 安装 Apache APISIX
通过源码包安装

注意:如果你想针对特定平台打包 Apache APISIX,请更新 https://github.com/api7/apisix-build-tools。 以下步骤仅用于设置 Apache APISIX 的开发环境。

  1. 安装依赖
       
        curl https://raw.githubusercontent.com/apache/apisix/master/utils/install-dependencies.sh -sL | bash -

  1. 创建一个名为 apisix-2.13.1 的目录。
       
        APISIX_VERSION='2.13.1'
        mkdir apisix-$

  1. 下载 Apache APISIX Release 源码包:
       
        wget https://downloads.apache.org/apisix/${APISIX_VERSION}/apache-apisix-${APISIX_VERSION}-src.tgz

您也可以通过 Apache APISIX 官网下载 Apache APISIX Release 源码包。 Apache APISIX 官网也提供了 Apache APISIX、APISIX Dashboard 和 APISIX Ingress Controller 的源码包,详情请参考 Apache APISIX 官网-下载页
4. 解压 Apache APISIX Release 源码包:

       
        tar zxvf apache-apisix-${APISIX_VERSION}-src.tgz -C apisix-${APISIX_VERSION}

  1. 安装运行时依赖的 Lua 库:
       
         切换到 apisix-$ 目录
        cd apisix-$
         安装依赖
        LUAROCKS_SERVER=https://luarocks.cn make deps
         安装 apisix 命令
        make install

注意 :使用 make deps 安装 lualdapPCREopenssl 等依赖包失败,错误信息如: Could not find header file for LDAP/PCRE/openssl,可使用本方法解决。
解决思路:luarocks 支持自定义编译时依赖目录(来自此链接),使用第三方工具安装缺失的依赖,并将其文件路径添加到 luarocks 的变量表中。这是一种通用的解决方法,适用于在各种常见操作系统(包括但不仅限于 Ubuntu、Centos、macOS)遇到的"缺失头文件式安装依赖包失败"问题。
这边暂给出 macOS 上的具体解决步骤,其他操作系统的解决方案类似:

  1. 使用 brew install openldap 命令将 openldap 安装到本地;
  2. 使用 brew --prefix openldap 命令找到本地安装目录;
  3. 将路径添加到项目配置文件中(选择两种方法中的一种即可):
            
             1. 方法一:通过 `luarocks config` 手动设置 `LDAP_DIR` 变量, 比如 `luarocks config variables.LDAP_DIR /opt/homebrew/cellar/openldap/2.6.1`;
             2. 方法二:当然你也可以选择直接更改 luarocks 的默认配置文件,执行 `cat ~/.luarocks/config-5.1.lua` 命令,然后在文件中添加 `openldap` 的安装目录;
             3. 参考配置文件示例如下:
              variables = {
              LDAP_DIR = "/opt/homebrew/cellar/openldap/2.6.1",
              LDAP_INCDIR = "/opt/homebrew/cellar/openldap/2.6.1/include",
              }

  `/opt/homebrew/cellar/openldap/` 是 `brew` 在 macOS(Apple Silicon) 上安装 `openldap` 的默认位置。 `/usr/local/opt/openldap/` 是 `brew` 在 macOS(Intel) 上安装 `openldap` 的默认位置。
  1. 如果您不再需要 Apache APISIX 运行时,您可以执行卸载,如:
  
     卸载 apisix 命令
    make uninstall
     卸载依赖
    make undeps

请注意,该操作将完整删除相关文件。
通过源码包安装 LTS 版本

目前 Apache APISIX 的 LTS 版本为 2.13.1,将"[通过源码包安装] %E9%80%9A%E8%BF%87%E6%BA%90%E7%A0%81%E5%8C%85%E5%AE%89%E8%A3%85

步骤2:安装 etcd

如果你只通过 RPM、Docker 或源代码安装了 Apache APISIX,而没有安装 etcd,则需要这一步。

你可以通过 Docker 或者二进制等方式安装 etcd。以下命令通过二进制方式在 Linux 上安装 etcd。

  
   ETCD_VERSION='3.4.13'
   wget https://github.com/etcd-io/etcd/releases/download/v${ETCD_VERSION}/etcd-v${ETCD_VERSION}-linux-amd64.tar.gz
   tar -xvf etcd-v$-linux-amd64.tar.gz && \
    cd etcd-v$-linux-amd64 && \
    sudo cp -a etcd etcdctl /usr/bin/
   nohup etcd >/tmp/etcd.log 2>&1 &

以下命令在 Mac 上安装 etcd:

  
   brew install etcd
    start etcd server
   brew services start etcd

步骤3:管理 Apache APISIX 服务

我们可以在 Apache APISIX 的目录下使用命令初始化依赖、启动服务和停止服务,也可以通过 apisix help 命令查看所有命令和对应的功能。
初始化依赖

运行以下命令初始化 NGINX 配置文件和 etcd。

  
    initialize NGINX config file and etcd
   apisix init

测试配置文件

运行以下命令测试配置文件。 APISIX 将根据 config.yaml 生成 nginx.conf,并检查 nginx.conf 的语法是否正确。

  
    generate `nginx.conf` from `config.yaml` and test it
   apisix test

启动 Apache APISIX

运行以下命令启动 Apache APISIX。

  
    start Apache APISIX server
   apisix start

停止运行 Apache APISIX

优雅停机 apisix quit 和强制停机 apisix stop 都可以停止运行 Apache APISIX。建议您优先选择优雅停机的方式停止 Apache APISIX,因为这种停止方式能够保证 Apache APISIX 完成了已经接受到的请求之后再停止;而强制停机则是立即停止 Apache APISIX,在这种情况下,Apache APISIX 接收到但未完成的请求会随着强制停机一并停止。

执行优雅停机的命令如下所示:

  
    stop Apache APISIX server gracefully
   apisix quit

执行强制停机的命令如下所示:

  
    stop Apache APISIX server immediately
   apisix stop

查看其他操作

运行 apisix help 命令,查看返回结果,获取其他操作的命令和描述。

  
    more actions find by `help`
   apisix help

步骤4:运行测试案例

  1. 安装 perl 的包管理器 cpanminus

详情请参考:安装包管理器 cpanmius

  1. 然后通过 cpanm 来安装 test-nginx 的依赖:
       
        sudo cpanm --notest Test::Nginx IPC::Run > build.log 2>&1 || (cat build.log && exit 1)

  1. 运行 git clone 命令,将最新的源码克隆到本地,请使用我们 fork 出来的版本:
       
        git clone https://github.com/openresty/test-nginx.git

  1. 有两种方法运行测试:
  • 追加当前目录到perl模块目录: export PERL5LIB=.:$PERL5LIB,然后运行 make test 命令。
  • 或指定 NGINX 二进制路径:TEST_NGINX_BINARY=/usr/local/bin/openresty prove -Itest-nginx/lib -r t
    说明
    部分测试需要依赖外部服务和修改系统配置。如果想要完整地构建测试环境,可以参考 ci/linux_openresty_common_runner.sh
    问题排查
    配置 NGINX 路径

出现 Error unknown directive "lua_package_path" in /API_ASPIX/apisix/t/servroot/conf/nginx.conf 报错的解决方法如下:

确保将 OpenResty 设置为默认的 NGINX,并按如下所示导出路径:

  • export PATH=/usr/local/openresty/nginx/sbin:$PATH
    • Linux 默认安装路径:
      • export PATH=/usr/local/openresty/nginx/sbin:$PATH
    • MacOS 通过 homebrew 默认安装路径:
      • export PATH=/usr/local/opt/openresty/nginx/sbin:$PATH
        运行单个测试用例

使用以下命令运行指定的测试用例:

  
   prove -Itest-nginx/lib -r t/plugin/openid-connect.t

关于测试用例的更多细节,参见 [测试框架]

步骤5:修改 Admin API key

您需要修改 Admin API 的 key,以保护 Apache APISIX。

请修改 conf/config.yaml 中的 apisix.admin_key 并重启服务,如下所示:

  
   apisix:
     ... ...
    admin_key
    -
    name: "admin"
    key: abcdefghabcdefgh  将原有的 key 修改为abcdefghabcdefgh
    role: admin

当我们需要访问 Admin API 时,就可以使用上面记录的 key 了,如下所示:

  
   curl http://127.0.0.1:9080/apisix/admin/routes?api_key=abcdefghabcdefgh -i

返回结果中的状态码 200 说明访问成功,如下所示:

  
   HTTP/1.1 200 OK
   Date: Fri, 28 Feb 2020 07:48:04 GMT
   Content-Type: text/plain
   ... ...
   {"node":{...},"action":"get"}

在这个时候,如果您输入的 key 与 conf/config.yaml  apisix.admin_key 的值不匹配,例如,我们已知正确的 key 是 abcdefghabcdefgh,但是我们选择输入一个错误的 key,例如 wrong-key,如下所示:

  
   curl http://127.0.0.1:9080/apisix/admin/routes?api_key=wrong-key -i

返回结果中的状态码 401 说明访问失败,原因是输入的 key 有误,未通过认证,触发 Unauthorized 错误,如下所示:

  
   HTTP/1.1 401 Unauthorized
   Date: Fri, 28 Feb 2020 08:17:58 GMT
   Content-Type: text/html
   ... ...
   {"node":{...},"action":"get"}

步骤6:为 Apache APISIX 构建 OpenResty

有些功能需要引入额外的 NGINX 模块到 OpenResty 当中。 如果您需要这些功能,您可以构建 APISIX OpenResty。 您可以根据 api7/apisix-build-tools 里面的代码,配置自己的构建环境,并完成 APISIX OpenResty 的构建。

步骤7:为 Apache APISIX 添加 systemd 配置文件

如果您使用的操作系统是 CentOS 7,且在步骤 2 中通过 RPM 包安装 Apache APISIX,配置文件已经自动安装到位,你可以直接运行以下命令:

  
   systemctl start apisix
   systemctl stop apisix

如果通过其他方法安装,可以参考 配置文件模板 进行修改,并将其放置在 /usr/lib/systemd/system/apisix.service 路径下。

文章列表

更多推荐

更多
  • Pulsar消息队列-一套高可用实时消息系统实现 实时消息【即时通信】系统,有群聊和单聊两种方式,其形态异于消息队列:1 大量的 group 信息变动,群聊形式的即时通信系统在正常服务形态下,瞬时可能有大量用户登入登出。2 ...
  • Pulsar消息队列-Pulsar对比Kafka笔记 很多人查看 Pulsar 之前可能对 Kafka 很熟悉,参照上图可见二者内部结构的区别,Pulsar 和 Kafka 都是以 Topic 描述一个基本的数据集合,Topic 数据又分为若干 Partition,即对数据进行逻辑上的 ...
  • Pulsar消息队列-对 2017 年一套 IM 系统的反思 信系统的开发,前前后后参与或者主导了六七个 IM 系统的研发。上一次开发的 IM 系统的时间点还是 2018 年,关于该系统的详细描述见 [一套高可用实时消息系统实现][1] ...
  • Apache APISIX文档-快速入门指南-如何构建 Apache APISIX 如何构建 Apache APISIX,步骤1:安装 Apache APISIX,步骤2:安装 etcd,步骤3:管理 Apache APISIX 服务,步骤4:运行测试案例,步骤5:修改 Admin API key,步骤6:为 Apac
  • Apache APISIX文档-快速入门指南-快速入门指南 快速入门指南,概述,前提条件,第一步:安装 Apache APISIX,第二步:创建路由,第三步:验证,进阶操作,工作原理,创建上游服务Upstream,绑定路由与上游服务,添加身份验证,为路由添加前缀,APISIX Dashboard
  • Apache APISIX文档-架构设计-APISIX APISIX,软件架构,插件加载流程,插件内部结构,配置 APISIX,插件加载流程,比如指定 APISIX 默认监听端口为 8000,并且设置 etcd 地址为 http://foo:2379, 其他配置保持默认。在 ...
  • Apache APISIX文档-架构设计-Service Service 是某类 API 的抽象(也可以理解为一组 Route 的抽象)。它通常与上游服务抽象是一一对应的,Route 与 Service 之间,通常是 N:1 的关系,参看下图。不同 Route 规则同时绑定到一个 Service ...
  • Apache APISIX文档-架构设计-Plugin Config 如果你想要复用一组通用的插件配置,你可以把它们提取成一个 Plugin config,并绑定到对应的路由上。举个例子,你可以这么做:创建 Plugin config,如果这个路由已经配置了 plugins,那么 Plugin config ...
  • Apache APISIX文档-架构设计-Debug Mode 注意:在 APISIX 2.10 之前,开启基本调试模式曾经是设置 conf/config.yaml 中的 apisix.enable_debug 为 true。设置 conf/debug.yaml 中的选项,开启高级调试模式。由于 ...
  • Apache APISIX文档-架构设计-Consumer 如上图所示,作为 API 网关,需要知道 API Consumer(消费方)具体是谁,这样就可以对不同 API Consumer 配置不同规则。授权认证:比如有 [key-auth] 等。获取 consumer_...
  • 近期文章

    更多
    文章目录

      推荐作者

      更多