libwebsockets 全文搜索（FTS）HTTP 服务器实战：构建与剖析 minimal-http-server-fulltext-search-开发者社区

人工智能
AI Agent
多模态
语音
AI 应用

【免费下载链接】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, &params); 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, &params)`	执行搜索，结果分配在`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" 一节）：

文件头（16 字节定长）：Magic0xCA7A5F75、根 trie 条目 fileoffset、创建时 trie 文件大小（用于检测截断）、filepath map 的 fileoffset、filepath 数量；
Filepath 行表：每文件按块记录各行字节长度，块头 8 字节（本块长度、覆盖行数、覆盖输入字节数），末尾全零块标记结束，支持快速跳跃定位逻辑行号；
Filepaths：每个文件一条记录（行表起始偏移、总行数、文件名字节长度、文件名字符串）；
Filepath map：每文件一个 32-bit 偏移表，用于把文件序号快速转换为文件信息；
Trie 条目：条目头含"首实例文件表偏移、子条目数、实例数"三个 VLI，其后是该条目的文件实例表（下一实例文件偏移、filepath 序号、行号实例数）、升序行号表、子表（子偏移、直接实例数、后代聚合实例数、后代聚合子数、匹配串长度、匹配串）。

除少数需事后回填的数字外，全部使用 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 代码演示的完整闭环。