# mongoose-web-server-demo

**Repository Path**: createskyblue/mongoose-web-server-demo

## Basic Information

- **Project Name**: mongoose-web-server-demo
- **Description**: A lightweight embedded web server demo using Mongoose library with a modern React + Tailwind CSS frontend. Features cross-platform CMake build system, RESTful API, and static file serving. Perfect for learning embedded web server development and C programming with network technologies.
- **Primary Language**: C
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-06
- **Last Updated**: 2026-08-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Mongoose Web Server Demo

![应用截图](img/PixPin_2026-02-18_05-30-12.png)

这是一个使用 Mongoose 嵌入式 Web Server 的示例项目，前端使用 React 和 Tailwind CSS。

## 项目结构

```
.
├── server/          # C 服务器代码
│   └── server.c     # 主服务器文件
├── public/          # React 前端应用
│   ├── src/         # React 源代码
│   ├── package.json
│   └── vite.config.js
├── CMakeLists.txt   # CMake 构建配置
├── mongoose.c       # Mongoose 库源文件
├── mongoose.h       # Mongoose 库头文件
└── README.md
```

## 功能特性

- ✅ 使用 C 语言编写的轻量级嵌入式 Web 服务器
- ✅ React 18 + Vite 构建的单页面应用
- ✅ Tailwind CSS 实现现代化 UI
- ✅ RESTful API 接口
- ✅ 静态文件服务
- ✅ 支持 CMake 和 Make 两种构建方式
- ✅ 跨平台支持（Windows、Linux、macOS）

## 快速开始

### 方式一：使用 CMake（推荐）

```bash
# 配置项目
cmake -B build

# 编译服务器
cmake --build build

# 运行服务器
./build/mongoose-web-server
```

**CMake 额外命令：**
```bash
# 下载 mongoose 库
cmake --build build --target download-mongoose

# 构建前端
cmake --build build --target build-frontend

# 安装前端依赖
cmake --build build --target install-frontend

# 清理构建
rm -rf build
```

## 前端开发

### 安装依赖

```bash
cd public && npm install
```

### 开发模式

```bash
cd public
npm run dev
```

开发服务器将在 http://localhost:3000 启动，API 请求会自动代理到后端服务器

### 生产构建

```bash
# 或直接使用 npm
cd public && npm run build
```

构建后的文件将输出到 `public/dist/` 目录，Mongoose 服务器会自动服务这些文件

## 技术要点详解

### Mongoose Web服务器特点

Mongoose是一个轻量级的嵌入式Web服务器库，具有以下特点：
- 单文件库（mongoose.c 和 mongoose.h）
- 跨平台支持（Windows、Linux、macOS、嵌入式系统）
- 事件驱动架构
- 支持HTTP/HTTPS、WebSocket、TCP/UDP等多种协议
- 内存占用小，适合资源受限环境

### CMake跨平台构建配置要点

#### 1. Windows与Unix-like系统的差异处理

```cmake
# 根据操作系统链接不同的库
if(WIN32)
    # Windows下需要链接网络库
    target_link_libraries(${PROJECT_NAME} PRIVATE ws2_32)
    target_compile_definitions(${PROJECT_NAME} PRIVATE _WIN32_WINNT=0x600)
else()
    # Unix/Linux系统下使用pthread
    target_link_libraries(${PROJECT_NAME} PRIVATE pthread)
endif()
```

**关键点说明：**
- Windows平台需要链接`ws2_32`库以支持WinSock API
- Unix-like平台需要链接`pthread`库以支持POSIX线程
- 在Windows上必须显式链接`ws2_32`库，否则会出现`undefined reference to __imp_`系列错误

#### 2. Mongoose库集成方式

Mongoose库作为一个单文件库，可以直接包含到项目中：
- 将`mongoose.c`作为源文件添加到构建中
- 将`mongoose.h`放置在包含路径中
- 通过`target_include_directories`设置包含路径

#### 3. 条件编译定义

根据平台不同设置适当的编译标志，确保Mongoose在不同平台上使用正确的API。

### 服务器端实现细节

服务器实现了以下功能：
- 处理API请求：`/api/hello` 和 `/api/info`
- 静态文件服务：托管`public/dist`目录中的前端构建产物
- 支持React SPA：使用SSI模式正确处理前端路由

### 前端集成策略

- 前端构建产物自动部署到`public/dist`
- 服务器自动托管静态文件
- API请求路径映射到对应的处理函数

## API 接口

- `GET /api/hello` - 返回欢迎信息
- `GET /api/info` - 返回服务器信息
- `GET /` - 返回前端应用

## 部署

构建完成后运行生成的可执行文件：
```bash
./build/mongoose-web-server
```

服务器默认监听8000端口，可以通过修改`server.c`中的端口号来更改。

## 常见问题

### 1. Windows编译错误

如果在Windows上遇到`undefined reference to __imp_*`错误，请确保：
- 已正确链接`ws2_32`库
- CMakeLists.txt中包含了Windows平台的特殊配置

### 2. 网络权限问题

在某些系统上可能需要管理员权限才能绑定特定端口。

### 3. 前端资源无法加载

确认前端已经构建到`public/dist`目录中：
```bash
cmake --build build --target build-frontend
```

## 技术优势

1. **轻量级**: 仅依赖标准库和单文件Mongoose库
2. **跨平台**: 统一的代码基础，支持多种操作系统
3. **高性能**: C语言实现，资源占用少
4. **易扩展**: 易于添加新的API路由和处理逻辑
5. **一体化**: 前后端整合到单一可执行文件中

## 学习价值

- 了解嵌入式Web服务器的实现原理
- 掌握C语言网络编程基础
- 学习跨平台构建的最佳实践
- 理解前后端一体化部署方案

## 系统要求

- GCC 或 Clang 编译器
- CMake 3.10+ (推荐) 或 Make
- Node.js 18+ (用于前端开发)
- curl 或 wget (用于下载 mongoose)

## 清理

```bash
# CMake 清理
rm -rf build
```


## 参考资料

- [Mongoose 官方文档](https://cesanta.com/docs/)
- [Mongoose GitHub](https://github.com/cesanta/mongoose)
- [CMake 官方文档](https://cmake.org/documentation/)