1. 从零到一为什么我们需要一个现代的API网关如果你正在构建微服务、管理多个后端应用或者厌倦了在Nginx配置文件里反复折腾location和upstream那么你很可能已经听过API网关这个词。但今天我们不谈那些老生常谈的概念我想从一个更实际的场景说起去年我接手了一个遗留系统它由十几个用不同语言写的服务组成对外暴露的接口散落在各处。每次有新需求比如要统一加个认证、限流或者把请求转发到新的服务地址我们都要去改好几个地方的Nginx配置然后心惊胆战地nginx -s reload。更头疼的是没有一个集中的地方能看清所有流量的来龙去脉出了问题只能靠猜和查日志。这就是我决定引入APISIX的起点。APISIX不是一个简单的反向代理它是一个动态、实时、高性能的API网关。和传统的Nginx最大区别在于它的所有路由、插件配置都是通过API动态管理的无需重启服务。这意味着你可以在毫秒级别内上线一个新的API路由或者给一批接口全局开启限流而服务本身毫无感知。对于追求快速迭代和稳定性的团队来说这种能力是革命性的。基于热词中提到的“静态路由配置实验”、“默认路由怎么配置”我能感觉到很多朋友可能还停留在手动配置路由的阶段。APISIX要解决的正是这种配置僵化、变更成本高的问题。它把路由规则、上游服务、认证、安全、可观测性等能力都抽象成了可通过API操作的对象让API管理变得像搭积木一样灵活。接下来我会带你从搭建到实战完整走一遍APISIX的核心使用流程你会发现管理API流量可以如此简单。2. 搭建基石部署APISIX与Dashboard的全链路指南搭建环境是第一步也是最容易踩坑的一步。网上教程很多但往往忽略了版本兼容性和生产环境的细节。我会基于当前以知识截止日期为参考的稳定版本给出一个兼顾开发测试与生产部署准备的方案。2.1 核心组件选型与架构理解在动手之前我们先理清几个核心组件和它们之间的关系APISIX (数据平面) 这是处理实际流量的核心网关。它基于Nginx和OpenResty但通过插件机制扩展了无数功能。它不直接存储配置而是从“配置中心”拉取。etcd (配置中心) APISIX使用etcd作为默认的配置存储和服务发现中心。所有你创建的路由、服务、上游、插件配置最终都存储在etcd中。APISIX节点会监听etcd的变化并实时更新自己的路由规则。APISIX Dashboard (控制平面) 这是一个可视化的管理界面让你可以通过Web UI来操作上述所有资源。它本质上是一组RESTful API你的操作会通过它写入etcd进而被APISIX读取。所以数据流向是你在Dashboard上点点点 - Dashboard调用其API - 配置写入etcd - APISIX监听etcd并更新内存配置 - 新流量生效。注意对于生产环境强烈建议将APISIX、etcd、Dashboard部署在不同的节点上并考虑etcd集群的高可用。对于本地测试或学习我们可以用Docker Compose一键拉起所有服务这是最便捷的方式。2.2 使用Docker Compose快速搭建开发环境假设你已经安装了Docker和Docker Compose。我们创建一个docker-compose.yml文件。这里的关键是版本匹配和网络配置。version: 3 services: etcd: image: bitnami/etcd:3.5.9 container_name: apisix-etcd environment: - ALLOW_NONE_AUTHENTICATIONyes - ETCD_ADVERTISE_CLIENT_URLShttp://0.0.0.0:2379 - ETCD_LISTEN_CLIENT_URLShttp://0.0.0.0:2379 ports: - 2379:2379 networks: - apisix-net apisix: image: apache/apisix:3.8.0-debian container_name: apisix-gateway restart: always volumes: - ./apisix_logs:/usr/local/apisix/logs - ./apisix_conf/config.yaml:/usr/local/apisix/conf/config.yaml:ro depends_on: - etcd ports: - 9080:9080 # HTTP 代理端口 - 9091:9091 # Admin API 端口 - 9443:9443 # HTTPS 代理端口 - 9180:9180 # 控制台API端口apisix-dashboard使用 networks: - apisix-net apisix-dashboard: image: apache/apisix-dashboard:3.0.1-alpine container_name: apisix-dashboard restart: always depends_on: - apisix environment: - APISIX_DASHBOARD_CONF/usr/local/apisix-dashboard/conf/conf.yaml volumes: - ./dashboard_conf/conf.yaml:/usr/local/apisix-dashboard/conf/conf.yaml:ro ports: - 9000:9000 networks: - apisix-net networks: apisix-net: driver: bridge接下来我们需要准备APISIX和Dashboard的配置文件。创建APISIX配置文件 (./apisix_conf/config.yaml):这个文件告诉APISIX去哪里找etcd以及如何配置自己。apisix: node_listen: - port: 9080 admin_key: - name: admin key: edd1c9f034335f136f87ad84b625c8f1 # 默认的admin key生产环境务必修改 role: admin deployment: admin: allow_admin: - 0.0.0.0/0 # 允许访问Admin API的IP生产环境应限制 admin_key_required: true etcd: host: - http://etcd:2379 # 注意这里用的是Docker服务名etcd prefix: /apisix timeout: 30创建Dashboard配置文件 (./dashboard_conf/conf.yaml):这个文件告诉Dashboard如何连接etcd和APISIX的Admin API。conf: listen: host: 0.0.0.0 port: 9000 etcd: endpoints: - http://etcd:2379 # 同样使用服务名 prefix: /apisix apisix: admin_api_url: http://apisix:9180/apisix/admin # 指向APISIX容器的Admin API admin_key: edd1c9f034335f136f87ad84b625c8f1 # 必须和APISIX配置中的admin_key一致 log: level: warn现在在包含docker-compose.yml的目录下执行docker-compose up -d等待片刻访问http://localhost:9000即可进入Dashboard默认用户名/密码admin/admin。访问http://localhost:9080是APISIX的代理端口但目前还没有路由会返回404。踩坑点1网络连接与主机名。在Docker Compose中服务之间通过服务名如etcdapisix通信。配置文件里必须用服务名而不是localhost或127.0.0.1否则容器内无法访问其他服务。踩坑点2Admin Key安全。上面的配置使用了默认key这在公网环境下极其危险。任何人拿到这个key都可以通过Admin API端口9091完全控制你的网关。生产环境必须生成一个复杂的key并替换同时严格限制allow_admin的IP范围。3. 路由配置实战从基础转发到高级匹配路由Route是APISIX中最核心的概念它定义了“什么样的请求”应该被转发到“哪里去”。热词中反复出现“静态路由配置”在APISIX里我们配置的是“动态路由”。3.1 创建你的第一个路由Hello World我们首先通过Dashboard创建一个最简单的路由。登录Dashboard进入“路由”菜单点击“创建”。基本信息 给路由起个名字比如first-route。请求匹配 这是路由规则的核心。路径 输入/hello。这意味着所有以/hello开头的请求都会匹配这条路由。高级匹配 可以先留空我们后续再玩。上游服务 这里定义请求被转发到哪里。选择“上游”为“新建上游”。上游名称my-first-upstream。目标节点 我们创建一个用于测试的Mock服务。输入httpbin.org作为主机端口80。httpbin.org是一个用于HTTP测试的公共服务。权重默认100。插件配置 暂时不启用任何插件点击“下一步”。提交 检查信息后点击“提交”。现在访问http://localhost:9080/helloAPISIX会将请求转发到http://httpbin.org/hello你应该能看到httpbin的响应。访问http://localhost:9080/hello/anything也会被转发到http://httpbin.org/hello/anything。这就是最基本的路由匹配和转发。3.2 理解路由匹配的优先级与高级规则如果只有一条路由很简单。但当你有几十上百条路由时理解匹配优先级就至关重要。APISIX的路由匹配遵循“更具体的规则优先”原则。让我们通过Dashboard再创建几条路由来实验精确匹配路由 创建路径为/hello/exact的路由上游指向另一个测试服务比如mock.api.com 这里为了演示你可以用另一个Mock服务地址或仍在httpbin但路径不同。这种完全精确的路径匹配优先级最高。前缀匹配路由 我们已经有了/hello。通用匹配路由 创建路径为/*的路由作为兜底。现在测试请求/hello/exact/foo 匹配/hello前缀匹配因为/hello/exact是精确匹配但/hello/exact/foo不是它所以降级为前缀匹配/hello。请求/hello/exact精确匹配/hello/exact的路由生效。请求/other 匹配通用路由/*。除了路径路由匹配还可以基于域名host、方法method、请求头headers、查询参数args等。例如你可以创建一条规则Host: api.example.comANDPath: /v1/*ANDMethod: POST。这在实现API版本化、多租户隔离时非常有用。实操心得 在设计路由时尽量让规则互斥避免过于宽泛的前缀匹配导致意外流量被错误路由。善用“优先级”字段在Dashboard的“高级匹配”中可以手动调整路由的匹配顺序数字越大优先级越高。对于重要的核心接口使用精确匹配或Host精确路径的组合是最稳妥的。3.3 上游、服务与消费者厘清核心概念在创建路由时你直接绑定了“上游”。但APISIX还有“服务”和“消费者”两个概念它们是什么关系上游Upstream 定义了一组后端服务节点负载均衡的目标以及负载均衡策略轮询、一致性哈希等、健康检查等配置。它是物理后端的抽象。服务Service 是某类业务功能的抽象可以绑定一组插件配置如限流、认证。一个服务可以关联一个上游。路由可以关联一个服务。这样做的好处是多个路由如/user/*下的所有接口可以共享同一套上游和插件配置避免重复配置。消费者Consumer 代表API的使用者用户、应用。可以为消费者配置身份凭证如API Key和专属的插件配置比如给VIP用户更高的限流额度。一个典型的流程是消费者通过认证插件如key-auth识别身份 -路由根据请求特征匹配 - 路由关联的服务生效其插件 -服务指向的上游处理请求并返回。在Dashboard上我建议的配置顺序是先创建上游定义好后端再创建服务绑定上游和通用插件最后创建路由绑定服务。这样逻辑最清晰也便于维护。4. 插件生态为你的API注入超能力插件是APISIX的灵魂。热词中提到了“vscode git插件”、“translation插件”APISIX的插件思想类似都是为核心系统添加可插拔的功能模块。APISIX官方提供了上百个插件涵盖认证、安全、流量控制、可观测性、请求/响应转换等方方面面。4.1 认证与安全从零搭建API防线我们以最常用的key-authAPI密钥认证和cors跨域插件为例。场景 我们希望/user/profile这个接口必须通过API Key才能访问。操作步骤创建消费者 在Dashboard“消费者”菜单中创建一名消费者比如叫app-client。在插件配置中启用key-auth插件系统会自动生成一个Key如auth-key-123你也可以手动指定。保存。配置路由插件 找到或创建一条路径为/user/profile的路由。在它的“插件配置”中启用key-auth插件。通常只需保持默认配置header中取Key名为apikey即可。测试不带Key访问http://localhost:9080/user/profile 会返回401 Unauthorized和{message:Missing API key found in request}。带Key访问curl http://localhost:9080/user/profile -H apikey: auth-key-123。此时请求成功转发到上游。结合cors插件 如果这个API需要被浏览器前端调用还必须解决跨域问题。在同一路由的插件配置中继续启用cors插件。你可以精细配置允许的源allow_origins、方法allow_methods、头信息allow_headers等。对于开发环境可以简单配置allow_origins: *和allow_credentials: false注意生产环境不要这样配。注意插件是有执行顺序的。通常认证类插件如key-auth,jwt-auth会优先执行因为如果认证失败后续的限流、转发等操作就没有必要了。APISIX内部有默认顺序一般无需手动调整。4.2 流量治理限流与熔断保稳定当你的API开始承受压力限流和熔断是保证服务稳定的关键。热词中虽然没有直接提及但这是API网关的核心场景。limit-count限流插件 限制单个客户端在单位时间内的请求次数。在目标路由或服务上启用该插件。关键配置count: 允许的请求数。time_window: 时间窗口秒。key_type: 限流维度常用var变量配合key使用。key: 例如remote_addr按客户端IP限流或consumer_name按消费者限流。示例配置{count:100, time_window:60, key_type:var, key:remote_addr}表示每个IP每分钟最多100次请求。超限后返回503 Service Temporarily Unavailable。proxy-mirror镜像流量插件 这是线上问题排查的神器。它可以将线上流量复制一份镜像发送到另一个测试环境而不影响主流程。这在复现线上bug、进行压测数据收集时非常有用。配置时只需指定一个host作为镜像目标即可。实操心得限流策略的设计。不要一上来就全局限流。建议按业务重要性分层设置1对核心登录、支付接口按用户ID或IP实施严格限流2对查询类接口可以设置较宽松的全局限流3对管理后台接口按消费者或IP白名单控制。同时一定要在Dashboard或通过日志监控限流触发情况它可能是攻击的征兆也可能是自身性能瓶颈的体现。4.3 日志与可观测性让流量一目了然APISIX本身会输出访问日志但更强大的功能是通过插件将日志推送到中心化系统。syslog插件 可以将日志推送到Syslog服务器便于传统系统集成。http-logger插件 这是我个人最常用的。它可以将每个请求的详细日志包括请求头、响应头、上游响应时间等以JSON格式POST到你指定的一个HTTP接口比如ELK的Logstash、或自研的日志服务。配置http-logger时你需要提供一个uri。此外可以配置batch_max_size和inactive_timeout来控制日志批量发送的规则避免对上游日志服务造成压力。结合Dashboard监控 APISIX Dashboard内置了简单的监控面板可以查看QPS、带宽、etcd状态等。但对于深度监控建议使用prometheus插件暴露Metrics数据然后由Grafana进行展示。这能让你清晰地看到每个路由的延迟、状态码分布、流量大小是性能分析和容量规划的基础。5. 生产环境进阶配置、调试与排坑指南将APISIX用于生产环境除了前面提到的安全配置还有更多细节需要注意。5.1 配置文件深度解析与优化我们之前用的config.yaml是最简配置。生产环境需要关注更多参数apisix: node_listen: - port: 9080 enable_admin: true admin_key: - name: admin key: your_super_strong_and_secret_key_here # 必须修改 role: admin config_center: etcd # 配置中心类型 router: http: radixtree_uri # 路由匹配算法radixtree性能很好 stream_proxy: # 如果需要代理TCP/UDP流量在此配置 tcp: - addr: 9100 deployment: role: traditional # 角色traditional(传统)或data_plane(数据平面配合控制平面) role_traditional: config_provider: etcd admin: allow_admin: # 强烈建议指定IP白名单如公司的运维网络IP段 - 10.0.0.0/8 - 192.168.1.0/24 admin_key_required: true etcd: host: - http://etcd-node1:2379 - http://etcd-node2:2379 - http://etcd-node3:2379 # 生产环境etcd集群 prefix: /apisix timeout: 30 plugins: # 明确列出需要加载的插件避免加载无用插件浪费内存 - key-auth - limit-count - cors - proxy-rewrite - http-logger # ... 仅添加你需要的插件关键优化点禁用不必要的插件 在plugins列表里只启用需要的插件可以显著减少内存占用和提高性能。调整工作进程 通过环境变量APISIX_WORKER_PROCESSES可以设置Nginx worker进程数通常设置为与CPU核心数相等。日志轮转 确保挂载的日志目录有日志轮转策略如使用logrotate防止日志占满磁盘。5.2 常见问题排查思路即使配置正确在实际运行中也可能遇到问题。这里分享几个我踩过的坑和排查思路。问题一路由配置成功但访问返回404或502。检查上游健康状态 在Dashboard的“上游”页面检查目标节点是否健康。APISIX默认有健康检查不健康的节点会被暂时摘除。检查插件冲突 是否启用了proxy-rewrite插件修改了URI或Host导致上游无法识别是否启用了redirect插件逐一禁用插件进行排查。查看APISIX错误日志docker logs apisix-gateway查看网关本身的错误信息通常会有更详细的 upstream 连接失败原因。使用curl -v调试 在APISIX服务器上直接curl上游服务地址看网络是否通端口是否正确。问题二Dashboard操作成功但配置不生效。检查etcd连接 确认APISIX和Dashboard的配置中etcd的地址和端口是否正确网络是否互通。检查配置前缀 确保APISIX和Dashboard的prefix配置一致默认都是/apisix。直接查询etcd 这是终极手段。使用etcdctl工具查看配置是否真的写入了etcdctl get --prefix /apisix。你可以看到所有以JSON格式存储的路由、上游等数据。如果这里没有说明Dashboard写入失败如果有但APISIX不生效说明APISIX读取etcd有问题。问题三性能瓶颈。监控系统资源 使用top或htop查看APISIX进程的CPU和内存使用情况。分析慢日志 如果启用了http-logger关注upstream_response_time字段如果这个值很大瓶颈可能在上游服务而非网关本身。调整Nginx参数 对于超高并发场景可能需要调整APISIX底层的Nginx参数如worker_connections这需要修改APISIX的模板文件并重建镜像属于高级优化。5.3 版本升级与备份策略升级 APISIX版本迭代较快新版本会修复bug并带来新功能。升级前务必详细阅读官方发布公告和升级指南。在测试环境充分验证。备份etcd中的所有数据。采用滚动升级方式先升级一个节点验证无误后再升级其他节点。备份 你的所有配置都存储在etcd中。定期备份etcd数据是必须的。可以使用etcdctl snapshot save命令创建快照。备份时确保APISIX集群处于稳定状态。6. 超越基础动态上游与服务发现集成对于微服务架构后端服务实例是动态变化的。手动在APISIX里维护上游节点列表是不现实的。这就需要用到服务发现集成。APISIX支持多种服务发现方式最常用的是与Nacos、Consul、Eureka等注册中心集成。这里以Nacos为例简述思路在APISIX配置中启用Nacos发现 需要在config.yaml的discovery部分配置Nacos服务器地址。创建使用服务发现的上游 在Dashboard创建上游时“服务发现”类型选择“nacos”并在“服务名”中填写你在Nacos中注册的服务名称如user-service。关联路由 创建路由时选择这个上游即可。此后当user-service有新的实例注册到Nacos或下线时APISIX会自动更新其负载均衡节点列表实现真正的动态路由。这大大降低了运维复杂度。7. 写在最后从工具到理念的转变搭建和配置APISIX掌握插件使用这些是具体的技能。但在这个过程中更重要的是理解一种理念将流量管理、API策略从业务代码中彻底解耦。以前限流、认证、熔断的代码可能散落在各个服务里标准不一难以维护。现在你可以在网关层统一定义、全局生效。以前一个服务下线或扩容需要通知所有调用方修改配置现在只需要在注册中心操作网关自动感知。APISIX Dashboard提供的可视化界面让开发和运维人员能清晰地看到整个系统的流量脉络而不再是一堆冰冷的配置文件。当出现问题时你可以快速定位是网关策略导致还是上游服务本身故障。我个人的体会是引入APISIX这类现代API网关的初期会有一个学习和适应成本比如要理解其路由模型、插件机制。但一旦团队熟悉了这套模式后续的API管理、迭代、监控都会变得异常顺畅。它就像给整个系统配备了一个智能交通指挥中心让每一股数据流都井然有序。 APISIX 从入门到生产：动态 API 网关部署与核心配置实战
1. 从零到一为什么我们需要一个现代的API网关如果你正在构建微服务、管理多个后端应用或者厌倦了在Nginx配置文件里反复折腾location和upstream那么你很可能已经听过API网关这个词。但今天我们不谈那些老生常谈的概念我想从一个更实际的场景说起去年我接手了一个遗留系统它由十几个用不同语言写的服务组成对外暴露的接口散落在各处。每次有新需求比如要统一加个认证、限流或者把请求转发到新的服务地址我们都要去改好几个地方的Nginx配置然后心惊胆战地nginx -s reload。更头疼的是没有一个集中的地方能看清所有流量的来龙去脉出了问题只能靠猜和查日志。这就是我决定引入APISIX的起点。APISIX不是一个简单的反向代理它是一个动态、实时、高性能的API网关。和传统的Nginx最大区别在于它的所有路由、插件配置都是通过API动态管理的无需重启服务。这意味着你可以在毫秒级别内上线一个新的API路由或者给一批接口全局开启限流而服务本身毫无感知。对于追求快速迭代和稳定性的团队来说这种能力是革命性的。基于热词中提到的“静态路由配置实验”、“默认路由怎么配置”我能感觉到很多朋友可能还停留在手动配置路由的阶段。APISIX要解决的正是这种配置僵化、变更成本高的问题。它把路由规则、上游服务、认证、安全、可观测性等能力都抽象成了可通过API操作的对象让API管理变得像搭积木一样灵活。接下来我会带你从搭建到实战完整走一遍APISIX的核心使用流程你会发现管理API流量可以如此简单。2. 搭建基石部署APISIX与Dashboard的全链路指南搭建环境是第一步也是最容易踩坑的一步。网上教程很多但往往忽略了版本兼容性和生产环境的细节。我会基于当前以知识截止日期为参考的稳定版本给出一个兼顾开发测试与生产部署准备的方案。2.1 核心组件选型与架构理解在动手之前我们先理清几个核心组件和它们之间的关系APISIX (数据平面) 这是处理实际流量的核心网关。它基于Nginx和OpenResty但通过插件机制扩展了无数功能。它不直接存储配置而是从“配置中心”拉取。etcd (配置中心) APISIX使用etcd作为默认的配置存储和服务发现中心。所有你创建的路由、服务、上游、插件配置最终都存储在etcd中。APISIX节点会监听etcd的变化并实时更新自己的路由规则。APISIX Dashboard (控制平面) 这是一个可视化的管理界面让你可以通过Web UI来操作上述所有资源。它本质上是一组RESTful API你的操作会通过它写入etcd进而被APISIX读取。所以数据流向是你在Dashboard上点点点 - Dashboard调用其API - 配置写入etcd - APISIX监听etcd并更新内存配置 - 新流量生效。注意对于生产环境强烈建议将APISIX、etcd、Dashboard部署在不同的节点上并考虑etcd集群的高可用。对于本地测试或学习我们可以用Docker Compose一键拉起所有服务这是最便捷的方式。2.2 使用Docker Compose快速搭建开发环境假设你已经安装了Docker和Docker Compose。我们创建一个docker-compose.yml文件。这里的关键是版本匹配和网络配置。version: 3 services: etcd: image: bitnami/etcd:3.5.9 container_name: apisix-etcd environment: - ALLOW_NONE_AUTHENTICATIONyes - ETCD_ADVERTISE_CLIENT_URLShttp://0.0.0.0:2379 - ETCD_LISTEN_CLIENT_URLShttp://0.0.0.0:2379 ports: - 2379:2379 networks: - apisix-net apisix: image: apache/apisix:3.8.0-debian container_name: apisix-gateway restart: always volumes: - ./apisix_logs:/usr/local/apisix/logs - ./apisix_conf/config.yaml:/usr/local/apisix/conf/config.yaml:ro depends_on: - etcd ports: - 9080:9080 # HTTP 代理端口 - 9091:9091 # Admin API 端口 - 9443:9443 # HTTPS 代理端口 - 9180:9180 # 控制台API端口apisix-dashboard使用 networks: - apisix-net apisix-dashboard: image: apache/apisix-dashboard:3.0.1-alpine container_name: apisix-dashboard restart: always depends_on: - apisix environment: - APISIX_DASHBOARD_CONF/usr/local/apisix-dashboard/conf/conf.yaml volumes: - ./dashboard_conf/conf.yaml:/usr/local/apisix-dashboard/conf/conf.yaml:ro ports: - 9000:9000 networks: - apisix-net networks: apisix-net: driver: bridge接下来我们需要准备APISIX和Dashboard的配置文件。创建APISIX配置文件 (./apisix_conf/config.yaml):这个文件告诉APISIX去哪里找etcd以及如何配置自己。apisix: node_listen: - port: 9080 admin_key: - name: admin key: edd1c9f034335f136f87ad84b625c8f1 # 默认的admin key生产环境务必修改 role: admin deployment: admin: allow_admin: - 0.0.0.0/0 # 允许访问Admin API的IP生产环境应限制 admin_key_required: true etcd: host: - http://etcd:2379 # 注意这里用的是Docker服务名etcd prefix: /apisix timeout: 30创建Dashboard配置文件 (./dashboard_conf/conf.yaml):这个文件告诉Dashboard如何连接etcd和APISIX的Admin API。conf: listen: host: 0.0.0.0 port: 9000 etcd: endpoints: - http://etcd:2379 # 同样使用服务名 prefix: /apisix apisix: admin_api_url: http://apisix:9180/apisix/admin # 指向APISIX容器的Admin API admin_key: edd1c9f034335f136f87ad84b625c8f1 # 必须和APISIX配置中的admin_key一致 log: level: warn现在在包含docker-compose.yml的目录下执行docker-compose up -d等待片刻访问http://localhost:9000即可进入Dashboard默认用户名/密码admin/admin。访问http://localhost:9080是APISIX的代理端口但目前还没有路由会返回404。踩坑点1网络连接与主机名。在Docker Compose中服务之间通过服务名如etcdapisix通信。配置文件里必须用服务名而不是localhost或127.0.0.1否则容器内无法访问其他服务。踩坑点2Admin Key安全。上面的配置使用了默认key这在公网环境下极其危险。任何人拿到这个key都可以通过Admin API端口9091完全控制你的网关。生产环境必须生成一个复杂的key并替换同时严格限制allow_admin的IP范围。3. 路由配置实战从基础转发到高级匹配路由Route是APISIX中最核心的概念它定义了“什么样的请求”应该被转发到“哪里去”。热词中反复出现“静态路由配置”在APISIX里我们配置的是“动态路由”。3.1 创建你的第一个路由Hello World我们首先通过Dashboard创建一个最简单的路由。登录Dashboard进入“路由”菜单点击“创建”。基本信息 给路由起个名字比如first-route。请求匹配 这是路由规则的核心。路径 输入/hello。这意味着所有以/hello开头的请求都会匹配这条路由。高级匹配 可以先留空我们后续再玩。上游服务 这里定义请求被转发到哪里。选择“上游”为“新建上游”。上游名称my-first-upstream。目标节点 我们创建一个用于测试的Mock服务。输入httpbin.org作为主机端口80。httpbin.org是一个用于HTTP测试的公共服务。权重默认100。插件配置 暂时不启用任何插件点击“下一步”。提交 检查信息后点击“提交”。现在访问http://localhost:9080/helloAPISIX会将请求转发到http://httpbin.org/hello你应该能看到httpbin的响应。访问http://localhost:9080/hello/anything也会被转发到http://httpbin.org/hello/anything。这就是最基本的路由匹配和转发。3.2 理解路由匹配的优先级与高级规则如果只有一条路由很简单。但当你有几十上百条路由时理解匹配优先级就至关重要。APISIX的路由匹配遵循“更具体的规则优先”原则。让我们通过Dashboard再创建几条路由来实验精确匹配路由 创建路径为/hello/exact的路由上游指向另一个测试服务比如mock.api.com 这里为了演示你可以用另一个Mock服务地址或仍在httpbin但路径不同。这种完全精确的路径匹配优先级最高。前缀匹配路由 我们已经有了/hello。通用匹配路由 创建路径为/*的路由作为兜底。现在测试请求/hello/exact/foo 匹配/hello前缀匹配因为/hello/exact是精确匹配但/hello/exact/foo不是它所以降级为前缀匹配/hello。请求/hello/exact精确匹配/hello/exact的路由生效。请求/other 匹配通用路由/*。除了路径路由匹配还可以基于域名host、方法method、请求头headers、查询参数args等。例如你可以创建一条规则Host: api.example.comANDPath: /v1/*ANDMethod: POST。这在实现API版本化、多租户隔离时非常有用。实操心得 在设计路由时尽量让规则互斥避免过于宽泛的前缀匹配导致意外流量被错误路由。善用“优先级”字段在Dashboard的“高级匹配”中可以手动调整路由的匹配顺序数字越大优先级越高。对于重要的核心接口使用精确匹配或Host精确路径的组合是最稳妥的。3.3 上游、服务与消费者厘清核心概念在创建路由时你直接绑定了“上游”。但APISIX还有“服务”和“消费者”两个概念它们是什么关系上游Upstream 定义了一组后端服务节点负载均衡的目标以及负载均衡策略轮询、一致性哈希等、健康检查等配置。它是物理后端的抽象。服务Service 是某类业务功能的抽象可以绑定一组插件配置如限流、认证。一个服务可以关联一个上游。路由可以关联一个服务。这样做的好处是多个路由如/user/*下的所有接口可以共享同一套上游和插件配置避免重复配置。消费者Consumer 代表API的使用者用户、应用。可以为消费者配置身份凭证如API Key和专属的插件配置比如给VIP用户更高的限流额度。一个典型的流程是消费者通过认证插件如key-auth识别身份 -路由根据请求特征匹配 - 路由关联的服务生效其插件 -服务指向的上游处理请求并返回。在Dashboard上我建议的配置顺序是先创建上游定义好后端再创建服务绑定上游和通用插件最后创建路由绑定服务。这样逻辑最清晰也便于维护。4. 插件生态为你的API注入超能力插件是APISIX的灵魂。热词中提到了“vscode git插件”、“translation插件”APISIX的插件思想类似都是为核心系统添加可插拔的功能模块。APISIX官方提供了上百个插件涵盖认证、安全、流量控制、可观测性、请求/响应转换等方方面面。4.1 认证与安全从零搭建API防线我们以最常用的key-authAPI密钥认证和cors跨域插件为例。场景 我们希望/user/profile这个接口必须通过API Key才能访问。操作步骤创建消费者 在Dashboard“消费者”菜单中创建一名消费者比如叫app-client。在插件配置中启用key-auth插件系统会自动生成一个Key如auth-key-123你也可以手动指定。保存。配置路由插件 找到或创建一条路径为/user/profile的路由。在它的“插件配置”中启用key-auth插件。通常只需保持默认配置header中取Key名为apikey即可。测试不带Key访问http://localhost:9080/user/profile 会返回401 Unauthorized和{message:Missing API key found in request}。带Key访问curl http://localhost:9080/user/profile -H apikey: auth-key-123。此时请求成功转发到上游。结合cors插件 如果这个API需要被浏览器前端调用还必须解决跨域问题。在同一路由的插件配置中继续启用cors插件。你可以精细配置允许的源allow_origins、方法allow_methods、头信息allow_headers等。对于开发环境可以简单配置allow_origins: *和allow_credentials: false注意生产环境不要这样配。注意插件是有执行顺序的。通常认证类插件如key-auth,jwt-auth会优先执行因为如果认证失败后续的限流、转发等操作就没有必要了。APISIX内部有默认顺序一般无需手动调整。4.2 流量治理限流与熔断保稳定当你的API开始承受压力限流和熔断是保证服务稳定的关键。热词中虽然没有直接提及但这是API网关的核心场景。limit-count限流插件 限制单个客户端在单位时间内的请求次数。在目标路由或服务上启用该插件。关键配置count: 允许的请求数。time_window: 时间窗口秒。key_type: 限流维度常用var变量配合key使用。key: 例如remote_addr按客户端IP限流或consumer_name按消费者限流。示例配置{count:100, time_window:60, key_type:var, key:remote_addr}表示每个IP每分钟最多100次请求。超限后返回503 Service Temporarily Unavailable。proxy-mirror镜像流量插件 这是线上问题排查的神器。它可以将线上流量复制一份镜像发送到另一个测试环境而不影响主流程。这在复现线上bug、进行压测数据收集时非常有用。配置时只需指定一个host作为镜像目标即可。实操心得限流策略的设计。不要一上来就全局限流。建议按业务重要性分层设置1对核心登录、支付接口按用户ID或IP实施严格限流2对查询类接口可以设置较宽松的全局限流3对管理后台接口按消费者或IP白名单控制。同时一定要在Dashboard或通过日志监控限流触发情况它可能是攻击的征兆也可能是自身性能瓶颈的体现。4.3 日志与可观测性让流量一目了然APISIX本身会输出访问日志但更强大的功能是通过插件将日志推送到中心化系统。syslog插件 可以将日志推送到Syslog服务器便于传统系统集成。http-logger插件 这是我个人最常用的。它可以将每个请求的详细日志包括请求头、响应头、上游响应时间等以JSON格式POST到你指定的一个HTTP接口比如ELK的Logstash、或自研的日志服务。配置http-logger时你需要提供一个uri。此外可以配置batch_max_size和inactive_timeout来控制日志批量发送的规则避免对上游日志服务造成压力。结合Dashboard监控 APISIX Dashboard内置了简单的监控面板可以查看QPS、带宽、etcd状态等。但对于深度监控建议使用prometheus插件暴露Metrics数据然后由Grafana进行展示。这能让你清晰地看到每个路由的延迟、状态码分布、流量大小是性能分析和容量规划的基础。5. 生产环境进阶配置、调试与排坑指南将APISIX用于生产环境除了前面提到的安全配置还有更多细节需要注意。5.1 配置文件深度解析与优化我们之前用的config.yaml是最简配置。生产环境需要关注更多参数apisix: node_listen: - port: 9080 enable_admin: true admin_key: - name: admin key: your_super_strong_and_secret_key_here # 必须修改 role: admin config_center: etcd # 配置中心类型 router: http: radixtree_uri # 路由匹配算法radixtree性能很好 stream_proxy: # 如果需要代理TCP/UDP流量在此配置 tcp: - addr: 9100 deployment: role: traditional # 角色traditional(传统)或data_plane(数据平面配合控制平面) role_traditional: config_provider: etcd admin: allow_admin: # 强烈建议指定IP白名单如公司的运维网络IP段 - 10.0.0.0/8 - 192.168.1.0/24 admin_key_required: true etcd: host: - http://etcd-node1:2379 - http://etcd-node2:2379 - http://etcd-node3:2379 # 生产环境etcd集群 prefix: /apisix timeout: 30 plugins: # 明确列出需要加载的插件避免加载无用插件浪费内存 - key-auth - limit-count - cors - proxy-rewrite - http-logger # ... 仅添加你需要的插件关键优化点禁用不必要的插件 在plugins列表里只启用需要的插件可以显著减少内存占用和提高性能。调整工作进程 通过环境变量APISIX_WORKER_PROCESSES可以设置Nginx worker进程数通常设置为与CPU核心数相等。日志轮转 确保挂载的日志目录有日志轮转策略如使用logrotate防止日志占满磁盘。5.2 常见问题排查思路即使配置正确在实际运行中也可能遇到问题。这里分享几个我踩过的坑和排查思路。问题一路由配置成功但访问返回404或502。检查上游健康状态 在Dashboard的“上游”页面检查目标节点是否健康。APISIX默认有健康检查不健康的节点会被暂时摘除。检查插件冲突 是否启用了proxy-rewrite插件修改了URI或Host导致上游无法识别是否启用了redirect插件逐一禁用插件进行排查。查看APISIX错误日志docker logs apisix-gateway查看网关本身的错误信息通常会有更详细的 upstream 连接失败原因。使用curl -v调试 在APISIX服务器上直接curl上游服务地址看网络是否通端口是否正确。问题二Dashboard操作成功但配置不生效。检查etcd连接 确认APISIX和Dashboard的配置中etcd的地址和端口是否正确网络是否互通。检查配置前缀 确保APISIX和Dashboard的prefix配置一致默认都是/apisix。直接查询etcd 这是终极手段。使用etcdctl工具查看配置是否真的写入了etcdctl get --prefix /apisix。你可以看到所有以JSON格式存储的路由、上游等数据。如果这里没有说明Dashboard写入失败如果有但APISIX不生效说明APISIX读取etcd有问题。问题三性能瓶颈。监控系统资源 使用top或htop查看APISIX进程的CPU和内存使用情况。分析慢日志 如果启用了http-logger关注upstream_response_time字段如果这个值很大瓶颈可能在上游服务而非网关本身。调整Nginx参数 对于超高并发场景可能需要调整APISIX底层的Nginx参数如worker_connections这需要修改APISIX的模板文件并重建镜像属于高级优化。5.3 版本升级与备份策略升级 APISIX版本迭代较快新版本会修复bug并带来新功能。升级前务必详细阅读官方发布公告和升级指南。在测试环境充分验证。备份etcd中的所有数据。采用滚动升级方式先升级一个节点验证无误后再升级其他节点。备份 你的所有配置都存储在etcd中。定期备份etcd数据是必须的。可以使用etcdctl snapshot save命令创建快照。备份时确保APISIX集群处于稳定状态。6. 超越基础动态上游与服务发现集成对于微服务架构后端服务实例是动态变化的。手动在APISIX里维护上游节点列表是不现实的。这就需要用到服务发现集成。APISIX支持多种服务发现方式最常用的是与Nacos、Consul、Eureka等注册中心集成。这里以Nacos为例简述思路在APISIX配置中启用Nacos发现 需要在config.yaml的discovery部分配置Nacos服务器地址。创建使用服务发现的上游 在Dashboard创建上游时“服务发现”类型选择“nacos”并在“服务名”中填写你在Nacos中注册的服务名称如user-service。关联路由 创建路由时选择这个上游即可。此后当user-service有新的实例注册到Nacos或下线时APISIX会自动更新其负载均衡节点列表实现真正的动态路由。这大大降低了运维复杂度。7. 写在最后从工具到理念的转变搭建和配置APISIX掌握插件使用这些是具体的技能。但在这个过程中更重要的是理解一种理念将流量管理、API策略从业务代码中彻底解耦。以前限流、认证、熔断的代码可能散落在各个服务里标准不一难以维护。现在你可以在网关层统一定义、全局生效。以前一个服务下线或扩容需要通知所有调用方修改配置现在只需要在注册中心操作网关自动感知。APISIX Dashboard提供的可视化界面让开发和运维人员能清晰地看到整个系统的流量脉络而不再是一堆冰冷的配置文件。当出现问题时你可以快速定位是网关策略导致还是上游服务本身故障。我个人的体会是引入APISIX这类现代API网关的初期会有一个学习和适应成本比如要理解其路由模型、插件机制。但一旦团队熟悉了这套模式后续的API管理、迭代、监控都会变得异常顺畅。它就像给整个系统配备了一个智能交通指挥中心让每一股数据流都井然有序。