企业官网建设流程全解析

如果你管理过 SonarQube，大概率在某次升级或加了新插件后，会在日志里撞见这句话：

java.lang.IllegalStateException: Unrecoverable indexation failures: 1 errors among 1 request

我第一次遇到时，第一反应是：重启会不会好？结果重启了三次，照样启动失败，页面打不开。后来才发现，这类报错并不是服务"抽风"，而是后台的 Elasticsearch 索引过程遇到了一个"重试也解决不了"的硬错误。它真正要命的地方在于：直接告诉你"不可恢复"，却不告诉你到底是哪条数据、哪个字段、哪次请求把整个索引流程拖垮了。

这篇文章就围绕这个报错展开，我会把索引机制讲清楚，再给出完整的日志排查链路，最后按不同根因给出修复操作。无论你是刚接手 SonarQube 的运维新手，还是已经被这个问题折腾过的老手，照着这个思路走，基本能在半小时内定位并处理。

1. 报错拆解：SonarQube 的索引机制与"不可恢复"的分界线

1.1 索引层在 SonarQube 中的角色：ES 是缓存，数据库才是权威

SonarQube 架构里有一个很容易被忽视的组件：内嵌的 Elasticsearch。它承担的核心职责不是存储，而是搜索和聚合加速。

比如你在界面上搜一个 issue、按规则统计项目问题数、查看组件树，这些都是走 ES 查询。ES 里存的并不是原始数据，而是从 Postgres/Oracle/MySQL 等数据库中读取业务数据后生成的索引文档。数据库里的 issues 表、components 表、measures 表才是权威数据源。

所以你要先建立这个认知：ES 索引损坏或丢失，不等于业务数据丢失。后面提到的重建索引、清空 data/es 目录，都不会动到数据库里的分析结果，只是在重建一份"供搜索用的副本"。

这个报错出现时，SonarQube 的索引器在把一批数据写入 ES 的过程中，有一个请求失败了，而且 ES 返回的错误属于"永久性错误"。索引器判断再怎么重试也没有意义，于是直接抛出 IllegalStateException，中断整个索引任务。

1.2 "1 errors among 1 request" 的概率与统计口径

先拆解信息本身。Unrecoverable indexation failures: 1 errors among 1 request中：

• 1 errors表示本次批量写入中有 1 条文档写入失败；
• among 1 request表示这次失败发生在 1 个 ES 批量请求里。

如果错误变成3 errors among 2 requests，说明这次索引流程中，ES 收到了 2 个批量请求，其中一共有 3 条文档没写进去。数字越大，说明污染面越广，但处理思路是一样的：找到让写入失败的那条数据的特征，而不是试图修复整个索引。

这里要特别提醒一句：报错信息本身并不会告诉你失败的是哪个索引、哪个字段。ES 只会在 es.log 里留下具体的底层异常，比如字段太长、mapping 冲突、磁盘只读等。所以看一眼报错就慌，或者直接去删 data/es 目录，都是不可取的。先定位底层异常，再动手。

1.3 什么错会被判为"不可恢复"

ES 写入失败的错误可以分成两类：

一类是临时性的。比如节点正在做大量合并请求导致线程池繁忙，返回es_rejected_execution_exception。这种错误偶尔发生，等一下重试通常就能成功，SonarQube 的索引器会走重试逻辑，不会上升到 Unrecoverable。

另一类是永久性的。比如：

• max_bytes_length_exceeded_exception：字段值超过 ES 单 term 最大长度 32766 字节；
• mapper_parsing_exception：文档字段类型与索引 mapping 不一致；
• illegal_argument_exception：ES 认为请求本身非法；
• 磁盘水位线触发后，索引被自动设置为只读，写入直接被拒。

这些错误即使重试一百次，结果也一样，因为问题出在数据本身或索引状态本身。SonarQube 的逻辑是：与其无限重试刷爆日志，不如抛个异常让管理员干预。这也就是你为什么反复重启都没用的原因——重启解决的是进程问题，解决不了数据问题。

2. 从日志顺藤摸瓜：三个日志文件与底层异常定位

2.1 先看哪个日志：sonar.log 只给结论，es.log 才有细节

拿到报错后，不要急着搜解决方案，先去翻日志。SonarQube 的日志目录一般在部署目录的 logs 下面，常见有这几个文件：

在我处理过的案例里，90% 的线索都在 es.log 里。sonar.log 里往往只有那一行抽象异常，顶多附一段调用栈：

2025-05-20 10:32:11,482ERROR [o.s.s.es.BulkIndexer] Unable to index ... java.lang.IllegalStateException: Unrecoverable indexation failures: 1 errors among 1 request at org.sonar.server.es.BulkIndexer.execute(BulkIndexer.java:...) at org.sonar.server.es.Indexer.index(Indexer.java:...) Caused by: org.elasticsearch.index.mapper.MapperParsingException: failed to parse field [message] ... Caused by: java.lang.IllegalArgumentException: Document contains at least one immense term in field="message" (whose UTF8 encoding is longer than the max length 32766)

看到 Caused by 这一串，才算真正找到病因。

2.2 用 grep 把底层异常找出来

日志文件可能很大，没法用编辑器直接翻。直接用命令行过滤：

# 先看启动过程的最后几百行 tail -n 500 logs/sonar.log # 在 es.log 里找底层 ES 异常 grep -n -E "max_bytes_length_exceeded|mapper_parsing_exception|disk_watermark|read_only_allow_delete|illegal_argument_exception" logs/es.log

max_bytes_length_exceeded_exception是最常见的一种。它来自 ES 底层机制：一个被索引的字段中，单个 token 的 UTF-8 编码长度不能超过 32766 字节。一旦超长，ES 会拒绝整个文档写入，而不是截断后继续。

如果 es.log 里出现的是类似blocked by: [FORBIDDEN/12/index read-only / allow delete (api)]这样的内容，那多半是磁盘空间触发了 ES 的自动只读保护。这种情况常见于数据盘空间不足，ES 为了保证集群不崩会主动拒绝写入。

2.3 用日志中的文档 ID 回查数据库，锁定问题记录

ES 日志里的报错通常还会带上失败的文档 ID，比如id [AeRxyYgBzhXK...]。这个 ID 一般就是 SonarQube 业务表里的主键或 UUID。拿到它之后，可以直接去数据库里定位：

SELECT id, uuid, project_uuid, status, message FROM issues WHERE uuid = 'AeRxyYgBzhXK...';

如果没有文档 ID，或者日志里没写清楚，另一条更稳的路径是通过计算引擎任务表反查。分析完成后，后台任务会把完整错误信息写到 ce_activity 表：

SELECT ca.id, ca.task_type, ca.component_uuid, ca.status, ca.error_message, ca.submitted_at FROM ce_activity ca ORDER BY ca.submitted_at DESC LIMIT 10;

拿到component_uuid后，再去 components 表里查项目名：

SELECT c.kee, c.name, c.qualifier FROM components c WHERE c.uuid = '具体uuid';

这个反查链路很关键。因为大部分情况下，我们需要的不是"重建所有索引"这种大招，而是"找到那个让索引失败的项目或 issue，然后单独处理它"。

2.4 区分启动阶段失败和计算引擎任务失败

同样一个报错，触发上下文不一样，处理侧重点也不同。

如果是在 SonarQube 启动时打印的，通常发生在系统启动后的"恢复索引"阶段。此时 ES 会因为之前遗留的索引状态和数据问题拒绝写入，导致启动流程无法完成。这种场景下，重置索引往往是最快的解法。

如果是在分析项目后，页面已能打开，但 ce.log 里反复出现这个报错，说明问题由某个具体项目触发。此时不需要重启，更不应该无脑清空所有索引，而是应该顺着 2.3 节的 SQL 找到那个项目，看它最近一次分析是否成功、失败报告是什么。

我见过有人在这种场景下直接把 data/es 整个删了，结果重新索引后问题依旧，因为触发问题的数据还在数据库里，重新索引照样失败。这就是典型的"没定位就动手"。

3. 按根因分头修复：从磁盘、超长字段到重建索引

3.1 磁盘问题：清理空间并解除索引只读块

如果 es.log 里看到FORBIDDEN/12/index read-only / allow delete (api)或 disk watermark 相关内容，第一件事是检查磁盘：

df -h

ES 会在数据盘使用率达到一定阈值后自动给索引加只读块。默认是 85% 触发 low watermark，90% 触发 high watermark，95% 直接变为只读。SonarQube 内嵌 ES 写入失败时，就有很大概率触发这个保护机制。

处理方式：清理磁盘空间，把日志、镜像、旧备份该删的删掉。磁盘恢复正常后，ES 不一定自动解除只读块，尤其在高版本 ES 中，这个块需要手动移除。如果 SonarQube 的内嵌 ES 端口对外可用，可以直接操作：

curl -X PUT "http://localhost:9200/_all/_settings" -H 'Content-Type: application/json' -d '{"index.blocks.read_only_allow_delete": null}'

如果 ES 端口没开放，更实际的做法是：清出足够空间后，重启 SonarQube。启动时 ES 会重新检查索引状态，如果磁盘恢复正常，索引会回到可写状态。重启前记得先确认磁盘空间真的够，否则会陷入"启动-写满-报错-再启动"的循环。

这类问题的根本解法是扩容或建立磁盘监控，而不是指望 ES 每次都能扛住。

3.2 超长字段：定位项目、关闭插件与数据库急救的取舍

如果 es.log 明确出现max_bytes_length_exceeded_exception，那问题几乎都出在某个超长字段上。SonarQube 里最容易出现超长字段的地方是 issue 的 message，其次是外部问题（external issue）的描述内容。

我遇到的最典型场景是：项目接入了第三方静态分析工具，通过 SonarQube 的外部问题机制上报 issue。工具输出的提示信息带了一整段代码，或者把整个编译日志塞了进去，某一条 message 轻松超过 30KB。索引器去写 ES 时，直接触发单个 term 超长限制。

定位超长记录最直接的方式，是去数据库按字节长度排一下：

-- PostgreSQL 下用 octet_length 统计字节数 SELECT id, project_uuid, status, octet_length(message) AS msg_bytes FROM issues WHERE octet_length(message) > 30000 ORDER BY msg_bytes DESC LIMIT 20;

如果是 MySQL，用LENGTH()；如果是 Oracle，用LENGTHB()。逻辑一样：找出 message 字段超过 30000 字节的 issue。

找到之后，按问题记录的归属项目缩小范围。常见处理路径有三种：

1. 清源头：如果超长内容来自某个特定插件或外部规则，在项目设置里关闭对应规则，或下线插件。注意，这只能阻止新问题继续产生，已存在的超长 issue 还在数据库里，下次索引任务照样会撞上它。

2. 清历史数据：通过界面删除对应项目，再重新执行分析。这是最干净的做法，但代价是丢失该项目在 SonarQube 里的历史状态记录。分析结果会在下次分析时重新生成。

3. 数据库急救：在备份前提下，把超长 message 手动截断，然后重启服务或触发索引重建。这个方法只建议在测试环境或紧急恢复时用，因为直接改 SonarQube 数据库里的业务数据，并不在官方支持范围内。

很多人容易犯一个错误：看到超长字段立刻去删 data/es。删完之后问题不解决，因为数据库里的超长记录还在。所以这个场景的核心逻辑是：数据库里有什么，ES 重建之后就还会有什么。想绕过，必须先把数据库里的污染源处理掉。

3.3 升级残留和 mapping 损坏：用 api/system/reset 重建索引

如果这个报错出现在 SonarQube 跨大版本升级后，比如从 8.x 升到 9.x，或者升到 10.x，那大概率是旧版本的 ES 索引和新版本不兼容导致的写入失败。这种场景下，底层异常可能是各种mapper_parsing_exception，也可能直接是 ES 启动时加载旧索引失败。

对于这类问题，与其去猜哪条数据坏了，不如直接重建全部索引。SonarQube 提供了系统重置接口：

curl -X POST -u "$SONAR_TOKEN:" "$SONAR_URL/api/system/reset"

这个接口会重置内部搜索引擎数据，然后从数据库重新构建索引。调用前确认你有管理员权限，且明白一点：重置的是索引副本，不是数据库。重置后不影响项目分析结果和历史统计数据，但全量重建期间，界面上的搜索和部分查询可能会变慢或暂时不可用。

如果接口调用不成功，也不用慌，可以用下面 3.4 节的手动方案，效果是一样的。

3.4 最后兜底：备份并移除 data/es 目录

手动删除 ES 数据目录，是社区里流传最广的兜底方案。操作步骤如下：

# 停服务 systemctl stop sonar # 找到 ES 数据目录 # 不同版本可能有差异，常见路径是 data/es，老版本可能是 data/search_0 cd $SONARQUBE_HOME ls -la data/ # 先备份再删除，别直接删 mv data/es data/es.bak.$(date +%Y%m%d%H%M) # 启动 systemctl start sonar # 观察日志 tail -f logs/sonar.log

服务启动后，SonarQube 会检测到索引数据不存在，自动从数据库重建。数据量小的话几分钟就完成，数据量大可能要一两个小时。期间日志里能看到类似Index [issues] has been created的信息，属正常现象。

需要特别注意的是：这个操作是用来兜底的，不是用来乱用的。只有在已经确认底层是索引数据损坏、mapping 冲突、升级遗留等无法通过业务数据层面解决时，才适合走到这一步。如果问题根源是超长字段，删完目录依然失败；如果问题根源是磁盘空间，删完目录甚至可能让启动过程因为磁盘满了直接挂掉。

也就是说，动手前先想清楚：我到底是在修数据问题，还是在修索引问题？两类问题的手段完全不同。

4. 重建之后的验证与回归：别以为服务起来就万事大吉

4.1 索引状态接口：区分 UPDATING 和 READY

重建完成后，服务能打开只是一个开始。要确认所有索引真正就绪，需要调用系统状态接口：

curl -s -u "$SONAR_TOKEN:" "$SONAR_URL/api/system/status" curl -s -u "$SONAR_TOKEN:" "$SONAR_URL/api/system/indexes"

看 indices 接口的返回，重点观察每个索引的状态。常见状态有 UPDATING 和 READY 两种。UPDATING 说明引擎还在从数据库加载数据、构建文档，此时界面上的搜索可能不全；等所有索引都变成 READY，才表示恢复完成。

如果某一个索引在很长一段时间内都是 UPDATING，或者重建后仍出现新的 Unrecoverable 报错，说明数据库里仍存在让写入失败的数据。这时要回到第 2 章排查链路，把失败文档找出来，在业务层面处理，再触发一次重建。

4.2 在 UI 里验证搜索和分析链路

索引状态接口返回 READY 后，建议再做一轮功能验证：

• 打开项目列表页，确认能列出所有项目；
• 随便进一个项目，搜索 issue 关键字，确认能正常出结果；
• 打开质量问题页，看 issue 列表是否完整；
• 看一次代码扫描任务，确认分析结果能正常提交。

其中第四点最重要。因为索引只是搜索层，如果新分析任务提交结果后仍然报 Unrecoverable，那说明问题还在，只是还没被触发。

4.3 重建期间的禁忌：反复重启只会拖长流程

全量重建索引是一个相对漫长的过程。我见过有人启动后看到日志里半天没动静，忍不住又停了服务，手动清理，再启动，来回折腾好几次，结果重建流程一直被中断，越弄越乱。

正确的做法是：启动后，让服务安静地跑。通过日志观察进度，通过状态接口确认结果。只要日志里没有继续堆出相同的 IllegalStateException，就不要因为"慢"去打断它。

如果确实等了几个小时都没有进展，再去翻日志，看是卡在哪个索引上。大部分"卡住"，背后都有一个明确的业务数据问题在等着你处理。

5. 一次完整处置记录：从看到报错到恢复的全过程

5.1 现场：升级重启后起不来，日志只给了这个异常

某个内部项目组找到我时，SonarQube 已经处于启动即失败的状态。他们刚从 9.x 升到 10.x，重启服务后，sonar.log 里能看到这句报错：

java.lang.IllegalStateException: Unrecoverable indexation failures: 1 errors among 1 request

项目组已经试过重启两次，没有效果，页面一直打不开。这个症状符合"升级后索引不兼容 + 数据写入失败"的特征。

5.2 梳理日志定位到超长字段

我先打开 es.log，在里面搜底层异常，很快就看到：

Caused by: java.lang.IllegalArgumentException: Document contains at least one immense term in field="message" (whose UTF8 encoding is longer than the max length 32766)

说明问题不在升级，而是一条超长的 issue message 在升级后全量索引时被卡住了。随后我在数据库里用同样的查询方式，按 message 字节长度倒序排，找到了那条超过 3 万字节的记录，确认属于某个接入外部问题的项目。再去 ce_activity 表里查那个项目最近的任务，发现端倪基本吻合。

5.3 处理与回访：后续如何避免

因为该项目的问题在于外部工具上报了过长信息，属于个例，我们最终选择了删除这个项目、停止接入该外部工具，然后调用/api/system/reset重置索引。服务正常起来后，重新分析了一个测试项目，确认搜索和指标展示都恢复。

事后给项目组的建议是：外部工具接入时，先确认 issue message 的长度边界；如果工具没有截断机制，需要在项目侧预处理；同时把磁盘使用率和 es.log 的底层异常纳入监控，不至于报错了才发现。

整体复盘下来，这个场景里最值得记住的一点是：先在 es.log 里找 Caused by，再看数据库定位污染源，最后选择从轻到重的处理手段。顺序反了，多半要白折腾几个小时。

最后再分享一个我的个人习惯：每次处理完这类问题，我会把 es.log 里跟索引失败相关的异常关键字收集到一个速查表里，下次再见到类似报错时，第一眼就能判断是重试问题、数据问题，还是状态问题。这个习惯帮我省下过不少时间，也推荐你做一份自己的速查表。