1. 为什么要在 Ubuntu 20.04.3 LTS 上折腾 CGI 运行环境先把话说在前头CGI 这门技术确实有年头了1993 年就随着早期 Web 服务器进入大众视野后来被 FastCGI、WSGI、各种应用服务器和反向代理架构挤到了边缘。但边缘不等于没用。我在实际工作中至少遇到过三类场景仍然需要把 CGI 跑起来一是维护十几年前遗留的运维面板或监控页面它们就是一堆.cgi脚本重写成本远高于直接跑起来二是教学和实验环境需要让学生直观理解“Web 服务器如何把请求交给外部程序处理”这件事CGI 是最朴素的模型三是一些轻量级内部工具用 Shell 或 Perl 写个 CGI 脚本几十行就能解决表单提交和结果展示比引入一整套框架省事得多。Ubuntu 20.04.3 LTS 是 20.04 系列的一个点版本底层依然是 Focal Fossa官方支持周期到 2025 年 4 月标准支持ESM 还能再延五年。它的软件源里 Apache2 是 2.4.x 系列默认就带mod_cgi模块配置 CGI 不需要额外编译这是它比某些精简发行版省心的地方。这篇文章要解决的问题很具体在一台干净的 Ubuntu 20.04.3 LTS 上从零把 CGI 运行环境搭起来让浏览器访问一个.cgi地址时能正确执行并返回结果而不是把源码当文本吐出来。适合谁看如果你是刚接触 Linux 服务端、想搞明白 Web 服务器和外部程序怎么协作的新手这篇可以当作一条完整的实操路径如果你是有经验但很久没碰 CGI 的老手这里面的权限坑、目录映射坑、SELinux/AppArmor 相关的排查思路应该能帮你省下重新踩一遍的时间。全文基于 Apache2 mod_cgi这条最主流、最稳妥的路线展开同时会说明为什么我不推荐一上来就用 Nginx 做 CGI——Nginx 本身不支持原生 CGI必须借助额外的 FastCGI 包装层对新手来说多一层就多一堆变量要调。需要提前说明的是下面所有操作都在一台全新安装的 Ubuntu 20.04.3 LTS 虚拟机上验证过网络环境是普通内网没有做任何特殊网络配置。涉及的命令和配置我会给出完整内容你可以直接照着敲。文中出现的路径、脚本名、测试用例都是通用示例你可以按自己的项目替换。2. 环境准备与软件选型为什么是 Apache2 而不是别的2.1 先更新系统并确认版本信息动手之前先做两件事确认系统版本更新软件包索引。很多人跳过更新这一步结果装出来的 Apache 版本和文档对不上配置语法有细微差异排查起来很费劲。lsb_release -a正常输出里应该能看到Description: Ubuntu 20.04.3 LTS和Codename: focal。如果版本号不是 20.04.x后面的配置大体通用但个别路径可能不同需要你自己核对。接着更新索引并升级已有包sudo apt update sudo apt upgrade -y提示apt upgrade在有内核更新时会提示是否重启相关服务CGI 环境搭建阶段可以直接回车接受默认选项搭完再统一重启一次系统更干净。2.2 Apache2 与 Nginx 在 CGI 场景下的取舍这是选型环节最该讲清楚的地方。Nginx 处理静态文件和反向代理的性能确实优秀但它从设计上就不支持直接执行 CGI 程序官方立场是让你用 FastCGI。要在 Nginx 上跑传统 CGI得额外装fcgiwrap这类包装程序再由 Nginx 把请求转发给它。多出来的这一层意味着多一个服务要管理、多一组 socket 权限要配、多一类 502 错误要排查。Apache2 则内置了mod_cgi加载模块、指定目录、给执行权限三步就能跑通。对于“我就是要让一个.cgi脚本能被访问执行”这个需求Apache2 的路径最短、变量最少、出错面最小。所以本文选 Apache2不是因为它更先进而是因为它在这个具体任务上更直接。对比项Apache2 mod_cgiNginx fcgiwrap原生 CGI 支持内置模块加载即用不支持需外部包装配置步骤3 步左右5 步以上含 socket 权限常见故障点权限、目录映射502、socket 权限、用户不匹配适合场景遗留脚本、教学、轻量工具已有 Nginx 架构且必须兼容 CGI2.3 安装 Apache2 及必要组件安装命令很直接sudo apt install -y apache2 apache2-utilsapache2-utils里带了htpasswd、ab等工具后面做访问控制和压测会用到建议一起装上。装完后 Apache 会自动启动用下面命令确认状态sudo systemctl status apache2看到active (running)就对了。此时在浏览器访问这台机器的 IP应该能看到 Apache 的默认欢迎页。如果访问不了先检查防火墙sudo ufw status如果ufw是启用状态且没放行 80 端口执行sudo ufw allow 80/tcp sudo ufw allow 443/tcp注意生产环境不要图省事直接ufw disable放行具体端口比关掉整个防火墙安全得多。这是我在早期运维里吃过亏的地方——图快关防火墙结果机器暴露在公网被扫教训很直接。3. 核心配置拆解让 mod_cgi 真正干活3.1 理解 CGI 目录的两种映射方式Apache 处理 CGI 有两种典型配置思路理解它们的区别能帮你少走弯路。第一种是ScriptAlias 方式。它把 URL 路径直接映射到一个专门存放 CGI 脚本的目录并且自动给这个目录加上“可执行”语义。也就是说只要脚本放在这个目录里Apache 就认为它是程序而不是普通文件。这是最传统、最省心的方式适合脚本集中管理的场景。第二种是Options ExecCGI 方式。它不要求脚本放在特定目录而是在某个普通目录上开启执行权限再通过AddHandler把.cgi后缀关联到 CGI 处理器。这种方式更灵活适合脚本和静态资源混放的场景但配置项更多容易漏。我一般推荐新手先用 ScriptAlias跑通之后再按需切换到第二种。下面两种都会讲你可以按自己的情况选。3.2 加载模块并确认状态Ubuntu 的 Apache2 用a2enmod/a2disconf这套工具管理模块比手动改配置文件再重启要规范。先确认mod_cgi是否已加载apache2ctl -M | grep cgi如果输出里有cgi_module (shared)说明已经加载。如果没有执行sudo a2enmod cgi sudo systemctl restart apache2a2enmod的本质是在/etc/apache2/mods-enabled/下创建指向mods-available/的软链接这样配置和模块文件分离升级时不会互相覆盖。理解这一点以后你手动排查模块问题时就知道该去哪个目录看。3.3 用 ScriptAlias 配置一个 CGI 目录打开 CGI 相关配置文件。Ubuntu 默认把 CGI 配置放在/etc/apache2/conf-available/下但更常见的做法是直接编辑站点配置或新建一个独立配置文件。我倾向于新建独立文件便于管理和回滚sudo nano /etc/apache2/conf-available/cgi-bin.conf写入以下内容ScriptAlias /cgi-bin/ /usr/lib/cgi-bin/ Directory /usr/lib/cgi-bin AllowOverride None Options ExecCGI -MultiViews SymLinksIfOwnerMatch Require all granted /Directory逐行解释一下这些参数不是随便写的ScriptAlias /cgi-bin/ /usr/lib/cgi-bin/把 URL 里的/cgi-bin/映射到文件系统的/usr/lib/cgi-bin/。注意结尾的斜杠两边都要有少一个就可能导致路径拼接错误。AllowOverride None禁止该目录下的.htaccess覆盖配置。CGI 目录通常不需要用户自定义配置关掉能减少一层潜在风险。Options ExecCGI -MultiViews SymLinksIfOwnerMatch开启执行权限关闭 MultiViews避免 URL 模糊匹配带来的意外行为符号链接仅在属主匹配时允许。Require all granted允许所有来源访问。生产环境如果要做访问控制这里换成具体的 IP 段或配合认证。启用配置并重载sudo a2enconf cgi-bin sudo systemctl reload apache2提示reload比restart温和它不会中断正在处理的连接。改配置优先用reload只有模块增删这种结构性变更才需要restart。3.4 用 Options ExecCGI 的灵活方式如果你不想把脚本都塞进/usr/lib/cgi-bin/可以在站点配置里对某个目录单独开权限。比如你有一个/var/www/mytools/目录里面既有 HTML 又有.cgiDirectory /var/www/mytools Options ExecCGI AddHandler cgi-script .cgi .pl .sh Require all granted /DirectoryAddHandler cgi-script .cgi .pl .sh这行的意思是凡是这些后缀的文件都交给 CGI 处理器执行。这里我特意把.sh也加进去因为很多内部工具就是 Shell 脚本。但要注意后缀越多误执行的风险越大生产环境建议只保留你真正需要的后缀。两种方式不要在同一目录上叠加使用否则行为会变得难以预测。选一种配清楚就够了。4. 实操全流程从写脚本到浏览器验证4.1 写第一个 CGI 脚本并设置权限在/usr/lib/cgi-bin/下创建一个测试脚本sudo nano /usr/lib/cgi-bin/hello.cgi内容如下#!/bin/bash echo Content-Type: text/html echo echo htmlheadtitleCGI Test/title/headbody echo h1CGI is working/h1 echo pCurrent time: $(date)/p echo pServer: $SERVER_SOFTWARE/p echo pClient: $REMOTE_ADDR/p echo /body/html这个脚本虽短但包含了 CGI 的几个关键点值得逐条说清楚第一行 shebang#!/bin/bash必须存在且路径正确。Apache 执行脚本时不会猜你用什么解释器它完全依赖这一行。写错路径脚本直接 500。Content-Type 头必须输出后面跟一个空行。这个空行是 HTTP 头和正文的分界少了它浏览器会把整个输出当正文或者服务器报错。这是新手最常犯的错误没有之一。环境变量如$SERVER_SOFTWARE、$REMOTE_ADDR是 Apache 在执行脚本前注入的CGI 协议规定了一整套标准变量脚本可以直接读取。这也是 CGI 模型直观的地方——请求信息通过环境变量传递响应通过标准输出返回。给脚本加执行权限sudo chmod x /usr/lib/cgi-bin/hello.cgi注意权限要加在文件上不是目录上。目录需要的是可进入权限x文件需要的是可执行权限。两者混淆会导致“目录能访问但脚本不执行”或“脚本能执行但目录列不出来”这类怪问题。4.2 权限与属主的那些坑Apache 在 Ubuntu 下默认以www-data用户运行。脚本要能被它执行需要满足文件对www-data或其所属组有执行权限。上面用chmod x给所有用户加了执行权限简单直接。但更规范的做法是把脚本属主设为www-data或把www-data加入脚本所属组sudo chown www-data:www-data /usr/lib/cgi-bin/hello.cgi sudo chmod 755 /usr/lib/cgi-bin/hello.cgi755的含义是属主可读写执行组和其他用户可读可执行。对 CGI 脚本来说这个权限足够不要给777那等于把脚本暴露给任何能登录的用户修改。还有一个容易忽略的点脚本所在目录的每一级父目录www-data都必须有执行权限否则它连进都进不去。/usr/lib/cgi-bin/默认权限通常是755一般没问题但如果你自己建了嵌套目录记得逐级检查。4.3 浏览器验证与命令行验证配置和脚本都就位后浏览器访问http://你的服务器IP/cgi-bin/hello.cgi如果看到 “CGI is working” 和当前时间说明整条链路通了。如果没通先别急着改配置用命令行从服务器本机验证能快速定位问题在哪一层curl -i http://localhost/cgi-bin/hello.cgi-i参数会显示响应头。如果返回200且正文正确说明服务端没问题问题在浏览器或网络如果返回500看 Apache 错误日志sudo tail -f /var/log/apache2/error.log日志会明确告诉你失败原因比如 “Premature end of script headers” 通常意味着脚本没输出正确的 Content-Type 头或者脚本本身执行报错。养成看日志的习惯比盲目改配置高效十倍。4.4 一个更实用的表单处理示例光跑个 hello 不够说明问题来个能接收表单输入的脚本更贴近真实用途。先写一个 HTML 表单页面放在/var/www/html/form.html!DOCTYPE html html headmeta charsetutf-8titleCGI Form/title/head body form action/cgi-bin/echo.cgi methodpost input typetext nameusername placeholder输入名字 input typesubmit value提交 /form /body /html再写处理脚本/usr/lib/cgi-bin/echo.cgi#!/bin/bash echo Content-Type: text/html echo read -n $CONTENT_LENGTH POST_DATA echo htmlbody echo h2收到数据/h2 echo pre$POST_DATA/pre echo /body/html这里的关键是read -n $CONTENT_LENGTH。POST 请求的数据通过标准输入传给 CGI 脚本长度由环境变量CONTENT_LENGTH给出。不读这个长度脚本可能读不到完整数据或阻塞。这是 CGI 处理 POST 的标准做法值得记住。提示上面这个示例为了演示简洁没有做输入转义。真实环境里把用户输入直接回显到 HTML 是有风险的至少要做 HTML 实体转义否则可能被注入脚本。这一点在内部工具里也常被忽视务必留意。5. 常见问题排查与避坑经验5.1 高频故障速查表下面这张表是我这些年遇到最多的 CGI 问题按现象归类方便你对照排查现象可能原因排查方向浏览器显示脚本源码mod_cgi 未加载或目录未开 ExecCGI检查apache2ctl -M和目录 Options500 Internal Server Error脚本无执行权限、shebang 错误、缺 Content-Type看 error.log逐项核对403 Forbidden目录权限不足、Require 配置限制检查目录逐级权限和 Require 指令404 Not FoundScriptAlias 路径拼写错误核对 URL 与文件系统路径映射脚本执行但输出为空脚本内部报错被吞、输出缓冲问题手动命令行执行脚本看报错POST 数据读不到未按 CONTENT_LENGTH 读取检查 read 逻辑5.2 几个只有踩过才知道的细节第一脚本里的相对路径不可靠。CGI 脚本执行时的工作目录不一定是脚本所在目录可能是 Apache 的某个工作目录。所以脚本里引用文件一律用绝对路径或者用$(dirname $0)动态取脚本目录。我早期写过一个脚本本地测试好好的部署后读配置文件失败查了半天才发现是工作目录变了。第二输出缓冲会骗你。有些语言比如 Perl默认对标准输出做缓冲脚本报错时错误信息可能和正常输出混在一起导致 HTTP 头解析失败。解决办法是在脚本里显式关闭缓冲或者确保错误信息输出到标准错误而不是标准输出。Shell 脚本相对简单但如果你调用外部命令也要注意它们的输出流向。第三环境变量比你想的少。CGI 执行时的环境变量是 Apache 精心挑选后注入的不是你登录 shell 的那一套。PATH可能很短导致脚本里调用的命令找不到。稳妥做法是在脚本开头显式设置PATHexport PATH/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin这一行能解决相当一部分“命令行能跑、CGI 里跑不了”的诡异问题。第四别在 CGI 目录放敏感文件。ScriptAlias 映射的目录Apache 会尝试执行里面的东西。如果你把配置文件、备份文件也丢进去轻则报错重则泄露内容。CGI 目录就只放脚本干干净净。5.3 日志是你的第一手线索Apache 的日志分两块access.log记录每个请求的结果码error.log记录错误详情。排查时两个都要看。access.log里如果某个请求返回 500去error.log找对应时间点的记录通常会有明确的错误描述。我习惯用tail -f实时盯着 error.log然后刷新浏览器错误信息立刻跳出来比猜快得多。如果日志里信息不够可以临时提高日志级别。在站点配置里加LogLevel debug然后reload。debug 级别会输出大量细节包括模块加载、请求处理流程。排查完记得改回warn否则日志会迅速膨胀。6. 安全加固与后续扩展方向6.1 最小化的安全措施CGI 的本质是让 Web 服务器执行外部程序这天然带有风险。哪怕只是内部工具也建议做几件基本的事。一是限制访问来源。如果只有内网用把Require all granted换成具体网段Require ip 192.168.1.0/24二是给 CGI 目录单独设限禁止列目录、禁止覆盖Directory /usr/lib/cgi-bin Options ExecCGI -Indexes AllowOverride None /Directory-Indexes能防止别人直接访问目录时看到文件列表减少信息暴露。三是脚本输入一律校验。CGI 脚本收到的所有数据都来自外部包括环境变量和标准输入。不要假设它们是干净的。Shell 脚本里尤其注意命令注入凡是拼接到命令里的变量都要引号包裹并做校验。6.2 从 CGI 平滑过渡到更现代的方案如果你的项目在长大CGI 每次请求都启动一个新进程的开销会变成瓶颈。这时候可以考虑迁移到 FastCGI 或 WSGI。好消息是CGI 脚本的逻辑往往可以复用——把输入输出那层适配一下核心处理代码基本不用动。Apache 的mod_fcgid或mod_proxy_fcgi都能承接这个过渡。另一个方向是把 CGI 脚本包装成 systemd 服务通过 socket 激活这样既能保留脚本的简单性又能避免每次请求重启进程。不过这就超出本文范围了属于后续可以单独展开的话题。6.3 我个人的几点体会搭这套环境最耗时间的从来不是敲命令而是排查那些“看起来配了但就是不生效”的问题。我的经验是每改一处配置就 reload 一次并立即验证不要攒一堆改动一起测。这样出问题时范围永远锁定在最后一次改动上。另外把配置文件和脚本都纳入版本管理。CGI 环境往往配一次用很久等哪天需要迁移或重建有版本记录能省下大量回忆时间。哪怕只是本地 git 仓库也比什么都没有强。最后别小看curl -i这个命令。它把响应头和正文一起打出来很多浏览器里看不清的问题在命令行下一目了然。这个习惯我从刚接触服务端保持到现在依然是最有效的排查手段之一。