Docker-Compose部署FastAPI遭遇404错误求助

问题背景 #

已通过Docker-Compose在带静态IP的远程服务器部署三个容器：postgres、pgadmin、fastapi，所有容器均启动成功。pgadmin可通过IP:8080正常访问，但访问IP:5000时出现404 page not found错误，期望能访问routes.user.py中定义的根路由及其他路由。

排查步骤 #

1. 核对端口映射配置 #

检查docker-compose.yml中FastAPI服务的端口映射是否匹配容器内服务监听的端口：

• FastAPI默认用8000端口，若容器内未修改，配置应类似：

services:
  fastapi:
    # 其他配置...
    ports:
      - "5000:8000"  # 宿主机5000端口映射到容器内8000端口

• 若你修改了容器内监听端口（比如改成5000），则映射应为"5000:5000"。

2. 验证路由注册逻辑 #

确认项目主文件（通常是main.py）已正确导入并注册routes.user.py中的路由：

from fastapi import FastAPI
from routes.user import router as user_router

app = FastAPI()

# 必须注册用户路由
app.include_router(user_router)

如果routes.user.py的根路由是通过router.get("/")定义的，需确保上述注册代码存在，否则路由不会被加载。

3. 查看容器启动日志 #

执行以下命令查看FastAPI容器的运行日志，排查启动或路由加载异常：

docker-compose logs fastapi

正常日志应包含Uvicorn running on http://0.0.0.0:xxxx（xxxx为容器内监听端口），若有路由导入失败、语法错误等问题，会在此处显示。

4. 测试容器内服务可用性 #

进入FastAPI容器内部，直接访问服务端口验证是否正常：

docker-compose exec fastapi curl localhost:8000  # 替换为容器内实际监听端口

• 若容器内访问正常但外部报错：排查服务器防火墙/安全组是否开放5000端口，或端口映射是否配置错误。
• 若容器内访问也报404：说明FastAPI应用本身路由配置存在问题，需检查routes.user.py的路由定义是否正确。

5. 检查Dockerfile启动命令 #

如果使用自定义Dockerfile，确认启动命令指定了正确的模块、应用对象和端口：

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

需保证main:app对应你的项目主模块和FastAPI实例，端口与docker-compose.yml中的容器端口一致。

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