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/YuxiYuxi-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 allocatedweb 端则是 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.shWindows 用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只看第一条错误。验证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_URIbolt://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、webLITE_MODEtrue下 graph 与 milvus 根本不拉起。修复docker compose ps确认 graph、milvus 是否在跑。需要图谱与向量检索时切回完整模式docker compose up --build。验证知识库页面能看到图谱构建任务检索返回引用来源。文档解析失败图片、PDF 一直卡在解析中现象上传backend/test/data/测试图片.png这类图片或 PDF 后状态长时间不更新。根因解析依赖 mineru-api30001和 paddlex8080二者属于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重建相关服务。验证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），仅供参考 Yuxi-Know故障排除速查：五个阶段搞定部署报错
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/YuxiYuxi-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 allocatedweb 端则是 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.shWindows 用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只看第一条错误。验证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_URIbolt://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、webLITE_MODEtrue下 graph 与 milvus 根本不拉起。修复docker compose ps确认 graph、milvus 是否在跑。需要图谱与向量检索时切回完整模式docker compose up --build。验证知识库页面能看到图谱构建任务检索返回引用来源。文档解析失败图片、PDF 一直卡在解析中现象上传backend/test/data/测试图片.png这类图片或 PDF 后状态长时间不更新。根因解析依赖 mineru-api30001和 paddlex8080二者属于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重建相关服务。验证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），仅供参考