一、环境搭建背景与价值

Apache APISIX作为云原生时代的高性能API网关，其插件化架构与动态路由能力广受开发者青睐。结合Dashboard管理界面、Prometheus时序数据库及Grafana可视化工具，可构建从API流量管理到性能监控的全栈解决方案。本地测试环境的搭建不仅能验证技术可行性，更能为后续生产环境部署提供标准化模板。

二、环境准备与组件版本

2.1 基础环境要求

• 操作系统：Linux（Ubuntu 20.04/CentOS 8）或macOS（11.0+）
• 依赖工具：Docker 20.10+、Docker Compose 1.29+、curl、jq
• 资源需求：4核CPU、8GB内存、50GB磁盘空间

2.2 组件版本选择

组件	版本	功能定位
Apache APISIX	3.5.0	核心API网关
APISIX Dashboard	2.15.0	管理控制台
Prometheus	2.47.0	监控数据采集与存储
Grafana	10.2.0	可视化展示
etcd	3.5.9	配置中心（APISIX依赖）

三、组件部署实施步骤

3.1 Docker Compose配置文件

创建docker-compose.yml文件，定义服务网络与卷映射：

version: '3.8'
services:
  etcd:
    image: bitnami/etcd:3.5.9
    environment:
      - ALLOW_NONE_AUTHENTICATION=yes
    volumes:
      - etcd_data:/bitnami/etcd
    ports:
      - "2379:2379"
  apisix:
    image: apache/apisix:3.5.0-alpine
    depends_on:
      - etcd
    environment:
      - APISIX_ETCD_SERVERS=etcd:2379
    ports:
      - "9080:9080"      # HTTP端口
      - "9443:9443"      # HTTPS端口
      - "9180:9180"      # Prometheus指标端口
  dashboard:
    image: apache/apisix-dashboard:2.15.0
    depends_on:
      - apisix
    environment:
      - APISIX_ADMIN_KEY=edd1c9f034335f136f87ad84b625c8f1
    ports:
      - "9000:9000"
  prometheus:
    image: prom/prometheus:v2.47.0
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
    ports:
      - "9090:9090"
  grafana:
    image: grafana/grafana:10.2.0
    volumes:
      - grafana_data:/var/lib/grafana
    ports:
      - "3000:3000"
volumes:
  etcd_data:
  grafana_data:

3.2 Prometheus配置优化

创建prometheus.yml文件，配置APISIX作为监控目标：

global:
  scrape_interval: 15s
scrape_configs:
  - job_name: 'apisix'
    static_configs:
      - targets: ['apisix:9180']
    metrics_path: '/apisix/prometheus/metrics'

3.3 组件启动流程

1. 初始化环境：

   mkdir -p apisix_env && cd apisix_env
   curl -O https://raw.githubusercontent.com/apache/apisix/master/docker/docker-compose.yml
   curl -O https://raw.githubusercontent.com/apache/apisix/master/docker/prometheus.yml

2. 启动服务集群：

   docker-compose up -d

3. 验证服务状态：

   docker-compose ps
   # 预期输出：所有服务显示"Up (healthy)"

四、功能集成与验证

4.1 Dashboard配置

1. 访问管理界面：http://localhost:9000
2. 使用默认凭据登录：
   • 用户名：admin
   • 密码：admin
3. 创建测试路由：
   • 路径：/test
   • 上游服务：httpbin.org（示例）
   • 插件配置：添加prometheus插件

4.2 Prometheus数据验证

1. 访问指标接口：

   curl http://localhost:9180/apisix/prometheus/metrics

2. 验证关键指标：
   • apisix_http_requests_total：请求总数
   • apisix_http_latency_seconds：请求延迟

4.3 Grafana仪表盘配置

1. 访问Grafana：http://localhost:3000
2. 添加Prometheus数据源：
   • URL：http://prometheus:9090
3. 导入APISIX官方仪表盘（ID：17121）
4. 配置告警规则示例：

   groups:
   - name: apisix_alerts
    rules:
      - alert: HighErrorRate
        expr: rate(apisix_http_status_total{code="5xx"}[1m]) > 10
        for: 5m
        labels:
          severity: critical
        annotations:
          summary: "高错误率告警"

五、常见问题解决方案

5.1 连接拒绝问题

现象：Dashboard无法连接APISIX
原因：网络配置错误或认证密钥不匹配
解决：

1. 检查APISIX_ADMIN_KEY环境变量
2. 验证etcd服务状态：

   docker exec -it apisix_etcd_1 etcdctl endpoint status

5.2 指标采集异常

现象：Prometheus无APISIX数据
解决：

1. 检查APISIX插件配置：

   curl http://localhost:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1'

2. 验证插件是否启用：

   {
   "plugins": {
    "prometheus": {}
   }
   }

5.3 Grafana面板无数据

解决：

1. 检查Prometheus数据源配置
2. 验证指标名称是否匹配：

   curl http://localhost:9090/api/v1/label/__name__/values

六、生产环境迁移建议

1. 持久化存储：将etcd和Grafana数据卷映射至云存储
2. 高可用部署：
   • etcd集群化（3节点起）
   • APISIX多实例负载均衡
3. 安全加固：
   • 启用HTTPS双向认证
   • 配置Dashboard访问控制
4. 监控扩展：
   • 集成Alertmanager告警系统
   • 添加Loki日志收集

七、总结与展望

本环境搭建方案通过容器化技术实现了APISIX生态组件的快速部署，验证了从API管理到监控告警的完整链路。实际生产环境中，建议结合Kubernetes Operator实现自动化运维，并考虑使用Thanos等方案解决Prometheus长期存储问题。后续篇章将深入探讨APISIX的插件开发、流量控制策略及多云部署实践。

附件：完整docker-compose.yml及配置文件参考GitHub仓库[示例链接]（需替换为实际链接）
技术支持：Apache APISIX官方Slack频道及邮件列表

本文提供的部署方案已在Ubuntu 22.04 LTS环境下验证通过，所有组件版本均来自官方稳定发布渠道。读者可根据实际需求调整资源配额和组件参数，建议首次部署时保持默认配置以降低复杂度。”