Docker容器中Uvicorn/FastAPI无法通过完整主机名连接的问题

问题描述 #

我在Docker容器中运行Uvicorn/FastAPI服务，容器外运行正常，但在容器内通过完整主机名my.hostname.domain.com访问时出现连接被拒绝的错误，仅通过localhost访问能正常工作。

我的main.py代码 #

import os
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
import routers.chat_router as chat_controller
import uvicorn

app = FastAPI(debug=True)

app.include_router(chat_controller.router)

origins = [
    "http://localhost:3000",
    "https://localhost:3000",
    "https://my.hostname.domain.com:3000"
]

app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

if __name__ == "__main__":
    host = "0.0.0.0"
    uvicorn.run("main:app", host=host, port=8000, log_level="debug",
                ssl_keyfile="privateKey2.key", ssl_certfile="certificate2.crt")

我的Dockerfile代码 #

FROM python:3.10

# set a directory for the app
WORKDIR /usr/src/app

# copy all the files to the container
COPY . .

# install dependencies
RUN pip install --no-cache-dir -r requirements.txt

RUN pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

# define the port number the container should expose
EXPOSE 8000

# run the command
CMD ["python", "main.py"]

原因分析与解决方案 #

1. 容器内主机名解析失败 #

容器内部的DNS默认可能无法正确解析my.hostname.domain.com，导致请求无法路由到服务端口。

• 排查：进入容器执行nslookup my.hostname.domain.com，查看是否能解析到正确IP。
• 解决：运行容器时手动添加主机映射，让容器内部能解析该主机名到服务绑定的地址：

  docker run --add-host my.hostname.domain.com:0.0.0.0 -p 8000:8000 <你的镜像名>
  

  或者如果主机名指向宿主机，替换0.0.0.0为宿主机的实际IP。

2. 端口映射与网络配置错误 #

如果运行容器时没有正确映射端口，容器外的主机名请求无法进入容器内部。

• 解决：确保运行容器时添加端口映射参数，将容器的8000端口映射到宿主机的对应端口：

  docker run -p 8000:8000 <你的镜像名>
  

  若在容器内访问宿主机的服务，可使用Docker内置的host.docker.internal（适用于Docker Desktop）代替自定义主机名：https://host.docker.internal:8000。

3. SSL协议与证书问题 #

你的Uvicorn服务启用了SSL，访问时必须使用https协议，若误用http会直接被拒绝。

• 排查：确认访问时使用的是https://my.hostname.domain.com:8000，而非http开头的地址。
• 验证证书：进入容器检查证书文件是否存在且路径正确：

  docker exec -it <容器ID> ls -l /usr/src/app
  

  确保privateKey2.key和certificate2.crt文件存在。

4. 确认Uvicorn监听地址 #

虽然代码中已设置host="0.0.0.0"，但仍需验证服务是否确实监听所有网卡：

• 排查：进入容器执行netstat -tulpn（需先安装net-tools：apt update && apt install net-tools），查看输出中是否有0.0.0.0:8000或:::8000的监听记录，确认服务未局限于localhost。

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