Listmonk 6.2.0 配置参数详解

目标：系统梳理 Listmonk 6.2.0 的全部配置入口——config.toml 配置文件逐项说明、命令行参数全表、LISTMONK_ 环境变量命名规则与机密文件模式、Settings API 运行时设置全景，并重点讲清 v6 版本 SMTP 配置位置变化与 Bounce（退信）策略配置。本文所有配置值与回显均在 v6.2.0 环境实测取得。

一、环境信息

• Listmonk 版本：v6.2.0（--version 实测输出 v6.2.0 (ef0a7587 2026-06-26T10:21:29Z, linux/amd64)，构建目标 linux/amd64）
• Web/API 端口：9000（app.address 默认 localhost:9000；app.root_url 默认 http://localhost:9000）
• PostgreSQL 连接默认值：localhost:5432，库名/账号/口令 listmonk（config.toml [db] 段实测默认值）
• 配置路径：config.toml（--config 指定，默认工作目录）；i18n 目录（--i18n-dir）与静态文件目录（--static-dir）可选指定

二、配置体系总览

Listmonk v6.2.0 的配置分布在三个层次，各自生效范围不同：

三者分工：启动相关的「连什么库、听什么端口」放配置文件或环境变量；运营相关的「发信账号、站点名、退信策略」放运行时设置。

⚠️ v6 关键变化：SMTP 发信配置已归入第三层（数据库运行时设置），不再支持用 LISTMONK_smtp__* 环境变量配置（实测证据见第七章）。这是从旧版本升级时最容易踩的坑。

三、config.toml 配置文件逐项详解

以下为 ./listmonk --new-config 生成的样例文件全文（实测原文）：

[app]
# Interface and port where the app will run its webserver.  The default value
# of localhost will only listen to connections from the current machine. To
# listen on all interfaces use '0.0.0.0'. To listen on the default web address
# port, use port 80 (this will require running with elevated permissions).
address = "localhost:9000"

# Database.
[db]
host = "localhost"
port = 5432
user = "listmonk"
password = "listmonk"

# Ensure that this database has been created in Postgres.
database = "listmonk"

ssl_mode = "disable"
max_open = 25
max_idle = 25
max_lifetime = "300s"

# Optional space separated Postgres DSN params. eg: "application_name=listmonk gssencmode=disable"
params = ""

3.1 [app] 段

3.2 [db] 段

四、命令行参数详解

./listmonk --help 实测输出全文：

      --config strings      path to one or more config files (will be merged in order) (default [config.toml])
      --i18n-dir string     (optional) path to directory with i18n language files
      --idempotent          make --install run only if the database isn't already setup
      --install             setup database (first time)
      --new-config          generate sample config file (at path given in --config)
      --passive             run in passive mode where campaigns are not processed
      --static-dir string   (optional) path to directory with static files
      --upgrade             upgrade database to the current version
      --version             show current version of the build
      --yes                 assume 'yes' to prompts during --install/upgrade

五、环境变量配置

5.1 命名规则

环境变量是 config.toml 的等价载体，命名规则为 LISTMONK_ + 配置段 + 双下划线 + 配置键：

规则要点：段与键之间是双下划线 __；段名与键名保持原有大小写（app/db 小写）。该映射可通过 docker compose config 渲染实测确认（《Docker Compose 部署指南》5.2 节）。

5.2 管理员自动创建变量

两个特殊变量不属于 config.toml 的键，仅在有意义的时机生效：

数据库初始化完成后这两个变量不再起作用，修改不会更新已有账号。compose 部署实测：设置 LISTMONK_ADMIN_USER: admin、LISTMONK_ADMIN_PASSWORD: q1w2e3r4 后首次 up，无需网页初始化即可直接登录后台。

5.3 机密文件模式

所有 LISTMONK_* 环境变量（含 LISTMONK_ADMIN_USER 等大写变量）均支持 _FILE 后缀变体：LISTMONK_ADMIN_USER_FILE=/path/to/file_with_value 指向一个存有真实值的文件，程序启动时读取文件内容作为变量值。该模式用于 Docker secrets / Podman secrets 场景，避免口令明文写在编排文件中（官方镜像文档说明）。

六、数据库运行时设置（Settings API）

6.1 settings 键全景

GET /api/settings 返回的设置键组（实测枚举，按前缀归类）：

6.2 关键默认值（实测）

注意 app.root_url 默认指向 localhost:9000——对外服务时务必改为真实域名，否则邮件中的退订链接、订阅页链接都会指向错误地址。

6.3 读写方式

运行时设置通过后台 Settings 页面或 API 读写。API 调用约定：

• GET /api/settings 返回完整设置对象；
• PUT /api/settings 要求全量回传：先 GET、在返回对象上修改目标键、再整体 PUT（实测 PUT 成功返回 {"data":true}）；
• 只传局部键会覆盖丢失其余设置，务必走「GET → 修改 → PUT」闭环。

七、v6 版本关键差异：SMTP 配置存放位置变化

结论：v6 起 SMTP 发信配置只存在于数据库运行时设置中，环境变量方式无效。

实测过程（该实验在 v6.1.0 的 compose 环境完成，结论对 v6.2.0 同样适用）：

1. 在 compose 中注入发信环境变量 LISTMONK_smtp__enabled: "true"、LISTMONK_smtp__host: mailpit、LISTMONK_smtp__port: "1025" 等，启动服务；
2. 启动日志显示发信通道仍使用默认占位 SMTP：messenger: username@smtp.yoursite.com；
3. 调用 GET /api/settings 回读，smtp[0].host 仍为默认值 smtp.yoursite.com——环境变量注入未生效；
4. 改走 Settings API：PUT /api/settings 把 smtp[0] 更新为 {"enabled": true, "host": "mailpit", "port": 1025, "auth_protocol": "", "tls_type": "none", "max_conns": 2}，返回 {"data":true}；回读确认写入成功，启动日志随后显示发信通道初始化为 @mailpit。

排障指引：如果发信不走预期 SMTP，先 GET /api/settings 看 smtp[0] 是否为默认值 smtp.yoursite.com——是则说明配置还在默认态，去后台 Settings → SMTP 或按上述 API 流程写入即可。

💡 技术拓展：settings 中的 smtp 是数组，支持配置多条发信通道并各自启用/停用；PUT 时数组整体提交。每条通道的键包括 enabled、host、port、auth_protocol（none/plain/cram-md5/空串）、tls_type（none/starttls/tls）、username、password、max_conns、max_msg_retries、wait_timeout、idle_timeout 等（实测键名以 GET 返回为准）。配置保存后可用 POST /api/settings/smtp/test 做连通性测试（请求体为该条 SMTP 配置加 email 收件地址字段，实测返回 200 并在收件箱收到主题为 Test connection 的测试邮件）。

八、Bounce（退信）配置

8.1 bounce.actions 默认策略

bounce.actions 定义收到退信（及投诉）后的自动处置阈值，实测默认值：

即：一次硬退信或一次投诉立即拉黑订阅者；连续两次软退信仅记录不处置。实测验证：向 /webhooks/bounce 上报一次 hard 退信后，对应订阅者状态自动变为 blocklisted（完整实操见《进阶实战与运维》）。

8.2 POP3 邮箱扫描配置

Listmonk 支持从 POP3 邮箱拉取退信通知。bounce.mailboxes 中每个邮箱的配置结构（实测可用形态）：

{
  "enabled": true,
  "type": "pop",
  "host": "mail.example.com",
  "port": 1110,
  "auth_protocol": "userpass",
  "username": "bounce@listmonk.local",
  "password": "password",
  "tls_type": "none",
  "scan_interval": "1m",
  "return_path": ""
}

启用扫描需同时打开 bounce.enabled 与 bounce.webhooks_enabled。两个实测约束：

• 扫描间隔下限 1 分钟：把 scan_interval 设为 30s 保存时被拒绝，报错原文 Bounce scan interval should be minimum 1 minute.；
• return_path 用于发信时标记回执地址，配合服务商的退信投递。

真实生产环境将 host 指向真实邮箱服务商（或自建 Dovecot 等）的 POP3 服务即可；测试环境如用 Mailpit 模拟，注意其 POP3 服务默认关闭，需以 --pop3 与 --pop3-auth-file 参数启用，否则扫描会持续报连接拒绝（排障实录见《进阶实战与运维》）。

九、常见问题与排障

9.1 环境变量配置了 SMTP 却不生效

v6 起 LISTMONK_smtp__* 不再是有效配置入口（实测第七章）。改用后台 Settings 或 Settings API 配置，保存后回读确认 smtp[0].host 已更新。

9.2 PUT /api/settings 后部分设置丢失

PUT 是全量覆盖语义。必须先 GET 拿到完整对象、只修改目标键、再整体回传；从零手拼局部对象会覆盖丢失其余设置。

9.3 外部访问邮件里的链接是 localhost

app.root_url 保持默认 http://localhost:9000 所致。在 Settings 中把 root_url 改为对外域名（如 https://lists.example.com），此后退订链接、订阅页链接均基于该地址生成。

9.4 scan_interval 设为 30 秒保存报错

扫描间隔下限 1 分钟，报错 Bounce scan interval should be minimum 1 minute.。改为 1m 及以上即可。

十、参考链接

• Listmonk 配置文档：https://listmonk.app/docs/configuration/
• 环境变量说明（官方 compose 文件头注释）：https://github.com/knadh/listmonk/blob/master/docker-compose.yml
• Settings API：https://listmonk.app/docs/apis/
• GitHub 仓库：https://github.com/knadh/listmonk