Fossil SCM 2.28 配置参数详解
拆解 Fossil 2.28 四层配置体系与 113 个 settings 参数，含 default-perms、manifest、ignore-glob 等生效验证与 fossil configuration/all 批量管理。
FossildvcsFossil SCM2026/10/29
Fossil SCM 2.28 配置参数详解
定位：Fossil 的配置分四层——内建默认、全局配置库（
~/.fossil）、仓库本地config表、以及随代码提交的.fossil-settings版本化文件。本文逐项梳理 2.28fossil settings实测的 113 个参数，给出分组说明、6 项以上真实生效验证，并拆解manifest、fossil configuration、fossil all三个仓库级管理面。全部命令与回显来自 2026-10-27 的 Ubuntu 22.04 + Fossil 2.28 实测环境。
1. 配置体系与优先级
fossil settings 的官方语义（实测 --help）：
Usage: fossil settings ?SETTING? ?VALUE? ?OPTIONS?
or: fossil unset SETTING ?OPTIONS?
The "settings" command with no arguments lists all settings and their values.
With just a SETTING name it shows the current value.
With a VALUE argument it changes the property for the current repository.
Settings marked as versionable are overridden by .fossil-settings/PROPERTY
in the check-out root, if that file exists.
Settings can have both a "local" repository-only value and a "global" value.
Local values are stored in the "config" table of the repository; global
values are stored in the configuration database. Local takes precedence.
关键选项：
--global：写入全局配置库，对所有仓库生效；不加则只写当前仓库。--changed：只列出与默认值不同的项，适合审计。--value：只输出值，适合脚本取值。--exact：只做精确名称匹配。fossil unset SETTING：清除本地值，回落到全局/内建默认。
优先级从高到低：.fossil-settings/<name> 版本化文件 → 仓库 config 表 → 全局配置库 → 内建默认。注意两点：
- 设置不会随
sync/push传播到服务器；服务器改了设置，所有克隆要手动同步该变更（官方文档明确说明）。 - 版本化设置（
ignore-glob、manifest等）一旦在检出的.fossil-settings/下存在对应文件，会覆盖fossil settings的值并给出警告。
实测一个新建仓库的 fossil settings 输出共 113 行，未显式赋值的项值列为空（例如 http-port 为空，但服务实际仍按内建默认 8080 监听）。因此"空"不等于"未生效"，排查时要以行为验证为准。
2. 全量参数清单（按功能分组）
以下为 2.28 fossil settings 实测输出中出现的全部 113 个名称，原样分组（组内按字母序）：
2.1 访问、安全与限流
access-log admin-log allow-symlinks
anon-cookie-lifespan auto-captcha auto-hyperlink
auto-hyperlink-delay auto-hyperlink-mouseover
auto-shun autosync autosync-tries
backoffice-disable backoffice-logfile backoffice-nodelay
clearsign default-csp default-perms
default-skin exec-rel-paths https-login
localauth lock-timeout max-cache-entry
max-loadavg max-upload redirect-to-https
regexp-limit robot-exception robot-restrict
robot-zip-leaf robot-zip-tag robots-txt
safe-html self-pw-reset self-register
ssl-ca-location ssl-identity user-color-map
verify-comments vuln-report web-browser
2.2 时间线与分支
main-branch timeline-default-style
timeline-hard-newlines timeline-mark-leaves
timeline-plaintext timeline-truncate-at-blank
timeline-tslink-info timeline-utc
2.3 工单、论坛与聊天
ticket-default-report forum-close-policy forum-title
chat-alert-sound chat-initial-history chat-inline-images
chat-keep-count chat-keep-days chat-poll-timeout
chat-timeline-user
2.4 邮件与通知
email-admin email-listid email-renew-interval
email-self email-send-command email-send-db
email-send-dir email-send-method email-send-relayhost
email-subname email-url
2.5 HTTP、网络与外部命令
http-port proxy ssh-command
tclsh th1-setup th1-uri-regexp
gdiff-command gmerge-command pgp-command
diff-command diff-binary preferred-diff-type
editor encoding-glob hash-digits
relative-paths repo-cksum sitemap-extra
suggested-downloads uv-sync mimetypes
2.6 版本化文件与检出行为
binary-glob clean-glob crlf-glob
crnl-glob dotfiles empty-dirs
fileedit-glob forbid-delta-manifests
ignore-glob keep-glob manifest
mtime-changes mv-rm-files raw-bgcolor
2.7 提交、同步与显示
comment-format dont-commit dont-push
large-file-size mainmenu repolist-skin
2.28 实测中不存在
wiki-*设置项；ticket-*只有ticket-default-report一个；Tcl 相关项是tclsh、th1-setup、th1-uri-regexp，没有tcl-*前缀。任务书里按惯例列出的这些名字需要按实际清单校正。
3. 关键参数逐项说明
| 参数 | 作用 | 实测/默认行为 |
|---|---|---|
default-perms | 新用户的默认能力位 | 设为 hm 后新建用户 bob 的能力即为 hm |
default-skin | 默认 Web 皮肤 | 设 original 与留空，同一页面 HTML 体积 22894 vs 25875 字节，确认生效 |
https-login | 要求登录走 HTTPS | 设为 on 后，经 HTTP 入口访问 /login 仍返回 200，不能替代强制 301 |
redirect-to-https | HTTP 自动跳 HTTPS | 设为 on 后，带 X-Forwarded-Proto: http 访问 /home 仍 200，未观察到跳转 |
auto-captcha | 登录/注册验证码 | 关/开时 /login 页面中 captcha 相关引用为 4/5 处，页面本就内嵌验证码脚本，肉眼差异小 |
max-loadavg | 高于该负载时限制同步 | 设为 0.01 后 fossil clone 仍成功，未触发拦截 |
max-upload | 单次上传大小上限 | 与 Nginx client_max_body_size 配合，默认按字节数限制 |
large-file-size | 大文件告警阈值 | 提交大文件时用于提示，不阻止 |
http-port | server/ui 默认端口 | 设为 8090 且不带 --port，实测监听 localhost:8090 |
ssl-ca-location | 出站 HTTPS 校验用 CA 文件 | 设为自签 CA 后，fossil sync 对 HTTPS 站点完成 1 轮往返（363/415 字节） |
ssl-identity | 客户端证书 | 双向 TLS 场景使用，需 PEM |
timeline-utc | 时间线用 UTC 显示 | 页面出现 UTC 标记，实测默认为开 |
timeline-default-style | 时间线默认样式 | 设 Compact 与默认，页面 49414 vs 49423 字节，确认渲染不同 |
timeline-hard-newlines | 保留硬换行 | 影响评论/提交说明显示 |
timeline-mark-leaves | 标记叶子节点 | 分支图可读性 |
timeline-plaintext | 纯文本时间线 | 便于脚本抓取 |
timeline-truncate-at-blank | 在空行处截断摘要 | 长提交说明显示更紧凑 |
timeline-tslink-info | 时间戳链接到 info 页 | 导航习惯 |
main-branch | 主分支名 | 影响默认分支视图 |
ticket-default-report | 工单默认报表编号 | 设为 2 后写入 config 表，--changed 可见 |
forum-title | 论坛标题 | 无论坛内容时页面标题不体现 |
forum-close-policy | 论坛关帖策略 | 版主/作者等策略 |
email-send-method | 发信方式 | 可设 off、relay、pipe 等 |
email-send-command | 管道发信命令 | 与 pipe 方式配合 |
email-send-relayhost | SMTP 中继 | 与 relay 方式配合 |
email-url | Web 基地址 | 邮件里的链接前缀 |
email-admin | 管理员邮箱 | 通知收件人 |
email-self | 发件人地址 | 投递身份 |
tclsh | Tcl 解释器路径 | TH1 扩展/脚本使用 |
th1-setup | 页面 TH1 初始化脚本 | 深度定制入口 |
th1-uri-regexp | TH1 适用 URI 正则 | 限定脚本作用范围 |
proxy | 出站 HTTP 代理 | 同步/抓取走代理 |
ssh-command | SSH 命令 | SSH 传输模式 |
hash-digits | 哈希显示位数 | 设为 6 后 Web 仍按上下文显示 8/16 位，说明该值不是硬截断 |
ignore-glob | 忽略的未纳管文件 | 设 *.log 后 fossil extras 不再列 debug.log |
manifest | 生成 manifest 文件 | 设 ru 后检出目录出现 manifest 与 manifest.uuid |
clean-glob | clean 时删除的额外文件 | 版本化 |
binary-glob | 按二进制处理的文件 | 版本化，影响 diff/合并 |
crlf-glob / crnl-glob | 行尾转换 | 互为别名 |
empty-dirs | 保留空目录 | 版本化 |
keep-glob | clean 时保留的额外文件 | 版本化 |
mimetypes | 扩展名到 MIME 映射 | 版本化 |
dotfiles | 是否纳入点文件 | 设为 on 后 .env 等可见 |
forbid-delta-manifests | 禁止增量存储 manifest | 影响仓库体积/兼容性 |
dont-commit | 禁止提交的路径 | 提交前拦截 |
dont-push | 禁止推送的路径 | 推送前拦截 |
autosync | 自动同步 | 设为 on 后提交后自动 sync |
autosync-tries | 自动同步重试次数 | 网络抖动场景 |
lock-timeout | 仓库锁等待秒数 | 并发写保护 |
max-cache-entry | 页面缓存条目上限 | Web 性能 |
repo-cksum | 仓库校验 | 完整性检查 |
self-register | 允许自助注册 | 与 auto-captcha 配合 |
self-pw-reset | 允许自助重置密码 | 需邮件配置 |
safe-html | HTML 安全策略 | 防 XSS |
allow-symlinks | 允许符号链接 | 安全边界 |
4. 实测生效的 6+ 项
以下每项都在 2026-10-27 的 demo.fossil 上完成"设置→观察行为"闭环。
4.1 default-perms：新用户能力位
fossil settings default-perms "hm" -R /var/lib/fossil/repos/demo.fossil
fossil user new bob bob@example.com bobpass -R /var/lib/fossil/repos/demo.fossil
fossil user capabilities bob -R /var/lib/fossil/repos/demo.fossil
实测：
hm
新建用户无需单独授权即继承 hm。能力位含义：s=setup、a=admin、i=check-in、o=check-out、r=read、w=write、z=zip、h=hyper、g=clone、p=password、q=moderate、t=ticket、f=forum、k=wiki。管理员 admin 的能力实测为 s。
4.2 ignore-glob：extras 过滤
fossil settings ignore-glob "*.log" -R /var/lib/fossil/repos/demo.fossil
cd /var/lib/fossil/checkout
touch debug.log notes.txt
fossil extras
实测只输出：
notes.txt
debug.log 被忽略。该设置同时是版本化项，推荐在检出根建 .fossil-settings/ignore-glob 随代码提交，团队共享。
4.3 manifest：生成 manifest 文件
fossil settings manifest ru -R /var/lib/fossil/repos/demo.fossil
cd /var/lib/fossil/checkout && fossil open /var/lib/fossil/repos/demo.fossil
ls -l
实测：
-rw-r--r-- 1 fossil fossil 224 manifest
-rw-r--r-- 1 fossil fossil 65 manifest.uuid
取值说明：r 生成 manifest，u 生成 manifest.uuid，t 生成 manifest.tags，组合使用。SQLite 与 Fossil 自身仓库都依赖该机制，Fossil 官方明确要求这两个项目保持开启。
4.4 http-port：fossil server 默认端口
fossil settings http-port 8090 -R /var/lib/fossil/repos/demo.fossil
runuser -u fossil -- /usr/local/bin/fossil server \
/var/lib/fossil/repos/demo.fossil --localhost --baseurl http://127.0.0.1:8090
实测首行：
Listening for HTTP requests on TCP port localhost:8090, IPv4 and IPv6
注意：systemd 单元里显式写了 --port 8080，命令行参数优先级高于该设置；只有省略 --port 时 http-port 才生效。
4.5 default-skin：整站皮肤
fossil settings default-skin "original" -R /var/lib/fossil/repos/demo.fossil
curl -s http://127.0.0.1:8080/home | wc -c # 22894
fossil settings default-skin "" -R /var/lib/fossil/repos/demo.fossil
curl -s http://127.0.0.1:8080/home | wc -c # 25875
实测两次 HTML 体积 22894 vs 25875 字节，cmp 判定不同，确认皮肤切换生效。生产建议保留默认皮肤或在 Web Admin 里预览后再定。
4.6 timeline-default-style：时间线默认视图
fossil settings timeline-default-style "Compact" -R /var/lib/fossil/repos/demo.fossil
curl -s "http://127.0.0.1:8080/timeline?y=ci" | wc -c # 49414
fossil settings timeline-default-style "" -R /var/lib/fossil/repos/demo.fossil
curl -s "http://127.0.0.1:8080/timeline?y=ci" | wc -c # 49423
两次输出不同（49414 vs 49423），确认样式参数进入渲染路径；差异小是因为当前只有一个空检入。
4.7 项目身份：project-name / project-description 不在 settings 里
任务书把它们列为 settings 项，实测直接设置会报错：
fossil settings project-name "Fossil Demo Renamed" -R /var/lib/fossil/repos/demo.fossil
no such setting: project-name
真实的存储位置是仓库 config 表：
fossil sql -R /var/lib/fossil/repos/demo.fossil \
"SELECT name,value FROM config WHERE name LIKE 'project%'"
project-code|c2cb9fde916f3925b2584cdef6ed9265a810b9d4
project-description|Fossil 2.28 deployment test
project-name|Fossil Demo
用 SQL 更新后，Web 标题立刻变化：
fossil sql -R ... "UPDATE config SET value='Fossil Demo Renamed' WHERE name='project-name'"
curl -s http://127.0.0.1:8080/home | grep -o "<title>[^<]*</title>"
<title>Fossil Demo Renamed: Fossil Demo Renamed</title>
生产环境不建议直接改表：在 Web 管理界面 Admin → Configuration 修改项目名/描述，或初始化时用 fossil init --project-name ... --project-desc ... 固定。SQL 方式仅用于无 Web 权限的应急恢复，改前务必备份仓库文件。
4.8 ssl-ca-location：自定义 CA
fossil settings ssl-ca-location /etc/ssl/certs/ca-certificates.crt \
-R /var/lib/fossil/repos/demo.fossil
runuser -u fossil -- fossil sync -R /var/lib/fossil/backups/clone-smoke.fossil \
https://fossil.example.com/demo
实测：
Round-trips: 1 Artifacts sent: 0 received: 0
Sync done, wire bytes sent: 363 received: 415 remote: 127.0.0.1
自签证书场景要把 CA 证书文件路径写入该设置（或系统信任库），否则 sync/clone 会在 TLS 校验阶段失败。该设置只影响出站连接，不影响入站 Web 服务。
5. 未按预期生效的项与边界（真问题）
这些是实测与文档直觉不一致的地方，部署时不要想当然：
https-login不是强制跳转开关。设为on后，curl -I http://127.0.0.1/login仍返回200 OK；它只约束登录凭据提交路径，且对本地/可信连接有豁免。强制 HTTPS 必须由 Nginx 的return 301 https://$host$request_uri;完成。redirect-to-https在反代后未触发。设为on并带X-Forwarded-Proto: http访问/home，实测仍是HTTP/1.0 200 OK，没有 301/302。max-loadavg未拦住克隆。设为0.01后执行fossil clone，克隆照常完成；该参数更适合作为同步限流的辅助信号，不能当硬开关。auto-captcha可见差异弱。关闭/开启时登录页 captcha 相关引用 4/5 处，页面本身始终包含验证码脚本与音频元素，是否弹出挑战取决于失败次数等上下文。hash-digits不是硬截断。设为6后 Web 时间线仍显示 8/16 位哈希，说明该值用于特定显示场景（如 CLI 短哈希），不影响所有页面。wiki-*不存在。2.28 没有 Wiki 专项设置；Wiki 行为由权限（k能力）、safe-html、default-perms等共同决定。ticket-*仅一项。只有ticket-default-report；工单字段、状态、报表格式存在数据库表与 Web Admin，不是 settings。tcl-*不存在。Tcl 相关是tclsh、th1-setup、th1-uri-regexp三个独立键。
6. 仓库级 manifest 与版本化配置
manifest 设置控制检出目录里是否自动生成三个文件：
manifest：当前检入的完整文件清单（含每个文件的哈希、权限、父提交），是 Fossil 的"结构工件"落盘形式；manifest.uuid：当前检入的 artifact 哈希，供构建脚本读取版本号；manifest.tags：当前检入的标签（取值为t时生成）。
实测生成物：
-rw-r--r-- 1 fossil fossil 224 manifest
-rw-r--r-- 1 fossil fossil 65 manifest.uuid
manifest、ignore-glob、binary-glob、clean-glob、crlf-glob/crnl-glob、empty-dirs、encoding-glob、keep-glob、mimetypes 属于版本化设置：在检出根建 .fossil-settings/<name> 文件，内容即参数值，随提交/合并传播。示例：
mkdir -p .fossil-settings
printf '*.log\n*.tmp\n' > .fossil-settings/ignore-glob
fossil add .fossil-settings/ignore-glob
fossil commit -m "chore: add ignore rules"
版本化文件存在时优先级高于 fossil settings 写入的本地值，Fossil 会给出覆盖警告。
7. fossil configuration（fossil config）
命令帮助实测：
Usage: fossil configuration METHOD ... ?OPTIONS?
Where METHOD is one of: export import merge pull push reset.
支持的区域（AREA）：
all email interwiki project shun skin ticket user alias subscriber
常用操作：
# 导出全部配置（含用户、工单报表、皮肤、订阅等）
fossil configuration export all /work/demo-config.txt -R /var/lib/fossil/repos/demo.fossil
# 导入会覆盖当前配置；merge 只补缺失项
fossil configuration import /work/demo-config.txt -R /var/lib/fossil/repos/demo.fossil
fossil configuration merge /work/demo-config.txt -R /var/lib/fossil/repos/demo.fossil
# 从另一台服务器拉取某区域配置
fossil configuration pull ticket https://fossil.example.com/demo -R ...
实测导出文件头与内容片段：
# The "all" configuration exported from
# repository "/var/lib/fossil/repos/demo.fossil"
# on 2026-10-27 12:31:36
config /user 88
1793103941 'admin' pw '3f367180bcca56de73c983570e34318102aea3ce' cap 's' info '' jx '{}'
config /user 98
注意：
fossil config是configuration的可用简称；单独执行会提示use --repository or -R to specify the repository database。export不含版本历史，只含配置与用户；迁移仓库仍应复制.fossil文件或fossil backup。import是覆盖式，生产执行前先导出当前配置做回滚点。
8. fossil all：多仓库批量管理
fossil all 依赖 ~/.fossil 记录本机所有仓库路径（打开/克隆仓库时自动登记）。实测注册表：
runuser -u fossil -- fossil all list
/var/lib/fossil/backups/clone-smoke.fossil
/var/lib/fossil/repos/demo.fossil
批量备份（目标目录必须已存在）：
mkdir -p /var/lib/fossil/backups/all
runuser -u fossil -- fossil all backup /var/lib/fossil/backups/all
实测回显与产物：
/usr/local/bin/fossil backup -R /var/lib/fossil/backups/clone-load.fossil /var/lib/fossil/backups/all
/usr/local/bin/fossil backup -R /var/lib/fossil/backups/clone-smoke.fossil /var/lib/fossil/backups/all
/usr/local/bin/fossil backup -R /var/lib/fossil/repos/demo.fossil /var/lib/fossil/backups/all
total 660
-rw-r--r-- 1 fossil fossil 229376 clone-load.fossil
-rw-r--r-- 1 fossil fossil 229376 clone-smoke.fossil
-rw-r--r-- 1 fossil fossil 217088 demo.fossil
常用子命令（实测 fossil all --help 全量）：
backup cache changes clean config dbstat extras fts-config
git info pull push rebuild remote repack sync settings unset
server ui whatis
生产建议：
- 用
fossil all settings max-loadavg 2.0统一设置限流阈值； - 用
fossil all sync做离线回来后的批量同步； - 用
fossil all rebuild在升级/异常后批量重建索引； fossil all clean会删除所有检出中的额外文件，执行前必须--dry-run。
9. 生产基线配置建议
一个面向公网、Nginx 反代的小团队仓库，推荐显式落以下设置（其余保持默认）：
R=/var/lib/fossil/repos/project.fossil
fossil settings project-name "My Project" -R $R # 初始化时设置更稳妥
fossil settings default-perms "hm" -R $R # 新用户最小权限
fossil settings https-login on -R $R # 纵深防御
fossil settings max-upload 104857600 -R $R # 单次上传 100 MB
fossil settings max-loadavg 4.0 -R $R # 高负载辅助限流
fossil settings ssl-ca-location /etc/ssl/certs/ca-certificates.crt -R $R
fossil settings manifest ru -R $R # 构建可读版本号
fossil settings ignore-glob "*.log,*.tmp,.DS_Store" -R $R
fossil settings email-send-method relay -R $R
fossil settings email-send-relayhost 127.0.0.1:25 -R $R
fossil settings email-admin admin@example.com -R $R
fossil settings email-self fossil@example.com -R $R
配合 Nginx：
client_max_body_size 512m;
proxy_read_timeout 300s;
10. 站内延伸阅读
- 认知与选型：本专栏《Fossil SCM 2.28 介绍与选型指南》。
- 部署落地：本专栏《Ubuntu 22.04 安装 Fossil SCM 2.28 指南》。
- 命令实战：本专栏《Fossil SCM 2.28 常用 CLI 命令详解》。
11. 实测环境与依据
- 实测日期 2026-10-27；Ubuntu 22.04.5 LTS；Fossil 2.28
[52445a27f1] 2026-03-11。 fossil settings、fossil settings --help、fossil configuration/fossil all --help均为本机实测输出。- 官方设置文档：https://fossil-scm.org/home/doc/trunk/www/settings.wiki（版本化设置清单、设置不随 sync 传播）。
- 官方
manifest设置说明：本机fossil help manifest实测输出。
章节目录