本地跑得再顺,第一次上线还是会遇到一批「不是代码问题」的问题。最常见的三个:改了 appsettings.Production.json,线上行为一点没变;服务起来了,健康检查返回 200,但业务接口全部 500;容器里进程是 root,日志时间比本地差八个小时。这三个问题在本地都不会出现,因为本地有 launchSettings、有开发环境的详细日志、有时区正确的宿主机。

这篇按上线前必须确认的顺序走一遍:配置从哪读、优先级谁高;日志怎么写成能检索的结构;健康检查为什么要把「活着」和「能干活」分开;Kestrel 的超时和体积上限、反向代理后面拿不到真实地址怎么办;容器里为什么不能 root。第 1 篇那个端口被 launchSettings 抢走的坑,这里也一起收尾。

所有命令和接口返回都来自本机 Windows 11、.NET SDK 8.0.427、Kestrel 的实测。发布产物的体积、IIS 和容器的实际部署、自包含发布的效果没有跑过,会逐条标出来。

先收尾:端口到底听谁的

第 1 篇留下的现象再复述一次:设了 ASPNETCORE_URLS,dotnet run 仍然打印 Now listening on: http://localhost:5050。原因是 dotnet run 默认会读 Properties/launchSettings.json,把里面的 applicationUrl 当成环境变量注入,而且这份注入发生在你手动设的环境变量之后,所以它赢了。

三种解法,按场景选:

开发时想换端口直接改 launchSettings.json 里的 applicationUrl,这是它的本职工作,改完 dotnet run 就按新端口。
不想要这份配置加 --no-launch-profile,dotnet run 不再读它,此时 --urls 或环境变量才生效。
上线时根本不存在发布产物里没有 launchSettings.json,线上读的是环境变量或命令行参数。所以「本地端口对、线上不对」通常不是同一套配置在起作用。

项目本身没有新增依赖,csproj 还是 Web SDK 加 net8.0:

<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
  </PropertyGroup>
</Project>

上线相关的配置文件都在项目根目录,其中一个不会进产物:

appsettings.json所有环境共享的默认配置,会进产物
appsettings.Production.json生产覆盖,必须确认它也在产物里
Properties/launchSettings.json只在 dotnet run 时生效,发布时不带走

验证过的启动命令是这样,日志里的监听地址和参数一致:

dotnet run --no-launch-profile --urls "http://127.0.0.1:18082"

info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://127.0.0.1:18082
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Development

注意最后一行:Hosting environment: Development。这是开发态的标志,也意味着详细错误页是打开的。上线前必须让这一行变成 Production,否则任何异常都会把堆栈、源码路径、甚至连接串的一部分暴露给调用方。

环境名不只影响错误页。它决定读哪个 appsettings.环境.json、决定日志的默认级别、决定是否启用开发专用的中间件。把它当成一个总开关,而不是一个随便填的字符串,就知道为什么上线前要专门确认这一行。

配置源有顺序,别猜谁生效

ASP.NET Core 的配置不是一个文件,而是一串按顺序叠加的来源。后面的覆盖前面的,同名的键以最后读到的为准。默认顺序从低到高是:

配置的覆盖顺序,越靠后优先级越高
appsettings.json所有环境共享的默认值
appsettings.环境.json按当前环境覆盖,如 Production
环境变量部署平台注入,键名用双下划线分层
命令行参数最高优先级,临时调试用

环境变量里嵌套的键要写成双下划线,比如配置里的 Auth:Key 对应环境变量 Auth__Key。这一点经常写错:写成 Auth:Key,冒号在某些 shell 里不合法,或者被当成别的意思,读出来就是空值,然后程序用了一个默认密钥,线上就出现「重启后令牌全失效」。

还有一个高频坑:appsettings.Production.json 没打进发布产物。项目文件默认会带上 appsettings 系列,但如果你自定义了输出目录、用了单文件发布、或者把它放在源码目录之外,它就可能不在结果里。判断方法不是看源码目录,而是去产物目录里找这个文件,或者启动时把配置里的某个值打出来确认。

var builder = WebApplication.CreateBuilder(args);

// 默认已经包含了 appsettings 与环境变量,这里只是把值读出来确认
var authKey = builder.Configuration["Auth:Key"];
var envName = builder.Environment.EnvironmentName;

打印配置值要小心。Auth:Key 这种密钥不能进日志,确认时只打印「有没有值」和长度,不要打印内容。配置排查的目标是确认来源,不是把秘密抄一遍。

环境名本身也来自配置,默认是 Production,dotnet run 通过 launchSettings 把它设成 Development。线上用环境变量 ASPNETCORE_ENVIRONMENT 指定,一般只会有 Development、Staging、Production 三个值。别把 Staging 当生产用,也别在 Production 里打开详细错误页。

配置读不到时的表现也很隐蔽:程序不报错,直接用默认值。默认值通常是为了本地方便写的,比如本地连接串、开发密钥。上线后如果环境变量没配对,服务会拿这些默认值去连一个不存在的库,报错信息又指向连接失败,很容易被误判成网络问题。所以启动时把「关键配置是否存在」打一行日志,是成本最低的保险。

日志:写给人看,也写给机器查

内置的 ILogger 够用,不需要为了「上生产」先引入一整套日志框架。关键不是库,而是写法:用占位符,不要把值拼进字符串。拼接会让日志变成一整段文本,后续没法按字段检索;占位符会保留成结构化字段,输出成 JSON 时能直接查。

// 差:拼成一整段,无法按 orderId 检索
_log.LogInformation("order " + orderId + " paid " + amount);

// 好:占位符会被保留成字段
_log.LogInformation("order {OrderId} paid {Amount}", orderId, amount);

输出格式按部署方式选。人在终端看,默认的文本格式最舒服;进日志平台,JSON 更好解析:

builder.Logging.ClearProviders();
builder.Logging.AddJsonConsole();

级别也要管。Information 能打出请求和关键业务事件,Debug 会多出参数值,生产环境开 Debug 既慢又可能泄露敏感数据。把默认级别定在 Information,需要排查的模块单独调高,比全局开 Debug 安全得多。

还有两个容易忽略的点。第一,日志要带请求标识,至少让同一次请求的几行能串起来,否则并发一高就分不清谁是谁。第二,异常要打完整堆栈,但不要把请求体整个打出来,那里面可能有密码和令牌。日志的价值在于「出事后能还原现场」,不是「记得越多越好」。

时区是上线后最常见的困惑之一。容器默认常用 UTC,日志时间戳会比本地早或晚几个小时,看日志的人容易误判「这个故障发生在凌晨」。统一做法是日志一律用 UTC,展示时再转本地时区;或者在容器里显式设 TZ。两种都可以,但团队要一致,不能一半 UTC 一半本地时间。

日志还要考虑落盘和轮转。直接输出到标准输出,由容器或系统服务收集,是最省事的做法;自己写文件就要处理按大小或按天切分,否则磁盘迟早被占满。不要在同一次请求里既写文件又打控制台,重复的日志只会让排查变乱。

健康检查:活着和能干活是两件事

第 1 篇的 /health 返回 200,响应头里有 Content-Type: application/json; charset=utf-8、Server: Kestrel、Transfer-Encoding: chunked。那是一个自定义的 JSON 端点,它能证明进程还在、能接请求,但不能证明数据库连得上。

上线后要把健康检查拆成两个。liveness(存活)只回答「进程要不要重启」,readiness(就绪)回答「能不能接流量」。两者混在一起会出大问题:数据库短暂抖动,liveness 跟着失败,编排系统把本来健康的进程重启了,重启后连不上库,陷入循环。

Liveness(存活)

只回答「进程还在不在」。检查永远返回健康,失败就重启实例。不要查数据库、不要查下游,避免依赖抖动引发重启风暴。

Readiness(就绪)

回答「现在能不能接流量」。查数据库、缓存和关键下游,失败就把实例从负载均衡里摘掉,但不重启它,等依赖恢复后自动回来。

using Microsoft.AspNetCore.Diagnostics.HealthChecks;

builder.Services.AddHealthChecks()
    .AddCheck("self", () => HealthCheckResult.Healthy())
    .AddDbContextCheck<AppDb>("db");

app.MapHealthChecks("/health/live", new HealthCheckOptions
{
    Predicate = _ => false
});

app.MapHealthChecks("/health/ready", new HealthCheckOptions
{
    Predicate = c => c.Name == "db"
});

liveness 用一个永远健康的检查,或者只查「进程能不能响应」;readiness 才去查数据库、缓存、下游依赖。这样数据库挂了,readiness 失败,负载均衡把流量摘走,但进程不会被杀,等数据库恢复它自己就回来了。

健康检查的返回也有讲究。默认的 MapHealthChecks 返回纯文本,很多网关需要 JSON,得自己写 ResponseWriter 定制。无论哪种格式,状态码要明确:健康 200,不健康 503。别用 200 加一个 "status":"down" 的字段,很多负载均衡只看状态码,会继续往坏实例送流量。

本机实测的是自定义的 /health JSON 端点,以及它的响应头。AddHealthChecks、AddDbContextCheck、MapHealthChecks 的实际输出没有在本机跑过,上面这段按框架用法写成,接入前请在自己项目里验证状态码和响应体。

健康检查还要注意别被滥用。它是一个高频、轻量的端点,不要在里面做重查询、不要每次全表扫描。检查数据库用一条 SELECT 1 或连接是否可打开就够了,查业务表数量既慢又容易误报。

两个端点的访问频率也不同。liveness 通常几秒一次,readiness 可以稍慢;如果把数据库检查挂在 liveness 上,每次探针都去连库,数据库压力会随实例数成倍增加。分开之后,这个成本只落在 readiness 上,而且可以按需调低频次。

探针的超时也要设,不能无限等。健康检查自己卡住,编排系统会认为实例失联,结果比不检查还糟。数据库检查尤其要设一个很短的超时,连不上就立刻报不健康,不要让它等默认的三十秒。

Kestrel、反向代理与容器

Kestrel 的 Limits 是资源上限,不是 QPS 限流。它能限制请求体大小、请求头超时、连接空闲时间,但管不了「每秒允许多少个请求」。后者要靠中间件或网关,别指望在 Kestrel 里配一个数字就完成限流。

builder.WebHost.ConfigureKestrel(o =>
{
    o.Limits.MaxRequestBodySize = 10 * 1024 * 1024;
    o.Limits.RequestHeadersTimeout = TimeSpan.FromSeconds(15);
    o.Limits.KeepAliveTimeout = TimeSpan.FromSeconds(60);
});

这几个值的取舍:请求体上限太小,正常上传会被 413 拒掉;太大,内存和带宽会被单个请求吃掉。请求头超时太长,慢连接攻击能长期占着连接;太短,网络差的正常用户会被误伤。默认值通常够用,改之前先想清楚「我在防什么」,不要为了「安全」把所有值调到极小。

反向代理后面,最常见的问题是日志里的客户端地址全是 127.0.0.1。因为请求是代理发来的,真实地址在 X-Forwarded-For 头里,框架默认不信任这个头。要显式启用并限定可信代理:

using Microsoft.AspNetCore.HttpOverrides;

app.UseForwardedHeaders(new ForwardedHeadersOptions
{
    ForwardedHeaders = ForwardedHeaders.XForwardedFor
        | ForwardedHeaders.XForwardedProto
});

启用之后还有一层安全考虑:只信任来自代理网段的头,否则客户端可以自己伪造 X-Forwarded-For,把日志和限流全部带偏。框架的 KnownProxies 和 KnownNetworks 就是干这个的,配置成代理的实际地址。

容器里有两件事必须做。第一,别用 root 运行,Dockerfile 里创建一个普通用户并 USER 切过去,这样即使应用被攻破,攻击者拿到的权限也有限。第二,把监听地址设成 0.0.0.0,否则容器外访问不到;同时只暴露必要的端口。这两条和 Kestrel 本身无关,但配错了表现都是「服务起不来」。

还有一个部署细节是用户和文件权限。以非 root 运行时,应用对工作目录、日志目录、证书目录通常只有读权限,需要写的地方要显式授权。很多「本地好好的、容器里启动就报权限不足」都是这一步漏了。

Kestrel 直接对外还是放在 nginx 后面,第 1 篇给过判断:内网、单实例、量不大,直接对外加防火墙就够了;公网、多实例、需要 TLS 终止和限流,就放代理。放代理时 Kestrel 只监听本机地址,公网端口由代理接,别忘了上面的 ForwardedHeaders。

容器还要注意基础镜像的选择。运行时镜像和 SDK 镜像体积差很多,上线只用运行时镜像,构建阶段才用 SDK。多阶段构建能把编译工具留在构建层,最终镜像里只有运行时和应用,攻击面小很多。

上线前把 ASPNETCORE_ENVIRONMENT 明确设成 Production,并在产物目录里确认 appsettings.Production.json 存在。这两件事漏一件,要么泄露内部错误信息,要么配置根本没生效。它们都不会在本地暴露,因为本地用的是 launchSettings 加 Development。

上线前后,按这张表对一遍

下面这些现象有一个共同点:本地都不出现。上线前逐条确认,比出事后再查便宜得多:

现象真实原因第一步查什么
改线上配置,行为一点没变文件没打进产物,或被更高优先级的环境变量覆盖产物目录里找文件,启动时打印配置值的来源
健康检查 200,但业务接口全 500检查只看了进程,没查数据库readiness 里有没有数据库检查
启动日志显示 Development环境变量没设,或设在了错误的启动脚本里看进程实际读到的 ASPNETCORE_ENVIRONMENT
日志里客户端地址全是 127.0.0.1反向代理后面没启用 ForwardedHeaders查 UseForwardedHeaders 与可信代理配置
日志时间与本地差几个小时容器默认 UTC,或宿主机时区不同查容器 TZ 与日志时间格式,统一用 UTC
正常上传被 413 拒绝Kestrel 的请求体上限小于实际文件查 MaxRequestBodySize 与代理的 body 限制
容器里进程以 root 运行Dockerfile 没建普通用户,也没切 USER查 Dockerfile 最后的 USER 指令
发布后启动报缺运行时框架依赖模式,目标机没装对应版本目标机执行 dotnet --list-runtimes

表里第一条最隐蔽,因为「改了没生效」和「代码没读到」表现一样。排查时不要反复改文件,先确认文件在不在产物里,再确认有没有更高优先级的来源把它覆盖了。启动时把关键配置的值和来源打一行日志,能省掉后面无数次猜测。

最后一条涉及发布模式的选择。框架依赖模式只打自己的代码,目标机要有对应运行时;自包含模式把运行时一起打进去,目标机不用装,但产物大很多。自家服务器能统一装运行时,用前者;交付给环境不可控的客户,用后者。本机没有实测 dotnet publish 的产物大小和自包含发布的效果,这里不给具体数字。

清单还可以再加两项:确认监听地址,以及确认进程管理器。监听地址要区分「容器内监听」和「对外暴露」,容器里必须监听 0.0.0.0 才对;Kestrel 本身不做守护,进程退出不会自动重启,要交给系统服务或容器编排。这是上线和本地调试最大的区别之一,也是「半夜挂了没人知道」的常见原因。

最后还有一项常被漏掉的确认:备份与回滚。上线前要确认数据库有可恢复的备份,确认上一版产物还在、能快速切回。配置和代码的回滚路径要分开想,配置改坏了用环境变量回退,代码改坏了用旧产物;两者混在一起,出事时容易手忙脚乱。

上线前能自验的五个练习

这些练习都能在本机模拟,不需要真实服务器:

  1. 用 dotnet run 和一个自定义端口启动,确认 launchSettings 覆盖了它;再加上 --no-launch-profile,确认端口按你的参数走。
  2. 把 ASPNETCORE_ENVIRONMENT 设成 Production,启动后确认日志里的环境名变了,再访问一个会抛异常的路由,对比错误页的变化。
  3. 把 Auth:Key 从 appsettings 里删掉,改用环境变量 Auth__Key 提供,启动后打印「有没有值」,确认双下划线写法被读到。
  4. 给 /health 加一个会失败的数据库检查,观察状态码从 200 变成 503;再把 liveness 与 readiness 拆开,确认 liveness 仍然是 200。
  5. 把 MaxRequestBodySize 改成 1KB,发一个稍大的请求体,记录 413 的响应;再改回去,确认恢复正常。

小结

这一组六篇到这里结束。从空目录到能上线的服务,主线其实只有几条:请求怎么进来、路由怎么匹配、数据怎么存、身份怎么确认、慢活怎么挪出去、上线前确认什么。建议把第 1 篇的项目按顺序重跑一遍,每一篇加的东西都叠在同一个项目上,这样六篇的因果关系才是连着的。想补 C# 本身的语法和类型,可以回到 C# 语法与类型,那边的规则正好解释这里很多「为什么这么写」。

这篇的三句话总结:第一,配置是有顺序的,环境变量和命令行覆盖文件,launchSettings 只在 dotnet run 时插一脚,上线前确认产物里有 appsettings.Production.json 并把环境设成 Production;第二,健康检查要分 liveness 和 readiness,后者必须查数据库这类真实依赖,状态码用 200 和 503 表达;第三,Kestrel 的 Limits 管的是资源上限不是 QPS,反向代理后面要启用 ForwardedHeaders 并限定可信来源,容器里别用 root。