APISIX 3.11.0 生产级高可用集群Docker Compose 编排实战与深度调优在微服务架构成为主流的今天API网关作为流量入口和治理中枢其稳定性和可维护性直接决定了整个系统的韧性。很多团队在从开发测试环境迈向生产部署时往往会遇到一个尴尬的局面单机部署的示例跑得飞快一旦需要组成集群、考虑高可用和持久化各种配置和编排问题便接踵而至。Apache APISIX 以其高性能和丰富的插件生态著称但如何将其与 etcd、Dashboard 等组件优雅地组合成一个易于维护、适合生产环境的高可用集群则是另一个层面的挑战。本文将彻底抛弃零散的docker run命令转向以Docker Compose为核心的声明式编排方案。我们不仅会搭建一个基础可用的集群更会深入生产环境必须关注的细节如何为容器设置合理的资源限制以避免相互干扰如何将关键日志持久化到宿主机以便排查问题如何配置 TLS 证书以保障管理通道安全以及如何利用 Docker Compose 内置的网络和服务发现机制彻底告别老旧且不推荐使用的--link方式。无论你是负责线上稳定的运维工程师还是追求架构优雅的开发者这份指南都将为你提供一个坚实、可复用的起点。1. 架构设计与核心组件规划在动手编写docker-compose.yml之前清晰的架构蓝图至关重要。一个生产可用的 APISIX 集群绝非简单地将几个容器堆叠在一起。我们需要考虑服务发现、配置存储、管理界面以及它们之间的网络通信和数据持久化。我们的目标架构包含以下核心组件Apache APISIX (数据平面)处理实际 API 流量支持动态路由、认证、限流等。在生产环境中我们通常会部署多个实例以实现负载均衡和高可用。etcd (控制平面)作为 APISIX 的配置存储中心所有路由、插件、上游等配置都持久化在此。etcd 本身需要以集群模式部署至少3节点来保证高可用但为了简化演示和资源考虑本文将以单节点模式展示其与 APISIX 的集成方式并给出扩展为集群的指引。APISIX Dashboard (管理平面)提供图形化界面用于配置和监控 APISIX。它通过读取和写入 etcd 来间接管理 APISIX。它们之间的关系如下图所示逻辑层面[外部客户端] | v [APISIX 节点] -- 读取配置 -- [etcd] | ^ | | [处理API请求] | | | v | [上游服务] [APISIX Dashboard] | v [修改/查看配置]在 Docker Compose 的语境下我们将利用其自定义网络功能让所有服务在同一个隔离的网络中运行通过服务名称如apisix,etcd-server直接进行 DNS 解析和通信这比传统的--link更加灵活和标准。注意本文假设你已在目标服务器上安装了 Docker 和 Docker Compose。对于离线环境你需要提前在有网络的环境中拉取所需镜像apache/apisix:3.11.0,bitnami/etcd:3.5,apache/apisix-dashboard:3.0.1并使用docker save导出在离线服务器上使用docker load导入。2. Docker Compose 编排文件详解我们将创建一个完整的docker-compose.yml文件并逐部分解释其生产级考量。请在你的项目根目录下创建此文件。version: 3.8 services: # 1. etcd 服务 - 配置存储中心 etcd: image: bitnami/etcd:3.5.18 container_name: apisix-etcd restart: unless-stopped environment: - ALLOW_NONE_AUTHENTICATIONyes - ETCD_ADVERTISE_CLIENT_URLShttp://etcd:2379 - ETCD_LISTEN_CLIENT_URLShttp://0.0.0.0:2379 - ETCD_DATA_DIR/data/etcd volumes: - ./data/etcd:/data/etcd - ./logs/etcd:/opt/bitnami/etcd/logs networks: - apisix-network deploy: resources: limits: memory: 512M cpus: 0.5 reservations: memory: 256M cpus: 0.25 healthcheck: test: [CMD, etcdctl, endpoint, health] interval: 30s timeout: 10s retries: 3 start_period: 40s # 2. APISIX 网关服务 apisix: image: apache/apisix:3.11.0-alpine container_name: apisix-gateway restart: unless-stopped depends_on: etcd: condition: service_healthy volumes: - ./conf/apisix/config.yaml:/usr/local/apisix/conf/config.yaml:ro - ./logs/apisix:/usr/local/apisix/logs ports: - 9080:9080 # HTTP 代理端口 - 9443:9443 # HTTPS 代理端口 - 9180:9180 # Admin API 端口 (生产环境建议不暴露或通过Nginx代理) environment: - TZAsia/Shanghai networks: - apisix-network deploy: resources: limits: memory: 1G cpus: 1.0 reservations: memory: 512M cpus: 0.5 healthcheck: test: [CMD, curl, -f, http://localhost:9080/apisix/admin/routes] interval: 30s timeout: 10s retries: 3 # 3. APISIX Dashboard 管理界面 dashboard: image: apache/apisix-dashboard:3.0.1-alpine container_name: apisix-dashboard restart: unless-stopped depends_on: etcd: condition: service_healthy apisix: condition: service_healthy volumes: - ./conf/dashboard/conf.yaml:/usr/local/apisix-dashboard/conf/conf.yaml:ro ports: - 9000:9000 environment: - TZAsia/Shanghai networks: - apisix-network deploy: resources: limits: memory: 512M cpus: 0.5 networks: apisix-network: driver: bridge ipam: config: - subnet: 172.28.0.0/16关键生产配置解析服务发现与网络我们创建了一个名为apisix-network的自定义桥接网络。所有服务加入此网络后可以直接使用服务名称如etcd,apisix作为主机名进行通信。例如APISIX 配置中连接 etcd 的地址就是http://etcd:2379。这比使用--link更清晰且是 Docker 推荐的方式。资源限制 (deploy.resources)这是生产环境必须项。它为每个容器设置了 CPU 和内存的使用上限 (limits) 和预留资源 (reservations)防止某个服务异常时耗尽主机资源影响其他服务。例如我们将 etcd 的内存限制在 512MB。健康检查 (healthcheck)我们为etcd和apisix配置了健康检查。depends_on中的condition: service_healthy确保了服务启动的顺序性和依赖性只有 etcd 健康后APISIX 才会启动这提升了启动的可靠性。配置与日志持久化 (volumes)将容器内的配置目录 (/usr/local/apisix/conf/config.yaml) 挂载到宿主机的./conf/apisix/目录。使用:ro(只读) 可以防止容器意外修改配置。将日志目录 (/usr/local/apisix/logs) 挂载到宿主机的./logs/apisix。这样日志不会随着容器销毁而丢失便于使用 ELK 等工具进行收集分析。etcd 的数据目录 (/data/etcd) 也必须持久化否则配置数据会丢失。镜像选择我们选择了-alpine标签的镜像它们基于 Alpine Linux体积更小安全性相对更高更适合生产环境。3. 关键配置文件定制与安全加固Docker Compose 编排了服务但每个服务的行为还需要通过配置文件来精细控制。下面我们分别配置 APISIX 和 Dashboard。3.1 APISIX 核心配置 (./conf/apisix/config.yaml)这个文件定义了 APISIX 网关本身的行为尤其是如何连接 etcd。apisix: node_listen: - port: 9080 - port: 9443 enable_http2: true enable_admin: true admin_key: - name: admin key: YOUR_STRONG_ADMIN_KEY_HERE # 务必修改使用强密码生成。 role: admin admin_listen: ip: 0.0.0.0 port: 9180 deployment: role: traditional role_traditional: config_provider: etcd admin: admin_key_required: true # 强制要求 Admin API 使用密钥 etcd: host: - http://etcd:2379 # 使用 Docker Compose 服务名 prefix: /apisix timeout: 30 plugins: - limit-req - limit-count - key-auth - jwt-auth - zipkin - prometheus # 按需添加其他插件 plugin_attr: prometheus: export_addr: ip: 0.0.0.0 port: 9091安全要点admin_key这是访问 Admin API (端口 9180) 的凭证。绝对不要使用示例中的默认值。请使用一个强随机字符串替换YOUR_STRONG_ADMIN_KEY_HERE。你可以用以下命令生成openssl rand -base64 32。admin_key_required: true确保 Admin API 必须验证密钥防止未授权访问。生产环境建议不要将 Admin API 端口 (9180) 直接暴露在公网。可以通过 Docker Compose 不映射此端口或者通过 Nginx 配置 IP 白名单和 HTTPS 反向代理来访问。3.2 APISIX Dashboard 配置 (./conf/dashboard/conf.yaml)Dashboard 需要连接 etcd 来读写配置并连接 APISIX 的 Admin API 来验证密钥。conf: listen: host: 0.0.0.0 port: 9000 allow_list: # 访问控制列表建议限制为内网或运维IP段 - 0.0.0.0/0 # 示例允许所有IP。生产环境应设置为具体IP如 192.168.1.0/24 etcd: endpoints: - http://etcd:2379 # 如果 etcd 启用了认证需配置 username 和 password # username: root # password: your-etcd-password apisix: admin_api_url: http://apisix:9180 admin_api_key: YOUR_STRONG_ADMIN_KEY_HERE # 必须与 APISIX config.yaml 中的 admin_key 一致 authentication: secret: ANOTHER_STRONG_SECRET_FOR_JWT # 用于 Dashboard 会话加密务必修改 expire_time: 3600 users: - username: admin # Dashboard 登录用户名 password: $2a$10$xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx # bcrypt 加密后的密码配置步骤创建上述目录和文件mkdir -p ./conf/apisix ./conf/dashboard ./data/etcd ./logs/{etcd,apisix}。生成 Dashboard 登录密码。使用htpasswd或在线 Bcrypt 生成器。例如密码设为admin123其 Bcrypt 哈希可能为$2a$10$xxxxxxxx...。将此哈希值填入password字段。将YOUR_STRONG_ADMIN_KEY_HERE替换为你在 APISIX 配置中生成的相同密钥。将ANOTHER_STRONG_SECRET_FOR_JWT替换为另一个随机字符串。4. 部署、操作与生产维护完成所有配置后即可启动整个集群。4.1 启动与验证在包含docker-compose.yml的目录下执行# 启动所有服务后台运行 docker-compose up -d # 查看服务状态和日志 docker-compose ps docker-compose logs -f apisix # 查看 APISIX 日志 # 停止服务 docker-compose down # 停止并清理持久化数据谨慎使用 docker-compose down -v启动后进行基础验证# 1. 检查 etcd 健康状态 docker-compose exec etcd etcdctl endpoint health # 应输出http://etcd:2379 is healthy # 2. 测试 APISIX Admin API curl -i http://localhost:9180/apisix/admin/routes -H X-API-KEY: YOUR_STRONG_ADMIN_KEY_HERE # 应返回 200 OK 及路由列表初始为空 # 3. 访问 APISIX Dashboard # 浏览器打开 http://你的服务器IP:9000 # 使用配置的用户名如 admin和密码如 admin123登录4.2 通过 Dashboard 配置第一个路由登录 Dashboard 后你可以直观地配置路由、上游和插件。创建上游Upstream在“上游”菜单中创建一个指向你的后端服务例如一个测试用的 HTTP Bin 服务httpbin.org:80的上游。创建路由Route在“路由”菜单中创建一个新路由。设置匹配路径如/get并选择刚才创建的上游。测试路由在终端执行curl http://localhost:9080/get你应该能看到来自httpbin.org的响应。这个过程完全在图形界面完成无需手动编写 curl 命令极大地提升了运维效率。4.3 生产环境进阶调优一个能抗住流量的生产集群还需要更多考量。1. 日志收集与监控日志我们已经将日志挂载到宿主机。可以配置 Filebeat 或 Fluentd 将这些日志发送到 Elasticsearch 或 Loki。监控APISIX 内置了 Prometheus 插件我们已在配置中启用。它会在http://apisix:9091/apisix/prometheus/metrics暴露指标。你可以在 Docker Compose 中为 APISIX 额外暴露 9091 端口或者部署一个 Prometheus 服务到同一网络中来抓取。2. TLS 证书配置为 Admin API 和 Dashboard 启用 HTTPS 是基本安全要求。你需要准备 SSL 证书和私钥。APISIX Admin API TLS在config.yaml的admin_listen部分配置ssl相关选项并挂载证书文件到容器。Dashboard TLS在 Dashboard 的conf.yaml中配置listen.ssl部分。更佳实践在 APISIX 前端放置一个 Nginx 或 HAProxy由它们终止 TLS并将请求代理到后端服务的 HTTP 端口。这样证书管理更集中。3. 高可用与扩展多 APISIX 节点要扩展 APISIX 本身只需在docker-compose.yml中复制apisix服务定义修改container_name和宿主机映射端口如- 9081:9080然后使用负载均衡器如 Nginx, HAProxy 或云负载均衡将流量分发到多个 APISIX 实例。etcd 集群生产环境 etcd 必须集群化至少3节点。你需要修改docker-compose.yml中的etcd服务配置设置ETCD_INITIAL_CLUSTER,ETCD_NAME,ETCD_INITIAL_ADVERTISE_PEER_URLS等环境变量来组建集群。这超出了单文件的范畴可能需要为每个 etcd 节点编写独立的 Compose 配置或使用更高级的编排工具如 Kubernetes。4. 资源与性能调优下表列出了一些关键参数及其生产环境调整建议组件配置项默认/示例值生产调优建议APISIXworker_processesauto(CPU核数)通常设置为与主机CPU逻辑核心数相同。worker_connections1024根据预期并发连接数调整可增至 4096 或更高。keepalive_timeout60s根据上游服务特性调整长连接场景可适当增加。etcdETCD_QUOTA_BACKEND_BYTES2GB根据配置数据量预估设置存储配额防止磁盘写满。ETCD_MAX_REQUEST_BYTES1.5MB如果单个配置项很大可能需要调大此值。Dockerdeploy.resources.limits.memory1G根据实际监控到的内存使用峰值设置留出 buffer。deploy.resources.limits.cpus1.0根据 CPU 使用率监控设置限制避免饥饿。配置这些参数通常需要修改各自的配置文件如 APISIX 的config.yaml或通过环境变量etcd传入。5. 故障排查与日常运维命令即使部署顺利日常也会遇到问题。掌握以下命令和排查思路至关重要。查看服务日志# 查看所有服务日志 docker-compose logs # 查看特定服务最近100行日志并持续跟踪 docker-compose logs -f --tail100 apisix # 进入容器内部查看日志文件 docker-compose exec apisix tail -f /usr/local/apisix/logs/error.log检查服务状态与资源使用# 查看容器状态和端口映射 docker-compose ps # 查看容器资源使用情况CPU内存 docker stats $(docker-compose ps -q) # 进入容器进行诊断 docker-compose exec apisix sh # 在容器内可以测试连接到 etcd curl -v http://etcd:2379/version常见问题与解决思路Dashboard 无法连接 etcd检查 Dashboard 日志docker-compose logs dashboard。最常见原因是 etcd 地址配置错误应使用服务名etcd或 etcd 未健康启动。确保depends_on和健康检查生效。APISIX 路由不生效首先检查 Admin API 是否配置成功curl -H X-API-KEY: xxx http://localhost:9180/apisix/admin/routes。如果返回空说明配置未同步到 etcd。检查 APISIX 日志看是否有连接 etcd 的错误。其次在 Dashboard 或通过 API 创建路由后确认路由的uri和host匹配你的请求。性能瓶颈如果发现 APISIX 吞吐量下降可以进入容器使用top或vmstat查看资源情况。同时开启 Prometheus 监控分析请求延迟、QPS 等指标。检查宿主机资源是否充足。最后记得将你的docker-compose.yml和所有自定义配置文件纳入版本控制系统如 Git。这样整个集群的部署状态就成为了可追溯、可复现的代码。每次变更都通过修改配置文件和重新执行docker-compose up -d来完成这本身就是一种基础设施即代码IaC的最佳实践。