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），僅供參考