libwebsockets 全文搜索实战:minimal-http-server-fulltext-search 示例深度解析
libwebsockets 全文搜索实战:minimal-http-server-fulltext-search 示例深度解析
本文以 libwebsockets 仓库中的 minimal-http-server-fulltext-search 示例为主线,完整讲解如何在 lws HTTP 服务器上落地一套"输入即补全、点选即检索"的全文搜索服务:从构建运行、URL 挂载与协议插件组装,到底层 lws FTS 全文索引库的索引创建、查询 API 与磁盘文件格式。读完本文,你将掌握把任意文本语料(甚至仅存在于内存中的虚拟文件)转成单文件索引、并对外提供毫秒级 autocomplete 与行级命中查询的完整技术方案。
一、示例概览:它到底做了什么
该示例是一个极简的 lws HTTP 服务器(lws-minimal-http-server),它把王尔德《道林·格雷的画像》全文(the-picture-of-dorian-gray.txt)预先建立成磁盘索引 lws-fts.index,然后在浏览器里提供一个搜索框:用户输入时实时返回补全建议,回车后展示命中文件、命中行号与行内容引用。示例目录结构如下:
minimal-http-server-fulltext-search/
├── CMakeLists.txt # 构建脚本,声明 LWS_WITH_FTS 依赖
├── README.md # 示例说明
├── minimal-http-server.c # 服务器主程序
├── lws-fts.index # 预生成的全文索引文件(约 325KiB)
├── the-picture-of-dorian-gray.txt # 被索引的语料
└── mount-origin/ # 静态 Web 资源(页面、CSS、JS)
├── index.html
├── lws-fts.js
├── lws-fts.css
└── ...
服务器端只做两件事:把静态页面目录挂载在 /,把全文搜索回调协议挂载在 /fts;前端通过 XHR 请求 ../fts/a/<词> 与 ../fts/r/<词> 分别获取补全建议和检索结果。
二、构建与运行
2.1 构建
示例的 CMakeLists.txt 通过 require_lws_config 声明了三项硬性依赖,缺一不可:
require_lws_config(LWS_ROLE_H1 1 requirements)
require_lws_config(LWS_WITH_FTS 1 requirements)
require_lws_config(LWS_WITH_SERVER 1 requirements)
其中 LWS_WITH_FTS 是全文搜索功能的总开关,在主 CMakeLists.txt 中默认值为 OFF(option(LWS_WITH_FTS "Full Text Search support" OFF)),因此编译 libwebsockets 时必须显式开启:
# 1) 先以开启 LWS_WITH_FTS 的方式构建并安装 libwebsockets 库
$ cmake .. -DLWS_WITH_FTS=1
$ make && sudo make install
# 2) 再构建本示例
$ cd minimal-examples-lowlevel/http-server/minimal-http-server-fulltext-search
$ cmake . && make
按原文档给出的命令执行 cmake . && make 即可完成示例自身的构建;由于示例通过 #include "../../../plugins/protocol_fulltext_demo/protocol_fulltext_demo.c" 以 LWS_PLUGIN_STATIC 方式把搜索协议插件静态编入,无需额外安装插件。
2.2 运行
$ ./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,即可看到《道林·格雷的画像》全文搜索页面。
2.3 命令行参数
主程序 minimal-http-server.c 通过 lws_cmdline_option 支持三个开关:
| 开关 | 含义 | 默认值 |
|---|---|---|
-d |
调试日志级别(如 -d 15) |
由编译配置决定 |
--port |
监听端口,须在 1~65535 之间,越界会报错退出 | 7681 |
--help |
打印帮助信息 | — |
代码中对端口做了显式校验:if (pt <= 0 || pt > 65535) 时输出错误并返回 1。此外上下文创建时设置了 info.port = 7681、info.fd_limit_per_thread = 0(服务端按进程 fd 上限扩充表),并开启了 LWS_SERVER_OPTION_HTTP_HEADERS_SECURITY_BEST_PRACTICES_ENFORCE 安全响应头策略,因此页面上的 strict-csp.svg 徽标正是该安全策略生效的标识。
三、服务器端是如何拼装出来的
3.1 两层 URL 挂载
lws-http-mount 结构 构成了挂载点链表,这是理解整个示例路由的关键:
/* /fts 挂到回调协议上,动态生成 JSON */
static const struct lws_http_mount mount_fts = {
.mountpoint = "/fts",
.protocol = "lws-test-fts",
.origin_protocol = LWSMPRO_CALLBACK, /* 动态回调 */
.mountpoint_len = 4,
};
/* / 挂到磁盘目录上,默认文件 index.html */
static const struct lws_http_mount mount = {
.mount_next = &mount_fts, /* 链表下一项 */
.mountpoint = "/",
.origin = "./mount-origin",
.def = "index.html",
.origin_protocol = LWSMPRO_FILE, /* 静态文件 */
.mountpoint_len = 1,
};
即:/ 走静态文件协议(LWSMPRO_FILE),从 ./mount-origin 目录取文件;/fts 走回调协议(LWSMPRO_CALLBACK),请求被派发给名为 lws-test-fts 的协议处理函数。把搜索协议"伪装"成一个 URL 子目录,是 lws 挂载机制的典型玩法。
3.2 通过 PVO 注入索引路径
协议插件并不知道索引文件放在哪,索引路径通过 lws 的协议 vhost 选项(PVO)注入:
static struct lws_protocol_vhost_options pvo_idx = {
NULL, NULL,
"indexpath", /* pvo 名字 */
NULL /* 运行时填入值 */
};
static const struct lws_protocol_vhost_options pvo = {
NULL, &pvo_idx, /* child 链表 */
"lws-test-fts", /* 该 PVO 归属的协议名 */
""
};
主函数中 pvo_idx.value = index_filepath;(即 "./lws-fts.index")在运行时被填入。协议插件侧在 LWS_CALLBACK_PROTOCOL_INIT 回调里用 lws_pvo_get_str(in, "indexpath", &vhd->indexpath) 取出该值;若某 vhost 没有配置 indexpath,插件会直接返回 1 拒绝初始化,并打印 "%s: indexpath pvo required" 错误(见 protocol_fulltext_demo.c)。这种"协议可插拔、配置靠 PVO"的机制让同一个插件可以服务于多份索引。
四、协议插件:/a/ 与 /r/ 两种查询
插件回调 callback_fts 在 LWS_CALLBACK_HTTP 阶段解析 URL,约定以第一个路径段选择任务:
| URL 前缀 | 含义 | 使用的查询标志 |
|---|---|---|
/fts/a/<词> |
autocomplete 补全建议 | LWSFTS_F_QUERY_AUTOCOMPLETE |
/fts/r/<词> |
检索结果(文件 + 行级命中) | LWSFTS_F_QUERY_FILES | LWSFTS_F_QUERY_FILE_LINES | LWSFTS_F_QUERY_QUOTE_LINE |
插件设置的查询参数为:max_autocomplete = 10、max_files = 10、max_lines = 128,即补全建议最多 10 条、命中的文件最多 10 个、每个文件的行命中最多 128 条。核心调用链如下:
jtf = lws_fts_open(vhd->indexpath); /* 打开磁盘索引 */
result = lws_fts_search(jtf, ¶ms); /* 执行搜索,结果放进 lwsac */
lws_fts_close(jtf);
如果 lws_fts_open 失败(例如索引文件不存在),插件并不 404,而是照样返回 200,并在 JSON 中以 "indexed": 0 告知前端"没有可用索引"——前端据此进入"正在建索引/无索引"的提示分支。
4.1 JSON 响应结构
搜索结构挂在 LWS_CALLBACK_HTTP_WRITEABLE 上分块写回(输出缓冲 buf[LWS_PRE + 2048],每块之间预留 FTS_RECORD_HEADROOM 384 字节余量防止 lws_snprintf 溢出)。最终 JSON 形如:
{
"indexed": 1,
"ac": [
{"ac": "be", "matches": 472, "agg": 472, "elided": 0},
{"ac": "been", "matches": 236, "agg": 236, "elided": 0}
],
"fp": [
{
"path": "the-picture-of-dorian-gray.txt",
"matches": 12,
"origlines": 4164,
"hits": [
{"l": 12, "o": 501, "s": "he has a simple and beautiful nature..."},
{"l": 47, "o": 2340, "s": "his beauty was marred..."}
]
}
]
}
字段含义:ac[].matches 是该补全词的直接命中数,agg 是沿该词后缀路径聚合的命中总数;fp[].hits[].l 为命中行号,o 为命中行在原始文件中的字节偏移,s 为行内容引用(LWSFTS_F_QUERY_QUOTE_LINE 开启时才有)。所有字符串经 lws_json_purify 转义后写入,避免注入 HTML/JSON。
4.2 分块写回与收尾
插件用 LWS_WRITE_HTTP 多次分块发送中间数据,全部遍历完后发送 LWS_WRITE_HTTP_FINAL 并调用 lws_http_transaction_completed 结束事务;结果 lwsac 在 LWS_CALLBACK_CLOSED_HTTP 或写完后通过 lwsac_free(&pss->result) 释放。这种"边遍历边写、按缓冲余量节流"的写法,保证了即使命中结果非常多,也不会一次性撑爆输出缓冲。
五、前端页面如何驱动搜索
页面 index.html 只含一个输入框 #lws_fts、一个补全弹出层 #acomplete 和一个结果区 #searchresults。lws-fts.js 实现了两条 XHR 链路:
- 输入事件(
lws_fts_search_input):每次输入向../fts/a/<当前词>发请求,把返回的补全建议渲染成<li>下拉菜单,点击(lws_fts_ac_select)后把建议词回填输入框并直接触发检索;若返回"indexed": 0则提示无索引,若返回值不是 0/1 则视为"正在建索引",显示进度条并 300ms 后重试。 - 回车/选择事件(
lws_fts_choose):向../fts/r/<词>发请求,遍历jj.fp[]渲染每个命中的文件路径与hits[]中的行号、行内容表格。
JS 全程用 document.createTextNode 与 HTML 转义处理返回文本,配合 cache-control: max-age=0 保证每次查询都命中最新索引状态。整个页面无需任何前端框架,是理解"lws 协议回调 + 原生 XHR"组合的绝佳样例。
六、底层全文索引库:lws FTS
示例只是冰山一角,其背后的 lib/misc/fts 子系统才是全文搜索的核心实现,公开 API 声明在 include/libwebsockets/lws-fts.h,实现在 trie.c(建索引)与 trie-fd.c(查询)。
6.1 总体思路
扫描一个或多个 UTF-8 文本"文件"(可以是内存中的虚拟文件),为每个 token 在内存中构建一棵优化过的 trie(字典树);全部语料索引完毕后,把整棵 trie 序列化为单个磁盘索引文件——无论输入文件多少、多大,最终都只有一个索引文件。设计目标是对内存与 CPU 都足够克制,能跑在存储为随机访问的弱设备上;查询时只需加载结果所需的内存,实际搜索与补全通过索引文件内的 seek 快速完成。
6.2 索引创建 API 调用链
索引创建是典型的四步流水线,调用顺序不可乱:
| API | 作用 |
|---|---|
lws_fts_create(fd) |
初始化新索引文件,返回 struct lws_fts * |
lws_fts_file_index(t, filepath, len, priority) |
登记一个输入文件路径,返回其序号(file_index) |
lws_fts_fill(t, file_index, buf, len) |
按缓冲块喂入文件内容;同一 file_index 必须连续喂完再喂下一个 |
lws_fts_serialize(t) |
把内存 trie 落盘 |
lws_fts_destroy(&t) |
收尾并释放内存,*t 置 NULL |
api-test-fts/main.c 中的 index_one_file() 展示了标准用法:lws_fts_file_index 拿到序号后,循环 read() + lws_fts_fill() 直到文件读完。priority 参数当前尚未使用(源码注释 "not used yet")。
6.3 搜索 API 与三种结果类型
struct lws_fts_search_params {
const char *needle; /* 检索词 */
const char *only_filepath; /* 只查某文件 */
struct lwsac *results_head; /* 结果 lwsac */
int flags; /* LWSFTS_F_QUERY_* 组合 */
int max_autocomplete; /* 补全建议上限 */
int max_files; /* 文件结果上限,0=不限 */
int max_lines; /* 每个文件行命中上限,0=不限 */
};
struct lws_fts_result *lws_fts_search(struct lws_fts_file *jtf,
struct lws_fts_search_params *ftsp);
调用前应 memset 参数结构;results_head 指向结果 lwsac,用完以 lwsac_free() 释放。一次搜索最多同时产出三类结果:
- Autocomplete 建议:随用户输入实时给出"以该前缀开头"的现存词,例如输入
len,会同时报出len自身、length以及索引中所有以len开头的词,并按聚合命中数排序("最可能"的排前面)。由LWSFTS_F_QUERY_AUTOCOMPLETE开启,链表头为result.autocomplete_head,元素类型struct lws_fts_result_autocomplete。 - 文件路径结果:列出包含检索词的文件及统计信息,便于做"下钻到具体文件"的选择 UI。由
LWSFTS_F_QUERY_FILES开启,链表头result.filepath_head,元素类型struct lws_fts_result_filepath。 - 文件路径 + 行结果:在文件结果基础上,进一步给出每个命中行的行号与原始文件字节偏移;再加
LWSFTS_F_QUERY_QUOTE_LINE则附带该行最多 255 字符的引用文本。
四个标志位的定义(lws-fts.h):
#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)
6.4 结果在 lwsac 中的布局
结果 lwsac 的第一个对象是 struct lws_fts_result,内含两个链表头、duration_ms(查询耗时)、effective_flags(实际生效的标志)与 truncated(文件结果被 max_files 截断标记)。内存布局要点:
- 补全建议字符串紧跟在每个
struct lws_fts_result_autocomplete之后; - 文件路径结果在
struct lws_fts_result_filepath之后依次是匹配表与文件路径字符串,匹配表的字节数由matches_length给出,因此文件路径始终位于((char *)&fp[1]) + fp->matches_length; - 匹配表按固定步长(stride)存放:不传
LWSFTS_F_QUERY_FILE_LINES时每匹配 0 字节;传了则为uint32_t 行号 + uint32_t 行起始字节偏移(8 字节);再叠加LWSFTS_F_QUERY_QUOTE_LINE则追加一个const char *指向 lwsac 内的 NUL 结尾行引用。若原始文件已变更导致无法解析某条匹配,该记录仍存在但为 0/NULL,消费者必须容忍 NULL 引用指针。
注意:
LWSFTS_F_QUERY_QUOTE_LINE依赖原始文件内容仍在索引文件旁可读;若被索引的是虚拟文件(如某次 git 版本的内容)或原始文件未随索引保存,则无法使用该标志。
七、磁盘索引文件格式
索引文件显式的多字节数字一律采用网络字节序(MSB 优先),结构依次为:文件头 → 文件路径行号表 → 文件路径信息 → 文件路径映射表 → trie 及其实例表、子节点表。
7.1 VLI 变长整数编码
文件内除少数需要事后回填的头字段外,所有数字都用 VLI(Variable Length Integer)编码:
[b7 EON] [b6..b0 DATA]
EON = 0:DATA 即数值的最低 7 位,编码结束;EON = 1:DATA 是更高位的 7 位,需左移续接,直到遇到EON = 0的字节。
示例与容量范围:
| 编码 | 值 | 字节数 | 表示范围 |
|---|---|---|---|
0x30 |
48 | 1 | ≤ 127 |
0x81 30 |
176 | 2 | ≤ 16K-1 |
0x81 0x80 0x00 |
16384 | 3 | ≤ 2M-1 |
| — | — | 4 | ≤ 256M-1 |
| — | — | 5 | ≤ 4G-1 |
VLI 对小数值极其高效:比如行号绝大多数小于 16K,只需 2 字节;偶遇超大文件也能从容扩展。
7.2 文件头与各表段
文件头共 5 个 32 位字段(当前实现由 private-lib-misc-fts.h 的常量 TRIE_FILE_HDR_SIZE 定义为 20 字节;所有 fileoffset 均相对于文件偏移 0):
| 字段 | 含义 |
|---|---|
Magic 0xCA7A5F75 |
索引文件魔数 |
| Root trie 偏移 | 根 trie 项的文件偏移 |
| 创建时文件大小 | 用于检测文件被截断 |
| Filepath map 偏移 | 文件路径映射表的文件偏移 |
| 文件路径数量 | 索引内登记的文件数 |
用 od 检查示例自带的 lws-fts.index,前 20 字节正是 ca 7a 5f 75(魔数)、00 05 12 03(根偏移)、00 05 13 61(= 332641,与文件实际字节数完全一致)、00 03 01 e2(映射表偏移)、00 00 00 01(1 个文件路径),与格式定义逐一对上。
其余段落的要点:
- 行号表:按 200 行一块切块(
LWS_FTS_LINES_PER_CHUNK),每块有 8 字节头(16-bit 块自身长度、16-bit 覆盖行数、32-bit 覆盖的输入文件字节数)+ 每行一个 VLI 行长度;块头允许快速跳过无关 VLI 区段,最后以全零块标记该文件行号段结束。 - 文件路径表:每个路径依次为 VLI 行号表偏移、VLI 总行数、VLI 路径字节长度、路径串(无 NUL)。
- 文件路径映射表:每个文件路径一个 32 位偏移,用于把路径索引快速换算成路径信息。
- trie 项:头部为 VLI 实例表首项偏移、子节点数、实例数;随后是子节点表、每个文件的实例表(下一项偏移、路径索引、行号实例数)、升序排列的行号实例表。
从源码结构看,查询侧正是靠这些"排序 + 偏移"设计做到低开销:trie-fd.c 中定义 AC_COUNT_STASHED_CHILDREN 8 做自动补全的少量子节点缓存,LWS_FTS_MAX_MATCHES_PER_FILEPATH (1024 * 1024) 作为未设 max_lines 时的内部硬上限,防止损坏索引导致 32 位平台结果溢出。
八、查询为什么快:两处关键优化
原文档明确给出的两点查询优化,是 FTS 保持高速的核心:
- trie 子节点按字符升序排序:匹配过程中一旦遇到"比目标字符更靠后"的字符即可立即判定无匹配,提前终止;
- 根 trie 附带 256 项指针表:让根节点的查找一步到位;但该表本身约 2KiB,成本过高,因此只给根 trie 使用,普通节点仍走链表。
再加上结果以 lwsac 连续分配、匹配表定步长可随机索引、索引文件直接 seek 定位,使"全库搜索 + 自动补全"都不需要把索引整体载入内存。
九、用 api-test-fts 验证与自测
命令行测试程序 api-test-fts 是与本示例配套的 CI/自测工具,支持三种模式:
| 选项 | 含义 |
|---|---|
-c / --createindex |
创建索引而非搜索 |
-i / --index <file> |
指定索引文件路径 |
-f / --file |
报告包含检索词的文件路径 |
-l / --lines |
报告每个命中的行号与文件偏移 |
-s / --selftest |
建索引并逐条核对结果(ctest 运行的模式) |
-d <loglevel> |
调试日志级别(如 -d15) |
创建索引:
$ ./lws-api-test-fts -c ./the-picture-of-dorian-gray.txt
[2018/10/15 07:14:15:1531] NOTICE: lws_fts_serialize: index 1 files (0MiB)
cpu time 32ms, alloc: 1024KiB + 1024KiB, serialize: 3ms, file: 325KiB
搜索并打印补全建议:
$ ./lws-api-test-fts b
[2018/10/15 07:15:44:1442] NOTICE: lws_fts_search: 'b' Matched: 3 instances, 8 children, 0ms
[2018/10/15 07:15:44:1443] NOTICE: lws_fts_results_dump: AC b: 3 agg hits
[2018/10/15 07:15:44:1443] NOTICE: lws_fts_results_dump: AC be: 472 agg hits
[2018/10/15 07:15:44:1443] NOTICE: lws_fts_results_dump: AC bee: 3 agg hits
[2018/10/15 07:15:44:1443] NOTICE: lws_fts_results_dump: AC before: 75 agg hits
...
自测(ctest 使用):
$ ./lws-api-test-fts --selftest --index /tmp/test.index \
./the-picture-of-dorian-gray.txt ./les-mis-utf8.txt
[2026/09/08 18:49:59:3976] N: lws_fts_serialize: index 3 files (1MiB) ...
[2026/09/08 18:49:59:4275] U: Completed: PASS
自测模式会额外生成一个纯 LF 换行的语料(main.c 中 selftest_make_lf_corpus(),因为两个自带语料是 CRLF,token 由 CR 终止,需要 LF 用例覆盖行尾 token 归行场景),然后用 "the" 检索,把每一条匹配记录与原始文件逐一核对:行号必须存在、报告的偏移必须是该行真实起始位置、引用的行必须真的包含检索词。这正是防止"行号表错位、行号差一、匹配记录错位"等回归的守卫测试。
十、性能参考
原文档给出了同一环境(2.8GHz AMD Threadripper,单线程)下的两组实测数据,可作选型参考(数据来自该文档,非本文编造):
| 指标 | Linux 内核 4.14 | libwebsockets 主分支 |
|---|---|---|
| 索引文件数 | 52932 | 489 |
| 语料大小 | 694MiB | 3MiB |
| 建索引 CPU 时间 | 50.1s(>1000 文件/秒;13.8MB/s) | 123ms |
| 峰值内存 | 78MiB | 3MiB |
| 序列化时间 | 202ms | 1ms |
| 索引文件大小 | 347MiB | 1.4MiB |
需要说明的是:内存 trie 由于携带大量链表指针、且多数值以大字宽存储,其峰值内存往往远大于最终序列化文件体积;而一旦索引落盘,查询侧仅需少量内存即可极速完成。本示例的 lws-fts.index(约 325KiB)对 462KB 的《道林·格雷的画像》正文即属于典型的"小语料、小索引"场景。
十一、相关文件清单
- 示例主程序:minimal-http-server.c
- 搜索协议插件:protocol_fulltext_demo.c
- 前端页面与脚本:index.html、lws-fts.js
- 公开 API:include/libwebsockets/lws-fts.h
- 实现与格式说明:lib/misc/fts、trie.c、trie-fd.c
- 自测程序:api-test-fts/main.c
- 编译开关:主 CMakeLists.txt 的
LWS_WITH_FTS
从"示例跑起来"到"原理看得懂",本文覆盖了 libwebsockets 全文搜索的完整链路。若要把它搬进自己的项目,只需要照抄三层结构:静态挂载目录承载前端、回调协议承载 /fts 查询、预先用 lws_fts_create 系列 API 生成索引文件,再用 PVO 把索引路径注入插件即可。