Yuxi-Know故障排除速查：五个阶段搞定部署报错
【免费下载链接】Yuxi可私有部署的多租户知识智能体平台：统一 RAG、知识图谱、多智能体、MCP/Skills、沙盒与权限管理。Self-hosted knowledge agent platform for RAG, knowledge graphs and multi-agent workflows.项目地址: https://gitcode.com/GitHub_Trending/yu/Yuxi
Yuxi-Know 是可私有部署的多租户知识智能体平台，集 RAG 知识库、知识图谱与多智能体编排于一体。遇到部署失败、启动报错或检索异常时，按这篇做 Yuxi-Know 故障排除：先对照诊断表定位阶段，再按"启动前 → 起不来 → 功能不对 → 占资源 → 还卡住"的时间线修。
| 你看到的现象 | 最可能的原因 | 跳到哪一节 |
|---|---|---|
port 5050 / 5173 is already allocated | 端口被其他进程占用 | 启动前自检 |
Set API_KEY_DERIVATION_SECRET in .env | .env缺失或密钥不合规 | 启动前自检 |
api-dev 反复重启，/ready返回 503 | 依赖未就绪或冷启动未完成 | 容器起不来 |
| 能登录但模型调用全失败 | 模型供应商未配置凭证 | 起来了但功能不对 |
| 图谱空、检索无结果 | 轻量模式未拉起 Neo4j/Milvus | 起来了但功能不对 |
| GPU 报 OOM、解析任务卡死 | 显存不足 | 答得慢、显存吃紧 |
🔍 启动前自检：端口与环境变量先过一遍
按up之前，两分钟确认这两项，能避开大部分启动报错。
启动就报port is already allocated
- 现象：
docker compose up直接失败，输出Bind for 0.0.0.0:5050 failed: port is already allocated，web 端则是 5173。 - 根因：api 服务固定占 5050，开发态前端占 5173，宿主机上另有进程先用了这两个端口。
- 修复：
- 运行
ss -tlnp | grep -E '5050|5173'找出占用进程。 - 停掉该进程，或改
docker-compose.yml中对应ports映射。
- 运行
- 验证：
docker compose ps全部 Up，浏览器能打开http://localhost:5173。
compose 报Set API_KEY_DERIVATION_SECRET in .env
- 现象：还没进入构建就报错，提示
Set API_KEY_DERIVATION_SECRET in .env [v0.7.2+], or rerun bash scripts/init.sh。 - 根因：开发环境读
.env、生产环境读.env.prod，密钥由初始化脚本生成；手工删改或位数不足（要求 32 位以上）就会触发 compose 的强制校验。 - 修复：
ls -l .env .env.prod确认文件存在。- 缺失或损坏时重跑
bash scripts/init.sh（Windows 用scripts\init.ps1）重新生成密钥。 - 生产部署还需在
.env.prod配齐POSTGRES_PASSWORD、NEO4J_PASSWORD、MINIO_ACCESS_KEY等项。
- 验证：
docker compose config不再抛错即通过。
🚀 容器起不来：先等三分钟，再动手
api-dev 反复重启，/ready一直 503
- 现象：
docker ps里 api-dev 状态是 Restarting，健康检查连续失败。 - 根因：健康检查的 start_period 给了 180 秒，首次启动要做存储迁移和内置模型模板同步，冷启动本来就慢；postgres、redis 未 healthy 前 api 也不会就绪。
- 修复：
- 等满 3 分钟，跑
docker compose ps看依赖是否都 healthy。 - 仍重启则执行
docker logs api-dev --tail 100，只看第一条错误。
- 等满 3 分钟，跑
- 验证：
curl -s http://localhost:5050/api/system/ready返回 200 且status为ready。
graph 容器不健康，Neo4j 认证失败
- 现象：
docker logs graph反复出现认证失败，api 日志里报 neo4j 连接异常。 - 根因：Neo4j 的认证串是
neo4j/NEO4J_PASSWORD，.env里的密码与数据卷中已有的库不一致时，每次连接都会被拒。 - 修复：
docker logs graph判断是认证错误还是启动错误。- 核对
.env中NEO4J_URI=bolt://graph:7687、NEO4J_USERNAME、NEO4J_PASSWORD三项一致。 - 改过密码又连不上的话，恢复原密码；确认可丢数据再清空
docker/volumes/neo4j/data重建。
- 验证：
docker compose ps graph显示 healthy。
🧩 起来了但功能不对：模型、图谱、解析逐一查
模型调用失败：先查模型供应商
- 现象：发消息报模型调用超时或鉴权失败，回答流出不来。
- 根因：所有对话、嵌入、重排模型都走"智能体管理 → 模型供应商"页面统一管理，内置模板只代表"可添加"，凭证、启用、模型三步都没做时调用必挂。
- 修复：
- 用管理员账号进入"智能体管理 → 模型供应商"，启用目标供应商。
- 填 Base URL 与 API Key，再添加并选中模型；密钥须与供应商文档一致。
- 验证：发一条测试消息，回答能正常流式输出。
图谱是空的、检索没结果：可能开了轻量模式
- 现象：平台功能正常，但知识图谱区域空着，图谱检索返回为空。
- 根因：
make up-lite只启动 postgres、redis、minio、api、worker、web，LITE_MODE=true下 graph 与 milvus 根本不拉起。 - 修复：
docker compose ps确认 graph、milvus 是否在跑。- 需要图谱与向量检索时，切回完整模式：
docker compose up --build。
- 验证：知识库页面能看到图谱构建任务，检索返回引用来源。
文档解析失败：图片、PDF 一直卡在"解析中"
- 现象：上传
backend/test/data/测试图片.png这类图片或 PDF 后，状态长时间不更新。 - 根因：解析依赖 mineru-api（30001）和 paddlex（8080），二者属于
allprofile，默认up不带。 - 修复：
curl -s http://localhost:5050/api/system/ocr/health看解析后端健康状态。- 按需补启：
docker compose --profile all up -d mineru-api paddlex（需 GPU 环境）。
- 验证：重新解析失败文件，状态变为成功且可预览。
⚡ 答得慢、显存吃紧：调两个 GPU 参数
MinerU 显存不足：OOM 或起不来
- 现象：mineru-api 反复重启，日志出现 CUDA out of memory。
- 根因：vLLM 引擎默认按整卡预留 KV 缓存，单卡显存被解析模型吃满。
- 修复：
- 在
docker-compose.yml的 mineru-api command 里启用注释中的--gpu-memory-utilization 0.5。 - 仍不足就降到
0.4，然后docker compose up -d mineru-api重建。
- 在
- 验证：
curl -s http://localhost:30001/health返回正常，容器保持 healthy。
多卡机器吃不满：改device_ids
- 现象：降参数后显存仍紧张，机器上还有闲置的卡。
- 根因：compose 里 deploy.devices 默认只预留
device_ids: ["0"]，其余 GPU 未分配。 - 修复：
- 将 mineru-api 与 paddlex 的
device_ids改为["0", "1"]。 docker compose --profile all up -d --build重建相关服务。
- 将 mineru-api 与 paddlex 的
- 验证：
nvidia-smi能看到两张卡都有解析进程占用。
🛟 还解决不了：日志与健康端点
两个健康端点先分阶段
/api/system/health返回 200 说明进程活着；/api/system/ready返回 503 说明存储或依赖没就绪。两个端点一组合，就能把问题圈定在"进程层"还是"依赖层"。
日志去哪找
- 现象：界面上的报错不足以定位问题。
- 根因：最直接的线索在容器日志里；应用同时把
yuxi-YYYY-MM-DD.log写到容器内运行时目录，逻辑见backend/package/yuxi/utils/logging_config.py。 - 修复：
docker logs api-dev --tail 200、docker logs worker-dev --tail 200。- 需要文件日志时
docker exec -it api-dev sh，查看/app/runtime/api/logs/。
- 验证：能在日志里找到与报错时间戳吻合的 ERROR 行。
反馈问题前，收集这三样
docker ps -a的完整输出，记录每个容器状态。docker logs api-dev中报错段落与/ready端点返回。- 版本号（
/api/system/health返回的version）与.env关键项（密钥打码）。
记住这三句：
- 按 up 之前先看端口和
.env，按 up 之后先给 ready 三分钟。 - 起来了但不对，先怀疑配置：模型供应商、轻量模式、解析服务三处。
- 日志是唯一线索，
docker logs加两个健康端点就是故障排除的第一站。
【免费下载链接】Yuxi可私有部署的多租户知识智能体平台：统一 RAG、知识图谱、多智能体、MCP/Skills、沙盒与权限管理。Self-hosted knowledge agent platform for RAG, knowledge graphs and multi-agent workflows.项目地址: https://gitcode.com/GitHub_Trending/yu/Yuxi
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
