Features - 508364/NetLeaf GitHub Wiki
NetLeaf支持Windows和Linux平台,以及多种CPU架构(已验证):
| 平台 | 架构 | 状态 |
|---|---|---|
| Windows | x64 | ✅ |
| Windows | x86 | ✅ |
| Windows | ARM64 | ✅ |
| Linux | amd64 | ✅ |
| Linux | i386 | ✅ |
| Linux | ARM | ✅ |
| Linux | ARM64 | ✅ |
| Linux | RISC-V 64 | ✅ |
| Linux | PowerPC 64 LE | ✅ |
| Linux | MIPS | ✅ |
| Linux | s390x | ✅ |
- HTTP/1.1: 完整支持
- HTTP/2: 多路复用、头部压缩
- HTTP/3 (QUIC): 基于QUIC的下一代协议
- WebSocket: 实时双向通信
- TCP/UDP: 原始套接字支持
// 创建Web服务器(自动启动)
nl_web_server_t* server = nl_web_create(8080);
// 添加HTML页面
nl_web_add_html(server, "/", "<h1>Hello World</h1>");
// 添加Vue页面
nl_web_add_vue(server, "/app", "<p>{{ message }}</p>");
// 服务器已自动启动,无需调用 nl_web_start()新增功能: 服务器端变量替换,用户即使使用F12无法看到原始变量名。
const char* vars[] = {"username", "user_id"};
const char* values[] = {"张三", "12345"};
nl_web_add_html_with_vars(server, "/profile",
"<h1>欢迎, {{<var>username</var>}}</h1>\n"
"<p>用户ID: {{<var>user_id</var>}}</p>",
vars, values, 2);输出到客户端:
<h1>欢迎, 张三</h1>
<p>用户ID: 12345</p>变量格式: {{<var>变量名</var>}}
// 设置响应编码(默认为UTF-8)
nl_web_set_encoding(server, "UTF-8");修改外部HTML/Vue/JSON文件后,刷新页面立即生效,无需重启服务器。
nl_web_add_html_file(server, "/", "index.html");
nl_web_add_vue_file(server, "/app", "app.vue");
nl_web_add_json_file(server, "/data", "data.json");平台: Windows/Linux/macOS
支持301永久重定向和302临时重定向,可在运行时切换类型。
// 添加重定向路由
nl_web_add_redirect(server, "/old", "/new");
nl_web_add_redirect(server, "/goto", "https://example.com");
// 运行时切换重定向类型
nl_web_set_redirect_type(server, NL_REDIRECT_PERMANENT); // 301
nl_web_set_redirect_type(server, NL_REDIRECT_TEMPORARY); // 302(默认)
// 获取当前重定向类型
nl_redirect_type_t type = nl_web_get_redirect_type(server);重定向类型:
-
NL_REDIRECT_TEMPORARY(302): 临时重定向 -
NL_REDIRECT_PERMANENT(301): 永久重定向
平台: Windows/Linux/macOS
nl_web_add_html/vue/json 自动识别URL、文件路径或静态内容:
- URL → 自动创建重定向路由
- 文件路径 → 自动创建热加载路由
- 其他字符串 → 作为内联静态内容
nl_web_add_html(server, "/goto", "https://google.com"); // URL→重定向
nl_web_add_html(server, "/", "index.html"); // 文件→热加载
nl_web_add_html(server, "/hello", "<h1>Hello</h1>"); // 静态→内联平台: Windows/Linux/macOS
在服务器运行期间添加、移除、查询和更新路由。
// 运行时添加新路由
nl_web_add_route(server, "/api/status", "{\"status\":\"ok\"}", "application/json");
// 查询路由数量
int count = nl_web_get_route_count(server);
// 列出所有路由路径
char* paths[32];
for (int i = 0; i < 32; i++) paths[i] = (char*)calloc(256, 1);
int n = nl_web_list_routes(server, paths, 32);
// 更新路由内容
nl_web_update_route(server, "/api/status", "{\"status\":\"maintenance\"}", "application/json");
// 移除路由
nl_web_remove_route(server, "/old-path");API:
-
nl_web_add_route()- 添加静态内容路由 -
nl_web_remove_route()- 移除指定路径的路由 -
nl_web_get_route_count()- 获取当前路由数量 -
nl_web_list_routes()- 列出所有路由路径 -
nl_web_update_route()- 更新路由内容(仅支持静态内容类型)
平台: Windows/Linux/macOS
// 设置日志级别
nl_log_set_level(NL_LOG_DEBUG);
// 输出日志
nl_log_debug("调试信息");
nl_log_info("一般信息");
nl_log_warn("警告信息");
nl_log_error("错误信息");
// 启用调试模式
nl_debug_enable(1);- JSON解析: 完整的JSON支持
- TOML解析: TOML配置文件支持
获取非敏感的系统信息,采用懒加载机制。
#include "netleaf.h"
int main() {
// 获取系统信息(首次调用时懒加载)
const char* os_name = nl_sys_info_get_os_name();
const char* arch = nl_sys_info_get_architecture();
const char* cpu = nl_sys_info_get_cpu_model();
int64_t ram = nl_sys_info_get_total_ram();
const char* runtime = nl_sys_info_get_runtime_version();
printf("OS: %s\n", os_name);
printf("Architecture: %s\n", arch);
printf("CPU: %s\n", cpu);
printf("Total RAM: %lld bytes\n", (long long)ram);
printf("Runtime: %s\n", runtime);
return 0;
}RAM进制配置:
-
NL_RAM_UNIT_DECIMAL (1000): Linux默认,符合SI标准 -
NL_RAM_UNIT_BINARY (1024): Windows默认,传统二进制
所有组件支持懒加载机制,仅在首次使用时加载。
#include "netleaf.h"
int main() {
// 预加载特定模块
nl_lazy_preload_module(NL_LAZY_MODULE_HTTP);
// 检查模块状态
if (nl_lazy_is_module_loaded(NL_LAZY_MODULE_HTTP)) {
printf("HTTP模块已加载\n");
}
// 停止模块释放资源
nl_lazy_stop_module(NL_LAZY_MODULE_HTTP);
return 0;
}支持懒加载的模块:
-
NL_LAZY_MODULE_HTTP- HTTP服务器 -
NL_LAZY_MODULE_WEBSOCKET- WebSocket -
NL_LAZY_MODULE_TCP- TCP通信 -
NL_LAZY_MODULE_UDP- UDP通信 -
NL_LAZY_MODULE_TOML- TOML解析 -
NL_LAZY_MODULE_JSON- JSON解析 -
NL_LAZY_MODULE_SYSINFO- 系统信息
// 设置线程池大小(1-256)
nl_lazy_set_thread_count(8);
// 获取当前线程池大小
int threads = nl_lazy_get_thread_count();线程池建议:
- IO密集型: 推荐设置较大线程数(如CPU核心数的2倍)
- CPU密集型: 推荐设置为CPU核心数
⚠️ Beta 阶段:反向代理引擎已实现完整功能,但 API 与行为可能在后续版本调整。 三平台实现:Linuxepoll/ macOSkqueue/ WindowsIOCP(select作为兼容回退)。 混合路由支持:同一 Web 服务器可同时启用proxy + static + content + redirect + file路由, 引擎内部统一处理,彻底消除早期"proxy 路由激活后其它路由返回 501"的限制。
NetLeaf 的 Web 反向代理已升级为数据驱动的异步并行事件引擎:不
为每个连接建立独立对象,而是把连接状态编码为 8 位无状态字节(
pr_state) + 一组按设备动态定容的整数 ring buffer 数组(pr_fd_client /
pr_fd_upstream / pr_route_idx / pr_hbuf / pr_hbuf_out / pr_hdr_len /
pr_remain / pr_free)。单线程通过 I/O 多路复用一次泵多个连接,彻底
摆脱旧版"并发 ≈ worker 数"的瓶颈,同时保持极低 CPU / 内存占用。
多路复用后端(按平台自动选择):
| 平台 | 后端 | 索引携带方式 | 空闲退避 |
|---|---|---|---|
| Linux | epoll |
event.data.u32 编码 idx + 方向位 |
epoll_wait 1000ms |
| macOS | kqueue |
kevent.udata 编码 idx + 方向位 |
kevent 1s |
| Windows |
IOCP 完成端口 |
AcceptEx 预 post + GetQueuedCompletionStatus 分发 |
200ms 退避 |
极低占用设计:
- 所有 fd(listen / 客户端 / 上游)一律非阻塞(
O_NONBLOCK/ioctlsocket(FIONBIO)),事件驱动、忙时零等待。 - 空闲时退避超时(Linux/macOS 1s、Windows 200ms),无连接时近乎零 CPU。
-
单线程引擎:
nl_web_start检测到 proxy 路由时直接起 1 个引擎线程, 不分配 worker 池;无 proxy 路由时回退到原有 worker 池,行为不变。 -
pr_remain记录每方向"已收待发余量",先补发上次EAGAIN/WSAEWOULDBLOCK未发完的部分再读新数据,杜绝半包丢数据。
ring 容量按设备动态调整(三平台统一):
- Linux / macOS / Windows:
逻辑核数 × 64,下限 64、上限 4096(1 核=64、8 核=512、 16 核=1024,高压 4096)。 - Windows 采用 IOCP 内核完成端口,不受
FD_SETSIZE硬上限约束;4096 为工程 保护值(防低内存设备爆掉),需要可按需调大。
上游协议分流(upstream 前缀决定):
-
tcp://host:port—— 纯字节透传,不解协议。 -
http:///https://—— 重组 request line +Host/X-Forwarded-For/Connection: close头,透传原始 header / body。
用法:
#include "netleaf.h"
int main(void) {
nl_web_server_t* server = nl_web_create(8080);
// 把 /api/ 透明转发到上游 API 服务(自动走数据驱动引擎)
nl_web_add_proxy(server, "/api/", "http://127.0.0.1:9000");
// TCP 上游(如 Redis)
nl_web_add_proxy(server, "/cache/", "tcp://127.0.0.1:6379");
nl_web_start(server); // 有 proxy 路由时单线程引擎自动拉起
nl_web_stop(server);
nl_web_destroy(server);
return 0;
}引擎接线细节:
-
nl_web_start持锁遍历routes,发现任意NL_ROUTE_TYPE_PROXY即起引擎 线程(pthread_create/CreateThread包装nl_web_proxy_engine)。 -
混合路由统一分发(v2.4.2 修复):引擎内对四种路由类型做完整分发,
非 proxy 路由(REDIRECT / FILE / CONTENT)临时把 fd 切阻塞处理后立即 close +
释放 slot,proxy 路由保持非阻塞走引擎 pump 链路,彻底消除早期"proxy 路由
激活后其它路由返回 501"的限制;路由查找走引擎内锁保护的
pr_lookup_route_idx。 -
nl_web_stop关闭 listen socket 后 join 引擎线程;引擎正常退出时已自行close全部活跃连接并逐字段freering。stop / destroy 额外做兜底 清理(防TerminateThread路径残留),保证无泄漏。
实现"见人说人话,见鬼说鬼话"的智能编码协商机制。
#include "netleaf.h"
int main() {
// 创建服务器
nl_web_server_t* server = nl_web_create(8080);
// 启用自动编码协商
nl_web_enable_auto_encoding(server, 1);
// 设置回退编码(当客户端未指定时使用)
nl_web_set_fallback_encoding(server, "UTF-8");
// 添加页面(内部始终使用UTF-8)
nl_web_add_html(server, "/", "<h1>你好,世界!</h1>");
// 添加JSON响应(自动转码)
nl_web_add_json(server, "/api/data", "{\"message\": \"你好世界\"}");
// 服务器会自动根据客户端Accept-Charset头转换编码
return 0;
}编码转换API:
// 编码转换(双向转换)
char* gbk_output = nl_encoding_convert(utf8_string, strlen(utf8_string),
"UTF-8", "GBK");
// 自动检测编码
const char* detected = nl_encoding_detect(data, data_len);
// 获取系统默认编码
const char* sys_enc = nl_encoding_get_system_default();支持的编码:
- UTF-8
- GBK
- GB2312
- GB18030
- Big5
- ISO-8859-1
- US-ASCII
- UTF-16
全场景支持:
- ✅ 控制台输出
- ✅ Web响应
- ✅ HTML页面
- ✅ Vue组件
- ✅ JSON响应
- ✅ TOML响应
特性:
- ✅ 自动解析Accept-Charset请求头
- ✅ 运行时自动转码
- ✅ 双向编码转换
- ✅ 跨平台支持(Windows/Linux)
- ✅ 编码自动检测
- ✅ 懒加载机制:功能拉起使用后自动下线,减少内存占用
- ✅ 智能优化:仅对非ASCII字符进行转码,减少性能开销
- ✅ 空指针检查
- ✅ 缓冲区溢出防护
- ✅ 字符串格式化安全
- ✅ 数组边界检查
- ✅ 内存管理安全
- ✅ 只能停止本库启动的端口
NetLeaf支持多个独立可拆卸模块,与主库共用版本号。
功能: 自动补全charset标签和自动引入Vue库
特性:
- Charset自动补全:根据统一编码格式添加
<meta charset>和<meta name="viewport"> - Vue自动引用:检测Vue代码但无引用时自动从CDN引入
- 灵活启用方式:支持
true/false,on/off,yes/no,1/0 - 单独控制:charset和Vue功能可独立启用/禁用
平台: Windows/Linux/macOS
功能: 404时自动查找相近端点并在错误页面提示
特性:
- Levenshtein距离算法计算路径相似度
- 多策略评分:路径段匹配、前缀共有、段数相同
- 通配符支持:
*和**
平台: Windows/Linux/macOS
功能: 支持自定义错误页面模板,强制预留变量区域
特性:
- 独立standalone模块,其他模块不可使用其功能
- 模板必须预留变量:
{{ERROR_CODE}},{{ERROR_MESSAGE}},{{REQUESTED_PATH}},{{SERVER_VERSION}},{{TIMESTAMP}} - 支持
{{#if SUGGESTION}}条件块 - 可与Auto-route联动显示路由建议
平台: Windows/Linux/macOS
功能: 进程间通讯服务
特性:
- Windows: Named Pipe
- Linux: Unix Domain Socket
- 支持服务端监听和客户端连接
- 跨进程数据传输
- 线程安全设计
平台: Windows/Linux
功能: 同端口链路聚合,将请求转发到多个后端
特性:
- 单端口监听
- 负载均衡策略: Round Robin, Random, Least Connections, Weighted Round Robin
- 支持 HTTP 和 IPC 后端
- 同端口路由聚合
平台: Windows/Linux
功能: Vue.js 后端支持和 HTML 生成
特性:
- Vue CDN 配置(unpkg、cdnjs、jsdelivr、local)
- Vue 代码检测和自动导入
- HTML 页面生成(带 Vue CDN)
- 本地 Vue.js 文件支持(离线/内嵌模式)
-
预制系统信息页面(
nl_vue_generate_sysinfo/nl_vue_generate_sysinfo_inline) - 变量替换支持
平台: Windows/Linux/macOS
所有独立模块通过统一接口进行管理:
typedef struct nl_module_info {
nl_module_type_t type;
const char* name;
const char* version;
uint32_t capabilities;
nl_module_status_t status;
int platform_windows;
int platform_linux;
int platform_macos;
int (*init)(void);
void (*shutdown)(void);
int (*is_available)(void);
const char* (*get_version)(void);
const char* description;
const char* author;
struct nl_module_info* next;
} nl_module_info_t;模块管理API:
-
nl_module_register()- 注册模块 -
nl_module_unregister()- 注销模块 -
nl_module_find()- 查找模块 -
nl_module_get_all()- 获取所有模块列表 -
nl_module_init_all()- 初始化所有模块 -
nl_module_shutdown_all()- 关闭所有模块
功能: 提供统一的多语言错误消息翻译功能,并增强支持变量替换和条件表达式求值
特性:
- 中英文错误消息支持
- 所有 NetLeaf 库的错误码统一翻译
- 简单易用的 API
- 运行时语言切换
-
变量替换:
{{VAR_NAME}}模板语法,支持字符串/整数/浮点/布尔类型 -
条件表达式:支持
== != >= <= > <运算符,兼容数值和字符串比较 - 脚本引擎:通过回调注册 Lua/Python/JavaScript 引擎(扩展 API)
-
动态变量(v2.4.1):
nl_lang_var_set_provider()按需计算变量值 -
外部变量(v2.4.1):
nl_lang_var_bind_env()/nl_lang_var_load_env()/nl_lang_var_load_file() -
表驱动错误注册(v2.4.1):
NL_ERROR_BEGIN/NL_ERROR/NL_ERROR_END+nl_lang_register_errors()
API 示例:
#include "netleaf_lang.h"
// 设置语言为中文
nl_lang_set(NL_LANG_ZH);
// 获取 LinkAgg 错误消息
const char* msg = nl_lang_get_error(NL_LIB_LINKAGG, -9);
// 输出: "不接入,ID被占用"
// 设置语言为英文
nl_lang_set(NL_LANG_EN);
msg = nl_lang_get_error(NL_LIB_LINKAGG, -9);
// 输出: "ID already in use, not connected"
// === v2.4.0 新增:变量替换 ===
nl_lang_var_set("user", "Alice");
nl_lang_var_set_int("age", 25);
nl_lang_var_set_float("price", 3.14);
nl_lang_var_set_bool("active", 1);
char buf[256];
nl_lang_var_replace("Hello {{ user }}, age={{ age }}", buf, sizeof(buf));
// buf == "Hello Alice, age=25"
// === v2.4.0 新增:条件表达式 ===
int result = nl_lang_var_condition_eval("age > 18"); // 1 (true)
result = nl_lang_var_condition_eval("user == 'Alice'"); // 1 (true)
result = nl_lang_var_condition_eval("price >= 3.0"); // 1 (true)
result = nl_lang_var_condition_eval("active == true"); // 1 (true)
// === v2.4.0 新增:脚本引擎注册 ===
nl_script_result_t* my_exec(const char* script, const char* lang_code, int error_code, void* userdata) {
// 实现脚本执行逻辑
static nl_script_result_t result;
result.status = 0;
result.result_type = 1;
result.result_str = "hello from script";
return &result;
}
nl_lang_register_script_engine("myscript", my_exec, NULL);
char script_out[256];
nl_lang_execute_script("myscript", "echo hello", NULL, 0, script_out, sizeof(script_out));平台: Windows/Linux/macOS
库标识符:
| 库 | 标识符 |
|---|---|
| Core |
NL_LIB_CORE (0x0000) |
| IPC |
NL_LIB_IPC (0x0001) |
| LinkAgg |
NL_LIB_LINKAGG (0x0002) |
| Auto-route |
NL_LIB_AUTOROUTE (0x0003) |
| Auto-complete |
NL_LIB_AUTOCOMPLETE (0x0004) |
| ErrorPage |
NL_LIB_ERRORPAGE (0x0005) |
| Lang |
NL_LIB_LANG (0x0006) |
| TLS |
NL_LIB_TLS (0x0007) |
| MQTT |
NL_LIB_MQTT (0x0008) |
模块: netleaf_tls.dll
说明: TLS/SSL 是一个独立的扩展库,其他通信协议(包括 MQTT)可通过 NL 扩展系统调用其功能。基于 mbedTLS 2.28.10 LTS 构建,支持多种安全协议。
- ✅ 协议支持: TLS 1.0, 1.1, 1.2, 1.3
- ✅ 密码套件: 多种主流密码套件
- ✅ 证书验证: CA 证书链验证、客户端证书认证
- ✅ 随机数生成: 基于硬件熵源的加密安全随机数
- ✅ 内存管理: 自动内存分配和释放
- ✅ 线程安全: 支持多线程并发使用
⚠️ 安全提示(不推荐 TLS 1.0 / 1.1):TLS 1.0/1.1 已被 RFC 8996 废弃且不再安全,不建议使用。 TLS 由本独立的 TLS 扩展库(netleaf_tls,内置 mbedTLS)统一负责,保留 1.0/1.1 仅为兼容老旧对端; 请将min_proto设置为NL_TLS_PROTO_TLS1_2或更高。
flowchart TD
subgraph NLEXT["NetLeaf 扩展系统"]
MQTT["netleaf_mqtt"]
OTHER["其他扩展库"]
end
TLS["netleaf_tls.dll<br/>(TLS/SSL 加密扩展)"]
MQTT -->|调用| TLS
OTHER -->|调用| TLS
# CMakeLists.txt
option(BUILD_TLS "Build TLS/SSL extension" ON)
# 编译时自动包含 mbedTLS 源码
if(BUILD_TLS)
target_link_libraries(netleaf_mqtt PRIVATE netleaf_tls)
endif()平台: Windows/Linux/macOS
模块: netleaf_mqtt.dll
说明: 轻量级 MQTT v5.0 协议客户端实现,支持 QoS 0/1/2、主题订阅发布、消息回调等核心功能。可选集成 TLS 加密通信。
- ✅ MQTT 5.0: 完整支持 MQTT v5.0 协议
- ✅ QoS 级别: QoS 0 (至多一次), QoS 1 (至少一次), QoS 2 (恰好一次)
- ✅ 主题订阅: 支持通配符 (+ 和 #)
- ✅ 消息回调: 异步消息接收和处理
- ✅ 连接管理: 自动重连、心跳保活
- ✅ 属性支持: 完整的属性编码/解码
- ✅ TLS 加密: 可选集成 TLS/SSL 安全通信
flowchart TD
subgraph MQTT["netleaf_mqtt.dll"]
direction LR
CORE["MQTT 核心<br/>(netleaf_mqtt.c)"]
MTLSP["MQTT TLS 模块<br/>(netleaf_mqtt_tls.c)"]
end
TLS["netleaf_tls<br/>(可选)"]
MQTT --> TLS
# CMakeLists.txt
option(BUILD_MQTT "Build MQTT client module" ON)
option(BUILD_TLS "Build TLS/SSL extension for MQTT" ON)平台: Windows/Linux/macOS
NetLeaf 项目中使用了以下开源项目,特此致谢:
| 项目 | 许可证 | 用途 | 链接 |
|---|---|---|---|
| mbedTLS | Apache 2.0 / GPL v2.0 | TLS/SSL 加密库 | github.com/Mbed-TLS/mbedTLS |
| MQTT 规范 | EPL-2.0 / EDL 1.0 | MQTT v5.0 协议定义 | mqtt.org |
| Paho MQTT C | EPL-2.0 / EDL 1.0 | MQTT 协议参考实现 | github.com/eclipse/paho.mqtt.c |
注意: 本项目中 mbedTLS 源码已内置于 third-party/mbedtls/ 目录,编译时自动包含,无需用户单独安装。