Local Deep Research 完整安装指南Docker Compose、裸 Docker、pip 与 Unraid 全平台部署【免费下载链接】local-deep-research~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10 search engines - arXiv, PubMed, your private documents. Everything Local Encrypted.项目地址: https://gitcode.com/GitHub_Trending/lo/local-deep-research本文是 Local Deep ResearchLDR项目的安装总纲覆盖四种官方支持的部署方式Docker Compose推荐、裸 Docker 逐容器部署、Python pip 包安装与Unraid 服务器模板。读完本文你将能够根据自身硬件CPU-only 或 NVIDIA GPU、操作系统Linux / macOS / Windows / WSL2与使用场景开箱即用、二次开发、NAS 自托管选择最合适的安装路径并理解每条命令背后的环境变量、卷挂载与安全机制。所有命令均来自 docs/installation.md 及仓库根目录的 docker-compose.yml、docker-compose.gpu.override.yml、docker-compose.unraid.yml 等真实配置可直接复制使用。安装方式总览与前置条件Local Deep Research 是一个Everything Local Encrypted的深度研究助手其标准运行拓扑由三部分构成组件作用默认端口local-deep-research主 Web 应用研究编排、知识库、Web UI5000ollama本地 LLM 推理引擎11434searxng隐私优先的元搜索引擎8080前置条件使用下述 Option 1–3Docker Compose、裸 Docker、Unraid均需要安装 Docker 与 Docker Compose纯 pip 用户则只需在可选配 SearXNG 容器时用到 Docker。四种方式的选择建议方式适用场景复杂度Docker Compose绝大多数用户一条命令拉起全部组件★裸 Docker已有 Ollama/SearXNG或想最小化部署★★pip开发者、将 LDR 集成进现有 Python 项目★★★Unraid 模板Unraid 服务器 NAS 自托管★★Docker Compose推荐一条命令拉起完整研究栈Docker Compose 是官方推荐方式仓库根目录的 docker-compose.yml 已内置合理默认值将 LDR、Ollama、SearXNG 三个服务打包在同一ldr-network网络中服务之间通过服务名互通无需手动配置地址。CPU-only全平台curl -O https://raw.githubusercontent.com/LearningCircuit/local-deep-research/main/docker-compose.yml docker compose up -d约30 秒后打开 http://localhost:5000 即可使用。注意curl -O会覆盖当前目录下已有的docker-compose.yml文件请在空白目录执行或提前备份。带 NVIDIA GPU仅 LinuxGPU 加速需要两步先安装 NVIDIA Container Toolkit仅此步骤依赖发行版差异再用 override 文件叠加 GPU 配置。Ubuntu/Debian 安装 NVIDIA Container Toolkitcurl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg \ curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \ sed s#deb https://#deb [signed-by/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g | \ sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list sudo apt-get update sudo apt-get install nvidia-container-toolkit -y sudo systemctl restart docker # 验证安装 nvidia-smiRHEL/CentOS/Fedora、Arch 等其他发行版请参考 NVIDIA Container Toolkit 官方安装指南按对应发行版操作。启动 GPU 版栈curl -O https://raw.githubusercontent.com/LearningCircuit/local-deep-research/main/docker-compose.yml \ curl -O https://raw.githubusercontent.com/LearningCircuit/local-deep-research/main/docker-compose.gpu.override.yml \ docker compose -f docker-compose.yml -f docker-compose.gpu.override.yml up -d可选为方便日常操作建立别名alias docker-compose-gpudocker compose -f docker-compose.yml -f docker-compose.gpu.override.yml # 之后直接使用: docker-compose-gpu up -dGPU override 做了什么查看仓库根目录 docker-compose.gpu.override.yml 可以看到它只做了一件事——为ollama服务声明 GPU 资源预留services: ollama: deploy: resources: reservations: devices: - driver: nvidia count: 1 capabilities: [ gpu ]即在 Compose 合并时向 Ollama 容器注入 NVIDIA GPU 驱动count: 1表示预留 1 块 GPUcapabilities: [gpu]声明需要 GPU 计算能力。基础版 docker-compose.yml 中 Ollama 服务本身注释写明GPU acceleration disabled by default未来计划新增docker-compose.amd.override.yml支持 AMD GPU。WindowsPowerShellWindows 下同样可用 Docker Compose注意 PowerShell 中curl是Invoke-WebRequest的别名需使用curl.exe调用原生工具curl.exe -O https://raw.githubusercontent.com/LearningCircuit/local-deep-research/main/docker-compose.yml if ($?) { docker compose up -d }更换默认模型默认栈使用gpt-oss:20b模型。Docker Compose 方式下可在启动时通过环境变量指定模型curl -O https://raw.githubusercontent.com/LearningCircuit/local-deep-research/main/docker-compose.yml MODELgpt-oss:20b docker compose up -d如需固定 LDR 实际调用的模型而不仅是 Ollama 侧拉取的模型可在 compose 中锁定LDR_LLM_MODEL环境变量见下文环境变量与 Web UI 的关系例如LDR_LLM_MODELgemma3:4b docker compose up -d模型不存在时 Ollama 会自动拉取。DIY 修改 compose 的常见需求docker-compose.yml 头部注释给出了清晰的定制指引常见改动点外部端口通过 Docker 端口映射而非环境变量修改。例如映射到 8080 端口ports: - 8080:5000保持容器内部端口 5000 不变避免与LDR_WEB_PORT产生配置错配。Ollama GPU 驱动 / 上下文长度 / keep alive 时长GPU 驱动见 override 文件OLLAMA_KEEP_ALIVE在基础 compose 中已设为30m即模型在内存中驻留 30 分钟避免频繁卸载。模型选择见上文。更完整的参数说明见 docs/docker-compose-guide.md完整环境变量参考见 docs/CONFIGURATION.md。深入理解默认 compose网络、数据卷与安全加固打开仓库根目录的 docker-compose.yml可以看到若干值得关注的默认设计1. 服务间网络与地址注入。三个服务同处ldr-network内部网络。compose 强制注入了两个服务发现端点- LDR_LLM_OLLAMA_URLhttp://ollama:11434 - LDR_SEARCH_ENGINE_WEB_SEARXNG_DEFAULT_PARAMS_INSTANCE_URLhttp://searxng:8080同时extra_hosts声明了host.docker.internal:host-gateway在 Linux 上让容器可达宿主机服务例如宿主上运行的 LM StudiomacOS/Windows 已内置此解析。2. 三类强制环境变量。compose 中的环境变量分为三层Docker 专用强制LDR_WEB_HOST0.0.0.0绑定全部网卡以支持容器网络、LDR_WEB_PORT5000与容器内端口一致、LDR_DATA_DIR/data与卷挂载点一致三者被锁定以保证容器正常工作。服务端点强制上述 Ollama/SearXNG 地址。注意将 SearXNG 地址通过环境变量锁定同时意味着将其标记为operator-provisioned运维方提供这恰好满足了 v1.10.3 起的私网引擎 URL 保护要求详见 docs/SearXNG-Setup.md。可选锁定默认注释LDR_LLM_PROVIDER、LDR_LLM_MODEL、OpenAI/Anthropic API Key、OpenRouterLDR_LLM_PROVIDERopenai_endpointLDR_LLM_OPENAI_ENDPOINT_URLhttps://openrouter.ai/api/v1、LM Studiohttp://host.docker.internal:1234/v1等。取消注释即锁定该配置使对应设置变为只读。3. 数据卷。基础 compose 声明了ldr_data应用数据、ldr_scripts启动脚本、ollama_data下载的模型、searxng_data搜索引擎配置四个命名卷。docs/docker-compose-guide.md 中另提及ldr_rag_cacheRAG 索引缓存。本地文档集合应通过 Web UI 的 Collections 系统上传管理不要通过 Docker 卷挂载方式添加。4. 最小权限安全加固。容器的 entrypointscripts/ldr_entrypoint.sh先以 root 短暂运行修正卷属主再通过setpriv永久降级到ldruserUID 1000运行应用。compose 相应配置了cap_drop: ALL后仅回补CHOWN/FOWNER/DAC_OVERRIDE/SETUID/SETGID五个能力、no-new-privileges: true、ulimits.memlock设为无限供 SQLCipher 的mlock()将加密密钥锁定在内存配合可选的cipher_memory_security。不要移除这些cap_add项否则 entrypoint 的 chown/chmod 会以 Operation not permitted 失败导致容器无法启动——这在 Proxmox LXC 等受限环境中尤其明显。5. 健康检查与镜像固定。ollama服务通过ollama list探活模型无关见 compose 中关于 #3885 的注释searxng通过wget -qO- http://localhost:8080/healthz探活Ollama 镜像与 SearXNG 镜像均固定了 digest 摘要确保可复现部署。Ollama 服务刻意不暴露11434:11434端口——Ollama 无鉴权仅限ldr-network内部访问更安全。6. 资源限制提醒。基础 compose 故意不设置deploy.resources.limits资源需求随部署而异部署者应通过自己的docker-compose.override.yml按环境设定nofile文件描述符上限也不应人为调低否则高负载下可能触发unable to open database file错误。CookieCutter 定制化生成对高级用户仓库提供了 cookiecutter-docker 模板用于交互式生成专属 composepip install --user cookiecutter git clone https://github.com/LearningCircuit/local-deep-research.git cd local-deep-research cookiecutter cookiecutter-docker/生成过程中可指定config_name配置名称、host_port暴露端口默认 5000、host_ip绑定 IP默认 0.0.0.0、host_network是否使用宿主机网络、enable_gpuNVIDIA GPU 支持、enable_searxng是否包含 SearXNG 服务。生成后使用docker compose -f docker-compose.default.yml up -d启动。Compose 常用运维命令# 启动前台跟随日志 docker compose up -d # 查看日志 docker compose logs -f # 停止 docker compose down # 升级到最新镜像 docker compose pull docker compose up -d # 彻底重置删除所有数据卷回到全新状态 docker compose down -v裸 Docker逐容器最小化部署不引入 Compose直接分别运行三个容器。适合已有部分组件或希望精细控制每个容器的用户。Linux原生 Docker Engine# Step 1: 拉取并运行 SearXNG获得最佳搜索结果 docker run -d -p 8080:8080 --name searxng searxng/searxng # Step 2: 拉取并运行 Ollama docker run -d -p 11434:11434 --name ollama ollama/ollama docker exec ollama ollama pull gpt-oss:20b # Step 3: 拉取并运行 Local Deep Research # (URL 行同时完成两件事: 固定 SearXNG 地址并将其标记为 operator-approved — # 自 v1.10.3 起 private/localhost 引擎 URL 默认被阻止。该 URL 在 Web UI 中变为只读; # docs/SearXNG-Setup.md 列出了其他替代方案, 如 origin 白名单。) docker run -d -p 5000:5000 --network host \ --name local-deep-research \ --volume deep-research:/data \ -e LDR_DATA_DIR/data \ -e LDR_SEARCH_ENGINE_WEB_SEARXNG_DEFAULT_PARAMS_INSTANCE_URLhttp://localhost:8080 \ localdeepresearch/local-deep-research关键点解析--network host让 LDR 容器共享宿主机网络栈因此容器内的localhost:8080能直接到达宿主机上的 SearXNG、localhost:11434能到达 Ollama——这是 Linux 原生 Docker 的最小连通方案。环境变量LDR_SEARCH_ENGINE_WEB_SEARXNG_DEFAULT_PARAMS_INSTANCE_URL一箭双雕既设置了 SearXNG 地址又因环境变量锁定的 URL 视为运维方提供而自动获得信任。自v1.10.3起私网/回环/链路本地地址含默认的http://localhost:8080默认被阻止SSRF 防护Web UI 中保存此类地址会被拒绝、运行时引擎也会自动禁用。数据目录通过--volume deep-research:/data挂载并配合LDR_DATA_DIR/data使用。Mac / Windows / WSL2Docker Desktop--network host在 Docker Desktop 上不生效——它会静默丢弃端口发布且容器内的localhost无法再到达 Ollama/SearXNG 容器。此时应去掉--network host、保留-p 5000:5000并通过host.docker.internal让 LDR 指向宿主机的 Ollama 与 SearXNG# Step 1 和 2SearXNG Ollama与上面相同。 # Step 3: 拉取并运行 Local Deep Research docker run -d -p 5000:5000 \ --name local-deep-research \ --add-hosthost.docker.internal:host-gateway \ --volume deep-research:/data \ -e LDR_DATA_DIR/data \ -e LDR_LLM_OLLAMA_URLhttp://host.docker.internal:11434 \ -e LDR_SEARCH_ENGINE_WEB_SEARXNG_DEFAULT_PARAMS_INSTANCE_URLhttp://host.docker.internal:8080 \ localdeepresearch/local-deep-research--add-host在 Mac/Windows 上是 no-op——host.docker.internal已被自动注入但加上它可让同一命令在 Linux 版 Docker Desktop 上同样可用。不想用环境变量锁死地址两个 URL 都可在首次登录后通过 Web UI 修改OllamaSettings → LLM → Ollama URL直接改即可。SearXNGSettings → Search → SearXNG → Instance URL输入私网地址会自 v1.10.3 起被拒绝除非运维方批准——需同时传-e LDR_SEARCH_PRIVATE_ENGINE_URL_ALLOWLISThttp://host.docker.internal:8080要求v1.10.5 及以上v1.10.3/v1.10.4 请改用-e LDR_SEARCH_ALLOW_PRIVATE_ENGINE_URLStrue详见 docs/SearXNG-Setup.md。对大多数这类平台的用户Docker Compose 更简单——它通过服务名自动接通各组件地址无需手工处理host.docker.internal。启动后同样等待约 30 秒访问 http://localhost:5000。关于私网 SearXNG URL 批准的补充由于该机制是 v1.10.3 最常见的升级后突然搜不到结果的根因这里单独说明三种批准方式三选一然后重启 LDR# 方式 A推荐v1.10.5: 只允许特定 URL origin精确匹配 scheme://host:port无通配符 LDR_SEARCH_PRIVATE_ENGINE_URL_ALLOWLISThttp://localhost:8080 # 方式 B: 用环境变量固定 URL 本身——env-locked URL 视为运维方提供并被信任 LDR_SEARCH_ENGINE_WEB_SEARXNG_DEFAULT_PARAMS_INSTANCE_URLhttp://localhost:8080 # 方式 C最宽泛: 允许所有私网/回环/LAN 引擎 URL LDR_SEARCH_ALLOW_PRIVATE_ENGINE_URLStrue无论哪种方式云元数据地址如169.254.169.254对应 AWS IMDS/ECS、Azure、OCI、DigitalOcean、阿里云、腾讯云等始终被阻止只接受http/https协议。IPv6-only 的 NAT6464:ff9b::/96、64:ff9b:1::/48部署如需访问 SearXNG需显式设置LDR_SECURITY_ALLOW_NAT64true且严格限定在这两个前缀内。详见 docs/SearXNG-Setup.md 与 SECURITY.md。Python Packagepip适合开发者或将 LDR 集成进现有 Python 项目的用户。pip 方式默认只安装应用本体SearXNG、Ollama、SQLCipher 需按下面步骤补齐。快速安装# Step 1: 安装包 pip install local-deep-research # Step 2: 为获得最佳结果部署 SearXNGDocker 可选 docker pull searxng/searxng docker run -d -p 8080:8080 --name searxng searxng/searxng # Step 3: 从 https://ollama.ai 安装 Ollama # Step 4: 下载模型 ollama pull gemma3:12b # Step 5: 固定 SearXNG URL同时将其标记为 operator-approved—— # 自 v1.10.3 起私网/localhost 引擎 URL 默认被阻止并启动 Web 界面。 # 该 URL 在 Web UI 中变为只读; docs/SearXNG-Setup.md 列出了替代方案。 export LDR_SEARCH_ENGINE_WEB_SEARXNG_DEFAULT_PARAMS_INSTANCE_URLhttp://localhost:8080 ldr-web数秒后打开 http://localhost:5000。SearXNG 无结果若日志出现SearXNG engine disabled: instance URL … is a private / loopback / link-local address说明运行ldr-web的环境缺少上述 allowlist 环境变量——注意LDR_SEARCH_PRIVATE_ENGINE_URL_ALLOWLIST需要 v1.10.5旧版本使用LDR_SEARCH_ALLOW_PRIVATE_ENGINE_URLStrue全部批准选项见 docs/SearXNG-Setup.md。SQLCipher 数据库加密LDR 使用 SQLCipher 提供 AES-256 加密数据库。Windows、macOS、Linux 均有预编译的sqlcipher3wheel绝大多数用户无需自行编译完整安装说明docs/SQLCIPHER_INSTALL.md跳过加密若不需要数据库加密设置export LDR_BOOTSTRAP_ALLOW_UNENCRYPTEDtrue改用标准 SQLite——注意此时 API 密钥和数据将以明文存储。Docker 用户官方镜像开箱即含 SQLCipher无需额外配置。可选依赖与平台注意MCP Server如需集成 Claude Desktop / Claude Code安装pip install local-deep-research[mcp]。Windows PDF 导出需要 Pango/Cairo 系统库WeasyPrint 依赖。CJK 字符在 PDF 中消失WeasyPrint 通过宿主机字体解析字形请安装相应 CJK 字体Debian/Ubuntusudo apt install fonts-noto-cjk fc-cache -fvFedora/RHELsudo dnf install google-noto-sans-cjk-fontsAlpineapk add font-noto-cjk。Docker 官方镜像已内置fonts-noto-cjk无需处理。Emoji 显示为方框tofu安装 emoji 字体Debian/Ubuntufonts-noto-color-emojiAlpinefont-noto-emoji。Docker 镜像已内置。更完整的 pip 安装说明见 docs/install-pip.md从源码运行与贡献见 docs/developing.md。Unraid 服务器部署Local Deep Research 为 Unraid 提供了预配置模板内置合理默认值、自动的 SearXNG/Ollama 集成与 NVIDIA GPU 透传支持。完整步骤见 docs/deployment/unraid.md仓库根目录的 docker-compose.unraid.yml 与 unraid-templates/local-deep-research.xml 是模板与 override 的真实来源。方式一Unraid 模板推荐Docker页签 →Docker Repositories→ 添加模板仓库https://github.com/LearningCircuit/local-deep-research→ 保存。Docker页签 →Add Container→ 模板下拉选择LocalDeepResearch→ 按需检查配置 → Apply。可选为本地 LLM 安装 Ollama、为本地搜索安装 SearXNGCommunity Applications 中搜索配置路径建议统一放在/mnt/user/appdata/local-deep-research/下如使用自定义网络先docker network create ldr-network再在 Extra Parameters 添加--networkldr-network。方式二Docker Compose Manager 插件安装Docker Compose Manager插件。Docker页签 →Compose→Add New Stack名称local-deep-researchRepository URL 填https://github.com/LearningCircuit/local-deep-research.gitCompose File 填docker-compose.yml:docker-compose.unraid.ymlBranch 为main保存并 Compose Up。GPU 支持将 Compose File 改为docker-compose.yml:docker-compose.unraid.yml:docker-compose.gpu.override.yml。本地文档集合编辑栈内docker-compose.unraid.yml取消对应路径注释。方式三手动 Docker 模板wget -O /boot/config/plugins/dockerMan/templates-user/local-deep-research.xml \ https://raw.githubusercontent.com/LearningCircuit/local-deep-research/main/unraid-templates/local-deep-research.xml随后Docker页签 →Add Container→ 选择LocalDeepResearch模板应用。Unraid 关键配置速览unraid-templates/local-deep-research.xml 及 docker-compose.unraid.yml 体现的要点卷映射推荐统一放在/mnt/user/appdata/local-deep-research//data用户数据库、研究输出、缓存、日志、/scripts启动脚本、Ollama 的/root/.ollama模型 5–15GB/个、SearXNG 的/etc/searxng配置。若 appdata 共享设置为 cache-only可改用/mnt/cache/appdata/...绕过 FUSE 开销获得更好性能。端口默认 5000若被占用只改模板中的宿主机端口左侧如5050:5000不要改动容器端口或LDR_WEB_PORT。必选变量勿改LDR_WEB_HOST0.0.0.0、LDR_WEB_PORT5000、LDR_DATA_DIR/data。服务连接变量LDR_LLM_OLLAMA_URL同在ldr-network时用http://ollama:11434外部 Ollama 用 IP、LDR_SEARCH_ENGINE_WEB_SEARXNG_DEFAULT_PARAMS_INSTANCE_URL默认http://searxng:8080。空值语义Unraid 模板即使留空也会创建环境变量但空值会被视为未设置不会覆盖或锁定任何 UI 配置——留空是安全的。注意将 API Key 设为空字符串不会清除已存于数据库的密钥要显式屏蔽请设为任意非空无效值如DISABLED。GPU安装 Nvidia-Driver 插件 → 在/etc/docker/daemon.json配置nvidiaruntime → 重启 Docker → 为 Ollama 容器添加--runtimenvidia及NVIDIA_DRIVER_CAPABILITIESall、NVIDIA_VISIBLE_DEVICESall。验证docker exec -it ollama_service nvidia-smi。备份优先备份/mnt/user/appdata/local-deep-research/data模型与 SearXNG 配置可选备份。更新模板安装用Force UpdateCompose 安装必须用 Compose 区的Update StackUnraid 原生 Docker UI 不识别 Compose 容器忽略其 Update Ready 提示。可用 Watchtower 实现自动更新。安装后的验证与故障排查环境自检清单# GPU 是否可用GPU 部署 nvidia-smi # 容器健康状态 docker compose ps # LDR / Ollama / SearXNG 日志 docker compose logs -f local-deep-research docker compose logs ollama docker compose logs searxng # SearXNG 健康检查 curl http://localhost:8080/healthz高频问题定位现象排查方向容器无法启动docker compose logs local-deep-research确认端口 5000 未被占用Ollama 模型未加载docker compose logs ollama核对LDR_LLM_MODEL确认磁盘空间足够下载模型GPU 未识别nvidia-smi检查驱动docker run --rm --gpus all nvidia/cuda:11.0-base nvidia-smi检查容器内 GPU升级 v1.10.3 后 SearXNG 无结果私网 URL 未批准——按上文三种批准方式之一配置并重启设置重启后丢失确认卷映射与LDR_DATA_DIR/data一致目录存在且可写更完整的排查手册见 docs/troubleshooting.md 与 docs/faq.md。配置入口启动成功后绝大多数运行期配置LLM 提供方与模型、SearXNG 地址与引擎列表、注册开关等都可通过 Web UI 的 http://localhost:5000/settings 完成。请记住一条核心原则环境变量会强制覆盖并锁定对应 UI 设置因此仅对部署相关值如LDR_DATA_DIR、API Key或必须锁定的策略使用环境变量日常调整优先使用 Web UI。完整的变量清单与默认值见 docs/CONFIGURATION.md环境变量专题见 docs/env_configuration.mdSearXNG 集成专项见 docs/SearXNG-Setup.md。相关文档Docker Compose 指南 —— compose 参数、卷、CookieCutter、外部 LLM 提供方pip 安装指南 —— pip 完整流程与平台注意事项Unraid 部署指南 —— 模板、GPU、备份与更新SearXNG 集成指南 —— 引擎批准、SSRF 防护与故障排查完整配置参考 —— 全部环境变量与默认值SQLCipher 安装指南 —— 数据库加密配置环境变量专题 —— 环境变量语义详解开发指南 —— 从源码运行与贡献【免费下载链接】local-deep-research~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10 search engines - arXiv, PubMed, your private documents. Everything Local Encrypted.项目地址: https://gitcode.com/GitHub_Trending/lo/local-deep-research创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考