附录D 常见问题排查指南

D.1 排障总原则

开发 KnowHub 这类 RAG 平台时，最容易让初学者崩溃的不是某一行代码，而是问题可能出现在很多层：

text 复制代码

前端页面
-> Gateway
-> auth-service
-> knowledge-service
-> task-service
-> MySQL
-> PostgreSQL/pgvector
-> Redis
-> RabbitMQ
-> MinIO
-> 外部 AI 模型

如果没有排查顺序，很容易今天改前端，明天改配置，后天又怀疑数据库，最后把原本能跑的环境也改坏。

本附录只解决一个问题：

text 复制代码

出现故障时，先看哪里，后看哪里。

推荐顺序如下：

text 复制代码

1. 看请求有没有到入口
2. 看服务是否启动
3. 看配置是否生效
4. 看数据库或缓存中有没有状态变化
5. 看依赖组件是否正常
6. 看日志里的错误码和异常堆栈
7. 最后再修改代码

不要一上来就重装环境，也不要一看到报错就同时改很多配置。一次只改一个因素，改完再验证。

D.2 启动类问题

D.2.1 Docker Compose 启动失败

现象：

text 复制代码

`docker compose up -d` 失败
容器没有全部启动
某些服务状态是 `Exited` 或 `Restarting`

优先检查：

powershell 复制代码

docker compose ps
docker compose logs mysql
docker compose logs postgres
docker compose logs redis
docker compose logs rabbitmq
docker compose logs minio
docker compose logs nacos

处理办法：

确认 Docker Desktop 已启动。
确认当前目录是项目根目录（rag-platform，Windows 上通常为 D:\rag\rag-platform，Linux 上通常为 /home/rag/rag-platform 或用户自行克隆的路径）。可通过 ls docker-compose.yml 或 dir docker-compose.yml 验证当前目录是否正确。如果文件不存在，说明终端不在项目根目录。
确认 .env 已从 .env.example 复制出来。
确认端口没有被本机其他程序占用。
内存不足时，不要同时打开太多 IDE、浏览器、数据库工具。
如果 Docker 容器全部启动后系统内存接近满载（可通过任务管理器或 free -h 查看），可以临时停掉不需要的容器。例如如果当前只测登录接口，可以只保留 MySQL 和 Nacos：docker compose stop postgres redis rabbitmq minio。需要时再执行 docker compose start postgres redis rabbitmq minio 恢复。如果内存在 8GB 以下，建议将基础设施迁移到 Linux 虚拟机，详见第 19 章 19.7 节。

如果容器一直重启，不要只看 ps，要看对应容器日志。ps 只能告诉你结果，logs 才能告诉你原因。

D.2.2 端口占用

现象：

text 复制代码

Bind for 0.0.0.0:3306 failed
port is already allocated
Web server failed to start. Port xxxx was already in use

优先检查：

powershell 复制代码

netstat -ano | findstr :3306
netstat -ano | findstr :5432
netstat -ano | findstr :6379
netstat -ano | findstr :8848
netstat -ano | findstr :9001
netstat -ano | findstr :9002

处理办法：

MySQL 常见端口：3306
PostgreSQL 常见端口：5432
Redis 常见端口：6379
Nacos 常见端口：8848
RabbitMQ 常见端口：5672、15672
MinIO 常见端口：9001、9002

如果本机已经装过 MySQL 或 Redis，要么停掉本机服务，要么修改 Compose 映射端口和应用配置。

D.2.3 Nacos 无法访问

现象：

text 复制代码

浏览器打不开 http://localhost:8848/nacos
微服务启动时报 Nacos 连接失败

优先检查：

powershell 复制代码

docker compose ps nacos
docker compose logs nacos

处理办法：

确认 rag-nacos 容器状态是 running。
确认端口 8848 没有被占用。
等待 Nacos 完成启动，Nacos 不是容器一启动就立刻可用。
微服务本地启动时，确认配置中的 Nacos 地址指向 localhost:8848 或实际部署地址。

D.2.4 Docker 磁盘空间不足

现象：

text 复制代码

Docker 容器启动失败，日志提示 no space left on device
MinIO 上传文件时报磁盘空间不足
MySQL 或 PostgreSQL 写入时报磁盘满

优先检查：

bash 复制代码

docker system df
df -h
du -sh /var/lib/docker

处理办法：

首先用 docker system df 查看 Docker 占用的磁盘空间分布，包括镜像、容器、数据卷和构建缓存各占多少。

可以清理未使用镜像和停止的容器：

bash 复制代码

docker system prune -a

注意：这会删除停止的容器和未使用的镜像，但不会删除数据卷。

如果数据卷占用过大，例如 MinIO 的 rag-minio-data 或 MySQL 的 rag-mysql-data，不要直接删除整个数据卷。应该先确认哪些文件或数据已经不需要，再进入对应数据卷目录手动清理，或者通过业务接口删除知识库和文档。

如果频繁遇到磁盘不足，建议把 Docker 数据目录迁移到空间更大的磁盘分区，或者定期清理不再需要的测试文档和对应向量数据。

学习阶段上传的测试文档和生成的向量数据会持续占用磁盘空间。建议定期清理不再需要的知识库及其关联的文档、chunk、向量和任务记录。清理时要按链路清理，不要只删一张表。

D.3 网关、登录与权限问题

D.3.1 Gateway 无法访问后端接口

现象：

text 复制代码

前端请求失败
接口返回 404
接口返回 503

优先检查：

text 复制代码

Gateway 是否启动
目标微服务是否启动
Nacos 中是否能看到服务实例
前端请求地址是否走 Gateway

处理办法：

用户端和管理端都应该优先访问 Gateway，而不是直接访问某个业务服务。
如果 Gateway 能启动但转发失败，先看 Nacos 服务注册情况。
如果直接访问业务服务成功、走 Gateway 失败，重点看路由配置和路径前缀。

D.3.2 登录后仍然 401

现象：

text 复制代码

登录成功，但访问知识库接口返回 401
刷新页面后登录态丢失

优先检查：

text 复制代码

前端是否保存 token
Axios 是否携带 Authorization header
Gateway 是否放行登录注册接口
JWT 是否过期
JWT secret 是否一致

处理办法：

打开浏览器开发者工具，查看请求头中有没有 Authorization。
确认格式是 Bearer xxx。
确认 auth-service 生成 Token 的密钥和 Gateway 校验 Token 的密钥一致。
如果清理过浏览器缓存或 localStorage，需要重新登录。

D.3.3 管理端接口返回 403

现象：

text 复制代码

/admin/** 接口返回 403
普通用户登录管理端后看不到数据

优先检查：

text 复制代码

JWT 中 role 是否为 ADMIN
Gateway 的 /admin/** 鉴权是否生效
数据库 user 表中的 role 字段是否正确

处理办法：

管理端不是只要登录就能访问。KnowHub 当前采用基础 USER/ADMIN 角色模型，/admin/** 接口要求 ADMIN。普通 USER 被拒绝是正常结果。

D.3.4 跨用户访问返回 40400

现象：

text 复制代码

userA 访问 userB 的知识库或文档，返回 40400

优先检查：

text 复制代码

当前登录用户是谁
请求的 kbId/documentId 属于谁
Gateway 是否正确透传用户信息
UserContext 是否读取到了 userId

处理办法：

这通常不是 bug，而是资源隔离生效。系统不返回「无权限访问该知识库」，而是返回资源不存在，可以减少资源枚举风险。

D.4 文件上传与 MinIO 问题

D.4.1 文件为空或文件类型不支持

现象：

text 复制代码

上传失败
返回 FILE_EMPTY
返回 FILE_TYPE_NOT_SUPPORTED

优先检查：

text 复制代码

文件是否为空
文件扩展名是否为 txt、md、markdown、PDF
前端 accept 是否限制了文件类型

处理办法：

使用非空的文本文件或 Markdown 文件先验证主流程。
如果要演示 PDF，确认后端解析器支持 PDF，前端上传控件也允许 .pdf。

D.4.2 文件过大

现象：

text 复制代码

返回 FILE_TOO_LARGE
请求直接被拦截

优先检查：

text 复制代码

Spring multipart 配置
Gateway 请求体限制
业务层文件大小限制

处理办法：

先用小文件跑通链路，再逐步调大限制。不要一开始就上传几十 MB 的 PDF。

D.4.3 MinIO Console 能打开，但程序连不上

现象：

text 复制代码

浏览器能打开 MinIO 管理台
后端上传对象失败
Connection refused
Access denied

优先检查：

text 复制代码

MinIO API 端口是否写对
MinIO Console 端口和 API 端口是否混淆
accessKey/secretKey 是否来自环境变量
bucket 是否存在

处理办法：

在当前 Compose 口径中：

text 复制代码

MinIO API：9002
MinIO Console：9001

后端程序连接对象存储时应该使用 API 地址，不是 Console 地址。

D.4.4 bucket 不存在

现象：

text 复制代码

上传对象时报 bucket does not exist
下载对象时报 NoSuchBucket

优先检查：

powershell 复制代码

mc alias set knowhub http://localhost:9002 <accessKey> <secretKey>
mc ls knowhub

处理办法：

如果 bucket 不存在，先创建：

powershell 复制代码

mc mb knowhub/knowhub-docs

实际 bucket 名称要和应用配置保持一致。

D.4.5 本地存储与 MinIO 口径差异

当前教材按最终平台主线讲 MinIO，但真实项目中曾存在本地磁盘文件存储实现。排查时要分清：

text 复制代码

当前代码实际走本地磁盘，还是已经接入 MinIO

如果代码还在走本地存储，优先看本地路径是否存在、是否可写。如果已经切到 MinIO，优先看 endpoint、bucket、accessKey、secretKey 和对象 key。

D.5 文档解析、切片与索引任务问题

D.5.1 上传成功但没有创建索引任务

现象：

text 复制代码

文档记录存在
indexStatus 仍是 UPLOADED
任务列表中没有对应任务

优先检查：

text 复制代码

knowledge-service 调用 task-service 是否成功
task-service 是否启动
Feign 调用是否走服务名
task-service 是否注册到 Nacos

处理办法：

先确认 task-service 可用，再看 knowledge-service 日志中是否出现「创建索引任务失败」。

D.5.2 任务一直 WAITING

现象：

text 复制代码

index_task.status = WAITING
前端一直显示等待中

优先检查：

text 复制代码

task-service 是否有消费者或调度执行逻辑
RabbitMQ exchange/queue/binding 是否存在
消息是否进入队列

处理办法：

先确认 RabbitMQ 管理台（http://localhost:15672）中 exchange（rag.index.exchange）和 queue（rag.index.queue）是否存在。如果 exchange/queue 不存在，说明 knowledge-service 或 task-service 启动时未自动声明，检查两个服务的 RabbitMQ 配置是否一致，详见附录 A。如果 exchange/queue 存在但消息数为 0，说明生产者未成功投递消息，检查 knowledge-service 日志中的 IndexTaskPublisher 输出。如果消息堆积但无人消费，说明 task-service 的 @RabbitListener 未生效，检查 task-service 是否启动、消费者类是否被 Spring 扫描到。完整的消息投递和消费代码可对照第 22 章第 22.8 节。

D.5.3 任务一直 RUNNING

现象：

text 复制代码

任务进入 RUNNING 后长期不结束

优先检查：

text 复制代码

task-service 日志
knowledge-service 日志
Redis 锁是否存在
外部模型调用是否卡住
pgvector 写入是否卡住
超时扫描是否启用

处理办法：

RUNNING 长时间不结束，通常要看执行线程卡在哪个依赖上。超时扫描会把长期 RUNNING 的任务标记为 TIMEOUT，之后才适合做重试。

D.5.4 任务 FAILED

现象：

text 复制代码

index_task.status = FAILED
document_info.indexStatus = FAILED
errorMessage 有错误信息

优先检查：

text 复制代码

errorMessage
解析器日志
切片结果
Embedding 日志
pgvector 写入日志

处理办法：

不要只看 task-service。很多索引失败发生在 knowledge-service 内部，例如解析、切片、Embedding 或向量写入。

D.5.5 Redis 锁冲突

现象：

text 复制代码

日志提示任务锁已被占用
重复点击重试但任务没有重复执行

优先检查：

text 复制代码

Redis 中 task lock key 是否存在
锁 TTL 是否合理
workerId 或 owner value 是否匹配

处理办法：

锁冲突不一定是错误。它可能说明系统正在阻止重复执行。只有锁长时间不释放，才需要进一步检查执行线程是否卡住或释放逻辑是否异常。

D.5.6 Java 服务内存溢出

现象：

text 复制代码

task-service 或 knowledge-service 在处理大文件或大量 chunk 时突然崩溃
日志中出现 OutOfMemoryError: Java heap space
日志中出现 GC overhead limit exceeded
服务进程消失或进入无响应状态

优先检查：

text 复制代码

应用日志中是否有 OutOfMemoryError
JVM 启动参数中 `-Xmx` 设置了多少
当前处理的文档大小和 chunk 数量

处理办法：

首先确认 JVM 堆内存配置。如果启动 jar 时没有指定 -Xmx，JVM 会使用默认值，通常约为物理内存的 1/4，在容器环境中还可能不准确。

可以在启动命令中显式限制或增大堆内存：

bash 复制代码

java -Xmx512m -jar rag-task-service/target/rag-task-service-0.0.1-SNAPSHOT.jar

或者：

bash 复制代码

java -Xmx1024m -jar rag-knowledge-service/target/rag-knowledge-service-0.0.1-SNAPSHOT.jar

其次检查是否有超大 PDF 文件正在解析，例如超过 50 MB 的 PDF。PDFBox 在解析大文件时会将整个文档加载到内存，限制可上传的 PDF 文件大小是更根本的解决方案，详见第 7 章和第 8 章的相关配置。

如果内存溢出发生在 Embedding 阶段，通常是单个文档生成了大量 chunk，并逐个调用 Embedding 模型。可以考虑调小上传文件大小上限、优化切片策略，或者分批处理 chunk。

Windows 上可以通过任务管理器查看 Java 进程的内存占用；Linux 上可以使用：

bash 复制代码

ps aux | grep java
top -p <pid>

如果内存占用持续增长且不释放，可能存在内存泄漏，例如 ThreadLocal 未清理导致用户上下文残留。此时回看第 4 章 UserContext 的 clear 机制和第 15 章的相关排查项。

D.6 Embedding 与 pgvector 问题

D.6.1 Embedding Model 不可用

现象：

text 复制代码

Embedding 调试接口失败
日志中出现模型不可用、认证失败或连接失败

优先检查：

text 复制代码

AI API Key 是否配置
base URL 是否正确
模型名称是否正确
网络是否能访问模型服务
Spring AI 相关配置是否加载

处理办法：

先用最短文本调用 Embedding 调试接口。短文本都失败，就不要继续排查文档索引，先修复模型配置。

D.6.2 向量维度不一致

现象：

text 复制代码

expected dimension 1024
actual dimension xxxx
pgvector 写入失败。

优先检查：

text 复制代码

`rag.vector.dimension`
`Embedding` 模型实际输出维度
`PostgreSQL` 表结构 `embedding vector(1024)`

处理办法：

这三处必须一致。换模型后最容易出现这个问题，因为不同模型的向量维度可能不同。

D.6.3 pgvector 扩展缺失

现象：

text 复制代码

type "vector" does not exist
CREATE TABLE 失败
向量字段无法创建

优先检查：

sql 复制代码

CREATE EXTENSION IF NOT EXISTS vector;

处理办法：

确认使用的是带 pgvector 的 PostgreSQL 镜像，或者数据库中已经安装并启用了 vector 扩展。

D.6.4 向量表无数据

现象：

text 复制代码

document_chunk 有数据
document_chunk_vector 没有数据
问答始终无检索结果

优先检查：

text 复制代码

索引任务是否成功
Embedding 是否成功
pgvector 写入是否成功
documentId/kbId/userId 是否一致

处理办法：

先查任务状态，再查向量表。不要只看文档表，因为文档上传成功不代表向量索引成功。

D.6.5 检索无结果

现象：

text 复制代码

向量表有数据，但搜索返回空
RAG 问答提示未检索到相关内容

优先检查：

text 复制代码

问题是否和文档内容相关
similarityThreshold 是否过高
topK 是否太小
userId/kbId 过滤条件是否正确
Embedding 模型是否更换过

处理办法：

先降低阈值做测试，再逐步调回合理值。如果降低阈值后能召回，说明链路是通的，问题在检索参数或知识内容质量。

D.7 RAG 问答与 AI 降级问题

D.7.1 问答返回「未检索到相关内容」

现象：

text 复制代码

answer = 知识库中未检索到相关内容，无法确定。
modelCalled = false

优先检查：

text 复制代码

文档是否已经 indexed
向量表是否有数据
检索接口是否能召回 chunk
问题是否偏离文档内容

处理办法：

这是无检索结果，不是模型失败。先修召回，再谈生成。

D.7.2 返回降级答案

现象：

text 复制代码

modelCalled = true
modelSuccess = false
modelFallback = true

优先检查：

text 复制代码

qa_log.modelErrorMessage
模型超时时间
Prompt 长度
外部模型服务状态
网络状态

处理办法：

降级答案说明系统稳定性保护生效了。先看模型为什么没成功返回，不要误判成检索失败。

D.7.3 Sentinel 限流

现象：

text 复制代码

接口返回 42900
提示当前 AI 问答服务繁忙

优先检查：

text 复制代码

是否短时间重复点击
Sentinel QPS 配置
blockHandler 是否生效

处理办法：

限流发生在入口，模型还没有被调用。演示时不要连续快速点击问答按钮，否则容易触发限流。

D.7.4 回答不准确

现象：

text 复制代码

接口成功返回，但答案和预期不一致
引用内容不相关

优先检查：

text 复制代码

检索出来的 chunk 是否正确
Prompt 是否正确约束只能基于资料回答
TopK 是否太少
切片是否把上下文切断
文档本身是否包含答案

处理办法：

RAG 回答质量首先取决于召回内容。如果召回内容不对，模型生成再强也很难答对。

D.8 前端联调问题

D.8.1 Vite 启动失败

现象：

text 复制代码

`npm run dev` 失败
依赖缺失
端口被占用

优先检查：

text 复制代码

Node.js 版本
是否执行 `npm install`
端口是否被占用
当前目录是否是 `rag-user-web` 或 `rag-admin-web`

处理办法：

先在对应前端目录执行依赖安装，再启动。用户端和管理端是两个独立前端，不要在错误目录执行命令。

D.8.2 页面能打开但接口失败

现象：

text 复制代码

页面空白
列表没有数据
浏览器 Network 中接口报错

优先检查：

text 复制代码

`VITE_RAG_GATEWAY_URL` 是否指向 Gateway
Gateway 是否启动
Token 是否携带
接口路径是否正确

处理办法：

前端问题优先看浏览器 Network。它能直接告诉你请求地址、状态码、响应体和请求头。

D.8.3 登录后页面仍显示未登录

现象：

text 复制代码

登录接口返回成功
跳转后又回到登录页

优先检查：

text 复制代码

token 是否写入 localStorage
路由守卫是否读取正确 token key
Axios 请求拦截器是否读取同一个 token key

处理办法：

用户端和管理端的 token key 可能不同。管理端使用管理端自己的登录态，不要混用用户端 token。

D.8.4 上传按钮无响应

现象：

text 复制代码

点击上传没有请求
选择文件后没有变化

优先检查：

text 复制代码

浏览器控制台是否有 JS 错误
文件类型是否被 accept 限制
当前是否已选择知识库
上传接口地址是否正确

处理办法：

先用 .txt 或 .md 小文件测试。如果 PDF 不能选择，检查前端 accept 配置是否包含 .pdf。

D.9 数据库与缓存问题

D.9.1 MySQL 表不存在

现象：

text 复制代码

Table 'rag_demo.xxx' doesn't exist
接口报 SQL 语法或表缺失错误

优先检查：

text 复制代码

是否创建 rag_demo 数据库
是否执行 MySQL 主建表脚本
应用连接的是不是同一个数据库

处理办法：

先确认连接库名，再执行建表脚本。不要在一个库里建表，应用却连另一个库。

D.9.2 RBAC 升级脚本重复执行

现象：

text 复制代码

Duplicate column name 'role'
Duplicate key name

优先检查：

text 复制代码

user 表是否已经有 role 字段
是否已经执行过 02_admin_rbac_schema.sql

处理办法：

当前主建表脚本已经包含 role 字段时，旧库升级脚本只给老库使用，不需要反复执行。

D.9.3 PostgreSQL 连接错库

现象：

text 复制代码

pgvector 表不存在
vector 扩展不存在
向量写入失败

优先检查：

text 复制代码

应用连接的数据库名是否是 rag_vector
建表脚本是否在 rag_vector 中执行
PostgreSQL 容器是否启动

处理办法：

MySQL 负责业务数据，PostgreSQL/pgvector 负责向量数据。不要把向量表建到 MySQL，也不要把业务表建到向量库里。

D.9.3.5 Redis 连接失败

现象：

text 复制代码

应用启动日志中出现 RedisConnectionFailureException
日志中出现 Unable to connect to Redis
知识库访问变慢但功能仍可用
owner 缓存降级到 MySQL
前端页面加载正常但部分缓存相关日志报错

优先检查：

bash 复制代码

docker compose ps redis
docker compose logs redis
redis-cli -h 127.0.0.1 -p 6379 PING

同时检查应用配置：

text 复制代码

spring.data.redis.host
spring.data.redis.port
spring.data.redis.password
spring.data.redis.database

处理办法：

首先确认 Redis 容器是否运行：

bash 复制代码

docker compose ps redis

如果 Redis 容器正常运行，进入容器内部执行：

bash 复制代码

docker compose exec redis redis-cli PING

返回 PONG 说明 Redis 本身可用。

如果 PING 成功但应用仍连不上，检查应用的 Redis 连接配置是否和 Docker Compose 中的 Redis 环境变量一致。重点看 host、port、password、database 四个字段。

如果 Redis 设置了密码，例如启用了 requirepass，应用配置中的 password 字段必须填写同一个值。

Redis 连接失败时，知识库 owner 缓存会自动降级到 MySQL 查询，详见第 13 章 13.4.5 节，所以功能通常仍可用，只是性能会下降。如果要确认业务链路是否不依赖缓存，可以临时关闭：

yaml 复制代码

rag:
  kb:
    owner-cache:
      enabled: false

关闭缓存后重新验证知识库详情和列表接口。如果无缓存时业务正常，再回头排查 Redis 连接。

D.9.4 Redis key 查不到

现象：

text 复制代码

缓存中没有 owner key
任务状态 key 不存在

优先检查：

text 复制代码

Redis 是否启动
key 前缀是否正确
TTL 是否已经过期
功能是否真的走到了写缓存逻辑

处理办法：

Redis 是缓存和协调层，不是主数据库。key 不存在不一定是错误，可能是还没触发、已经过期，或者系统降级回查 MySQL。

D.9.5 清理数据后系统异常

现象：

text 复制代码

文档记录还在，但文件或向量没了
向量还在，但文档记录没了
任务引用了不存在的 documentId

优先检查：

text 复制代码

清理了哪些表
是否同时清理对象存储或本地文件
是否清理 pgvector 向量表
是否清理 Redis 缓存

处理办法：

清理演示数据时要按链路清理，不要只删一张表。文档元数据、chunk、向量、任务、问答日志、对象文件之间有关联。

D.10 演示前最终检查清单

正式演示前，建议按下面顺序检查。

D.10.1 基础设施

确认以下组件已启动：

text 复制代码

MySQL
PostgreSQL/pgvector
Redis
RabbitMQ
MinIO
Nacos

检查方式：

powershell 复制代码

docker compose ps

D.10.2 后端服务

确认以下服务已启动并注册：

text 复制代码

gateway-service
auth-service
knowledge-service
task-service

重点检查：

text 复制代码

端口是否冲突
Nacos 注册是否正常
环境变量是否加载
JWT 密钥是否一致
AI 模型配置是否可用

D.10.3 前端应用

确认以下前端可访问：

text 复制代码

rag-user-web
rag-admin-web

重点检查：

text 复制代码

VITE_RAG_GATEWAY_URL
登录态保存
请求是否走 Gateway
管理端是否使用 ADMIN 账号

D.10.4 主流程

按下面顺序跑一遍：

text 复制代码

注册/登录
创建知识库
上传文档
查看索引状态
等待 INDEXED
执行向量检索
执行 RAG 问答
查看引用内容
查看后台任务和问答日志

如果某一步失败，不要跳到下一步。RAG 链路是串起来的，前面失败，后面一定不可靠。

D.10.5 敏感配置

交付或截图前检查：

text 复制代码

不要暴露真实 AI API Key
不要暴露真实数据库密码
不要暴露 JWT secret
不要把 .env 提交到公开仓库
不要在教材或简历中写真实密钥

教材附录中的配置应使用环境变量占位，真实运行值只保留在本机 .env 或安全配置中心中。

D.11 最短排障路径表

现象	先看什么	再看什么
前端打不开	Vite 是否启动	端口、依赖、启动目录
接口 401	Token 是否携带	JWT secret、Token 是否过期
接口 403	当前角色是否 ADMIN	Gateway `/admin/**` 鉴权
接口 404	请求路径是否正确	资源是否属于当前用户
上传失败	文件大小和类型	存储路径或 MinIO 配置
任务 WAITING	task-service 是否消费	RabbitMQ 队列与业务监听代码
任务 RUNNING 很久	执行日志	Redis 锁、模型、pgvector、超时扫描
任务 FAILED	errorMessage	解析、切片、Embedding、向量写入
Java 服务 OOM 崩溃	应用日志中的 OutOfMemoryError	文档大小、chunk 数量、JVM -Xmx 设置
检索无结果	向量表是否有数据	阈值、TopK、userId/kbId
问答降级	qa_log 模型字段	超时、模型服务、网络
429 限流	Sentinel QPS	是否重复点击
MinIO 连不上	API 端口 9002	Console 端口和 API 端口是否混淆
pgvector 报错	vector 扩展	数据库名和表结构
Redis key 没有	TTL 是否过期	是否触发写缓存逻辑
Redis 连接失败	docker compose ps redis + redis-cli PING	应用 Redis 连接配置四要素

附录小结

本附录把 KnowHub 项目的常见问题整理成排障速查表。

遇到问题时，先不要急着改代码。正确做法是先确认入口、服务、配置、状态、依赖和日志。上传问题优先看文件校验和存储；索引问题优先看任务状态、解析、Embedding 和 pgvector；问答问题优先区分无检索结果、模型降级和 Sentinel 限流；前端问题优先看浏览器 Network；环境问题优先看 Docker Compose 和容器日志。

只要按这个顺序排查，大多数演示和开发阶段的问题都能快速定位。