企业官网建设流程全解析

1. 项目概述：为什么我用ELK收拾Spring Boot日志

先说结论：这套方案解决的核心问题就两个字——"排查"。微服务拆完以后，日志散落在几十台机器上，出问题的时候grep登录一台台翻，翻到天亮都不一定定位到根因。ELK把日志从"到处翻"变成"一个框里搜"，这带来的效率提升，用过的都知道。

ELK这个词拆开看：Elasticsearch负责存储和索引，Logstash负责日志的清洗和转换，Kibana负责可视化查询。后面通常还会加一个Filebeat，负责在应用机器上轻量采集日志并转发给Logstash。整套链路跑起来以后，Spring Boot应用只需要把自己的日志按一定格式输出，剩下的采集、解析、存储、展示，全部交给这套管道。

这个项目适合谁参考？两类人。一类是刚接触微服务日志聚合的中小型团队，系统里跑着几个Spring Boot服务，日志还散落在各自的服务器上；另一类是已经上了ELK但只是"能跑"，日志格式五花八门，Kibana里搜不到有价值字段，想把管道规范化重做一遍的同学。

我在实际项目中用的版本组合是：Elasticsearch 7.10.2 + Logstash 7.10.2 + Kibana 7.10.2 + Filebeat 7.10.2，Spring Boot版本是2.3.x，JDK用的是8。这组版本比较稳定，网上踩坑资料也多。如果用更高版本的8.x，需要注意ES的默认安全配置变了，API也有一些改动，后面会提到。

2. Spring Boot日志端改造：先把日志改成机器能读懂的样子

2.1 为什么不能直接把默认日志丢给ELK

Spring Boot默认的日志格式是为"人眼阅读"设计的，大概长这样：

2024-12-18 14:23:45.678 ERROR 12345 --- [http-nio-8080-exec-1] com.demo.payment.service.OrderService : 订单创建失败，用户ID=10086

这种格式人眼看着舒服，但对ELK来说是噩梦。Logstash如果要做字段解析，得写一堆正则去抠时间、日志级别、线程、类名、消息体，而且不同开发者的日志格式稍微有点出入，匹配就失败。更麻烦的是，多行堆栈信息默认会被当成多条日志分别采集，一个异常StackTrace被拆成七八条记录，查起来恨不得骂人。

所以第一步必须是改造应用端日志输出，让程序直接输出结构化日志，最推荐的做法是输出JSON格式。这就像咱们平时和人对接数据，与其给一份排版漂亮的Excel让他自己拆，不如直接给一份JSON，他拿去就能用。

2.2 用logstash-logback-encoder输出JSON日志

Spring Boot默认的日志实现是Logback，不用换框架，直接加一个依赖就行。在pom.xml里加：

<dependency> <groupId>net.logstash.logback.encoder</groupId> <artifactId>logstash-logback-encoder</artifactId> <version>6.6</version> </dependency>

然后在src/main/resources下放一个logback-spring.xml，关键配置如下：

<?xml version="1.0" encoding="UTF-8"?> <configuration> <springProperty scope="context" name="appName" source="spring.application.name"/> <appender name="JSON_FILE" class="ch.qos.logback.core.rolling.RollingFileAppender"> <file>logs/${appName}.log</file> <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy"> <fileNamePattern>logs/${appName}.%d{yyyy-MM-dd}.%i.log.gz</fileNamePattern> <timeBasedFileNamingAndTriggeringPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedFNATP"> <maxFileSize>200MB</maxFileSize> </timeBasedFileNamingAndTriggeringPolicy> <maxHistory>7</maxHistory> </rollingPolicy> <encoder class="net.logstash.logback.encoder.LogstashEncoder"> <includeMdc>true</includeMdc> <customFields>{"service.name":"${appName}"}</customFields> </encoder> </appender> <root level="INFO"> <appender-ref ref="JSON_FILE"/> </root> </configuration>

这里有几个细节值得展开说。

includeMdc设为true，是为了把MDC里的上下文信息带出来。比如你在代码里往MDC放了一个traceId，那这条日志的JSON里就会多出一个mdc.traceId字段。这一点对排查分布式调用链特别有用——不用改业务代码，只要在请求入口处过滤器里设置MDC，所有日志自动带上追踪ID。

customFields用来把应用名打进每一条日志。当时我差点忽略这个，结果日志收上来以后，Kibana里根本看不出哪条日志来自哪个服务，毫无区分度。加了service.name之后，后边做多服务对比查询、按服务维度过滤日志就全都顺了。

输出JSON后，同样的日志就变成：

{"@timestamp":"2024-12-18T14:23:45.678+08:00","@version":"1","message":"订单创建失败，用户ID=10086","logger_name":"com.demo.payment.service.OrderService","thread_name":"http-nio-8080-exec-1","level":"ERROR","level_value":40000,"service.name":"order-service"}

Logstash不需要任何解析规则，直接就能把这些字段抽出来用。

2.3 非JSON日志的兜底做法

有些老项目不好动依赖，或者有些第三方日志（比如Nacos客户端自身的日志）不是JSON格式，没法统一改。我的建议是保留JSON输出为主，然后通过Filebeat或Logstash的多行处理（multiline）来兜底。下面这个filebeat配置里就有，稍后细说。

另外还有一个Spring Boot自带的logback配置技巧：如果不想引额外的依赖，也可以自己写一个PatternLayout，把字段用分隔符隔开，之后在Logstash中用grok解析。但我的实践体会是，这属于"能跑但不好维护"的方案——日志格式一旦调整，正则就得跟着改。既然logstash-logback-encoder只有一个小依赖，直接用JSON格式才是长期正解。

3. 采集与传输链路：Filebeat做轻量搬运工

3.1 为什么用Filebeat而不是直接上Logstash

很多人刚入门时想：我都有Logstash了，为什么还要Filebeat？直接在每台机器上装Logstash采集不就行了？

技术上确实可以，但实操中有两个问题：Logstash是JVM进程，默认堆内存起步就是1GB，每台业务机器都多跑一个它，资源开销不是每个团队都扛得住；另外Logstash重在对日志做清洗转换，放在采集端有点"大材小用"，管道一旦堵塞，丢失数据的风险也高。

Filebeat是用Go写的，安装包小，启动只占10~20MB内存，把"采集"和"搬运"这两件轻量事做了，然后把清洗转换的活留给集群里的Logstash。这样业务机器只有个轻量agent，日志处理压力全在日志集群侧，边界也清晰。

我们线上环境大概是：30台左右的业务机器，每台都装了Filebeat，由Ansible批量推送配置。Filebeat把采集到的日志转发给Logstash集群，Logstash做解析清洗后再写入Elasticsearch。

3.2 filebeat.yml的关键配置拆解

下面是这套方案里我实际用下来稳定的filebeat.yml配置：

filebeat.inputs: - type: log enabled: true paths: - /home/app/*/logs/*.log exclude_files: ['\.gz$'] multiline: pattern: '^\d{4}-\d{2}-\d{2}' negate: true match: after fields: log_type: springboot fields_under_root: true output.logstash: hosts: ["logstash-node1:5044", "logstash-node2:5044"] loadbalance: true logging.level: info logging.to_files: true

这段配置里，multiline部分非常重要。上面我们用的logstash-logback-encoder会把堆栈信息的多行内容整体作为message字段放进JSON，所以严格来说JSON日志并不需要multiline。但我这里加上它，是为了兼容老文件里可能存在的非JSON格式日志，比如启动时Spring Boot打印的Banner，还有其它第三方库输出的纯文本日志。pattern用时间戳开头的正则判断：如果某一行不是以时间戳开头，就把它和上一行合并。这样如果哪天应用输出的日志里混进来一个多行堆栈的文本日志，也不会在ES里碎成一条条垃圾数据。

fields_under_root: true的作用是把fields字段放到JSON根节点，这样在Logstash里可以直接用[log_type]取到值。如果忽略这个设置，它会被嵌套在fields子节点下面，取用的时候路径多一层，容易写错。

输出端配置了两台Logstash，同时开了loadbalance，这个机制会按连接数做负载分发。好处自然是单点故障时，一台宕了另一台还能顶上，采集端不会中断。

还有几个运维上的细节：Filebeat的registry文件记录了每个文件采集到的offset，Filebeat重启后从断点续采，不用担心重复或丢日志；如果要手动重新采集某个日志文件，删除registry目录再重启Filebeat就行，但这是一个很危险的操作，误删会导致从头开始重采大量历史日志把ES打爆，生产环境千万不要乱动。

3.3 Filebeat采集后的日志完整性保障

Filebeat有个特性叫"至少一次投递"，它的内部处理机制是：日志读到后先写入本地的spool队列，确认投递给Logstash成功后才从spool中删除，如果投递失败，会按backoff策略重试，同时写入硬盘缓冲。也就是说，只要磁盘没炸，日志基本不会丢。

但"至少一次"意味着可能存在重复投递。比如网络闪断，Logstash收到了数据但Filebeat没收到ack，它就会重发，ES里就会出现重复记录。如果业务场景对日志重复极度敏感（比如根据日志做计费统计），可以考虑在Logstash侧用fingerprint插件对日志内容算指纹ID，然后写入ES时指定文档_id来实现去重。一般搭建日志平台，这点重复可以忽略不计，不用特殊处理。

4. Logstash管道配置：把日志洗成想要的样子

4.1 Logstash定位与三个阶段的配置逻辑

Logstash的工作方式就是一个管道：input接收数据，filter处理数据，output输出数据。每一段都有对应的插件。下面这条管道配置是我长期在用的，结合注释来看：

input { beats { port => 5044 client_inactivity_timeout => 120 } } filter { if [fields][log_type] == "springboot" { json { source => "message" target => "json_body" } if [json_body][@timestamp] { date { match => ["[@timestamp]", "ISO8601"] target => "@timestamp" } mutate { remove_field => ["json_body", "message", "@version", "log", "input", "ecs"] } mutate { rename => { "json_body" => "springboot" } } } } } output { elasticsearch { hosts => ["http://es-node1:9200", "http://es-node2:9200"] index => "springboot-%{+YYYY.MM.dd}" user => "elastic" password => "YOUR_PASSWORD" } }

filter阶段的核心动作就是做json解析：Filebeat传过来的原始日志内容是在message字段里，Logstash的json插件把字符串解析成结构化JSON对象，存到json_body里。接着用date插件重写@timestamp为日志原始时间戳里的时间，这一步很重要，因为默认的@timestamp是Logstash接收到日志的时间，如果管道堵塞或者Filebeat延迟了，这个时间和业务日志实际发生的时间就会有偏差，查询排序都会出问题。

解析成功后，原始message字段已经没用了，删掉它，同时把解析出来的完整JSON对象重命名为springboot，Kibana里查起来字段都在这个嵌套层级下。这样既保留了原始日志的所有字段，又避免字段平铺后和系统字段冲突。

一个值得注意的点：如果某条日志message里不是合法JSON，json插件会抛异常，管道会把这批日志打上_jsonparsefailure标签。我在filter里没有做特殊处理，是因为日常日志基本都是JSON，偶尔几行解析失败也留着后续排查。如果想强制处理，可以在json插件后面加一个条件判断，解析失败就丢到单独的索引，或者尝试用grok兜底。

4.2 管道性能与缓冲调优

Logstash默认配置在小流量下没问题，但日志量大以后，有几个参数值得专门调一调，都在config/logstash.yml里：

pipeline.workers: 8 pipeline.batch.size: 2000 pipeline.batch.delay: 50

这几个参数的含义要搞清楚：pipeline.workers是执行filter和output的并发线程数，一般建议等于CPU核数；batch.size是每个worker一次性从input拉取的最大事件数，数值大吞吐高，但内存压力也大；batch.delay是攒批的等待时间，单位毫秒。小流量环境可以保守一点，大流量环境（单机每天日志量几百G）可以试着把batch调整到4000~5000，同时观察JVM堆内存使用，别把GC搞成瓶颈。

还有output时的一个细节：如果Elasticsearch写入跟不上Logstash消费速度，除了ES扩容，还可以考虑Logstash侧调整pipeline.queue.type: persisted，启用持久化队列，这样在ES抖动时Logstash会把事件先存到磁盘，ES恢复后继续投递，避免内存限制导致丢数据。代价是额外的磁盘IO和一定延迟，看业务容忍度。

4.3 Logstash处理Spring Boot多行日志的另一种方案

如果你确实有一批日志不是JSON，而是纯文本多行日志（比如老项目一直在用的pattern规则），Logstash里可以通过multilinecodec实现在管道入口合并。但要注意，multiline codec属于Logstash的input codec级别，它对内存有一定消耗，且合并状态下无法实时逐行输出。相比之下Filebeat侧做multiline更节省资源，建议能用Filebeat处理就尽量不要在Logstash里做。

在管道里如果真的要处理单行文本日志，grok是绕不开的利器。举一个例子，解析Spring Boot启动日志里的监听端口：

2019-11-11 15:30:29.456 INFO 1123 --- [main] o.s.b.w.embedded.tomcat.TomcatWebServer : Start TomcatServer on port: 8080

对应的grok表达式是：

grok { match => { "message" => "%{TIMESTAMP_ISO8601:log_time} %{LOGLEVEL:level} %{NUMBER:pid} --- \[%{DATA:thread_name}\] %{JAVACLASS:logger_name} : %{GREEDYDATA:log_message}" } }

这玩意儿写起来非常劳神，所以我才反复强调那句"日志输出端就改成JSON，别让下游做文本解析"。能在源头解决的事，不要拖到管道环节再做。

5. Elasticsearch索引设计与Kibana排查实战

5.1 索引模板、分片与数据生命周期

Logstash写入ES时用的索引名是springboot-%{+YYYY.MM.DD}，即按天分索引。这个模式配合ES的索引模板，可以批量设置分片数、副本数、字段映射和ILM策略。

我在ES里专门建了一个名为springboot_template的索引模板，核心配置是：

{ "index_patterns": ["springboot-*"], "template": { "settings": { "number_of_shards": 3, "number_of_replicas": 1, "index.lifecycle.name": "logs_retention_30d" }, "mappings": { "properties": { "level": { "type": "keyword" }, "logger_name": { "type": "keyword" }, "thread_name": { "type": "keyword" }, "message": { "type": "text", "analyzer": "ik_max_word" }, "springboot": { "type": "object", "enabled": true } } } } }

这里分片数和副本数的选择有讲究。分片数不是越多越好：数量太少，单分片数据量过大会拖慢查询和写入；数量太多，每个分片都要占用内存和文件句柄，集群开销直线上升。一般建议按每个分片数据量控制在30GB~50GB估算，日均日志量如果是10GB，留三天的查询热窗口，30GB左右，3个主分片够用。副本数在测试环境可以设0，生产至少1，保证节点挂了还能查到数据。

message字段我没有让它默认不分词搜索，单独配置了分词器。如果日志里要按关键字搜业务信息，这个字段是重中之重。

ILM（Index Lifecycle Management）策略是把"按天生成索引"和"磁盘清理"自动化起来的关键。我设了一个30天保留策略，索引生成30天后自动进入delete阶段。在这个策略出来之前，老团队都是写crontab脚本定期手动删除索引，或者用curator，麻烦还容易出错。用了ILM以后，存储成本得到有效控制，日志保留周期的调整也只需要改一处策略，全自动生效。

关于时区问题，这里必须单独强调。Kibana的默认时区是浏览器时区，而ES里@timestamp存的是UTC时间。如果你的日志产生时间是北京时间，Kibana里如果没调时区，所有日志看起来都会慢8个小时。要么在Kibana设置界面把时区改成Asia/Shanghai，要么在Logstash的date插件里指定时区：timezone => "Asia/Shanghai"。这看似小问题，但排查时极易把人带沟里。我就在测试环境踩过一次，明明刚打的日志看不到，折腾了半天发现是时区偏移。

5.2 Kibana查询语法与字段分布

写完配置、数据落库后，剩下的日常工作都发生在Kibana里。分享一下我排查问题时最常用的几个操作。

Kibana里的Discover页面，首先要建好Index Pattern。这里有个坑：当你输入springboot-*建好Pattern并选择@timestamp作为时间筛选字段后，如果在Discover里什么都看不到，大概率是Index Pattern的时间筛选范围不对。Kibana默认只显示最近15分钟的数据，如果你的日志是好几个小时之前产生的，直接把右上角时间范围拉大，数据就会出来了。

查询语法上，Lucene语法支持field:value精确匹配，也可以用KQL的新语法。我常用的组合是：

• 查某个服务的所有错误：service.name : order-service AND level : ERROR
• 查某个用户的操作日志：springboot.mdc.traceId : "abc123"（前提是你日志里带了MDC字段）
• 用通配符模糊搜：message : *优惠券*

注意KQL里如果字段值包含特殊字符，比如逗号、中括号、冒号，最好用双引号包裹。另外查询关键字时区分大小写比较严格，ERROR和error的结果完全不一样。如果不想纠结大小写，可以在索引映射里把keyword字段的normalizer配置成小写归一化，或者查询时多用小写并用通配符。为了省事，我在做映射时就把能归一化的keyword字段都配了normalizer。

另外一个很实用的功能是Kibana的KQL过滤器配合时间线。在页面上可以保存多个filter组合，每次排查同一类问题时直接点保存好的filter，不用每次都重新输入一长串查询语句。团队协作时，还可以把常用的查询和Dashboard做成可视化对象分享出去，前端同事查问题也就点两下的事。

5.3 索引级别的排查：为什么Kibana里明明有日志却搜不到

这是一个高频问题。Kibana里能看到Discover左侧索引列表，如果某个索引显示在列表里但查询返回空，或者查询特别慢，先按下面顺序排查：

1. 看时间范围，确认不是被15分钟默认窗口挡了；
2. 看字段映射，如果字段被映射成了text类型，但你想精确匹配完整值，KQL里用field.keyword试一下；
3. 看索引是否被ILM切换了别名。Kibana的Index Pattern有时候绑定的是具体索引名而不是通配符，一旦索引被ILM rollover或delete了，Pattern失效，自然就搜不到。改成基于通配符的Pattern能避免这个坑；
4. 如果查询直接报"search_phase_execution_exception"，多半是某个分片副本不可用，去ES的健康接口看下集群状态，是不是yellow甚至是red。

除此之外，ES里如果索引字段非常多，映射膨胀严重，写入性能和存储都会直线劣化，特别是日志里带了大量业务上下文的时候。这个问题的解法是开dynamic: false或使用index.mapping.total_fields.limit做约束，只保留真正需要检索的字段做显式映射，其他冗余字段一律不索引。这是很多团队日志索引越建越大的一个隐性原因，值得提前控制。

6. 兼容Spring Boot 2.x和3.x的注意点

如果你的项目用的是Spring Boot 3.x，需要注意一件事：Spring Boot 3是构建在Jakarta EE上的，但logstash-logback-encoder这个库本身不依赖Servlet API，所以直接引入logback encoder依赖即可，不受Spring Boot大版本影响。

不过Spring Boot 3默认使用Logback 1.4.x，logstash-logback-encoder需要6.6以上版本才支持，版本太老会直接报IncompatibleClassChangeError。建议直接用当时最新的稳定版本，比如7.4。

另外Spring Boot 3.2以后支持logback-spring.xml中的一些新特性，比如条件化配置，如果你愿意折腾，可以让测试环境打控制台人类可读日志，生产环境输出JSON日志。配置文件长这样：

<springProfile name="dev"> <!-- 开发环境的人类可读格式 --> </springProfile> <springProfile name="prod"> <!-- 生产环境的JSON格式 --> </springProfile>

这样本地开发时日志还是传统样子，看着舒服，测试也方便；上到生产环境后自动切换到JSON输出，管道上不用做额外动作。这套方案在团队里推行起来大家普遍接受度很高。

还有一个要注意的是异步日志。Spring Boot的默认日志是同步写的，每个日志事件都会走一遍IO，高并发下多少会对业务线程有影响。logback本身支持AsyncAppender，我建议在logback-spring.xml里包一层：

<appender name="ASYNC_JSON" class="ch.qos.logback.classic.AsyncAppender"> <queueSize>8192</queueSize> <discardingThreshold>0</discardingThreshold> <neverBlock>true</neverBlock> <appender-ref ref="JSON_FILE"/> </appender>

这里三个参数都不建议用默认值：queueSize设太小会导致激烈竞争，设太大则内存占用多；discardingThreshold默认是20%，意思是队列快满时直接丢弃20%的低级别日志来保护TPS，但如果在排查关键错误时把ERROR级别日志丢了就亏大了，所以设成0；neverBlock设为true保证日志队列满了以后不阻塞业务线程，毕竟打日志不能把业务拖垮，日志丢失在这种极端时刻反而是可接受的。日志本身就是"尽最大努力去记录"，和业务可用性放一起，优先级还是业务更高。

7. 常见问题与排查技巧实录

7.1 日志重复、缺失与延迟问题怎么快速定位

我排查的时候习惯按数据流一路往下看数据：先确认业务机器上Filebeat采集到了多少event（filebeat monitor命令或日志里能看到），再看Logstash的output统计，再看ES索引的文档数量。哪一段数量对不上，问题就在哪一段。这个思路比瞎猜快得多。

7.2 磁盘与性能优化建议

ELK最烧钱的部分就是存储。ES的索引副本、Logstash的队列、Filebeat的registry和buffer都会占磁盘。有几个省钱又省心的做法：

1. Elasticsearch开启best_compression压缩，同时调大索引刷新间隔（refresh_interval从默认1秒改成30秒）。日志场景对实时性要求没那么高，半小时内的延迟完全可以接受，但性能提升立竿见影。
2. 同步开启ILM策略，控制保留周期。日志保留多久要事先想清楚，一般业务日志保留30天足够，安全合规需要的再单独走冷热架构。
3. Filebeat的max_procs默认是CPU核数，低配机器上可以限制为2，减少空转。

另外，如果你的日志索引用上面提到的按天分开，Kibana查一个月范围内的日志就是把30个索引全查一遍，速度自然慢。需要长期保留热数据时，可以按周分索引并配合冷热节点，让老数据自动迁移到机械盘节点。不过这是团队成长到一定规模才需要考虑的事，初期先别把架构搞得这么复杂。

7.3 排查时最容易被忽略的几个细节

首先要说的是关闭两个默认开启但日志场景不用的ES功能。一是_source里除了原始JSON还保留了message字段，这会让存储翻倍，我一般在索引模板里把_source保持为true但不单独保留重复内容，而是在Logstash阶段把没用的原始字段删干净。二是ES默认开启了全文搜索打分，日志检索场景根本不需要算相关性分数，设置"index_options": "docs"或者把norms关掉，能省不少内存。

其次是尽量不要在Kibana里直接对message字段用wildcard查询，数据量大以后这个查询特别慢。如果想支持快速模糊检索，更科学的方案是引入IK分词器并搭配ngram分词器做前缀匹配，或者干脆用Elasticsearch的match查询替代无脑*关键字*。

最后特别提醒：不要把Elasticsearch的JVM堆内存设置得过大，官方建议不超过物理内存的一半，且最大不超过30GB（超过这个值，JVM的压缩指针优化会失效）。很多同学看服务器内存128G就给ES配64G堆，结果GC越来越频繁，性能反而更差。堆内存只是缓存的一部分，操作系统文件缓存对ES读取性能的影响更大，堆外内存才是大头。

8. 搭建ELK日志平台的最后复盘与经验补充

整套方案从落地到稳定运行，最花时间的地方反而不是配置本身，而是日志格式的统一。如果你有机会从零开始推进一个日志平台，建议先把"日志输出规范"定下来，用文档明确字段标准，然后在应用侧用统一的logback-spring.xml模板配上标准化依赖，让每个服务开箱即用地输出JSON日志。规范先行，技术方案反而好落地。

在我自己的经历中，还有一个小技巧值得拿出来分享：Kibana索引模板建好后，先不要急着接生产流量，先用一台测试服务以高并发压测方式打一批日志，把索引的分片数、副本数、字段映射都调到位，再放量到全集群。这一步能帮你省掉后面大量的深夜拔头发时间。数据量上了才发现分片数不够或者字段类型不对，改起来牵扯面非常大。

如果你后续想把日志平台玩得更深，还可以接进链路追踪系统，比如在日志里关联traceId，再在Kibana里按traceId聚合一次请求的全链路日志，排查问题就从"翻日志"进化成了"看时间线"。这个扩展方向不需要推翻已有架构，只是在上游日志采集时补一个traceId字段，回报率极高。