1. 项目概述为什么选择 Apache APISIX如果你正在寻找一个高性能、云原生、可扩展的 API 网关那么 Apache APISIX 大概率已经进入了你的视野。我最初接触它是因为团队需要一个能同时处理南北向和东西向流量、并且能无缝集成到现有 Kubernetes 环境中的网关方案。在对比了市面上几个主流选项后APISIX 以其极致的性能、活跃的社区和声明式的配置管理方式最终胜出。简单来说APISIX 就像一个功能超级强大的智能交通枢纽所有进出你微服务集群的 API 请求都经过它由它来负责路由、认证、限流、监控、安全防护等一系列工作让后端的服务可以更专注于业务逻辑。从技术栈上看APISIX 基于 Nginx 和 OpenResty用 Lua 编写插件这赋予了它极高的性能上限和灵活性。但更重要的是它通过 etcd 作为配置中心实现了动态、实时的配置更新无需重启服务这对于追求零宕机的现代应用架构至关重要。无论是处理突发的高并发流量还是快速上线一个新的 API 版本APISIX 都能从容应对。接下来我将从一个实践者的角度带你从零开始完成 APISIX 的安装、核心功能配置并分享一些在生产环境中摸爬滚打总结出来的经验。2. 安装部署多种环境下的实战指南安装 APISIX 有多种方式你可以根据自身的技术栈和环境选择最合适的一种。这里我会详细介绍最常用的两种使用 Docker-Compose 快速拉起测试环境以及在 Kubernetes 中使用 Helm 进行生产级部署。无论哪种方式理解其背后的组件构成都是第一步。2.1 核心组件与架构理解在动手安装之前花几分钟理解 APISIX 的架构能让你在后续的配置和排错中事半功倍。一个标准的 APISIX 集群主要包含以下组件APISIX 节点这是数据面真正处理流量的进程。每个节点都是无状态的可以水平扩展。etcd这是控制面存储所有的路由、插件、上游等配置信息。APISIX 节点会监听 etcd 的变化并实时更新自己的路由规则。APISIX Dashboard一个可选但强烈建议使用的 Web 管理界面用于可视化配置和监控。它们之间的关系是你在 Dashboard 或通过 Admin API 创建的配置会被写入 etcdAPISIX 的各个节点从 etcd 同步这些配置并应用到运行时的流量处理中。这种架构实现了配置与服务的解耦。2.2 方案一使用 Docker-Compose 快速启动开发/测试首选对于想快速体验和开发测试的同学Docker-Compose 是最佳选择。它能在几分钟内帮你搭建一个包含 APISIX 和 etcd 的完整环境。首先你需要确保系统已经安装了 Docker 和 Docker-Compose。然后创建一个docker-compose.yml文件version: 3 services: apisix: image: apache/apisix:3.10.0-alpine restart: always ports: - 9080:9080 # HTTP 代理端口 - 9091:9091 # Admin API 端口 - 9443:9443 # HTTPS 代理端口 volumes: - ./apisix_log:/usr/local/apisix/logs - ./apisix_conf/config.yaml:/usr/local/apisix/conf/config.yaml:ro depends_on: - etcd networks: - apisix-net etcd: image: bitnami/etcd:3.5 restart: always environment: ETCD_ENABLE_V2: true ALLOW_NONE_AUTHENTICATION: yes ETCD_ADVERTISE_CLIENT_URLS: http://0.0.0.0:2379 ETCD_LISTEN_CLIENT_URLS: http://0.0.0.0:2379 volumes: - ./etcd_data:/bitnami/etcd networks: - apisix-net apisix-dashboard: image: apache/apisix-dashboard:3.0.1-alpine restart: always ports: - 9000:9000 environment: - APISIX_DASHBOARD_CONF/usr/local/apisix-dashboard/conf/conf.yaml volumes: - ./dashboard_conf/conf.yaml:/usr/local/apisix-dashboard/conf/conf.yaml:ro depends_on: - apisix networks: apisix-net networks: apisix-net: driver: bridge接下来需要配置 APISIX 以连接 etcd。在./apisix_conf目录下创建config.yamlapisix: node_listen: 9080 enable_admin: true admin_key: - name: admin key: edd1c9f034335f136f87ad84b625c8f1 # 务必修改此密钥 role: admin deployment: admin: allow_admin: # 允许访问 Admin API 的 IP 列表生产环境请严格限制 - 0.0.0.0/0 admin_key: - name: admin key: edd1c9f034335f136f87ad84b625c8f1 role: admin etcd: host: - http://etcd:2379 # 注意这里使用 Docker Compose 的服务名 prefix: /apisix timeout: 30同样配置 Dashboard 的./dashboard_conf/conf.yaml关键是指定 etcd 地址conf: listen: host: 0.0.0.0 port: 9000 etcd: endpoints: - http://etcd:2379 # 同样使用服务名 log: level: warn配置完成后在docker-compose.yml同级目录下执行docker-compose up -d三个服务就会启动。访问http://localhost:9000即可登录 Dashboard默认用户名/密码admin/admin而http://localhost:9080就是 APISIX 的代理入口。注意这个配置中的admin_key是默认的并且 Admin API 允许所有 IP 访问这仅适用于本地测试。在生产环境中你必须生成一个复杂的密钥并通过allow_admin字段严格限制可访问 Admin API 的 IP 地址范围这是安全底线。2.3 方案二使用 Helm 在 Kubernetes 中部署生产推荐对于生产环境Kubernetes 是更主流的平台。APISIX 官方提供了成熟的 Helm Chart让部署变得非常规范。首先添加 APISIX 的 Helm 仓库并更新helm repo add apisix https://charts.apiseven.com helm repo update在安装之前建议创建一个独立的values.yaml文件来覆盖默认配置以适应生产需求。以下是一个关键配置示例# values-prod.yaml gateway: type: LoadBalancer # 或 NodePort根据你的 K8s 环境决定 http: enabled: true servicePort: 80 containerPort: 9080 admin: enabled: true servicePort: 9180 containerPort: 9180 externalTrafficPolicy: Local # 保留客户端真实 IP admin: enabled: true credentials: admin: your-strong-admin-password-here # 修改为强密码 dashboard: enabled: true service: type: ClusterIP # 通常通过 Ingress 暴露而非直接 NodePort etcd: replicaCount: 3 # 生产环境至少3个节点确保高可用 auth: rbac: create: true # 启用 etcd 的 RBAC 认证更安全 plugins: - api-breaker - authz-keycloak - cors - limit-count - prometheus - proxy-rewrite - request-id - zipkin # 列出你需要的所有插件避免加载未使用的插件然后使用 Helm 进行安装kubectl create namespace apisix helm install apisix apisix/apisix -f values-prod.yaml --namespace apisix这个命令会在apisix命名空间中部署一个包含多个副本的 APISIX 网关、一个三节点的 etcd 集群以及 Dashboard。你可以通过kubectl get svc -n apisix查看网关对外的服务地址。实操心得在 K8s 中将 APISIX 的externalTrafficPolicy设置为Local至关重要。这能确保 APISIX 获取到客户端的真实源 IP而不是 K8s 节点 IP。否则所有限流、黑白名单等功能将基于错误的 IP 工作导致规则失效。这是我们早期踩过的一个大坑。3. 核心概念与基础配置实战安装完成后我们通过 Dashboard 或 Admin API 来配置第一个路由。理解 APISIX 的几个核心概念是灵活运用的关键路由、上游、服务和插件。3.1 创建第一个路由与上游假设我们有一个用户服务运行在http://user-service:8080在 K8s 中是 Service 名在 Docker 中是容器名或主机名。我们想将所有路径以/users开头的请求代理到这个服务。第一步创建上游上游就是一组后端服务实例的抽象。在 Dashboard 的“上游”页面点击创建名称user-service-upstream类型选择roundrobin轮询或chash一致性哈希等负载均衡算法。节点添加目标节点。对于服务发现可以直接填写服务域名和端口如user-service:8080权重设为 1。第二步创建路由路由是匹配规则和动作的绑定。在“路由”页面创建名称user-service-route路径/users/*。这表示匹配所有以/users/开头的请求。HTTP 方法可以留空匹配所有或选择GET, POST, PUT, DELETE。上游选择我们刚刚创建的user-service-upstream。点击提交这个配置会立刻生效。现在访问http://你的APISIX地址:9080/users/profile请求就会被转发到后端的用户服务。3.2 插件机制功能扩展的核心APISIX 的强大很大程度上源于其丰富的插件生态。插件可以无缝地附加到路由、服务或全局上。我们来配置两个最常用的插件限流和密钥认证。配置限流插件在刚才创建的user-service-route路由中点击“插件”搜索并启用limit-count。配置选择“局部配置”。参数count: 100time_window: 60key_type:varkey:remote_addr这是内置变量代表客户端IPrejected_code: 503解释这个配置意味着同一个客户端 IP 在 60 秒内最多只能访问该路由 100 次超出后返回 503 状态码。key也可以设置为consumer_name针对消费者限流或者server_addr针对服务端限流非常灵活。配置密钥认证插件假设我们想保护一个管理接口/admin/*只允许持有特定 API Key 的请求访问。首先创建一个消费者。在 Dashboard 的“消费者”页面创建一个名为admin-consumer的消费者。为这个消费者启用key-auth插件。在插件配置中你可以选择“自动生成密钥”也可以手动指定一个比如super-secret-key-2024。创建一个新的路由路径为/admin/*并启用key-auth插件。在插件配置中选择“局部配置”并将header参数设置为X-API-KEY这是客户端需要在请求头中传递密钥的字段名。最后将这个路由绑定到你的后端管理服务上游。现在任何对/admin/*的请求必须在请求头中携带X-API-KEY: super-secret-key-2024否则 APISIX 将直接返回 401 未授权错误。注意事项插件的执行顺序有时很重要。APISIX 的插件执行分为多个阶段rewrite,access,header_filter,body_filter,log。例如proxy-rewrite修改请求头插件通常需要在access阶段之前执行。在 Dashboard 上配置多个插件时你可以通过拖动来调整它们的顺序。如果通过 Admin API 配置则需要在plugins对象中按你期望的顺序列出插件。4. 高级特性与生产环境配置当基本的路由和插件满足需求后你会需要更高级的功能来应对复杂的生产场景。4.1 服务发现动态上游管理在生产中后端服务的实例可能随时扩缩容手动维护上游节点列表是不可行的。APISIX 支持多种服务发现集成。以 Kubernetes 为例你可以使用kubernetes服务发现。这需要你在 APISIX 的配置中启用相关插件并在创建上游时选择类型为“服务发现”然后填写 K8s 的 Service 名称和端口。APISIX 会自动从 Kubernetes API 拉取该 Service 对应的 EndpointsPod IP列表并动态更新上游节点。对于 Consul 或 NacosAPISIX 也有对应的插件。你需要先在config.yaml中配置服务发现的服务器地址然后在创建上游时指定服务名。这样当有新的服务实例注册到 Consul/Nacos 时APISIX 能近乎实时地感知并更新路由实现真正的无缝服务上下线。4.2 可观测性监控与链路追踪“可观测性”是生产系统的生命线。APISIX 提供了强大的监控数据出口。Prometheus 指标启用prometheus插件通常是全局启用。APISIX 会在/apisix/prometheus/metrics端点暴露丰富的指标包括请求总数、延迟分布P99 P95等、带宽、各种 HTTP 状态码计数等。你可以配置 Prometheus 来抓取这些数据并在 Grafana 中使用官方提供的仪表盘进行可视化。链路追踪在微服务架构中一个请求可能穿过多个服务排查问题需要完整的调用链。启用zipkin或jaeger插件。你需要在插件配置中指定追踪系统的 collector 端点如http://jaeger-collector:9411/api/v2/spans。APISIX 会自动为经过的请求生成和传播追踪上下文Trace ID, Span ID将网关这一环纳入整个调用链让你能清晰看到请求在网关的耗时和状态。4.3 安全加固Admin API 与 Dashboard 防护Admin API默认端口 9180和 Dashboard默认端口 9000是 APISIX 的控制入口必须重点防护。网络隔离绝对不要将它们直接暴露在公网。在 Kubernetes 中将它们的 Service 类型设置为ClusterIP并通过一个安全的 Ingress 网关甚至可以再用一层 APISIX来访问并配置严格的 IP 白名单和身份认证。强密码与密钥修改默认的admin_key和 Dashboard 密码。使用密码生成器创建长度超过 16 位包含大小写字母、数字和特殊字符的强密码。启用 HTTPS为 Admin API 和 Dashboard 配置 TLS 证书。对于 Dashboard你可以在其配置文件中指定证书路径。对于 Admin API可以在 APISIX 的config.yaml中配置admin_listen为 HTTPS 端口并绑定证书。审计日志确保 APISIX 的访问日志和错误日志被妥善收集如输出到 stdout 由 Fluentd 收集或写入文件由 Filebeat 采集并接入 ELK 或 Loki 等日志平台用于审计和异常行为分析。5. 常见问题与深度排错指南即使配置正确在实际运行中也可能遇到各种问题。这里记录了几个我们遇到过的高频问题及其排查思路。5.1 路由匹配失败404 Not Found这是最常见的问题。请求到了 APISIX但返回了 404。排查步骤 1检查路由路径。确认请求的 URL 是否完全匹配路由中配置的路径。注意/users和/users/在严格模式下是不同的。APISIX 支持精确匹配、前缀匹配、正则匹配等多种方式要确认你使用的匹配类型。排查步骤 2检查上游状态。在 Dashboard 中查看该路由绑定的上游确认其中的节点是否健康、地址和端口是否正确。可以尝试在 APISIX 容器内使用curl直接访问上游节点地址看服务是否正常响应。排查步骤 3查看 APISIX 日志。APISIX 的error.log会包含路由查找失败的详细信息。通过命令docker logs apisix-container-id或kubectl logs apisix-pod-name查看搜索关键字no matched route。排查步骤 4检查插件冲突。某些插件如redirect或proxy-rewrite可能会修改请求的 URI导致后续的路由匹配出现问题。检查该路由上启用的所有插件及其执行顺序。5.2 插件配置不生效配置了插件但预期的行为如限流、认证没有发生。排查步骤 1插件作用域。确认插件是绑定在正确的“作用域”上。插件可以绑定在路由、服务、消费者或全局。它们的优先级通常是路由 服务 消费者 全局。一个路由上的插件会覆盖服务上同名的插件配置。排查步骤 2插件配置格式。通过 Admin API 或 Dashboard 检查插件配置的 JSON 格式是否正确。特别是当使用复杂配置如limit-count的key为自定义变量时很容易出现语法错误。建议先在 Dashboard 上配置它提供了验证功能。排查步骤 3插件执行阶段。如前所述插件在不同阶段执行。如果proxy-rewrite插件在access阶段之后执行那么它修改的请求头可能对后续的access阶段插件如authz-keycloak无效。确保插件顺序符合逻辑。排查步骤 4查看插件特定日志。许多插件有自己的日志输出级别。你可以在config.yaml中调整日志级别为debug然后观察特定插件的日志输出这能提供最直接的线索。5.3 性能瓶颈排查在高并发下APISIX 出现延迟增高或吞吐下降。排查步骤 1监控指标分析。首先查看 Prometheus 指标关注apisix_bandwidth、apisix_latency、apisix_http_status。如果延迟的 P99 值飙升可能意味着某个上游服务响应变慢或者 APISIX 本身处理能力达到瓶颈。排查步骤 2资源利用率。使用top或kubectl top pod检查 APISIX 容器的 CPU 和内存使用率。APISIX 基于 Nginx是 CPU 密集型应用。如果 CPU 持续高于 70%考虑水平扩展 APISIX 实例。排查步骤 3检查 etcd 性能。APISIX 频繁从 etcd 拉取配置。如果 etcd 集群负载过高或网络延迟大会影响 APISIX 配置同步速度。监控 etcd 的磁盘 I/O、CPU 以及请求延迟。确保 etcd 部署在低延迟、高性能的存储上。排查步骤 4插件开销。复杂的插件特别是涉及外部网络调用的如authz-keycloak、openid-connect会显著增加请求延迟。使用 APISIX 的batch-requests插件将多个内部 API 调用合并或者考虑将认证信息缓存到 Redis 中可以极大缓解这个问题。5.4 配置同步延迟或失败在 Dashboard 上修改了配置但过了很久网关才生效或者根本不生效。排查步骤 1检查 etcd 连接。查看 APISIX 的error.log搜索etcd相关错误。确认config.yaml中的 etcd 地址和端口无误并且网络连通。在 APISIX 容器内执行curl http://etcd-host:2379/health检查 etcd 健康状态。排查步骤 2检查 APISIX 节点状态。在多节点 APISIX 集群中确认所有节点都在运行并且日志中没有持续的错误。有时某个节点可能因为内存不足等原因与 etcd 失联。排查步骤 3手动触发同步。APISIX 有热加载机制。你可以通过 Admin API 发送一个PUT /apisix/admin/plugins/reload请求需要 admin key 认证来强制重新加载所有插件和配置。这是一个有用的临时恢复手段。排查步骤 4Dashboard 与 etcd 的连接。如果 Dashboard 操作失败同样需要检查 Dashboard 配置文件中的 etcd 地址是否正确以及 Dashboard 容器到 etcd 的网络是否通畅。6. 进阶场景灰度发布与全链路压测掌握了基础和高阶功能后我们可以用 APISIX 玩出更多花样解决更复杂的业务需求。6.1 基于权重的灰度发布假设我们开发了用户服务的 V2 版本希望将 10% 的流量切到新版本进行灰度测试。在 APISIX 中这可以通过上游的节点权重轻松实现。创建上游user-service-gray-upstream。添加两个节点节点1user-service-v1:8080, 权重90节点2user-service-v2:8080, 权重10将原有的用户服务路由指向这个新的上游。这样APISIX 会按照 9:1 的比例将请求分发到 V1 和 V2 版本。你可以通过监控两个版本的错误率、延迟等指标逐步调整权重直至 V2 版本接收 100% 的流量。整个过程无需重启任何服务实现了平滑迁移。6.2 基于请求头的金丝雀发布更精细的灰度策略可以基于用户属性。例如我们只想让内部测试用户或特定地区的用户访问新版本。这需要结合使用traffic-split插件和vars变量匹配。你可以创建两条路由路由 A匹配路径/users/*且请求头包含X-User-Type: internal-tester。该路由指向 V2 版本的上游。路由 B匹配路径/users/*不设置特殊请求头条件。该路由指向默认的 V1 版本上游。由于 APISIX 的路由匹配优先级是从上到下或通过优先级字段设置路由 A 会优先被匹配。这样只有携带特定请求头的内部测试流量会走到 V2其他流量仍走 V1。这种方式可以用于 A/B 测试、内部体验等场景。6.3 全链路压测的影子流量在进行全链路压测时我们希望压测流量不影响线上真实数据。一种常见做法是使用“影子表”或“影子库”。APISIX 可以配合proxy-mirror插件来实现请求的镜像复制。为压测创建一个独立的上游指向你的“影子环境”服务集群。在线上路由上启用proxy-mirror插件。配置插件将一定比例例如 100%的线上真实请求镜像复制一份发送到压测上游但忽略其响应。在压测环境中服务将请求写入影子库从而在不污染线上数据的前提下获得最真实的业务流量和压力模型。这个方案的妙处在于它对线上业务完全透明性能开销极小主要是网络带宽却能获得极其真实的压测效果。