APISIX 工作原理
APISIX 将配置加载到工作进程的内存中,在 OpenResty 内匹配路由、运行插件,并在代理请求时选择上游。本文介绍这些组件如何协作、请求如何经过 NGINX 各阶段,以及配置如何在不重启进程的情况下更新。
文末的相关资源可帮助你进一步了解各主题。
概览
APISIX 是一个运行在 OpenResty 中的 Lua 应用。OpenResty 通过 lua-nginx-module 扩展 NGINX。NGINX 负责连接处理、工作进程模型和请求阶段机制;APISIX 通过挂载到各个阶段的 Lua 程序完成路由、插件执行和上游选择。
本页从请求流角度说明 APISIX。所有由 APISIX 处理的请求都会经过三个运行时组件:
- 提供路由和插件定义的配置存储。
- 将请求匹配到路由的路由器。
- 在对应 NGINX 阶段 运行匹配路由插件的插件引擎。
以下各节先介绍这些组件,再跟踪一个请求如何依次经过它们。负载均衡、服务发现和 Admin API 等其他组件会在请求流中的相关位置提及,并在各自页面中详细介绍。
下图展示默认传统部署模式中的请求流和配置流,其中 etcd 是配置来源。路由器、插件引擎、负载均衡器和内存配置均位于 APISIX 工作进程内:
基于文件的独立部署模式沿用相同的请求处理流程,配置来自磁盘上的 apisix.yaml 或 apisix.json。每个工作进程都会轮询该文件,并在内容变化时重新加载配置:
配置存储
在默认部署模式中,APISIX 使用 etcd 作为路由、上游、服务、消费者、SSL 证书、插件配置和全局规则的事实来源。每个 NGINX 工作进程通过长轮询订阅 etcd,并在内存中保存一份配置副本。
通过 Admin API 创建或更新资源时,更改会写入 etcd。工作进程通过 watch 机制观察更改,并独立重建内存中的路由结构,不需要重新加载、重启或跨工作进程协调。配置更改会应用到运行中的工作进程,不会中断现有连接。
APISIX 支持以下配置分发路径:
- 使用 etcd 的模式:传统模式和分离式部署的数据面均以 etcd 为配置的事实来源,每个工作进程都会监听 etcd。上图展示的是传统模式。
- 基于文件的独立部署模式:每个工作进程轮询
apisix.yaml或apisix.json,并将变更加载到内存中;无需 etcd。参见基于文件的独立部署模式配置。 - 面向 APISIX Ingress Controller 的基于 API 的独立部署模式:Controller 通过不依赖 etcd 的独立部署 Admin API 发送完整配置快照。它解析网关端点,并向每个 APISIX 实例发送快照;工作进程之间的协调仅在接收快照的实例内部进行。此模式专用于 Ingress Controller 集成,并非通用的运维人员管理配置流程。参见设置 Ingress Controller 和网关及基于 API 的独立部署模式使用说明。
本页其余部分介绍的请求处理行为在所有模式中相同,区别仅在于配置来源。有关支持的完整模式列表和配置方式,请参阅部署模式。
路由器
路由器将传入请求匹配到路由。APISIX 使用 Radix Tree(压缩前缀树)作为匹配引擎。
配置路由时,路由会被插入树中。处理请求时,URI 的匹配时间与 URI 长度相关,而不是与已配置的路由数量相关。因此,即使路由数量增加,匹配开销也大致保持不变。
APISIX 内置三种 HTTP 路由器,它们使用不同的字段作为树的主索引:
radixtree_host_uri(默认):使用host + uri作为主索引,同时匹配请求 Host 和 URI。radixtree_uri:仅使用uri作为主索引,Host 不属于索引。radixtree_uri_with_parameter:与radixtree_uri相同,同时支持/user/:id之类的路径参数。
当前使用的 HTTP 路由器通过 config.yaml 中的 apisix.router.http 配置选择。TLS 握手期间的 SSL 证书选择使用独立的 radixtree_sni 路由器,将客户端 SNI 与已配置的证书匹配。有关 HTTP 路由器的配置和功能对比,请参阅路由选项。
插件引擎
路由器确定匹配路由后,插件引擎会从以下来源组合本地绑定的插件配置:
- 匹配的路由。
- 路由引用的插件配置(如果有)。
- 路由关联的服务(如果有)。
- 匹配的消费者和消费者组(如果有)。
对于非身份认证插件,如果同一个插件出现在多个本地来源中,APISIX 采用优先级最高的配置:
Consumer > Consumer Group > Route > Plugin Config > Service
身份认证插件遵循不同的执行流程。APISIX 在确定消费者身份之前,先运行消费者之外的本地身份认证配置;随后合并消费者和消费者组的插件,但不会重新运行合并进来的身份认证插件。
全局规则中的插件不属于上述优先级链,而是在单独的全局范围运行。对于 HTTP 的 rewrite 和 access 阶段,执行顺序依次为全局 rewrite、本地 rewrite、全局 access、本地 access。在后续共同阶段中,全局范围也先于本地范围运行。
在同一个阶段及全局或本地范围内,引擎按插件的 priority 排序,值越大越先执行。优先级不能让插件跨越阶段或范围边界。插件可以修改请求或响应,也可以提前终止请求。例如,身份认证插件可以在请求到达上游前返回 401。
插件会定义一个或多个阶段函数。对于 HTTP 流量,引擎会驱动 rewrite、access、before_proxy、header_filter、body_filter 和 log 阶段。
大多数插件以 Lua 模块形式提供。APISIX 还支持通过外部插件运行器执行 Go、Java 和 Python 插件,并通过 WASM 运行器支持 WebAssembly 模块。有关阶段模型,以及如何组合路由、服务和消费者上的插件配置,请参阅插件。
请求生命周期
下表按照 NGINX 阶段展示 APISIX 如何处理单个 HTTP 请求:
| 阶段 | APISIX 会做什么 |
|---|---|
ssl_client_hello / ssl_certificate | 使用客户端的 SNI 值,从 radixtree_sni 路由器中选择证书。 |
access | 使用 HTTP 路由器匹配请求,再将引用的 Plugin Config 和 Service 合并到本地路由配置中。按执行顺序运行全局及本地的 rewrite 和 access 插件组。认证后,消费者和消费者组的插件可以加入本地配置。插件可以在此提前终止请求。随后解析上游,选择初始节点,并运行 before_proxy 插件。 |
balancer | 使用 access 阶段选定的上游节点。对于符合条件的重试,按配置的负载均衡算法和健康检查状态重新选择上游节点。 |
header_filter | 在 NGINX 组装响应头时运行响应头处理插件。 |
body_filter | 在响应体以流式方式返回客户端时运行响应体处理插件。 |
log | 响应发送完成后运行日志插件。大多数日志插件使用 NGINX 定时器,因此客户端无需等待日志写入完成。 |
下图展示 APISIX 对单个 HTTP 请求执行路由、插件阶段、上游选择和代理的顺序:
Stream(四层)流量遵循类似但更精简的生命周期:
| 阶段 | APISIX 会做什么 |
|---|---|
preread | 使用流路由器匹配连接,并运行路由的 preread 插件。插件可以在此阶段关闭连接。随后解析上游、选择初始节点,再运行 before_proxy。 |
balancer | 应用在 preread 阶段选择的上游节点。对于符合条件的重试,依据配置的负载均衡算法和健康检查状态重新选择上游节点。 |
log | 连接关闭后运行日志插件。 |
热配置更新
每个工作进程都在内存中保存一份配置。所有模式均可在不重新加载 NGINX 或重启工作进程的情况下应用变更,但分发方式不同:
- 使用 etcd 的模式:控制面将变更写入 etcd,每个数据面工作进程通过自己的 etcd watch 独立接收变更。
- 基于文件的独立部署模式:每个工作进程轮询本地
apisix.yaml或apisix.json,并加载完整更新。 - 面向 APISIX Ingress Controller 的基于 API 的独立部署模式:接收快照的实例将 Controller 的快照存入共享内存,通过工作进程事件及备用轮询协调本地工作进程。独立部署 API 可选择在限定时间内等待本地工作进程应用配置;跨 APISIX 实例的发布仍由 Controller 负责。
额外资源
- 核心概念:路由、上游、插件、Stream Route
- 参考:路由选项