localGPT RAG 系统部署实战：Docker 生产部署与直接开发模式完整指南

localGPT RAG 系统部署实战Docker 生产部署与直接开发模式完整指南【免费下载链接】localGPTChat with your documents on your local device using GPT models. No data leaves your device and 100% private.项目地址: https://gitcode.com/GitHub_Trending/lo/localGPT本指南以Documentation/deployment_guide.md为核心骨架面向需要将 localGPT 本地化 RAG检索增强生成系统落地到生产或开发环境的开发者。文中所有命令与配置均经过当前仓库源码核对覆盖 Docker 容器化部署与直接开发两种路径的完整步骤、架构选型、环境变量、性能调优、运维备份与故障排查。读完本文你将掌握从零搭建一套 100% 本地私有、数据不出设备的文档问答系统并能独立完成部署验证、日志管理、备份恢复与性能诊断。一、部署方式总览两种路径如何选localGPT 的 RAG 系统由四个核心进程组成前端Next.js端口 3000、后端 APIPython端口 8000、RAG API文档处理与检索推理端口 8001以及Ollama本地大模型推理服务端口 11434。仓库为这套组件提供了两种部署路径维度Option 1Docker 部署生产Option 2直接开发开发调试适用场景生产环境、容器化交付、水平扩展开发调试、深度定制、快速迭代优势环境隔离、可复现、易管理直接接触代码、迭代快、调试方便劣势配置略复杂、有资源开销需要自行管理更多依赖部署文档 deployment_guide.md 明确建议生产环境优先 Docker开发环境优先直接运行。两条路径共享同一个 Ollama 服务运行在宿主机上仅应用层前端/后端/RAG API的承载方式不同。二、前置条件检查2.1 系统资源要求最低配置可运行CPU4 核2.5GHz内存8GB建议 16GB存储50GB 可用空间操作系统Linux、macOS或带 WSL2 后端的 Windows推荐配置承载大模型CPU8 核以上3.0GHz内存32GB用于大型模型推理与 Embedding存储200GB SSDGPUNVIDIA GPU显存 8GB可选用于推理加速注意以上为部署文档给出的基准值。若使用qwen3:8b这类生成模型内存与显存占用会显著上升建议优先按推荐配置准备。2.2 通用依赖两种方式都需要# Ollama两种部署方式均依赖且运行在宿主机 curl -fsSL https://ollama.ai/install.sh | sh # Git用于克隆仓库需要 2.302.3 Docker 部署专属依赖# Docker Engine 24.0 与 Docker Compose 2.202.4 直接开发专属依赖# Python 3.8仓库 Docker 镜像实际使用 python:3.11-slim见 Dockerfile # Node.js 16 与 npm 8仓库前端 Docker 镜像使用 node:18-alpine事实核对仓库的 Dockerfile.backend 与 Dockerfile.rag-api 均基于python:3.11-slim构建Dockerfile.frontend 基于node:18-alpine因此本地直接开发时建议使用 Python 3.11 与 Node 18 以获得与生产镜像一致的环境。三、Docker 部署生产路径3.1 安装 DockerUbuntu/Debian# 安装 Docker curl -fsSL https://get.docker.com -o get-docker.sh sudo sh get-docker.sh sudo usermod -aG docker $USER newgrp docker # 安装 Docker Compose V2 插件 sudo apt-get update sudo apt-get install docker-compose-pluginmacOSbrew install --cask dockerWindows安装带 WSL2 后端的 Docker Desktop在 Docker 官网下载安装包。3.2 克隆仓库git clone 当前仓库地址 localGPT cd localGPT3.3 安装并启动 OllamaOllama 始终跑在宿主机# 安装 Ollama curl -fsSL https://ollama.ai/install.sh | sh # 启动 Ollama 服务 ollama serve # 另开一个终端拉取生成模型 ollama pull qwen3:0.6b ollama pull qwen3:8b源码佐证run_system.py 中的ensure_models()方法会在启动时自动核对qwen3:8b与qwen3:0.6b两个必需模型缺失时自动执行ollama pull5 分钟超时。这也是 Docker 与直接开发两条路径共用的模型基线。3.4 启动容器系统# 推荐使用仓库自带的便捷脚本 ./start-docker.sh # 等价于手动执行 docker compose --env-file docker.env up --build -dstart-docker.sh详解该脚本封装了本地 Ollama 检测与容器编排支持以下子命令./start-docker.sh local # 使用宿主机 Ollama默认推荐 ./start-docker.sh container # 使用容器化 Ollama--profile with-ollama ./start-docker.sh stop # 停止全部容器 ./start-docker.sh logs # 查看容器日志CtrlC 退出 ./start-docker.sh status # 查看容器状态 ./start-docker.sh help # 查看帮助脚本的默认逻辑值得注意见 start-docker.sh首先检测http://localhost:11434/api/tags是否有本地 Ollama 响应检测通过则执行docker compose --env-file docker.env up --build -d启动不含Ollama 容器的三个应用容器检测失败会提示你先启动ollama serve或交互式询问是否改用容器化 Ollama./start-docker.sh container。容器化 Ollama 模式通过docker compose --profile with-ollama up --build -d启动对应 docker-compose.yml 中带profiles: [with-ollama]的ollama服务数据持久化在ollama_data卷中。3.5 验证部署# 查看容器状态 docker compose ps # 逐端点健康检查 curl http://localhost:3000 # 前端 curl http://localhost:8000/health # 后端 API curl http://localhost:8001/models # RAG API返回生成/嵌入模型列表 curl http://localhost:11434/api/tags # Ollama端点事实核对三个容器的健康检查分别对应 docker-compose.yml 中的healthcheck配置——前端探测http://localhost:3000、后端探测http://localhost:8000/health、RAG API 探测http://localhost:8001/models。其中backend/server.py的/health返回{status: ok}等 JSON 状态rag_system/api_server.py的/models端点会动态汇总 Ollama 已安装模型与内置 HuggingFace 嵌入模型Qwen/Qwen3-Embedding-0.6B / -4B / -8B。3.6 Docker 日常管理整体操作./start-docker.sh # 启动系统 ./start-docker.sh stop # 停止系统等价 docker compose down ./start-docker.sh logs # 查看日志 ./start-docker.sh status # 查看状态 # 手动 Docker Compose 命令 docker compose ps # 查看状态 docker compose logs -f # 跟踪日志 docker compose down # 停止全部容器 docker compose up --build -d # 重新构建并启动单个容器管理# 重启指定服务 docker compose restart rag-api # 查看指定服务日志 docker compose logs -f backend # 进入容器执行命令 docker compose exec rag-api python -c print(Hello)容器结构与卷挂载依据 docker-compose.yml服务容器名端口关键卷挂载rag-apirag-api8001./lancedb、./index_store、./shared_uploadsbackendrag-backend8000./backend、./shared_uploadsfrontendrag-frontend3000无数据卷纯静态构建产物ollama可选rag-ollama11434ollama_data:/root/.ollama容器之间存在健康依赖链frontend depends_on backendhealthybackend depends_on rag-apihealthy保证启动顺序正确。四、直接开发部署开发调试路径4.1 安装依赖# 克隆仓库 git clone 当前仓库地址 localGPT cd localGPT # 创建 Python 虚拟环境推荐 python -m venv venv source venv/bin/activate # Windows: venv\Scripts\activate # 安装 Python 依赖 pip install -r requirements.txt # 安装前端依赖 npm install提示仓库还提供了 requirements-docker.txtDocker 专用依赖清单含transformers4.51.0、torch2.4.1、docling、colpali-engine、lancedb、rerankers等并注明移除了 macOS 专属的ocrmac。直接开发时按 requirements.txt 安装即可。4.2 安装并配置 Ollamacurl -fsSL https://ollama.ai/install.sh | sh ollama serve # 另开终端拉取模型 ollama pull qwen3:0.6b ollama pull qwen3:8b4.3 启动系统方式 A一体化启动器推荐python run_system.pyrun_system.py 是仓库的统一进程编排器启动后自动完成前置检查验证ollama、python、npm是否存在于 PATH缺失工具直接报错npm 缺失时仅禁用前端并降级为非必需服务依赖顺序启动按ollama → rag-api → backend → frontend顺序拉起进程源码中service_order定义每个服务带独立启动延迟与端口占用检测is_port_in_use基于 psutil模型自检调用ensure_models()确保qwen3:8b与qwen3:0.6b已就绪彩色聚合日志各服务日志按服务名着色输出到终端同时落盘到logs/service.log与logs/system.log进程守护每 30 秒巡检一次必需服务意外退出会自动重启优雅停机响应 CtrlC / SIGTERM按逆序terminate()10 秒宽限后kill()。启动器还支持丰富的命令行参数python run_system.py --mode prod # 生产模式前端改用 npm run start python run_system.py --no-frontend # 跳过前端无 Node 环境时 python run_system.py --health # 仅打印各服务状态摘要 python run_system.py --logs-only # 仅跟踪已有日志 python run_system.py --stop # 停止全部进程方式 B手动分进程启动# 终端 1RAG API端口 8001 python -m rag_system.api_server # 终端 2后端端口 8000 cd backend python server.py # 终端 3前端端口 3000 npm run dev # 浏览器访问 http://localhost:30004.4 验证安装# 一键健康体检 python system_health_check.py # 手动测试端点 curl http://localhost:3000 # 前端 curl http://localhost:8000/health # 后端 curl http://localhost:8001/models # RAG APIsystem_health_check.py体检项说明共 6 项检查源码见 system_health_check.py检查项验证内容基础导入能否成功 importrag_system.main中的核心对象配置检查输出EXTERNAL_MODELS、OLLAMA_CONFIG、PIPELINE_CONFIGS并提示 Embedding 维度384 维 bge 系 vs 1024 维 Qwen3 系兼容性LanceDB 访问连接./lancedb列出已有表无表时会提示需先建索引Agent 初始化调用get_agent(default)构建默认智能体Embedding 模型真实跑一次create_embeddings([test])打印模型名与向量维度示例查询若有索引表对首个表发起一次真实问答并打印答案摘要全部通过时输出System is healthy!否则会给出具体失败项定位问题。4.5 直接开发日常管理# 启动系统 python run_system.py # 健康检查 python system_health_check.py # 停止系统在运行 run_system.py 的终端按 CtrlC # 单独启动组件 python -m rag_system.api_server # RAG API8001 cd backend python server.py # 后端8000 npm run dev # 前端3000 # 前端生产构建 npm run build # 升级 Python 依赖 pip install -r requirements.txt --upgrade五、两种部署架构对比5.1 Docker 部署架构5.2 直接开发架构两种架构的调用链完全一致前端3000→ 后端8000→ RAG API8001→ Ollama11434。区别仅在于应用层承载在容器还是本机进程Ollama 在两种方案中都建议运行在宿主机以保证模型数据与显存调度的最大灵活性若希望全部容器化可用start-docker.sh container开启with-ollamaprofile。六、配置详解6.1 环境变量Docker 配置docker.env# Ollama 配置 # 使用 Docker 网关 IP172.18.0.1而非 host.docker.internal以保证 Linux 兼容 OLLAMA_HOSThttp://172.18.0.1:11434 # 备选使用容器化 Ollama 时改为配合 --profile with-ollama # OLLAMA_HOSThttp://ollama:11434 # 服务配置 NODE_ENVproduction NEXT_PUBLIC_API_URLhttp://localhost:8000 # 前端访问后端的地址 RAG_API_URLhttp://rag-api:8001 # 后端访问 RAG API 的容器内地址事实说明部署文档原稿写的是host.docker.internal但仓库 docker.env 注释明确说明改用 Docker 网关 IP 以获得 Linux 兼容性。docker-compose.yml中同时以${OLLAMA_HOST:-...}形式提供默认值兜底其中 rag-api 默认指向http://host.docker.internal:11434backend 默认指向http://172.18.0.1:11434——因此通过--env-file docker.env传入统一变量是最可控的方式。另有 docker-compose.local-ollama.yml 提供仅连接宿主 Ollama的精简 Compose 变体。直接开发配置# run_system.py 会自动设置环境变量 # 需要覆盖时手动导出 export OLLAMA_HOSThttp://localhost:11434 export RAG_API_URLhttp://localhost:80016.2 模型配置默认模型基线与 run_system.py 的required_models及部署文档一致# 生成模型经 Ollama 提供 qwen3:0.6b # 快速响应 qwen3:8b # 高质量回答 # 嵌入模型由 rag_system/api_server.py 的 /models 端点提供候选 Qwen/Qwen3-Embedding-0.6B # 快速1024 维 Qwen/Qwen3-Embedding-4B # 高质量2048 维 Qwen/Qwen3-Embedding-8B # 更高质量api_server.py 中同样支持模型发现的实现细节rag_system/api_server.py的handle_models会先调用 Ollama 的/api/tags拉取已安装模型并按名称启发式分类含embed/bge/embedding/text关键词的归入嵌入模型其余归入生成模型再追加内置的 HuggingFace 嵌入模型候选最终返回{generation_models: [...], embedding_models: [...]}供前端下拉选择。6.3 性能调优内存设置# Docker DesktopSettings → Resources → Memory → 16GB # 直接开发用 htopmacOS 用 top监控内存批处理与分块参数部署文档给出的调优基准RAM 不足时降低数值EMBEDDING_BATCH_SIZE 50 # 嵌入批大小OOM 时减小 ENRICHMENT_BATCH_SIZE 25 # 富化批大小OOM 时减小 CHUNK_SIZE 512 # 文本分块大小 CHUNK_OVERLAP 64 # 分块重叠窗口关联阅读分块与索引流水线的详细参数见 indexing_pipeline.md 与 indexing 模块检索侧还有retrieval_k、context_window_size、reranker_top_k、search_type等运行时参数可通过/chat接口的请求体传入见 api_server.py。七、运维流程7.1 系统监控健康检查一键脚本式curl -f http://localhost:3000 echo Frontend OK curl -f http://localhost:8000/health echo Backend OK curl -f http://localhost:8001/models echo RAG API OK curl -f http://localhost:11434/api/tags echo Ollama OK性能监控docker stats # Docker 容器资源占用 htop # 直接开发整体系统监控 nvidia-smi # GPU 使用情况如有 NVIDIA GPU7.2 日志管理Docker 日志docker compose logs -f # 全部服务 docker compose logs -f rag-api # 指定服务 docker compose logs system.log 21 # 落盘保存直接开发日志# 日志默认输出到终端run_system.py 同时写入 logs/ 目录 python run_system.py system.log 21 # 查看聚合日志 tail -f logs/*.log7.3 备份与恢复数据备份关键数据为 LanceDB 向量库、索引存储与 SQLite 会话库# 创建按日期命名的备份目录 mkdir -p backups/$(date %Y%m%d) # 备份数据库与索引 cp -r backend/chat_data.db backups/$(date %Y%m%d)/ # SQLite 会话数据库文件 cp -r lancedb backups/$(date %Y%m%d)/ # 向量数据库 cp -r index_store backups/$(date %Y%m%d)/ # 索引元数据存储 # Docker 环境额外备份 Ollama 模型卷需先停止容器 docker compose down docker run --rm \ -v rag_system_old_ollama_data:/data \ -v $(pwd)/backups:/backup \ alpine tar czf /backup/ollama_models_$(date %Y%m%d).tar.gz -C /data .数据恢复# 停止系统 ./start-docker.sh stop # Docker # 或直接开发下按 CtrlC # 恢复文件 cp -r backups/YYYYMMDD/* ./ # 重启系统 ./start-docker.sh # Docker python run_system.py # 直接开发说明backend/chat_data.db实际是 SQLite 数据库文件由backend/server.py初始化备份时直接拷贝文件即可向量数据主体位于lancedb/目录由system_health_check.py中的lancedb.connect(./lancedb)确认。八、故障排查8.1 常见问题端口冲突3000/8000/8001/11434# 检查端口占用 lsof -i :3000 -i :8000 -i :8001 -i :11434 # Docker 方案停止冲突容器 ./start-docker.sh stop # 直接开发方案结束相关进程 pkill -f npm run dev pkill -f server.py pkill -f api_serverDocker 问题docker version # 检查 daemon 是否响应 sudo systemctl restart docker # Linux 重启 docker 服务 # macOS/Windows重启 Docker Desktop docker system prune -f # 清理 Docker 缓存Ollama 问题curl http://localhost:11434/api/tags # 检查 Ollama 状态 pkill ollama # 重启 Ollama ollama serve ollama pull qwen3:0.6b # 重新拉取模型 ollama pull qwen3:8b8.2 性能问题内存不足free -h # Linux 内存检查 vm_stat # macOS 内存检查 docker stats # 容器内存占用 # 解决方案 # 1. 增加系统内存 # 2. 调低 6.3 节中的批大小参数 # 3. 改用更小模型qwen3:0.6b 代替 qwen3:8b响应缓慢curl http://localhost:11434/api/tags # 检查模型加载状态 time curl http://localhost:8001/models # 测量组件响应耗时 # 解决方案 # 1. 使用 SSD 存储 # 2. 增加 CPU 核数 # 3. 启用 GPU 加速如有 NVIDIA GPU九、生产环境考量9.1 安全网络安全生产环境前置反向代理nginx / traefik统一入口启用 HTTPS/TLS 加密传输用防火墙限制端口暴露范围仅对外开放 443/80内部端口如 8000/8001 不直接暴露公网。数据安全生产环境启用身份认证敏感数据加密存储保持依赖与系统安全更新。9.2 扩展与资源优化水平扩展使用 Docker Swarm 或 Kubernetes 编排多副本对前端与后端做负载均衡依据负载水平伸缩 RAG API 实例其工作负载为文档处理与检索推理最值得扩展。资源优化为 AI 推理任务配备专用 GPU 节点实现模型缓存避免重复加载优化批处理与分块参数提升吞吐。十、成功标准与验收10.1 部署成功判定当以下条件全部满足时即视为部署成功所有健康检查通过前端 3000 / 后端/health/ RAG API/models/ Ollama/api/tags前端在 http://localhost:3000 正常加载能够成功创建文档索引Index Creation 流程可用能够与已上传文档进行对话Chat 流程可用日志中无报错信息。10.2 性能验收参考以下为部署文档给出的验收基准非基准测试数据供部署后自评参考指标可接受水平最优水平索引创建每 100MB 文档 2 分钟每 100MB 文档 1 分钟复杂问题查询响应 30 秒 10 秒系统内存占用 8GB 16GB相关文档导航系统总览 与 架构总览理解各模块职责与调用关系索引流水线 与 检索流水线深入理解分块、Embedding、重排与 Agent 检索链路安装指南 与 快速开始面向首次上手的精简流程Docker 使用手册 与 Docker 故障排查容器化场景的补充说明API 参考RAG API 各端点的请求/响应契约【免费下载链接】localGPTChat with your documents on your local device using GPT models. No data leaves your device and 100% private.项目地址: https://gitcode.com/GitHub_Trending/lo/localGPT创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考