Paozhu C++ Web Framework · 入门完整简介

📚 框架简介 📚 Framework Introduction

Paozhu 炮竹 (🧨) 来源中国传统鞭炮，迅速、响亮。 Paozhu (🧨) — named after the traditional Chinese firecracker, fast and loud.

Paozhu (🧨) 是一款 C++ Web 开发框架，内置 HTTP/1、HTTP/2、C++ ORM，可以轻松优雅地编写 Web 程序，打破以往 C++ 写 Web 程序不方便的问题。 Paozhu is a high-performance C++20 web framework with native support for HTTP/1, HTTP/2, and a built-in C++ ORM. It makes writing web programs in C++ straightforward and elegant — something that used to be painful.

Paozhu 编写了 Web 开发底层设施，比如多域名绑定、SSL 证书管理、Cookie、Session、HTML 表单管理、URL 处理、文件上传下载、HttpClient 客户端、数据库连接 ORM、WebSocket、日志、HTML 模板，涵盖 Web 开发基础。 Paozhu implements the full stack of web infrastructure: multi-domain binding, SSL certificate management, cookies & sessions, HTML form handling, URL routing, file uploads & downloads, HttpClient, ORM with coroutines, WebSocket support, logging, and an HTML template engine.

框架基于 C++20 标准，开启了 ASAN 和完整错误提示，方便开发阶段发现问题。压力测试可发现多线程数据竞争问题，运行时可结合 coredumpctl 查看内存栈。配合智能指针基本杜绝内存泄露和越界问题。 The framework is built on C++20, so you get modern language features and full compiler support. It ships with ASAN enabled and all compiler warnings turned on, which makes bugs easier to catch during development; stress tests help surface race conditions. At runtime, you can pair it with coredumpctl to inspect thread stacks. Smart pointers and RAII patterns mean memory leaks and buffer overflows are practically eliminated.

Paozhu 使用 C++，主要考虑接入大模型（CUDA、文件存储、网络、内存操作）。对比 Go、Java、Rust，各有不足，C++ 更适合 AI 深度整合。ASAN 和 coredumpctl 两个工具可保证 C++ 质量。 We chose C++ because it integrates naturally with large-model ecosystems: CUDA, file storage, networking, and raw memory operations are all first-class citizens here. To be fair, every language has tradeoffs — but with modern tooling (ASAN, coredumpctl, strict compiler warnings), C++ is very manageable and powerful for AI-heavy backends.

💻 Hello World 示例 💻 Hello World Example

📦 项目完整源码已开源，欢迎访问 GitHub: https://github.com/hggq/paozhu 获取全部源码与示例 📦 The full source code is open source. Visit GitHub: https://github.com/hggq/paozhu for all source code and examples

仅需几行代码即可创建一个 Web 接口：将 testhello.cpp 放在 controller/src 目录下 Create a web endpoint with just a few lines of code. Save testhello.cpp under the controller/src directory.

#include "httppeer.h"
#include "testhello.h"

namespace http
{
//@urlpath(null,hello)
std::string testhello(std::shared_ptr<httppeer> peer)
{
    httppeer &client = peer->get_peer();
    client << " Hello world! Paozhu c++ web framework ";
    return "";
}
}// namespace http

无需编写 testhello.h 文件，框架自动生成这个文件，直接编译 No need to write testhello.h — the framework auto-generates it. Just run:

mkdir build
cd build 
cmake ..
make

📁 控制器文件必须放在 controller/src 目录下面 📁 Controller files must be placed in the controller/src directory

//@urlpath 注解自动将函数映射到 /hello 路径 The //@urlpath annotation auto-maps the function to the /hello route.

✨ 核心特色 ✨ Core Features

强大的内置功能，助你快速构建高性能 Web 应用 Powerful built-in features to help you build high-performance web apps

⚡

支持 HTTP/2HTTP/2 Support 新一代 HTTP 协议支持Next-gen HTTP protocol

🗄️

内置 ORMBuilt-in ORM 自研 MySQL PostgreSQL SQLite 协议，支持协程模式Custom wire protocol for MySQL, PostgreSQL, SQLite — with coroutine support

☁️

多域名与 SaaSMulti-domain & SaaS 多域名管理、SaaS 模式支持Multi-domain management and multi-tenant SaaS mode

🔄

IO 与业务线程分离IO/Business Thread Separation IO 线程和业务线程分开Dedicated IO and business thread pools

📊

内置微型对象Built-in Micro Objects JSON 导入导出，类似脚本语言变量A lightweight dynamic type with JSON import/export — like variables in scripting languages

🐘

FastCGI 支持FastCGI for PHP 内置 FastCGI 支持 PHPBuilt-in FastCGI for PHP support

🔐 SSL 证书自动续期 🔐 SSL Certificate Auto-Renewal

内置 ACME 协议支持，自动申请与续期 SSL 证书，HTTPS 永不过期 Built-in ACME protocol for automatic SSL certificate issuance and renewal

🔄

ACME 自动续期ACME Auto-Renewal

证书到期前自动更新，全程无需人工干预Renews certificates before expiry, fully automated

🛡️

OCSP StaplingOCSP Stapling

自动 OCSP 装订，提升握手性能与隐私Automatic OCSP stapling for faster, private handshakes

🌐

ZeroSSL 支持ZeroSSL Support

内置 ZeroSSL DV 接口，支持 EAB 认证Built-in ZeroSSL DV endpoint with EAB auth

⏰

智能续期时机Smart Renewal Timing

可配置到期前天数与每日执行时刻Configurable days-before-expiry and run time


; conf/server.conf ACME 配置ACME settings
acme_auto = 0             自动 SSL 证书更新Auto SSL certificate renewal
acme_every_day = 7        每天几点执行 ACMEDaily hour to run ACME
ocsp_intv_time = 14400    OCSP 更新间隔（秒）OCSP update interval (seconds)

; conf/acme.conf ACME 证书配置ACME certificate config
[info]
acme_path = ./acme        ACME 工作目录ACME working directory
cert_path = ./conf        证书存储目录Certificate storage directory
email = your@email.com    邮箱（必须）Email (mandatory)
days_remain = 10          提前多少天更新证书Renew days before expiry

[zerossl]
server_url = https://acme.zerossl.com/v2/DV90  ZeroSSL 接口ZeroSSL endpoint
eab_kid =                 EAB Key IDEAB Key ID
eab_hmac_key =            EAB HMAC KeyEAB HMAC Key

💻 需求环境 💻 System Requirements

框架基于 C++20，确保你的系统支持相应的编译器 Built on C++20, ensure your compiler supports C++20 standard

🍎

macOSmacOS

macOS 11 BigSur 以上，推荐 macOS 14 SonomamacOS 11 BigSur+, recommended macOS 14 Sonoma

🐧

UbuntuUbuntu

Ubuntu 22.04 以上Ubuntu 22.04 or higher

🐢

RockyLinux/AlmaLinuxRockyLinux/AlmaLinux

9.1 以上版本9.1 or higher

🪟

WindowsWindows

Win10，编译器 19.25 以上Win10 with compiler 19.25+

依赖第三方开发包： OpenSSL、Zlib、Brotli、ASIORequired dependencies: OpenSSL, Zlib, Brotli, ASIO

🏗️ 技术架构 🏗️ Technical Architecture

框架使用 M:N 并发模型，IO 线程与业务线程分离 Uses M:N concurrency model with separated IO and business threads


+-----------------------+  +-----------------------+   +----------------------------+
| thread accept(80 443) |  | asio coroutine thread |   | thread pool(business code) |
+-----------------------+  +-----------------------+   +----------------------------+

框架使用 ASIO 的线程池做 IO 处理（网络收发），内置业务线程池运行业务代码。HTTP/HTTPS 监听连接到来，协程函数直接运行，普通函数丢到业务线程池。静态文件直接发送，不走业务线程。 The ASIO thread pool handles all IO — network send/receive, TLS handshake, and HTTP parsing. A separate business thread pool runs your application code. The server listens on ports 80 and 443; when a request comes in, the framework decides based on the handler signature: coroutines run directly on ASIO workers, regular functions go to the business thread pool. Static files are streamed back without touching business threads.

C++ 协程具有传染性，在协程注册函数中需使用 ORM 协程方法。普通函数中无法发起协程函数，只能使用 ORM 普通函数。建议一个连接一个线程的经典模式。 C++ coroutines are contagious: if a handler is a coroutine, every ORM call inside must use the async async_* versions. Regular handlers can only use sync ORM methods — you can't mix them. If your handler is CPU-heavy, keep it a regular function so it runs on the business thread pool.

📂 项目结构 📂 Project Structure

框架未分离命令行工具独立安装，全部包含在一个项目内 Framework and CLI live inside one project — no separate global install needed.


.
├── asio                    asio 库文件ASIO library files
├── bin                     编译后的执行文件Compiled executables
├── cache                   缓存压缩文件Compressed response cache
├── conf                    配置文件 (server.conf, orm.conf)Config files (server.conf, orm.conf)
├── controller              路由器代码入口Controller & route handlers
├── libs                    业务代码库Reusable business libraries
├── log                     日志目录Log directory
├── models                  ORM 业务代码ORM-based data models
├── module                  可插拔 SO 存放Pluggable .so modules
├── orm                     ORM 实体映射类ORM entity mapping classes
├── startup                 框架 main 入口Framework entry point (main)
├── temp                    临时文件Temporary files
├── vendor                  主程序与第三方包Main binary & third-party libs
├── view                    HTML 模板HTML templates
├── viewsrc                 编译好的视图Pre-compiled views
├── websockets              WebSocket 程序WebSocket handlers
└── www                     静态文件目录Document root (static files)

🎯 核心特性 🎯 Core Features

强大的内置功能，助你快速构建高性能 Web 应用 Powerful built-in features to help you build high-performance web apps

⚡

高性能 I/OHigh-Performance I/O 基于 ASIO 协程调度Based on ASIO coroutine scheduling

🎯

注解驱动Annotation-Driven //@urlpath 自动路由//@urlpath auto routing

🗄️

内置 ORMBuilt-in ORM MySQL / PostgreSQL / SQLite 支持MySQL / PostgreSQL / SQLite support

🔌

WebSocketWebSocket 原生客户端与服务端Native client & server

🎨

视图系统View System 灵活模板渲染Flexible template rendering

📄

Office 处理Office Processing PDF / Excel / WordPDF / Excel / Word

📊

SVG 图表SVG Charts 17 种内置图表类型17 built-in chart types

📊 SVG 图表模块 📊 SVG Charts Module

Paozhu 内置强大的 SVG 图表生成库 pzcharts，支持 17 种图表类型，纯 C++ 实现，无需任何前端依赖 Paozhu includes the powerful pzcharts SVG chart library with 17 chart types, pure C++ implementation with no frontend dependencies

💡 编译时添加 -DENABLE_CHART=ON 即可启用图表模块 💡 Add -DENABLE_CHART=ON during compilation to enable the chart module

📚 查看全部 17 种图表类型，请访问高级模块 → 📚 For all 17 chart types, visit the Advanced Modules →