Docker中FastAPI挂载静态HTML页面无法访问的问题求助

一、先确认容器内FastAPI服务的可达性 #

你在容器内用localhost访问失败，先换0.0.0.0测试：

python3 -c "import urllib.request as r; print(r.urlopen('http://0.0.0.0:8000/qgis/static/index.html').read().decode())"

如果还是连接拒绝：

1. 检查容器内是否有uvicorn进程：ps aux | grep uvicorn，确认服务是否正常启动
2. 确认启动命令是否指定了--host 0.0.0.0，比如Dockerfile的CMD应该是：

   uvicorn main:app --host 0.0.0.0 --port 8000
   

   只写uvicorn main:app会默认监听127.0.0.1，容器外部（包括nginx）能访问但容器内localhost可能解析异常。

二、验证静态文件路径一致性 #

1. 检查Dockerfile的工作目录配置：
   确保WORKDIR和代码复制路径与volume挂载匹配。比如Dockerfile如果是：

   WORKDIR /app
   COPY . .
   

   那么FastAPI中StaticFiles(directory="static")指向的是/app/static，和docker-compose里的./static:/app/static挂载路径一致。如果WORKDIR设为/api，则需要把volume改成./static:/api/static。
2. 进入容器后执行ls -l /app/static（根据WORKDIR调整路径），确认index.html存在且权限正常（比如不是root只读，FastAPI进程有权限读取）。

三、排查FastAPI静态文件挂载逻辑 #

当前root_path="/qgis"和app.mount("/static", ...)的配置是正确的，访问路径/qgis/static/index.html逻辑上没问题。如果容器内用0.0.0.0能访问到静态文件，但外部访问返回nginx的404，问题出在nginx反向代理配置。

四、修复nginx反向代理规则 #

返回nginx的404说明/qgis/static的请求没被转发到FastAPI容器，而是被nginx当作本地静态文件处理。需要修改nginx配置，将所有/qgis前缀的请求转发到FastAPI：

location /qgis {
    proxy_pass http://<你的FastAPI容器IP或服务名>:8000;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    # 如果你用到WebSocket，需加以下配置
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

注意：不要单独给/qgis/static设置location规则，否则会优先匹配该规则，导致请求不转发到FastAPI。

五、其他细节检查 #

• 强制刷新浏览器缓存（Ctrl+F5），避免旧缓存导致的404
• 修正docker-compose的网络拼写错误：当前services里用的是geonet_entw，但networks定义的是entw，统一成：

  services:
    api:
      ...
      networks:
        - geonet_entw
  networks:
    geonet_entw:
      external: true
  

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