Schleuder 5.0.0 配置参数详解：schleuder.yml 与 list-defaults.yml 逐项解析

目标：把 Schleuder 的两个 YAML 配置文件——全局主配置 schleuder.yml 与新建列表默认值模板 list-defaults.yml——逐项讲透：每个参数管什么、默认值是什么、改了影响什么、生产上建议怎么配。全部参数取自 5.0.0 与 4.0.3 实机安装生成的配置文件本体（官方第一手注释），并标注两个大版本间的差异。安装过程见本专栏《Schleuder 5.0.0 安装指南》。

一、配置体系全景：三层结构

Schleuder 的配置分三层，理解层级关系比记住每个参数更重要：

/etc/schleuder/schleuder.yml        ← 全局层：服务器级（路径/SMTP/数据库/API），改动即时生效（重启 API daemon）
/etc/schleuder/list-defaults.yml    ← 模板层：只对「之后新建」的列表生效
数据库（列表级 options）             ← 实际层：每个列表自己的参数副本，运行时真正读的是这一层

三条关键生效规则（官方注释原文明确 + 实测确认）：

1. 模板层是快照不是引用：list-defaults.yml 的注释开宗明义——"Once a list is created it is not affected by these settings but has its own set of options in the database"（列表一旦创建就不受这些设置影响，它有自己的数据库选项集）。改模板不会波及存量列表；
2. 改存量列表要走 API/CLI：用 schleuder-cli lists save 系命令改单个列表属性（详见 D1 篇）；
3. 全局层立即生效但需重启：schleuder.yml 属于 daemon 进程的启动参数，改后需重启 schleuder-api-daemon（systemd 环境下 systemctl restart schleuder-api-daemon）。

二、schleuder.yml 逐项解析（全局层）

2.1 路径与目录段

💡 运维要点：lists_dir 里是密钥环，umask 与属主错一个字符都可能造成「列表无法解密」级别的事故，变更前先备份。

2.2 日志与杂项

2.3 公钥检索段（4.0 → 5.0 的最大配置差异）

Schleuder 需要按需从公钥服务器拉取订阅者公钥。两个版本模型不同：

4.0.3（Debian 12 包）——单一 keyserver 参数：

#keyserver: hkps://hkps.pool.sks-keyservers.net   # gnupg 2.1 建议 hkps
#keyserver: hkp://jirk5u4osbsr34t5.onion          # 本机有 Tor 时的 onion 服务
keyserver:                                        # Debian 打包者注释：交由系统级 gpg 配置

5.0.0（官方 gem）——拆分为 VKS/SKS 双服务器 + 代理：

💡 升级提示：从 4.x 迁移到 5.x 时，旧的 keyserver: 参数会被静默忽略，必须改写成 vks_keyserver/sks_keyserver 成对的新格式。

2.4 出站邮件段：smtp_settings

传给 Ruby ActionMailer 的 SMTP 参数，5.0.0 默认只启用两行，其余注释待用：

smtp_settings:
  address: localhost   # 出站 SMTP 服务器地址
  port: 25             # 端口
  #domain: / #enable_starttls_auto: / #openssl_verify_mode:
  #authentication: / #user_name: / #password:

2.5 数据库段：database

database:
  production:
    adapter:  'sqlite3'
    database: /var/lib/schleuder/db.sqlite
    timeout:  5000

• 默认 SQLite，单文件 /var/lib/schleuder/db.sqlite，timeout: 5000（毫秒，SQLite 锁等待上限）；
• 只需维护 production 段（development/test 段仅测试用）；
• 换 MySQL/MariaDB：改 adapter、建库、gem install mysql2（或发行版对应包）后重跑 schleuder install 建表（B1 篇实测输出原文也提示了这条路径）。

2.6 API 段：api（服务端核心安全参数）

api:
  host: localhost
  port: 4443
  tls_cert_file: /etc/schleuder/schleuder-certificate.pem
  tls_key_file:  /etc/schleuder/schleuder-private-key.pem
  valid_api_keys:
    - q1w2e3r4-QWERTY-key-0001

三、list-defaults.yml 逐项解析（模板层）

以下参数构成每个新建列表的初始选项集。按功能分组讲解（默认值均为 5.0.0 实机值）。

3.1 收发加密门槛（安全核心组）

💡 组合心法：send_encrypted_only: true（默认）保证出站永远密文；入站三开关（encrypted/signed/authenticated）是逐级收紧的三道门。社群秘密列表的常见基线是只开 receive_authenticated_only: true——既能进能出又不拒收「忘加密但验签通过」的内部信。

3.2 邮件头与线程处理（隐私权衡组）

3.3 关键词权限组（邮件命令的管控面）

3.4 主题前缀与页脚（版面组）

3.5 退信与容量防护组

3.6 行为杂项组

四、4.0 vs 5.0 配置差异对照（实测 diff 摘要）

五、生产最小安全基线（可直接抄）

# schleuder.yml 建议落点（在默认值基础上）
superadmin: admin@example.org          # 换成真实 postmaster 邮箱
umask: 0077                            # 保持不动
api:
  host: localhost                      # 管理面不对网，远程管理走 SSH 隧道
  valid_api_keys:
    - <长随机串>                        # 别用示例值
smtp_settings:
  address: 127.0.0.1                   # 出站交给本机 MTA
  port: 25

# list-defaults.yml 建议落点（新列表继承）
send_encrypted_only: true              # 默认即 true，确认未放松
receive_authenticated_only: true       # 入站验签门（最强身份机制）
bounces_drop_on_headers:
  x-spam-flag: yes
max_message_size_kb: 10240
forward_all_incoming_to_admins: false  # 排障时才临时开

配套纪律：valid_api_keys 用密码管理器生成 ≥32 位随机串；TLS 指纹分发到每台运行 schleuder-cli 的客户端（schleuder-cli 的对应校验配置见 D1 篇）；lists_dir 与数据库纳入加密备份。

六、常见配置错误速查

七、下一篇

参数就位后，真正的高频操作都发生在「邮件关键词命令」与 schleuder-cli 里。下一篇《常用 CLI 命令详解》以实测输出逐条演示列表创建、订阅管理、密钥操作与 API 探活的完整命令链。