LocalGPT 容器化部署完全指南基于 Docker 与本地 Ollama 的私有化 RAG 系统搭建【免费下载链接】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导读本指南以仓库根目录的 DOCKER_README.md 为核心骨架系统讲解如何在 Docker 容器中运行 LocalGPT——一个完全本地化的文档对话系统前端 Next.js 界面、后端会话网关与 RAG API 检索服务三者容器化而大模型推理交给宿主机上的 Ollama实现数据不出本机、100% 私有。读完本文你将掌握5 分钟快速启动流程、三容器 本地 Ollama 的架构与数据卷设计、docker.env与模型配置的每一项参数含义、./start-docker.sh全部子命令及原生 docker compose 等价操作、容器级调试与常见故障的排查套路以及判断部署是否成功的验收标准。一、快速开始5 分钟跑通完整链路按照官方推荐的完整流程在满足前置条件的机器上按顺序执行即可# 1. 安装本地 Ollama curl -fsSL https://ollama.ai/install.sh | sh # 2. 启动 Ollama 服务端 ollama serve # 3. 在另一个终端拉取所需模型 ollama pull qwen3:0.6b ollama pull qwen3:8b # 4. 克隆仓库并启动 LocalGPT git clone https://github.com/your-org/rag-system.git cd rag-system ./start-docker.sh # 5. 访问应用 open http://localhost:3000从源码角度补充说明几点执行细节./start-docker.sh默认走local分支脚本会先调用check_local_ollama()通过curl -s http://localhost:11434/api/tags探测宿主机 Ollama 是否存活见 start-docker.sh若未检测到本地 Ollama脚本会交互式询问是否改用容器化 Ollama--profile with-ollama回答y则自动切换否则取消启动。为什么推荐本地 Ollama原文档给出的理由是四点——直接访问 GPU 性能更好、少一个容器部署更简单、模型管理更方便、连接更可靠。此外从架构上看把最吃显存的推理进程留在宿主机也便于用ollama list、ollama ps等原生工具管理模型生命周期。若在 Linux 上执行./start-docker.sh探测失败可先手动确认curl http://localhost:11434/api/tags是否返回 JSON再检查下文的环境变量小节中的网关地址配置。启动成功后各服务端口约定如下与原文档、start-docker.sh 的提示输出一致服务地址说明前端http://localhost:3000Next.js Web 界面后端http://localhost:8000会话管理、聊天历史、API 网关RAG APIhttp://localhost:8001文档索引、检索、AI 处理Ollamahttp://localhost:11434宿主机本地推理服务二、前置条件与资源规划原文档列出的硬性要求Docker Desktop已安装并运行macOS / WindowsLinux 则需 Docker Engine 服务见 DOCKER_TROUBLESHOOTING.md 中sudo systemctl status docker的排查方式Ollama 本机安装即使使用 Docker 部署也建议保留以获得最佳性能8GB 内存运行更大模型建议 16GB10GB 可用磁盘空间需容纳 Docker 镜像、模型权重、向量数据库与上传文档。结合仓库的镜像定义可将资源估算得更精确前端镜像基于node:18-alpine约占用数百 MB见 Dockerfile.frontend后端与 RAG API 镜像均基于python:3.11-slim并安装requirements-docker.txt中的依赖见 Dockerfile.backend、Dockerfile.rag-api其中包含 torch、transformers、lancedb 等重量级 Python 包构建阶段较耗时属正常现象模型权重由 Ollama 管理qwen3:0.6b约 650MBqwen3:8b约 4.7GB参考 Documentation/docker_usage.md 的说明不进入 Docker 镜像。三、架构总览三容器 本地 Ollama原文档给出如下架构图三个应用容器横向串联RAG API 向下调用宿主机 Ollama┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ Frontend │────│ Backend │────│ RAG API │ │ (Container) │ │ (Container) │ │ (Container) │ │ Port: 3000 │ │ Port: 8000 │ │ Port: 8001 │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ │ API calls ▼ ┌─────────────────┐ │ Ollama │ │ (Local/Host) │ │ Port: 11434 │ └─────────────────┘3.1 容器职责与启动细节原文档对三个容器的定位、镜像、端口与健康检查如下表内存占用为文档给出的经验值实际随负载浮动容器镜像基础端口职责健康检查内存参考rag-frontendNode.js 18 定制构建3000Next.js Web 界面HTTP GET/~500MBrag-backendPython 3.11 定制构建8000会话管理、聊天历史、API 网关HTTP GET/health~300MBrag-apiPython 3.11 定制构建8001文档索引、检索、AI 处理HTTP GET/models~2GB随模型使用波动从 docker-compose.yml 可以看到更完整的编排细节启动顺序通过depends_on的condition: service_healthy保证backend 等待 rag-api 健康、frontend 等待 backend 健康形成严格的依赖链避免出现前端已就绪但后端还在初始化的窗口期所有容器均配置健康检查healthcheck每 30s 探测一次、超时 10s、连续 3 次失败标记为 unhealthy与restart: unless-stopped自动重启策略共享网络rag-networkbridge 驱动backend 通过服务名rag-api:8001访问 RAG API对应环境变量RAG_API_URLhttp://rag-api:8001这是 compose 内置 DNS 的典型用法无需依赖固定 IP。3.2 RAG API 内部初始化逻辑RAG API 容器启动命令为python -m rag_system.api_server见 Dockerfile.rag-api。结合 rag_system/api_server.py 的源码其初始化流程是模块加载时即创建全局ChatDatabase()连接数据库路径由DATABASE_PATH环境变量决定容器内默认为/app/backend/chat_data.db依据RAG_CONFIG_MODE默认default通过get_agent()与get_indexing_pipeline()构建 RAG Agent 与索引流水线打印 Initializing RAG Agent with MAXIMUM ACCURACY...并一次性加载模型模型只在服务启动时加载一次后续请求复用全局单例避免每次请求重复加载权重导致响应变慢——这也是为什么文档提醒RAG API 首次启动可能较慢。四、数据持久化Volume Mounts 与共享存储原文档定义的四类持久化数据宿主机路径容器内路径用途./lancedb//app/lancedb向量数据库存储LanceDB./index_store//app/index_store文档索引与元数据./shared_uploads//app/shared_uploads上传的文档文件./backend/chat_data.db/app/backend/chat_data.dbSQLite 聊天历史数据库共享的语义通过 bind mountrag-api 与 backend 都能访问shared_uploadsrag-api 独占lancedb与index_storebackend 独占chat_data.db但 docker-compose.local-ollama.yml 中对数据库做了精确到单文件的挂载。宿主机直接修改这些目录即可完成备份或清理无需进入容器。重要区分docker.env中声明的DATABASE_PATH/app/backend/chat_data.db、LANCEDB_PATH/app/lancedb、UPLOADS_PATH/app/shared_uploads是容器内路径服务于应用代码而 compose 文件中的./lancedb:/app/lancedb这类映射是宿主机 ↔ 容器的桥接。两者配合才构成完整的数据通路。五、配置详解docker.env 与模型配置5.1 环境变量文件 docker.env仓库根目录的 docker.env 是官方默认配置原文档将其归纳为三组# Ollama Configuration OLLAMA_HOSThttp://host.docker.internal:11434 # Service Configuration NODE_ENVproduction RAG_API_URLhttp://rag-api:8001 NEXT_PUBLIC_API_URLhttp://localhost:8000 # Database Paths (inside containers) DATABASE_PATH/app/backend/chat_data.db LANCEDB_PATH/app/lancedb UPLOADS_PATH/app/shared_uploads结合源码与当前仓库实际文件这里需要澄清一个关键差异文档版本演进带来的地址变化docker-compose.yml 中 rag-api 的OLLAMA_HOST默认值为${OLLAMA_HOST:-http://host.docker.internal:11434}即默认使用host.docker.internalmacOS/Windows 上由 Docker Desktop 提供指向宿主机但当前仓库的 docker.env 实际写入的是OLLAMA_HOSThttp://172.18.0.1:11434文件注释明确说明Using Docker gateway IP instead of host.docker.internal for Linux compatibilityLinux 上host.docker.internal不可用时改用 Docker 默认 bridge 网段172.18.0.1指向宿主机backend 容器在 docker-compose.yml 中的默认值则是${OLLAMA_HOST:-http://172.18.0.1:11434}。实操建议如果你的 Docker 网络网段不是默认的172.18.0.1可在docker compose exec rag-api后执行route -n或ip route查看网关 IP并同步修改docker.envhost.docker.internal在 Linux 上也可通过--add-hosthost.docker.internal:host-gateway方式启用当前仓库未内置该配置。其余三个服务级变量含义NODE_ENVproduction以生产模式运行 Node/Python 服务RAG_API_URLhttp://rag-api:8001backend 通过 compose 内部 DNS 服务名访问 RAG APINEXT_PUBLIC_API_URLhttp://localhost:8000浏览器端发起请求时访问的 backend 地址必须是宿主机可达地址。5.2 模型配置原文档默认模型组合如下用途模型说明Embedding向量化Qwen/Qwen3-Embedding-0.6B1024 维向量Generation生成qwen3:0.6b快 /qwen3:8b高质量由 Ollama 管理Reranking重排序内置交叉编码器cross-encoder无需额外模型补充说明从 rag_system/api_server.py 的_apply_index_embedding_model实现可以看到每个索引创建时会把embedding_model写入索引元数据检索时会动态将 retrieval pipeline 的 embedding 模型切换为与该索引一致的模型从而保证索引时用什么模型向量化检索时就用什么模型召回这是多模型混用场景下保证召回质量的关键机制。切换生成模型只需一条命令无需改容器ollama pull qwen3:0.6b # 追求响应速度 ollama pull qwen3:8b # 追求回答质量六、管理命令一键脚本与原生 docker compose6.1 ./start-docker.sh 一键脚本原文档列出的命令及其等价逻辑均已在 start-docker.sh 中实现# 启动全部服务默认 local 模式先探测本地 Ollama ./start-docker.sh # 停止全部服务 ./start-docker.sh stop # 重启服务 ./start-docker.sh stop ./start-docker.sh # 查看状态 ./start-docker.sh status # 查看实时日志 ./start-docker.sh logs脚本还支持两个容易被忽略的模式参数$0 [option]默认local./start-docker.sh container改用容器化 Ollama执行docker compose --profile with-ollama up --build -d并设置OLLAMA_HOSThttp://ollama:11434。此时会额外拉起 docker-compose.yml 中定义的ollama服务镜像ollama/ollama:latest容器名rag-ollama数据卷ollama_data持久化模型权重./start-docker.sh status/logs/help分别对应docker compose ps、按需选择--profile with-ollama logs -f或docker compose logs -f、打印用法帮助。值得注意的是脚本的stop分支会同时执行docker compose down与docker compose --profile with-ollama down后者失败被忽略确保无论以哪种模式启动都能完整清理。6.2 原生 docker compose 命令不依赖脚本、完全手动控制的等价操作# 启动读取 docker.env docker compose --env-file docker.env up --build -d # 停止 docker compose down # 重建指定服务 docker compose build --no-cache rag-api docker compose up -d rag-api # 查看状态与日志 docker compose ps docker compose logs -f docker compose logs -f rag-api docker compose logs -f backend docker compose logs -f frontend6.3 四端点健康检查部署后建议立即执行原文档给出的全套健康检查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期望输出为四行全绿✅ ... OK。若./start-docker.sh status显示某容器unhealthy可直接用docker inspect rag-api --format{{.State.Health.Status}}查看健康状态详情见 DOCKER_TROUBLESHOOTING.md。七、容器内调试进 shell、验初始化、查资源7.1 进入容器# RAG API 容器大部分调试发生在这里 docker compose exec rag-api bash # 后端容器 docker compose exec backend bash # 前端容器alpine 镜像用 sh docker compose exec frontend sh7.2 关键调试命令原文档提供的四类验证命令逐条说明其验证目标# ① 验证 RAG 系统能否初始化验证 get_agent 链路与模型加载 docker compose exec rag-api python -c from rag_system.main import get_agent agent get_agent(default) print(✅ RAG System OK) # ② 从容器内验证到宿主机 Ollama 的连通性验证 OLLAMA_HOST 配置 docker compose exec rag-api curl http://host.docker.internal:11434/api/tags # ③ 检查容器内的 Ollama 相关环境变量确认 docker.env 是否生效 docker compose exec rag-api env | grep OLLAMA # ④ 查看关键 Python 依赖是否装齐torch/transformers/lancedb docker compose exec rag-api pip list | grep -E (torch|transformers|lancedb)其中第②条是排查RAG API 连不上 Ollama最直接的证据若在容器内curl宿主机 11434 失败而宿主机本机访问成功问题几乎必然出在OLLAMA_HOST地址选择host.docker.internalvs172.18.0.1或防火墙上。7.3 资源监控# 实时监控容器资源 docker stats # 磁盘占用总览 docker system df df -h ./lancedb ./shared_uploads # 按服务查看内存 docker stats --format table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}\t{{.MemPerc}}八、故障排查手册8.1 容器无法启动# 先看对应服务日志定位具体错误 docker compose logs [service-name] # 端口占用排查3000/8000/8001 同时检查 lsof -i :3000 -i :8000 -i :8001 # 彻底重建 ./start-docker.sh stop docker system prune -f ./start-docker.sh若日志中出现bind: address already in use说明端口被本机进程占用可用pkill -f npm run dev、pkill -f server.py、pkill -f api_server清理非 Docker 的本地开发进程或用sudo kill -9 $(lsof -t -i:3000)按端口强杀详见 DOCKER_TROUBLESHOOTING.md。8.2 连不上 Ollama# ① 宿主机侧确认 Ollama 存活 curl http://localhost:11434/api/tags # ② 重启 Ollama pkill ollama ollama serve # ③ 容器侧再测 docker compose exec rag-api curl http://host.docker.internal:11434/api/tags若第③步失败而第①步成功按当前仓库的 docker.env 实践可将OLLAMA_HOST改为http://172.18.0.1:11434Linux 网关地址后./start-docker.sh stop ./start-docker.sh重启生效。8.3 内存不足# 查看当前占用 docker stats --no-stream free -h # 宿主机视角 # 调大 Docker 内存配额 # Docker Desktop → Settings → Resources → Memory → 8GB # 换用更小的模型 ollama pull qwen3:0.6b # 替代 qwen3:8b8.4 前端构建失败# 无缓存重建前端 docker compose build --no-cache frontend docker compose up -d frontend # 查看前端日志 docker compose logs frontend8.5 数据库 / 存储权限问题# 检查文件权限 ls -la backend/chat_data.db ls -la lancedb/ # 修复权限 chmod 664 backend/chat_data.db chmod -R 755 lancedb/ shared_uploads/ # 容器内验证 SQLite 可读 docker compose exec backend sqlite3 /app/backend/chat_data.db .tables若数据库文件缺失可按 DOCKER_TROUBLESHOOTING.md 提供的方式初始化docker compose exec backend python -c from backend.database import ChatDatabase db ChatDatabase() db.init_database() print(Database initialized) 8.6 性能优化响应慢改用qwen3:0.6b提高 Docker 内存配额数据库与向量存储置于 SSD用docker stats持续观察瓶颈内存占用高在配置中调小批处理大小batch size换更小的 embedding 模型docker system prune清理无用资源。8.7 完全重置破坏性操作谨慎执行# 停止并清理所有容器、镜像、卷 ./start-docker.sh stop docker system prune -a --volumes # 清空本地数据⚠️ 将删除全部文档与聊天历史 rm -rf lancedb/* shared_uploads/* backend/chat_data.db # 重新构建启动 ./start-docker.sh如果只想重置部分数据可选择性删除仅重置聊天记录删backend/chat_data.db仅重置向量库删lancedb/*仅重置上传文档删shared_uploads/*见 DOCKER_TROUBLESHOOTING.md 的 Selective Reset 一节。九、成功标准与性能基线9.1 部署成功的验收清单原文档给出的判定标准全部满足即视为部署成功✅./start-docker.sh status显示所有容器 healthy✅ 上文四个端点的健康检查全部通过✅ 可访问 http://localhost:3000✅ 能上传文档并创建索引✅ 能与文档进行对话✅ 容器日志无报错。9.2 性能基线参考原文档给出的两组经验基线在当前仓库硬件未标定的情况下作为参考阈值而非承诺指标指标Good良好Optimal最优容器启动时间 2 分钟 1 分钟索引创建速度 2 分钟 / 100MB 文档 1 分钟 / 100MB 文档查询响应时间 30 秒 10 秒容器总内存占用 4GB 2GB十、进阶容器化 Ollama、独立镜像测试与替代部署10.1 容器化 Ollama可选若宿主机不便安装 Ollama可通过 profile 方式在容器中运行./start-docker.sh container # 等价于 docker compose --profile with-ollama up --build -d此时rag-ollama容器监听 11434模型权重存入命名卷ollama_dataOLLAMA_HOST需指向http://ollama:11434docker.env 中已预留注释掉的备选配置。注意该模式会牺牲 GPU 直通效率文档仍推荐本地 Ollama 作为首选。10.2 单容器独立测试先单独构建并运行 RAG API 容器验证镜像本身可用见 DOCKER_TROUBLESHOOTING.mddocker build -f Dockerfile.rag-api -t test-rag-api . docker run --rm -p 8001:8001 -e OLLAMA_HOSThttp://host.docker.internal:11434 test-rag-api sleep 30 curl http://localhost:8001/models10.3 替代部署路径纯本地开发不用 Dockerpython run_system.py见仓库根目录 run_system.py混合模式RAG API 入容器、后端与前端直接跑docker compose up -d rag-api后分别执行python backend/server.py与npm run dev非 Docker 部署的完整说明见根目录 README.md。十一、更多资料深度排障手册DOCKER_TROUBLESHOOTING.mdDocker daemon 重启、网络调试、日志分析、自动化健康测试脚本test-docker-health.sh等Docker 使用全流程Documentation/docker_usage.md开发工作流、日志管理、数据备份、Swarm 扩展、镜像安全扫描docker scout cves系统架构Documentation/architecture_overview.mdDocker Compose 编排文件docker-compose.yml、docker-compose.local-ollama.yml镜像定义Dockerfile.frontend、Dockerfile.backend、Dockerfile.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），仅供参考