kongdeqiang
2026-10-12 7c687dd3c8fba9f7632f5e29d94a708e5f497abd
src/main/java/com/custom/webui/config/StartupDiagnostics.java
@@ -1,37 +1,94 @@
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;
/**
 * 启动自检:把关键数据的**实际落盘位置**打进启动日志。
 * 启动自检:把两个**只在运行时才暴露、且报错信息会把人带偏**的配置项
 * 在启动日志里说清楚。
 *
 * <p><b>为什么需要它</b>:{@code webui.storage.location} 是相对路径,
 * 相对路径按「进程工作目录」解析,而工作目录随启动方式变化 ——
 * 在 IDE 里以 webui-springboot 为工作目录启动,和从项目根目录
 * {@code java -jar} 启动,会指向两个不同的目录。
 *
 * <p>这个差异不会在启动时报任何错,只会在用户真正上传或读取文件时才炸,
 * <h2>一、文件落盘位置</h2>
 * {@code webui.storage.location} 是相对路径,相对路径按「进程工作目录」解析,
 * 而工作目录随启动方式变化 —— 在 IDE 里以 webui-springboot 为工作目录启动,
 * 和从项目根目录 {@code java -jar} 启动,会指向两个不同的目录。
 * 这个差异不会在启动时报任何错,只会在用户真正上传或读取文件时才炸,
 * 而且表现为「知识库里的文件找不到」这种极易误判成数据丢失的现象。
 * 把路径在启动时就打出来,问题一眼可见。
 *
 * <p>这只是**可观测性**措施,不是校验门禁:目录不存在也不阻断启动 ——
 * 首次上传会自动创建,硬失败反而会把「只是想先起个服务看看」的人挡在门外。
 * <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;
    private final com.custom.webui.util.PdfFontSupport pdfFontSupport;
    // ------------------------------------------------------------------
    // 一、存储位置
    // ------------------------------------------------------------------
    @EventListener(ApplicationReadyEvent.class)
    public void reportStorageLocations() {
@@ -44,6 +101,9 @@
        log.info("  配置值       : {}", storageProperties.getLocation());
        log.info("  实际上传目录 : {}", uploadRoot);
        log.info("  目录状态     : {}", describe(uploadRoot));
        // 顺便报一下 PDF 导出的字体:找不到中文字体时 PDF 导出会失败,
        // 而这件事在启动时说一句,比等用户点了「下载 PDF」再报错友好得多
        log.info("  导出自检     : {}", pdfFontSupport.describe());
        log.info("=".repeat(66));
    }
@@ -61,4 +121,373 @@
        }
        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) {
    }
}