解决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

当然第一次和第二次排查问题时候的内容也要加上

原理解释

这个中间件的作用是：

1. 检测请求的host头是否为"backend:8000"（Docker网络中的主机名）
2. 如果是，则将host头修改为"localhost:8000"
3. 同时修改request.scope中的server信息
4. 这样，后续的请求处理逻辑就会认为请求是发往localhost的，避免了重定向和其他不一致性问题

经验总结

1. 环境变量处理：在使用Next.js时，要注意环境变量的"烘焙"机制。对于需要在运行时动态设置的值，考虑使用运行时配置或服务端API。

2. Docker网络通信：在Docker环境中，容器间通信使用容器名作为主机名，但应用可能期望使用localhost。要注意处理这种差异。

3. 中间件的强大作用：合理使用中间件可以优雅地解决很多看似复杂的问题，而无需修改核心业务逻辑。

4. 问题诊断：在解决复杂问题时，逐步缩小问题范围，并且不要忽视看似微小的细节（如主机名差异）是非常重要的。

5. 跨容器通信：在设计跨容器通信的应用时，要充分考虑网络配置、主机名解析等因素。

结论

通过这次问题的解决，我们不仅修复了当前的通信问题，还深入理解了Docker网络、Next.js的环境变量处理机制以及FastAPI的中间件功能。这些知识和经验将在未来的项目开发中发挥重要作用。

记住，在处理复杂的系统集成问题时，耐心和系统的调试方法是关键。有时候，问题的解决方案可能出人意料的简单，关键是要找到问题的根源。

一点思考

1. 我后端配置了allow_origins=[“*”]，这理论上应该允许来自任何主机名的请求。然而，CORS 主要处理的是浏览器端的安全策略，而不是服务器端的主机名验证。而我docker中前端访问后端，不是浏览器访问，所以不生效。

2. 但其实最终我还是有一事不明， 我应该在FastApi的代码中进行什么配置才能阻止307重定向呢？

app = FastAPI(redirect_slashes=False)

这样就可以限制307重定向了，但限制后，像这样的端点就会访问不到：

@router.get("/stations/", response_model=list[Station])

最终结论，如果你不想改端点最后的斜杠，那就需要添加最终解决方案部分的代码。如果你愿意改，那就可以使用redirect_slashes=False。