Yuxi-Know部署与运维深度指南从零到生产环境的完整解决方案【免费下载链接】Yuxi-Know基于大模型 RAG 知识库与知识图谱的问答平台。Llamaindex VueJS Flask Neo4j。大模型适配 OpenAI、国内主流大模型平台的模型调用、本地 vllm 部署。项目地址: https://gitcode.com/GitHub_Trending/yu/Yuxi-KnowYuxi-Know是一个基于大模型RAG知识库与知识图谱的智能问答平台集成了Llamaindex、VueJS、Flask和Neo4j等技术栈。本文将提供从部署启动到生产运维的完整解决方案涵盖容器化部署、模型配置、知识库检索等核心功能的问题诊断与修复。核心关键词Yuxi-Know部署、RAG知识库故障排除、知识图谱平台运维、Docker容器化问题、大模型配置错误部署启动问题诊断与解决方案1. Docker Compose服务启动失败故障现象执行docker compose up -d命令后部分或全部容器无法正常启动出现端口冲突、镜像拉取失败、环境变量缺失等错误。排查步骤检查端口占用情况# 检查常用端口占用 netstat -tulpn | grep -E :(5050|5173|7474|7687|9000|19530) lsof -i :5050 # 检查特定端口占用查看容器日志定位具体错误# 查看API服务日志 docker logs api-dev --tail 100 # 查看Web前端日志 docker logs web-dev --tail 50 # 查看数据库服务状态 docker logs postgres --tail 30验证环境变量配置# 检查.env文件是否存在 ls -la .env # 验证关键环境变量 grep -E SILICONFLOW_API_KEY|NEO4J_PASSWORD|MINIO_ACCESS_KEY .env修复方案端口冲突解决方案# 修改docker-compose.yml中的端口映射 # 例如将API端口从5050改为5051 sed -i s/5050:5050/5051:5050/g docker-compose.yml镜像拉取失败处理# 手动拉取基础镜像 docker pull python:3.12-slim docker pull neo4j:5.26 docker pull milvusdb/milvus:v2.5.6 # 使用脚本初始化 bash scripts/init.sh环境变量缺失修复# 创建.env文件模板 cat .env EOF # 必填配置 SILICONFLOW_API_KEYyour_siliconflow_api_key_here NEO4J_PASSWORDyour_secure_password MINIO_ACCESS_KEYminioadmin MINIO_SECRET_KEYminioadmin # 可选配置 TAVILY_API_KEYyour_tavily_api_key_here POSTGRES_PASSWORDpostgres REDIS_PASSWORD EOF预防建议使用生产环境配置docker compose -f docker-compose.prod.yml up -d --build提前规划端口映射避免与现有服务冲突将敏感配置存储在安全的密码管理器中定期更新基础镜像版本2. 数据库连接异常故障现象Neo4j知识图谱数据库连接失败PostgreSQL业务数据库无法访问Milvus向量数据库连接超时。排查步骤检查数据库服务健康状态# Neo4j连接测试 docker exec graph cypher-shell -u neo4j -p ${NEO4J_PASSWORD} RETURN 1; # PostgreSQL连接测试 docker exec postgres pg_isready -U postgres # Redis连接测试 docker exec redis redis-cli ping # Milvus健康检查 curl http://localhost:9091/healthz验证连接字符串配置# 查看API容器环境变量 docker exec api-dev env | grep -E POSTGRES|NEO4J|MILVUS|REDIS # 检查连接URL格式 echo POSTGRES_URL: ${POSTGRES_URL:-postgresqlasyncpg://postgres:postgrespostgres:5432/yuxi_know} echo NEO4J_URI: ${NEO4J_URI:-bolt://graph:7687} echo MILVUS_URI: ${MILVUS_URI:-http://milvus:19530}修复方案Neo4j连接问题修复# 重置Neo4j密码 docker exec graph cypher-shell -u neo4j -p neo4j ALTER CURRENT USER SET PASSWORD FROM neo4j TO new_password; # 更新环境变量 echo NEO4J_PASSWORDnew_password .envPostgreSQL数据库初始化# 进入PostgreSQL容器 docker exec -it postgres psql -U postgres # 创建数据库 CREATE DATABASE yuxi_know; # 验证表结构 \c yuxi_know \dtMilvus向量数据库配置# 检查Milvus服务状态 docker exec milvus curl -s http://localhost:9091/healthz # 查看Milvus日志 docker logs milvus --tail 50 # 重启Milvus服务 docker restart milvus验证步骤# 运行健康检查脚本 curl http://localhost:5050/api/system/health # 检查各组件连接状态 docker-compose ps模型服务配置与故障处理1. AI模型调用失败故障现象聊天界面返回模型调用错误API密钥无效基础URL配置错误网络连接超时。排查步骤检查模型配置文件backend/package/yuxi/config/static/models.py验证API密钥有效性# 测试SiliconFlow API连接 curl -H Authorization: Bearer $SILICONFLOW_API_KEY \ https://api.siliconflow.cn/v1/models # 测试OpenAI兼容接口 curl -H Authorization: Bearer $OPENAI_API_KEY \ https://api.openai.com/v1/models查看模型服务日志# 查看API服务中的模型调用日志 docker logs api-dev 21 | grep -i model\|api\|error | tail -20 # 检查网络连通性 docker exec api-dev curl -I https://api.siliconflow.cn修复方案更新模型配置文件# 在models.private.yml中添加自定义模型 openai: name: OpenAI base_url: https://api.openai.com/v1 default: gpt-4o env: OPENAI_API_KEY models: - gpt-4o - gpt-4-turbo - gpt-3.5-turbo配置多模型提供商# 设置环境变量 export OPENAI_API_KEYsk-... export DEEPSEEK_API_KEYsk-... export ZHIPUAI_API_KEYyour_zhipu_key # 验证配置 docker-compose restart api网络代理配置# 在.env文件中添加代理配置 HTTP_PROXYhttp://your-proxy:8080 HTTPS_PROXYhttp://your-proxy:8080 NO_PROXYlocalhost,127.0.0.1,milvus,graph,postgres2. 本地vLLM服务部署问题故障现象本地vLLM服务启动失败GPU显存不足模型加载超时。排查步骤检查GPU资源# 查看GPU状态 nvidia-smi # 检查Docker GPU支持 docker run --rm --gpus all nvidia/cuda:12.1.0-base nvidia-smi查看vLLM服务日志docker logs mineru-vllm-server --tail 50 docker logs mineru-api --tail 50验证模型文件# 检查模型目录 ls -la ${MODEL_DIR:-./models}/ # 验证模型格式 file ${MODEL_DIR}/your-model/model.safetensors修复方案GPU资源优化配置# 在docker-compose.yml中调整vLLM配置 mineru-vllm-server: deploy: resources: reservations: devices: - driver: nvidia device_ids: [0] capabilities: [gpu] command: - --host 0.0.0.0 - --port 30000 - --gpu-memory-utilization 0.5 # 降低显存使用率 - --max-model-len 8192 # 限制模型长度多GPU并行配置mineru-vllm-server: command: - --host 0.0.0.0 - --port 30000 - --data-parallel-size 2 # 使用2个GPU - --tensor-parallel-size 1 - --gpu-memory-utilization 0.8模型下载与验证# 使用HuggingFace下载模型 docker exec mineru-vllm-server \ python -c from transformers import AutoModel; AutoModel.from_pretrained(Qwen/Qwen2.5-7B-Instruct)预防建议定期监控GPU显存使用nvidia-smi --query-gpumemory.used --formatcsv设置模型缓存目录export HF_HOME/path/to/cache使用量化模型减少显存占用配置模型预热机制知识库与知识图谱问题诊断1. 文档索引与检索异常故障现象文档上传后无法检索向量化失败检索结果不准确知识库服务无响应。排查步骤检查知识库服务状态# 查看知识库处理日志 docker logs api-dev 21 | grep -i knowledge\|index\|vector | tail -30 # 检查Milvus连接 docker exec api-dev python -c import pymilvus from pymilvus import connections connections.connect(hostmilvus, port19530) print(Milvus连接成功) 验证文档处理流水线# 查看文档解析日志 docker logs api-dev 21 | grep -i parser\|chunk\|embed | tail -20 # 检查文件存储 docker exec api-dev ls -la /app/saves/knowledge/测试检索功能# 使用API测试检索 curl -X POST http://localhost:5050/api/knowledge/search \ -H Content-Type: application/json \ -d {query: 测试查询, kb_id: 1, top_k: 5}修复方案重建向量索引# 在Python交互环境中执行 from yuxi.knowledge.manager import KnowledgeBaseManager manager KnowledgeBaseManager() kb manager.get_knowledge_base(1) kb.rebuild_index()检查分块配置# 查看分块参数配置 from yuxi.knowledge.chunking.ragflow_like.dispatcher import ChunkDispatcher dispatcher ChunkDispatcher() print(dispatcher.get_available_parsers())手动触发文档处理# 通过API重新处理文档 curl -X POST http://localhost:5050/api/knowledge/1/reprocess \ -H Content-Type: application/json \ -d {force: true}验证步骤# 验证知识库健康状态 curl http://localhost:5050/api/knowledge/1/status # 测试检索性能 time curl -X POST http://localhost:5050/api/knowledge/search \ -H Content-Type: application/json \ -d {query: 系统架构, kb_id: 1}2. 知识图谱构建与查询问题故障现象Neo4j图数据库连接失败知识图谱可视化异常图查询返回空结果。排查步骤检查Neo4j服务# 验证Neo4j连接 docker exec graph cypher-shell -u neo4j -p $NEO4J_PASSWORD \ MATCH (n) RETURN count(n) as node_count; # 查看图数据库大小 docker exec graph du -sh /data/databases/验证知识图谱数据# 检查图谱节点类型 docker exec graph cypher-shell -u neo4j -p $NEO4J_PASSWORD \ CALL db.labels() YIELD label RETURN label; # 查看关系类型 docker exec graph cypher-shell -u neo4j -p $NEO4J_PASSWORD \ CALL db.relationshipTypes() YIELD relationshipType RETURN relationshipType;测试图查询性能# 执行复杂查询测试 docker exec graph cypher-shell -u neo4j -p $NEO4J_PASSWORD \ PROFILE MATCH (n)-[r]-(m) RETURN n.entity_type, type(r), m.entity_type LIMIT 100;修复方案Neo4j数据库优化-- 创建索引优化查询性能 CREATE INDEX entity_type_index IF NOT EXISTS FOR (n:Entity) ON (n.entity_type); CREATE INDEX entity_name_index IF NOT EXISTS FOR (n:Entity) ON (n.name); -- 清理无效数据 MATCH (n) WHERE n.created_at IS NULL DETACH DELETE n;知识图谱重建# 重新构建知识图谱 from yuxi.knowledge.graphs.upload_graph_service import GraphUploadService service GraphUploadService() service.rebuild_graph_from_knowledge_base(kb_id1)图数据库连接池配置# 在backend/package/yuxi/config/app.py中调整 NEO4J_CONFIG { uri: os.getenv(NEO4J_URI, bolt://graph:7687), auth: (os.getenv(NEO4J_USERNAME, neo4j), os.getenv(NEO4J_PASSWORD, 0123456789)), max_connection_lifetime: 3600, max_connection_pool_size: 50, }预防建议定期备份Neo4j数据库docker exec graph neo4j-admin dump --to/backup/neo4j.dump监控图数据库性能使用Neo4j Browser的:sysinfo命令设置自动清理任务定期删除过期节点优化Cypher查询使用参数化查询避免注入系统监控与日志分析1. 日志配置与错误追踪故障现象日志文件过大错误信息不清晰难以定位问题根源。排查步骤检查日志配置backend/package/yuxi/utils/logging_config.py查看应用日志# 查看最新的错误日志 tail -f saves/logs/yuxi-$(date %Y-%m-%d).log | grep -E ERROR|CRITICAL # 按时间范围搜索日志 grep 2026-03-25 saves/logs/yuxi-*.log | head -20分析容器日志# 查看所有容器日志摘要 docker-compose logs --tail50 --timestamps # 按服务过滤日志 docker-compose logs api --tail100 docker-compose logs worker --tail100修复方案调整日志级别# 临时调整日志级别为DEBUG import logging from yuxi.utils.logging_config import logger logger.setLevel(logging.DEBUG)配置日志轮转# 在logging_config.py中调整 loguru_logger.add( LOG_FILE, levellevel, format{time:YYYY-MM-DD HH:mm:ss} - {level} - {file}:{line} - {message}, encodingutf-8, rotation10 MB, # 每10MB轮转 retention30 days, # 保留30天 compressionzip, # 压缩旧日志 enqueueTrue, )结构化日志输出# 使用jq解析JSON格式日志 docker logs api-dev --tail 100 | jq -r . | select(.levelERROR)2. 性能监控与优化故障现象系统响应缓慢内存使用过高CPU占用率持续高位。排查步骤监控系统资源# 查看容器资源使用 docker stats --no-stream # 检查进程资源占用 docker exec api-dev top -b -n 1 # 监控网络连接 docker exec api-dev netstat -tulpn | grep -E 5050|8000分析API性能# 使用ab进行压力测试 ab -n 100 -c 10 http://localhost:5050/api/system/health # 监控响应时间 curl -o /dev/null -s -w Time: %{time_total}s\n http://localhost:5050/api/system/health数据库性能分析# PostgreSQL查询分析 docker exec postgres psql -U postgres -d yuxi_know \ -c SELECT query, calls, total_time, mean_time FROM pg_stat_statements ORDER BY total_time DESC LIMIT 10;修复方案优化数据库连接池# 在数据库配置中调整连接池 DATABASE_CONFIG { pool_size: 20, max_overflow: 30, pool_recycle: 3600, pool_pre_ping: True, }缓存策略优化# 调整Redis配置 docker exec redis redis-cli CONFIG SET maxmemory 1gb docker exec redis redis-cli CONFIG SET maxmemory-policy allkeys-lru异步任务队列优化# 调整worker配置 ARQ_CONFIG { redis_settings: REDIS_URL, worker_settings: { max_jobs: 10, queue_name: default, on_startup: startup, on_shutdown: shutdown, } }验证步骤# 运行性能测试脚本 python -m backend.test.test_concurrency # 检查内存泄漏 docker stats --format table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}生产环境部署最佳实践1. 安全配置与防护关键配置环境变量安全# 使用.env.prod文件存储生产配置 cp .env .env.prod chmod 600 .env.prod # 设置强密码 export NEO4J_PASSWORD$(openssl rand -base64 32) export POSTGRES_PASSWORD$(openssl rand -base64 32) export MINIO_ACCESS_KEY$(openssl rand -hex 16) export MINIO_SECRET_KEY$(openssl rand -hex 32)网络隔离配置# 在docker-compose.prod.yml中添加网络配置 networks: frontend: driver: bridge backend: driver: bridge database: internal: true # 内部网络外部不可访问HTTPS配置# nginx配置SSL server { listen 443 ssl http2; server_name your-domain.com; ssl_certificate /etc/ssl/certs/your-domain.crt; ssl_certificate_key /etc/ssl/private/your-domain.key; location / { proxy_pass http://web:5173; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } location /api/ { proxy_pass http://api:5050; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } }2. 高可用与备份策略部署架构多节点部署# docker-compose.prod.yml扩展 services: api: deploy: mode: replicated replicas: 3 resources: limits: memory: 2G reservations: memory: 1G healthcheck: test: [CMD, curl, -f, http://localhost:5050/api/system/health] interval: 30s timeout: 10s retries: 3 start_period: 40s数据备份策略# 每日数据库备份脚本 #!/bin/bash BACKUP_DIR/backup/$(date %Y%m%d) mkdir -p $BACKUP_DIR # PostgreSQL备份 docker exec postgres pg_dump -U postgres yuxi_know $BACKUP_DIR/postgres.sql # Neo4j备份 docker exec graph neo4j-admin dump --to$BACKUP_DIR/neo4j.dump # MinIO数据备份 docker exec milvus-minio mc mirror /minio_data $BACKUP_DIR/minio/ # 压缩备份 tar -czf $BACKUP_DIR.tar.gz $BACKUP_DIR监控告警配置# Prometheus监控配置 scrape_configs: - job_name: yuxi-api static_configs: - targets: [api:5050] metrics_path: /metrics - job_name: yuxi-db static_configs: - targets: [postgres:9187, redis:9121]快速故障排查清单1. 服务启动检查清单# 1. 检查Docker服务状态 docker-compose ps docker-compose logs --tail20 # 2. 验证端口占用 ss -tulpn | grep -E 5050|5173|7474|7687 # 3. 检查环境变量 docker exec api-dev env | grep -E API_KEY|PASSWORD|URL # 4. 测试API端点 curl -f http://localhost:5050/api/system/health # 5. 验证数据库连接 docker exec postgres pg_isready -U postgres docker exec redis redis-cli ping2. 性能问题排查清单# 1. 资源监控 docker stats --no-stream nvidia-smi # GPU系统 # 2. 日志分析 tail -f saves/logs/yuxi-*.log | grep -E ERROR|WARNING|slow # 3. 网络延迟测试 ping -c 4 api.siliconflow.cn curl -o /dev/null -s -w %{time_total}\n https://api.openai.com # 4. 数据库性能 docker exec postgres psql -U postgres -d yuxi_know -c VACUUM ANALYZE;3. 紧急恢复步骤# 1. 停止所有服务 docker-compose down # 2. 备份关键数据 cp -r saves/ saves_backup_$(date %Y%m%d_%H%M%S)/ docker exec postgres pg_dumpall -U postgres postgres_backup.sql # 3. 清理临时文件 docker system prune -f rm -rf docker/volumes/postgresql/data/* # 4. 重新启动 docker-compose up -d --build docker-compose logs -f api通过本文提供的系统化故障排查方案您可以快速定位和解决Yuxi-Know平台在部署、运行和优化过程中遇到的各种问题。建议定期检查系统日志、监控资源使用情况并建立完善的备份恢复机制确保平台的稳定运行。【免费下载链接】Yuxi-Know基于大模型 RAG 知识库与知识图谱的问答平台。Llamaindex VueJS Flask Neo4j。大模型适配 OpenAI、国内主流大模型平台的模型调用、本地 vllm 部署。项目地址: https://gitcode.com/GitHub_Trending/yu/Yuxi-Know创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考