部署到Openshift后Blazor服务端应用调用Refit接口出现500异常

算力阿峰

2026-10-2

问题根因分析

Refit接口声明错误：你提供的代码里PostMyEntityAsync方法错误标注了[Patch]特性而非[Post]，虽然本地Windows环境可能因为路由宽松或者调试配置兼容未触发问题，但部署到严格的路由规则环境下会出现匹配失败
路由拼接错误：如果你的API部署在子路径下，Refit的BaseUrl尾部未加斜杠，同时接口路由以/开头，会导致路由拼接时忽略BaseUrl的子路径部分，GET请求可能刚好命中默认路由，POST/PATCH则出现404或者500错误
Openshift路由/Ingress规则限制：多数K8s/Openshift的默认路由配置会限制非GET/HEAD请求的转发，或者配置了CSRF校验、请求体大小限制，导致POST/PATCH请求在到达API服务前就被网关拦截返回500
序列化行为差异：.NET 5使用的System.Text.Json在Linux和Windows环境下存在部分行为差异，比如日期格式化、特殊字符转义、大小写敏感规则，如果你的MyEntity类包含特殊类型字段（比如DateTime、非ASCII字符的字符串、嵌套对象），序列化失败会导致Refit直接抛出异常，请求未发出
Blazor服务端Circuit异常残留：Blazor服务端采用SignalR长连接维持用户会话，只要当前Circuit内存在未捕获的异常，后续所有操作（包括页面跳转）都会触发异常抛出，你看到的跳转报错大概率是之前提交操作的异常未被捕获导致的连带问题
容器时区/编码配置缺失：Linux容器默认缺少中文编码、时区配置，导致实体序列化时出现乱码或者格式错误，触发序列化失败

排查步骤

第一步：先修复Refit接口声明错误，将PostMyEntityAsync的特性改为[Post("/MyEntity/")]，重新打包测试
第二步：在Blazor服务端添加Refit请求日志，输出完整的请求地址、请求方法、请求体内容，确认请求是否正常发出：

// 注册Refit时添加日志处理
services.AddRefitClient<IMyEntityApi>()
        .ConfigureHttpClient(c => c.BaseAddress = new Uri(Configuration["ApiBaseUrl"]))
        .AddHttpMessageHandler(() => new LoggingHandler());

自定义LoggingHandler输出所有请求的完整信息，确认部署环境下POST/PATCH请求的方法、地址、请求体是否符合预期

第三步：排查Openshift路由配置，确认路由是否允许PATCH、POST方法，没有配置请求方法限制、WAF拦截规则，同时检查API服务的CORS配置是否允许Blazor应用的域名发起非GET请求
第四步：捕获Refit的完整异常内容，查看ApiException的Content、Headers属性，确认500错误返回的具体内容，判断错误是由网关、API服务还是Refit本地抛出：

try
{
    await _api.PostMyEntityAsync(entity);
}
catch (ApiException ex)
{
    // 输出异常详情到日志
    Console.WriteLine($"异常内容：{ex.Content}，状态码：{ex.StatusCode}，请求地址：{ex.Uri}");
}

第五步：验证Linux容器的序列化行为，本地启动Linux容器运行你的Blazor应用，模拟序列化MyEntity实体，确认是否有序列化异常抛出

解决方案

修复Refit接口的特性标注错误，确保请求方法和接口路由匹配；如果API部署在子路径下，要么BaseUrl尾部加斜杠，要么接口路由去掉开头的/，保证路由拼接正确
在Openshift路由配置中添加允许POST、PATCH方法的规则，关闭不必要的WAF拦截规则
显式配置Refit的序列化规则，统一Linux和Windows的序列化行为：

services.AddRefitClient<IMyEntityApi>(new RefitSettings
{
    ContentSerializer = new SystemTextJsonContentSerializer(new JsonSerializerOptions
    {
        PropertyNameCaseInsensitive = true,
        DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
        Encoder = JavaScriptEncoder.UnsafeRelaxedJsonEscaping
    })
})
.ConfigureHttpClient(c => c.BaseAddress = new Uri(Configuration["ApiBaseUrl"]));

在Blazor服务端添加全局异常捕获，避免Circuit被异常锁定：

// App.razor中添加ErrorBoundary
<ErrorBoundary>
    <ChildContent>
        <Router AppAssembly="@typeof(App).Assembly">
            <!-- 原有路由配置 -->
        </Router>
    </ChildContent>
    <ErrorContent>
        <p>操作出现异常，请刷新页面重试</p>
    </ErrorContent>
</ErrorBoundary>

给Linux容器添加中文编码和时区配置，在Dockerfile中加入以下配置：

RUN apt-get install -y tzdata locales && \
    locale-gen zh_CN.UTF-8 && \
    update-locale LANG=zh_CN.UTF-8
ENV TZ=Asia/Shanghai
ENV LANG=zh_CN.UTF-8
ENV LC_ALL=zh_CN.UTF-8

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