CivetWeb

定义

CivetWeb 是一个以 C 语言实现的嵌入式 Web 服务器库，同时提供 C 与 C++ 两套编程接口。开发者的使用方式是把它编译进现有应用，从而为程序加上 HTTP 服务、HTTPS 服务和 WebSocket 通信能力；例如某类应用服务器可以借助它对外暴露用于自动化或远程控制的 Web 接口^[1]。

除作为库嵌入外，CivetWeb 也可以编译成独立可执行文件，作为普通 Web 服务器运行，用于提供静态文件，并内置服务端的 Lua、JavaScript 与 CGI 支持^[1]。Debian、Fedora、openSUSE 等发行版都把它收录为软件包，包描述为可选支持 CGI、SSL 和 Lua 的可嵌入 Web 服务器^[2][3]。

该项目的授权方式是 MIT 许可证。项目文档强调选择这一宽松许可证，是为了让使用者不受 GPL 一类著佐权许可证约束，可以自由地在商业产品中使用和修改代码^[4]。

原理

CivetWeb 采用为每条 HTTP 连接分配一个线程的模型。在内存充足的系统上它会使用默认线程栈大小，Windows 通常为 1 MB，Linux 最多可达 8 MB，每个线程各自占用一份；请求处理函数若发生阻塞，只会影响该连接，其余连接不受干扰，同时可处理的并发连接数受配置的线程总数限制^[5]。

嵌入使用时，程序引入 C 接口头文件 civetweb.h，调用 mg_start() 启动服务器，通过选项参数指定监听端口与文档根目录，再用回调函数挂接自定义逻辑，用 mg_set_request_handler() 注册请求处理函数，最后用 mg_stop() 停止服务^[5]。C++ 接口 CivetServer.h 只是对 C 接口的包装层，并不额外增加服务器功能，因此 C 接口中有些能力在 C++ 接口中并不存在^[1]。

功能裁剪在编译期完成。默认构建带有较合理的功能集合，需要额外能力时加入 USE_ 宏，去掉默认能力则使用 NO_ 宏，例如定义 USE_LUA 可启用 Lua 支持，定义 NO_CGI 则关闭 CGI 支持^[5]。为此，核心实现集中在单个源文件 civetweb.c 中，便于直接放入项目编译^[4]。

发展历程

CivetWeb 源自 Mongoose 项目。Mongoose 由 Sergey Lyubka 在 2004 年至 2013 年间以 MIT 许可证发布，2013 年 8 月 16 日 Mongoose 改用 GPL 第 2 版与商业授权并存的双重许可，CivetWeb 便是在这一许可变更之前、从最后一个 MIT 版本的 Mongoose 分叉出来的，由 Thomas Davis 创建，最初的定位是 Mongoose 的 MIT 分叉^[6]。

分叉之后，代码与文档中的 Mongoose 名称被改为 CivetWeb，并建立了独立的代码仓库与发布站点^[7]。自此 CivetWeb 与 Mongoose 各自独立演进，两边代码差异逐渐扩大，补丁已无法在两者之间安全地互相移植；项目文档明确要求不要照搬 Mongoose 的修复，以免引入 GPL 许可问题^[4]。

1.6 版本扩充了 Lua 支持，增加了 Windows 配置对话框、新示例和多项缺陷修复^[8]。1.13 版本加入 Lua 5.4 支持并弃用 Lua 5.1，同时引入对部分 HTTP/2 特性的实验性支持^[8]。1.14 版本将 SSL 的默认最低版本改为 TLS 1.2，允许以 mbedTLS 作为 OpenSSL 的替代^[9]。1.16 版本在使用 CMake 构建时默认启用 IPv6，修复了对 OpenSSL 3.0 的支持，新增对 Mbed TLS 3.0.0 的支持，并加入 HTTP 基本认证^[10]。

应用

CivetWeb 的典型用法是为不带网络功能的既有程序补上 Web 服务入口，常见于需要远程控制或自动化接口的场景^[1]。它支持 Windows、macOS、Linux、UNIX、iOS、Android、Buildroot 等多种平台，因此也被用在嵌入式与移动端环境中^[11]。

作为独立服务器运行时，它无需安装、以单个可执行文件的形式提供，可直接在 Windows 或 Linux 上启动^[2]。它内置 CGI、SSI、HTTP 摘要式（MD5）认证、WebSocket、WebDAV 等支持，HTTPS 借助 OpenSSL 实现，还可以作为 Windows 服务或 systemd 服务运行^[11]。可选功能包括基于客户端 X.509 证书的认证、断点续传下载、URL 重写、文件黑名单、基于 IP 的访问控制，以及按客户端子网或 URI 模式限制下载速度^[11]。

此外，CivetWeb 附带 HTTP 客户端能力，可以发送任意 HTTP 与 HTTPS 请求，也提供 WebSocket 客户端功能^[4]。Ceph 等项目曾在 2013 年底因 Mongoose 更换许可证而把所用组件从 Mongoose 换成 CivetWeb^[12]，CERN 的 ROOT 数据分析框架也在其 HTTP 模块中包含了 CivetWeb^[6]。

局限

CivetWeb 的功能取舍偏向简洁。项目自述其做法是在功能与简单之间保持平衡，选取的是一组经过取舍的特性，而非追求大而全的服务器功能^[4]。它的 HTTP/2 支持长期处于实验状态，官方说明该功能尚未达到可用于生产环境的程度^[7]。

并发模型也带来限制。由于每条连接占用一个线程，可同时处理的连接数受线程数上限约束，超出的请求只能排队等待；浏览器加载单个页面时往往会向同一服务器打开多条连接，因此线程数配置得过少（低于 5 至 10 个）就可能出现延迟^[5]。线程栈会按线程数乘以单线程栈大小预留虚拟地址空间，若某一线程栈用尽预留的地址空间，整个进程都会崩溃，所以资源紧张的嵌入式系统需要在栈大小与内存占用之间权衡^[5]。

WebDAV 支持存在已知缺陷。1.16 版本的说明指出，当客户端使用 Windows 资源管理器访问时，重命名或移动文件与文件夹有多种限制，其中在 Linux 上运行服务器并用 Windows 资源管理器连接时，非拉丁字符的文件名可能出问题^[10]。

C++ 接口的能力弱于 C 接口。由于 CivetServer.h 仅是对 C 接口的封装，C 接口提供的部分功能在 C++ 接口中并未暴露，使用 C++ 封装层的项目可能无法直接调用全部特性^[5]。

参见

• Mongoose —— CivetWeb 所分叉的原始项目，2013 年变更许可证后两者各自独立发展。

• MIT 许可证 —— CivetWeb 所采用的宽松开源许可证。

• HTTP —— CivetWeb 实现并提供服务的网络协议。

• WebSocket —— CivetWeb 支持的浏览器与服务器双向通信协议。

• CGI —— CivetWeb 可选支持的服务器端脚本调用接口。

• Lua —— CivetWeb 可选支持的服务端脚本语言。