Gitit 介绍与选型指南

目标：本文面向需要为团队/个人知识库选型「Git 后端 Wiki 引擎」的读者，系统介绍 Gitit 的定位、架构、功能特性与版本节奏，并给出与同类 Wiki 引擎的量化选型对比。本文内容全部来自官方仓库、Hackage 包页与 shields.io 徽章的联网溯源（查询日期 2026-11-01），安装与配置实测见本专栏《Ubuntu 24.04 安装 Gitit 0.16.0.2 指南》《Gitit 0.16.0.2 配置参数详解》《Gitit 0.16.0.2 常用 CLI 命令与工具详解》。

一、环境信息

本文属联网溯源类介绍文档，不涉及本地实测，信息核实所用的查询渠道如下：

• 官方源码仓库：https://github.com/jgm/gitit（GitHub，查询日期 2026-11-01）
• 官方发布与版本元数据：https://hackage.haskell.org/package/gitit（Hackage，查询日期 2026-11-01）
• 社区活跃度徽章：https://img.shields.io/github/stars/jgm/gitit.json（shields.io，查询日期 2026-11-01）
• 同类项目对比数据：各同类项目 GitHub 仓库 shields.io 徽章 + 本平台已交付的 Wiki 家族实测文档（见第七章）

二、软件概述

Gitit 是一个用 Haskell 编写的 Wiki 引擎，自 2008 年由 John MacFarlane 创建并持续维护至今（gitit --version 版权行为 "Copyright (C) 2008 John MacFarlane"）。John MacFarlane 同时是著名文档转换工具 Pandoc 的作者，这决定了 Gitit 的血统：它的网页服务由 Happstack 提供，而页面渲染直接复用 Pandoc 全家桶的标记语言解析能力。

Gitit 最核心的设计理念是「Wiki 即 Git 仓库」：全部页面和上传文件存放在一个 git（或 darcs、mercurial）版本库中，页面既可以通过 Web 界面编辑，也可以直接用 git 命令行工具增删改查——两种途径修改会互相感知，Git 历史天然就是 Wiki 的页面历史。这一设计带来三个直接收益：

1. 版本控制免费获得：每次编辑自动产生一次 git commit，页面历史、差异对比、回滚全部复用 git 能力；
2. 数据零锁定：Wiki 数据就是一个普通 git 仓库目录，git clone 即完整备份/迁移，可推送到任何 Git 服务做异地容灾；
3. 双通道编辑：浏览器编辑与命令行编辑（改 .page 文件后 git commit）可以并存，自动化脚本可以直接操作文件落盘。

官方描述（Hackage 包页，查询日期 2026-11-01）：

Gitit is a wiki program written in Haskell. It uses Happstack for the web server and pandoc for markup processing. Pages and uploaded files are stored in a git, darcs, or mercurial repository and may be modified either by using the VCS's command-line tools or through the wiki's web interface.

三、核心架构

Gitit 采用「单二进制、内嵌 Web 服务器、外部 VCS 文件存储」的三层架构，无数据库依赖：

浏览器 ──HTTP──> Happstack Web Server（内嵌，默认监听 5001）
                     │
                     ├─ Network.Gitit 库层：路由/认证/状态管理
                     ├─ Pandoc：标记语言解析与渲染（markdown/reST/LaTeX/HTML/DocBook/Org）
                     ├─ texmath：TeX 数学公式 → MathML；skylighting：源代码高亮
                     ├─ Plugins：动态加载的 Haskell 页面变换插件（Network.Gitit.Interface）
                     │
                     └─ filestore 抽象层 ──> git / darcs / mercurial 仓库（wikidata/）

• 进程形态：gitit 单个可执行文件内嵌 HTTP 服务器（Happstack），响应头 Server: Happstack/7.8.0.2；不需要 nginx/tomcat 之类外部容器，也不需要 MySQL/PostgreSQL。
• 存储层：首次启动在当前工作目录自动创建 wikidata/ git 仓库并写入默认页面（Front Page、Help、Gitit User's Guide）；页面文件为 <页面名>.page 纯文本。
• 配套产物：运行目录还会生成 static/（CSS/图片，可覆盖定制）、templates/（页面模板 .st，可覆盖定制）、gitit-users（用户口令文件，盐化哈希）、gitit.log（日志）。
• 库形态：Gitit 同时是一个 Haskell 库（Network.Gitit），可以嵌入任何 Happstack 应用——官方特性列表明确列出这一项。
• 认证体系：内置用户名/口令注册登录（gitit-users 文件），支持 GitHub OAuth（Network.Gitit.Authentication.Github 模块）、reCAPTCHA 防注册机；权限分 viewer/editor/admin 三级。

💡 技术拓展：Wiki 引擎的「存储后端」不止 Git 一种。常见形态对比——

后端	代表引擎	特点/取舍
关系数据库	MediaWiki、XWiki	成熟稳定、并发好；版本历史需引擎自建，迁移依赖数据库导出
文件系统（无 VCS）	DokuWiki、PmWiki、WiKiss	零依赖、纯文本落盘；历史靠引擎自管的 diff 文件
Git 仓库	Gitit、Gollum	版本历史/回滚/备份直接复用 git；大并发写与海量小文件场景性能一般
NoSQL/对象存储	Wiki.js（可插拔多种后端）	灵活；运维面扩大

Gitit 属于第三类「Git 仓库后端」，与 Gollum 同族；本文选型对象即此类引擎中最有代表性的 Haskell 实现。

四、功能特性

官方 README（gitit-0.16.0.2，Hackage 包页，查询日期 2026-11-01）列出的特性：

其他实用能力：页面可打印视图（?printable）、随机页面（/_random）、按 URL 直接跳转（/_go）、删除/讨论页命名空间（/_delete、/_discuss）、导出（/_source 系列）。

五、版本节奏

Hackage 官方包页各版本上传时间（查询日期 2026-11-01）：

版本节奏解读：Gitit 采用「低频大版本 + 快速修订」模式——2020→2024 约每 3 年一个功能代际，每次代际后 1-2 个月内密集出修订版（0.16 → 0.16.0.1 → 0.16.0.2 于 2026-06 至 2026-09 连续发布）。注意 jgm/gitit 仓库不发布 GitHub Release 二进制（releases/latest API 返回 404，查询日期 2026-11-01），官方分发渠道是 Hackage 源码包 + 各发行版仓库，安装路径详见本专栏部署篇。

发行版收录矩阵（Hackage "Distributions" 栏 + 各发行版仓库实查，查询日期 2026-11-01）：

⚠️ 说明：Debian/Ubuntu 打包版以 +dfsg 重打包并关闭了插件编译开关，gitit --version 显示 0.15.1.1 -plugins（减号表示 plugins 功能未编入）；需要插件能力必须走 cabal/stack 源码安装，实测细节见部署篇。

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

以下命令来自官方 README「Getting started」章节（查询日期 2026-11-01），完整多方案安装与 systemd 托管实测见本专栏《Ubuntu 24.04 安装 Gitit 0.16.0.2 指南》：

# 安装（官方两条推荐路径，任选其一；需先有 GHC/cabal 或 stack 工具链）
cabal update && cabal install gitit      # 路径一：cabal，装 Hackage 最新 release
git clone https://github.com/jgm/gitit && cd gitit && stack install   # 路径二：stack（README 称"最可靠"）

# 启动：切到可写目录，gitit 自动创建 wikidata/static/templates/gitit-users/gitit.log
cd /srv/gitit/wiki
gitit            # 默认监听 5001 端口

# 验证：浏览器访问 http://localhost:5001 即见默认 Front Page

⚠️ 注意：官方 README 强调运行 Gitit 必须处于 UTF-8 locale（locale 命令确认），否则页面名与正文的 UTF-8 编解码会出错。

七、适用场景与限制

适用场景：

• 个人/小团队技术知识库：单二进制 + git 备份，运维成本几乎为零；
• 需要「文档即代码」的团队：Wiki 内容可直接 git clone 进 CI/CD、用 PR 流程评审文档变更；
• 混合标记语言需求：同一 Wiki 内不同页面可用 Markdown、reST、LaTeX、Org 书写（按扩展名/配置选择解析器）；
• 数学/代码密集型文档：TeX 公式 + 语法高亮开箱即用；
• 内网离线部署：单文件 + git 即可运行，无数据库、无外部服务依赖。

限制与不适用场景：

• Haskell 技术栈门槛：插件必须用 Haskell 编写并参与编译，非 Haskell 团队无法扩展；发行版仓库版本常年偏旧，追新需自备 GHC/cabal 工具链；
• 并发写与规模上限：每次编辑即一次 git commit，高并发写场景（数百人同时编辑）下 git 文件锁会成为瓶颈；海量页面（万级）下搜索为全库正则扫描，性能一般；
• 无实时协作/所见即所得：编辑是传统 textarea + Markdown 源码模式，无协同光标、无富文本 WYSIWYG；
• 前端定制弱于 JS 系：模板为 HStringTemplate（.st 文件），改界面不如 Node/PHP 系引擎顺手；
• GPL-2 许可：闭源二次分发需评估许可证传染（自用部署不受影响）。

社区活跃度（shields.io，查询日期 2026-11-01）：GitHub stars 2.3k、forks 233、open issues 189；Hackage 累计下载 74508 次（近 30 天 535 次）。属「维护者单一但持续活跃」的长寿项目形态（2008 年至今，作者即 Pandoc 作者，工程品质高、issue 响应稳定）。

同类选型对比（星数来源 shields.io，查询日期 2026-11-01；对比维度含本平台已实测交付的同类文档）：

解读：同为「git 后端」的 Gollum 星数更高、Ruby 生态更易扩展插件，但依赖 Ruby 运行时且近年更新放缓；Gitit 的差异化优势是 Pandoc 渲染品质（6+ 种标记语言、数学、高亮）+ 单二进制零依赖部署。若团队已在用 Git 做文档管理、且内容以技术文档（公式/代码）为主，Gitit 是 Git 后端 Wiki 中渲染能力最强的一档；若需要可视化编辑、大型站点与权限体系，应转向 MediaWiki/Wiki.js。

选型建议（「如果…则…」）：

• 如果是个人/小团队技术 Wiki、想要 git 版本历史与文档即代码 → Gitit 或 Otter Wiki（后者 Python 栈、界面更现代）；
• 如果页面含大量数学公式、多标记语言混排 → Gitit（Pandoc 独占优势）；
• 如果需要万级页面、复杂权限、可视化编辑器 → MediaWiki/Wiki.js，不要用 Git 系；
• 如果运维团队只会 PHP、要极简部署 → PmWiki/WiKiss/DokuWiki。

八、参考链接

• 官方仓库：https://github.com/jgm/gitit （查询日期 2026-11-01）
• Hackage 包页（版本/日期/依赖/README 权威来源）：https://hackage.haskell.org/package/gitit （查询日期 2026-11-01）
• 官方文档站：http://gitit.net/ （README 指向）
• Pandoc 标记语法参考：https://pandoc.org/MANUAL.html
• 本专栏配套实测篇：《Ubuntu 24.04 安装 Gitit 0.16.0.2 指南》《Gitit 0.16.0.2 配置参数详解》《Gitit 0.16.0.2 常用 CLI 命令与工具详解》