Isso 0.14.0 配置参数详解

本文对 Isso 0.14.0 的全部九个配置节做参数级详解：以源码内置默认值为基线，逐项给出「默认值 → 本文取值 → 实测行为」。全部行为均在真实服务器上以 curl 驱动 JSON API 实测并留存逐行回显（实测日期 2026-10-30），403 拦截原因、通知邮件报文、渲染结果等关键输出均照抄实录。

部署过程见《Isso Docker Compose 部署指南》，接口级用法见《Isso 0.14.0 API 使用详解》，组件定位见《Isso 0.14.0 介绍与选型指南》。

一、环境信息

二、前置条件

1. 一套运行中的 Isso 0.14.0（部署步骤见本系列部署指南），版本确认：

curl -s http://127.0.0.1:8141/info

实测回显：

{"version": "0.14.0", "host": "http://127.0.0.1:8141", "origin": "http://10.89.71.1:8142", "moderation": true}

2. 已在配置文件中开启管理后台（[admin]），便于复核审核类参数：
3. （可选）本地 SMTP 测试存根（本文用约 30 行 Python 脚本在 2525 端口收信并落日志），用于逐行观察通知邮件报文——生产接真实邮箱前建议先用同法演练。

三、参数查看与修改方式

3.1 配置文件的定位与生效

• Isso 启动时先加载内置默认值，再用 ISSO_SETTINGS 环境变量指定的主配置覆盖。发行环境已内置 ISSO_SETTINGS=/config/isso.cfg，因此只需维护 /config 下的 isso.cfg；
• 该变量优先级高于命令行 -c 参数（源码 isso/__init__.py 注释原文：ISSO_SETTINGS env var takes precedence over -c flag）；
• 修改流程固定为三步：编辑 isso.cfg → 重启 Isso 服务 → 复核（启动日志 + /config 开关 + 行为实测）。不重启不生效。

3.2 运行时只读视图：/config 公开开关

/config 只暴露嵌入页需要的公开子集，不是全量配置：

curl -s http://127.0.0.1:8141/config

实测回显：

{"config": {"reply-to-self": true, "require-email": false, "require-author": false, "reply-notifications": true, "gravatar": true, "avatar": false, "feed": true}}

七个键与配置项的映射：reply-to-self ← [guard] reply-to-self；require-email / require-author ← [guard] 同名项；reply-notifications ← [general] reply-notifications；gravatar / avatar ← [general] gravatar（及头像开关）；feed ← [rss] base 是否非空。改完配置用该端点做第一层复核最方便。

3.3 配置语法要点

• INI 风格。缩进的连续行表示多值列表（如 [general] host、[server] trusted-proxies，源码 IssoParser.getiter 按行切分）；
• 时长值支持人类可读单位组合，如 15m、30d、3h45m12s（解析时统一换算成秒，源码 IssoParser.getint）；
• 布尔值用 true / false；
• 0.14.0 起配置值支持环境变量替换（官方 CHANGES #1037，实现于 IssoParser.get），口令类敏感项可留在宿主环境而非写入文件。

四、参数总览

五、核心参数分类详解

5.1 [general] 全局参数

5.2 [server] 服务参数

5.3 [admin] 管理后台参数

5.4 [moderation] 审核策略参数

审核闭环实测（enabled=true 全流程）：管理口令 POST /login/ 取得会话 → GET /admin/?mode=2 列出待审（页面内嵌每条的签名 key，形如 send_edit(5, 'NQ.auR_RQ.Rwrj_i5AkLiwQuLHKXUoIdfazHQ'）→ POST /id/<id>/activate/<key> 放行、POST /id/<id>/delete/<key> 删除（均返回 200）→ 放行后 GET /?uri= 公开可见（实测 total_replies 从 0 变 2）。SMTP 通知邮件正文同样携带 Activate/Delete 链接（GET 形态先出确认页、POST 才执行）；本文实测按邮件文本直接还原链接访问返回 403——链接经邮件 quoted-printable 编码，手工还原不精确即签名校验失败，生产上请直接使用邮件原链或管理后台。

5.5 [guard] 反垃圾参数

guard 在新评论入库前做拦截，命中即 403 且原因写明（POST /new 实测逐条命中过全部四类）：

来源聚合规则：来源 IP 先经 /24（IPv4）或 /48（IPv6）匿名化再计数——同网段用户共享全部配额。实测：以 X-Forwarded-For 伪造同网段两个地址（.24 与 .30）发评，第二个地址被第一个的计数撞限。经反向代理接入时务必配 [server] trusted-proxies，否则全站共享代理出口的一个桶。

5.6 [smtp] 邮件通知参数

通知报文实测（存根日志逐行）：管理员通知 From: Ich schrei sonst! <isso@example.com>（发件人显示名硬编码），Subject: New comment posted on Isso <线程标题>（中文标题走 UTF-8 base64 编码），正文 base64 编码，含评论内容、IP address、Link to comment、Delete comment 与 Activate comment 链接；回复通知如 5.1 所述发往父评论作者邮箱并带退订链接。SMTP 会话本身为标准流程（ehlo → mail FROM → rcpt TO → data → quit）。

5.7 [markup] 渲染参数

渲染行为实测三种情形：

1. 默认（escape 开启）：评论中的原始 HTML 整体转义为纯文本——<img ...>、<script>alert(1)</script> 均以转义文本呈现，XSS 注入无效；
2. 放行图片（本文 allowed-elements=img + allowed-attributes=src, alt）：Markdown 图片语法渲染为真元素——实测输出 <p>Markdown 图片：<img src="https://www.gravatar.com/avatar/97a979289edfdf0031359cff31583ef3?d=identicon&amp;s=55" alt="头像"></p>；
3. 默认白名单内：链接渲染为 <a href="https://isso-comments.de" rel="nofollow noopener">Isso 官网</a>（自动追加 nofollow/noopener），删除线渲染为 <del>不要了</del>。

5.8 [hash] 匿名化指纹参数

指纹出现在响应的 hash 字段（邮箱优先，未留邮箱用来源 IP），是前端生成 identicon 的输入。

5.9 [rss] 订阅参数

5.10 未实测参数如实说明

以下参数本文未实测，口径来自官方文档与源码，引用时请注意：[general] name 多站点分发；[server] reload / profile（仅内置服务器生效的开发参数）；[smtp] security=starttls/ssl 与真实外部邮箱投递；回复通知邮件中的退订（unsubscribe）闭环（链接形态已从邮件头确认，完整流程未走通）；[markup.misaka]（misaka 渲染器，0.14.0 已弃用）。

六、生产配置模板

以下模板整合本文全部实测结论，可直接作为生产起点（值按站点替换；演示后台口令务必换强口令）：

[general]
dbpath = /var/lib/isso/comments.db
host =
    https://comments.example.com/
    http://comments.example.com/
max-age = 15m
notify = stdout, smtp
reply-notifications = true
gravatar = true
latest-enabled = true

[server]
listen = http://0.0.0.0:8080/
trusted-proxies =
    127.0.0.1
samesite = Lax

[admin]
enabled = true
password = please_choose_a_strong_password

[moderation]
enabled = true
approve-if-email-previously-approved = true
purge-after = 30d

[guard]
enabled = true
ratelimit = 4
direct-reply = 3
reply-to-self = true
require-author = false
require-email = false

[smtp]
host = smtp.example.com
port = 587
security = starttls
username = isso-notifier@example.com
password = please_choose_a_strong_password
to = admin@example.com
from = isso@example.com
timeout = 10

[markup]
renderer = mistune
allowed-elements = img
allowed-attributes = src, alt

[hash]
salt = please_generate_a_random_salt_string
algorithm = pbkdf2

[rss]
base = https://comments.example.com/
limit = 100

要点：dbpath 移出临时目录；host 白名单写真实域名（首项须服务侧可达）；trusted-proxies 写紧贴服务的代理地址；salt 用随机长串且一经上线不再更换；其余与本文实测配置同构。

七、常见问题

1. 改了配置不生效：必须重启 Isso 服务；重启后先看启动日志（数据库路径、Mistune 引擎行），再用 /config 核对公开开关子集。
2. 启动 WARNING unable to connect to your website：[general] host 白名单逐项 HEAD 探测全部失败。检查首项是否服务侧可达——实测踩坑：页面服务与 Isso 不同网段时，白名单要写「从服务侧看得到的地址」（如网关地址），写宿主局域网 IP 会一直告警且建线程报 400 Cannot create new thread: URI ... is not accessible and no title was provided。
3. 提交返回 403 ratelimit exceeded (N, M)：60 秒窗口内同来源评论超限。来源按 /24 网段聚合，同网段共享额度；调大 ratelimit 或配好 trusted-proxies 让来源解析落到真实访客。
4. 提交返回 403 N direct responses to <uri>：同来源对该线程的直评达上限（默认 3，且无时间窗、终身累计）。引导用户以「回复」形式参与，或适度调大。
5. 待审评论不见了：purge-after 到期自动清理，不可恢复；审核要形成定期处理习惯（管理后台或邮件链接）。
6. 邮件收不到：确认 notify 含 smtp；用本地明文存根（security=none）验证协议交互后再切真实服务器；security 档位与服务器要求一致；to/from 已填。
7. 升级/迁移后所有头像变了：[hash] salt 与历史不一致。salt 变更会重算全部指纹，属预期行为；跨迁移应保持 salt 不变。
8. /feed 返回 404：[rss] base 为空即禁用 Feed，填写页面基地址即恢复。

参考链接

1. 官方配置参考：https://isso-comments.de/docs/reference/configuration/
2. 源码内置默认配置（0.14.0）：https://github.com/posativ/isso/blob/0.14.0/isso/isso.cfg
3. 0.14.0 Release 说明（Mistune 引擎、环境变量替换等变更）：https://github.com/posativ/isso/releases/tag/0.14.0
4. GitHub 仓库：https://github.com/posativ/isso