agilelabs-fx-docs main tasks/troubleshoot-startup-and-logging.md

排查启动、日志与诊断问题

本页用于服务启动失败、启动慢、日志不输出、运行期错误难定位时快速找到排查路径。先按顺序确认启动期日志、控制台输出、运行期日志，再使用诊断端点和 WorkContext/Activity 信息定位请求链路。

先看哪份日志

场景 优先查看 说明
进程刚启动就退出 Bootstrap Logger 的 bootlog Host、配置、DI 建立前后的异常会优先写在这里
控制台能看到错误但文件没有 控制台输出和 BoostrapLogPath 确认 bootlog 路径是否可写
服务已启动但接口报错 运行期 applog / ASP.NET Core Logging 请求进入应用后主要看常规 Logger
请求链路断裂或后台任务异常 WorkContext、Activity、业务日志 确认是否有 TraceId、SpanId、ContextId
发布后版本不对 /fwdev/ASSEMBLY_VERSIONS 或 /fwdiag/v 前者看加载程序集，后者看运行目录 version.txt

启动期 bootlog

AgileLabs WebApp 通过 AppBootstrapper.SafeStartAsync 包住宿主启动过程。Bootstrap Logger 会在 ASP.NET Core Host 和 DI 完全建立之前创建，因此适合定位早期启动错误。

默认行为：

  • bootlog 默认目录来自 AppData.GetPath("bootlog")。
  • 可通过 AppBuildOptions.BoostrapLogPath 覆盖目录。
  • 文件名形如 bootlog_{yyyyMMdd_HHmmss}_{MachineName}.txt。
  • 文件 Sink 使用滚动策略，保留数量为 10。
  • 控制台和 bootlog 都会使用包含 TraceId、SpanId 的输出模板。

示例配置：

await AgileLabApplication.StartApplicationAsync<DefaultMvcApplicationOptions>(options =>
{
    options.BoostrapLogPath = "D:/logs/my-service/bootlog";
    options.BootstrapLoggerConfiguration = logger =>
    {
        logger.WriteTo.Console();
    };
});

启动阶段如果抛出未处理异常，SafeStartAsync 会记录 Host terminated unexpectedly，并把完整异常类型、消息和堆栈写入 critical 日志。UnhandledException 和 UnobservedTaskException 也会进入 Bootstrap Logger。

运行期日志

运行期日志由 ASP.NET Core Logging 与 Serilog Provider 承接。默认 UseSerilogProvider = true，框架会注册 Serilog 到 Logging 架构。

常用配置点：

配置 用途
UseSerilogProvider 是否使用框架默认 Serilog Provider
ConfigureLoggingBuilder 扩展 ASP.NET Core ILoggingBuilder
ConfigureSerilogConfiguration 项目级 Serilog 配置入口
BootstrapLoggingLevelControl 控制 Bootstrap Logger 最小级别
LOG_MINI_LEVEL 通过环境变量覆盖最小日志级别
LOG_FILE 强制开启运行期文件日志
AG_APP_DATA 调整 app_data 根目录，影响日志目录

如果启动期有日志、运行期没有日志，优先检查：

  • UseSerilogProvider 是否被设为 false。
  • ConfigureLoggingBuilder 是否清空或替换了 Provider。
  • LOG_MINI_LEVEL 或 appsettings 中的 Serilog 级别是否过高。
  • 容器内 AG_APP_DATA 指向的目录是否可写。

启动配置顺序

源码中主要启动阶段可以按下面顺序理解：

  1. StartApplicationAsync 创建 AppBuildOptions 并进入 AppBootstrapper.SafeStartAsync。
  2. CreateHostPrepare 配置 Activity 默认行为。
  3. CreateHostAsync 初始化 AppBuildContext，创建 WebApplicationBuilder。
  4. 执行 ConfigureWebApplicationBuilder 和 ConfigureWebApplicationBuilderAsync。
  5. 执行 ConfigureHostBuilder，包括 Autofac、Host 配置、Logging、ConfigureServices 和自动发现服务注册。
  6. 执行 ConfigureWebHostBuilder，配置 Kestrel、URL、WebHost 级能力。
  7. webApplicationBuilder.Build() 构建容器。
  8. ConfigureWebApplication 初始化 RootServiceProvider、执行启动初始化服务、装配请求管道。
  9. RunAsync 进入 ASP.NET Core 主循环。

排查启动失败时，要先判断错误发生在哪个阶段。比如配置源没加载通常在 ConfigureWebApplicationBuilder 或 ConfigureHostBuilder 附近；DI 注册失败通常在 Build() 或启动初始化服务附近；中间件顺序问题通常在 ConfigureRequestPipeline 之后才暴露。

诊断端点

诊断端点适合服务已经启动、但行为不符合预期时使用。

端点 用途
/fwdev/ASSEMBLY_VERSIONS 查看当前节点实际加载的程序集版本
/fwdev/HEADER_INFO 查看请求 Header，排查代理转发和 Cookie
/fwdev/IDENTITY_INFO 查看当前认证身份和 Claims
/fwdiag/v 查看运行目录 version.txt 中的发布版本
/req_stat/wait_path 查看当前在途请求
/req_stat/switch 查看请求统计中间件内部开关状态

这些入口必须受认证、网关或网络边界保护，不能裸露到公网。

常见问题表

现象 优先检查 处理方向
启动后立即退出 bootlog 中的 Host terminated unexpectedly 看完整异常和堆栈
appsettings 配置没生效 ConfigureWebApplicationBuilder / ConfigureHostBuilder 顺序 确认配置源注册发生在读取之前
DI 解析失败 ConfigureServices、自动发现日志、Autofac 注册 补显式注册或检查扫描过滤器
IAdvancedServiceRegister 没执行 IsEnableAdvancedServiceRegister 和启动日志 保持默认开启，确认类型被扫描
未注册类型被错误构造 IsEnableNotRegisteredTypeResolve 关闭开关或限制 UnregisteredTypeResolveNamespacePattern
[Authorize] 不生效 请求管道日志和认证集成开关 确认认证 scheme 与 IsIntegrateAspNetAuthentication
请求管道中间件没生效 [AutoRequestPipeline-*] 日志 检查阶段、顺序、名称重复和过滤器
日志太少 LOG_MINI_LEVEL、Serilog MinimumLevel 降低最小日志级别
容器里没有日志文件 AG_APP_DATA、目录权限、LOG_FILE 指定可写目录并开启文件日志
诊断端点访问不到 是否注册诊断中间件或 endpoint 检查项目宿主和网络策略
诊断端点暴露到公网 网关、认证、网络 ACL 立即收口访问范围

相关页面