FastAPI应用部署Cloud Run失败问题排查

一、容器未监听PORT环境变量导致启动失败 #

关键排查点与修复方案 #

• 强制监听所有网卡并动态读取PORT
  不管用uvicorn还是fastapi-cli启动，必须指定host="0.0.0.0"（不能用127.0.0.1，否则容器外部无法访问），同时动态读取Cloud Run提供的PORT环境变量：

  • uvicorn启动示例（server.py）：

    import os
    from fastapi import FastAPI
    
    app = FastAPI()
    
    @app.get("/")
    async def health_check():
        return {"status": "healthy"}
    
    if __name__ == "__main__":
        import uvicorn
        port = int(os.getenv("PORT", 8080))
        uvicorn.run("server:app", host="0.0.0.0", port=port, reload=False)
    

  • fastapi-cli启动的Dockerfile CMD指令：

    CMD ["fastapi", "run", "server.py", "--host", "0.0.0.0", "--port", "${PORT:-8080}"]
    

• 确保Dockerfile依赖完整
  镜像中必须安装所有运行依赖，比如在requirements.txt中包含fastapi、uvicorn（如果用uvicorn启动）或fastapi[all]（如果用fastapi-cli）。

• 添加健康检查路由
  Cloud Run默认访问/路径做健康检查，如果你的应用没有根路由，会导致健康检查失败，进而标记版本未就绪。添加上面示例中的/路由即可。

二、python-dotenv无法加载.env文件的问题 #

修复方案 #

• 确认.env文件路径正确
  根据代码位置调整加载路径：

  • 如果.env和server.py在同一目录：

    from dotenv import load_dotenv
    load_dotenv()  # 默认读取当前目录的.env
    

  • 如果server.py在app/目录，.env在项目根目录：

    from dotenv import load_dotenv
    import os
    load_dotenv(os.path.join(os.path.dirname(os.path.dirname(__file__)), ".env"))
    

• 确保.env被复制到Docker镜像
  在Dockerfile中添加复制指令：

  COPY .env .
  

  注意：如果.env包含敏感信息，不要提交到代码仓库，但必须确保构建镜像时能获取到该文件（比如通过构建参数或秘密管理器）。

• 添加日志验证加载状态
  在代码中添加日志输出，确认环境变量是否成功加载：

  import logging
  import os
  from dotenv import load_dotenv
  
  logging.basicConfig(level=logging.INFO)
  logger = logging.getLogger(__name__)
  
  load_dotenv()
  test_var = os.getenv("TEST_VAR")
  logger.info(f"TEST_VAR loaded: {test_var is not None}")
  

  这样可以在Cloud Run日志中直接查看加载结果，定位是否真的是加载失败。

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