kongdeqiang
2026-10-10 ad24c871d74a417db5412fd9d1fa60411c33ae7f
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
package com.custom.webui.config;
 
import com.custom.webui.config.props.LlmProperties;
import com.custom.webui.config.props.StorageProperties;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.boot.context.event.ApplicationReadyEvent;
import org.springframework.context.event.EventListener;
import org.springframework.stereotype.Component;
 
import java.io.InputStream;
import java.net.HttpURLConnection;
import java.net.URI;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.util.ArrayList;
import java.util.List;
 
/**
 * 启动自检:把两个**只在运行时才暴露、且报错信息会把人带偏**的配置项
 * 在启动日志里说清楚。
 *
 * <h2>一、文件落盘位置</h2>
 * {@code webui.storage.location} 是相对路径,相对路径按「进程工作目录」解析,
 * 而工作目录随启动方式变化 —— 在 IDE 里以 webui-springboot 为工作目录启动,
 * 和从项目根目录 {@code java -jar} 启动,会指向两个不同的目录。
 * 这个差异不会在启动时报任何错,只会在用户真正上传或读取文件时才炸,
 * 而且表现为「知识库里的文件找不到」这种极易误判成数据丢失的现象。
 *
 * <h2>二、LLM 服务地址与协议是否匹配</h2>
 * 这是本类存在的主要理由。项目里真实踩过一次,现象是:
 * <pre>
 *   前端提示:LLM 服务返回错误 (HTTP 404)。请确认模型 qwen35 已通过 `ollama pull` 下载。
 * </pre>
 * 但真实原因是:{@code webui.llm.provider=ollama}(被 IDE 的
 * {@code -D} 参数钉死的)配上了一个 **OpenAI 兼容服务**的地址,
 * 于是后端去请求 {@code http://127.0.0.1:10020/api/chat} ——
 * 那个地址只有 {@code /v1/chat/completions},没有 {@code /api/chat},
 * 返回 404。提示却让人去 {@code ollama pull},方向完全错了。
 *
 * <p>两种协议长得像但互不兼容:
 * <table border="1">
 *   <tr><th>provider</th><th>路径</th><th>默认地址</th><th>响应格式</th></tr>
 *   <tr><td>ollama</td><td>POST /api/chat</td><td>:11434</td><td>NDJSON(每行一个 JSON)</td></tr>
 *   <tr><td>openai-compat</td><td>POST /v1/chat/completions</td><td>:8000/v1</td><td>SSE(data: {...})</td></tr>
 * </table>
 *
 * <p>所以启动时主动探一次:地址通不通、协议对不对、配置的模型在不在
 * 服务返回的模型列表里。**不阻断启动** —— 这只是可观测性措施,
 * 硬失败会把「只想先起个服务看看」的人挡在门外;但日志里会明确写出
 * 怎么改,不用再去猜。
 */
@Slf4j
@Component
@RequiredArgsConstructor
public class StartupDiagnostics {
 
    /**
     * 探测超时。
     *
     * <p>给 5 秒而不是 1~2 秒:实测 10020 上那个转发器在冷启动或正忙时,
     * {@code /v1/models} 可能 2 秒内不返回 —— 而与此同时真正的对话请求
     * 完全正常。**自检报假警比不报更糟**:用户会照着「服务似乎没有启动」
     * 去排查一个根本不存在的问题,这正是本项目已经踩过一次的坑。
     *
     * <p>超时也不等同于不可用,所以超时单独措辞(见 {@link Check})。
     * 又不能给太大:自检是「顺手看一眼」的辅助信息,不该把启动拖住。
     */
    private static final int PROBE_TIMEOUT_MILLIS = 5000;
 
    /** 日志里最多列几个模型名,太多会刷屏 */
    private static final int MAX_MODELS_IN_LOG = 8;
 
    /** provider 对应的配置键(system property / 配置文件里都是这个名字) */
    private static final String KEY_PROVIDER = "webui.llm.provider";
 
    /** provider 对应的环境变量名(application.yml 里写的是 ${WEBUI_LLM_PROVIDER:...}) */
    private static final String ENV_PROVIDER = "WEBUI_LLM_PROVIDER";
 
    private final StorageProperties storageProperties;
    private final LlmProperties llmProperties;
    private final ObjectMapper objectMapper;
 
    // ------------------------------------------------------------------
    // 一、存储位置
    // ------------------------------------------------------------------
 
    @EventListener(ApplicationReadyEvent.class)
    public void reportStorageLocations() {
        Path cwd = Paths.get("").toAbsolutePath().normalize();
        Path uploadRoot = Paths.get(storageProperties.getLocation()).toAbsolutePath().normalize();
 
        log.info("=".repeat(66));
        log.info("存储位置自检(如需固定位置,请把 webui.storage.location 配成绝对路径)");
        log.info("  进程工作目录 : {}", cwd);
        log.info("  配置值       : {}", storageProperties.getLocation());
        log.info("  实际上传目录 : {}", uploadRoot);
        log.info("  目录状态     : {}", describe(uploadRoot));
        log.info("=".repeat(66));
    }
 
    private String describe(Path path) {
        if (Files.isDirectory(path)) {
            try (var stream = Files.walk(path, 4)) {
                long files = stream.filter(Files::isRegularFile).count();
                return "已存在,含 " + files + " 个文件";
            } catch (Exception e) {
                return "已存在,但统计文件数失败: " + e.getMessage();
            }
        }
        if (Files.exists(path)) {
            return "存在但不是目录(配置有误)";
        }
        return "尚不存在,首次上传时会自动创建";
    }
 
    // ------------------------------------------------------------------
    // 二、LLM 服务
    // ------------------------------------------------------------------
 
    @EventListener(ApplicationReadyEvent.class)
    public void reportLlmEndpoint() {
        String provider = llmProperties.getProvider();
        String shadowWarning = providerShadowWarning();
 
        log.info("=".repeat(66));
 
        if ("mock".equalsIgnoreCase(provider)) {
            log.info("LLM 自检:provider=mock —— 不调用任何真实模型,回复由本地模拟器生成");
            log.info("  配置来源 : {}", providerSource());
            log.info("=".repeat(66));
            return;
        }
 
        // 只有这两个取值会走到这里:mock 已在上面返回,
        // 其余取值在 Spring 阶段就会因为找不到 LlmService Bean 而启动失败。
        boolean useOllama = "ollama".equalsIgnoreCase(provider);
        String baseUrl = useOllama
                ? llmProperties.getOllama().getBaseUrl()
                : llmProperties.getOpenaiCompat().getBaseUrl();
        String model = useOllama
                ? llmProperties.getOllama().getDefaultModel()
                : llmProperties.getOpenaiCompat().getModel();
        String chatPath = useOllama ? "/api/chat" : "/chat/completions";
 
        log.info("LLM 自检(provider={})", provider);
        log.info("  配置来源 : {}", providerSource());
        // 把所有能盖住配置文件的来源都摊开打出来。
        // 排查「改了 yml 不生效」时,用户和我们都无法直接看到 JVM 收到了哪些
        // 外部参数 —— 尤其当 IDE 界面里根本找不到那个 -D 的时候。
        // 这里一次性列全,省掉反复猜的来回。
        String sysOverrides = describeSystemPropertyOverrides();
        if (sysOverrides != null) {
            log.info("  系统属性覆盖 : {}", sysOverrides);
        }
        String envOverrides = describeEnvOverrides();
        if (envOverrides != null) {
            log.info("  环境变量覆盖 : {}", envOverrides);
        }
        log.info("  对话地址 : {}{}", trimTrailingSlash(baseUrl), chatPath);
        log.info("  默认模型 : {}", model);
 
        if (shadowWarning != null) {
            // 优先于连通性告警打出来:这是「改了配置却不生效」的根因,
            // 不先说清楚,用户会去怀疑网络、模型、代码,而不会想到 -D 参数
            log.warn("  ⚠️  {}", shadowWarning);
        }
 
        Check check = useOllama ? checkOllama(baseUrl) : checkOpenAiCompat(baseUrl);
        log.info("  连通性   : {}", check.summary());
        if (check.advice() != null) {
            log.warn("  ⚠️  {}", check.advice());
        }
        log.info("=".repeat(66));
    }
 
    /**
     * provider 的**生效来源**,只用于日志展示。
     *
     * <p>优先级从高到低:
     * <ol>
     *   <li>JVM 系统属性 {@code -Dwebui.llm.provider=...}</li>
     *   <li>环境变量 {@code WEBUI_LLM_PROVIDER=...}</li>
     *   <li>application.yml / application-{profile}.yml</li>
     * </ol>
     */
    private String providerSource() {
        if (isSet(System.getProperty(KEY_PROVIDER))) {
            return "JVM 系统属性 -D" + KEY_PROVIDER;
        }
        if (isSet(System.getenv(ENV_PROVIDER))) {
            return "环境变量 " + ENV_PROVIDER;
        }
        return "application.yml";
    }
 
    /**
     * 「provider 被外部来源盖住」时给出的警告,没被盖住则返回 {@code null}。
     *
     * <p><b>为什么必须有这段</b>:踩过一次很难受的坑 —— 用户已经把
     * application.yml 改成 {@code provider: ${WEBUI_LLM_PROVIDER:openai-compat}},
     * 重启后却**仍然在用 ollama**。原因是 IDE 的 Run Configuration 里
     * 留着 {@code -Dwebui.llm.provider=ollama}:
     *
     * <p>系统属性({@code -D})与 OS 环境变量都属于 Spring Boot 的
     * <b>外部化配置</b>,优先级**高于**任何 application.yml ——
     * 于是 yml 里那一行被静默压住,怎么改都没反应,而且不报任何错。
     * 用户能看到的只有「配置改了但没生效」,很容易怀疑到代码或缓存上。
     *
     * <p>所以这里直接把生效来源和怎么改写在日志里。
     */
    private String providerShadowWarning() {
        String flag = System.getProperty(KEY_PROVIDER);
        if (isSet(flag)) {
            String hint = "。系统属性优先级高于所有配置文件 —— "
                    + "你在 application.yml 里把 provider 改成什么都不生效,这一行被静默盖住了。";
            String toolOptions = toolOptionsHint();
            if (toolOptions != null) {
                // 这种情况 IDE 界面里**根本找不到**那个 -D,必须单独说明来源
                hint = hint + toolOptions;
            } else {
                hint = hint + "IDE 用户请打开 Run → Edit Configurations…,"
                        + "在选中配置的 VM options 里删掉这个 -D 参数,然后重启;"
                        + "若界面上确实找不到它,请把上一行「系统属性覆盖」与下面的环境变量一起核对。";
            }
            return "provider 的值来自 JVM 系统属性 -D" + KEY_PROVIDER + "=" + flag + hint;
        }
        String env = System.getenv(ENV_PROVIDER);
        if (isSet(env)) {
            return "provider 的值来自环境变量 " + ENV_PROVIDER + "=" + env
                    + "。环境变量优先级高于 application.yml,改 yml 不生效。"
                    + "请从环境变量里去掉它,或直接改这个变量的值。";
        }
        return null;
    }
 
    /**
     * 如果 {@code -D} 其实是 {@code JAVA_TOOL_OPTIONS} / {@code _JAVA_OPTIONS}
     * 塞进来的,给出对应说明,否则返回 {@code null}。
     *
     * <p>这两个环境变量会被 **JVM 自动注入到所有 java 进程**的命令行里,
     * 表现为「多出来一堆 -D 参数,但 IDE 的 Run Configuration 里怎么找都找不到」。
     * 排查时这是最容易漏掉的一条路径 —— 因为它根本不在 IDE 里,
     * 而在 IDE 进程自己的环境变量里(通常是 `launchctl setenv` 或 shell rc 设的)。
     */
    private String toolOptionsHint() {
        for (String key : new String[]{"JAVA_TOOL_OPTIONS", "_JAVA_OPTIONS"}) {
            String value = System.getenv(key);
            if (isSet(value) && value.contains(KEY_PROVIDER)) {
                return "注意:这个 -D 是环境变量 " + key + " 注入的"
                        + "(当前值:" + value + "),它会被 JVM 自动加到**所有** java 进程上,"
                        + "所以你在 Edit Configurations 里永远找不到它。"
                        + "请清除这个环境变量后重启 IDE(`launchctl unsetenv " + key + "`"
                        + ",或删掉 shell 配置里的 export)再启动后端。";
            }
        }
        return null;
    }
 
    /** 列出所有以 {@code webui.} 开头的系统属性(即 -D 覆盖项),没有则返回 null */
    private String describeSystemPropertyOverrides() {
        List<String> items = new ArrayList<>();
        for (String key : System.getProperties().stringPropertyNames()) {
            if (key.startsWith("webui.")) {
                items.add(key + "=" + System.getProperty(key));
            }
        }
        if (items.isEmpty()) {
            return null;
        }
        items.sort(String::compareTo);
        return String.join(", ", items);
    }
 
    /** 列出所有与模型服务相关的环境变量(含 JAVA_TOOL_OPTIONS),没有则返回 null */
    private String describeEnvOverrides() {
        List<String> items = new ArrayList<>();
        for (String key : System.getenv().keySet()) {
            boolean relevant = key.startsWith("WEBUI_")
                    || key.startsWith("OLLAMA_")
                    || key.startsWith("OPENAI_COMPAT_")
                    || "JAVA_TOOL_OPTIONS".equals(key)
                    || "_JAVA_OPTIONS".equals(key)
                    || "MAVEN_OPTS".equals(key);
            if (relevant) {
                String value = System.getenv(key);
                // 密钥类只显示长度,避免把 API Key 写进日志
                if (key.contains("KEY") || key.contains("SECRET") || key.contains("TOKEN")) {
                    value = "***(长度 " + (value == null ? 0 : value.length()) + ")";
                }
                items.add(key + "=" + value);
            }
        }
        if (items.isEmpty()) {
            return null;
        }
        items.sort(String::compareTo);
        return String.join(", ", items);
    }
 
    private boolean isSet(String value) {
        return value != null && !value.isBlank();
    }
 
    /**
     * provider=ollama:探 {@code GET <baseUrl>/}。
     *
     * <p>Ollama 守护进程的根路径会返回一行纯文本 {@code Ollama is running},
     * 这是最省的识别方式(不用真的跑一次推理)。
     */
    private Check checkOllama(String baseUrl) {
        Response resp = get(trimTrailingSlash(baseUrl) + "/");
        if (resp.timeout()) {
            return Check.ok("探测超时(" + baseUrl + ")—— 不代表不可用,"
                    + "可能只是 Ollama 正忙或正在加载模型");
        }
        if (resp.failure() != null) {
            return new Check("连不上 " + baseUrl + "(" + resp.failure() + ")",
                    "Ollama 似乎没有启动。先执行 `ollama serve`;"
                            + "若要被本机其他进程访问,可加 OLLAMA_HOST=0.0.0.0。"
                            + "若你其实想用的是 OpenAI 兼容服务,请把 webui.llm.provider 改成 openai-compat。");
        }
        if (resp.status() == 200 && resp.body().contains("Ollama is running")) {
            return Check.ok("正常,Ollama 已就绪");
        }
        return new Check("HTTP " + resp.status() + ",但返回内容不是 Ollama 的标识文本:" + preview(resp.body()),
                protocolMismatchAdvice(baseUrl));
    }
 
    /**
     * provider=openai-compat:探 {@code GET <baseUrl>/models}。
     *
     * <p>选 {@code /models} 而不是直接发一次 chat 请求,是因为它顺带能拿到
     * **可用模型列表** —— 这样「模型名写错 / 模型没下载」这类问题也能在
     * 启动时就发现,而不是等用户点开对话才看到报错。
     */
    private Check checkOpenAiCompat(String baseUrl) {
        String modelsUrl = trimTrailingSlash(baseUrl) + "/models";
        Response resp = get(modelsUrl);
        if (resp.timeout()) {
            // 实测:转发型网关在冷启动/繁忙时 /models 可能超时,而对话请求本身是正常的。
            // 所以这里不下「服务没启动」的结论,避免自检自己制造假故障。
            return Check.ok("探测超时(" + modelsUrl + " 在 "
                    + PROBE_TIMEOUT_MILLIS + "ms 内没有响应)—— 不代表不可用,"
                    + "可能只是服务在冷启动或正忙;真实对话若也失败再按下面排查");
        }
        if (resp.failure() != null) {
            return new Check("连不上 " + modelsUrl + "(" + resp.failure() + ")",
                    "模型服务似乎没有启动。本地部署请先把它拉起来;"
                            + "地址不对则改 webui.llm.openaiCompat.base-url(注意要带 /v1)。");
        }
        if (resp.status() != 200) {
            String advice = trimTrailingSlash(baseUrl).endsWith("/v1")
                    ? "地址可达,但没有 /v1/models 接口。请确认这个服务实现了 OpenAI 兼容协议。"
                    : "base-url 需要带上 /v1(例如 http://127.0.0.1:10020/v1),少了它就会 404。";
            return new Check("HTTP " + resp.status() + "," + modelsUrl + " 返回:" + preview(resp.body()), advice);
        }
 
        List<String> models = parseModelIds(resp.body());
        String summary = models.isEmpty()
                ? "正常(服务已就绪,但 /models 没有返回模型列表)"
                : "正常,可用模型:" + String.join(", ", models);
 
        String configured = llmProperties.getOpenaiCompat().getModel();
        if (!models.isEmpty() && configured != null && !configured.isBlank()
                && models.stream().noneMatch(m -> m.equals(configured))) {
            return new Check(summary,
                    "配置的模型「" + configured + "」不在服务返回的模型列表里,"
                            + "对话时会报 model not found。请改 webui.llm.openaiCompat.model"
                            + "(或用环境变量 OPENAI_COMPAT_MODEL 覆盖)。");
        }
        return Check.ok(summary);
    }
 
    /**
     * 地址可达但「不像 Ollama」时该怎么说。
     *
     * <p>这里刻意把「以 /v1 结尾」当成强信号单独提示 ——
     * 项目踩的那个坑正是 base-url 写成了 {@code http://127.0.0.1:10020},
     * 对方是 OpenAI 兼容服务(即便不带 /v1),所以两种说法都给。
     */
    private String protocolMismatchAdvice(String baseUrl) {
        String tail = "当前配置下对话会请求 " + trimTrailingSlash(baseUrl) + "/api/chat,"
                + "对方没有这个路由,会返回 404,而错误提示会误报成「模型未下载」。";
        if (trimTrailingSlash(baseUrl).endsWith("/v1")) {
            return "base-url 以 /v1 结尾,这是 OpenAI 兼容服务的地址,不是 Ollama。"
                    + "请把 webui.llm.provider 改成 openai-compat,"
                    + "或把 webui.llm.ollama.base-url 改回 http://127.0.0.1:11434。" + tail;
        }
        return "这个地址上跑的似乎不是 Ollama(Ollama 原生接口是 /api/chat)。"
                + "若对方是 OpenAI 兼容服务(vLLM / LM Studio / SGLang / one-api 等),"
                + "请把 webui.llm.provider 设为 openai-compat,并把 base-url 配成以 /v1 结尾的地址。" + tail;
    }
 
    /** 从 {@code {"data":[{"id":"qwen35"},...]}} 里取模型名,取不到就返回空列表 */
    private List<String> parseModelIds(String body) {
        List<String> ids = new ArrayList<>();
        try {
            JsonNode data = objectMapper.readTree(body).path("data");
            if (data.isArray()) {
                for (JsonNode item : data) {
                    String id = item.path("id").asText(null);
                    if (id != null && !id.isBlank()) {
                        ids.add(id);
                    }
                    if (ids.size() >= MAX_MODELS_IN_LOG) {
                        ids.add("…");
                        break;
                    }
                }
            }
        } catch (Exception e) {
            log.debug("解析 /models 响应失败,跳过模型列表检查: {}", e.getMessage());
        }
        return ids;
    }
 
    // ------------------------------------------------------------------
    // 极简 HTTP GET
    // ------------------------------------------------------------------
 
    /**
     * 自检用的 GET。
     *
     * <p>用 {@link HttpURLConnection} 而不是项目里别处用的 RestTemplate:
     * 这里只需要一个「拿到状态码和几行文本」的能力,而且必须**绝不抛异常** ——
     * 任何一个自检失败都不该影响启动。
     */
    private Response get(String url) {
        HttpURLConnection conn = null;
        try {
            conn = (HttpURLConnection) URI.create(url).toURL().openConnection();
            conn.setRequestMethod("GET");
            conn.setConnectTimeout(PROBE_TIMEOUT_MILLIS);
            conn.setReadTimeout(PROBE_TIMEOUT_MILLIS);
            int status = conn.getResponseCode();
            InputStream in = status >= 400 ? conn.getErrorStream() : conn.getInputStream();
            String body = in == null ? "" : new String(in.readAllBytes(), StandardCharsets.UTF_8);
            return new Response(status, body, null, false);
        } catch (java.net.SocketTimeoutException e) {
            // 单独识别超时:它和「连接被拒」是完全不同的结论,
            // 混在一起会让人误以为服务没起(实测踩过,见 PROBE_TIMEOUT_MILLIS 的注释)
            return new Response(-1, "", "超时(" + PROBE_TIMEOUT_MILLIS + "ms 内没有响应)", true);
        } catch (Exception e) {
            // 连接被拒 / DNS 失败等
            return new Response(-1, "", e.getClass().getSimpleName()
                    + (e.getMessage() == null ? "" : ": " + e.getMessage()), false);
        } finally {
            if (conn != null) {
                conn.disconnect();
            }
        }
    }
 
    /** 把响应体压成一行短预览,顺便去掉 NUL 等控制字符(某些服务会返回一长串) */
    private String preview(String body) {
        if (body == null || body.isBlank()) {
            return "(空)";
        }
        String cleaned = body.replaceAll("[\\p{Cntrl}&&[^\r\n\t]]", "").replaceAll("\\s+", " ").trim();
        return cleaned.length() > 120 ? cleaned.substring(0, 120) + "…" : cleaned;
    }
 
    private String trimTrailingSlash(String url) {
        if (url == null) {
            return "";
        }
        String s = url.trim();
        while (s.endsWith("/")) {
            s = s.substring(0, s.length() - 1);
        }
        return s;
    }
 
    /** 单个检查项的结论:一行摘要 + 可选修复建议(有建议时按 WARN 打) */
    private record Check(String summary, String advice) {
        static Check ok(String summary) {
            return new Check(summary, null);
        }
    }
 
    /** 探测结果:failure 非空表示压根没连上;timeout 为 true 时 failure 描述超时 */
    private record Response(int status, String body, String failure, boolean timeout) {
    }
}