Docker部署FastAPI+CouchDB启动时连接拒绝问题求助

你的问题核心是容器启动顺序与服务就绪状态不匹配：Docker Compose默认的depends_on仅等待目标容器启动，而非容器内的服务完全就绪。当FastAPI容器启动时，CouchDB容器虽已运行，但还在初始化用户和配置，此时发起连接必然被拒绝。

下面提供两种可靠的解决方案，可根据场景选择，甚至组合使用：

方案1：通过Docker Compose健康检查控制启动顺序 #

从容器编排层面解决问题，让FastAPI仅在CouchDB服务真正就绪后启动。

修改你的docker-compose.yml，更新couchdb和server服务配置：

version: "3.4"
networks:
  default:
    ipam:
      driver: default
      config:
        - subnet: 192.168.112.0/24
services:
  couchdb:
    restart: unless-stopped
    build:
      context: .
      dockerfile: compose/couchdb.Dockerfile
    expose:
      - 5984
    ports:
      - "59840:5984"
    env_file:
      - .env
    # 添加CouchDB健康检查，验证服务是否就绪
    healthcheck:
      test: ["CMD", "curl", "-f", "http://${COUCHDB_USER}:${COUCHDB_PASSWORD}@localhost:5984/_up"]
      interval: 5s          # 每5秒检查一次
      timeout: 5s           # 单次检查超时时间
      retries: 10           # 最多重试10次（总计等待50秒）
      start_period: 10s     # 启动后10秒再开始检查，给CouchDB初始化缓冲时间
  server:
    restart: unless-stopped
    build:
      context: .
      dockerfile: compose/server.Dockerfile
    expose:
      - 8080
    ports:
      - "8080:8080"
    env_file:
      - .env
    # 依赖CouchDB的健康状态，而非仅容器启动
    depends_on:
      couchdb:
        condition: service_healthy

关键说明 #

• /_up是CouchDB官方提供的健康检查端点，返回200表示服务完全就绪；
• start_period避免了CouchDB初始化管理员用户时的误判；
• service_healthy条件确保FastAPI容器仅在CouchDB健康检查通过后启动。

方案2：在FastAPI代码中添加连接重试逻辑 #

从应用层面做兜底，即使容器启动顺序有偏差，应用也会自动重试直到连接成功，更适合生产环境。

修改你的app.py，为数据库初始化添加重试逻辑：

import couchdb
from fastapi import FastAPI, HTTPException
import os
import time

def _load_db_client():
    _user = os.environ["COUCHDB_USER"]
    _password = os.environ["COUCHDB_PASSWORD"]
    _host = os.environ["COUCHDB_HOST"]
    _port = os.environ["COUCHDB_PORT"]
    
    max_retries = 10
    retry_count = 0
    while retry_count < max_retries:
        try:
            _client = couchdb.Server(f"http://{_user}:{_password}@{_host}:{_port}")
            # 主动验证连接有效性（获取服务器信息）
            _client.info()
            del _user, _password, _host, _port
            return _client
        except (ConnectionRefusedError, couchdb.ServerError) as e:
            retry_count += 1
            print(f"CouchDB连接失败，重试 {retry_count}/{max_retries}: {e}")
            time.sleep(2)
    raise Exception(f"经过{max_retries}次重试后仍无法连接CouchDB")

def _get_or_create_db(_client: couchdb.Server, db_name: str) -> couchdb.Database:
    if db_name in _client:
        return _client[db_name]
    print("创建数据库", db_name)
    return _client.create(db_name)

couch: couchdb.Server = _load_db_client()
db_user = _get_or_create_db(_client=couch, db_name="user")
app = FastAPI()

关键说明 #

• 捕获ConnectionRefusedError（连接被拒）和couchdb.ServerError（服务未就绪返回错误）两种异常；
• 每次重试间隔2秒，最多重试10次，足够覆盖CouchDB的初始化时间；
• 通过_client.info()验证连接的有效性，避免创建Server对象但服务未就绪的假成功情况。

推荐实践 #

生产环境建议同时使用两种方案：Docker Compose健康检查确保启动顺序合理，应用层重试作为兜底，应对网络波动或健康检查误判等突发情况。

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