.NET 9 API在Docker中运行时OpenAPI地址异常致UI请求失败

问题原因 #

Docker容器内的Kestrel默认绑定[::]:8080（IPv6任意地址），OpenAPI文档生成时会直接使用这个监听地址。外部客户端（如Swagger UI/Scalar）运行在宿主机，无法通过容器内部的[::]:8080访问API，导致请求失败；而宿主机的localhost:8080能正常访问，是因为Docker完成了端口映射。

解决方案 #

方法1：配置ForwardedHeaders识别外部真实地址 #

在Program.cs中添加ForwardedHeaders配置，让应用正确识别外部请求的地址：

var builder = WebApplication.CreateBuilder(args);

// 配置ForwardedHeaders
builder.Services.Configure<ForwardedHeadersOptions>(options =>
{
    options.ForwardedHeaders = Microsoft.AspNetCore.HttpOverrides.ForwardedHeaders.XForwardedFor | Microsoft.AspNetCore.HttpOverrides.ForwardedHeaders.XForwardedProto;
    // 允许Docker网关地址作为代理
    options.KnownProxies.Add(IPAddress.Parse("172.17.0.1"));
});

// 其他服务注册...

var app = builder.Build();

// 启用ForwardedHeaders中间件（需放在其他中间件之前）
app.UseForwardedHeaders();

// 其他中间件配置（如Swagger、路由等）...

启动容器时添加环境变量：

docker run -p 8080:8080 -e ASPNETCORE_FORWARDEDHEADERS_ENABLED=true your-image-name

方法2：手动指定OpenAPI服务器地址 #

在Swagger配置中直接添加外部可访问的服务器地址，覆盖自动生成的容器内部地址：

builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "你的API名称", Version = "v1" });
    // 手动添加宿主机可访问的服务器地址
    c.AddServer(new OpenApiServer { Url = "http://localhost:8080" });
});

方法3：修改Kestrel绑定地址 #

在Dockerfile的final阶段添加环境变量，指定Kestrel绑定IPv4任意地址：

FROM base AS final
WORKDIR /app
COPY --from=publish /app/publish .
ENV ASPNETCORE_URLS=http://0.0.0.0:8080
ENTRYPOINT ["dotnet", "Scientometrics.Api.v3.dll"]

验证 #

重新构建镜像并启动容器，访问openapi/v1.json查看servers字段，确认地址已变为http://localhost:8080，此时Swagger UI/Scalar即可正常发起API请求。

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