Local Deep Research 数据库架构深度解析SQLCipher 加密、ORM 模型与全链路数据设计【免费下载链接】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-researchLocal Deep Research 是一套完全本地化、加密存储的深度研究系统其数据层以SQLAlchemy ORM SQLCipher 加密 SQLite为基石为每个用户提供独立的加密数据库并以单一auth.db集中管理用户注册信息。本文以仓库 DATABASE_SCHEMA.md 为核心骨架结合 models 下的真实模型实现与 encrypted_db.py、sqlcipher_utils.py 的加密逻辑完整梳理研究任务、文档库RAG、笔记、队列、指标、新闻、基准测试、限流、文件完整性等十余组领域模型及其表间关系帮助你从建表到读写调用全面掌握该项目的数据库设计。存储架构总览每用户一个加密数据库核心设计特征Local Deep Research 的数据层采用中央认证库 每用户加密库的双库架构每用户独立数据库每个注册用户拥有属于自己的加密 SQLite 数据库文件用户数据天然隔离AES-256 加密用户密码经 PBKDF2 派生密钥SQLCipher 以 AES-256 加密整个数据库文件HMAC 完整性校验数据库页面附带 HMAC任何磁盘篡改都会被检测中央认证库只存用户名auth.db中从不存储密码只保存用户名等元数据——密码的正确性通过能否用该密码成功解密用户库来判定。数据库落盘位置文档给出的标准目录结构DATABASE_SCHEMA.md~/.local/share/local-deep-research/ ├── auth.db # Central auth database (unencrypted) └── users/ └── username/ └── research.db # Users encrypted database结合 paths.py 的源码实现可以补充几点精确信息数据根目录由platformdirs按平台解析Linux 为~/.local/share/local-deep-researchmacOS 为~/Library/Application Support/local-deep-researchWindows 为%LOCALAPPDATA%\local-deep-research可通过环境变量LDR_DATA_DIR覆盖默认位置必须为绝对路径且拒绝含空字节、换行、回车符的危险路径实际加密库存放于LDR_DATA_DIR/encrypted_databases/下而非文档示例中的users/username/子目录——这正是文档标注示例结构的原因真实布局以encrypted_databases/为准用户名并不直接作为文件名而是先经 SHA-256 取前 16 位十六进制生成形如ldr_user_hash.db的文件名paths.py避免特殊字符导致文件系统问题目录权限被收紧为0o700数据库文件为0o600encrypted_db.py。中央认证库 auth.db认证库由 auth_db.py 管理文件名为ldr_auth.db注意与文档示例auth.db的差异。该库是不加密的普通 SQLite因为它本身不含敏感数据只包含users一张表。引擎采用QueuePool(pool_size10, max_overflow20)并以模块级全局缓存复用避免每个请求重复建引擎造成文件描述符泄漏连接建立时应用PRAGMA busy_timeout 10000与PRAGMA temp_store MEMORY。实体关系总览ER 图原文档用 Mermaid ER 图刻画了核心模型间的关系此处完整保留需要指出的是ER 图中的Research与ResearchHistory在源码中承担着不同的历史角色research_historyUUID 主键是当前实际使用的活跃表researchInteger 主键则是文档所述现代类型安全追踪模型ResearchStrategy等外键实际指向的是research_history.id而非research.idresearch.py。研究域模型ResearchTask、SearchQuery、SearchResult 与 Report研究域是系统的核心。ResearchTask是顶层容器通过searches、results、reports三个级联关系聚合全部研究活动。源码中的状态与索引细节如下research.pyColumnTypeDescriptionidIntegerPrimary keytitleString(500)研究标题nullableFalsedescriptionText详细描述statusString(50)pending / in_progress / completed / failedpriorityInteger优先级默认 0数值越大越优先tagsJSON分类标签列表research_metadataJSON灵活元数据存储created_at/updated_atUtcDateTime创建 / 更新时间戳UTCstarted_at/completed_atUtcDateTime开始 / 完成时间源码补充三个关系均声明cascadeall, delete-orphan删除任务会级联清理其查询、结果与报告时间戳统一使用sqlalchemy_utc的UtcDateTime确保跨时区一致。SearchQuery记录任务中的每一次检索research.pyresearch_task_id外键带ondeleteCASCADEsearch_engine可取值 duckduckgo、arxiv 等search_type区分 web / academic / news。它定义了两个复合索引idx_research_task_status (research_task_id, status)idx_search_engine (search_engine, status)SearchResult存储检索结果及抓取内容research.py其文档化字段包括content_hash去重、relevance_score相关度、fetch_statuspending/fetched/failed/skipped等。源码额外增加三个性能索引idx_task_relevance (research_task_id, relevance_score)、idx_content_hash (content_hash)、idx_domain_task (domain, research_task_id)其中url与domain列直接声明indexTrue。Report与ReportSection构成报告主从结构reports.py。文档的字段表之外源码还包含subtitle、abstract、template、style、language、word_count、section_count、reference_count、image_count、generation_params、generation_model、generation_time_seconds、version、is_draft、published_at等增强列sections关系按section_order排序并级联删除。认证与凭据模型密码永不落库User模型auth.py存放在中央认证库中ColumnTypeDescriptionidIntegerPrimary keyusernameString(80)唯一用户名索引created_atDateTime注册时间last_loginDateTime最后登录时间database_versionInteger数据库 schema 版本源码注释明确强调此模型没有 password_hash 列也没有 set_password 方法。认证流程是尝试用提交的密码解密该用户的 SQLCipher 库——解密成功即密码正确失败即密码错误。修改密码时只需对 SQLCipher 数据库执行PRAGMA rekey模型层没有任何需要更新的字段。APIKeysettings.py在文档中描述了key_hash列而当前源码实现为按provider唯一存储加密后的key由 SQLCipher 加密、is_active、usage_count、last_used等字段其__repr__刻意不输出密钥本体。设置模型全局 Setting 与每用户 UserSettingsSettingsettings.py是全局应用设置key唯一且索引type使用SettingType枚举app / chat / llm / search / report / database并支持 UI 元数据ui_element、options、min_value、max_value、step、visible、editable及env_var环境变量映射UserSettingssettings.py是存于用户加密库中的个性化覆盖key唯一索引value为 JSON 类型替代了传统配置文件或明文存储方案。文档库与 RAG 模型Document、Collection、DocumentChunk 与 RAGIndex文档库为 RAG检索增强生成提供数据底座。Documentlibrary.py是统一文档表同时承载研究下载与用户上传id为 UUID 字符串source_type_id外键指向规范化表source_types取值包括 research_download、user_upload、manual_entry、research_report、research_sourcedocument_hashSHA256唯一索引用于去重并保留doi、arxiv_id、pmid、pmcid等学术标识字段。源码还包含文档模型所描述的file_size、mime_type、text_content、metadata之外的storage_modenone/filesystem/database、authorsJSON、upload_batch_id等扩展列。Collectionlibrary.py按collection_type区分默认库/用户集合/链接文件夹is_public标记集合内容是否非敏感默认私有用于 egress 数据分级私有集合禁止向云端模型发送其分块。DocumentCollection为文档-集合多对多连接表。DocumentChunklibrary.py是 RAG 分块存储表chunk_text存于加密库中embedding_idUUID唯一映射 FAISS 向量embedding_model、embedding_model_type、embedding_dimension记录向量来源与维度start_char/end_char/word_count提供精确定位。RAGIndex记录集合级向量索引元数据status使用RAGIndexStatus枚举。笔记模型复用 documents 的 note_* 卫星表笔记并非独立表而是source_type note的documents行配合多张note_*卫星表复用 Library/RAG/embedding 全栈能力详见 NOTES.mdTablePurposeKey FKs (ondelete)note_versions版本历史快照原子恢复FIFO 上限 100 份document_id → documents(CASCADE)note_linksWiki 风格[[link]]笔记间边source_document_id,target_document_id → documents(CASCADE)note_research固定到笔记的研究运行document_id → documents,research_id → research_history(CASCADE)note_references通用引用/行内标注层文档 XOR 研究目标note_id,target_document_id → documents;target_research_id → research_history(all CASCADE)note_synthesesAI 综合合并/摘要/对比审计记录result_document_id → documents(SET NULL)note_synthesis_sources综合的源笔记synthesis_id → note_syntheses,source_document_id → documents(CASCADE)对应的模型定义位于 note.py由迁移0021_add_note_tables.py与0022_add_note_references.py创建migrations/versions。队列管理QueuedResearch 与 TaskMetadataQueuedResearchqueued_research.py跟踪排队中的研究请求research_idUUID唯一username索引settings_snapshotJSON 保存完整研究设置快照position记录队列位置is_processing标记是否正在处理。文档所述QueueStatus枚举pending/running/completed/failed/cancelled在 queue.py 中以TaskMetadata承载该表以task_id字符串为主键支持task_typeresearch、benchmark 等、retry_count/max_retries默认 3、进度三元组progress_current/progress_total/progress_message及metadata_json。指标与分析TokenUsage、SearchCall、ModelUsage 与 ResearchRatingTokenUsagemetrics.py按research_id索引的 LLM 令牌消费明细除prompt_tokens/completion_tokens/total_tokens外还记录prompt_cost/completion_cost/total_cost美元、operation_type、operation_detailsJSON、response_time_ms、success_status、error_type、research_query、research_phase、search_iteration、calling_file/calling_function等增强字段——可用于精确归因每次研究各阶段的模型成本与耗时SearchCall检索 API 调用日志engine、query、result_count、duration_ms、successModelUsage按(model, provider, date)聚合的日粒度统计total_input_tokens / total_output_tokens / total_cost / request_countResearchRating研究质量用户评分1-5 分 可选反馈文本。新闻系统NewsSubscription、NewsCard 与推荐相关表NewsSubscriptionnews.py字段远比文档表格丰富subscription_typesearch/topic、refresh_interval_minutes默认 1440即 24 小时、frequency、last_refresh/next_refresh/expires_at、来源追踪source_type/source_id/created_from、组织folder/folder_id、模型配置model_provider/model/search_strategy/custom_endpoint、搜索配置search_engine/search_iterations/questions_per_iteration以及status状态字段。NewsCard对应单条新闻news_user_ratings、news_user_preferences、news_interests三表构成推荐系统的用户交互数据news.py。基准测试BenchmarkRun、BenchmarkResult 与 BenchmarkProgress基准测试域benchmark.py的枚举在源码中得到精确化DatasetType为 simpleqa / browsecomp / xbench_deepsearch / customBenchmarkStatus为 pending / in_progress / completed / failed / cancelled / paused。BenchmarkRun记录运行名、数据集类型、被测策略与configJSON 快照BenchmarkResult逐题记录question/expected_answer/actual_answer/is_correct/score/latency_ms/tokens_usedBenchmarkProgress以completed/total/current_accuracy支持运行中的进度与准确率回传。自适应限流RateLimitAttempt 与 RateLimitEstimate限流域rate_limiting.py服务于多搜索引擎的自适应退避RateLimitAttempt记录每次限流事件engine_type、timestamp、wait_time、retry_count、success、error_type并定义三个复合索引enginetimestamp、successtimestamp、enginesuccesstimestampRateLimitEstimate存储学习得到的每引擎最优等待时长estimated_wait、confidence置信度与sample_count样本数。文件完整性FileIntegrityRecord 与 FileVerificationFailureFileIntegrityRecordfile_integrity.py以file_path唯一索引跟踪 FAISS 索引、PDF、导出文件等资产的当前校验和sha256 与 blake3及内嵌验证统计只有失败事件才写入FileVerificationFailureexpected_hash/actual_hash/failure_type以控制审计日志体积。加密引擎实现从密码到 SQLCipher 密钥理解这套 schema 后还需掌握数据是如何被加密保护的。核心实现位于 encrypted_db.py 与 sqlcipher_utils.py1. 每库独立盐Salt新库创建时生成 32 字节256 位随机盐写入与数据库同名的.salt侧文件SALT_FILE_SUFFIX .saltsqlcipher_utils.py旧版 v1 库回退到共享盐以保证向后兼容但会输出弃用警告。create_user_database对盐文件缺失/孤儿场景做了自愈处理encrypted_db.py。2. PBKDF2 密钥派生用户密码经pbkdf2_hmac与每库盐共同派生加密密钥sqlcipher_utils.py。默认 KDF 迭代次数DEFAULT_KDF_ITERATIONS 256000上限MAX_KDF_ITERATIONS 1_000_000可通过环境设置db_config.kdf_iterations调整越界时回退默认值。3. 规范化 PRAGMA 序列SQLCipher 初始化遵循固定顺序——先设置密钥再应用 cipher 参数cipher_page_size、cipher_hmac_algorithm、cipher_kdf_algorithm、cipher_memory_security随后用PRAGMA cipher_version验证连接最后应用性能 PRAGMA。默认 HMAC 算法为HMAC_SHA512DEFAULT_HMAC_ALGORITHMsqlcipher_utils.py这正对应文档所述 AES-256 encryption HMAC verification 的完整形态。4. 连接池与并发生产环境使用QueuePool(pool_size20, max_overflow40, pool_timeout10)测试环境用 StaticPool理由记录在 ADR-0004SQLCipherWAL 模式连接乱序关闭易泄漏文件句柄、SQLite 写事务全局串行、UI 轮询/api/research/id/status每秒 1-2 次需要足够并发余量。连接以username → engine缓存并配套密钥化 HMAC 校验器防止缓存命中时错误接受任意密码encrypted_db.py。5. 无 SQLCipher 时的降级若环境未安装 SQLCipher_check_encryption_available会拒绝启动并给出安装指引仅当显式设置LDR_BOOTSTRAP_ALLOW_UNENCRYPTEDtrue或其注册表对应项bootstrap.allow_unencrypted时才以明文 SQLite 运行并输出显著警告encrypted_db.py。明文模式下数据库文件仍会被收紧到0o600权限。SQLCipher 的安装方式可参考 SQLCIPHER_INSTALL.md。6. 迁移体系用户库创建后由 initialize.py 完成 schema 初始化与 Alembic 版本盖章后续 schema 演进全部经由 migrations/versions 下的编号迁移文件当前已推进至0030_default_time_period_all.py涵盖列新增、索引重建、表废弃如0015_drop_document_notes.py、0016_drop_orphaned_cache_tables.py等操作。实践要点与排查建议定位数据文件默认 Linux 路径为~/.local/share/local-deep-research/其中ldr_auth.db是明文认证库encrypted_databases/ldr_user_hash.db是用户的加密库如需迁移可设置LDR_DATA_DIR指向新绝对路径备份加密库备份与源库盐文件强绑定备份不复制盐删除.salt会使既有备份失效备份方案详见 database-backup.md排查登录/迁移问题数据库初始化采用失败即报错并清理半成品的策略——注册或迁移失败时会删除残缺的.db/.salt/WAL 侧文件避免用户名被永久锁定常见问题可参考 troubleshooting.md理解状态机任务、查询、队列、基准测试各自拥有独立状态枚举排查问题时需区分research_tasks.statusresearch 生命周期与queued_researches.is_processing队列调度状态扩展新模型新增表需遵循模型定义在 models 迁移脚本在 migrations/versions 导出到 models/__init__.py 的 Base.metadata三步流程扩展指南见 EXTENDING.md。本文所有模型字段与加密细节均可回溯至 DATABASE_SCHEMA.md 及 models 目录下的同名实现文件你可以对照源码逐表核验并在 OVERVIEW.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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Local Deep Research 数据库架构深度解析：SQLCipher 加密、ORM 模型与全链路数据设计
Local Deep Research 数据库架构深度解析SQLCipher 加密、ORM 模型与全链路数据设计【免费下载链接】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-researchLocal Deep Research 是一套完全本地化、加密存储的深度研究系统其数据层以SQLAlchemy ORM SQLCipher 加密 SQLite为基石为每个用户提供独立的加密数据库并以单一auth.db集中管理用户注册信息。本文以仓库 DATABASE_SCHEMA.md 为核心骨架结合 models 下的真实模型实现与 encrypted_db.py、sqlcipher_utils.py 的加密逻辑完整梳理研究任务、文档库RAG、笔记、队列、指标、新闻、基准测试、限流、文件完整性等十余组领域模型及其表间关系帮助你从建表到读写调用全面掌握该项目的数据库设计。存储架构总览每用户一个加密数据库核心设计特征Local Deep Research 的数据层采用中央认证库 每用户加密库的双库架构每用户独立数据库每个注册用户拥有属于自己的加密 SQLite 数据库文件用户数据天然隔离AES-256 加密用户密码经 PBKDF2 派生密钥SQLCipher 以 AES-256 加密整个数据库文件HMAC 完整性校验数据库页面附带 HMAC任何磁盘篡改都会被检测中央认证库只存用户名auth.db中从不存储密码只保存用户名等元数据——密码的正确性通过能否用该密码成功解密用户库来判定。数据库落盘位置文档给出的标准目录结构DATABASE_SCHEMA.md~/.local/share/local-deep-research/ ├── auth.db # Central auth database (unencrypted) └── users/ └── username/ └── research.db # Users encrypted database结合 paths.py 的源码实现可以补充几点精确信息数据根目录由platformdirs按平台解析Linux 为~/.local/share/local-deep-researchmacOS 为~/Library/Application Support/local-deep-researchWindows 为%LOCALAPPDATA%\local-deep-research可通过环境变量LDR_DATA_DIR覆盖默认位置必须为绝对路径且拒绝含空字节、换行、回车符的危险路径实际加密库存放于LDR_DATA_DIR/encrypted_databases/下而非文档示例中的users/username/子目录——这正是文档标注示例结构的原因真实布局以encrypted_databases/为准用户名并不直接作为文件名而是先经 SHA-256 取前 16 位十六进制生成形如ldr_user_hash.db的文件名paths.py避免特殊字符导致文件系统问题目录权限被收紧为0o700数据库文件为0o600encrypted_db.py。中央认证库 auth.db认证库由 auth_db.py 管理文件名为ldr_auth.db注意与文档示例auth.db的差异。该库是不加密的普通 SQLite因为它本身不含敏感数据只包含users一张表。引擎采用QueuePool(pool_size10, max_overflow20)并以模块级全局缓存复用避免每个请求重复建引擎造成文件描述符泄漏连接建立时应用PRAGMA busy_timeout 10000与PRAGMA temp_store MEMORY。实体关系总览ER 图原文档用 Mermaid ER 图刻画了核心模型间的关系此处完整保留需要指出的是ER 图中的Research与ResearchHistory在源码中承担着不同的历史角色research_historyUUID 主键是当前实际使用的活跃表researchInteger 主键则是文档所述现代类型安全追踪模型ResearchStrategy等外键实际指向的是research_history.id而非research.idresearch.py。研究域模型ResearchTask、SearchQuery、SearchResult 与 Report研究域是系统的核心。ResearchTask是顶层容器通过searches、results、reports三个级联关系聚合全部研究活动。源码中的状态与索引细节如下research.pyColumnTypeDescriptionidIntegerPrimary keytitleString(500)研究标题nullableFalsedescriptionText详细描述statusString(50)pending / in_progress / completed / failedpriorityInteger优先级默认 0数值越大越优先tagsJSON分类标签列表research_metadataJSON灵活元数据存储created_at/updated_atUtcDateTime创建 / 更新时间戳UTCstarted_at/completed_atUtcDateTime开始 / 完成时间源码补充三个关系均声明cascadeall, delete-orphan删除任务会级联清理其查询、结果与报告时间戳统一使用sqlalchemy_utc的UtcDateTime确保跨时区一致。SearchQuery记录任务中的每一次检索research.pyresearch_task_id外键带ondeleteCASCADEsearch_engine可取值 duckduckgo、arxiv 等search_type区分 web / academic / news。它定义了两个复合索引idx_research_task_status (research_task_id, status)idx_search_engine (search_engine, status)SearchResult存储检索结果及抓取内容research.py其文档化字段包括content_hash去重、relevance_score相关度、fetch_statuspending/fetched/failed/skipped等。源码额外增加三个性能索引idx_task_relevance (research_task_id, relevance_score)、idx_content_hash (content_hash)、idx_domain_task (domain, research_task_id)其中url与domain列直接声明indexTrue。Report与ReportSection构成报告主从结构reports.py。文档的字段表之外源码还包含subtitle、abstract、template、style、language、word_count、section_count、reference_count、image_count、generation_params、generation_model、generation_time_seconds、version、is_draft、published_at等增强列sections关系按section_order排序并级联删除。认证与凭据模型密码永不落库User模型auth.py存放在中央认证库中ColumnTypeDescriptionidIntegerPrimary keyusernameString(80)唯一用户名索引created_atDateTime注册时间last_loginDateTime最后登录时间database_versionInteger数据库 schema 版本源码注释明确强调此模型没有 password_hash 列也没有 set_password 方法。认证流程是尝试用提交的密码解密该用户的 SQLCipher 库——解密成功即密码正确失败即密码错误。修改密码时只需对 SQLCipher 数据库执行PRAGMA rekey模型层没有任何需要更新的字段。APIKeysettings.py在文档中描述了key_hash列而当前源码实现为按provider唯一存储加密后的key由 SQLCipher 加密、is_active、usage_count、last_used等字段其__repr__刻意不输出密钥本体。设置模型全局 Setting 与每用户 UserSettingsSettingsettings.py是全局应用设置key唯一且索引type使用SettingType枚举app / chat / llm / search / report / database并支持 UI 元数据ui_element、options、min_value、max_value、step、visible、editable及env_var环境变量映射UserSettingssettings.py是存于用户加密库中的个性化覆盖key唯一索引value为 JSON 类型替代了传统配置文件或明文存储方案。文档库与 RAG 模型Document、Collection、DocumentChunk 与 RAGIndex文档库为 RAG检索增强生成提供数据底座。Documentlibrary.py是统一文档表同时承载研究下载与用户上传id为 UUID 字符串source_type_id外键指向规范化表source_types取值包括 research_download、user_upload、manual_entry、research_report、research_sourcedocument_hashSHA256唯一索引用于去重并保留doi、arxiv_id、pmid、pmcid等学术标识字段。源码还包含文档模型所描述的file_size、mime_type、text_content、metadata之外的storage_modenone/filesystem/database、authorsJSON、upload_batch_id等扩展列。Collectionlibrary.py按collection_type区分默认库/用户集合/链接文件夹is_public标记集合内容是否非敏感默认私有用于 egress 数据分级私有集合禁止向云端模型发送其分块。DocumentCollection为文档-集合多对多连接表。DocumentChunklibrary.py是 RAG 分块存储表chunk_text存于加密库中embedding_idUUID唯一映射 FAISS 向量embedding_model、embedding_model_type、embedding_dimension记录向量来源与维度start_char/end_char/word_count提供精确定位。RAGIndex记录集合级向量索引元数据status使用RAGIndexStatus枚举。笔记模型复用 documents 的 note_* 卫星表笔记并非独立表而是source_type note的documents行配合多张note_*卫星表复用 Library/RAG/embedding 全栈能力详见 NOTES.mdTablePurposeKey FKs (ondelete)note_versions版本历史快照原子恢复FIFO 上限 100 份document_id → documents(CASCADE)note_linksWiki 风格[[link]]笔记间边source_document_id,target_document_id → documents(CASCADE)note_research固定到笔记的研究运行document_id → documents,research_id → research_history(CASCADE)note_references通用引用/行内标注层文档 XOR 研究目标note_id,target_document_id → documents;target_research_id → research_history(all CASCADE)note_synthesesAI 综合合并/摘要/对比审计记录result_document_id → documents(SET NULL)note_synthesis_sources综合的源笔记synthesis_id → note_syntheses,source_document_id → documents(CASCADE)对应的模型定义位于 note.py由迁移0021_add_note_tables.py与0022_add_note_references.py创建migrations/versions。队列管理QueuedResearch 与 TaskMetadataQueuedResearchqueued_research.py跟踪排队中的研究请求research_idUUID唯一username索引settings_snapshotJSON 保存完整研究设置快照position记录队列位置is_processing标记是否正在处理。文档所述QueueStatus枚举pending/running/completed/failed/cancelled在 queue.py 中以TaskMetadata承载该表以task_id字符串为主键支持task_typeresearch、benchmark 等、retry_count/max_retries默认 3、进度三元组progress_current/progress_total/progress_message及metadata_json。指标与分析TokenUsage、SearchCall、ModelUsage 与 ResearchRatingTokenUsagemetrics.py按research_id索引的 LLM 令牌消费明细除prompt_tokens/completion_tokens/total_tokens外还记录prompt_cost/completion_cost/total_cost美元、operation_type、operation_detailsJSON、response_time_ms、success_status、error_type、research_query、research_phase、search_iteration、calling_file/calling_function等增强字段——可用于精确归因每次研究各阶段的模型成本与耗时SearchCall检索 API 调用日志engine、query、result_count、duration_ms、successModelUsage按(model, provider, date)聚合的日粒度统计total_input_tokens / total_output_tokens / total_cost / request_countResearchRating研究质量用户评分1-5 分 可选反馈文本。新闻系统NewsSubscription、NewsCard 与推荐相关表NewsSubscriptionnews.py字段远比文档表格丰富subscription_typesearch/topic、refresh_interval_minutes默认 1440即 24 小时、frequency、last_refresh/next_refresh/expires_at、来源追踪source_type/source_id/created_from、组织folder/folder_id、模型配置model_provider/model/search_strategy/custom_endpoint、搜索配置search_engine/search_iterations/questions_per_iteration以及status状态字段。NewsCard对应单条新闻news_user_ratings、news_user_preferences、news_interests三表构成推荐系统的用户交互数据news.py。基准测试BenchmarkRun、BenchmarkResult 与 BenchmarkProgress基准测试域benchmark.py的枚举在源码中得到精确化DatasetType为 simpleqa / browsecomp / xbench_deepsearch / customBenchmarkStatus为 pending / in_progress / completed / failed / cancelled / paused。BenchmarkRun记录运行名、数据集类型、被测策略与configJSON 快照BenchmarkResult逐题记录question/expected_answer/actual_answer/is_correct/score/latency_ms/tokens_usedBenchmarkProgress以completed/total/current_accuracy支持运行中的进度与准确率回传。自适应限流RateLimitAttempt 与 RateLimitEstimate限流域rate_limiting.py服务于多搜索引擎的自适应退避RateLimitAttempt记录每次限流事件engine_type、timestamp、wait_time、retry_count、success、error_type并定义三个复合索引enginetimestamp、successtimestamp、enginesuccesstimestampRateLimitEstimate存储学习得到的每引擎最优等待时长estimated_wait、confidence置信度与sample_count样本数。文件完整性FileIntegrityRecord 与 FileVerificationFailureFileIntegrityRecordfile_integrity.py以file_path唯一索引跟踪 FAISS 索引、PDF、导出文件等资产的当前校验和sha256 与 blake3及内嵌验证统计只有失败事件才写入FileVerificationFailureexpected_hash/actual_hash/failure_type以控制审计日志体积。加密引擎实现从密码到 SQLCipher 密钥理解这套 schema 后还需掌握数据是如何被加密保护的。核心实现位于 encrypted_db.py 与 sqlcipher_utils.py1. 每库独立盐Salt新库创建时生成 32 字节256 位随机盐写入与数据库同名的.salt侧文件SALT_FILE_SUFFIX .saltsqlcipher_utils.py旧版 v1 库回退到共享盐以保证向后兼容但会输出弃用警告。create_user_database对盐文件缺失/孤儿场景做了自愈处理encrypted_db.py。2. PBKDF2 密钥派生用户密码经pbkdf2_hmac与每库盐共同派生加密密钥sqlcipher_utils.py。默认 KDF 迭代次数DEFAULT_KDF_ITERATIONS 256000上限MAX_KDF_ITERATIONS 1_000_000可通过环境设置db_config.kdf_iterations调整越界时回退默认值。3. 规范化 PRAGMA 序列SQLCipher 初始化遵循固定顺序——先设置密钥再应用 cipher 参数cipher_page_size、cipher_hmac_algorithm、cipher_kdf_algorithm、cipher_memory_security随后用PRAGMA cipher_version验证连接最后应用性能 PRAGMA。默认 HMAC 算法为HMAC_SHA512DEFAULT_HMAC_ALGORITHMsqlcipher_utils.py这正对应文档所述 AES-256 encryption HMAC verification 的完整形态。4. 连接池与并发生产环境使用QueuePool(pool_size20, max_overflow40, pool_timeout10)测试环境用 StaticPool理由记录在 ADR-0004SQLCipherWAL 模式连接乱序关闭易泄漏文件句柄、SQLite 写事务全局串行、UI 轮询/api/research/id/status每秒 1-2 次需要足够并发余量。连接以username → engine缓存并配套密钥化 HMAC 校验器防止缓存命中时错误接受任意密码encrypted_db.py。5. 无 SQLCipher 时的降级若环境未安装 SQLCipher_check_encryption_available会拒绝启动并给出安装指引仅当显式设置LDR_BOOTSTRAP_ALLOW_UNENCRYPTEDtrue或其注册表对应项bootstrap.allow_unencrypted时才以明文 SQLite 运行并输出显著警告encrypted_db.py。明文模式下数据库文件仍会被收紧到0o600权限。SQLCipher 的安装方式可参考 SQLCIPHER_INSTALL.md。6. 迁移体系用户库创建后由 initialize.py 完成 schema 初始化与 Alembic 版本盖章后续 schema 演进全部经由 migrations/versions 下的编号迁移文件当前已推进至0030_default_time_period_all.py涵盖列新增、索引重建、表废弃如0015_drop_document_notes.py、0016_drop_orphaned_cache_tables.py等操作。实践要点与排查建议定位数据文件默认 Linux 路径为~/.local/share/local-deep-research/其中ldr_auth.db是明文认证库encrypted_databases/ldr_user_hash.db是用户的加密库如需迁移可设置LDR_DATA_DIR指向新绝对路径备份加密库备份与源库盐文件强绑定备份不复制盐删除.salt会使既有备份失效备份方案详见 database-backup.md排查登录/迁移问题数据库初始化采用失败即报错并清理半成品的策略——注册或迁移失败时会删除残缺的.db/.salt/WAL 侧文件避免用户名被永久锁定常见问题可参考 troubleshooting.md理解状态机任务、查询、队列、基准测试各自拥有独立状态枚举排查问题时需区分research_tasks.statusresearch 生命周期与queued_researches.is_processing队列调度状态扩展新模型新增表需遵循模型定义在 models 迁移脚本在 migrations/versions 导出到 models/__init__.py 的 Base.metadata三步流程扩展指南见 EXTENDING.md。本文所有模型字段与加密细节均可回溯至 DATABASE_SCHEMA.md 及 models 目录下的同名实现文件你可以对照源码逐表核验并在 OVERVIEW.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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考