企业官网建设流程全解析

Yuxi：部署报错与故障排查完整指南

【免费下载链接】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 是一个可私有部署的多租户知识智能体平台，把 RAG 检索、知识图谱、多智能体放进同一个工作台。本文覆盖你部署或使用 Yuxi 时最常遇到的报错：容器起不来、前端打不开、worker 不续租、模型调用失败、检索无结果，按「从外到内」五层给你一套可照做的排查路径。

30 秒快速自检

拿到报错先对表，排除五个最高频原因：

分层排查

网络与端口：端口被占用时怎么改

现象：docker compose up输出Bind for 0.0.0.0:5050 failed: port is already allocated，或页面一直转圈。

原因：Yuxi 固定占用宿主机 5050（API）与 5173（前端），这两个端口被别的进程占了。

解决：

1. 先查占用：netstat -tulpn | grep :5050
2. 停掉占用进程，或改 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_PROXY=http://IP:PORT export HTTPS_PROXY=http://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三个安全密钥，缺一个就拒绝启动。

解决：

1. 重新跑初始化脚本：./scripts/init.sh（Windows 用.\scripts\init.ps1），按提示自动生成并写入三个密钥
2. 手动配置时要求每个值至少 32 字符，且三者不能复用同一个值

执行docker compose up -d --build后docker ps，你应该看到api-dev状态为Up，且不再出现退出码。

worker 断连后怎么恢复

现象：能登录、能建会话，但发出去的消息永远没有回答；curl http://localhost:5050/api/system/ready返回 503，checks里worker一项是error。

原因：/api/system/ready检查启动完成状态、PostgreSQL、Redis 和 worker 续租四件事（探针实现见 backend/package/yuxi/services/readiness_service.py）。arq worker 在 Redis 断连后不会自动重连，所以重建过 Redis 的部署几乎必现这个症状。

解决：

1. 先看容器：docker ps -a | grep worker，确认 worker-dev 是否还在运行
2. 重启 Redis 与 worker：

docker 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，向量库就不可用。

解决：

1. 查三者状态：docker ps --filter "health=starting"，确认 etcd、minio、milvus 是否都过了健康检查
2. 单独拉起 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 无效、供应商地址配错、模型名与官方文档不一致。

解决（按序检查）：

1. .env里的SILICONFLOW_API_KEY：grep SILICONFLOW_API_KEY .env，执行后你应该看到一行非空的SILICONFLOW_API_KEY=sk-...
2. 前端「模型管理」中的 Base URL 与 API Key：以供应商官方 API 文档为准
3. 模型名称：必须与官方列表完全一致，含大小写

改完后发一条测试消息，你应该看到回答逐字流式返回，而不是直接报错。Embedding 慢不是故障，默认超时EMBEDDING_TIMEOUT是 600 秒，入库大批量文件时耐心等。

检索与生成链路：检索没有引用怎么定位

现象：智能体能回答，但回答里没有来源引用，或知识图谱一直是空的。

原因：文档解析还没跑完，或图谱构建服务（graph 容器，即 Neo4j）异常。PDF/图片解析依赖 MinerU、PaddleX 两个 OCR 服务，它们属于allprofile，默认docker compose up不会启动，没有它们时扫描件类文件解析不出文本。

解决：

1. 先看前端知识库文件列表的解析状态，卡在「解析中」的优先处理
2. 查 Neo4j：docker logs graph --tail 50，执行后你应该看到启动完成日志，而不是Connection refused
3. 需要 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 Toolkit：docker 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

健康检查端点：

注意/api/system/health只证明进程活着，不能替代业务验收；判断「能不能用」以/api/system/ready为准。

附录：排查命令速查

遇到本文没覆盖的报错，先抓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