Yuxi部署报错与故障排查完整指南【免费下载链接】Yuxi可私有部署的多租户知识智能体平台统一 RAG、知识图谱、多智能体、MCP/Skills、沙盒与权限管理。Self-hosted knowledge agent platform for RAG, knowledge graphs and multi-agent workflows.项目地址: https://gitcode.com/GitHub_Trending/yu/YuxiYuxi 是一个可私有部署的多租户知识智能体平台把 RAG 检索、知识图谱、多智能体放进同一个工作台。本文覆盖你部署或使用 Yuxi 时最常遇到的报错容器起不来、前端打不开、worker 不续租、模型调用失败、检索无结果按「从外到内」五层给你一套可照做的排查路径。30 秒快速自检拿到报错先对表排除五个最高频原因你看到的现象最先检查的一项跳转小节docker compose up秒退提示Set API_KEY_DERIVATION_SECRET in .env.env是否缺少三个安全密钥「.env 缺密钥时怎么补」http://localhost:5173打不开、5050端口不通api 容器状态与 5050 端口占用「端口被占用时怎么改」能登录但发消息没有任何回答curl http://localhost:5050/api/system/ready「worker 断连后怎么恢复」知识库检索空结果、文件解析失败milvus、etcd、graph 三个容器是否全部 healthy「Milvus 起不来时重启哪两个服务」对话回复模型调用失败.env里的SILICONFLOW_API_KEY与前端模型供应商配置「模型调用失败先查三处」分层排查网络与端口端口被占用时怎么改现象docker compose up输出Bind for 0.0.0.0:5050 failed: port is already allocated或页面一直转圈。原因Yuxi 固定占用宿主机 5050API与 5173前端这两个端口被别的进程占了。解决先查占用netstat -tulpn | grep :5050停掉占用进程或改 docker-compose.yml 中 api 服务的 ports 映射5050:5050改为6060:5050同步更新前端访问地址。执行netstat -tulpn | grep :5050后你应该看到类似tcp 0 0 0.0.0.0:5050 ... python的输出进程名就是占用者。改完端口后curl http://localhost:6060/docs能返回 API 文档页说明通了。构建期网络问题镜像拉取或docker build失败报错里出现proxy或timeout字样时是代理问题。先配代理再重试export HTTP_PROXYhttp://IP:PORT export HTTPS_PROXYhttp://IP:PORT执行后你应该看到镜像开始正常拉取、构建日志继续滚动。配置后反而失败就移除代理再试一次。容器与服务.env 缺密钥时怎么补现象api-dev 容器反复退出docker logs api-dev里有这行API_KEY_DERIVATION_SECRET:?Set API_KEY_DERIVATION_SECRET in .env [v0.7.2], or rerun bash scripts/init.sh.原因Compose 启动前会校验JWT_SECRET_KEY、API_KEY_DERIVATION_SECRET、SANDBOX_PROVISIONER_TOKEN三个安全密钥缺一个就拒绝启动。解决重新跑初始化脚本./scripts/init.shWindows 用.\scripts\init.ps1按提示自动生成并写入三个密钥手动配置时要求每个值至少 32 字符且三者不能复用同一个值执行docker compose up -d --build后docker ps你应该看到api-dev状态为Up且不再出现退出码。worker 断连后怎么恢复现象能登录、能建会话但发出去的消息永远没有回答curl http://localhost:5050/api/system/ready返回 503checks里worker一项是error。原因/api/system/ready检查启动完成状态、PostgreSQL、Redis 和 worker 续租四件事探针实现见 backend/package/yuxi/services/readiness_service.py。arq worker 在 Redis 断连后不会自动重连所以重建过 Redis 的部署几乎必现这个症状。解决先看容器docker ps -a | grep worker确认 worker-dev 是否还在运行重启 Redis 与 workerdocker compose up -d redis docker compose restart worker执行curl http://localhost:5050/api/system/ready后你应该看到status: ready四项 checks 全为ok。旧布局升级失败从旧文件布局升到 v0.7.2 时不能直接up先执行停机迁移bash scripts/migrate-storage.sh -f docker-compose.prod.yml --env-file .env.prod执行后docker ps -a中storage-migrator状态应为Exited (0)再执行docker compose -f docker-compose.prod.yml up -d --build启动核心服务。数据与存储Milvus 起不来时重启哪两个服务现象知识库列表为空、检索无结果docker logs api-dev反复出现连接milvus:19530失败。原因Milvus 依赖 etcd元数据与 minio对象存储先就绪三者任何一个是unhealthy向量库就不可用。解决查三者状态docker ps --filter healthstarting确认 etcd、minio、milvus 是否都过了健康检查单独拉起 Milvus 并让 API 重新建连docker compose up milvus -d docker restart api-dev执行curl http://localhost:9091/healthz你应该看到ok。注意 9091 只在 127.0.0.1 上暴露宿主机上直接访问才算数。模型与 API模型调用失败先查三处现象对话界面报模型调用失败或知识库入库时 Embedding 报超时。原因只有三类来源——API Key 无效、供应商地址配错、模型名与官方文档不一致。解决按序检查.env里的SILICONFLOW_API_KEYgrep SILICONFLOW_API_KEY .env执行后你应该看到一行非空的SILICONFLOW_API_KEYsk-...前端「模型管理」中的 Base URL 与 API Key以供应商官方 API 文档为准模型名称必须与官方列表完全一致含大小写改完后发一条测试消息你应该看到回答逐字流式返回而不是直接报错。Embedding 慢不是故障默认超时EMBEDDING_TIMEOUT是 600 秒入库大批量文件时耐心等。检索与生成链路检索没有引用怎么定位现象智能体能回答但回答里没有来源引用或知识图谱一直是空的。原因文档解析还没跑完或图谱构建服务graph 容器即 Neo4j异常。PDF/图片解析依赖 MinerU、PaddleX 两个 OCR 服务它们属于allprofile默认docker compose up不会启动没有它们时扫描件类文件解析不出文本。解决先看前端知识库文件列表的解析状态卡在「解析中」的优先处理查 Neo4jdocker logs graph --tail 50执行后你应该看到启动完成日志而不是Connection refused需要 OCR 时带 profile 重启docker compose -f docker-compose.prod.yml --profile all up -d --build前置条件是宿主机装好 NVIDIA Container Toolkit缺 GPU 时 mineru-api 会因显存不足启动失败可按 docker-compose.yml 中注释调低--gpu-memory-utilization到 0.5 甚至更低验证方式重新解析一个已存在的文件回答中出现可点击的来源引用即修复完成。预防与日常维护部署前检查清单.env已生成且含SILICONFLOW_API_KEY与三个安全密钥跑一遍./scripts/init.sh即可全补齐宿主机 5050、5173 端口空闲netstat -tulpn | grep -E :5050|:5173需要 OCR 的机器已装 NVIDIA 驱动与 Container Toolkitdocker run --rm --gpus all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi执行后你应该看到 GPU 列表不需要知识库/图谱的机器用make up-lite轻量模式启动少起 Milvus、Neo4j、etcd 五个重服务日志位置API 日志docker logs -f api-dev生产容器名api-prod前端/Nginx 日志docker logs -f web-dev生产web-prod容器内应用日志saves/logs/yuxi-{日期}.log健康检查端点端点证明什么期望返回GET /api/system/healthAPI 进程存活{status: ok}GET /api/system/ready可接流量启动完成 PostgreSQL Redis worker 续租200 且status: ready否则 503GET /api/system/discovery版本与能力发现含knowledge能力开关注意/api/system/health只证明进程活着不能替代业务验收判断「能不能用」以/api/system/ready为准。附录排查命令速查目的命令期望结果看全部容器状态docker psapi-dev、worker-dev、web-dev 均为Up查端口占用netstat -tulpn \| grep :5050只列出期望的 api-dev 进程查 API 就绪状态curl http://localhost:5050/api/system/ready200status: ready看 API 日志docker logs -f api-dev无连续Traceback单独拉起 Milvusdocker compose up milvus -d docker restart api-devcurl http://localhost:9091/healthz返回okRedis 断连后恢复 workerdocker compose up -d redis docker compose restart worker/api/system/ready转 200旧布局停机迁移bash scripts/migrate-storage.sh -f docker-compose.prod.yml --env-file .env.prodstorage-migratorExited (0)沙盒服务健康检查curl http://127.0.0.1:8002/health返回 200遇到本文没覆盖的报错先抓docker logs api-dev --tail 200里的第一条Traceback它比界面提示更靠近根因带着完整日志再提 issue响应会快很多。【免费下载链接】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），仅供参考