企业官网建设流程全解析

Local Deep Research 开发者指南：从环境搭建到测试、构建与排障的完整实战手册

【免费下载链接】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

本指南以项目官方开发者文档 docs/developing.md 为核心骨架，系统讲解 Local Deep Research 的本地开发全流程：架构文档导航、前后端环境初始化、开发/生产模式运行、预发布镜像测试、包与前端资产构建、测试体系、加密数据库备份恢复，以及高频故障的排查思路。读者读完将掌握一套可直接复制的开发工作流，并能结合源码定位配置、线程与安全相关的关键机制。

一、架构文档导航：先读懂再动手

在开始写代码前，建议先通读项目沉淀的架构类文档，它们分别覆盖了系统设计、数据模型、扩展点和工程化约束四个维度：

其中 架构总览 值得重点精读：它用 Mermaid 图清晰刻画了ldr-web（FastAPI 应用）、REST API/api/v1、核心研究引擎（SearchSystem→StrategyFactory→ReportGenerator）、搜索层（32 个搜索策略、30+ 搜索引擎、自适应限流）、数据层（每用户独立的 SQLCipher 加密库）以及 LLM 层（Provider/Embedding/Reranker）之间的调用关系，并给出了研究状态机（QUEUED → IN_PROGRESS → COMPLETED / FAILED / SUSPENDED）与线程模型。

二、开发环境准备：前置依赖一览

根据 docs/developing.md 的 Prerequisites 小节，本地开发需要以下工具链：

注意：pyproject.toml的构建后端是pdm-backend，依赖项里同时声明了sqlcipher3-binary（Linux x86_64）与sqlcipher3（ARM64/非 Linux）两套绑定，PDM 会按平台自动选择。

SQLCipher 按平台安装

SQLCipher 是"每个用户数据（含 API Key、研究成果）静态加密"的关键依赖，详细步骤见 docs/SQLCIPHER_INSTALL.md：

• Ubuntu/Debian：sudo apt update && sudo apt install sqlcipher libsqlcipher-dev，随后pdm install；
• macOS：brew install sqlcipher，必要时导出LDFLAGS="-L$(brew --prefix sqlcipher)/lib"与CPPFLAGS="-I$(brew --prefix sqlcipher)/include"再pdm install；
• Windows：sqlcipher30.6.2+ 提供预编译自包含 wheel（x86/x64/ARM64，Python 3.9–3.14），pip install sqlcipher3即可，无需编译。

三、初始设置：一键拉起后端 + 前端 + Git Hooks

按以下顺序完成首次开发环境初始化：

# 1. 克隆并进入仓库 git clone git@github.com:LearningCircuit/local-deep-research.git # 或 HTTPS：https://github.com/LearningCircuit/local-deep-research.git cd local-deep-research # 2. 后端：创建虚拟环境并安装依赖 python -m venv .venv source .venv/bin/activate pip install pdm pdm install --no-self # 3. 前端：安装 npm 依赖 npm install # 4. 安装 Git Hooks（pre-commit 框架） pre-commit install pre-commit install-hooks

其中第 4 步很关键：仓库通过pre-commit框架管理钩子，除了ruff、eslint、gitleaks等标准检查外，还挂载了位于 .pre-commit-hooks/ 的大量自定义本地钩子（如check-env-vars强制环境变量走SettingsManager、check-deprecated-db-connection禁止共享ldr.db、check-pathlib-usage强制使用pathlib.Path等），提交前会自动拦截常见问题。

四、运行应用：开发模式与生产模式

4.1 开发模式（热更新）

# 终端 1：启动后端 source .venv/bin/activate ldr-web # 方式 A：已安装的命令入口 # 或 python -m local_deep_research.web.app # 方式 B：直接用 Python 模块 # 终端 2：启动前端 Vite 开发服务器 npm run dev # 访问 http://localhost:5173

从 入口文件 的源码可以看到ldr-web实际做了三件事：安装全局线程异常钩子（避免后台队列/调度线程静默崩溃）、执行遗留 RAG docstore 的一次性清理迁移、再以workers=1启动 uvicorn 加载 web/fastapi_app.py 中的 ASGI 应用——单 worker 是 Socket.IO 在无 Redis 消息队列下的硬性要求，源码注释明确标注了这一约束。

4.2 开发环境变量

完整配置清单见 docs/CONFIGURATION.md。日常开发调试最常用的三个变量：

⚠️ 警告：切勿在生产环境设置LDR_BOOTSTRAP_ALLOW_UNENCRYPTED=true，否则用户数据将以明文存储。

4.3 Docker（类生产环境）

docker build -t localdeepresearch/local-deep-research:dev . docker run -p 5000:5000 -e LDR_DATA_DIR=/data -v ldr_data:/data localdeepresearch/local-deep-research:dev

4.4 测试预发布镜像（RC 版）

每次发版时，.github/workflows/prerelease-docker.yml会向 Docker Hub 发布两种标签：

• prerelease-vX.Y.Z-<sha>：不可变、精确锁定单个构建，适合复现 Bug 时使用的确定测试目标；
• prerelease：浮动的别名，始终指向最新 RC，适合"快速尝鲜下一版"。

推荐的隔离测试姿势：在docker-compose.yml中追加一个独立 service，使用不同端口和独立卷，避免 RC 的迁移脚本破坏生产库：

local-deep-research-pre: image: localdeepresearch/local-deep-research:prerelease container_name: local-deep-research-pre networks: - ldr-network extra_hosts: - "host.docker.internal:host-gateway" ports: - "5001:5000" # 生产仍占用 5000 environment: - LDR_WEB_HOST=0.0.0.0 - LDR_WEB_PORT=5000 - LDR_DATA_DIR=/data - LDR_LLM_OLLAMA_URL=http://ollama:11434 - LDR_SEARCH_ENGINE_WEB_SEARXNG_DEFAULT_PARAMS_INSTANCE_URL=http://searxng:8080 volumes: - ldr_data_pre:/data # ← 与生产的 ldr_data 隔离 - ldr_scripts_pre:/scripts restart: unless-stopped volumes: ldr_data_pre: ldr_scripts_pre:

记得从主local-deep-researchservice 复制ulimits、security_opt、cap_drop、cap_add等加固块——它们不是可选项，而是正确启动的前置条件。

启动与升级 RC：

docker compose pull local-deep-research-pre docker compose up -d local-deep-research-pre # UI 地址：http://localhost:5001 # 新版 RC 发布后重复执行上面的 pull + up -d 即可升级

五、构建：Python 包与前端资产

5.1 构建 Python 发行包

pdm build

生成 wheel 与源码分发包。项目的ldr-web与ldr-mcp两个 console script 入口在 pyproject.toml 中声明，分别指向local_deep_research.web.app:main和local_deep_research.mcp:run_server。

5.2 构建前端资产

从源码开发 Web UI 时需要手动构建 Vite 前端：

npm install npm run build

产物输出到src/local_deep_research/web/static/dist/。

对 pip 用户无需此步——PyPI 发布的包已内置预构建资产。

5.3 依赖锁文件管理（pdm.lock）

项目用PDM与pdm.lock精确锁定依赖版本，保证可复现构建。若 Docker 构建时出现：

WARNING: Lockfile hash doesn't match pyproject.toml, packages may be outdated

说明pyproject.toml已变更但锁文件未重新生成，执行修复：

pdm lock

务必把pdm.lock与pyproject.toml的改动一并提交，确保构建可复现。

六、测试体系：三种测试模式怎么选

6.1 后端隔离测试（默认推荐，无需起服务）

基于 FastAPI 的TestClient（底层为 Starlette）mock 服务器，是日常单元/集成测试的首选：

source .venv/bin/activate pytest tests/ # 运行全部隔离测试 pytest tests/api_tests/ # 指定 API 测试 pytest tests/auth_tests/ # 指定认证测试

仓库测试目录 tests/ 结构清晰，除api_tests/、auth_tests/外，还包括security/、database/、llm_providers/、connected/（真实每用户加密 SQLCipher 库的联通测试）、infrastructure_tests/等专项目录，conftest.py提供了统一的 mock 与 fixture。

6.2 在线系统测试（需真实运行的服务）

对运行中的应用实例发起真实 HTTP 请求：

# 前提：先在终端 1 启动后端 ldr-web（或 Docker） python tests/ui_tests/test_simple_research_api.py

6.3 前端与 E2E 测试（Puppeteer）

项目用 Puppeteer 做 UI 与端到端测试：

cd tests # 进入测试目录 npm install # 安装测试依赖 # 前提：应用已在本地 5000 端口（或 Docker）运行 node tests/ui_tests/run_all_ui_tests.js # 全部 UI 测试 node tests/ui_tests/test_simple_auth.js # 单个测试

关于测试标记，pyproject.toml 定义了requires_llm、integration、slow、asyncio、serial、nonroot、connected、lifespan等 pytest marker，其中serial/nonroot涉及进程全局状态与权限断言，CI 中需要在专门的容器步骤里以非 root 用户执行，本地跑全量测试时留意这些约束即可。

七、数据库管理：备份与恢复

创建备份

docker run --rm \ -v ldr_data:/from \ -v ldr_data-backup:/to \ debian:latest \ bash -c "cd /from ; tar -cf - . | (cd /to ; tar -xpf -)"

从备份恢复

⚠️ 警告：以下操作会覆盖现有数据

docker run --rm \ -v ldr_data:/target \ -v ldr_data-backup:/source \ debian:latest \ bash -c "rm -rf /target/* /target/.[!.]* ; \ cd /source ; tar -cf - . | (cd /target ; tar -xpf -)"

关于加密数据库的安全设计，docs/architecture/DATABASE_SCHEMA.md 描述了每用户独立 SQLCipher 库的模型关系；docs/security/database-backup.md 提供了更细粒度的备份安全说明。

八、故障排查速查表

8.1 SQLCipher 相关错误

见 docs/SQLCIPHER_INSTALL.md#troubleshooting 的排障小节，覆盖各类平台下的编译/加载失败场景。

8.2 Docker 卷权限拒绝

• 报错：PermissionError: [Errno 13] Permission denied: '/app/.config/...'
• 原因：卷可能由不同属主创建。
• 解决：

docker volume rm ldr_data # 重新运行容器以创建全新卷

8.3 服务重启后会话丢失

• 原因：应用使用密钥签名会话 Cookie。
• 解决：密钥在首次运行时自动生成并持久化到数据目录（由LDR_DATA_DIR控制）下的.secret_key文件中。只有删除该文件才会丢会话。若用 Docker，请确保数据卷（ldr_data:/data）持久化。

8.4 后台线程报 NoSettingsContextError

• 报错：NoSettingsContextError: No settings context available
• 原因：后台线程不继承线程本地的设置上下文（见 config/thread_settings.py），该上下文按线程而非按请求建立。
• 解决：应用已自动处理此场景；开发中如遇此类报错，请先在 Web UI 设置页确认 LLM 设置已配置。这也是 架构总览 中"每个研究线程持有独立设置快照、避免配置变更竞态"这一线程模型的直接体现。

8.5 PDM 锁文件不同步

• 报错：Lockfile hash doesn't match pyproject.toml
• 解决：

pdm lock git add pdm.lock

九、开发最佳实践小结

贯穿整份开发者指南的几个工程化要点值得沉淀为团队约定：

1. 提交前检查靠钩子：pre-commit install后，标准钩子（ruff/eslint/gitleaks）与 .pre-commit-hooks/ 中 50+ 个自定义钩子共同构成质量红线，其中安全类钩子（check-sensitive-logging、check-safe-requests、check-image-pinning）直接对齐 docs/CI_CD_INFRASTRUCTURE.md 描述的供应链与运行时安全策略。
2. 锁文件是构建契约：任何pyproject.toml变更都必须同步pdm lock，否则 Docker 与 CI 都会告警。
3. 数据隔离是安全底线：开发期可用LDR_BOOTSTRAP_ALLOW_UNENCRYPTED=true加速迭代，但生产环境必须保持加密数据库（SQLCipher）与独立卷（ldr_data）配置，LDR_DATA_DIR统一管理数据落盘位置。
4. 测试分层执行：日常用隔离 pytest，涉及真实 HTTP 与浏览器行为时切到在线脚本与 Puppeteer E2E，尊重serial/nonroot等特殊 marker 的运行前提。

如需继续深入，推荐依次阅读 docs/developing/EXTENDING.md（自定义搜索/策略/LLM 提供方）、docs/architecture/DATABASE_SCHEMA.md（数据模型）与 docs/CONFIGURATION.md（全量环境变量清单），把"能跑起来"升级为"能按需扩展"。

【免费下载链接】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