Local Deep Research 完整安装指南：Docker Compose、裸 Docker、pip 与 Unraid 全平台部署

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 Research（LDR）项目的安装总纲，覆盖四种官方支持的部署方式：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"的深度研究助手，其标准运行拓扑由三部分构成：

前置条件：使用下述 Option 1–3（Docker Compose、裸 Docker、Unraid）均需要安装 Docker 与 Docker Compose；纯 pip 用户则只需在可选配 SearXNG 容器时用到 Docker。

四种方式的选择建议：

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（仅 Linux）

GPU 加速需要两步：先安装 NVIDIA Container Toolkit（仅此步骤依赖发行版差异），再用 override 文件叠加 GPU 配置。

Ubuntu/Debian 安装 NVIDIA Container Toolkit：

curl -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-smi

RHEL/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-gpu='docker compose -f docker-compose.yml -f docker-compose.gpu.override.yml' # 之后直接使用: docker-compose-gpu up -d

GPU 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 块 GPU，capabilities: [gpu]声明需要 GPU 计算能力）。基础版 docker-compose.yml 中 Ollama 服务本身注释写明"GPU acceleration disabled by default"，未来计划新增docker-compose.amd.override.yml支持 AMD GPU。

Windows（PowerShell）

Windows 下同样可用 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 && MODEL=gpt-oss:20b docker compose up -d

如需固定 LDR 实际调用的模型（而不仅是 Ollama 侧拉取的模型），可在 compose 中锁定LDR_LLM_MODEL环境变量（见下文"环境变量与 Web UI 的关系"），例如LDR_LLM_MODEL=gemma3: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_URL=http://ollama:11434 - LDR_SEARCH_ENGINE_WEB_SEARXNG_DEFAULT_PARAMS_INSTANCE_URL=http://searxng:8080

同时extra_hosts声明了host.docker.internal:host-gateway（在 Linux 上让容器可达宿主机服务，例如宿主上运行的 LM Studio；macOS/Windows 已内置此解析）。

2. 三类强制环境变量。compose 中的环境变量分为三层：

• Docker 专用（强制）：LDR_WEB_HOST=0.0.0.0（绑定全部网卡以支持容器网络）、LDR_WEB_PORT=5000（与容器内端口一致）、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、OpenRouter（LDR_LLM_PROVIDER=openai_endpoint+LDR_LLM_OPENAI_ENDPOINT_URL=https://openrouter.ai/api/v1）、LM Studio（http://host.docker.internal:1234/v1）等。取消注释即锁定该配置，使对应设置变为只读。

3. 数据卷。基础 compose 声明了ldr_data（应用数据）、ldr_scripts（启动脚本）、ollama_data（下载的模型）、searxng_data（搜索引擎配置）四个命名卷。docs/docker-compose-guide.md 中另提及ldr_rag_cache（RAG 索引缓存）。本地文档集合应通过 Web UI 的 Collections 系统上传管理，不要通过 Docker 卷挂载方式添加。

4. 最小权限安全加固。容器的 entrypoint（scripts/ldr_entrypoint.sh）先以 root 短暂运行修正卷属主，再通过setpriv永久降级到ldruser（UID 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 模板用于交互式生成专属 compose：

pip 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_gpu（NVIDIA 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_URL=http://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 / WSL2（Docker Desktop）

--network host在 Docker Desktop 上不生效——它会静默丢弃端口发布，且容器内的localhost无法再到达 Ollama/SearXNG 容器。此时应去掉--network host、保留-p 5000:5000，并通过host.docker.internal让 LDR 指向宿主机的 Ollama 与 SearXNG：

# Step 1 和 2（SearXNG + Ollama）与上面相同。 # Step 3: 拉取并运行 Local Deep Research docker run -d -p 5000:5000 \ --name local-deep-research \ --add-host=host.docker.internal:host-gateway \ --volume 'deep-research:/data' \ -e LDR_DATA_DIR=/data \ -e LDR_LLM_OLLAMA_URL=http://host.docker.internal:11434 \ -e LDR_SEARCH_ENGINE_WEB_SEARXNG_DEFAULT_PARAMS_INSTANCE_URL=http://host.docker.internal:8080 \ localdeepresearch/local-deep-research

（--add-host在 Mac/Windows 上是 no-op——host.docker.internal已被自动注入，但加上它可让同一命令在 Linux 版 Docker Desktop 上同样可用。）

不想用环境变量锁死地址？两个 URL 都可在首次登录后通过 Web UI 修改：

• Ollama：Settings → LLM → Ollama URL，直接改即可。
• SearXNG：Settings → Search → SearXNG → Instance URL输入私网地址会自 v1.10.3 起被拒绝，除非运维方批准——需同时传-e LDR_SEARCH_PRIVATE_ENGINE_URL_ALLOWLIST=http://host.docker.internal:8080（要求v1.10.5 及以上；v1.10.3/v1.10.4 请改用-e LDR_SEARCH_ALLOW_PRIVATE_ENGINE_URLS=true；详见 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_ALLOWLIST=http://localhost:8080 # 方式 B: 用环境变量固定 URL 本身——env-locked URL 视为运维方提供并被信任 LDR_SEARCH_ENGINE_WEB_SEARXNG_DEFAULT_PARAMS_INSTANCE_URL=http://localhost:8080 # 方式 C（最宽泛）: 允许所有私网/回环/LAN 引擎 URL LDR_SEARCH_ALLOW_PRIVATE_ENGINE_URLS=true

无论哪种方式，云元数据地址（如169.254.169.254，对应 AWS IMDS/ECS、Azure、OCI、DigitalOcean、阿里云、腾讯云等）始终被阻止；只接受http/https协议。IPv6-only 的 NAT64（64:ff9b::/96、64:ff9b:1::/48）部署如需访问 SearXNG，需显式设置LDR_SECURITY_ALLOW_NAT64=true，且严格限定在这两个前缀内。详见 docs/SearXNG-Setup.md 与 SECURITY.md。

Python Package（pip）

适合开发者或将 LDR 集成进现有 Python 项目的用户。pip 方式默认只安装应用本体，SearXNG、Ollama、SQLCipher 需按下面步骤补齐。

快速安装：

# Step 1: 安装包 pip install local-deep-research # Step 2: 为获得最佳结果部署 SearXNG（Docker 可选） 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_URL=http://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_URLS=true，全部批准选项见 docs/SearXNG-Setup.md。

SQLCipher 数据库加密

LDR 使用 SQLCipher 提供 AES-256 加密数据库。Windows、macOS、Linux 均有预编译的sqlcipher3wheel，绝大多数用户无需自行编译：

• 完整安装说明：docs/SQLCIPHER_INSTALL.md
• 跳过加密：若不需要数据库加密，设置export LDR_BOOTSTRAP_ALLOW_UNENCRYPTED=true改用标准 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/Ubuntu：sudo apt install fonts-noto-cjk && fc-cache -fv；Fedora/RHEL：sudo dnf install google-noto-sans-cjk-fonts；Alpine：apk add font-noto-cjk）。Docker 官方镜像已内置fonts-noto-cjk，无需处理。
• Emoji 显示为方框（tofu）：安装 emoji 字体（Debian/Ubuntu：fonts-noto-color-emoji；Alpine：font-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 模板（推荐）

1. Docker页签 →Docker Repositories→ 添加模板仓库https://github.com/LearningCircuit/local-deep-research→ 保存。
2. Docker页签 →Add Container→ 模板下拉选择LocalDeepResearch→ 按需检查配置 → Apply。
3. 可选：为本地 LLM 安装 Ollama、为本地搜索安装 SearXNG（Community Applications 中搜索，配置路径建议统一放在/mnt/user/appdata/local-deep-research/下；如使用自定义网络，先docker network create ldr-network再在 Extra Parameters 添加--network=ldr-network）。

方式二：Docker Compose Manager 插件

1. 安装Docker Compose Manager插件。
2. Docker页签 →Compose→Add New Stack，名称local-deep-research，Repository URL 填https://github.com/LearningCircuit/local-deep-research.git，Compose File 填docker-compose.yml:docker-compose.unraid.yml，Branch 为main，保存并 Compose Up。
3. GPU 支持：将 Compose File 改为docker-compose.yml:docker-compose.unraid.yml:docker-compose.gpu.override.yml。
4. 本地文档集合：编辑栈内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_HOST=0.0.0.0、LDR_WEB_PORT=5000、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 容器添加--runtime=nvidia及NVIDIA_DRIVER_CAPABILITIES=all、NVIDIA_VISIBLE_DEVICES=all。验证：docker exec -it ollama_service nvidia-smi。
• 备份：优先备份/mnt/user/appdata/local-deep-research/data；模型与 SearXNG 配置可选备份。
• 更新：模板安装用Force Update；Compose 安装必须用 Compose 区的Update Stack（Unraid 原生 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

高频问题定位

更完整的排查手册见 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.md，SearXNG 集成专项见 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