人工智能AI Agent多模态语音AI 应用【免费下载链接】ten-frameworkOpen-source framework for conversational voice AI agents项目地址https://gitcode.com/TEN-framework/ten-framework点击查看免费下载libwebsocketslws内置的lws_spaStateful Post Arguments解析器可以一站式处理application/x-www-form-urlencoded与multipart/form-data两种 POST 编码并原生支持流式文件上传。本仓库中的 minimal-http-server-form-post-file 示例完整演示了这一能力它运行一个仅约 260 行 C 代码的最小 HTTP 服务器接收带普通文本字段与文件字段的 multipart 表单把上传文件落盘到当前工作目录将表单字段打印到控制台日志然后用 301 重定向把浏览器带往一个静态感谢页。读完本文你将掌握 lws HTTP 回调的四个关键阶段URL 校验、BODY 解析、BODY 完成、资源释放、lws_spa解析器的创建/喂数据/收尾/销毁全流程以及基于lws_http_mount的静态资源挂载方式可直接照搬到自己的 lws 服务端项目中。一、示例概览与目录结构该示例位于仓库third_party/libwebsockets/minimal-examples/http-server/下属于 libwebsockets 官方 minimal-examples 集合中的 http-server 系列其核心文件如下文件作用minimal-http-server-form-post-file.c主程序HTTP 回调、spa 解析器、文件落盘、重定向逻辑CMakeLists.txt构建脚本校验LWS_ROLE_H1与LWS_WITH_SERVER两个编译选项mount-origin/index.html首页静态表单页表单以multipart/form-data编码 POST 到/form1mount-origin/after-form1.html提交成功后重定向到达的静态感谢页mount-origin/404.html未挂载 URL 的默认 404 页其中mount-origin/目录就是上面lws_http_mount结构中.origin ./mount-origin所指向的静态资源根目录。二、构建与运行2.1 构建示例自带的 CMakeLists.txt 通过find_package(libwebsockets CONFIG REQUIRED)查找已安装的 lws 库并通过require_lws_config(LWS_ROLE_H1 ...)与require_lws_config(LWS_WITH_SERVER ...)在构建期校验当前 lws 是否启用了 HTTP/1.x 角色与服务端功能——若库未启用这两个选项则示例不参与编译。构建命令与原文档一致$ cmake . make编译产物为可执行文件lws-minimal-http-server-form-post-file。2.2 运行与预期输出$ ./lws-minimal-http-server-form-post-file [2018/03/29 09:58:30:8800] USER: LWS minimal http server POST file | visit http://localhost:7681 [2018/03/29 09:58:30:8800] NOTICE: Creating Vhost default port 7681, 1 protocols, IPv6 off [2018/03/29 09:58:45:3284] USER: file_upload_cb: upload done, written 2729 to wss-over-h2.png [2018/03/29 09:58:45:3284] USER: text1: (len 3) xxx [2018/03/29 09:58:45:3284] USER: send: (len 6) Submit日志解读前两行是服务启动信息监听localhost:7681创建一个名为default的 Vhost注册 1 个协议即protocols数组中的httpIPv6 关闭第三行来自file_upload_cb回调一个名为wss-over-h2.png的文件上传完成共写入 2729 字节到当前工作目录后两行是表单普通字段的解析结果text1字段长度为 3内容xxxsend字段长度为 6内容Submit即提交按钮的 value。2.3 使用方式访问 http://localhost:7681页面为mount-origin/index.html渲染出的静态表单。表单包含一个文本输入框text1、一个文件选择框file和一个提交按钮send。选择文件并点击 Submit 后文件被 multipart 编码上传服务端接收并保存在当前工作目录即运行服务时所在的 cwd文件名沿用客户端提供的原始文件名表单参数text1、send被解码后打印到服务端控制台日志浏览器被 301 重定向到after-form1.html静态页面。三、前端表单multipart/form-data 的入口mount-origin/index.html中的表单定义如下节选form namemultipart action/form1 methodpost enctypemultipart/form-data Type some text:br input typetext nametext1br Select a file to upload: input typefile namefile idfile size20nbsp; input typesubmit namesend valueSubmit /form三个关键点值得注意enctypemultipart/form-data是文件上传的必要条件它让浏览器以 MIME multipart 分块编码请求体而不是普通 URL 编码action/form1指定了提交目标 URL。服务端在LWS_CALLBACK_HTTP回调中专门放行了该 URL否则未挂载的 URL 会走默认 404 逻辑提交按钮的namesend与valueSubmit会作为一个普通表单字段随 POST 一并提交这也解释了日志中send: (len 6) Submit的来源。mount-origin/after-form1.html则是提交成功后的落点页面正文仅提示The file you uploaded should have been saved in the current directory配合服务端日志可确认整个流程闭环。四、核心源码剖析spa 解析器与文件落盘主程序 minimal-http-server-form-post-file.c 围绕struct pssper-session data与四个 HTTP 回调阶段组织逻辑。4.1 会话数据结构struct pss { struct lws_spa *spa; /* lws helper decodes multipart form */ char filename[128]; /* the filename of the uploaded file */ unsigned long long file_length; /* the amount of bytes uploaded */ int fd; /* fd on file being saved */ };源码注释强调了一个重要概念HTTP 是无状态协议这个pss只存在于单次 HTTP 事务期间在 HTTP/1.1 keep-alive 与 HTTP/2 场景下它的生命周期短于底层网络连接。也就是说每次表单提交都会产生一个独立的pss互不干扰。4.2 声明要解析的字段名static const char * const param_names[] { text1, send, }; enum enum_param_names { EPN_TEXT1, EPN_SEND, };字段名数组必须与表单name一一对应枚举值则用于后续按序索引取值。spa 解析器只关心这些具名参数其他字段如文件字段file不占用参数存储空间而是走文件上传回调。4.3 文件上传回调file_upload_cb该回调的类型即 lws-spa.h 中定义的lws_spa_fileupload_cb原型为int (*lws_spa_fileupload_cb)(void *data, const char *name, const char *filename, char *buf, int len, enum lws_spa_fileupload_states state);回调会随解析进度被调用多次state指示当前事件类型。enum lws_spa_fileupload_states共四个状态见 lws-spa.h状态含义LWS_UFS_OPEN一个新文件开始到达LWS_UFS_CONTENT到达一段文件内容非最后一段LWS_UFS_FINAL_CONTENT文件内容的最后一段到达长度可能为 0LWS_UFS_CLOSE文件解码相关资源即将被销毁示例回调的对应处理逻辑如下LWS_UFS_OPEN用lws_strncpy复制客户端传来的文件名随后调用lws_filename_purify_inplace净化文件名再用lws_open(filename, O_CREAT | O_TRUNC | O_RDWR, 0600)以创建/截断/读写模式打开文件权限 0600。打开失败则返回 1 表示出错。LWS_UFS_CONTENT/LWS_UFS_FINAL_CONTENT累加pss-file_length把buf中len字节直接write进文件描述符若写入字节数小于len说明磁盘写入异常。当状态为LWS_UFS_CONTENT时表示后面还有分片直接跳出到达LWS_UFS_FINAL_CONTENT时才打印upload done, written %lld to %s并close文件、将fd置为 -1。LWS_UFS_CLOSE示例中为空操作。由于 spa 是有状态解析器请求体可能跨越多次LWS_CALLBACK_HTTP_BODY回调到达且上传文件大小没有上限数据边到达边写盘不缓存整个文件于内存。4.4 文件名净化lws_filename_purify_inplace文件名直接来自客户端 HTTP 请求是不可信输入。libwebsockets 在 lib/core/libwebsockets.c 中实现了lws_filename_purify_inplacevoid lws_filename_purify_inplace(char *filename) { while (*filename) { if (*filename . filename[1] .) { *filename _; filename[1] _; } if (*filename : || #if !defined(WIN32) *filename \\ || #endif *filename $ || *filename %) *filename _; filename; } }该函数把..、:、\非 Windows 平台、$、%等危险字符就地替换为下划线从而阻止路径穿越../与注入类文件名。任何实现文件上传的服务端都必须做类似的净化这是本示例给出的安全基线lws-purify.h 中对它的定位正是replace scary filename chars with underscore。4.5 HTTP 回调callback_http的四个阶段主回调callback_http通过enum lws_callback_reasons区分事件示例实际处理了以下四个1.LWS_CALLBACK_HTTP校验 URLif (!strcmp((const char *)in, /form1)) /* assertively allow it to exist in the URL space */ return 0; /* default to 404-ing the URL if not mounted */ break;in携带请求 URL。示例对/form1直接返回 0 放行其余 URL 走默认 404。源码注释还给出另一种做法在协议挂载mount中把表单 URL 以LWSMPRO_CALLBACK类型挂载就不需要在此手动放行。2.LWS_CALLBACK_HTTP_BODY创建解析器并喂数据if (!pss-spa) { pss-spa lws_spa_create(wsi, param_names, LWS_ARRAY_SIZE(param_names), 1024, file_upload_cb, pss); if (!pss-spa) return -1; } if (lws_spa_process(pss-spa, in, (int)len)) return -1;首次进入时用lws_spa_create创建解析器参数分别为连接、字段名数组、字段数、参数值存储上限 1024 字节、文件上传回调、回调私有数据之后把每次到达的 body 分块交给lws_spa_process增量解析。lws_spa_create的完整签名见 lws-spa.hstruct lws_spa * lws_spa_create(struct lws *wsi, const char * const *param_names, int count_params, int max_storage, lws_spa_fileupload_cb opt_cb, void *opt_data);max_storage是所有普通参数值的总存储上限示例为 1024 字节文件内容不占用该预算。头文件中还说明opt_cb可以为 NULL纯namevalue解析场景回调在致命错误时应返回 -1、正常返回 0。同一组 API 对 urlencoded 与 multipart 两种表单编码通用且推荐的新式创建入口是lws_spa_create_via_info通过lws_spa_create_info结构体传参见 lws-spa.h。3.LWS_CALLBACK_HTTP_BODY_COMPLETION收尾、输出、重定向lws_spa_finalize(pss-spa); for (n 0; n (int)LWS_ARRAY_SIZE(param_names); n) { if (!lws_spa_get_string(pss-spa, n)) lwsl_user(%s: undefined\n, param_names[n]); else lwsl_user(%s: (len %d) %s\n, param_names[n], lws_spa_get_length(pss-spa, n), lws_spa_get_string(pss-spa, n)); } if (lws_http_redirect(wsi, HTTP_STATUS_MOVED_PERMANENTLY, (unsigned char *)after-form1.html, 16, p, end) 0) return -1;lws_spa_finalize通知解析器没有更多 payload随后通过lws_spa_get_string/lws_spa_get_length按字段序号取出解码后的值与长度并打日志。最后用lws_http_redirect发送HTTP_STATUS_MOVED_PERMANENTLY即 301重定向到after-form1.html。该 API 的声明见 lws-http.h参数依次为连接、状态码、重定向目标、目标长度、缓冲区当前位置指针会被更新与缓冲区末尾指针返回写入量负值表示致命写入失败。4.LWS_CALLBACK_HTTP_DROP_PROTOCOL资源回收if (pss-spa) { lws_spa_destroy(pss-spa); pss-spa NULL; }该回调在 wsi 的 user_space 即将销毁时触发示例在此显式调用lws_spa_destroy释放解析器文件描述符已在上传完成时关闭。如果文件上传中途发生错误导致文件未关闭通常也应在此阶段兜底关闭。4.6 协议与静态资源挂载static struct lws_protocols protocols[] { { http, callback_http, sizeof(struct pss), 0, 0, NULL, 0 }, LWS_PROTOCOL_LIST_TERM };协议名为httpuser space 大小为sizeof(struct pss)。而静态资源通过lws_http_mount结构挂载static const struct lws_http_mount mount { .mountpoint /, .origin ./mount-origin, .def index.html, .origin_protocol LWSMPRO_FILE, .mountpoint_len 1, ... };含义为URL 空间根/映射到本地目录./mount-origin默认文档为index.html来源类型LWSMPRO_FILE表示从目录提供静态文件。因此/返回表单页/after-form1.html与/404.html同样来自该目录。在main中通过info.mounts mount挂上同时设置端口 7681 与选项LWS_SERVER_OPTION_HTTP_HEADERS_SECURITY_BEST_PRACTICES_ENFORCE强制启用 HTTP 安全响应头最佳实践。五、主循环与生命周期info.port 7681; info.protocols protocols; info.mounts mount; info.options LWS_SERVER_OPTION_HTTP_HEADERS_SECURITY_BEST_PRACTICES_ENFORCE; context lws_create_context(info); ... while (n 0 !interrupted) n lws_service(context, 0); lws_context_destroy(context);lws_context_creation_info以memset清零防止未初始化垃圾值SIGINT信号将interrupted置 1使lws_service主循环退出最后销毁 context 完成优雅关闭。日志级别默认为LLL_USER | LLL_ERR | LLL_WARN | LLL_NOTICE也可用-d n命令行参数覆盖源码通过lws_cmdline_option(argc, argv, -d)解析。代码注释还提示只有以-DCMAKE_BUILD_TYPEDEBUG构建 lwsLLL_INFO及更细的解析/头/调试日志才可用。六、可复用的工程要点流式落盘lws_spa分块回调意味着大文件上传几乎不占内存write到 fd 即可file_length以unsigned long long累加可支持超大文件计数。安全基线客户端文件名必须经过lws_filename_purify_inplace净化再用于lws_open防止路径穿越lws-purify.h 与 libwebsockets.c 给出了实现细节。生命周期管理解析器在LWS_CALLBACK_HTTP_BODY中惰性创建在LWS_CALLBACK_HTTP_DROP_PROTOCOL中销毁避免跨 HTTP 事务泄漏。错误处理spa 创建失败、lws_spa_process解析出错、写盘字节数不足、重定向失败均返回非 0 或 -1 终止该事务。构建期校验通过require_lws_config检查LWS_ROLE_H1与LWS_WITH_SERVER保证示例只在具备 HTTP 服务端能力的 lws 构建下编译。需要留意的是该示例依赖 libwebsockets 的完整构建产物find_package(libwebsockets CONFIG REQUIRED)在本仓库中 libwebsockets 位于 third_party/libwebsockets其顶层 BUILD.gn 在ten_enable_libwebsockets开启时作为 GN 目标参与构建。若要在本地验证示例需先以 CMake 方式构建并安装 libwebsockets 库再进入示例目录执行cmake . make并运行./lws-minimal-http-server-form-post-file。由于构建依赖当前环境的 cmake、make 与编译器工具链请在具备这些工具的环境中操作。赞分享人工智能AI Agent多模态语音AI 应用【免费下载链接】ten-frameworkOpen-source framework for conversational voice AI agents项目地址https://gitcode.com/TEN-framework/ten-framework点击查看免费下载相关推荐TypeSpec 文件型 multipart 上传实战基于 http-client-js 的 HttpPart\File\ 场景深度解析TypeSpec 文件型 multipart 上传实战基于 http client js 的 HttpPart\File\ 场景深度解析 TypeSpec编程语言编译器后端Hindsight 记忆层实践让 AI Agent 跨会话保持一致性的 Retain 与 Recall 机制Hindsight 记忆层实践让 AI Agent 跨会话保持一致性的 Retain 与 Recall 机制 AI Agent 的一致性问题——同一个用户后端GraphQL代码生成Ventoy 混合 ISO 快速指南一次生成 UEFI/BIOS 双启动的多系统启动镜像Ventoy 混合 ISO 快速指南一次生成 UEFI/BIOS 双启动的多系统启动镜像 Ventoy 能把 UEFI 引导与 BIOS 引导打包进同一个 I操作系统固件开发工具上一篇告别激活烦恼KMS_VL_ALL_AIO智能激活方案的完整指南下一篇如何快速掌握微信自动化提升工作效率的完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考