Docker部署FastAPI后无法访问API文档问题咨询

不需要额外新增独立Docker容器承载API文档，访问失败是配置不匹配导致的，按以下步骤排查修正即可：

核心配置错误点 #

• 端口映射规则和服务实际监听端口不匹配：你的docker-compose.yml中api服务的端口配置为8020:80，含义是将宿主机8020端口映射到api容器内部的80端口，但你在api服务的Dockerfile中，启动uvicorn时指定的监听端口是8020，容器内80端口没有任何服务监听，端口映射规则完全失效。
• 访问路径对应的服务错误：你访问localhost/docs时，流量会直接打到映射到80端口的web（ui）服务上，如果你没有在web服务的反向代理规则中配置docs相关路径的转发，请求根本不会到达FastAPI服务，自然无法打开文档。

修复方案 #

快速验证方案（直接访问api服务端口） #

1. 修改api服务对应的Dockerfile，将启动命令中的端口改为和容器内映射端口一致的80：

FROM python:3.9

COPY requirements.txt /app/

RUN pip install -r /app/requirements.txt
COPY ./ /app
WORKDIR /app
CMD ["uvicorn", "api:app", "--host", "0.0.0.0", "--port", "80"]

2. 重新执行docker-compose up --build构建启动服务
3. 直接访问http://localhost:8020/docs即可正常打开API文档

生产环境方案（通过80端口web服务统一访问） #

如果需要直接通过http://localhost/docs（不带8020端口）访问文档，在完成上述端口修正的基础上，给web服务（一般是Nginx等反向代理）添加路径转发规则，将以下和文档相关的路径全部转发到http://api:80即可：

• /docs
• /redoc
• /openapi.json
• /docs/oauth2-redirect（使用OAuth2授权场景需要配置）

Nginx配置参考：

location ~ ^/(docs|redoc|openapi.json|docs/oauth2-redirect) {
    proxy_pass http://api:80;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}

配置完成后重启web服务，即可通过80端口正常访问API文档。

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