Docker Compose部署APISIX 3.11.0无法连接etcd求助

问题现象 #

APISIX启动失败，无法连接etcd，日志报错：

Warning! Request etcd endpoint 'http://127.0.0.1:2379/version' error, connection refused, retry time=1
Warning! Request etcd endpoint 'http://127.0.0.1:2379/version' error, connection refused, retry time=2
request etcd endpoint 'http://127.0.0.1:2379/version' error, connection refused
all etcd nodes are unavailable

宿主机测试etcd端点正常：
执行命令：

wget http://127.0.0.1:2379/version

响应：

{"etcdserver":"3.5.11","etcdcluster":"3.5.0"}

环境配置 #

docker-compose.yml #

version: "3"

services:
  apisix:
    image: apache/apisix:${APISIX_IMAGE_TAG:-3.11.0-debian}
    restart: always
    volumes:
      - ./apisix_conf/config.yaml:/usr/local/apisix/conf/config.yaml:ro
    depends_on:
      - etcd
    ports:
      - "9180:9180/tcp"
      - "9080:9080/tcp"
      - "9091:9091/tcp"
      - "9443:9443/tcp"
      - "9093:9092/tcp"
    networks:
      - apisix

  etcd:
    image: bitnami/etcd:3.5.11
    restart: always
    volumes:
      - etcd_data:/bitnami/etcd
    environment:
      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"
    ports:
      - "2379:2379/tcp"
    networks:
      - apisix

networks:
  apisix:
    driver: bridge

volumes:
  etcd_data:
    driver: local

APISIX config.yaml #

apisix:
  node_listen: 9080
  enable_admin: true
  admin_key:
    - name: "admin"
      key: "admin123"
      role: admin

etcd:
  host:
    - "http://etcd:2379"

已尝试操作 #

• 验证etcd在宿主机可正常访问
• 确认APISIX与etcd容器在同一Docker网络（apisix-docker_apisix）
• 确认config.yaml已正确挂载到APISIX容器
• 将etcd.host配置改为http://etcd:2379而非http://127.0.0.1:2379
• 多次重启容器

额外信息 #

• Docker版本：20.10.12
• Docker Compose版本：2.20.3
• 操作系统：Ubuntu 24.04

疑问 #

1. 为何APISIX仍尝试连接http://127.0.0.1:2379而非http://etcd:2379？
2. docker-compose.yml或config.yaml配置是否存在问题？
3. 还需执行哪些操作确保APISIX能连接etcd？

解决方案 #

1. 排查配置文件是否生效 #

APISIX日志显示连接127.0.0.1:2379，大概率是挂载的config.yaml未生效，APISIX读取了默认配置。执行以下命令验证容器内的配置：

docker exec -it <你的APISIX容器名称> cat /usr/local/apisix/conf/config.yaml

如果输出的etcd.host不是http://etcd:2379，说明挂载失败：

• 检查本地./apisix_conf/config.yaml路径是否正确，确保该文件存在于docker-compose.yml所在目录的apisix_conf子文件夹中
• 检查挂载权限，确保容器有读取该文件的权限

2. 修复启动顺序问题 #

depends_on仅保证容器启动顺序，不等待etcd完全就绪。给etcd添加健康检查，并让APISIX等待etcd健康后再启动：

修改docker-compose.yml中的etcd服务，添加健康检查：

etcd:
  # 原有配置不变
  healthcheck:
    test: ["CMD", "etcdctl", "endpoint", "health"]
    interval: 5s
    timeout: 5s
    retries: 5

修改APISIX服务的depends_on配置：

apisix:
  # 原有配置不变
  depends_on:
    etcd:
      condition: service_healthy

3. 清理并重新部署 #

清理旧容器、卷和缓存，重新启动服务：

docker-compose down -v
docker-compose up -d

4. 验证结果 #

查看APISIX启动日志，确认是否成功连接etcd：

docker logs <你的APISIX容器名称>

如果日志中出现etcd: init success或类似信息，说明连接成功。同时可以通过APISIX admin接口验证：

curl http://127.0.0.1:9180/apisix/admin/services -H 'X-API-KEY: admin123'

返回正常JSON响应则表示部署成功。

内容的提问来源于stack exchange，提问作者user3090303