企业官网建设流程全解析

日志这件事，几乎每个后端项目都绕不开。刚入行那会儿，我习惯用Console.WriteLine打天下，后来换成内置的ILogger，再后来项目上了规模，日志散落在各个角落，排查一个线上问题要翻三四个地方，才开始认真琢磨日志框架的选型和落地方式。.NET Core WebAPI里做日志，Log4net是个老牌选手，虽然Serilog、NLog这几年风头很劲，但很多存量系统、传统企业项目依然在用Log4net，尤其是需要把日志按级别分类、再落到数据库做统一审计和检索的场景。这篇内容就围绕“在.NET Core WebAPI中用Log4net做日志级别分类并记录到数据库”这个主题，把我自己踩过的坑、调过的参数、写过的配置完整拆一遍。适合正在做日志体系改造的后端同学，也适合刚接触Log4net想搞清楚它到底怎么和WebAPI结合的新手。核心关键词包括Log4net、日志级别、WebAPI、数据库日志、AdoNetAppender，这些会在下文自然展开，不堆砌。

1. 整体方案设计与选型考量

1.1 为什么在 WebAPI 里还要用 Log4net

先说个现实问题：.NET Core自带的Microsoft.Extensions.Logging抽象层已经很好用了，为什么还要引入Log4net？我自己的答案分两层。第一层是存量兼容，很多团队的老系统、公共库、工具类都是基于Log4net写的，贸然全量替换成Serilog成本高、风险大，而Log4net官方提供了Log4net.Extensions.Logging适配包，可以让它挂到ILogger体系下，新旧代码共存，平滑过渡。第二层是Appender 生态成熟，Log4net的AdoNetAppender对数据库写入的支持非常直接，配置里写 SQL、配参数、设缓冲，几乎不用写代码就能把日志落到表里，这对需要做日志审计、按级别分类入库的场景特别省事。

需要说明的是，Log4net在.NET Core上的支持并不是“原生一等公民”，它依赖log4net2.0.8 以上版本对.NET Standard的兼容。所以选型时要确认版本，低于 2.0.8 的包在.NET Core下会有各种奇怪问题，比如配置文件加载不到、Appender 不生效等。我一般直接上 2.0.15 或更新的稳定版，实测下来兼容性最好。

1.2 日志级别分类的核心思路

Log4net的级别体系是OFF > FATAL > ERROR > WARN > INFO > DEBUG > ALL，从左到右严重程度递减。所谓“级别分类”，本质上是两件事：一是按级别过滤，低于阈值的日志不输出；二是按级别分流，不同级别写到不同的目的地。比如ERROR及以上单独进一张错误表，方便告警和快速检索；INFO进业务日志表，用于日常追踪；DEBUG只在开发环境开，生产环境关掉，避免日志量爆炸。

这里有个容易混淆的点：Log4net的级别过滤有两道闸门。第一道是root或logger上配置的level，它决定这个 logger 最低记录到哪个级别；第二道是Appender上的Threshold，它决定这个 Appender 最低接收哪个级别。两道闸门是“与”的关系，只有同时满足才会真正写出去。理解这一点，后面配置分流才不会绕晕。

1.3 数据库落库方案的整体架构

整体链路是这样的：WebAPI业务代码通过ILogger<T>或ILogManager.GetLogger()写日志，Log4net根据配置的logger级别做第一层过滤，然后分发给不同的Appender。落库用的是AdoNetAppender，它内部维护一个缓冲区，日志先攒在内存里，达到BufferSize或者超过FlushTimeout才批量提交，这样能显著降低数据库压力。多个Appender可以指向同一张表，也可以指向不同的表，取决于你要不要按级别分表。

我倾向于按级别分表：ERROR和FATAL进Sys_ErrorLog，INFO、WARN、DEBUG进Sys_OperationLog。理由是错误日志量小但查询频繁，单独一张表可以加更细的索引、做更短的保留周期；业务日志量大，单独一张表方便做归档和分区。这个设计不是硬性规定，如果团队规模小、日志量不大，一张表加Level字段过滤也完全够用。

2. 核心配置细节与实操要点

2.1 项目引入与配置文件加载

第一步是装包。WebAPI项目里需要两个包：log4net和log4net.Extensions.Logging（如果想让ILogger走Log4net）。用命令行装：

dotnet add package log4net --version 2.0.15 dotnet add package Microsoft.Extensions.Logging.Log4Net.AspNetCore --version 6.0.0

注意第二个包的名字，社区里有好几个类似的适配包，我用的这个是Microsoft.Extensions.Logging.Log4Net.AspNetCore，它提供了AddLog4Net()扩展方法，集成最省心。装完之后，在Program.cs里注册：

builder.Logging.ClearProviders(); builder.Logging.AddLog4Net("log4net.config");

ClearProviders()是为了避免默认控制台输出和Log4net重复打印，这个细节很多人忽略，结果日志打两遍还找不到原因。配置文件log4net.config放在项目根目录，记得在.csproj里设置复制到输出目录：

<ItemGroup> <None Update="log4net.config"> <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory> </None> </ItemGroup>

注意：log4net.config的文件名大小写在不同操作系统上表现不同，Linux 容器里对大小写敏感，建议统一用小写，避免部署到容器后配置加载失败。

2.2 配置文件结构拆解

log4net.config的骨架分三块：appender定义、logger定义、root定义。先看一个完整的落库配置示例：

<log4net> <appender name="ErrorDbAppender" type="log4net.Appender.AdoNetAppender"> <bufferSize value="1" /> <connectionType value="Microsoft.Data.SqlClient.SqlConnection, Microsoft.Data.SqlClient" /> <connectionString value="Server=.;Database=LogDb;User Id=sa;Password=***;" /> <commandText value="INSERT INTO Sys_ErrorLog (LogTime, Level, Logger, Message, Exception, ThreadId) VALUES (@logTime, @level, @logger, @message, @exception, @threadId)" /> <parameter> <parameterName value="@logTime" /> <dbType value="DateTime" /> <layout type="log4net.Layout.RawTimeStampLayout" /> </parameter> <parameter> <parameterName value="@level" /> <dbType value="String" /> <size value="16" /> <layout type="log4net.Layout.PatternLayout"> <conversionPattern value="%level" /> </layout> </parameter> <parameter> <parameterName value="@logger" /> <dbType value="String" /> <size value="256" /> <layout type="log4net.Layout.PatternLayout"> <conversionPattern value="%logger" /> </layout> </parameter> <parameter> <parameterName value="@message" /> <dbType value="String" /> <size value="4000" /> <layout type="log4net.Layout.PatternLayout"> <conversionPattern value="%message" /> </layout> </parameter> <parameter> <parameterName value="@exception" /> <dbType value="String" /> <size value="4000" /> <layout type="log4net.Layout.ExceptionLayout" /> </parameter> <parameter> <parameterName value="@threadId" /> <dbType value="String" /> <size value="64" /> <layout type="log4net.Layout.PatternLayout"> <conversionPattern value="%thread" /> </layout> </parameter> <threshold value="ERROR" /> <filter type="log4net.Filter.LevelRangeFilter"> <levelMin value="ERROR" /> <levelMax value="FATAL" /> </filter> </appender> <appender name="InfoDbAppender" type="log4net.Appender.AdoNetAppender"> <bufferSize value="20" /> <connectionType value="Microsoft.Data.SqlClient.SqlConnection, Microsoft.Data.SqlClient" /> <connectionString value="Server=.;Database=LogDb;User Id=sa;Password=***;" /> <commandText value="INSERT INTO Sys_OperationLog (LogTime, Level, Logger, Message, ThreadId) VALUES (@logTime, @level, @logger, @message, @threadId)" /> <parameter> <parameterName value="@logTime" /> <dbType value="DateTime" /> <layout type="log4net.Layout.RawTimeStampLayout" /> </parameter> <parameter> <parameterName value="@level" /> <dbType value="String" /> <size value="16" /> <layout type="log4net.Layout.PatternLayout"> <conversionPattern value="%level" /> </layout> </parameter> <parameter> <parameterName value="@logger" /> <dbType value="String" /> <size value="256" /> <layout type="log4net.Layout.PatternLayout"> <conversionPattern value="%logger" /> </layout> </parameter> <parameter> <parameterName value="@message" /> <dbType value="String" /> <size value="4000" /> <layout type="log4net.Layout.PatternLayout"> <conversionPattern value="%message" /> </layout> </parameter> <parameter> <parameterName value="@threadId" /> <dbType value="String" /> <size value="64" /> <layout type="log4net.Layout.PatternLayout"> <conversionPattern value="%thread" /> </layout> </parameter> <threshold value="INFO" /> <filter type="log4net.Filter.LevelRangeFilter"> <levelMin value="INFO" /> <levelMax value="WARN" /> </filter> </appender> <root> <level value="INFO" /> <appender-ref ref="ErrorDbAppender" /> <appender-ref ref="InfoDbAppender" /> </root> </log4net>

几个关键点值得展开。bufferSize对错误日志设成 1，意思是来一条写一条，不缓冲，因为错误日志量小、实时性要求高；业务日志设成 20，攒够 20 条批量提交，减少数据库往返。connectionType这里用的是Microsoft.Data.SqlClient，.NET Core下推荐用这个而不是老的System.Data.SqlClient，后者在新版本里已经逐步被替代。filter用LevelRangeFilter做区间过滤，比单纯靠threshold更精确，因为threshold是“大于等于”，而LevelRangeFilter可以同时限定上下界。

2.3 数据库表结构设计

表结构要和配置里的commandText严格对应，字段类型、长度都要匹配，否则写入时会报截断或类型转换错误。我用的两张表结构如下：

Message和Exception都设成 4000，是因为nvarchar(max)在某些批量插入场景下性能不如定长，而 4000 已经能覆盖绝大多数日志正文。如果确实有超长堆栈，可以在应用层截断，或者把字段改成nvarchar(max)并接受性能损耗。LogTime用datetime2而不是datetime，精度更高，避免同一秒内多条日志排序错乱。

提示：AdoNetAppender的parameter顺序必须和commandText里占位符的顺序一致，虽然部分驱动能自动匹配，但顺序错位在批量插入时容易出隐蔽 bug，建议严格对齐。

3. 完整实操流程与关键环节实现

3.1 从零搭建的完整步骤

假设现在有一个空的WebAPI项目，我按实际操作顺序走一遍。第一步建项目：

dotnet new webapi -n LogDemo cd LogDemo

第二步装包，前面提过，两个包。第三步建数据库和表，用下面的 SQL：

CREATE TABLE Sys_ErrorLog ( Id BIGINT IDENTITY(1,1) PRIMARY KEY, LogTime DATETIME2 NOT NULL, Level NVARCHAR(16) NOT NULL, Logger NVARCHAR(256) NULL, Message NVARCHAR(4000) NULL, Exception NVARCHAR(4000) NULL, ThreadId NVARCHAR(64) NULL ); CREATE TABLE Sys_OperationLog ( Id BIGINT IDENTITY(1,1) PRIMARY KEY, LogTime DATETIME2 NOT NULL, Level NVARCHAR(16) NOT NULL, Logger NVARCHAR(256) NULL, Message NVARCHAR(4000) NULL, ThreadId NVARCHAR(64) NULL );

第四步写log4net.config，内容就是 2.2 节那份，把连接串换成自己的。第五步在Program.cs注册，第六步在业务代码里注入ILogger<T>写日志。整个流程半小时内能跑通，真正花时间的是调参数和验证分流是否正确。

3.2 业务代码中的日志写法

注入ILogger<T>之后，写法很自然：

[ApiController] [Route("api/[controller]")] public class OrderController : ControllerBase { private readonly ILogger<OrderController> _logger; public OrderController(ILogger<OrderController> logger) { _logger = logger; } [HttpGet("{id}")] public IActionResult GetOrder(int id) { _logger.LogInformation("查询订单，订单号：{OrderId}", id); try { if (id <= 0) throw new ArgumentException("订单号非法"); return Ok(new { OrderId = id, Status = "OK" }); } catch (Exception ex) { _logger.LogError(ex, "查询订单失败，订单号：{OrderId}", id); return StatusCode(500, "内部错误"); } } }

这里有个细节：LogInformation用的是结构化日志的占位符写法{OrderId}，而不是字符串拼接。Log4net的PatternLayout里%message会把占位符替换成实际值，所以最终入库的是替换后的文本。如果想让参数单独存字段，需要自定义Layout或者用PatternLayout的%property配合LogicalThreadContext，这个属于进阶用法，普通场景用%message足够。

3.3 验证分流是否生效

配置写完后，最怕的是“看起来配了但没生效”。我的验证方法是写一个临时接口，依次打四个级别的日志：

_logger.LogDebug("这是一条 DEBUG"); _logger.LogInformation("这是一条 INFO"); _logger.LogWarning("这是一条 WARN"); _logger.LogError("这是一条 ERROR");

然后查库：Sys_ErrorLog里应该只有ERROR一条，Sys_OperationLog里应该有INFO和WARN两条，DEBUG因为root级别是INFO被过滤掉。如果结果不符，按这个顺序排查：先看root的level是不是INFO，再看两个Appender的threshold和filter有没有写反，最后看bufferSize是不是太大导致日志还没刷进去。bufferSize大于 1 时，程序正常退出前要调用LogManager.Flush()，否则缓冲区里的日志会丢，这个坑我踩过不止一次。

3.4 参数计算与容量估算

日志落库最容易被忽视的是容量。假设一个中等规模接口每天产生 5000 条INFO日志，每条平均 300 字节，一天约 1.5MB，一年约 550MB，加上索引大概 800MB。这个量级单表完全扛得住。但如果接口调用量大，比如每天 50 万条，一年就是 55GB，这时候就要考虑分区或者定期归档。我的经验是：单表超过 2000 万行或者 20GB 就考虑归档，归档策略可以按LogTime每月清理一次，保留最近 3 个月。

bufferSize的选择也有讲究。设太小，数据库往返频繁；设太大，程序崩溃时丢日志多。业务日志我一般设 20 到 50，错误日志设 1。FlushTimeout默认是 0，表示不按时间刷，只按条数刷，如果希望即使没攒够也定时刷，可以设成 5000 毫秒，但要注意这会增加数据库压力。

4. 常见问题排查与避坑经验

4.1 日志不落库的典型原因

这是最高频的问题，我整理了一张速查表：

Log4net内部错误默认是静默的，排查时可以在Program.cs里打开内部调试：

log4net.Util.LogLog.InternalDebugging = true;

打开后控制台会打印Log4net自己的错误，比如连接失败、SQL 语法错误、参数不匹配，非常有用。生产环境记得关掉，否则日志量会翻倍。

4.2 连接池与并发写入的坑

AdoNetAppender每次批量写入会从连接池取连接，如果bufferSize设得大、并发高，可能出现连接池耗尽。我的做法是给日志库单独配一个连接串，Max Pool Size设成 20 左右，和业务库隔离，避免日志写入拖垮业务查询。另外，多个Appender同时写同一个库时，要注意死锁风险，尤其是批量插入加索引的表，建议把日志表的索引控制在 2 到 3 个，主键加LogTime加Level足够，索引太多会拖慢插入。

4.3 级别分类的实操心得

最后分享几个配置层面的经验。第一，不要在生产环境开 DEBUG，root级别设INFO是底线，DEBUG 日志量可能是 INFO 的十倍以上，落库会直接把表撑爆。第二，错误日志和业务日志分表，前面说过理由，实际运维时错误表可以设更短的保留周期，业务表保留更久，灵活度高。第三，Logger字段存全名，%logger会输出完整的命名空间加类名，排查时能直接定位到代码位置，比只存类名有用得多。第四，时间用 UTC 还是本地时间要统一，RawTimeStampLayout默认取DateTime.Now，如果系统跨时区部署，建议在应用层统一转 UTC 再写，避免时间错乱。

我在实际项目里还遇到过一个隐蔽问题：Log4net的配置文件如果被多个项目共享，appender名字冲突会导致后加载的覆盖先加载的。解决办法是每个项目用独立的配置文件，或者给appender加项目前缀。这个坑不常见，但一旦遇到很难查，因为日志表现是“时有时无”，其实是加载顺序问题。

日志体系这件事，配好只是开始，真正考验人的是长期运维中的容量、性能和检索效率。把级别分类和落库这两件事做扎实，后面加告警、做日志分析平台都是水到渠成的事。