简介这份C CGI库源码包面向希望了解早期Web开发机制、练习C网络编程与数据库访问的开发者。它把CGI请求处理、字符串操作、MySQL连接和Socket通信封装为可复用模块涵盖请求方法识别、查询字符串与表单数据解析、HTML响应拼装、SQL访问及套接字收发等基础环节可用于学习动态网页生成与服务器交互流程。压缩包共49个文件、约43KB以17个cpp源文件和17个h头文件为主体另含4个Makefile构建脚本及少量备份文件模块划分覆盖CGI核心、HTML模板、TCP套接字、日志与MD5等工具。已有325人浏览学习。读者可观察CGI程序如何接收请求、连接数据库并组织响应理解C在网络服务端的工程组织方式也能借鉴字符串工具、异常处理和构建脚本的写法适合作为Web开发历史与C网络编程的参考案例。1. 别急着写路由一个 C CGI 库真正替你挡掉的是什么第一次用 C CGI 接表单的人多半会卡在同一个画面本地跑得好好的程序扔进 cgi-bin 就返回 502日志里只有一行 “malformed header”。问题不在业务代码而在你手写了协议。一个 C CGI 库的价值是把「读环境变量、按 CONTENT_LENGTH 读 stdin、拼头部、写 stdout」这套重复且极易写错的胶水封进 Request / Response 两个对象里让你只关心「哪个路径、返回什么」。它适合三类人手上已有大量 C 算法代码想直接暴露成 HTTP 接口的要给内网工具加一个轻量管理页面的以及被脚本语言运行时体积困扰、想用单个二进制交付的。它不适合做高并发 API 网关——读完第 6 章的进程开销数据你自己就能判断边界在哪。2. CGI 进程模型拆开看从环境变量到 stdout 的完整链路2.1 一次请求在 CGI 里走的七步CGI 不是库是约定。宿主 HTTP 服务器收到请求后如果 URL 命中 cgi-bin 之类的映射规则就 fork 一个子进程、exec 你的可执行文件并把请求信息塞进环境变量把请求体塞进子进程的 stdin你的程序把响应头和响应体写到 stdout进程退出服务器把这段输出补上状态行转发给客户端。这条链路上有七个环节每一环都有坑服务器设置REQUEST_METHOD、QUERY_STRING、CONTENT_TYPE、CONTENT_LENGTH、SCRIPT_NAME、SERVER_PROTOCOL、REMOTE_ADDR等变量你的进程启动此时 stdin 是一个管道里面是请求体GET 时为空库读取环境变量构造 Request库按CONTENT_LENGTH指定的字节数从 stdin 读满请求体——注意是「读满指定字节」不是「读到 EOF」路由分发到你的处理函数处理函数往 Response 里写头字段和正文库把Content-Type: ...\r\n\r\n加正文一次性写到 stdoutreturn 0。理解第 4 步和第 7 步能解决后面 80% 的疑难问题。stdin 不读到 EOF 是因为服务器可能复用管道或迟迟不关写端读到 EOF 会直接挂住stdout 必须是「头部 空行 正文」的裸格式不能带 HTTP 状态行因为状态行由服务器生成。2.2 最小可跑二十行接进工程以这类库常见的三层结构Request / Response / App为例不同实现类名会有差异对照头文件改一下名字即可。// main.cpp —— 一个入口注册路由后交给库接管 #include cgi/app.h #include cgi/response.h #include string int main() { cgi::App app; // 注册一个 GET 端点处理函数签名固定为 (const Request, Response) app.route(GET, /hello, [](const cgi::Request req, cgi::Response res) { // query() 第二个参数是默认值参数缺失时不会抛异常也不会返回空指针 std::string name req.query(name, world); res.set_header(Content-Type, text/plain; charsetutf-8); res.body(hello, name \n); }); return app.run(); // 内部解析环境变量 - 分发 - 拼头部 - 写 stdout }编译成独立可执行文件不需要链接任何 Web 框架# 头文件方式引入若该库为 header-only去掉 -L 和 -l 两段即可 $CXX -stdc17 -O2 -Wall -Wextra \ -I./include -L./build \ -o hello.cgi main.cpp -lcgic # CGI 程序必须可执行否则服务器 exec 失败前端只会看到 500 chmod 755 hello.cgi逻辑说明app.route的第一个参数是方法名第二个是SCRIPT_NAME或PATH_INFO匹配的路径具体用哪个要看库的实现——多数库先比SCRIPT_NAME再把PATH_INFO交给路由做子路径匹配这一点在后面讲 RESTful 风格路径时会再遇到。res.body()是追加写入同一个处理函数里调用多次会拼接不要误以为是覆盖。参数方面-O2不是为了性能而是减小二进制体积-Wall -Wextra建议保留这套代码里最容易出现的警告是「有返回值未处理」往往对应真的漏了错误分支。2.3 环境变量到请求对象的映射表库把环境变量包装了一层但底层语义没变。排查问题时对照这张表比翻头文件快CGI 环境变量库里的取法典型常见误用REQUEST_METHODreq.method()大小写敏感别和get比较QUERY_STRINGreq.query(k)原始串未解码需要req.raw_query()CONTENT_TYPEreq.content_type()带; charset和; boundary必须切分CONTENT_LENGTHreq.content_length()无请求体时为空串转数字要判空SCRIPT_NAMEreq.script_name()是 URL 里的程序路径不等于文件系统路径PATH_INFOreq.path_info()可能为空路由要能吃空串REMOTE_ADDRreq.remote_addr()前面有反向代理时是代理地址HTTP_COOKIEreq.cookie(sid)多个 Cookie 以;分隔值里可能有提示CONTENT_LENGTH在 GET 请求里通常不存在std::getenv返回空指针。直接std::stoul(nullptr)是未定义行为必须先判空再转。2.4 不用起服务器也能调本地造环境跑一遍调试 CGI 最省时间的做法是不装任何 Web 服务器自己在 shell 里把环境变量摆出来直接跑可执行文件。这是我每次改完解析逻辑必走的一步比反复重启服务器快一个数量级。# GET查询串要写成百分号编码后的样子模拟浏览器发出来的原始形态 export REQUEST_METHODGET export SCRIPT_NAME/hello export QUERY_STRINGname%E5%B0%8F%E7%8E%8B export SERVER_PROTOCOLHTTP/1.1 ./hello.cgi正确输出应该是「头部 空行 正文」三段形如Content-Type: text/plain; charsetutf-8空一行再是hello, 小王。如果你看到的是完整 HTML 页面或一堆乱码说明 stdout 被污染了去看第 4 章。POST 要额外配对CONTENT_LENGTH而且长度必须按字节算BODYuserabcage30 export REQUEST_METHODPOST export CONTENT_TYPEapplication/x-www-form-urlencoded # 用 wc -c 取字节数${#BODY} 在部分 locale 下数的是字符数 export CONTENT_LENGTH$(printf %s $BODY | wc -c) printf %s $BODY | ./hello.cgi这里有个血泪经验printf %s $BODY必须加引号并显式给格式串。写成echo $BODY会多一个换行符长度对不上程序读满 N 字节后把多出来的\n留在管道里下一次读就错位了——在常驻模式下这类错位会串到别的请求上非常难查。3. 请求解析的三块硬骨头查询串、表单体与 multipart3.1 查询串先切分、后解码顺序反了就出乱码QUERY_STRING是a1b2形式但它没有转义机制保护和——这两个字符在值里一定已经被百分号编码过。所以解析顺序必须是「先按切、再按第一个切、最后统一解码」。反过来先解码值里原本编码的%26会变成真正的一刀切下去字段就散了。#include string #include vector #include utility static int hexval(char c) { if (c 0 c 9) return c - 0; if (c a c f) return c - a 10; if (c A c F) return c - A 10; return -1; // 非法十六进制位 } std::string url_decode(const std::string in) { std::string out; out.reserve(in.size()); for (size_t i 0; i in.size(); i) { char c in[i]; if (c ) { out.push_back( ); continue; } // 表单语义 代表空格 if (c % i 2 in.size()) { int hi hexval(in[i 1]), lo hexval(in[i 2]); if (hi 0 lo 0) { // 只解合法的两位转义 out.push_back(static_castchar(hi * 16 lo)); i 2; continue; } } out.push_back(c); // 非法转义原样保留宁可露出问题也不要丢数据 } return out; } void split_query(const std::string qs, std::vectorstd::pairstd::string, std::string out) { size_t i 0; while (i qs.size()) { size_t amp qs.find(, i); if (amp std::string::npos) amp qs.size(); std::string kv qs.substr(i, amp - i); if (!kv.empty()) { size_t eq kv.find(); // 只切第一个等号 std::string k (eq std::string::npos) ? kv : kv.substr(0, eq); std::string v (eq std::string::npos) ? : kv.substr(eq 1); out.emplace_back(url_decode(k), url_decode(v)); // 解码放在最后 } i amp 1; } }逻辑说明hexval返回 -1 表示不是十六进制位这时不消费、不跳过把%原样写出去避免%zz这种脏数据导致少字节。split_query用i qs.size()而不是是为了让循环体处理最后一个之后的尾段虽然多跑一次空串但被kv.empty()挡住了代价可以接受。参数上这个函数把结果追加到调用方传入的 vector好处是能自然保留重复键——?tagatagb在多数业务里是数组语义用map会悄悄丢一个。取单个值时用first或last需要你在库里明确约定别让上层猜。3.2 表单体按 CONTENT_LENGTH 读别用流到 EOFapplication/x-www-form-urlencoded的请求体和查询串格式完全一样可以直接复用split_query。真正的坑在读取这一步。#include istream #include string #include cstdlib std::string read_body(std::istream in, const char* content_length, size_t max_bytes) { if (content_length nullptr) return {}; // GET / DELETE 常见 char* end nullptr; unsigned long long n std::strtoull(content_length, end, 10); if (end content_length || n 0) return {}; // 空串或非数字 if (n max_bytes) return {}; // 超过上限直接拒别硬读 std::string body; body.resize(static_castsize_t(n)); in.read(body[0], static_caststd::streamsize(n)); body.resize(static_castsize_t(in.gcount())); // 短读按实际字节截断 return body; }逻辑说明三个校验缺一不可。判空指针防的是 GETend content_length防的是abc这种非数字上限校验防的是有人发一个CONTENT_LENGTH: 99999999999让你一次resize把内存吃光这是最廉价的 DoS。resize后立刻用gcount()回填长度是因为客户端可能中途断开read只读到一部分就置 failbit此时按原始 N 截断会把一段未初始化内存当成请求体交给业务代码后果比报错严重得多。参数怎么定max_bytes建议按业务分层纯表单 64KB 到 256KB 足够带文件上传的走 multipart 单独设上限见 3.4。不要用一个全局常量糊住所有端点上传端点和登录端点用同一个限额要么登录被限制要么内存被放大。3.3 multipart边界、CRLF 与文件落盘multipart/form-data是三者里唯一需要自己写状态机的。CONTENT_TYPE里带着boundary----WebKitFormBoundaryXXXX正文用这个边界分隔每一段每段内部再是「头部 空行 数据」。#include string #include vector struct Part { std::string name; // 表单字段名 std::string filename; // 有值说明是文件空则是普通字段 std::string content_type; std::string data; }; std::vectorPart parse_multipart(const std::string body, const std::string boundary) { std::vectorPart parts; const std::string delim -- boundary; size_t pos body.find(delim); if (pos std::string::npos) return parts; while (true) { pos delim.size(); if (body.compare(pos, 2, --) 0) break; // 结束标记 --boundary-- if (body.compare(pos, 2, \r\n) 0) pos 2; // 跳过段间换行 size_t head_end body.find(\r\n\r\n, pos); // 头部与数据的分界 if (head_end std::string::npos) break; std::string headers body.substr(pos, head_end - pos); size_t next body.find(\r\n delim, head_end 4); if (next std::string::npos) break; std::string data body.substr(head_end 4, next - (head_end 4)); Part p; p.data std::move(data); if (size_t n headers.find(name\); n ! std::string::npos) p.name headers.substr(n 6, headers.find(, n 6) - (n 6)); if (size_t f headers.find(filename\); f ! std::string::npos) p.filename headers.substr(f 10, headers.find(, f 10) - (f 10)); if (size_t c headers.find(Content-Type: ); c ! std::string::npos) p.content_type headers.substr(c 14, headers.find(\r\n, c) - (c 14)); parts.push_back(std::move(p)); pos next 2; // 回到下一个 delim 起点 } return parts; }逻辑说明循环顶部先pos delim.size()跨过分隔符本身再判断是不是--结尾pos next 2从\r\n--boundary里跳过 CRLF 回到--boundary起点这样下一轮顶部那次加法正好对齐。文件数据里如果恰好出现\r\n--boundary这段字节会被误判为结束——这是 multipart 协议本身的局限标准做法是让边界串足够随机库在生成时保证这一点。落盘时不要用客户端传来的filename拼路径。它在正文里出现的顺序、编码的字节序列完全由客户端控制。库里一般提供save_as(part, dir)之类的接口底层做法是「在目标目录下用随机名创建文件 → 写入 → 把原始文件名另存为元数据」。参数上filename只用于展示和下载时设置Content-Disposition绝不能参与路径拼接。3.4 上传相关参数怎么定这套参数我在几个内网工具上反复调过可以直接当起点参数建议值依据单请求体上限8MB纯表单 256KB超过后进程常驻内存翻倍收益不抵风险文件落盘阈值1MB小于此值留在内存避免小文件把磁盘 inode 打满读取超时5s10s内网够用公网慢速上传要单独放宽单段文件名长度≤ 255 字节多数文件系统的单段上限临时目录独立分区写满时不影响程序自身日志注意如果库是「一次把整个请求体读进std::string」的实现上面第一行的上限就是硬约束。想支持大文件必须确认它有没有流式接口没有的话只能在服务器层限制请求体大小让超限请求根本进不到你的进程。4. 响应侧最容易翻车的地方头部、状态码与输出缓冲4.1 首行不是 HTTP/1.1 200 OK这是最高频的错误没有之一。写了十年 HTTP 的人第一次写 CGI 也会顺手写上状态行。// 错误写法把完整 HTTP 响应写到 stdout服务器会认为头部格式非法 // std::cout HTTP/1.1 200 OK\r\nContent-Type: text/plain\r\n\r\n; // 正确写法只输出头字段空行之后是正文状态行由服务器生成 std::cout Content-Type: text/plain; charsetutf-8\r\n; std::cout Cache-Control: no-store\r\n; std::cout \r\n; std::cout ok\n;逻辑说明CGI 的输出格式是「若干Name: value\r\n」「\r\n」「正文」。服务器解析到空行后开始转发正文。行尾必须是 CRLF 而不是单个 LF有些服务器宽容有些直接判 502写死成\r\n最省事。头部字段名大小写不敏感但约定俗成都用首字母大写形式。char*字面量里混进\n是第二个隐蔽错法...utf-8\n少了\r看上去本地输出正常一到服务器就报头部非法。用std::cout时建议所有头部一次性拼好再输出减少部分写入的机会。4.2 状态码、重定向与 Cookie 的三种写法CGI 没有状态行可写非 200 的响应靠约定的Status:头传递// 404库里一般封装成 set_status底层就是输出 Status 头 res.set_status(404); // - Status: 404 Not Found\r\n // 302 重定向Location 必须存在且正文可以为空 res.set_status(302); res.set_header(Location, /login?from%2Fadmin); // 有些服务器只认 Location 就自动切 302但显式给 Status 更稳 // Cookie多个值用同名字段重复输出不要自己用逗号拼 res.set_header(Set-Cookie, sidabc123; Path/; HttpOnly; SameSiteLax); res.set_header(Set-Cookie, themedark; Path/; Max-Age86400);逻辑说明Status的值是「三位数字 空格 原因短语」原因短语可以省略但建议带上某些客户端解析器依赖它。Set-Cookie的坑在于它是一个「多值头」——HTTP 规定同名头可以重复出现但Set-Cookie的值内部又用;分隔属性所以绝对不能把两个 Cookie 用逗号或分号拼成一个头否则客户端只会认第一个。多数库的set_header是追加而不是覆盖如果你的库是覆盖语义需要找它对应的add_header接口。HttpOnly和SameSite建议默认带上。内网工具也一样管理页面的会话 Cookie 一旦被 XSS 读走等于把后台交出去。4.3 输出缓冲什么时候必须自己算 Content-Length不写Content-Length时服务器有两种处理方式对 HTTP/1.1 客户端改用 chunked 编码或者先把整个输出缓冲起来自己算长度。前者对客户端友好后者会让你的响应在服务器内存里多待一会儿。需要自己算长度的场景只有三种要显示下载进度条、要输出超大文件、或者客户端是不支持 chunked 的老设备。前两种场景意味着你要走流式输出// 流式输出大响应明确给长度边生成边写写完立刻 flush res.set_header(Content-Type, application/octet-stream); res.set_header(Content-Length, std::to_string(file_size)); res.flush_headers(); // 先落地头部客户端可以开始接收 char buf[64 * 1024]; size_t n; while ((n fread(buf, 1, sizeof(buf), fp)) 0) { res.write(buf, n); // 追加到输出缓冲 res.flush(); // 每块都推出去避免内存堆积 }逻辑说明flush_headers和flush是两个不同动作前者在第一次真正写出时发生且只发生一次后者可以重复调用。如果库没有这两个接口说明它是「全缓冲」实现整份响应在内存里拼完再输出那就老老实实设上限别指望流式。参数上64KB 是管道缓冲区常见的整数倍能减少系统调用次数再大也不会显著变快因为瓶颈在写端。反过来如果你不设Content-Length又手动flush就变成既没长度也没法 chunked 的尴尬状态服务器可能缓冲全部再发也可能出错别这么干。4.4 stdout 只走响应日志全部走 stderrCGI 进程的 stdout 是「协议通道」任何计划外的输出都会污染头部。最常见的三种污染源std::cout调试语句忘了删、某个第三方库往 stdout 打印版本信息、printf和std::cout混用导致缓冲区乱序。#include cstdio #include iostream // 日志一律走 stderr服务器会把它收进错误日志 void log_line(const char* level, const std::string msg) { std::fprintf(stderr, [%s] %s\n, level, msg.c_str()); std::fflush(stderr); // stderr 通常无缓冲显式 flush 更保险 } // 如果必须用 iostream进来第一件事是把它和 C 的缓冲区解绑 int main() { std::ios::sync_with_stdio(false); std::cin.tie(nullptr); log_line(INFO, cgi start); // ... }逻辑说明sync_with_stdio(false)让 C 流不再和 C 的FILE*共享缓冲区速度更快代价是两者输出顺序不再保证——所以要么全用cout要么全用printf别混。日志走 stderr 的好处是它不受 CGI 协议约束服务器会把它和自身错误日志合并出问题时在一处就能看到前后文不用去翻两个文件。注意stderr 写入过多也会阻塞。如果单次请求日志量可能超过管道缓冲区通常 64KB考虑改成写文件而不是 stderr否则进程会卡在写日志上表现为「请求超时但 CPU 空闲」。5. 避坑与排查五条把服务打挂的血泪记录5.1 页面一直转圈最后 504日志里什么都没有现象提交表单后浏览器转圈十几秒服务器返回 504你自己的日志一个字都没打出来。原因处理函数里读请求体读到了 EOF或者根本没读。前者发生在你自己写解析、用while (in.good())循环读管道的时候——服务器不关写端good()一直是真循环永远不结束。后者是POST请求体留在管道里没消费进程退出时某些服务器认为「响应不完整」把连接挂在那里等。解决请求体只按CONTENT_LENGTH读固定字节数读完就停。写成in.read(buf, n)一次读完不要用while循环拼。如果确实需要分块读循环条件必须是「已读字节数 N」而不是流状态。修完后顺手在main开头打一行 stderr 日志确认进程真的起来了。5.2 中文全变问号或者返回的内容被截断现象浏览器显示ä½ å¥½或一串????接口返回的 JSON 少半截。原因三个独立问题撞在一起。环境变量和请求体里的中文是百分号编码的 UTF-8 字节序列你没解码就往外拼Content-Type里没写charsetutf-8浏览器按本地编码猜长度用了字符数而不是字节数中文被按字节截断。解决解码放在切分之后见 3.1所有文本响应显式写charsetutf-8长度一律用std::string::size()它返回的就是字节数。排查时用xxd看实际输出的字节序列%E4%BD%A0解出来应该是E4 BD A0三个字节对得上就说明解码没问题问题在传输层。5.3 小文件正常超过几兆就变成空文件现象上传 100KB 的图成功上传 5MB 的视频得到一个 0 字节文件程序没有任何报错。原因服务器层有请求体上限超限的请求被截断或直接拒绝但你的程序按CONTENT_LENGTH去读时只读到一部分gcount()小于预期你resize回填后得到一个短 bodyparse_multipart找不到结束边界返回空数组——中间没有任何异常因为每一步都「合法」。解决读完立刻校验body.size() n不等就返回 413 并记录实际字节数。同时在服务器配置里把上限调到和业务匹配的值两个数字要对齐否则一边放宽一边收紧排查时会被误导。上传大文件前先确认库有没有流式解析接口没有就别硬撑。5.4 偶发 500重放就正常现象一天出现几次 500同样的请求重发就成功日志干净。原因处理函数里抛了异常App::run()没有兜底异常穿过main导致进程以非零码退出。服务器看到子进程异常终止且没有输出完整头部只能返回 500。因为没输出任何内容你的日志也没来得及 flush。解决在分发那一层加try/catch(...)捕获后输出一个合法的 500 响应带Status: 500头和简单正文并把what()写 stderr。别指望catch(std::exception)能覆盖全部std::string的substr越界抛的是std::out_of_range能被捕获但有些库会抛非标准异常。同时把「进程启动时打一行日志」变成惯例这样能区分「没起来」和「起来后崩了」。5.5 压测一上就大量 CLOSE_WAIT进程数暴涨现象几十个并发就出现大量僵死进程系统负载飙升请求大面积超时。原因一请求一进程的模型下每次请求都 fork exec进程创建本身有成本而如果父进程没有正确回收子进程waitpid会留下僵尸。这不是你的库的问题是 CGI 模型的天花板但表现得很像「库有 bug」。解决先量出单次调用的成本第 6 章有脚本确认是模型问题还是自己代码慢。并发真的上来了只有两条路把业务改成常驻进程FastCGI 模式或者把重活挪到独立服务里CGI 只做转发。别在这个模型上做连接池、线程池之类的优化收益和复杂度不成比例。6. 常驻化与压测把 CGI 的进程开销算清楚再决定6.1 先把 forkexec 的成本量出来在讨论「要不要上常驻」之前得先有一个自己环境下的数字。不需要装压测工具用一段 Python 直接 fork/exec 那个可执行文件模拟服务器的调用方式测出来的就是 CGI 模型的下限。import os, subprocess, statistics, time # 完全模拟服务器设置的环境别漏 GATEWAY_INTERFACE ENV { REQUEST_METHOD: GET, QUERY_STRING: nametest, SCRIPT_NAME: /hello, SERVER_PROTOCOL: HTTP/1.1, GATEWAY_INTERFACE: CGI/1.1, } def once(): t0 time.perf_counter() p subprocess.run([./hello.cgi], env{**os.environ, **ENV}, stdoutsubprocess.PIPE, stderrsubprocess.PIPE, timeout5) dt (time.perf_counter() - t0) * 1000 assert p.returncode 0, p.stderr.decode(utf-8, replace)[:200] assert p.stdout.startswith(bContent-Type), 头部缺失stdout 被污染 return dt samples sorted(once() for _ in range(200)) print(fp50{statistics.median(samples):.2f}ms fp95{samples[int(len(samples) * 0.95)]:.2f}ms fmax{samples[-1]:.2f}ms)逻辑说明once()里两个断言就是前面几章所有坑的自动检查——非零退出码说明异常没兜住stdout 不以Content-Type开头说明头部格式错了或被日志污染。取 200 个样本去掉预热影响看 p95 而不是平均值因为偶发的慢请求才是真正影响体验的。参数上timeout5是必须的没有它一个卡在 READ 上的进程会让脚本永远挂着。在一台普通开发机上这个数字通常在 2 到 8 毫秒之间其中绝大部分是 fork exec 动态链接的开销你的业务代码往往只占零点几毫秒。也就是说如果你的接口需要 200 QPSCGI 模型光进程创建就吃满了这时候讨论代码优化毫无意义。6.2 常驻化改造从 CGI 到 FastCGI 的三处改动常驻化的标准路径是 FastCGI进程启动后不退出与服务器保持一条连接循环接收请求帧。库里如果带了这个模式改造只涉及三处业务代码几乎不动。第一处是请求来源。环境变量变成了帧里的 name-value 对键名基本沿用 CGI 那套REQUEST_METHOD、QUERY_STRING、CONTENT_LENGTH都在库内部把它们塞进同一个 Request 对象所以req.query()这类调用不用改。差别在REMOTE_ADDR可能变成REMOTE_ADDR加HTTP_X_FORWARDED_FOR组合取真实 IP 的逻辑要跟着调整。第二处是输出通道。不再是 stdout而是FCGI_STDOUT帧响应结束时必须发FCGI_END_REQUEST告知服务器这一轮完了。多数库的Response析构或run()内部会处理但如果你手写了输出路径漏发这个帧的表现是「请求一直挂着服务器等不到结束标记」。第三处是状态清理。一请求一进程时全局变量天然干净常驻之后上一次请求写在static里的东西会带到下一次。最典型的是自己缓存的路由表、连接池、错误状态标志。改造时要做的第一件事是把所有static和全局变量过一遍能挪进请求上下文的全挪进去。# 常驻模式启动后用同一段解析逻辑连续发三个请求验证状态没串 export CGI_MODEfastcgi export FCGI_LISTEN127.0.0.1:9001 ./hello.cgi # 用不同的 name 连续请求三次返回必须互不影响6.3 上线前的验证清单改造完别急着压测先把下面这张表逐条走一遍。我踩过的坑里有一半能在这张表上提前拦住检查项通过标准不通过的典型表现头部格式首行是Content-Type:或Status:502、malformed header空请求体GET 不读 stdin直接返回请求挂起直到超时超大请求体超过上限返回 413 且有日志内存暴涨、OOM中文响应字节序列为合法 UTF-8乱码、JSON 解析失败异常路径抛异常仍返回合法 500 响应连接被重置、日志空白重复键?tatb两个值都在只剩一个并发 50无僵尸进程、无 CLOSE_WAIT 堆积进程数持续上涨常驻模式连续 100 次请求结果一致第 N 次开始返回上次的数据最后一行是常驻化最容易被忽略的验证点。做法很简单让处理函数把一个自增计数器写进响应体发 100 次请求如果看到计数器一直增长说明状态确实串了——注意有时候串状态是「预期行为」比如统计总请求数关键是你要知道哪些该串、哪些不该。我一般会把这个自增测试保留在仓库里当回归用例每次改动解析层都跑一遍。还有个更隐蔽的验证点请求中途断开。用脚本发一个 POST声明CONTENT_LENGTH: 1000实际只写 300 字节就关连接。合格的表现是进程在读超时后干净退出或返回 400不合格的表现是永远阻塞在那次read上把连接池里的名额占死。这个场景平时遇不到一旦碰上就是凌晨三点的故障。从那以后我每次接一个新的 C CGI 库第一件事都不是写业务路由而是先用 shell 手工造环境跑通 GET 和 POST 两条路径把头部字节用xxd看一眼再跑一遍并发脚本拿到基线数字。这三步加起来不到二十分钟能省掉后面几天的排查。希望帮到你。本文还有配套的精品资源点击获取
简介这份C CGI库源码包面向希望了解早期Web开发机制、练习C网络编程与数据库访问的开发者。它把CGI请求处理、字符串操作、MySQL连接和Socket通信封装为可复用模块涵盖请求方法识别、查询字符串与表单数据解析、HTML响应拼装、SQL访问及套接字收发等基础环节可用于学习动态网页生成与服务器交互流程。压缩包共49个文件、约43KB以17个cpp源文件和17个h头文件为主体另含4个Makefile构建脚本及少量备份文件模块划分覆盖CGI核心、HTML模板、TCP套接字、日志与MD5等工具。已有325人浏览学习。读者可观察CGI程序如何接收请求、连接数据库并组织响应理解C在网络服务端的工程组织方式也能借鉴字符串工具、异常处理和构建脚本的写法适合作为Web开发历史与C网络编程的参考案例。1. 别急着写路由一个 C CGI 库真正替你挡掉的是什么第一次用 C CGI 接表单的人多半会卡在同一个画面本地跑得好好的程序扔进 cgi-bin 就返回 502日志里只有一行 “malformed header”。问题不在业务代码而在你手写了协议。一个 C CGI 库的价值是把「读环境变量、按 CONTENT_LENGTH 读 stdin、拼头部、写 stdout」这套重复且极易写错的胶水封进 Request / Response 两个对象里让你只关心「哪个路径、返回什么」。它适合三类人手上已有大量 C 算法代码想直接暴露成 HTTP 接口的要给内网工具加一个轻量管理页面的以及被脚本语言运行时体积困扰、想用单个二进制交付的。它不适合做高并发 API 网关——读完第 6 章的进程开销数据你自己就能判断边界在哪。2. CGI 进程模型拆开看从环境变量到 stdout 的完整链路2.1 一次请求在 CGI 里走的七步CGI 不是库是约定。宿主 HTTP 服务器收到请求后如果 URL 命中 cgi-bin 之类的映射规则就 fork 一个子进程、exec 你的可执行文件并把请求信息塞进环境变量把请求体塞进子进程的 stdin你的程序把响应头和响应体写到 stdout进程退出服务器把这段输出补上状态行转发给客户端。这条链路上有七个环节每一环都有坑服务器设置REQUEST_METHOD、QUERY_STRING、CONTENT_TYPE、CONTENT_LENGTH、SCRIPT_NAME、SERVER_PROTOCOL、REMOTE_ADDR等变量你的进程启动此时 stdin 是一个管道里面是请求体GET 时为空库读取环境变量构造 Request库按CONTENT_LENGTH指定的字节数从 stdin 读满请求体——注意是「读满指定字节」不是「读到 EOF」路由分发到你的处理函数处理函数往 Response 里写头字段和正文库把Content-Type: ...\r\n\r\n加正文一次性写到 stdoutreturn 0。理解第 4 步和第 7 步能解决后面 80% 的疑难问题。stdin 不读到 EOF 是因为服务器可能复用管道或迟迟不关写端读到 EOF 会直接挂住stdout 必须是「头部 空行 正文」的裸格式不能带 HTTP 状态行因为状态行由服务器生成。2.2 最小可跑二十行接进工程以这类库常见的三层结构Request / Response / App为例不同实现类名会有差异对照头文件改一下名字即可。// main.cpp —— 一个入口注册路由后交给库接管 #include cgi/app.h #include cgi/response.h #include string int main() { cgi::App app; // 注册一个 GET 端点处理函数签名固定为 (const Request, Response) app.route(GET, /hello, [](const cgi::Request req, cgi::Response res) { // query() 第二个参数是默认值参数缺失时不会抛异常也不会返回空指针 std::string name req.query(name, world); res.set_header(Content-Type, text/plain; charsetutf-8); res.body(hello, name \n); }); return app.run(); // 内部解析环境变量 - 分发 - 拼头部 - 写 stdout }编译成独立可执行文件不需要链接任何 Web 框架# 头文件方式引入若该库为 header-only去掉 -L 和 -l 两段即可 $CXX -stdc17 -O2 -Wall -Wextra \ -I./include -L./build \ -o hello.cgi main.cpp -lcgic # CGI 程序必须可执行否则服务器 exec 失败前端只会看到 500 chmod 755 hello.cgi逻辑说明app.route的第一个参数是方法名第二个是SCRIPT_NAME或PATH_INFO匹配的路径具体用哪个要看库的实现——多数库先比SCRIPT_NAME再把PATH_INFO交给路由做子路径匹配这一点在后面讲 RESTful 风格路径时会再遇到。res.body()是追加写入同一个处理函数里调用多次会拼接不要误以为是覆盖。参数方面-O2不是为了性能而是减小二进制体积-Wall -Wextra建议保留这套代码里最容易出现的警告是「有返回值未处理」往往对应真的漏了错误分支。2.3 环境变量到请求对象的映射表库把环境变量包装了一层但底层语义没变。排查问题时对照这张表比翻头文件快CGI 环境变量库里的取法典型常见误用REQUEST_METHODreq.method()大小写敏感别和get比较QUERY_STRINGreq.query(k)原始串未解码需要req.raw_query()CONTENT_TYPEreq.content_type()带; charset和; boundary必须切分CONTENT_LENGTHreq.content_length()无请求体时为空串转数字要判空SCRIPT_NAMEreq.script_name()是 URL 里的程序路径不等于文件系统路径PATH_INFOreq.path_info()可能为空路由要能吃空串REMOTE_ADDRreq.remote_addr()前面有反向代理时是代理地址HTTP_COOKIEreq.cookie(sid)多个 Cookie 以;分隔值里可能有提示CONTENT_LENGTH在 GET 请求里通常不存在std::getenv返回空指针。直接std::stoul(nullptr)是未定义行为必须先判空再转。2.4 不用起服务器也能调本地造环境跑一遍调试 CGI 最省时间的做法是不装任何 Web 服务器自己在 shell 里把环境变量摆出来直接跑可执行文件。这是我每次改完解析逻辑必走的一步比反复重启服务器快一个数量级。# GET查询串要写成百分号编码后的样子模拟浏览器发出来的原始形态 export REQUEST_METHODGET export SCRIPT_NAME/hello export QUERY_STRINGname%E5%B0%8F%E7%8E%8B export SERVER_PROTOCOLHTTP/1.1 ./hello.cgi正确输出应该是「头部 空行 正文」三段形如Content-Type: text/plain; charsetutf-8空一行再是hello, 小王。如果你看到的是完整 HTML 页面或一堆乱码说明 stdout 被污染了去看第 4 章。POST 要额外配对CONTENT_LENGTH而且长度必须按字节算BODYuserabcage30 export REQUEST_METHODPOST export CONTENT_TYPEapplication/x-www-form-urlencoded # 用 wc -c 取字节数${#BODY} 在部分 locale 下数的是字符数 export CONTENT_LENGTH$(printf %s $BODY | wc -c) printf %s $BODY | ./hello.cgi这里有个血泪经验printf %s $BODY必须加引号并显式给格式串。写成echo $BODY会多一个换行符长度对不上程序读满 N 字节后把多出来的\n留在管道里下一次读就错位了——在常驻模式下这类错位会串到别的请求上非常难查。3. 请求解析的三块硬骨头查询串、表单体与 multipart3.1 查询串先切分、后解码顺序反了就出乱码QUERY_STRING是a1b2形式但它没有转义机制保护和——这两个字符在值里一定已经被百分号编码过。所以解析顺序必须是「先按切、再按第一个切、最后统一解码」。反过来先解码值里原本编码的%26会变成真正的一刀切下去字段就散了。#include string #include vector #include utility static int hexval(char c) { if (c 0 c 9) return c - 0; if (c a c f) return c - a 10; if (c A c F) return c - A 10; return -1; // 非法十六进制位 } std::string url_decode(const std::string in) { std::string out; out.reserve(in.size()); for (size_t i 0; i in.size(); i) { char c in[i]; if (c ) { out.push_back( ); continue; } // 表单语义 代表空格 if (c % i 2 in.size()) { int hi hexval(in[i 1]), lo hexval(in[i 2]); if (hi 0 lo 0) { // 只解合法的两位转义 out.push_back(static_castchar(hi * 16 lo)); i 2; continue; } } out.push_back(c); // 非法转义原样保留宁可露出问题也不要丢数据 } return out; } void split_query(const std::string qs, std::vectorstd::pairstd::string, std::string out) { size_t i 0; while (i qs.size()) { size_t amp qs.find(, i); if (amp std::string::npos) amp qs.size(); std::string kv qs.substr(i, amp - i); if (!kv.empty()) { size_t eq kv.find(); // 只切第一个等号 std::string k (eq std::string::npos) ? kv : kv.substr(0, eq); std::string v (eq std::string::npos) ? : kv.substr(eq 1); out.emplace_back(url_decode(k), url_decode(v)); // 解码放在最后 } i amp 1; } }逻辑说明hexval返回 -1 表示不是十六进制位这时不消费、不跳过把%原样写出去避免%zz这种脏数据导致少字节。split_query用i qs.size()而不是是为了让循环体处理最后一个之后的尾段虽然多跑一次空串但被kv.empty()挡住了代价可以接受。参数上这个函数把结果追加到调用方传入的 vector好处是能自然保留重复键——?tagatagb在多数业务里是数组语义用map会悄悄丢一个。取单个值时用first或last需要你在库里明确约定别让上层猜。3.2 表单体按 CONTENT_LENGTH 读别用流到 EOFapplication/x-www-form-urlencoded的请求体和查询串格式完全一样可以直接复用split_query。真正的坑在读取这一步。#include istream #include string #include cstdlib std::string read_body(std::istream in, const char* content_length, size_t max_bytes) { if (content_length nullptr) return {}; // GET / DELETE 常见 char* end nullptr; unsigned long long n std::strtoull(content_length, end, 10); if (end content_length || n 0) return {}; // 空串或非数字 if (n max_bytes) return {}; // 超过上限直接拒别硬读 std::string body; body.resize(static_castsize_t(n)); in.read(body[0], static_caststd::streamsize(n)); body.resize(static_castsize_t(in.gcount())); // 短读按实际字节截断 return body; }逻辑说明三个校验缺一不可。判空指针防的是 GETend content_length防的是abc这种非数字上限校验防的是有人发一个CONTENT_LENGTH: 99999999999让你一次resize把内存吃光这是最廉价的 DoS。resize后立刻用gcount()回填长度是因为客户端可能中途断开read只读到一部分就置 failbit此时按原始 N 截断会把一段未初始化内存当成请求体交给业务代码后果比报错严重得多。参数怎么定max_bytes建议按业务分层纯表单 64KB 到 256KB 足够带文件上传的走 multipart 单独设上限见 3.4。不要用一个全局常量糊住所有端点上传端点和登录端点用同一个限额要么登录被限制要么内存被放大。3.3 multipart边界、CRLF 与文件落盘multipart/form-data是三者里唯一需要自己写状态机的。CONTENT_TYPE里带着boundary----WebKitFormBoundaryXXXX正文用这个边界分隔每一段每段内部再是「头部 空行 数据」。#include string #include vector struct Part { std::string name; // 表单字段名 std::string filename; // 有值说明是文件空则是普通字段 std::string content_type; std::string data; }; std::vectorPart parse_multipart(const std::string body, const std::string boundary) { std::vectorPart parts; const std::string delim -- boundary; size_t pos body.find(delim); if (pos std::string::npos) return parts; while (true) { pos delim.size(); if (body.compare(pos, 2, --) 0) break; // 结束标记 --boundary-- if (body.compare(pos, 2, \r\n) 0) pos 2; // 跳过段间换行 size_t head_end body.find(\r\n\r\n, pos); // 头部与数据的分界 if (head_end std::string::npos) break; std::string headers body.substr(pos, head_end - pos); size_t next body.find(\r\n delim, head_end 4); if (next std::string::npos) break; std::string data body.substr(head_end 4, next - (head_end 4)); Part p; p.data std::move(data); if (size_t n headers.find(name\); n ! std::string::npos) p.name headers.substr(n 6, headers.find(, n 6) - (n 6)); if (size_t f headers.find(filename\); f ! std::string::npos) p.filename headers.substr(f 10, headers.find(, f 10) - (f 10)); if (size_t c headers.find(Content-Type: ); c ! std::string::npos) p.content_type headers.substr(c 14, headers.find(\r\n, c) - (c 14)); parts.push_back(std::move(p)); pos next 2; // 回到下一个 delim 起点 } return parts; }逻辑说明循环顶部先pos delim.size()跨过分隔符本身再判断是不是--结尾pos next 2从\r\n--boundary里跳过 CRLF 回到--boundary起点这样下一轮顶部那次加法正好对齐。文件数据里如果恰好出现\r\n--boundary这段字节会被误判为结束——这是 multipart 协议本身的局限标准做法是让边界串足够随机库在生成时保证这一点。落盘时不要用客户端传来的filename拼路径。它在正文里出现的顺序、编码的字节序列完全由客户端控制。库里一般提供save_as(part, dir)之类的接口底层做法是「在目标目录下用随机名创建文件 → 写入 → 把原始文件名另存为元数据」。参数上filename只用于展示和下载时设置Content-Disposition绝不能参与路径拼接。3.4 上传相关参数怎么定这套参数我在几个内网工具上反复调过可以直接当起点参数建议值依据单请求体上限8MB纯表单 256KB超过后进程常驻内存翻倍收益不抵风险文件落盘阈值1MB小于此值留在内存避免小文件把磁盘 inode 打满读取超时5s10s内网够用公网慢速上传要单独放宽单段文件名长度≤ 255 字节多数文件系统的单段上限临时目录独立分区写满时不影响程序自身日志注意如果库是「一次把整个请求体读进std::string」的实现上面第一行的上限就是硬约束。想支持大文件必须确认它有没有流式接口没有的话只能在服务器层限制请求体大小让超限请求根本进不到你的进程。4. 响应侧最容易翻车的地方头部、状态码与输出缓冲4.1 首行不是 HTTP/1.1 200 OK这是最高频的错误没有之一。写了十年 HTTP 的人第一次写 CGI 也会顺手写上状态行。// 错误写法把完整 HTTP 响应写到 stdout服务器会认为头部格式非法 // std::cout HTTP/1.1 200 OK\r\nContent-Type: text/plain\r\n\r\n; // 正确写法只输出头字段空行之后是正文状态行由服务器生成 std::cout Content-Type: text/plain; charsetutf-8\r\n; std::cout Cache-Control: no-store\r\n; std::cout \r\n; std::cout ok\n;逻辑说明CGI 的输出格式是「若干Name: value\r\n」「\r\n」「正文」。服务器解析到空行后开始转发正文。行尾必须是 CRLF 而不是单个 LF有些服务器宽容有些直接判 502写死成\r\n最省事。头部字段名大小写不敏感但约定俗成都用首字母大写形式。char*字面量里混进\n是第二个隐蔽错法...utf-8\n少了\r看上去本地输出正常一到服务器就报头部非法。用std::cout时建议所有头部一次性拼好再输出减少部分写入的机会。4.2 状态码、重定向与 Cookie 的三种写法CGI 没有状态行可写非 200 的响应靠约定的Status:头传递// 404库里一般封装成 set_status底层就是输出 Status 头 res.set_status(404); // - Status: 404 Not Found\r\n // 302 重定向Location 必须存在且正文可以为空 res.set_status(302); res.set_header(Location, /login?from%2Fadmin); // 有些服务器只认 Location 就自动切 302但显式给 Status 更稳 // Cookie多个值用同名字段重复输出不要自己用逗号拼 res.set_header(Set-Cookie, sidabc123; Path/; HttpOnly; SameSiteLax); res.set_header(Set-Cookie, themedark; Path/; Max-Age86400);逻辑说明Status的值是「三位数字 空格 原因短语」原因短语可以省略但建议带上某些客户端解析器依赖它。Set-Cookie的坑在于它是一个「多值头」——HTTP 规定同名头可以重复出现但Set-Cookie的值内部又用;分隔属性所以绝对不能把两个 Cookie 用逗号或分号拼成一个头否则客户端只会认第一个。多数库的set_header是追加而不是覆盖如果你的库是覆盖语义需要找它对应的add_header接口。HttpOnly和SameSite建议默认带上。内网工具也一样管理页面的会话 Cookie 一旦被 XSS 读走等于把后台交出去。4.3 输出缓冲什么时候必须自己算 Content-Length不写Content-Length时服务器有两种处理方式对 HTTP/1.1 客户端改用 chunked 编码或者先把整个输出缓冲起来自己算长度。前者对客户端友好后者会让你的响应在服务器内存里多待一会儿。需要自己算长度的场景只有三种要显示下载进度条、要输出超大文件、或者客户端是不支持 chunked 的老设备。前两种场景意味着你要走流式输出// 流式输出大响应明确给长度边生成边写写完立刻 flush res.set_header(Content-Type, application/octet-stream); res.set_header(Content-Length, std::to_string(file_size)); res.flush_headers(); // 先落地头部客户端可以开始接收 char buf[64 * 1024]; size_t n; while ((n fread(buf, 1, sizeof(buf), fp)) 0) { res.write(buf, n); // 追加到输出缓冲 res.flush(); // 每块都推出去避免内存堆积 }逻辑说明flush_headers和flush是两个不同动作前者在第一次真正写出时发生且只发生一次后者可以重复调用。如果库没有这两个接口说明它是「全缓冲」实现整份响应在内存里拼完再输出那就老老实实设上限别指望流式。参数上64KB 是管道缓冲区常见的整数倍能减少系统调用次数再大也不会显著变快因为瓶颈在写端。反过来如果你不设Content-Length又手动flush就变成既没长度也没法 chunked 的尴尬状态服务器可能缓冲全部再发也可能出错别这么干。4.4 stdout 只走响应日志全部走 stderrCGI 进程的 stdout 是「协议通道」任何计划外的输出都会污染头部。最常见的三种污染源std::cout调试语句忘了删、某个第三方库往 stdout 打印版本信息、printf和std::cout混用导致缓冲区乱序。#include cstdio #include iostream // 日志一律走 stderr服务器会把它收进错误日志 void log_line(const char* level, const std::string msg) { std::fprintf(stderr, [%s] %s\n, level, msg.c_str()); std::fflush(stderr); // stderr 通常无缓冲显式 flush 更保险 } // 如果必须用 iostream进来第一件事是把它和 C 的缓冲区解绑 int main() { std::ios::sync_with_stdio(false); std::cin.tie(nullptr); log_line(INFO, cgi start); // ... }逻辑说明sync_with_stdio(false)让 C 流不再和 C 的FILE*共享缓冲区速度更快代价是两者输出顺序不再保证——所以要么全用cout要么全用printf别混。日志走 stderr 的好处是它不受 CGI 协议约束服务器会把它和自身错误日志合并出问题时在一处就能看到前后文不用去翻两个文件。注意stderr 写入过多也会阻塞。如果单次请求日志量可能超过管道缓冲区通常 64KB考虑改成写文件而不是 stderr否则进程会卡在写日志上表现为「请求超时但 CPU 空闲」。5. 避坑与排查五条把服务打挂的血泪记录5.1 页面一直转圈最后 504日志里什么都没有现象提交表单后浏览器转圈十几秒服务器返回 504你自己的日志一个字都没打出来。原因处理函数里读请求体读到了 EOF或者根本没读。前者发生在你自己写解析、用while (in.good())循环读管道的时候——服务器不关写端good()一直是真循环永远不结束。后者是POST请求体留在管道里没消费进程退出时某些服务器认为「响应不完整」把连接挂在那里等。解决请求体只按CONTENT_LENGTH读固定字节数读完就停。写成in.read(buf, n)一次读完不要用while循环拼。如果确实需要分块读循环条件必须是「已读字节数 N」而不是流状态。修完后顺手在main开头打一行 stderr 日志确认进程真的起来了。5.2 中文全变问号或者返回的内容被截断现象浏览器显示ä½ å¥½或一串????接口返回的 JSON 少半截。原因三个独立问题撞在一起。环境变量和请求体里的中文是百分号编码的 UTF-8 字节序列你没解码就往外拼Content-Type里没写charsetutf-8浏览器按本地编码猜长度用了字符数而不是字节数中文被按字节截断。解决解码放在切分之后见 3.1所有文本响应显式写charsetutf-8长度一律用std::string::size()它返回的就是字节数。排查时用xxd看实际输出的字节序列%E4%BD%A0解出来应该是E4 BD A0三个字节对得上就说明解码没问题问题在传输层。5.3 小文件正常超过几兆就变成空文件现象上传 100KB 的图成功上传 5MB 的视频得到一个 0 字节文件程序没有任何报错。原因服务器层有请求体上限超限的请求被截断或直接拒绝但你的程序按CONTENT_LENGTH去读时只读到一部分gcount()小于预期你resize回填后得到一个短 bodyparse_multipart找不到结束边界返回空数组——中间没有任何异常因为每一步都「合法」。解决读完立刻校验body.size() n不等就返回 413 并记录实际字节数。同时在服务器配置里把上限调到和业务匹配的值两个数字要对齐否则一边放宽一边收紧排查时会被误导。上传大文件前先确认库有没有流式解析接口没有就别硬撑。5.4 偶发 500重放就正常现象一天出现几次 500同样的请求重发就成功日志干净。原因处理函数里抛了异常App::run()没有兜底异常穿过main导致进程以非零码退出。服务器看到子进程异常终止且没有输出完整头部只能返回 500。因为没输出任何内容你的日志也没来得及 flush。解决在分发那一层加try/catch(...)捕获后输出一个合法的 500 响应带Status: 500头和简单正文并把what()写 stderr。别指望catch(std::exception)能覆盖全部std::string的substr越界抛的是std::out_of_range能被捕获但有些库会抛非标准异常。同时把「进程启动时打一行日志」变成惯例这样能区分「没起来」和「起来后崩了」。5.5 压测一上就大量 CLOSE_WAIT进程数暴涨现象几十个并发就出现大量僵死进程系统负载飙升请求大面积超时。原因一请求一进程的模型下每次请求都 fork exec进程创建本身有成本而如果父进程没有正确回收子进程waitpid会留下僵尸。这不是你的库的问题是 CGI 模型的天花板但表现得很像「库有 bug」。解决先量出单次调用的成本第 6 章有脚本确认是模型问题还是自己代码慢。并发真的上来了只有两条路把业务改成常驻进程FastCGI 模式或者把重活挪到独立服务里CGI 只做转发。别在这个模型上做连接池、线程池之类的优化收益和复杂度不成比例。6. 常驻化与压测把 CGI 的进程开销算清楚再决定6.1 先把 forkexec 的成本量出来在讨论「要不要上常驻」之前得先有一个自己环境下的数字。不需要装压测工具用一段 Python 直接 fork/exec 那个可执行文件模拟服务器的调用方式测出来的就是 CGI 模型的下限。import os, subprocess, statistics, time # 完全模拟服务器设置的环境别漏 GATEWAY_INTERFACE ENV { REQUEST_METHOD: GET, QUERY_STRING: nametest, SCRIPT_NAME: /hello, SERVER_PROTOCOL: HTTP/1.1, GATEWAY_INTERFACE: CGI/1.1, } def once(): t0 time.perf_counter() p subprocess.run([./hello.cgi], env{**os.environ, **ENV}, stdoutsubprocess.PIPE, stderrsubprocess.PIPE, timeout5) dt (time.perf_counter() - t0) * 1000 assert p.returncode 0, p.stderr.decode(utf-8, replace)[:200] assert p.stdout.startswith(bContent-Type), 头部缺失stdout 被污染 return dt samples sorted(once() for _ in range(200)) print(fp50{statistics.median(samples):.2f}ms fp95{samples[int(len(samples) * 0.95)]:.2f}ms fmax{samples[-1]:.2f}ms)逻辑说明once()里两个断言就是前面几章所有坑的自动检查——非零退出码说明异常没兜住stdout 不以Content-Type开头说明头部格式错了或被日志污染。取 200 个样本去掉预热影响看 p95 而不是平均值因为偶发的慢请求才是真正影响体验的。参数上timeout5是必须的没有它一个卡在 READ 上的进程会让脚本永远挂着。在一台普通开发机上这个数字通常在 2 到 8 毫秒之间其中绝大部分是 fork exec 动态链接的开销你的业务代码往往只占零点几毫秒。也就是说如果你的接口需要 200 QPSCGI 模型光进程创建就吃满了这时候讨论代码优化毫无意义。6.2 常驻化改造从 CGI 到 FastCGI 的三处改动常驻化的标准路径是 FastCGI进程启动后不退出与服务器保持一条连接循环接收请求帧。库里如果带了这个模式改造只涉及三处业务代码几乎不动。第一处是请求来源。环境变量变成了帧里的 name-value 对键名基本沿用 CGI 那套REQUEST_METHOD、QUERY_STRING、CONTENT_LENGTH都在库内部把它们塞进同一个 Request 对象所以req.query()这类调用不用改。差别在REMOTE_ADDR可能变成REMOTE_ADDR加HTTP_X_FORWARDED_FOR组合取真实 IP 的逻辑要跟着调整。第二处是输出通道。不再是 stdout而是FCGI_STDOUT帧响应结束时必须发FCGI_END_REQUEST告知服务器这一轮完了。多数库的Response析构或run()内部会处理但如果你手写了输出路径漏发这个帧的表现是「请求一直挂着服务器等不到结束标记」。第三处是状态清理。一请求一进程时全局变量天然干净常驻之后上一次请求写在static里的东西会带到下一次。最典型的是自己缓存的路由表、连接池、错误状态标志。改造时要做的第一件事是把所有static和全局变量过一遍能挪进请求上下文的全挪进去。# 常驻模式启动后用同一段解析逻辑连续发三个请求验证状态没串 export CGI_MODEfastcgi export FCGI_LISTEN127.0.0.1:9001 ./hello.cgi # 用不同的 name 连续请求三次返回必须互不影响6.3 上线前的验证清单改造完别急着压测先把下面这张表逐条走一遍。我踩过的坑里有一半能在这张表上提前拦住检查项通过标准不通过的典型表现头部格式首行是Content-Type:或Status:502、malformed header空请求体GET 不读 stdin直接返回请求挂起直到超时超大请求体超过上限返回 413 且有日志内存暴涨、OOM中文响应字节序列为合法 UTF-8乱码、JSON 解析失败异常路径抛异常仍返回合法 500 响应连接被重置、日志空白重复键?tatb两个值都在只剩一个并发 50无僵尸进程、无 CLOSE_WAIT 堆积进程数持续上涨常驻模式连续 100 次请求结果一致第 N 次开始返回上次的数据最后一行是常驻化最容易被忽略的验证点。做法很简单让处理函数把一个自增计数器写进响应体发 100 次请求如果看到计数器一直增长说明状态确实串了——注意有时候串状态是「预期行为」比如统计总请求数关键是你要知道哪些该串、哪些不该。我一般会把这个自增测试保留在仓库里当回归用例每次改动解析层都跑一遍。还有个更隐蔽的验证点请求中途断开。用脚本发一个 POST声明CONTENT_LENGTH: 1000实际只写 300 字节就关连接。合格的表现是进程在读超时后干净退出或返回 400不合格的表现是永远阻塞在那次read上把连接池里的名额占死。这个场景平时遇不到一旦碰上就是凌晨三点的故障。从那以后我每次接一个新的 C CGI 库第一件事都不是写业务路由而是先用 shell 手工造环境跑通 GET 和 POST 两条路径把头部字节用xxd看一眼再跑一遍并发脚本拿到基线数字。这三步加起来不到二十分钟能省掉后面几天的排查。希望帮到你。本文还有配套的精品资源点击获取
