D.1 排障总原则开发 KnowHub 这类 RAG 平台时最容易让初学者崩溃的不是某一行代码而是问题可能出现在很多层前端页面 - Gateway - auth-service - knowledge-service - task-service - MySQL - PostgreSQL/pgvector - Redis - RabbitMQ - MinIO - 外部 AI 模型如果没有排查顺序很容易今天改前端明天改配置后天又怀疑数据库最后把原本能跑的环境也改坏。本附录只解决一个问题出现故障时先看哪里后看哪里。推荐顺序如下1. 看请求有没有到入口 2. 看服务是否启动 3. 看配置是否生效 4. 看数据库或缓存中有没有状态变化 5. 看依赖组件是否正常 6. 看日志里的错误码和异常堆栈 7. 最后再修改代码不要一上来就重装环境也不要一看到报错就同时改很多配置。一次只改一个因素改完再验证。D.2 启动类问题D.2.1 Docker Compose 启动失败现象docker compose up -d 失败 容器没有全部启动 某些服务状态是 Exited 或 Restarting优先检查docker composepsdocker 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-platformWindows 上通常为D:\rag\rag-platformLinux 上通常为/home/rag/rag-platform或用户自行克隆的路径。可通过ls docker-compose.yml或dir docker-compose.yml验证当前目录是否正确。如果文件不存在说明终端不在项目根目录。确认.env已从.env.example复制出来。确认端口没有被本机其他程序占用。内存不足时不要同时打开太多 IDE、浏览器、数据库工具。如果 Docker 容器全部启动后系统内存接近满载可通过任务管理器或free -h查看可以临时停掉不需要的容器。例如如果当前只测登录接口可以只保留 MySQL 和 Nacosdocker compose stop postgres redis rabbitmq minio。需要时再执行docker compose start postgres redis rabbitmq minio恢复。如果内存在 8GB 以下建议将基础设施迁移到 Linux 虚拟机详见第 19 章 19.7 节。如果容器一直重启不要只看ps要看对应容器日志。ps只能告诉你结果logs才能告诉你原因。D.2.2 端口占用现象Bind for 0.0.0.0:3306 failed port is already allocated Web server failed to start. Port xxxx was already in use优先检查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 常见端口3306PostgreSQL 常见端口5432Redis 常见端口6379Nacos 常见端口8848RabbitMQ 常见端口5672、15672MinIO 常见端口9001、9002如果本机已经装过 MySQL 或 Redis要么停掉本机服务要么修改 Compose 映射端口和应用配置。D.2.3 Nacos 无法访问现象浏览器打不开 http://localhost:8848/nacos 微服务启动时报 Nacos 连接失败优先检查docker composepsnacos docker compose logs nacos处理办法确认rag-nacos容器状态是 running。确认端口8848没有被占用。等待 Nacos 完成启动Nacos 不是容器一启动就立刻可用。微服务本地启动时确认配置中的 Nacos 地址指向localhost:8848或实际部署地址。D.2.4 Docker 磁盘空间不足现象Docker 容器启动失败日志提示 no space left on device MinIO 上传文件时报磁盘空间不足 MySQL 或 PostgreSQL 写入时报磁盘满优先检查dockersystemdfdf-hdu-sh/var/lib/docker处理办法首先用docker system df查看 Docker 占用的磁盘空间分布包括镜像、容器、数据卷和构建缓存各占多少。可以清理未使用镜像和停止的容器dockersystem prune-a注意这会删除停止的容器和未使用的镜像但不会删除数据卷。如果数据卷占用过大例如 MinIO 的rag-minio-data或 MySQL 的rag-mysql-data不要直接删除整个数据卷。应该先确认哪些文件或数据已经不需要再进入对应数据卷目录手动清理或者通过业务接口删除知识库和文档。如果频繁遇到磁盘不足建议把 Docker 数据目录迁移到空间更大的磁盘分区或者定期清理不再需要的测试文档和对应向量数据。学习阶段上传的测试文档和生成的向量数据会持续占用磁盘空间。建议定期清理不再需要的知识库及其关联的文档、chunk、向量和任务记录。清理时要按链路清理不要只删一张表。D.3 网关、登录与权限问题D.3.1 Gateway 无法访问后端接口现象前端请求失败 接口返回 404 接口返回 503优先检查Gateway 是否启动 目标微服务是否启动 Nacos 中是否能看到服务实例 前端请求地址是否走 Gateway处理办法用户端和管理端都应该优先访问 Gateway而不是直接访问某个业务服务。如果 Gateway 能启动但转发失败先看 Nacos 服务注册情况。如果直接访问业务服务成功、走 Gateway 失败重点看路由配置和路径前缀。D.3.2 登录后仍然 401现象登录成功但访问知识库接口返回 401 刷新页面后登录态丢失优先检查前端是否保存 token Axios 是否携带 Authorization header Gateway 是否放行登录注册接口 JWT 是否过期 JWT secret 是否一致处理办法打开浏览器开发者工具查看请求头中有没有Authorization。确认格式是Bearer xxx。确认 auth-service 生成 Token 的密钥和 Gateway 校验 Token 的密钥一致。如果清理过浏览器缓存或 localStorage需要重新登录。D.3.3 管理端接口返回 403现象/admin/** 接口返回 403 普通用户登录管理端后看不到数据优先检查JWT 中 role 是否为 ADMIN Gateway 的 /admin/** 鉴权是否生效 数据库 user 表中的 role 字段是否正确处理办法管理端不是只要登录就能访问。KnowHub 当前采用基础 USER/ADMIN 角色模型/admin/**接口要求 ADMIN。普通 USER 被拒绝是正常结果。D.3.4 跨用户访问返回 40400现象userA 访问 userB 的知识库或文档返回 40400优先检查当前登录用户是谁 请求的 kbId/documentId 属于谁 Gateway 是否正确透传用户信息 UserContext 是否读取到了 userId处理办法这通常不是 bug而是资源隔离生效。系统不返回「无权限访问该知识库」而是返回资源不存在可以减少资源枚举风险。D.4 文件上传与 MinIO 问题D.4.1 文件为空或文件类型不支持现象上传失败 返回 FILE_EMPTY 返回 FILE_TYPE_NOT_SUPPORTED优先检查文件是否为空 文件扩展名是否为 txt、md、markdown、PDF 前端 accept 是否限制了文件类型处理办法使用非空的文本文件或 Markdown 文件先验证主流程。如果要演示 PDF确认后端解析器支持 PDF前端上传控件也允许.pdf。D.4.2 文件过大现象返回 FILE_TOO_LARGE 请求直接被拦截优先检查Spring multipart 配置 Gateway 请求体限制 业务层文件大小限制处理办法先用小文件跑通链路再逐步调大限制。不要一开始就上传几十 MB 的 PDF。D.4.3 MinIO Console 能打开但程序连不上现象浏览器能打开 MinIO 管理台 后端上传对象失败 Connection refused Access denied优先检查MinIO API 端口是否写对 MinIO Console 端口和 API 端口是否混淆 accessKey/secretKey 是否来自环境变量 bucket 是否存在处理办法在当前 Compose 口径中MinIO API9002 MinIO Console9001后端程序连接对象存储时应该使用 API 地址不是 Console 地址。D.4.4 bucket 不存在现象上传对象时报 bucket does not exist 下载对象时报 NoSuchBucket优先检查mc aliassetknowhub http://localhost:9002 accessKey secretKey mclsknowhub处理办法如果 bucket 不存在先创建mc mb knowhub/knowhub-docs实际 bucket 名称要和应用配置保持一致。D.4.5 本地存储与 MinIO 口径差异当前教材按最终平台主线讲 MinIO但真实项目中曾存在本地磁盘文件存储实现。排查时要分清当前代码实际走本地磁盘还是已经接入 MinIO如果代码还在走本地存储优先看本地路径是否存在、是否可写。如果已经切到 MinIO优先看 endpoint、bucket、accessKey、secretKey 和对象 key。D.5 文档解析、切片与索引任务问题D.5.1 上传成功但没有创建索引任务现象文档记录存在 indexStatus 仍是 UPLOADED 任务列表中没有对应任务优先检查knowledge-service 调用 task-service 是否成功 task-service 是否启动 Feign 调用是否走服务名 task-service 是否注册到 Nacos处理办法先确认 task-service 可用再看 knowledge-service 日志中是否出现「创建索引任务失败」。D.5.2 任务一直 WAITING现象index_task.status WAITING 前端一直显示等待中优先检查task-service 是否有消费者或调度执行逻辑 RabbitMQ exchange/queue/binding 是否存在 消息是否进入队列处理办法先确认 RabbitMQ 管理台http://localhost:15672中 exchangerag.index.exchange和 queuerag.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现象任务进入 RUNNING 后长期不结束优先检查task-service 日志 knowledge-service 日志 Redis 锁是否存在 外部模型调用是否卡住 pgvector 写入是否卡住 超时扫描是否启用处理办法RUNNING 长时间不结束通常要看执行线程卡在哪个依赖上。超时扫描会把长期 RUNNING 的任务标记为 TIMEOUT之后才适合做重试。D.5.4 任务 FAILED现象index_task.status FAILED document_info.indexStatus FAILED errorMessage 有错误信息优先检查errorMessage 解析器日志 切片结果 Embedding 日志 pgvector 写入日志处理办法不要只看 task-service。很多索引失败发生在 knowledge-service 内部例如解析、切片、Embedding 或向量写入。D.5.5 Redis 锁冲突现象日志提示任务锁已被占用 重复点击重试但任务没有重复执行优先检查Redis 中 task lock key 是否存在 锁 TTL 是否合理 workerId 或 owner value 是否匹配处理办法锁冲突不一定是错误。它可能说明系统正在阻止重复执行。只有锁长时间不释放才需要进一步检查执行线程是否卡住或释放逻辑是否异常。D.5.6 Java 服务内存溢出现象task-service 或 knowledge-service 在处理大文件或大量 chunk 时突然崩溃 日志中出现 OutOfMemoryError: Java heap space 日志中出现 GC overhead limit exceeded 服务进程消失或进入无响应状态优先检查应用日志中是否有 OutOfMemoryError JVM 启动参数中 -Xmx 设置了多少 当前处理的文档大小和 chunk 数量处理办法首先确认 JVM 堆内存配置。如果启动 jar 时没有指定-XmxJVM 会使用默认值通常约为物理内存的 1/4在容器环境中还可能不准确。可以在启动命令中显式限制或增大堆内存java-Xmx512m-jarrag-task-service/target/rag-task-service-0.0.1-SNAPSHOT.jar或者java-Xmx1024m-jarrag-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 上可以使用psaux|grepjavatop-ppid如果内存占用持续增长且不释放可能存在内存泄漏例如ThreadLocal未清理导致用户上下文残留。此时回看第 4 章UserContext的clear机制和第 15 章的相关排查项。D.6 Embedding 与 pgvector 问题D.6.1 Embedding Model 不可用现象Embedding 调试接口失败 日志中出现模型不可用、认证失败或连接失败优先检查AI API Key 是否配置 base URL 是否正确 模型名称是否正确 网络是否能访问模型服务 Spring AI 相关配置是否加载处理办法先用最短文本调用 Embedding 调试接口。短文本都失败就不要继续排查文档索引先修复模型配置。D.6.2 向量维度不一致现象expected dimension 1024 actual dimension xxxx pgvector 写入失败。优先检查rag.vector.dimension Embedding 模型实际输出维度 PostgreSQL 表结构 embedding vector(1024)处理办法这三处必须一致。换模型后最容易出现这个问题因为不同模型的向量维度可能不同。D.6.3 pgvector 扩展缺失现象type vector does not exist CREATE TABLE 失败 向量字段无法创建优先检查CREATEEXTENSIONIFNOTEXISTSvector;处理办法确认使用的是带 pgvector 的 PostgreSQL 镜像或者数据库中已经安装并启用了 vector 扩展。D.6.4 向量表无数据现象document_chunk 有数据 document_chunk_vector 没有数据 问答始终无检索结果优先检查索引任务是否成功 Embedding 是否成功 pgvector 写入是否成功 documentId/kbId/userId 是否一致处理办法先查任务状态再查向量表。不要只看文档表因为文档上传成功不代表向量索引成功。D.6.5 检索无结果现象向量表有数据但搜索返回空 RAG 问答提示未检索到相关内容优先检查问题是否和文档内容相关 similarityThreshold 是否过高 topK 是否太小 userId/kbId 过滤条件是否正确 Embedding 模型是否更换过处理办法先降低阈值做测试再逐步调回合理值。如果降低阈值后能召回说明链路是通的问题在检索参数或知识内容质量。D.7 RAG 问答与 AI 降级问题D.7.1 问答返回「未检索到相关内容」现象answer 知识库中未检索到相关内容无法确定。 modelCalled false优先检查文档是否已经 indexed 向量表是否有数据 检索接口是否能召回 chunk 问题是否偏离文档内容处理办法这是无检索结果不是模型失败。先修召回再谈生成。D.7.2 返回降级答案现象modelCalled true modelSuccess false modelFallback true优先检查qa_log.modelErrorMessage 模型超时时间 Prompt 长度 外部模型服务状态 网络状态处理办法降级答案说明系统稳定性保护生效了。先看模型为什么没成功返回不要误判成检索失败。D.7.3 Sentinel 限流现象接口返回 42900 提示当前 AI 问答服务繁忙优先检查是否短时间重复点击 Sentinel QPS 配置 blockHandler 是否生效处理办法限流发生在入口模型还没有被调用。演示时不要连续快速点击问答按钮否则容易触发限流。D.7.4 回答不准确现象接口成功返回但答案和预期不一致 引用内容不相关优先检查检索出来的 chunk 是否正确 Prompt 是否正确约束只能基于资料回答 TopK 是否太少 切片是否把上下文切断 文档本身是否包含答案处理办法RAG 回答质量首先取决于召回内容。如果召回内容不对模型生成再强也很难答对。D.8 前端联调问题D.8.1 Vite 启动失败现象npm run dev 失败 依赖缺失 端口被占用优先检查Node.js 版本 是否执行 npm install 端口是否被占用 当前目录是否是 rag-user-web 或 rag-admin-web处理办法先在对应前端目录执行依赖安装再启动。用户端和管理端是两个独立前端不要在错误目录执行命令。D.8.2 页面能打开但接口失败现象页面空白 列表没有数据 浏览器 Network 中接口报错优先检查VITE_RAG_GATEWAY_URL 是否指向 Gateway Gateway 是否启动 Token 是否携带 接口路径是否正确处理办法前端问题优先看浏览器 Network。它能直接告诉你请求地址、状态码、响应体和请求头。D.8.3 登录后页面仍显示未登录现象登录接口返回成功 跳转后又回到登录页优先检查token 是否写入 localStorage 路由守卫是否读取正确 token key Axios 请求拦截器是否读取同一个 token key处理办法用户端和管理端的 token key 可能不同。管理端使用管理端自己的登录态不要混用用户端 token。D.8.4 上传按钮无响应现象点击上传没有请求 选择文件后没有变化优先检查浏览器控制台是否有 JS 错误 文件类型是否被 accept 限制 当前是否已选择知识库 上传接口地址是否正确处理办法先用.txt或.md小文件测试。如果 PDF 不能选择检查前端 accept 配置是否包含.pdf。D.9 数据库与缓存问题D.9.1 MySQL 表不存在现象Table rag_demo.xxx doesnt exist 接口报 SQL 语法或表缺失错误优先检查是否创建 rag_demo 数据库 是否执行 MySQL 主建表脚本 应用连接的是不是同一个数据库处理办法先确认连接库名再执行建表脚本。不要在一个库里建表应用却连另一个库。D.9.2 RBAC 升级脚本重复执行现象Duplicate column name role Duplicate key name优先检查user 表是否已经有 role 字段 是否已经执行过 02_admin_rbac_schema.sql处理办法当前主建表脚本已经包含role字段时旧库升级脚本只给老库使用不需要反复执行。D.9.3 PostgreSQL 连接错库现象pgvector 表不存在 vector 扩展不存在 向量写入失败优先检查应用连接的数据库名是否是 rag_vector 建表脚本是否在 rag_vector 中执行 PostgreSQL 容器是否启动处理办法MySQL 负责业务数据PostgreSQL/pgvector 负责向量数据。不要把向量表建到 MySQL也不要把业务表建到向量库里。D.9.3.5 Redis 连接失败现象应用启动日志中出现 RedisConnectionFailureException 日志中出现 Unable to connect to Redis 知识库访问变慢但功能仍可用 owner 缓存降级到 MySQL 前端页面加载正常但部分缓存相关日志报错优先检查dockercomposepsredisdockercompose logs redis redis-cli-h127.0.0.1-p6379PING同时检查应用配置spring.data.redis.host spring.data.redis.port spring.data.redis.password spring.data.redis.database处理办法首先确认 Redis 容器是否运行dockercomposepsredis如果 Redis 容器正常运行进入容器内部执行dockercomposeexecredis redis-cli PING返回PONG说明 Redis 本身可用。如果PING成功但应用仍连不上检查应用的 Redis 连接配置是否和 Docker Compose 中的 Redis 环境变量一致。重点看 host、port、password、database 四个字段。如果 Redis 设置了密码例如启用了requirepass应用配置中的password字段必须填写同一个值。Redis 连接失败时知识库 owner 缓存会自动降级到 MySQL 查询详见第 13 章 13.4.5 节所以功能通常仍可用只是性能会下降。如果要确认业务链路是否不依赖缓存可以临时关闭rag:kb:owner-cache:enabled:false关闭缓存后重新验证知识库详情和列表接口。如果无缓存时业务正常再回头排查 Redis 连接。D.9.4 Redis key 查不到现象缓存中没有 owner key 任务状态 key 不存在优先检查Redis 是否启动 key 前缀是否正确 TTL 是否已经过期 功能是否真的走到了写缓存逻辑处理办法Redis 是缓存和协调层不是主数据库。key 不存在不一定是错误可能是还没触发、已经过期或者系统降级回查 MySQL。D.9.5 清理数据后系统异常现象文档记录还在但文件或向量没了 向量还在但文档记录没了 任务引用了不存在的 documentId优先检查清理了哪些表 是否同时清理对象存储或本地文件 是否清理 pgvector 向量表 是否清理 Redis 缓存处理办法清理演示数据时要按链路清理不要只删一张表。文档元数据、chunk、向量、任务、问答日志、对象文件之间有关联。D.10 演示前最终检查清单正式演示前建议按下面顺序检查。D.10.1 基础设施确认以下组件已启动MySQL PostgreSQL/pgvector Redis RabbitMQ MinIO Nacos检查方式docker composepsD.10.2 后端服务确认以下服务已启动并注册gateway-service auth-service knowledge-service task-service重点检查端口是否冲突 Nacos 注册是否正常 环境变量是否加载 JWT 密钥是否一致 AI 模型配置是否可用D.10.3 前端应用确认以下前端可访问rag-user-web rag-admin-web重点检查VITE_RAG_GATEWAY_URL 登录态保存 请求是否走 Gateway 管理端是否使用 ADMIN 账号D.10.4 主流程按下面顺序跑一遍注册/登录 创建知识库 上传文档 查看索引状态 等待 INDEXED 执行向量检索 执行 RAG 问答 查看引用内容 查看后台任务和问答日志如果某一步失败不要跳到下一步。RAG 链路是串起来的前面失败后面一定不可靠。D.10.5 敏感配置交付或截图前检查不要暴露真实 AI API Key 不要暴露真实数据库密码 不要暴露 JWT secret 不要把 .env 提交到公开仓库 不要在教材或简历中写真实密钥教材附录中的配置应使用环境变量占位真实运行值只保留在本机.env或安全配置中心中。D.11 最短排障路径表现象先看什么再看什么前端打不开Vite 是否启动端口、依赖、启动目录接口 401Token 是否携带JWT secret、Token 是否过期接口 403当前角色是否 ADMINGateway/admin/**鉴权接口 404请求路径是否正确资源是否属于当前用户上传失败文件大小和类型存储路径或 MinIO 配置任务 WAITINGtask-service 是否消费RabbitMQ 队列与业务监听代码任务 RUNNING 很久执行日志Redis 锁、模型、pgvector、超时扫描任务 FAILEDerrorMessage解析、切片、Embedding、向量写入Java 服务 OOM 崩溃应用日志中的 OutOfMemoryError文档大小、chunk 数量、JVM -Xmx 设置检索无结果向量表是否有数据阈值、TopK、userId/kbId问答降级qa_log 模型字段超时、模型服务、网络429 限流Sentinel QPS是否重复点击MinIO 连不上API 端口 9002Console 端口和 API 端口是否混淆pgvector 报错vector 扩展数据库名和表结构Redis key 没有TTL 是否过期是否触发写缓存逻辑Redis 连接失败docker compose ps redis redis-cli PING应用 Redis 连接配置四要素附录小结本附录把 KnowHub 项目的常见问题整理成排障速查表。遇到问题时先不要急着改代码。正确做法是先确认入口、服务、配置、状态、依赖和日志。上传问题优先看文件校验和存储索引问题优先看任务状态、解析、Embedding 和 pgvector问答问题优先区分无检索结果、模型降级和 Sentinel 限流前端问题优先看浏览器 Network环境问题优先看 Docker Compose 和容器日志。只要按这个顺序排查大多数演示和开发阶段的问题都能快速定位。