数据库文档数据库后端【免费下载链接】couchdbSeamless multi-primary syncing database with an intuitive HTTP/JSON API, designed for reliability项目地址https://gitcode.com/gh_mirrors/co/couchdb点击查看免费下载dreyfus 是 CouchDB 中负责全文搜索Full-Text Search能力的核心 Erlang 应用它通过管理一组名为 Clouseau 的 Java 节点将 Lucene 的索引与查询能力无缝接入 CouchDB 的分布式架构。本文以 dreyfus 模块的 README 为骨架结合仓库源码逐层拆解其应用结构、HTTP 请求生命周期与索引更新机制帮助你理解 CouchDB 全文搜索从 HTTP 请求到 Lucene 查询、再到跨分片结果合并的完整链路。dreyfus 是什么连接 CouchDB 与 Lucene 的桥梁dreyfus源码位于 src/dreyfus本身并不实现搜索算法它的职责是管理 Clouseau 节点以交付全文搜索功能。Clouseau 是基于 Java 的独立搜索服务内部使用 Lucene 完成真正的索引构建与查询dreyfus 则运行在 Erlang VM 中负责解析设计文档Design Document中的全文索引定义indexes字段为每个索引函数维护一个独立的 Erlang 索引进程并通过 RPC 与对应的 Clouseau 索引双胞胎twin保持同步将 HTTP 查询请求分发到数据库的各个分片shard上并行执行汇总各分片返回的top_docs结果排序、分页bookmark后返回给客户端。从代码结构看dreyfus 同时依赖mem3分片元数据、ioqIO 队列用于向 Clouseau 发起 RPC、couch_epi插件服务注册等应用见 dreyfus.app.src 中的{applications, [kernel, stdlib, couch_log, config, couch_event, mem3, ioq, couch_epi]}。模块文件组成一份源码级代码地图README 以文件为单位勾勒了 dreyfus 的整体结构下表结合源码逐一说明每个文件的实际职责文件职责结合源码dreyfus.app.src应用资源文件声明回调模块为dreyfus_app注册进程为dreyfus_index_manager与dreyfus_sup描述为 Clouseau index managerdreyfus_app.erl应用回调模块start/2中直接调用dreyfus_sup:start_link()启动顶层监督者dreyfus_sup.erl顶层监督者采用one_for_one策略唯一的子进程是dreyfus_index_managerpermanent、重启间隔 1000ms、强度 10dreyfus_index_manager.erl管理多个dreyfus_index进程的 gen_server维护 ETS 表?BY_SIG与?BY_PIDdreyfus_index.erl每个索引一个进程设计文档中一个索引函数对应一个索引封装索引打开、await、search、info、group1/group2 等回调dreyfus_index_updater.erl索引更新回调扫描增量变更文档并同步到 Lucene处理 purge 与 commitdreyfus_httpd.erl处理 HTTP 请求导出handle_search_req、handle_info_req、handle_cleanup_req、handle_analyze_req等dreyfus_fabric.erl 等 fabric 系列集群分片操作的代理函数集合包括dreyfus_fabric_search、dreyfus_fabric_cleanup、dreyfus_fabric_group1、dreyfus_fabric_group2、dreyfus_fabric_infodreyfus_rpc.erl在每个分片上执行的代理函数search/info/disk_size 等通过 rexi 在分片节点上运行clouseau_rpc.erl封装对 Clouseau Java 节点的远程过程调用open_index、search、update、delete、commit、analyze 等dreyfus_bookmark.erl书签管理工具用于取下一页结果dreyfus_util.erl各类工具函数如get_shards、get_ring_opts、sort、export、黑名单检查等从源码结构看dreyfus 还包含 dreyfus_config.erl、dreyfus_epi.erl 与 dreyfus_plugin_couch_db.erl分别负责配置读取、插件服务注册以及监听数据库变更事件README 未单独列出的这些文件进一步完善了模块的功能闭环。应用启动与监督树一次极简的 Erlang 应用dreyfus 是一个标准 OTP application。启动链条非常清晰dreyfus.app.src 声明{mod, {dreyfus_app, []}}与{registered, [dreyfus_index_manager, dreyfus_sup]}即启动时由dreyfus_app回调负责拉起进程并保证这两个注册进程存在。dreyfus_app.erl 的start/2调用dreyfus_sup:start_link()。dreyfus_sup.erl 初始化时把子进程列表通过couch_epi:register_service(dreyfus_epi, Children)注册为 epi 服务子进程即dreyfus_index_manager。也就是说整个 dreyfus 应用在运行时只需保证一个dreyfus_index_manager进程存活其余索引进程全部由它按需动态派生这与 README 中dreyfus_index_manager 管理多个 dreyfus_index 进程的描述完全吻合。核心数据结构dreyfus.hrl 中的记录设计理解 dreyfus 的关键在于 dreyfus.hrl 中定义的核心记录#index{}一个索引的本地表示字段包括current_seq当前已同步的数据库更新序号默认 0、dbname、ddoc_id、analyzer分析器、def索引函数定义、def_lang定义语言默认javascript、name索引名、sig签名nil 表示未计算。#index_query_args{}查询参数集合默认值直接反映了 CouchDB Search API 的行为limit25、stalefalse、sortrelevance、grouping#grouping{}、drilldown[]以及高亮相关参数highlight_pre_tag em、highlight_post_tag /em、highlight_number1、highlight_size0。#top_docs{}本地的 top_docs 表示README 特别注明不等同于线上传输格式字段为update_seq、total_hits、hits、counts、ranges。#hit{}单个命中结果含order排序键与fields字段注释指出该结构必须与 Clouseau 侧 Java 的 case class 保持一致。#sortable{}带排序信息的命中记录order为排序键、shard为来源分片、item为命中本身。#index_query_args是查询参数在分片间传递的核心载体dreyfus_util.erl 的export/1会对partition、counts、ranges、include_fields、highlight_fields等字段做裁剪置为 nil/空只把必要参数序列化到远端执行从而减小集群间 RPC 的传输开销。HTTP 请求的完整生命周期12 步拆解README 用一张时序图描述了请求的生命周期下面结合源码把每一步落到实处。第 1 步从 chttpd 进入 dreyfus_httpdHTTP 请求GET/POST的_search端点由 chttpd 分发到 dreyfus_httpd.erl 的handle_search_req/3。该函数先调用verify_search_available()检查搜索是否可用再解析查询参数。分片shard场景下请求路径形如/db/_design/ddoc/_search/index路径段数量决定了索引名在path_parts中的位置。第 2 步参数解析与校验parse_index_params(Req, Db)与validate_index_query负责把 URL 参数转换为#index_query_args{}记录。此后根据Grouping#grouping.by是否为nil分流by为nil普通搜索调用 dreyfus_fabric_search:go/4by非nil分组查询先调dreyfus_fabric_group1:go取分组列表再调dreyfus_fabric_group2:go取各组结果对应 README 提到的 fabric 函数族。第 3 步dreyfus_fabric 提交分片任务dreyfus_fabric_search.erl 的核心动作正是 README 摘录的两行代码Shards dreyfus_util:get_shards(DbName, QueryArgs), Workers fabric_util:submit_jobs( Shards, dreyfus_rpc, search, [DDoc, IndexName, dreyfus_util:export(QueryArgs)] )get_shards/2见 dreyfus_util.erl根据是否指定partition以及staleok/stabletrue等条件选择mem3:ushards用于 stale/stable 查询的统一分片或mem3:shards获取分片集合任务提交后fabric 进程通过rexi_utils:recv(Workers, #shard.ref, fun handle_message/3, State, ...)阻塞等待各分片结果超时上限为fabric_util:timeout(search, infinity)单条消息超时search_permsg默认 3600000ms1 小时。第 4 步dreyfus_rpc 在每个分片并行执行dreyfus_rpc.erl 的call/5是每个分片上的执行入口执行顺序为check_interactive_mode()若配置couchdb.maintenance_mode为true直接回复{rexi_EXIT, {maintenance_mode, node()}}并退出避免维护模式下的日志刷屏打开数据库并计算{_LastSeq, MinSeq} calculate_seqs(Db, Stale)dreyfus_index:design_doc_to_index(DDoc, IndexName)生成索引记录dreyfus_index_manager:get_index(DbName, Index)获取或创建索引进程dreyfus_index:await(Pid, MinSeq)按需触发索引更新调用对应搜索函数并把结果通过rexi:reply(Result)返回给发起方 fabric 进程。第 57 步dreyfus_index → clouseau_rpc → Lucenedreyfus_index:search_int/2见 dreyfus_index.erl把#index_query_args{}通过args_to_proplist转成属性列表query、limit、refresh、after、sort、counts、ranges、drilldown、高亮参数等随后调用clouseau_rpc:search(Pid, Props)。而 clouseau_rpc.erl 的所有 RPC 最终都汇入rpc(Ref, Msg) - ioq:call_search(Ref, Msg, erlang:get(io_priority)).即通过ioqIO 队列按当前进程的io_priority优先级向 Clouseau 发起调用真正在 Clouseau 节点上用 Lucene 完成检索并返回top_docs。返回后clouseau_rpc:search/2会把响应解析成#top_docs{}记录update_seq、total_hits、hits、counts、ranges。第 811 步结果回传与分片合并top_docs依次经dreyfus_index、dreyfus_rpc回到各分片进程每个分片以rexi:reply(Result)异步回复发起方。fabric 侧的handle_message({ok, #top_docs{} NewTopDocs}, Shard, State)dreyfus_fabric_search.erl对每个分片结果执行Sortable make_sortable(Shard, NewTopDocs), MergedTopDocs merge_top_docs(TopDocs, Sortable, Limit, Sort)merge_top_docs/4dreyfus_fabric_search.erl做的事情包括累加各分片的total_hits将各分片 hits 拼接后按Sort排序并截取Limit条对counts、ranges两个 facet 通过merge_facets递归合并同键累加计数。每收到一个分片结果就更新一次合并状态直到fabric_dict:any(nil, C2)为false所有分片都响应才停止。该合并逻辑还附带了完整的 EUnit 测试同文件-ifdef(TEST)段的merge_facets_test覆盖单层/多层、单键/多键的 facet 合并正确性。第 12 步dreyfus_httpd 格式化返回fabric 返回{ok, Bookmark, TotalHits, Hits, Counts, Ranges}后dreyfus_httpd.erl 通过hits_to_json将命中转成 JSON、用dreyfus_bookmark:pack打包书签最后以send_json(Req, 200, {...})返回total_rows、bookmark、rows以及可选的counts、ranges字段。索引机制搜索请求如何触发索引更新README 的第二张时序图解释了搜索请求驱动的索引更新这是 dreyfus 保证最终一致性的核心机制。第 1 步计算 MinSeqdreyfus_rpc.erl 的calculate_seqs/2calculate_seqs(Db, Stale) - LastSeq couch_db:get_update_seq(Db), if Stale ok orelse Stale update_after - {LastSeq, 0}; true - {LastSeq, LastSeq} end.非 stale 查询MinSeq LastSeq即查询前必须把索引至少推进到数据库当前更新序号保证结果反映最新变更staleok或staleupdate_afterMinSeq 0含义是等待索引至少到 update_seq 0——空索引也满足该条件因此无需触发更新即可直接返回结果。这也是 stale 查询吞吐更高的根本原因。第 2 步设计文档到索引记录dreyfus_index:design_doc_to_index/2dreyfus_index.erl解析设计文档的indexes字段取language默认javascript、索引的analyzer默认standard与index索引函数缺失时报invalid_design_doc错误。签名计算方式为Sig couch_util:to_hex(couch_hash:md5_hash(?term_to_bin({Analyzer, Def})))即对{分析器, 索引函数定义}求 MD5 哈希。如 README 所述Sig用于判断索引描述是否变化若设计文档中的索引函数或分析器改变Sig随之改变索引将被判定为需要重建。第 3 步get_index 与索引进程的懒创建dreyfus_index_manager:get_index(DbName, Index)dreyfus_index_manager.erl走 gen_server 的handle_call({get_index, DbName, #index{sig Sig} Index}, ...)逻辑如下在ets:lookup(?BY_SIG, {DbName, Sig})中命中已有 Pid → 直接返回{ok, ExistingPid}未命中 →spawn_link(fun() - new_index(DbName, Index) end)派生创建进程把调用方From记入?BY_SIG的等待列表gen_server 返回{noreply, State}不阻塞自己后续再来的同一索引调用会追加到等待列表[{_, WaitList}] when is_list(WaitList)分支new_index调用dreyfus_index:start_link成功则发{open_ok, DbName, Sig, NewPid}失败则发{open_error, ...}handle_call({open_ok, ...})向等待列表中的所有调用方gen_server:reply(From, {ok, NewPid})并调用add_to_ets(NewPid, DbName, Sig)更新?BY_SIG与?BY_PID两张 ETS 表。此外dreyfus_index_manager通过handle_db_event/3监听数据库事件dreyfus_index_manager.erl库创建时 cast{cleanup, DbName}清理 Clouseau 端残留库删除时依据配置couchdb.enable_database_recovery决定 cast{rename, DbName}启用恢复还是{cleanup, DbName}。第 4 步await 与增量更新dreyfus_index:await(Pid, MinSeq)dreyfus_index.erl判断RequestSeq Seq时才会触发更新spawn 一个 updater 进程执行dreyfus_index_updater:update(IndexPid, Index)并把调用方放入waiting_list若当前RequestSeq Seq则直接回复{ok, IndexPid, Seq}。update 完成后handle_info({EXIT, FromPid, {updated, NewSeq}}, ...)会逐个回复等待列表中的调用方。这里还有一个细节updater 启动前会经dreyfus_util:in_black_list/3检查索引黑名单命中则打日志并跳过更新对应测试文件 dreyfus_blacklist_await_test.erl 与 dreyfus_blacklist_request_test.erl。索引更新器详解从增量扫描到 Lucene 提交dreyfus_index_updater.erl 的update/2是索引同步的主体流程为couch_db:count_changes_since(Db, CurSeq)统计自上次同步以来的变更数加上待处理的 purge 变更数注册search_indexer类型任务到任务状态含database、design_document、index、progress、changes_done、total_changes每 500ms 刷新进度purge_index/3先处理被 purge 的文档从 Clouseau 读取get_purge_seq对已删除的文档调用clouseau_rpc:delete清理 Lucene 索引并返回需排除的{Id, Rev}列表避免更新阶段重复写入获取查询服务器进程get_os_process(Index#index.def_lang)通过proc_prompt(Proc, [add_fun, Index#index.def])注入索引函数couch_db:fold_changes(Db, CurSeq, EnumFun, Acc0, [])从CurSeq起增量遍历变更对每个文档调用clouseau_rpc:update更新或clouseau_rpc:delete删除README 中描述的逐文档调用期间每满 60 秒强制clouseau_rpc:commit一次防止长时间无提交全部处理完后clouseau_rpc:commit(IndexPid, NewCurSeq)提交并记录新序号进程以exit({updated, NewCurSeq})结束通知 dreyfus_index 唤醒等待者。整个链路验证了 README 的关键论断dreyfus 通过#index{current_seq}与 Clouseau 侧的 Lucene 提交序号保持一致实现增量式同步而 purge 场景的同步则另有 dreyfus_purge_test.erl 专项覆盖。关键配置项与运维提示从源码中可以确认以下直接影响 dreyfus 行为的配置配置位置/默认值作用dreyfus.nameclouseau_rpc.erl默认clouseau127.0.0.1Clouseau 节点的 Erlang 节点名dreyfus 通过该原子名发起 RPC部署时须与实际 Clouseau 节点保持一致couchdb.enable_database_recoverydreyfus_index_manager.erl默认false数据库被删除时为true则对索引执行rename配合恢复为false则直接cleanupcouchdb.maintenance_modedreyfus_rpc.erl默认false为true时所有分片搜索直接回复maintenance_mode错误并退出fabric.search/fabric.search_permsgdreyfus_fabric_search.erl搜索总超时默认infinity单消息超时默认 3600000ms控制集群搜索的等待超时其中 Clouseau 节点名配置是部署全文搜索时最容易出错的点dreyfus 与 Clouseau 之间是 Erlang 分布式节点互联erlang:nodes(hidden)中查找必要时net_adm:ping探测节点名、cookie 与网络可达性缺一不可。测试覆盖行为即契约dreyfus 的 EUnit 测试位于 src/dreyfus/test/eunit与 README 描述的行为一一对应dreyfus_blacklist_await_test.erl / dreyfus_blacklist_request_test.erl验证被列入黑名单的索引不触发更新、不响应查询dreyfus_config_test.erl验证配置读取逻辑dreyfus_purge_test.erl验证 purge 后索引的正确清理dreyfus_test_util.erl公共测试工具启动测试 Clouseau、构造设计文档等。小结dreyfus 的架构可以概括为一条清晰的职责链dreyfus_httpd 收请求 → dreyfus_fabric 分片分发与结果合并 → dreyfus_rpc 分片执行 → dreyfus_index 索引进程 → clouseau_rpc 桥接 → Clouseau/Lucene 完成检索而索引同步则由calculate_seqs计算的最小序号驱动经dreyfus_index_updater增量同步到 Lucene。理解这条链路后无论是排查为什么 stale 查询不返回最新结果MinSeq0的语义还是为什么改了索引函数后索引要重建Sig的 MD5 判定都能迅速在 src/dreyfus/src 中找到对应实现。赞分享数据库文档数据库后端【免费下载链接】couchdbSeamless multi-primary syncing database with an intuitive HTTP/JSON API, designed for reliability项目地址https://gitcode.com/gh_mirrors/co/couchdb点击查看免费下载相关推荐CouchDB 全文搜索索引实战指南设计文档、Lucene 查询语法与 Clouseau 集成CouchDB 全文搜索索引实战指南设计文档、Lucene 查询语法与 Clouseau 集成 全文搜索Search是 CouchDB 在传统 MapRe数据库文档数据库后端Obsidian Tracker终极指南从笔记数据到可视化洞察的完整解决方案Obsidian Tracker终极指南从笔记数据到可视化洞察的完整解决方案 你是否曾经在Obsidian中积累了大量的笔记数据却不知道如何从中提取有价值的CouchDB Nouveau 全文索引实战指南从索引定义、分析器到 Lucene 查询与分面检索CouchDB Nouveau 全文索引实战指南从索引定义、分析器到 Lucene 查询与分面检索 CouchDB 的 Nouveau 是一个实验性全文搜索索数据库文档数据库后端上一篇misakaX深度解析基于TrollRestore漏洞的iOS系统定制化技术实现与应用指南下一篇终极免费AI瞄准助手Aimmy5分钟解决你的游戏瞄准难题创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考