源码深度学习 · 零基础友好

Apache APISIX 源码学习

20 天 · 每天 30 分钟 · 逐层读懂 Apache APISIX——一个用 Lua + OpenResty（Nginx + LuaJIT）写的高性能云原生 API 网关。它以 etcd 存配置、全动态热更新著称：加路由/改插件不用 reload。这是继 higress-group 之后的另一条网关技术路线——和 Envoy/Higress 形成鲜明对照。

00

开篇 · 这是个什么项目

Apache APISIX（README.md：Apache APISIX API Gateway ｜ AI Gateway）是 Apache 顶级项目，一个动态、实时、高性能的云原生 API 网关。它基于 OpenResty（Nginx + LuaJIT），用 etcd 做配置中心，支持热插拔的 Lua 插件（仓库自带 104 个插件）。

🎯 一句话：APISIX = OpenResty（Nginx 的 Lua 编程能力） + etcd（配置中心 + watch 热更新） + radixtree 路由 + 插件系统（按 priority 在 Nginx 各阶段运行）。改配置写进 etcd，所有网关节点 watch 到秒级生效、无需 reload。

⚡

OpenResty 内核

Nginx + LuaJIT，用 Lua 在 Nginx 各阶段编程。

🔄

全动态热更新

etcd watch，加路由/改插件不用 reload。

🧩

104 个插件

鉴权/限流/可观测/AI，按 priority 编排。

🎯

radixtree 路由

高性能前缀树路由匹配。

和 higress-group 的对照：Envoy/Higress 是 C++ 数据面 + 控制面下发 xDS 的路线；APISIX 是 OpenResty 单体 + etcd 配置 的路线——两种主流网关架构。学完能横向对比"C++/xDS"和"Lua/etcd"两条技术路径的取舍。源码在 apisix/（Lua），核心是 init.lua（请求生命周期）+ plugin.lua（插件）+ router.lua（路由）+ core/（基础设施）。
01

架构全景（动起来看）

下图那颗发光小球是"一个请求进 APISIX → 匹配路由 → 跑插件 → 转发上游"的旅程。从上到下：请求 → Nginx 阶段 → APISIX 核心 → 上游。

L1 · 请求进入（OpenResty/Nginx）
HTTP 请求ngx access 阶段
ssl_phase动态证书
api_ctx请求上下文
L2 · APISIX 核心（Lua）
routerradixtree 匹配
consumer鉴权识别
plugin.filter选插件
L3 · 插件与配置
run_plugin各阶段执行
etcd配置 watch
schema校验
L4 · 上游（Upstream）
balancer负载均衡
health check健康检查
discovery服务发现

心智模型是"请求进 → 匹配路由 → 选插件 → 各阶段跑插件 → 负载均衡转发上游"：

请求进入access 阶段→ router匹配路由→ plugin各阶段执行→ balancer转发上游
APISIX 为什么快 + 动态？ "快"来自 OpenResty——Nginx 的 C 级性能 + LuaJIT 的即时编译；"动态"来自 etcd——配置存 etcd，每个网关节点 watch 变化，加路由/改插件写进 etcd 后秒级生效、无需 nginx -s reload。这和传统 Nginx"改配置要 reload"是本质区别。
02

怎么用这份教程

⏱️

每天 30 分钟

一天一个独立页面，跟着"今日小结 + 动手"收尾。

👶

零基础友好

不假设你懂 Lua/OpenResty/Nginx 阶段，术语首次出现都有大白话解释。

📍

精确到行号

关键代码标 文件:行号，可在真源码里跳转对照。

一条主线：从"APISIX 是什么、Nginx 阶段与请求生命周期",到"路由/配置/上游怎么组织",到"插件系统怎么运行",最后是"服务发现/Admin/stream/SSL 等子系统 + 部署收官"。不需要先学 higress-group，但学过的话能做精彩的横向对比。
W1

第 1 周 · 全景与请求生命周期

全景、Nginx 阶段、启动、请求旅程、api_ctx
01

项目全景（Lua 网关）

APISIX 是什么、OpenResty/etcd、和 Envoy/Higress 对照。

≈30 min开始学 →
02

OpenResty 与 Nginx 阶段

init/init_worker/access/header_filter/body_filter/log/balancer。

≈30 min开始学 →
03

启动流程

bin/apisix CLI → nginx.conf 生成 → http_init/http_init_worker。

≈30 min开始学 →
04

请求生命周期总览

http_access_phase 逐段：ctx→路由→consumer→plugin→upstream。

≈30 min开始学 →
05

core.ctx 与 api_ctx

请求上下文、ngx.ctx、变量惰性求值。

≈30 min开始学 →
W2

第 2 周 · 路由/配置/数据面

router、etcd 配置、抽象对象、schema、upstream/balancer
06

路由 router

radixtree、router_http/router_ssl、匹配流程。

≈30 min开始学 →
07

配置中心 etcd

config_etcd watch 增量同步 vs config_yaml standalone。

≈30 min开始学 →
08

六大抽象对象

Route/Service/Upstream/Consumer/Plugin_config/Global_rule。

≈30 min开始学 →
09

schema 校验

schema_def、core.schema、jsonschema。

≈30 min开始学 →
10

upstream 与 balancer

负载均衡 roundrobin/chash/least_conn、健康检查。

≈30 min开始学 →
W3

第 3 周 · 插件系统

插件机制、运行、配置合并、鉴权、典型插件
11

插件机制全景

plugin.load、priority、phase、filter 选插件。

≈30 min开始学 →
12

插件运行

run_plugin 各阶段、global_rules 全局插件。

≈30 min开始学 →
13

插件配置合并

merge_service_route/merge_consumer_route。

≈30 min开始学 →
14

鉴权与 consumer

key-auth/jwt-auth、consumer 识别与匹配。

≈30 min开始学 →
15

典型插件精读

limit-count 限流 / proxy-rewrite / ai-proxy。

≈30 min开始学 →
W4

第 4 周 · 高级子系统与运维

服务发现、Admin/control、stream、SSL/secret/wasm、收官
16

服务发现 discovery

nacos/consul/dns/eureka/kubernetes。

≈30 min开始学 →
17

Admin API 与 control API

admin/ 增删改配置、control 健康检查接口。

≈30 min开始学 →
18

stream 子系统

L4 TCP/UDP 代理、stream_preread_phase。

≈30 min开始学 →
19

SSL/secret/wasm/pubsub

动态证书、密钥管理、Wasm 插件、发布订阅。

≈30 min开始学 →
20

部署与收官串讲

bin/apisix、config.yaml + 三种网关大对比。

≈30 min开始学 →

✅ 全部 20 天已就绪。零基础也能跟——每个 Lua/Nginx 概念都有大白话铺垫。