解决Docker环境下Next.js和FastAPI的跨容器通信问题
在开发使用Docker容器化的全栈应用时，我们经常会遇到前后端通信的问题。本文记录了我们在使用Next.js作为前端，FastAPI作为后端的项目中遇到的一个棘手问题，以及最终的解决方案。
问题背景
我们的应用架构如下：
- 前端：Next.js应用，运行在一个Docker容器中
- 后端：FastAPI应用，运行在另一个Docker容器中
- 两个容器通过Docker网络进行通信
初始问题
我们在Next.js的rewrites配置中使用了NEXT_PUBLIC_API_URL环境变量来设置API请求的目标地址。然而，我们发现这个环境变量在Docker容器运行时没有生效。
原因
Next.js在构建时会"烘焙"环境变量，这意味着在运行时设置的环境变量不会被使用。这是Next.js的一个特性，旨在提高性能和安全性。
第一次修复尝试（这个配置最终解决问题需要）
为了解决这个问题，我们在前端Dockerfile中添加了环境变量：
ENV NEXT_PUBLIC_API_URL=http://backend:8000/api
结果
这个修改使得前端项目能够找到后端容器的地址，但是URL的解析出现了问题：
- 错误URL：
http://backend:8000/api?path=stations - 期望URL：
http://backend:8000/api/stations
第二次修复尝试（这个配置最终解决问题也需要）
我们修改了Next.js的配置：
{async rewrites() {const apiUrl = process.env.NEXT_PUBLIC_API_URL;return [{source: '/api/:path*',destination: apiUrl ? `${apiUrl}/:path*` : 'http://localhost:8000/api/:path*',},];},
}
目前这个配置完美，兼容了本地开发和docker部署。
结果
这次修改使得后端成功接收到了正确格式的URL，但是出现了新的问题：后端返回307临时重定向响应。
最终解决方案
经过多次尝试和深入分析，我们发现问题的根源在于Docker网络环境下的主机名处理。最终，我们通过在FastAPI应用中添加一个自定义中间件解决了这个问题：
@app.middleware("http")
async def handle_host(request: Request, call_next):if request.headers.get("host") == "backend:8000":request.scope["headers"] = [(b"host", b"localhost:8000") if k == b"host" else (k, v) for k, v in request.scope["headers"]]request.scope["server"] = ("localhost", 8000)response = await call_next(request)return response
当然第一次和第二次排查问题时候的内容也要加上
原理解释
这个中间件的作用是：
- 检测请求的host头是否为"backend:8000"（Docker网络中的主机名）
- 如果是，则将host头修改为"localhost:8000"
- 同时修改request.scope中的server信息
- 这样，后续的请求处理逻辑就会认为请求是发往localhost的，避免了重定向和其他不一致性问题
经验总结
-
环境变量处理：在使用Next.js时，要注意环境变量的"烘焙"机制。对于需要在运行时动态设置的值，考虑使用运行时配置或服务端API。
-
Docker网络通信：在Docker环境中，容器间通信使用容器名作为主机名，但应用可能期望使用localhost。要注意处理这种差异。
-
中间件的强大作用：合理使用中间件可以优雅地解决很多看似复杂的问题，而无需修改核心业务逻辑。
-
问题诊断：在解决复杂问题时，逐步缩小问题范围，并且不要忽视看似微小的细节（如主机名差异）是非常重要的。
-
跨容器通信：在设计跨容器通信的应用时，要充分考虑网络配置、主机名解析等因素。
结论
通过这次问题的解决，我们不仅修复了当前的通信问题，还深入理解了Docker网络、Next.js的环境变量处理机制以及FastAPI的中间件功能。这些知识和经验将在未来的项目开发中发挥重要作用。
记住，在处理复杂的系统集成问题时，耐心和系统的调试方法是关键。有时候，问题的解决方案可能出人意料的简单，关键是要找到问题的根源。
一点思考
-
我后端配置了allow_origins=[“*”]，这理论上应该允许来自任何主机名的请求。然而，CORS 主要处理的是浏览器端的安全策略，而不是服务器端的主机名验证。而我docker中前端访问后端，不是浏览器访问，所以不生效。
-
但其实最终我还是有一事不明， 我应该在FastApi的代码中进行什么配置才能阻止307重定向呢？
app = FastAPI(redirect_slashes=False)
这样就可以限制307重定向了，但限制后，像这样的端点就会访问不到：
@router.get("/stations/", response_model=list[Station])
最终结论，如果你不想改端点最后的斜杠，那就需要添加最终解决方案部分的代码。如果你愿意改，那就可以使用redirect_slashes=False。