无法从主机连接Docker Compose部署的FastAPI服务问题排查

核心问题 #

从FastAPI容器的启动日志里能看到关键问题：

fast-api-1  | INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

Uvicorn绑定了容器内部的127.0.0.1，这意味着服务只能在容器自身内部访问，即便Docker做了8000:8000的端口映射，外部（包括虚拟机主机、Windows主机）也无法连接。

解决方案 #

修改FastAPI的启动命令，让Uvicorn监听容器的所有网络接口（0.0.0.0），有两种实现方式：

1. 修改Docker镜像的启动命令 #

如果你是自行构建的api_rest镜像，在Dockerfile中更新启动命令：

CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

重新构建镜像后再用Compose启动即可。

2. 在docker-compose.yml中覆盖启动命令 #

无需重新构建镜像，直接在api服务中添加command字段：

services:
  db:
    image: postgres
    environment:
      POSTGRES_USER: my-user
      POSTGRES_PASSWORD: password
    ports:
      - '5432:5432'
    volumes:
      - /var/lib/postgresql/data:/var/lib/postgresql/data

  api:
    image: api_rest
    command: uvicorn main:app --host 0.0.0.0 --port 8000
    ports:
      - 8000:8000
    # 移除无用的extra_hosts配置
    # extra_hosts:
    #   - "host.docker.internal:host-gateway"

注意：将main:app替换为你实际的FastAPI应用入口（比如主文件是app.py，则改为app:app）。

额外说明 #

• extra_hosts的作用：该配置是把host.docker.internal域名映射到宿主机网关IP，用于容器访问宿主机上的服务，你这里FastAPI连接的是Compose内部的PostgreSQL，完全用不上，可直接移除。
• 访问地址：由于你在Windows上的Ubuntu虚拟机中运行Docker，访问时需使用Ubuntu虚拟机的IP地址加8000端口（例如http://192.168.x.x:8000/docs）；若虚拟机已配置端口转发到Windows，也可使用Windows的127.0.0.1:8000访问，但前提是FastAPI容器的监听地址已改为0.0.0.0。
• 数据库连接：日志显示Connecting to database using postgresql+psycopg2://my-user:password@db:5432/postgres，说明服务间网络连接正常，数据库部分无问题。

内容的提问来源于stack exchange，提问作者J Agustin Barrachina