Go-Zero项目开发29: 下载并集成APISIX API网关
纲要
go-zero服务架构概述- APISIX 简介与选型理由
- 环境准备与依赖说明
- APISIX 的安装方式
- 基于 Docker Compose 的快速部署
- 文件结构与权限处理
- 配置 APISIX
- 登录 APISIX Dashboard
- 配置上游（Upstream）以对接
go-zero服务 - 配置 HTTP 路由
- 配置 WebSocket 路由并升级协议
- 测试集成效果
- 验证 HTTP 接口
- 验证 WebSocket 连接
- 总结与后续扩展
整体架构
在上一阶段，我们已经使用go-zero构建了多个微服务，包括用户服务、WebSocket 服务等。随着服务数量的增加，直接暴露各个服务的地址不仅增加了客户端的复杂度，也不利于统一鉴权、限流、监控等。因此引入 API 网关作为唯一入口。本文选择 APISIX 作为 API 网关，完成与现有go-zero服务的集成。
APISIX 简介
APISIX 是由 Apache 软件基金会（原始团队为 api7.ai）开发的高性能、可扩展的云原生 API 网关。它具备以下特点：
- 基于 Nginx/OpenResty，天然支持四层和七层代理
- 控制面与数据面分离，配置动态生效，无需重启
- 丰富的插件生态：限流、鉴权、熔断、可观测性等
- 支持 HTTP、gRPC、Dubbo、WebSocket 等多种协议
- 提供可视化管理界面（Dashboard）
在go-zero生态中，APISIX 可以作为流量的统一调度中心，将外部请求转发至后端go-zero服务，同时提供负载均衡、协议升级等能力。
安装 APISIX
安装方式主要分为源码编译和容器化部署。为了快速与go-zero项目集成，这里采用 Docker Compose 方式进行部署。
在项目根目录下创建docker/apisix目录，并写入以下文件：
project-root/ ├─ docker/ │ └─ apisix/ │ ├─ docker-compose.yaml │ ├─ config.yaml # APISIX 网关配置 │ └─ dashboard_conf.yaml # Dashboard 配置Docker Compose 编排文件
version:"3.8"services:apisix:image:apache/apisix:3.8.0-debianrestart:alwaysvolumes:-./config.yaml:/usr/local/apisix/conf/config.yaml:roports:-"9080:9080"-"9443:9443"networks:-apisix-netapisix-dashboard:image:apache/apisix-dashboard:3.0.1restart:alwaysvolumes:-./dashboard_conf.yaml:/usr/local/apisix-dashboard/conf/conf.yaml:roports:-"9000:9000"networks:-apisix-netdepends_on:-apisixnetworks:apisix-net:driver:bridge说明：
apisix服务使用最新稳定版镜像，暴露 9080（HTTP）和 9443（HTTPS）端口，并挂载自定义配置apisix-dashboard提供可视化管理界面，暴露 9000 端口- 两个服务位于同一自定义网络，确保互相通信
APISIX 配置文件
config.yaml允许 APISIX 通过 etcd 存储配置，同时启用allow_admin以便 Dashboard 管理。
apisix:node_listen:9080enable_admin:trueallow_admin:-0.0.0.0/0admin_key:-name:"admin"key:edd1c9f034335f136f87ad84b625c8f1role:adminetcd:host:-"http://etcd:2379"prefix:"/apisix"timeout:30如果环境内已有 etcd，请根据实际地址修改。简单测试可使用内置的 etcd 或另起一个 etcd 容器。
Dashboard 配置文件
dashboard_conf.yaml指定了 Dashboard 自身监听端口及 APISIX Admin API 的地址。
conf:listen:host:0.0.0.0port:9000etcd:endpoints:-etcd:2379admin_api:api_key:edd1c9f034335f136f87ad84b625c8f1将以上文件上传至服务器后，进入docker/apisix目录执行：
docker-composeup-d首次启动可能因为目录权限问题导致 APISIX 启动失败。检查日志常见错误为Permission denied访问挂载的配置文件或日志目录。解决方案：
# 根据实际情况调整目录权限chmod-R755./config.yaml ./dashboard_conf.yamldocker-composedown&&docker-composeup-d通过docker-compose ps确认两个服务均为Up状态即可。
配置 APISIX 对接 go-zero 服务
登录 Dashboard，假设服务器 IP 为192.168.1.100，浏览器访问http://192.168.1.100:9000，默认用户名密码为admin/admin（可根据安全要求修改）。
配置上游（Upstream）
上游代表一组后端服务实例。我们为go-zero的用户服务创建上游。
- 名称：
user-api - 类型：轮询（roundrobin）负载均衡
- 目标节点：
192.168.1.100:8888（go-zero用户服务的实际监听地址） - 协议：HTTP
若存在多个实例，可添加多个节点实现负载均衡。
类似的，为 WebSocket 服务创建上游：
- 名称：
ws-api - 节点：
192.168.1.100:9999（假设 WebSocket 服务监听 9999） - 协议：HTTP（APISIX 会自动处理 WebSocket 升级）
配置路由
HTTP 用户服务路由
- 名称：
user-route-v1 - 路径：
/v1/user/* - 方法：所有
- 匹配上游：
user-api - 其他保持默认即可
其中go-zero的用户 API 通常定义类似/v1/user/login，使用前缀匹配即可将所有用户相关请求转发。
WebSocket 路由
- 名称：
ws-route-v1 - 路径：
/v1/ws - 方法：GET
- 高级匹配 -> 协议：
WebSocket（勾选后 APISIX 会识别Upgrade头并转为 WebSocket 代理） - 匹配上游：
ws-api
此时，外部客户端只需将请求统一发往 APISIX 的9080端口，路径与上述路由匹配后即可到达对应的go-zero服务。
测试集成
HTTP 接口测试
原本直接访问http://192.168.1.100:8888/v1/user/login，现在改为：
POST http://192.168.1.100:9080/v1/user/login
携带正确的 JSON 请求体，响应应与直连时一致。例如：
{"username":"test","password":"123456"}返回 token 等信息，说明网关转发成功。
WebSocket 测试
原本 WebSocket 地址为ws://192.168.1.100:9999/v1/ws，现改为ws://192.168.1.100:9080/v1/ws。使用在线工具或wscat测试：
wscat-cws://192.168.1.100:9080/v1/ws连接成功后发送心跳或查询消息，能够正常收发，证明 WebSocket 路由与协议升级配置正确。
总结
通过以上步骤，我们在go-zero项目中成功集成了 APISIX 网关。所有客户端现在只需面向 APISIX 的单一入口地址，内部路由和负载均衡由网关处理。后续可以在 APISIX 上叠加身份认证、限流、日志等插件，进一步完善微服务体系。
后续建议
- 将 APISIX 的 etcd 配置改为高可用集群
- 为路由添加 JWT 插件，与
go-zero的认证体系对接 - 集成 Prometheus 插件，将指标暴露至监控系统
- 使用 APISIX 的
openid-connect或自定义插件实现统一鉴权
本集成方式同样适用于任何采用go-zero框架构建的服务集群。