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; /** * 启动自检:把两个**只在运行时才暴露、且报错信息会把人带偏**的配置项 * 在启动日志里说清楚。 * *
* 前端提示: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 | 路径 | 默认地址 | 响应格式 |
|---|---|---|---|
| ollama | POST /api/chat | :11434 | NDJSON(每行一个 JSON) |
| openai-compat | POST /v1/chat/completions | :8000/v1 | SSE(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 的**生效来源**,只用于日志展示。 * *
优先级从高到低: *
为什么必须有这段:踩过一次很难受的坑 —— 用户已经把 * 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 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 选 {@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 这里刻意把「以 /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 用 {@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) {
}
}