rs-short 3.3.1 配置参数详解

覆盖 rs-short 3.3.1 的全部两个配置文件：config.toml（16 个参数）与 lists.toml（策略名单）。所有参数语义取自源码（src/init.rs、src/structs.rs、src/spam.rs）与样例文件注释，关键行为均经"改参→重启→验证"闭环实测（取证：/opt/data/quzuo/tmp/rs-short/evidence.md）。

一、配置文件总览

启动红线（源码 check() 实测）：以下任一情况进程直接 panic 退出，容器表现为重启循环——

1. config_version ≠ 3（提示 "Your configuration file is obsolete!"）；
2. instance_hostname / cookie_key / phishing_password 仍是样例默认值（前两者中 instance_hostname 为阻断级）；
3. cookie_key 长度 < 88；
4. lists.toml 解析失败（含 §3 的 _category 陷阱）。

二、config.toml 参数详解

2.1 [general] 站点与网络（10 项）

2.2 [phishing] 反钓鱼与日志（6 项）

三、lists.toml 策略名单详解

结构：[names] 与 [urls] 两个域，各含 allowlist / blocklist。

3.1 语义

• allowlist（仅 { expr = '<regex>' }）：命中项永不进入 verbose_console / verbose_suspicious 的日志与监视（治理豁免，如自家活动链接）；
• blocklist：建链时命中即 403 拒绝。[urls] 条目 { expr, category, matching }，category ∈ shortener | freehost | spam（决定用户端提示文案），matching ∈ host(默认) | full-uri | port | authority | path | query（基于 http::Uri 组件匹配，大小写不敏感）；
• 默认版内置 100+ 条短链域名黑名单（bit.ly/t.co/tinyurl/linkvertise/iplogger 等）——实测缩短 https://bit.ly/fake 返回 403「Please do not chain shortened links with another link shortener.」✅

3.2 ⚠️ 实测最大的坑：names 的 _category

文件头注释写条目格式是 { expr, category }，但源码 BlockEntryName 结构体字段为 _category（serde 按字段原名解析）：

[names]
allowlist = []
blocklist = [
    { expr = '^blocked-name$', _category = 'spam' },   # ✅ 正确（注意下划线）
]

写成 category 的实测后果——启动即 panic，容器重启循环：

thread 'main' panicked at src/spam.rs:89:34:
called `Result::unwrap()` on an `Err` value: Error { message: "missing field `_category`", ... }

[urls] blocklist 则正常用 category（无下划线），两域不一致，属上游文档/代码缺陷。

3.3 命中 names 黑名单的已知显示缺陷

_category='spam' 命中后用户端提示区显示 「Missing translation」（HTTP 403 正常返回）。源码定位：spam.rs 抛 ErrorKind::WarnBlockedName，而 lang.json 只有 WarnBlockedNameSpam 键，键名不匹配，日志伴随 FATAL: Missing translation for key WarnBlockedName。功能不受影响（仍拦截），文案待上游修复；急需可读提示可自行给 lang.json 补键（需重建镜像）。

四、改参→重启→验证闭环实录

以本部署（compose 挂载两个文件，docker compose restart rs-short 约 2 秒）为例：

对照实验（负向）：把 config_version 改 2 → panic "configuration file is obsolete"；phishing_password 留 CHANGE ME → panic "You must change it in order to proceed"。校验前置、宁崩不裸奔，是该项目值得称道的安全默认。

五、生产配置建议清单

1. instance_hostname 用真实 HTTPS 域名（不带端口、不带尾斜杠）；
2. 两个密钥按 §2.1 命令现场生成，纳入备份（cookie_key 丢失仅影响进行中会话；phishing_password 泄露=治理权旁落）；
3. 公开实例建议 verbose_console = true + 反代日志 + fail2ban（README 官方推荐组合）；captcha_difficulty 保持 ≥3；
4. 用 allowlist 豁免自家高频链接，避免日志噪音；
5. 名单变更纳入发布流程（无热加载，重启秒级但会清空 RAM 监视器）；
6. 反代层对 /phishing/ 路径加访问日志脱敏或来源限制。

六、下一步与互链

• 部署编排：《rs-short 3.3.1 Docker Compose 部署指南》
• 端点与数据管理：《rs-short 3.3.1 命令与 HTTP 端点详解》
• 选型背景：《rs-short 3.3.1 介绍与选型指南》