新版Docker Compose部署Couchbase集群无法连接localhost:8091

问题现象 #

使用Docker Compose在M1芯片macOS上部署3节点Couchbase集群：

• 无版本声明的旧版Compose格式配置可正常启动，能正常访问localhost:8091控制台
• 切换为3.5版本带自定义网络的配置后，集群启动后无法访问localhost:8091

可正常运行的旧版配置 #

couchbase1:
  image: couchbase/server:community-aarch64
  volumes:
    - ~/couchbase/node1:/opt/couchbase/var
couchbase2:
  image: couchbase/server:community-aarch64
  volumes:
    - ~/couchbase/node2:/opt/couchbase/var
couchbase3:
  image: couchbase/server:community-aarch64
  volumes:
    - ~/couchbase/node3:/opt/couchbase/var
  ports:
    - 8091-8097:8091-8097
    - 9140:9140
    - 11207:11207 
    - 18091-18097:18091-18097
    - 11210:11210

无法正常运行的新版配置 #

version: '3.5'

services:
  couchbase1:
    image: couchbase/server:community-aarch64
    volumes:
      - ~/couchbase/node1:/opt/couchbase/var
    networks:
    - proxynet
  couchbase2:
    image: couchbase/server:community-aarch64
    volumes:
      - ~/couchbase/node2:/opt/couchbase/var
    networks:
    - proxynet
  couchbase3:
    image: couchbase/server:community-aarch64
    volumes:
      - ~/couchbase/node3:/opt/couchbase/var
    ports:
      - 8091-8097:8091-8097
      - 9140:9140
      - 11207:11207 
      - 18091-18097:18091-18097
      - 11210:11210
    networks:
      - proxynet
networks:
  proxynet:
    name: custom_network

故障原因 #

• 切换配置前未清理旧版启动的遗留容器和持久化数据：旧版配置的容器运行在docker0默认网桥上，持久化目录中存储的集群配置记录了旧网段的节点IP，切换到自定义网络后容器IP段变更，Couchbase加载旧集群配置失败，无法正常启动服务，因此不会监听8091端口。
• 自定义网络未显式指定驱动：部分M1芯片macOS的Docker Desktop版本，对未指定驱动的自定义网络会出现驱动识别异常，可能默认加载overlay驱动，导致容器网络栈初始化失败，服务无法正常对外暴露端口。
• 未给Couchbase节点配置固定主机名：Couchbase节点间通信依赖稳定的主机名解析，自定义网络内未配置固定hostname时，容器重启后主机名解析可能出现异常，触发服务启动失败。

修复方案 #

1. 清理遗留资源
   先执行命令停止删除所有相关Couchbase容器，如果不需要保留历史测试数据，清空持久化目录：

docker rm -f $(docker ps -a | grep couchbase | awk '{print $1}')
# 有需要保留的数据请提前备份目录
rm -rf ~/couchbase/node*/*

2. 修正Compose配置
   补全网络驱动声明，为每个节点配置固定hostname，端口映射值添加引号避免YAML格式解析异常，修正后配置如下：

version: '3.5'

services:
  couchbase1:
    image: couchbase/server:community-aarch64
    hostname: couchbase1
    volumes:
      - ~/couchbase/node1:/opt/couchbase/var
    networks:
      - proxynet
  couchbase2:
    image: couchbase/server:community-aarch64
    hostname: couchbase2
    volumes:
      - ~/couchbase/node2:/opt/couchbase/var
    networks:
      - proxynet
  couchbase3:
    image: couchbase/server:community-aarch64
    hostname: couchbase3
    volumes:
      - ~/couchbase/node3:/opt/couchbase/var
    ports:
      - "8091-8097:8091-8097"
      - "9140:9140"
      - "11207:11207"
      - "18091-18097:18091-18097"
      - "11210:11210"
    networks:
      - proxynet
networks:
  proxynet:
    name: custom_network
    driver: bridge

3. 重新启动集群
   在配置文件所在目录执行启动命令，等待40-60秒待Couchbase完成初始化后，即可正常访问localhost:8091打开管理控制台：

docker compose up -d

验证注意事项 #

• 启动后先执行docker ps确认couchbase3容器状态为Up，如果状态为Exited，执行docker logs couchbase3查看具体启动报错。
• 初始化集群添加节点时，直接使用配置的couchbase1、couchbase2作为节点地址即可，自定义bridge网络内置DNS会自动解析到对应容器IP，不需要手动指定容器IP。

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