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