网硕互联帮助中心【免费下载链接】ten-framework
Open-source framework for conversational voice AI agents
项目地址：
https://gitcode.com/TEN-framework/ten-framework
点击查看 免费下载
本篇指南以 libwebsockets 官方最小示例 minimal-http-server-fulltext-search 为核心，讲解如何构建、运行一个内置全文检索能力的 HTTP 服务器，并深入剖析其背后的 lws FTS（Full Text Search）索引与查询机制。读完本文，你将掌握该示例的编译运行方式、前端自动补全与结果展示的交互流程、lws_fts_* 公共 API 的用法，以及 on-disk 索引文件的格式设计，可直接参考本仓库示例搭建自己的轻量全文搜索服务。
示例概览：一个自带全文搜索的 HTTP 服务器
该示例位于仓库的 third_party/libwebsockets/minimal-examples/http-server/minimal-http-server-fulltext-search 目录。它的目标非常具体：用 libwebsockets 启动一个 HTTP 服务器，将 Oscar Wilde《The Picture of Dorian Gray》全文（共 8904 行）作为检索语料，通过一个网页前端提供边输入边补全、命中行原文展示的全文搜索体验。
目录结构如下：
| minimal-http-server.c | 服务器主程序：创建 context、挂载静态目录与 /fts 动态协议 |
| CMakeLists.txt | 构建脚本，显式检查 LWS_WITH_FTS 等编译选项 |
| lws-fts.index | 预先生成的 FTS 索引文件（trie 序列化产物） |
| the-picture-of-dorian-gray.txt | 搜索语料：小说全文 |
| mount-origin/ | 静态页面资源：index.html、lws-fts.js、lws-fts.css 等 |
| plugins/protocol_fulltext_demo.c | 全文字搜索协议插件：处理 /a/（自动补全）与 /r/（查询结果）请求 |
构建：cmake 与 make
原文档给出的构建方式非常简洁：
$ cmake . && make
当前仓库内对应的 CMakeLists.txt 揭示了该示例的真实编译前提——libwebsockets 在编译时必须开启三个特性，否则构建会被 require_lws_config 检查拦截：
require_lws_config(LWS_ROLE_H1 1 requirements) # HTTP/1 角色
require_lws_config(LWS_WITH_FTS 1 requirements) # 全文搜索组件
require_lws_config(LWS_WITH_SERVER 1 requirements) # 服务器能力
也就是说，构建 libwebsockets 本身时需要开启 LWS_WITH_FTS（cmake 配置项），本示例依赖的 FTS 功能才可用。构建成功后会生成可执行文件 lws-minimal-http-server-fulltext-search。注意 CMakeLists.txt 中通过 include_directories(../../../plugins) 把插件目录加入头文件搜索路径，主程序里正是以 #include <protocol_fulltext_demo.c> 的方式静态引用插件源码（对应源码见 minimal-http-server.c）。
运行与访问：端口 7681
构建完成后按原文档运行：
$ ./lws-minimal-http-server
[2018/03/04 09:30:02:7986] USER: LWS minimal http server | visit http://localhost:7681
[2018/03/04 09:30:02:7986] NOTICE: Creating Vhost 'default' port 7681, 1 protocols, IPv6 on
然后浏览器访问 http://localhost:7681 即可。启动日志的两行含义：
- USER 行是示例自身的欢迎提示，告知访问地址；
- NOTICE 行来自 libwebsockets 核心，说明已创建名为 default 的 vhost，监听端口 7681，启用 IPv6。
服务器主程序的关键配置（见 minimal-http-server.c）：
memset(&info, 0, sizeof info);
info.port = 7681;
info.mounts = &mount; // 静态目录挂载链
info.protocols = protocols; // 含 lws-test-fts 协议
info.pvo = &pvo; // 协议私有选项：indexpath
info.options = LWS_SERVER_OPTION_HTTP_HEADERS_SECURITY_BEST_PRACTICES_ENFORCE;
- 静态挂载：URL 根路径 / 映射到 ./mount-origin 目录，默认文件 index.html（LWSMPRO_FILE）；
- 动态挂载：URL /fts 映射到协议 lws-test-fts（LWSMPRO_CALLBACK），所有全文搜索请求都走这里；
- 通过 pvo（protocol vhost options）将 indexpath 指向索引文件路径，默认值为 ./lws-fts.index。
前端交互：自动补全与命中行展示
页面入口 mount-origin/index.html 定义了一个搜索输入框（maxlength=80）和两个结果容器。全部逻辑在 mount-origin/lws-fts.js 中：
- 边输入边补全：监听输入框的 input 事件，每次输入都发起 GET ../fts/a/<关键词> 请求，返回以该前缀开头的自动补全建议列表；
- 回车出结果：输入框获得 viable 样式（即存在有效建议）后，按 Enter 发起 GET ../fts/r/<关键词> 请求，展示每个命中文件的行号与命中行原文；
- 两个请求都带 cache-control: max-age=0 头禁用缓存，确保实时性。
前端调用的 /a/ 与 /r/ 两个 URL 子路径，正是后端协议插件约定的"子目录选择任务"约定（见下文）。
后端协议剖析：一次搜索请求的完整链路
所有搜索请求最终落在协议插件 plugins/protocol_fulltext_demo.c 中。核心是 callback_fts 回调，关键分支如下：
1. 协议初始化（LWS_CALLBACK_PROTOCOL_INIT）
从 pvo 读取 indexpath 参数并存入 vhost 私有数据：
vhd = lws_protocol_vh_priv_zalloc(…);
if (lws_pvo_get_str(in, "indexpath", (const char **)&vhd->indexpath))
return 1;
若读取失败则初始化失败，协议不可用。
2. HTTP 请求分发（LWS_CALLBACK_HTTP）
if (strncmp(ccp, "/a/", 3) && strncmp(ccp, "/r/", 3))
goto reply_404;
params.needle = ccp + 3; // 关键词在第三个字符之后
if (*(ccp + 1) == 'a') // /a/ 自动补全
params.flags = LWSFTS_F_QUERY_AUTOCOMPLETE;
if (*(ccp + 1) == 'r') // /r/ 查询结果
params.flags = LWSFTS_F_QUERY_FILES |
LWSFTS_F_QUERY_FILE_LINES |
LWSFTS_F_QUERY_QUOTE_LINE;
params.max_autocomplete = 10;
params.max_files = 10;
然后执行一次完整的"打开索引 -> 搜索 -> 关闭"流程：
jtf = lws_fts_open(vhd->indexpath);
result = lws_fts_search(jtf, ¶ms);
lws_fts_close(jtf);
搜索结果是分配在 lwsac（内存块分配器）中的，从 result->autocomplete_head 与 result->filepath_head 拿到两条链表头，之后在 LWS_CALLBACK_HTTP_WRITEABLE 中分多次、按 2KB 缓冲流式序列化为 JSON 返回给前端。搜索结束后用 lwsac_free 释放结果内存（LWS_CALLBACK_CLOSED_HTTP 分支）。
3. JSON 输出格式
自动补全项输出 {"ac": "…", "matches": N, "agg": N, "elided": N}，其中 agg 是该前缀路径下所有后代命中的聚合数，用于排序"最可能结果"；文件命中项输出 {"path": "…", "matches": N, "origlines": N, "hits": [{"l": 行号, "o": 行起始偏移, "s": "命中行原文"}]}。
若索引文件打不开，则输出 {"indexed": 0, …}，前端据此显示"没有索引"的提示；索引构建中则由 JS 轮询并展示进度条。
FTS 公共 API 与查询选项
libwebsockets 的全文搜索接口集中在 include/libwebsockets/lws-fts.h，分为索引创建与索引搜索两组：
索引创建侧（写索引）：
| lws_fts_create(int fd) | 初始化新索引文件，返回 struct lws_fts * |
| lws_fts_file_index(t, filepath, len, priority) | 为每个输入文件登记 filepath，返回其序号 |
| lws_fts_fill(t, file_index, buf, len) | 逐缓冲块索引输入文件内容 |
| lws_fts_serialize(t) | 将所有输入处理完后，把内存 trie 序列化写入索引文件 |
| lws_fts_destroy(&trie) | 结束写入并释放内存 trie |
索引搜索侧（读索引）：
| lws_fts_open(filepath) | 打开现有索引文件，返回 struct lws_fts_file *，失败返回 NULL |
| lws_fts_search(jtf, ¶ms) | 执行搜索，结果分配在 params.results_head 指向的 lwsac 中 |
| lws_fts_close(jtf) | 关闭索引文件并释放相关分配 |
查询标志（params.flags 组合）：
#define LWSFTS_F_QUERY_AUTOCOMPLETE (1 << 0) // 返回自动补全建议
#define LWSFTS_F_QUERY_FILES (1 << 1) // 返回命中文件列表
#define LWSFTS_F_QUERY_FILE_LINES (1 << 2) // 每个文件附带行号+行起始偏移
#define LWSFTS_F_QUERY_QUOTE_LINE (1 << 3) // 额外附带命中行原文（最多255字符）
struct lws_fts_search_params 关键成员：needle（检索词）、only_filepath（限定单文件检索）、flags、max_autocomplete、max_files、max_lines（每个文件最多返回多少行结果）。
三种结果形态与示例的对应关系：自动补全（/a/）、文件列表（/r/ 的 fp 段）、文件+行号+原文（/r/ 的 hits 段）。调用前应将 params 整体 memset 为 0，避免后续版本新增成员包含未知值。
索引原理：内存 trie 与磁盘序列化
lws FTS 的整体设计在 third_party/libwebsockets/lib/misc/fts/README.md 中有完整说明，实现代码位于 lib/misc/fts/trie.c 与 lib/misc/fts/trie-fd.c。核心思路：
- 扫描一个或多个 UTF-8 文本"文件"（可以是纯内存数据），为每个 token 构建内存优化的 trie（前缀树）；
- 无论输入文件多少、体量多大，最终序列化为单一索引文件；
- 搜索时只需读入结果内存，通过在磁盘索引文件中快速 seek 完成检索与自动补全，对弱性能设备（带随机访问存储）友好。
内存中的 trie 节点包含大量额外指针与大类型字段，而序列化后的文件大量采用 VLI（变长整数） 编码按值大小伸缩占字节，因此大语料的峰值内存占用远高于最终索引文件体积。序列化完成后，查询成本极低：子节点按字符排序可提前判定"无匹配"；根 trie 额外附带 256 项指针表实现一步定位（该表约 2KiB，过大故仅根节点使用）。
文档还给出了同条件下的实测参考数据（来自 libwebsockets 项目文档，非本仓库评测）：索引 Linux 4.14 内核源码默认文件列表时，52932 个文件、694MiB 语料，索引耗时约 50.1s（约 13.8MB/s），峰值分配约 78MiB，序列化耗时约 202ms，trie 文件约 347MiB；索引 libwebsockets 自身 main 分支（489 文件、3MiB）时，索引耗时约 123ms，峰值约 3MiB，trie 文件约 1.4MiB。
磁盘索引文件格式
lws-fts.index 遵循固定布局（详见 lib/misc/fts/README.md 的 "Structure on disk" 一节）：
除少数需事后回填的数字外，全部使用 VLI 编码，多字节数字按网络字节序（MSB first）。VLI 规则：字节最高位为 EON 标志，0 表示数据结束、低 7 位即数值；1 表示后续字节为更高位。例如 0x30 = 48、0x81 0x30 = 176、0x81 0x80 0x00 = 16384。由于行号通常小于 16K（2 字节即可表示），这种编码对行号类小数值极其紧凑。
本示例在仓库中的定位
libwebsockets 以 submodule/third_party 形式随本仓库提供（见 third_party/BUILD.gn 等构建入口），本示例属于其 minimal-examples 中的 http-server 演示集合，是 FTS 功能的官方最小可运行展示。它的价值在于：完整的构建配置、预生成的 lws-fts.index、可离线运行的语料与前端，让开发者无需任何额外数据即可体验并理解 libwebsockets 全文搜索的完整工作链路。从 plugins/protocol_fulltext_demo.c 头部注释可以看出，该插件以 Public Domain（CC0）许可提供，明确"意在让你改编进自己的（可能专有的）代码"，是学习与复用的直接模板。
若要在自己的项目中复用，参考路径是：用 lws_fts_create/lws_fts_file_index/lws_fts_fill/lws_fts_serialize 建立索引文件，再在 HTTP 协议回调中用 lws_fts_open/lws_fts_search/lws_fts_close 响应搜索请求，最后用 lwsac_free 释放结果——这正是本示例用 200 余行 C 代码演示的完整闭环。
赞
【免费下载链接】ten-framework
Open-source framework for conversational voice AI agents
项目地址：
https://gitcode.com/TEN-framework/ten-framework
点击查看 免费下载
相关推荐
《经济研究》LaTeX模板终极指南：从零基础到学术达人的完美蜕变
3步搞定SD模型下载：告别慢速和复杂配置的终极方案
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
评论前必须登录！
注册