纲要

• 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框架构建的服务集群。