Gitit 0.15.1.1 配置参数详解

目标：把 Gitit 的全部可配项（配置文件 40+ 参数、命令行 7 个选项）逐项讲清含义、默认值与改动效果，关键参数均给出在 Ubuntu 24.04 + gitit 0.15.1.1 服务器上的实测行为与回显。安装与服务化前置见《Ubuntu 24.04 安装 Gitit 0.15.1.1 指南》，产品定位见《Gitit 介绍与选型指南》。

一、环境信息

操作系统：Ubuntu 24.04.2 LTS (noble)，x86_64
软件：gitit 0.15.1.1+dfsg-1build3（apt 安装，gitit version 0.15.1.1 -plugins）
运行方式：systemd 服务 gitit.service，WorkingDirectory=/srv/gitit/wiki，Environment=LANG=C.UTF-8
监听：TCP 8138（0.0.0.0）
配置文件：/srv/gitit/wiki/gitit.cfg（经 -f 显式加载）
演示账号：admin / q1w2e3r4
参数默认值权威来源：gitit --print-default-config（实测输出 294 行，本文引用其原始注释）

二、前置条件

Gitit 已按部署篇完成安装与 systemd 托管，systemctl is-active gitit 返回 active；
数据目录 /srv/gitit/wiki 内含 wikidata/（git 仓库）、static/、templates/；
本文所有 Web 行为实测均携带登录会话 Cookie（curl -c/-b cookies.txt），管理员 admin 已通过 /_register 注册；
每次修改配置后需 systemctl restart gitit 生效，重启会使既有登录会话失效（旧 Cookie 请求返回 307 跳登录页），脚本化验证时需重新登录。

三、参数查看与修改方式

3.1 打印默认配置全量模板

--print-default-config 输出带官方注释的完整默认配置（294 行），是逐项核对参数的第一手依据：

gitit --print-default-config | head -14
# gitit wiki configuration file

address: 0.0.0.0
# sets the IP address on which the web server will listen.

port: 5001
# sets the port on which the web server will run.

wiki-title: Wiki
# the title of the wiki.

repository-type: Git
# specifies the type of repository used for wiki content.
# Options are Git, Darcs, and Mercurial.

repository-path: wikidata
# specifies the path of the repository directory.  If it does not
# exist, gitit will create it on startup.

3.2 命令行选项（实测 `gitit --help` 全量）

gitit --help
Usage:  gitit [opts...]
  -h            --help                  Print this help message
  -v            --version               Print version information
  -p PORT       --port=PORT             Specify port
  -l INTERFACE  --listen=INTERFACE      Specify IP address to listen on
                --print-default-config  Print default configuration
  -f FILE       --config-file=FILE      Specify configuration file

命令行选项只有这 7 个；其余全部配置能力都在配置文件里，命令行同名项优先级更高。

3.3 配置文件加载机制（实测关键结论）

Gitit 0.15.1.1 不会自动读取工作目录下的 gitit.cfg，必须 -f 显式指定。 对照实验：在 /srv/gitit/wiki 放置含 wiki-title: Team Knowledge Base 的 gitit.cfg 后——

# 裸启动（cwd 存在 gitit.cfg，但未用 -f）
curl -s http://localhost:8138/ | grep -oE "<title>[^<]*"
<title>Wiki - Front Page

# 改用 -f 显式加载同一文件
# ExecStart=/usr/bin/gitit -f /srv/gitit/wiki/gitit.cfg
curl -s http://localhost:8138/ | grep -oE "<title>[^<]*"
<title>Team Knowledge Base - Front Page

因此 systemd 单元的 ExecStart 应写成 gitit -f /srv/gitit/wiki/gitit.cfg（改完 systemctl daemon-reload && systemctl restart gitit）。

3.4 语法约定

配置文件为「键: 值」逐行格式，# 起注释；布尔值用 yes/no；多值（如 no-delete）用逗号分隔；多行值（如 reset-password-message）要求每行缩进且以 > 开头；文件末尾有独立的 [Github] 小节承载 OAuth 参数。

四、参数总览

按功能域分组（默认值均取自 --print-default-config 实测输出）：

分组	参数	默认值
网络	address / port	0.0.0.0 / 5001
站点标识	wiki-title / front-page	Wiki / Front Page
存储	repository-type / repository-path / default-extension / default-page-type	Git / wikidata / page / Markdown
认证	require-authentication / authentication-method / user-file / session-timeout / disable-registration / access-question(+answers) / use-recaptcha / recaptcha-private-key / recaptcha-public-key	modify / form / gitit-users / 60 / no / 空 / 空 / 空 / 空
渲染	math / mathjax-script / show-lhs-bird-tracks / table-of-contents / xss-sanitize / pandoc-user-data	mathjax / cdnjs MathJax 2.7.0 / no / yes / yes / 空
权限保护	no-delete / no-edit / default-summary / delete-summary / max-upload-size / max-page-size	"Front Page, Help" / Help / 空 / "Deleted using web interface." / 100K / 100K
缓存	use-cache / cache-dir	no / cache
订阅	use-feed / feed-days / feed-refresh-time	no / 14 / 60
URL	base-url / absolute-urls	空 / no
静态与模板	static-dir / templates-dir / mime-types-file	static / templates / /etc/mime.types
日志与调试	log-file / log-level / debug-mode / compress-responses	gitit.log / WARNING / no / yes
邮件	mail-command / reset-password-message	"sendmail %s" / 模板
扩展	plugins	空（apt 版不可用）
OAuth	authentication-method=github + [Github] 小节 / rpx-domain / rpx-key	见第六章 6.4

五、核心参数分类详解

5.1 网络监听：address、port（-l、-p）

port: 5001 为默认监听端口，address: 0.0.0.0 默认监听全部网卡。命令行 -p 8138 实测生效（ss -ltn 回显）：

ss -ltn | grep 8138
LISTEN 0      10           0.0.0.0:8138       0.0.0.0:*

-l/--listen 收紧监听地址，实测 -l 127.0.0.1 后仅回环可达：

gitit -f gitit.cfg -l 127.0.0.1 -p 8138 &
ss -ltn | grep 8138
LISTEN 0      10         127.0.0.1:8138       0.0.0.0:*

⚠️ 注意：-l 127.0.0.1 或 address: 127.0.0.1 会让局域网其他主机完全无法访问（连接被拒），仅适合前置反向代理场景。

5.2 站点标识：wiki-title、front-page

wiki-title 决定页面 <title> 前缀、侧栏标题与 Atom feed 标题，实测改为 Team Knowledge Base 后：

curl -s http://localhost:8138/ | grep -oE "<title>[^<]*"
<title>Team Knowledge Base - Front Page

front-page: Front Page 指定首页对应的页面名；改名后 Gitit 会尝试把首页渲染指向新页面名。

5.3 存储后端：repository-type、repository-path、default-extension、default-page-type

repository-type: Git：仓库类型，可选 Git / Darcs / Mercurial（apt 包描述明确支持 git/darcs，mercurial 需另行装 hg）；
repository-path: wikidata：相对 WorkingDirectory 的仓库路径，不存在则首启自动创建（部署篇 4.3 节 journal 实证 Created repository in wikidata）；
default-extension: page：页面文件扩展名，仓库内 *.page 才被识别为 Wiki 页面，其他文件（如上传的 notes.txt）按原样文件服务；
default-page-type: Markdown：默认解析器，可选 Markdown、CommonMark、RST、LaTeX、HTML、DocBook、Org 及 +LHS 变体（Pandoc 全家桶）。页面文件头部的 format: 声明优先于该默认值——实测默认首页首行即 ---\nformat: Markdown\n...。

💡 技术拓展：Wiki 页面标记语法的选择本质是解析器选型。常见方案对比——

方案语法族特点/取舍
Markdown(Pandoc 扩展) default-page-type: Markdown 生态最广；Gitit 启用 Pandoc 脚注/围栏代码等扩展
reStructuredText RST Python 文档圈标准；Pandoc 的 RST 解析器不完整
LaTeX LaTeX 学术排版强；Web 渲染损耗大
Org-mode Org Emacs 用户零迁移成本
HTML/DocBook HTML/DocBook 已有文档直接入库

本文实测环境采用默认 Markdown；RST/LaTeX/HTML/Org 官方注明「部分页面可能渲染不正确」，切换前先在测试库验证存量页面。

方案	语法族	特点/取舍
Markdown(Pandoc 扩展)	`default-page-type: Markdown`	生态最广；Gitit 启用 Pandoc 脚注/围栏代码等扩展
reStructuredText	`RST`	Python 文档圈标准；Pandoc 的 RST 解析器不完整
LaTeX	`LaTeX`	学术排版强；Web 渲染损耗大
Org-mode	`Org`	Emacs 用户零迁移成本
HTML/DocBook	`HTML`/`DocBook`	已有文档直接入库

5.4 认证与访问控制：require-authentication（三态实测）

require-authentication 控制登录要求的宽严，三档行为全部实测（服务重启后重新登录）：

modify（默认）——匿名可读、改动需登录。匿名取页面 200，匿名进编辑页被 307 重定向到登录：

curl -s -o /dev/null -w "HTTP=%{http_code}\n" http://localhost:8138/CLI%20Notes
HTTP=200
curl -s -o /dev/null -w "HTTP=%{http_code} redirect=%{redirect_url}\n" http://localhost:8138/_edit/Deploy%20Test
HTTP=307 redirect=http://localhost:8138/_login?destination=%2F_edit%2FDeploy%2520Test

none——匿名可改。实测不带 Cookie 直接保存新页面成功且产生提交：

curl -s --data-urlencode "editedText=# Anonymous Edit Test" --data-urlencode "logMsg=anon edit" \
     --data-urlencode "update=Save" -w "HTTP=%{http_code}\n" http://localhost:8138/AnonTest
HTTP=303

git -C /srv/gitit/wiki/wikidata log --oneline -1
9d7a3ed anon edit

read——看任何页面都要登录。实测匿名访问首页即跳登录：

curl -s -o /dev/null -w "anon HTTP=%{http_code} redirect=%{redirect_url}\n" http://localhost:8138/
anon HTTP=307 redirect=http://localhost:8138/_login?destination=%2F

配套参数：

user-file: gitit-users：用户口令文件路径，盐化哈希存储（实测内容为 [("admin",User {uUsername = "admin", uPassword = Password {pSalt = ..., pHashed = ...}... 的 Haskell Show 格式）；authentication-method 取 http 时不使用该文件；
authentication-method: form：内置表单认证；可改 http（信任反代注入的 Authorization 头）、generic（信任 REMOTE_USER，如 Apache mod_auth_cas）、github（GitHub OAuth，见第六章 6.4）；
session-timeout: 60：会话闲置分钟数；
disable-registration: no：改 yes 后关闭自助注册（配合预先建好账号的内网场景）；
access-question / access-question-answers：注册暗号问答，替代 reCAPTCHA 的轻量门槛；
use-recaptcha + recaptcha-public-key/recaptcha-private-key：接入 reCAPTCHA 防注册机（需外网可达 recaptcha.net，内网场景改用 access-question）。

5.5 渲染：math、mathjax-script、table-of-contents、xss-sanitize

math: mathjax（默认）控制 TeX 公式渲染方式，可选 MathML（本地转换，无外网依赖）、raw（原样 LaTeX）、mathjax（引用远端 MathJax 脚本）、google（Google 图表 API，官方注释明确提示隐私/连通问题）。mathjax-script 默认指向：

mathjax-script: https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-AMS_CHTML-full

实测新建含公式页面 # Math Demo ... Inline formula: $E = mc^2$ 后，页面 HTML 确实引用了该脚本：

curl -s http://localhost:8138/MathDemo | grep -oE "mathjax[^\" ]{0,50}" | head -1
mathjax/2.7.0/MathJax.js?config=TeX-AMS_CHTML-full

⚠️ 注意：纯内网部署时浏览器无法访问 cdnjs，公式不渲染。官方注释给出的方案是把 mathjax-script 改指自建 HTTP 服务上的 MathJax 副本（不能写本地磁盘绝对路径），或改 math: MathML 走服务端转换。

table-of-contents: yes（默认）在含多级标题的页面生成目录，实测 MathDemo（含 ## Physics Section）页面 HTML 中 toc 节点命中 2 处。xss-sanitize: yes（默认）把所有 HTML（含 Pandoc 产物）过滤过 xss-sanitize，官方注释明确「仅当你信任全部用户时才设为 no」。show-lhs-bird-tracks、pandoc-user-data（指定 Pandoc 定制目录，默认 $HOME/.pandoc）为 literate Haskell 与 Pandoc 深度定制项。

5.6 权限保护与限额：no-delete、no-edit、default-summary、delete-summary、max-upload-size、max-page-size

no-delete / no-edit（默认 Front Page, Help / Help）——Web 界面保护页实测：

# 删除受保护首页：请求被拒，仓库无删除提交
curl -s -b cookies.txt --data-urlencode "filetodelete=Front Page.page" \
     --data-urlencode "confirm=Yes, delete it!" -w "HTTP=%{http_code}\n" \
     http://localhost:8138/_delete/Front%20Page -o nd.html
HTTP=200
git -C /srv/gitit/wiki/wikidata log --oneline -1   # 无新提交

/_edit/Help 同样返回 200 但不给编辑通道。注意保护只对 Web 生效——官方注释明确「They can still be deleted directly using git」，命令行 git rm 不受限。

default-summary（默认空）——变更说明必填开关。实测 logMsg= 留空提交被拒（表单回显、无提交产生）；填了说明才 303 落库。设为固定文案后，留空提交将自动使用该文案。

delete-summary: Deleted using web interface.——Web 删除的提交说明取该值，实测删除 Deploy Test 产生的提交标题即：

082356e Deleted using web interface.

（该提交忽略了表单里的 logMsg，删除说明只认 delete-summary——脚本化操作时注意。）

max-upload-size: 100K / max-page-size: 100K——上传与页面体积上限。实测配置 max-upload-size: 50K 后上传 60 KB 文件：

dd if=/dev/zero of=/root/big.txt bs=1024 count=60
curl -s -b cookies.txt -F "file=@/root/big.txt" -F "wikiname=big.txt" \
     -F "logMsg=oversize" -F "upload=Upload" -w "HTTP=%{http_code}\n" \
     http://localhost:8138/_upload
HTTP=413

返回 413（Payload Too Large）。设 0K 则彻底关闭上传（侧栏上传链接消失、/_upload 失效）。

5.7 缓存：use-cache、cache-dir（联动 expireGititCache）

use-cache: no（默认）；开启后渲染页缓存写入 cache-dir: cache（相对 WorkingDirectory）。实测 use-cache: yes 访问页面后：

find /srv/gitit/wiki/cache -type f | sort
/srv/gitit/wiki/cache/CLI Notes.page
/srv/gitit/wiki/cache/Front Page.page
/srv/gitit/wiki/cache/_site.feed

缓存不感知 git 命令行侧的改动（Web 编辑会主动失效对应缓存，git commit 不会），需配套 expireGititCache 工具手动失效——实测失效单页后对应缓存文件消失：

expireGititCache http://localhost:8138 "CLI Notes.page"; echo "exit=$?"
exit=0
find /srv/gitit/wiki/cache -name "CLI*"
# 无输出：缓存已清除

⚠️ 注意：官方注释说明即使 use-cache: no，只要 use-feed: yes，feed 仍会被缓存（_site.feed），排障时别被这个「看不见的缓存」迷惑。

5.8 订阅与 URL：use-feed、base-url、feed-days、feed-refresh-time、absolute-urls

use-feed: yes 开启全站/单页 Atom feed。base-url 用于构造 feed ID——实测 feed 输出中 <id> 与 <link> 均取自它：

curl -s http://localhost:8138/_feed | head -c 300
<?xml version="1.0" encoding="UTF-8"?><feed xmlns="http://www.w3.org/2005/Atom"><title type="text">Team Knowledge Base</title><id>http://localhost:8138/</id><updated>2026-11-01T12:47:40Z</updated>...

feed 的作者条目来自 git 提交作者（实测输出含 Gitit、admin、root 三个 <author><name>）。feed-days: 14 限定 feed 收录天数（实测配 7），feed-refresh-time: 60 为 feed 缓存分钟数。absolute-urls: no（默认）控制 wikilink 相对/绝对生成——子目录页面多且经反代挂子路径时改 yes。

⚠️ 注意：use-feed: yes 但进程 locale 非 UTF-8 时 /_feed 直接 500（git: recoverEncode: invalid argument (cannot encode character '\8217')），根因与修复见部署篇 FAQ 9.3——默认帮助页文件名含 U+2019 右单引号，feed 枚举仓库文件必经此编码。

5.9 静态资源、模板与日志：static-dir、templates-dir、log-file、log-level、debug-mode、compress-responses、mime-types-file

static-dir: static / templates-dir: templates：不存在则首启自动释放默认内容（实测 Created static/css/custom.css、Created templates/footer.st）；定制外观就在同名目录里覆盖，升级不冲掉自定义（默认文件只在缺失时生成）；
log-file: gitit.log：实测内容以启动事件为主（Created/Added 系列行），配合 --debug 时追加请求转储；
log-level: WARNING：可选 DEBUG/INFO/NOTICE/WARNING/ERROR/CRITICAL/ALERT/EMERGENCY；
debug-mode: no：等价命令行 --debug，实测每请求打印 Happstack 请求结构：

gitit -f /srv/gitit/wiki/gitit.cfg --debug -p 8138
================== Request =================
rqSecure      = False
rqMethod      = GET
rqPaths       = []
rqUri         = /
rqQuery       =

（生产环境勿长期开启：每请求数百行转储会迅速撑大日志。）

compress-responses: yes：HTTP 响应压缩；mime-types-file: /etc/mime.types：上传文件的 MIME 映射来源，缺失时退化为内置简单映射。

5.10 邮件与密码找回：mail-command、reset-password-message

mail-command: sendmail %s 定义发信命令（%s 替换为收件地址，正文走 stdin）；留空则登录页不提供密码找回链接。reset-password-message 为找回邮件模板（每行缩进 + > 开头），支持 $username$ 、 $useremail$ 、 $hostname$ 、 $port$ 、 $resetlink$ 变量；经反代部署时需按官方注释把模板里的链接改写为对外路径。内网无 MTA 场景保持默认即可（实测登录页有 /_resetPassword 入口，但发信依赖 sendmail 存在）。

5.11 插件：plugins（apt 版实测不可用）

plugins: 列表加载 Haskell 页面变换插件（源码路径或 Gitit.Plugin.* 模块名）。apt 的 dfsg 构建关闭了插件开关，实测配置后启动即崩：

Loading plugin '/usr/share/gitit/plugins/CapitalizeEmphasis.hs'...
gitit: Missing file: /usr/lib/ghc/lib/settings

插件路线必须源码编译（部署篇第六章），示例插件源码随包在 /usr/share/gitit/plugins/（Dot、Interwiki、PigLatin、ImgTex 等 7 个）。

六、生产配置模板

6.1 内网团队 Wiki（实测可用配置）

适用：16 GB 内存服务器、内网可达、5–50 人团队、无外网 CDN。/srv/gitit/wiki/gitit.cfg：

address: 0.0.0.0
port: 8138
wiki-title: Team Knowledge Base
front-page: Front Page
require-authentication: modify
disable-registration: yes
access-question: 入职文档里的接入码是什么？
access-question-answers: RED DOG, red dog
session-timeout: 60
math: MathML
use-feed: yes
base-url: http://wiki.example.internal:8138
feed-days: 30
use-cache: yes
max-upload-size: 2M
max-page-size: 512K
log-level: WARNING

要点解读：disable-registration: yes + access-question 双闸门控注册；math: MathML 摆脱对 cdnjs 的依赖（5.5 节实测的离线渲染替代路径）；use-cache: yes 配合 cron 定期 expireGititCache 全量刷新（若引入 git 命令行批量写入）；base-url 换成真实域名否则 feed ID 不稳定。

6.2 GitHub OAuth 接入（[Github] 小节，未实测）

authentication-method: github 时启用文件末尾 [Github] 小节，官方默认模板为占位值，需换成自建 OAuth App 的真实凭据（系统级密钥按平台规范用环境变量注入，勿明文入库）：

[Github]
oauthclientid: ${GITIT_GITHUB_CLIENT_ID}
oauthclientsecret: ${GITIT_GITHUB_CLIENT_SECRET}
oauthcallback: http://mysite/_githubCallback
oauthoauthorizeendpoint: https://github.com/login/oauth/authorize
oauthaccesstokenendpoint: https://github.com/login/oauth/access_token
# github-org: your-org    # 取消注释则校验组织成员身份

本节为官方默认配置注释口径，实验环境无 GitHub OAuth 应用，未做接入实测。

七、常见问题

7.1 改了 gitit.cfg 毫无效果

九成是没加 -f：0.15.1.1 不自动加载工作目录配置文件（对照实验见第三章 3.3 节）。确认 ps -ef | grep [g]itit 的命令行里有 -f，改完 systemctl daemon-reload && systemctl restart gitit。

7.2 重启服务后脚本全部 307

会话保存在服务端，进程重启即清空；session-timeout: 60 只约束存活期内闲置时长。脚本化操作在每次重启后需重新 POST /_login。

7.3 /_feed 500 recoverEncode

locale 非 UTF-8 的标志性故障（见 5.8 节注意框）。systemd 单元补 Environment=LANG=C.UTF-8；前台调试先 export LANG=C.UTF-8。

7.4 Web 删除页面时填的说明没进 git log

删除提交的说明强制取 delete-summary，表单 logMsg 被忽略（实测提交标题固定 Deleted using web interface.）。想区分删除原因就改 delete-summary 文案或走命令行 git rm + commit -m。

7.5 上传大文件 413

max-upload-size 默认仅 100K，超限即 413（实测 50K 配置下 60 KB 文件被拒，见 5.6 节）。按业务调整该值，同时注意 max-page-size 对页面正文的独立限制。

7.6 git 命令行改了页面，Web 还显示旧内容

use-cache: yes 时命令行提交不触发缓存失效（Web 编辑才触发）。执行 expireGititCache http://localhost:8138 <页面文件..> 清除，或临时关缓存验证。

八、参考链接

官方仓库与 README：https://github.com/jgm/gitit （查询日期 2026-11-01）
Hackage 包页（配置文档随包发布）：https://hackage.haskell.org/package/gitit （查询日期 2026-11-01）
默认配置权威来源：gitit --print-default-config（本文实测输出）
本专栏配套篇：《Gitit 介绍与选型指南》、《Ubuntu 24.04 安装 Gitit 0.15.1.1 指南》

Gitit 0.15.1.1 配置参数详解

Gitit 0.15.1.1 配置参数详解

一、环境信息

二、前置条件

三、参数查看与修改方式

3.1 打印默认配置全量模板

3.2 命令行选项（实测 gitit --help 全量）

3.3 配置文件加载机制（实测关键结论）

3.4 语法约定

四、参数总览

五、核心参数分类详解

5.1 网络监听：address、port（-l、-p）

5.2 站点标识：wiki-title、front-page

5.3 存储后端：repository-type、repository-path、default-extension、default-page-type

5.4 认证与访问控制：require-authentication（三态实测）

5.5 渲染：math、mathjax-script、table-of-contents、xss-sanitize

5.6 权限保护与限额：no-delete、no-edit、default-summary、delete-summary、max-upload-size、max-page-size

5.7 缓存：use-cache、cache-dir（联动 expireGititCache）

5.8 订阅与 URL：use-feed、base-url、feed-days、feed-refresh-time、absolute-urls

5.9 静态资源、模板与日志：static-dir、templates-dir、log-file、log-level、debug-mode、compress-responses、mime-types-file

5.10 邮件与密码找回：mail-command、reset-password-message

5.11 插件：plugins（apt 版实测不可用）

六、生产配置模板

6.1 内网团队 Wiki（实测可用配置）

6.2 GitHub OAuth 接入（[Github] 小节，未实测）

七、常见问题

7.1 改了 gitit.cfg 毫无效果

7.2 重启服务后脚本全部 307

7.3 /_feed 500 recoverEncode

7.4 Web 删除页面时填的说明没进 git log

7.5 上传大文件 413

7.6 git 命令行改了页面，Web 还显示旧内容

八、参考链接

3.2 命令行选项（实测 `gitit --help` 全量）