基于 Docker Compose 部署 Apache APISIX：全栈 API 网关实践

本文基于 APISIX 3.9.1 + Dashboard 3.0.1 + etcd 3.5.15 + Prometheus + Grafana 的生产级 Docker Compose 部署实践。

一、整体架构

本次部署采用 Docker Compose 编排五大组件，形成从配置管理到流量监控的完整闭环：

所有组件运行在 Docker Bridge 网络 apisix 中，通过容器名互访，对外通过宿主机端口映射提供服务。

二、端口映射设计

采用 2xxxx 系列高位端口，避免与宿主机常用端口冲突：

三、数据流分析

整个系统包含两条核心数据流：配置流 和 监控流。

3.1 配置流

1. Dashboard → etcd：运维人员通过 Dashboard 创建路由、配置插件，数据写入 etcd
2. etcd → APISIX：APISIX 通过 etcd watch 实时感知配置变更，无需重启即可生效

这种 etcd 驱动的配置模式是 APISIX 的核心设计优势 —— 配置热更新，零中断。

3.2 监控流

1. APISIX → Prometheus：APISIX 内置 prometheus 插件，在 9091 端口暴露指标端点，Prometheus 以 5 秒间隔持续采集
2. Prometheus → Grafana：Grafana 以 Prometheus 作为数据源，通过预配置的 Dashboard 实现可视化

四、APISIX 核心配置

4.1 Admin API 双角色认证

APISIX 的 Admin API 定义了两个角色，各自持有独立 API Key：

deployment:
  admin:
    allow_admin:
      - 0.0.0.0/0
    admin_key:
      - name: "admin"
        key: <admin-api-key>
        role: admin
      - name: "viewer"
        key: <viewer-api-key>
        role: viewer

生产环境中应将 allow_admin 限制为可信 IP 资段，而非 0.0.0.0/0。

4.2 etcd 连接配置

deployment:
  etcd:
    host:
      - "http://etcd:2379"
    prefix: "/apisix"
    timeout: 30

• host 使用 Docker 网络内的容器名 etcd，无需硬编码 IP
• prefix: "/apisix" 是 APISIX 在 etcd 中的键前缀，与 Dashboard 配置一致
• timeout: 30 秒，适应容器启动初期的网络延迟

4.3 Prometheus 插件配置

plugin_attr:
  prometheus:
    export_addr:
      ip: "0.0.0.0"
      port: 9091

指标端点绑定 0.0.0.0:9091，允许 Prometheus 从 Docker 网络内访问。指标路径为 /apisix/prometheus/metrics。

4.4 Control API

apisix:
  enable_control: true
  control:
    ip: "0.0.0.0"
    port: 9092

Control API 用于 APISIX 自身健康检查与运行时信息查询，独立于 Admin API。

五、Dashboard 配置

5.1 访问控制

conf:
  allow_list:
    - 127.0.0.1
    - ::1
    - 0.0.0.0/0

allow_list 定义了 Dashboard Manager API 的 IP 白名单。当前配置允许所有访问，生产环境应收紧。

5.2 认证体系

Dashboard 定义了两个登录账号：

authentication:
  secret: <jwt-secret>
  expire_time: 3600
  users:
    - username: admin
      password: <admin-password>
    - username: user
      password: <user-password>

认证机制基于 JWT，Token 有效期 3600 秒（1 小时）。secret 字段强烈建议修改，默认值会在启动时被随机替换。

5.3 etcd 连接

conf:
  etcd:
    endpoints:
      - etcd:2379

与 APISIX 使用相同的 etcd 地址，确保配置读写一致性。

5.4 日志级别

conf:
  log:
    error_log:
      level: warn

日志级别设为 warn，平衡了信息量与性能开销，适合生产环境。

六、插件生态

Dashboard 配置中声明了完整的插件列表，涵盖六大核心类别：

插件通过 etcd 配置动态加载，无需重启 APISIX 即可生效。

七、监控体系

7.1 Prometheus 采集配置

global:
  scrape_interval: 1s
  external_labels:
    stack: "apisix"

scrape_configs:
  - job_name: "prometheus"
    scrape_interval: 5s
    static_configs:
      - targets: ["localhost:9090"]
  - job_name: "apisix"
    scrape_interval: 5s
    metrics_path: "/apisix/prometheus/metrics"
    static_configs:
      - targets: ["apisix:9091"]

关键配置：

• 全局默认采集间隔 1 秒，Prometheus 自身和 APISIX 各 5 秒
• APISIX job 的 metrics_path 指定 /apisix/prometheus/metrics（APISIX 插件默认路径）
• targets 使用 Docker 容器名 apisix，与 docker-compose 网络一致
• external_labels.stack: "apisix" 为所有指标添加栈标签，便于多环境区分

7.2 Grafana 自动配置

Grafana 通过 provisioning 机制实现了 开箱即用：

数据源自动配置：

datasources:
  - access: 'proxy'
    editable: true
    is_default: true
    name: 'apisix'
    org_id: 1
    type: 'prometheus'
    url: 'http://prometheus:9090'
    version: 1

数据源指向 Docker 内网的 Prometheus，Grafana 启动后即可直接查询 APISIX 指标。

Dashboard 自动加载：

providers:
  - name: 'default'
    orgId: 1
    folder: ''
    type: file
    options:
      path: /var/lib/grafana/dashboards

预置了 apisix-grafana-dashboard.json，启动后自动呈现 APISIX 专用监控面板，无需手动配置。

7.3 Grafana 安全配置

[security]
allow_embedding = true
content_security_policy = true

[auth.anonymous]
enabled = true

• allow_embedding = true：允许 Dashboard 将 Grafana 面板嵌入 iframe
• auth.anonymous.enabled = true：匿名访问，适合内部监控场景
• CSP 中允许了内网 IP 段的 frame-src，支持 Dashboard 嵌入 Grafana 面板

八、etcd 配置要点

# etcd docker-compose 环境变量
ETCD_ENABLE_V2: "true"
ALLOW_NONE_AUTHENTICATION: "yes"
ETCD_ADVERTISE_CLIENT_URLS: "http://etcd:2379"
ETCD_LISTEN_CLIENT_URLS: "http://0.0.0.0:2379"

关键配置：

• ETCD_ENABLE_V2: "true"：APISIX 依赖 etcd V2 API，必须启用
• ALLOW_NONE_AUTHENTICATION: "yes"：无认证模式，适合内网部署；生产环境应启用认证
• advertise URL 使用容器名：确保 Docker 网络内客户端能正确发现 etcd

# etcd.conf.yml 关键参数
heartbeat-interval: 100
election-timeout: 1000
auto-compaction-mode: periodic
auto-compaction-retention: "1"

• auto-compaction-mode: periodic + retention: "1"：每小时自动压缩历史数据，防止 etcd 数据无限膨胀
• strict-reconfig-check: false：放宽重新配置检查，简化单节点部署

九、部署流程

步骤 1：配置文件准备

根据实际环境修改以下关键配置：

• apisix_conf/config.yaml：Admin API Key、etcd 地址
• dashboard_conf/config.yaml：登录密码、JWT Secret、allow_list
• prometheus_conf/prometheus.yml：采集目标地址
• grafana_conf/config/grafana.ini：CSP 域名白名单

步骤 2：启动服务

docker-compose up -d

验证所有容器状态：

docker-compose ps

步骤 3：访问 Dashboard

浏览器打开 http://<宿主机IP>:29000，使用 admin 账号登录。

步骤 4：配置路由与插件

在 Dashboard 中创建 Route、Upstream，并绑定所需插件（如限流、认证、日志等）。

步骤 5：监控可视化

浏览器打开 http://<宿主机IP>:23000，查看预配置的 APISIX 监控面板。

十、生产环境加固建议

十一、实践总结