Cgit 1.3.1 介绍与选型指南

目标：全面介绍 Cgit 的定位、架构、功能特性与适用边界，并与 Gitweb、Gitea 做量化选型对比，帮助读者判断「我只想要一个极快的 Git 仓库 Web 浏览前端」场景下该不该选 Cgit。文中版本、发布日期、页面回显均来自 2026-10-27 对官方仓库的实查与本机实测（Cgit 1.3.1 + nginx 1.18.0 + fcgiwrap，Ubuntu 22.04）。

一、环境信息

• 操作系统：Ubuntu 22.04 LTS（Jammy）
• 架构：x86_64
• 软件版本：Cgit 1.3.1（内置 Git 2.54.0，上游 2026-05-04 发布）
• Web 链路：nginx 1.18.0 + fcgiwrap（FastCGI 协议承载 CGI 程序）
• 实测访问入口：http://127.0.0.1:8145/cgit/
• 数据目录：/var/lib/git（裸仓库扫描根）、/var/cache/cgit（页面缓存）
• 信息溯源时间：2026-10-27（官网 about/log/tags 页面实查）

二、软件概述

Cgit 官方自我定位一句话："A hyperfast web frontend for git repositories written in C"（用 C 写的超快 Git 仓库 Web 前端）。它是一个标准 CGI 程序（RFC 3875），编译产出单个 cgit.cgi 二进制，由任意支持 CGI/FastCGI 的 Web 服务器（nginx+fcgiwrap、Apache、lighttpd 等）承载运行，直接读取磁盘上的 Git 裸仓库并生成 HTML 浏览页面。

关键身份信息（2026-10-27 实查官方仓库 https://git.zx2c4.com/cgit）：

Cgit 最著名的部署实例是 kernel.org——Linux 内核官方源码站 https://git.kernel.org/ 全站由 Cgit 承载，页脚可见「generated by cgit」字样。kernel.org 在 2011 年安全事件后重建基础设施时从 Gitweb 切换到 Cgit，看重的就是它面对海量仓库与高并发时的缓存架构。这一生产级背书至今有效（2026-10-27 访问 git.kernel.org 确认页脚为 cgit）。

三、核心架构

Cgit 的架构极简，这也是它快的根本原因：

浏览器 ──HTTP──> Web 服务器(nginx/Apache) ──FastCGI/CGI──> cgit.cgi(C 二进制)
                                                          │
                                                          ├─> /var/lib/git/*.git  (直接读裸仓库)
                                                          └─> /var/cache/cgit/*   (HTML 页面缓存)

1. 单二进制 CGI：Cgit 整个应用就是一个编译后的 cgit.cgi（实测 1.3.1 编译产物约 1.6MB），无常驻进程、无应用服务器。每个 HTTP 请求由 Web 服务器经 CGI（直接 fork）或 FastCGI（经 fcgiwrap 常驻池）调起，处理完即退出——内存占用按请求计，空闲时零占用。
2. 内嵌 Git 库：Cgit 源码树内嵌一份 Git 源码（构建时编译进二进制），直接以库方式调用 Git 对象读取，不走 git 命令行 fork-exec，省掉进程创建开销。1.3.1 内嵌 Git 2.54.0。
3. 三级页面缓存：这是 Cgit 的核心竞争力。生成的 HTML 按 URL 写入 cache-root（如 /var/cache/cgit），配合 cache-static-ttl（提交页等永久不变内容可设 -1 永不过期）、cache-dynamic-ttl（仓库列表等动态页）、cache-repo-ttl（仓库概要页）分级控制。命中缓存的请求就是一次纯静态文件读取——官方自称 "hyperfast" 的依据正在于此。
4. 仓库自动发现：配置 scan-path=/var/lib/git 后，Cgit 启动请求时自动扫描目录树发现所有裸仓库（支持 section-from-path 按目录层级分组），无需逐仓库注册。也兼容 Gitweb 的 projects.list 项目清单格式。
5. 过滤框架：提交信息、README、源码高亮等均可挂接外部脚本或内置 Lua 过滤器（编译时 NO_LUA=1 可裁掉 Lua 依赖）。

💡 技术拓展：Web 服务器承载 CGI 程序有四种主流方式——

方式	原理	特点
CGI（原生）	每请求 fork 一个新进程执行 CGI	最简单，高并发下 fork 开销大
FastCGI（fcgiwrap）	fcgiwrap 常驻进程池接收 Web 服务器的 FastCGI 请求，再 fork CGI	兼容任意 CGI 程序，省掉 Web 服务器到 CGI 的协议开销
Apache mod_cgi/mod_fcgid	Apache 内建模块直接承载	Apache 用户零额外组件
lighttpd mod_cgi	lighttpd 内建 CGI 模块	轻量，适合小机

Cgit 是标准 CGI 程序，四种方式均可。本系列文档实际采用「nginx + fcgiwrap」组合——nginx 不支持原生 CGI，fcgiwrap 是最小桥接层，这也是 Cgit 官方 FAQ 推荐的 nginx 方案。

四、功能特性

官方 about 页列出的完整特性清单（2026-10-27 实查），结合实测说明：

• 仓库浏览全家桶：summary（概要）、refs（分支/标签）、log（提交日志）、tree（文件树）、commit（提交详情）、diff（差异）、stats（时间/作者统计）——顶部导航 tab 实测与官方仓库页面完全一致。
• HTML 缓存：见核心架构第 3 点，缓存粒度到页面类型。
• 可克隆 URL（dumb HTTP transport）：配合 Web 服务器配置，git clone http://host/cgit/repo.git/ 直接可用（哑协议，只读场景够用；如需 smart HTTP 另挂 git-http-backend CGI）。
• Atom 订阅：每个仓库的 log 页自动生成 Atom feed（/cgit/<repo>/atom），RSS 阅读器可订阅提交动态。
• 仓库自动发现：scan-path 目录扫描 + Gitweb projects.list 兼容 + 读取裸仓库 gitweb.owner 配置作为 Owner 列显示。
• 在线打包下载：snapshots=tar.gz tar.xz 配置后，任意 tag/commit 页面提供源码 tar 包下载链接（on-the-fly 生成）。
• 并排 diff（side-by-side）：/cgit/<repo>/diff/?id=<commit> 提供双栏对照视图。
• 虚拟主机宏展开：virtual-root 等配置支持宏，单一 Cgit 实例可服务多域名。
• 语法高亮等过滤器插件：可接 highlight/pygments 等外部过滤器渲染源码着色。

实测回显（Ubuntu 22.04，nginx+fcgiwrap 链路，端口 8145）：

curl -sI http://127.0.0.1:8145/cgit/

HTTP/1.1 200 OK
Server: nginx/1.18.0 (Ubuntu)
Date: Tue, 27 Oct 2026 10:13:10 GMT
Content-Type: text/html; charset=UTF-8
Connection: keep-alive
Last-Modified: Tue, 27 Oct 2026 10:13:10 GMT
Expires: Tue, 27 Oct 2026 10:18:10 GMT

页面 HTML 中的生成器标识与仓库列表（节选，实测照抄）：

<meta name='generator' content='cgit v1.3.1'/>
...
<tr><td class='toplevel-repo'><a href='/cgit/demo-hello.git/'>demo-hello.git</a></td><td><a href='/cgit/demo-hello.git/'>cgit compose 演示仓库</a></td><td><a href='/cgit/?q=www-data'>www-data</a></td><td><span class='age-mins' data-ut='1793093594' title='2026-10-27 09:33:14 +0000'>40 min.</span></td></tr>
...
<div class='footer'>generated by <a href='https://git.zx2c4.com/cgit/about/'>cgit v1.3.1</a> (<a href='https://git-scm.com/'>git 2.54.0</a>) at 2026-10-27 10:13:10 +0000</div>

五、快速开始（最小可用示例）

最快的验证方式是在 Ubuntu 22.04 上用发行版仓库包装一个最小链路（版本为 1.2.3，适合先体验界面；生产部署 1.3.1 的完整 apt/源码双方案见《Ubuntu 22.04 安装 Cgit 1.3.1 指南》）：

apt update && apt install -y cgit nginx fcgiwrap git

cgit:
  Installed: 1.2.3+git2.25.1-1
  Candidate: 1.2.3+git2.25.1-1

准备一个裸仓库并指向它：

mkdir -p /var/lib/git
cd /var/lib/git && git init --bare demo-hello.git

写入最小 /etc/cgitrc：

virtual-root=/cgit/
scan-path=/var/lib/git

配置 nginx 通过 fcgiwrap 调起 cgit.cgi（完整配置见安装篇），启动后验证：

curl -s http://127.0.0.1/cgit/ | grep -o 'cgit v[0-9.]*'

cgit v1.3.1

看到版本标识即说明「Web 服务器 → fcgiwrap → cgit.cgi → 裸仓库」整条链路已通。

六、适用场景与限制

适合选 Cgit 的场景：

1. 只读仓库浏览门户：给团队/公众提供一个秒开的 Git 仓库浏览站（内核、发行版源码站形态），不需要在线改代码。
2. 海量仓库 + 高并发：缓存架构决定仓库越多收益越大，kernel.org 级负载有生产实证。
3. 已有 gitolite/SSH 推送体系：Cgit 只做「看」，推送继续走 SSH，职责清晰互补。
4. 资源受限环境：无常驻进程，空闲零内存，VM/低配 VPS 友好。

明确限制（选型红线）：

• 无用户体系：Cgit 没有任何登录/注册/权限概念，访问控制完全交给前置 Web 服务器（Basic Auth/IP 白名单）。要私有仓库权限管理，Cgit 本身无能为力。
• 无 Issue/PR/Wiki：它不是代码协作平台，只有浏览。
• 无在线编辑：纯只读。
• 无运维 CLI / REST API：所有管理=编辑 cgitrc 文本文件 + 重启 Web 链路，无任何命令行管理工具或 HTTP 管理面。
• Debian/Ubuntu 仓库版本滞后：jammy 仓库仅 1.2.3（2026-10-27 apt-cache 实测），要 1.3.1 必须源码编译或自建包。
• 无官方容器镜像：Docker Hub 无官方镜像，容器化须自建（本系列 Compose 篇给出完整自建方案）。

七、同类选型对比

Git 仓库 Web 浏览/托管的主流候选对比（数据实查于 2026-10-27）：

量化解读与选型建议：

• 三者不是同量级产品：Cgit/Gitweb 是「浏览前端」，Gitea 是「协作平台」。要 Issue/PR/权限 → Gitea；只要秒开的只读浏览 → Cgit；已经在装 Git 顺手蹭一个临时界面 → Gitweb。
• Cgit vs Gitweb 的决定性差异是缓存：Gitweb 每请求重新 fork Perl 并重新走 Git 对象解析，Cgit 命中缓存时等价于读静态文件。仓库一多（数百个以上）Gitweb 响应会明显劣化，而 Cgit 有 kernel.org（数万仓库）生产实证。Gitweb 的唯一优势是「随 Git 安装自带、零额外依赖」。
• 本系列选择 Cgit 1.3.1：它是当前上游最新稳定版，且官方仓库持续活跃（2026-09 仍有提交），不是停滞项目。

八、参考链接

• Cgit 官网与官方仓库：https://git.zx2c4.com/cgit/about/
• Cgit v1.3 发布公告（官方邮件列表）：https://lists.zx2c4.com/pipermail/cgit/2026-February/004968.html
• Cgit 提交日志（版本时间线实查依据）：https://git.zx2c4.com/cgit/log/
• 源码下载：https://git.zx2c4.com/cgit/snapshot/cgit-1.3.1.tar.xz
• kernel.org 源码站（Cgit 生产实例）：https://git.kernel.org/
• Gitea（对比项）：https://github.com/go-gitea/gitea