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; /** * 启动自检:把两个**只在运行时才暴露、且报错信息会把人带偏**的配置项 * 在启动日志里说清楚。 * *

一、文件落盘位置

* {@code webui.storage.location} 是相对路径,相对路径按「进程工作目录」解析, * 而工作目录随启动方式变化 —— 在 IDE 里以 webui-springboot 为工作目录启动, * 和从项目根目录 {@code java -jar} 启动,会指向两个不同的目录。 * 这个差异不会在启动时报任何错,只会在用户真正上传或读取文件时才炸, * 而且表现为「知识库里的文件找不到」这种极易误判成数据丢失的现象。 * *

二、LLM 服务地址与协议是否匹配

* 这是本类存在的主要理由。项目里真实踩过一次,现象是: *
 *   前端提示:LLM 服务返回错误 (HTTP 404)。请确认模型 qwen35 已通过 `ollama pull` 下载。
 * 
* 但真实原因是:{@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},方向完全错了。 * *

两种协议长得像但互不兼容: * * * * *
provider路径默认地址响应格式
ollamaPOST /api/chat:11434NDJSON(每行一个 JSON)
openai-compatPOST /v1/chat/completions:8000/v1SSE(data: {...})
* *

所以启动时主动探一次:地址通不通、协议对不对、配置的模型在不在 * 服务返回的模型列表里。**不阻断启动** —— 这只是可观测性措施, * 硬失败会把「只想先起个服务看看」的人挡在门外;但日志里会明确写出 * 怎么改,不用再去猜。 */ @Slf4j @Component @RequiredArgsConstructor public class StartupDiagnostics { /** * 探测超时。 * *

给 5 秒而不是 1~2 秒:实测 10020 上那个转发器在冷启动或正忙时, * {@code /v1/models} 可能 2 秒内不返回 —— 而与此同时真正的对话请求 * 完全正常。**自检报假警比不报更糟**:用户会照着「服务似乎没有启动」 * 去排查一个根本不存在的问题,这正是本项目已经踩过一次的坑。 * *

超时也不等同于不可用,所以超时单独措辞(见 {@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() { 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)); // 顺便报一下 PDF 导出的字体:找不到中文字体时 PDF 导出会失败, // 而这件事在启动时说一句,比等用户点了「下载 PDF」再报错友好得多 log.info(" 导出自检 : {}", pdfFontSupport.describe()); 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 的**生效来源**,只用于日志展示。 * *

优先级从高到低: *

    *
  1. JVM 系统属性 {@code -Dwebui.llm.provider=...}
  2. *
  3. 环境变量 {@code WEBUI_LLM_PROVIDER=...}
  4. *
  5. application.yml / application-{profile}.yml
  6. *
*/ 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}。 * *

为什么必须有这段:踩过一次很难受的坑 —— 用户已经把 * application.yml 改成 {@code provider: ${WEBUI_LLM_PROVIDER:openai-compat}}, * 重启后却**仍然在用 ollama**。原因是 IDE 的 Run Configuration 里 * 留着 {@code -Dwebui.llm.provider=ollama}: * *

系统属性({@code -D})与 OS 环境变量都属于 Spring Boot 的 * 外部化配置,优先级**高于**任何 application.yml —— * 于是 yml 里那一行被静默压住,怎么改都没反应,而且不报任何错。 * 用户能看到的只有「配置改了但没生效」,很容易怀疑到代码或缓存上。 * *

所以这里直接把生效来源和怎么改写在日志里。 */ 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}。 * *

这两个环境变量会被 **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 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 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 /}。 * *

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 /models}。 * *

选 {@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 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」时该怎么说。 * *

这里刻意把「以 /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 parseModelIds(String body) { List 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。 * *

用 {@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) { } }