chasquid 1.19.0 配置参数详解

目标：逐组讲透 chasquid 1.19.0 的全部配置项——/etc/chasquid/chasquid.conf 的 18 个主参数按「基础标识 / 端口监听 / 监控端点 / 本地投递 / 地址归一化 / 日志 / Dovecot 桥接 / HAProxy / 队列」九组拆解，每个参数给出类型、默认值、生效方式与实测验证方法；并覆盖 domains/、certs/、hooks/ 三处目录型配置。全部验证均在 Ubuntu 22.04.5 LTS + chasquid v1.19.0 服务器（主机名 mail.chasquid.example，邮件域 chasquid.example）上实测通过。

一、环境信息

• 操作系统：Ubuntu 22.04.5 LTS（jammy），x86_64
• chasquid：v1.19.0（源码编译安装，二进制在 /usr/local/bin/；参数集与发行版 1.8 的差异见 4.2 节标注）
• 主机名：mail.chasquid.example；示例邮件域：chasquid.example
• 配置路径：/etc/chasquid/（主配置 chasquid.conf + domains/ + certs/ + hooks/）
• 数据路径：/var/lib/chasquid/（队列、domaininfo、STS 缓存、LocalRPC 套接字）
• 安装方式：见本专栏 《Ubuntu 22.04 安装 chasquid 指南》第五节（源码编译 v1.19.0）

二、前置条件

• chasquid 1.19.0 已安装并能启动（systemctl is-active chasquid.service 返回 active）；
• 已至少创建一个域名与用户（chasquid-util user-add admin@chasquid.example --password=q1w2e3r4），否则服务拒绝启动；
• certs/ 下至少有一张证书（本篇实验用自签名证书，CN=mail.chasquid.example）；
• 了解配置的书写格式：chasquid.conf 为「参数名: 值」的简单文本格式，# 开头为注释，字符串值用双引号，布尔值 true/false，数值直接书写；同名参数可重复出现多次形成列表（典型如 mail_delivery_agent_args）。

三、参数查看与修改方式

3.1 查看当前生效配置：chasquid-util print-config

改配置最怕「改了没生效」。chasquid 提供 print-config 子命令直接输出进程视角的生效配置：

chasquid-util print-config

实测回显（v1.19.0，监控与 MDA 已按本篇实验改动）：

hostname:  "mail.chasquid.example"
max_data_size_mb:  50
smtp_address:  ":25"
submission_address:  ":587"
submission_over_tls_address:  ":465"
monitoring_address:  "127.0.0.1:1099"
mail_delivery_agent_bin:  "procmail"
mail_delivery_agent_args:  "-f"
mail_delivery_agent_args:  "%from%"
mail_delivery_agent_args:  "-d"
mail_delivery_agent_args:  "%to_user%"
data_dir:  "/var/lib/chasquid"
suffix_separators:  "+"
drop_characters:  "."
mail_log_path:  "<syslog>"
max_queue_items:  200
give_up_send_after:  "20h"

注意 print-config 会把默认值也显式列出（文件里未写的参数以默认值补全），且同名列表参数逐行重复展示——这是核对「列表型参数」最直观的方式。

3.2 服务端启动时的配置转储

每次启动，chasquid 都把解析后的配置打进日志，可用 journalctl 核对：

journalctl -u chasquid.service --no-pager -b | grep -A14 'Configuration:' | head -16

实测回显：

Oct 21 02:23:46 mail.chasquid.example chasquid[8389]: _ config.go:173        Max queue items: 200
Oct 21 02:23:46 mail.chasquid.example chasquid[8389]: _ config.go:174        Give up send after: 20h0m0s
Oct 21 02:23:46 mail.chasquid.example chasquid[8389]: _ chasquid.go:91     Loading certificates:
Oct 21 02:23:46 mail.chasquid.example chasquid[8389]: _ chasquid.go:264      mail.chasquid.example
Oct 21 02:23:46 mail.chasquid.example chasquid[8389]: _ monitoring.go:92   Monitoring HTTP server listening on 127.0.0.1:1099
Oct 21 02:23:46 mail.chasquid.example chasquid[8389]: _ chasquid.go:104    Loading domains:
Oct 21 02:23:46 mail.chasquid.example chasquid[8389]: _ chasquid.go:338      chasquid.example (2 users, 0 aliases, 0 DKIM keys)

3.3 修改与重载流程

chasquid 没有 reload 信号，配置变更一律走「改文件 → 重启」流程：

sudo vim /etc/chasquid/chasquid.conf
chasquid-util print-config          # 改后先核对（读文件，不依赖服务）
sudo systemctl restart chasquid.service
journalctl -u chasquid.service --no-pager -n 5

⚠️ 注意：print-config 读的是配置文件与目录结构，不校验参数合法性；真正的合法性校验发生在 restart 时，改错参数名会导致服务起不来——所以 restart 后必须跟一条 systemctl is-active chasquid.service 确认。

四、参数总览

4.1 chasquid.conf 主参数速查表（v1.19.0 全集，18 个）

4.2 与 Ubuntu 包 1.8 版的参数差异

1.8-1ubuntu0.3 的配置骨架不含两个队列参数（max_queue_items、give_up_send_after，1.15 前后引入），且监听参数默认值同为 "systemd"（配合 Ubuntu 包的三个 socket 单元）。其余参数两版一致。用 chasquid-util print-config 在两版上分别核对即可确认。

五、核心参数分类详解

5.1 基础标识组：hostname 与 max_data_size_mb

hostname 是 chasquid 对外的身份：对客户端出现在 250 应答 banner 里，对外发时用作 HELO/EHLO 域名。默认取系统主机名；正式环境应设为「能反解回本机 IP 的名字」（如 mail.example.com），有利于对端 SPF/反向校验。

hostname: "mail.chasquid.example"

验证：banner 即它（实测见 6.1 节）。

max_data_size_mb 限制单封信体积，默认 50MB，直接决定 EHLO 应答里的 SIZE 值（50 × 1024 × 1024 = 52428800 字节）。收大附件的场景可调大，但注意上限同时约束内存缓冲。

5.2 端口监听组：三个 address 参数（本组最重要的概念：systemd 与直连两种形态）

三个监听参数的取值都有两种形态：

• "systemd"（默认）：不由 chasquid 自己绑端口，而是接收 systemd 传入的文件描述符。要求存在 FileDescriptorName=smtp（或 submission / submission_tls）的 socket 单元。Ubuntu/Debian 包正是这个形态——chasquid-smtp.socket、chasquid-submission.socket、chasquid-submission_tls.socket 三个 socket 单元持有 25/587/465，服务重启期间端口不掉线；
• ":25" 形式：chasquid 直接绑定（可写多行监听多地址，如 ":25" 与 "192.168.1.10:25"）。上游源码自带 systemd 单元配合 AmbientCapabilities=CAP_NET_BIND_SERVICE 走这个形态。

本篇实验环境（上游单元 + 源码安装）即直连形态，三个参数的实测值：

smtp_address: ":25"
submission_address: ":587"
submission_over_tls_address: ":465"

重启后验证监听：

systemctl restart chasquid.service
ss -ltn | grep -E ':(25|465|587)\b'

实测回显：

LISTEN 0      4096               *:587             *:*
LISTEN 0      4096               *:25              *:*
LISTEN 0      4096               *:465             *:*

日志里两种形态的鉴别特征（实测）：直连形态打印 Server listening on :25 (SMTP)，socket 激活形态打印 Server listening on [::]:25 (SMTP, via systemd)。

💡 技术拓展：MTA 的三个经典端口各有分工——25 号是服务器间转发（MTA↔MTA），587 号是用户提交（要求认证，先 STARTTLS），465 号是隐式 TLS 的提交端口（连上即 TLS，无 STARTTLS 协商）。把「收信」与「用户提交」分开，是反滥用与审计的基本盘，三个监听参数正好一一对应。

5.3 监控端点组：monitoring_address

监控 HTTP 服务默认关闭（参数不设即无），设为监听地址即开启。官方文档明确警告「Do NOT expose this to the public internet」——端点暴露队列、配置、pprof 剖析等敏感面，务必只绑回环或内网管理网段：

monitoring_address: "127.0.0.1:1099"

开启后启动日志：

Oct 21 02:23:46 mail.chasquid.example chasquid[8389]: _ monitoring.go:92   Monitoring HTTP server listening on 127.0.0.1:1099

端口确认：

ss -ltn | grep 1099

实测回显：

LISTEN 0      4096       127.0.0.1:1099      0.0.0.0:*

监控端点的完整清单（/metrics、/debug/queue、/debug/config 等）与 Prometheus 对接见本专栏 《chasquid 1.19.0 常用 CLI 命令详解》 的监控章节。

5.4 本地投递组：mail_delivery_agent_bin 与 mail_delivery_agent_args

chasquid 自己不做 mailbox 写入，本地投递全权交给外部 MDA：信件从 stdin 喂给 mail_delivery_agent_bin，退出码非零即视为投递失败。

mail_delivery_agent_bin 默认 maildrop。⚠️ 实测要点：Ubuntu 的 maildrop 构建依赖 courier-authdaemon，独立安装的机器上会报 exit status 75 - ERR: authdaemon: s_connect() failed（完整排障实录见 《Ubuntu 22.04 安装 chasquid 指南》8.2 节）。本篇实测改用 procmail：

mail_delivery_agent_bin: "procmail"

mail_delivery_agent_args 是逐行书写、可重复的参数列表，支持五个占位符替换（以发件 marsnik@mars → 收件 venera@venus 为例）：

默认值 -f %from% -d %to_user% 对 procmail/maildrop 都适用（procmail 侧 -d 指定收件用户）。print-config 的实测回显里它以四行重复出现：

mail_delivery_agent_args:  "-f"
mail_delivery_agent_args:  "%from%"
mail_delivery_agent_args:  "-d"
mail_delivery_agent_args:  "%to_user%"

改配置时最常见错误是只加一行 mail_delivery_agent_bin 而默认 args 仍在——args 与 bin 是独立参数，二者需配套检查。

5.5 数据目录组：data_dir

队列信封、投递状态、domaininfo（远端域 TLS 能力记忆）、STS 缓存、LocalRPC 管理套接字都落在 data_dir（默认 /var/lib/chasquid）。目录属主必须是服务运行用户（上游单元为 mail），权限建议保持 0700：

ls -la /var/lib/chasquid/ && stat -c '%U:%G %a' /var/lib/chasquid

实测回显：

drwx------  2 mail mail 4096 Oct 21 02:23 .
mail:mail 700

迁盘/换目录时改本参数并同步 chown 即可；备份策略把 /var/lib/chasquid 与 /etc/chasquid 一起纳入即可覆盖全部状态。

5.6 地址归一化组：suffix_separators 与 drop_characters

两个参数共同决定「怎么把变体地址归到真实用户」：

• suffix_separators（默认 +）：地址中分隔符之后的部分视为后缀丢弃，user+anything@ 归投 user@。官方强烈建议包含 +（邮件转发链路普遍假设它存在）；
• drop_characters（默认 .）：用户名内出现的这些字符直接删掉再查库，u.se_r 归投 user。

两个实测验证（收件人写变体，观察投进真实用户邮箱）：

变体一（+ 后缀）：

python3 -c "
import smtplib
from email.message import EmailMessage
msg = EmailMessage()
msg['From'] = 'admin@chasquid.example'
msg['To'] = 'lab+news@chasquid.example'
msg['Subject'] = 'suffix test'
msg.set_content('via 465 SMTP_SSL')
s = smtplib.SMTP_SSL('127.0.0.1', 465)
s.login('admin@chasquid.example', 'q1w2e3r4')
s.send_message(msg)
print('sent to lab+news@')
s.quit()"
tail -1 /var/mail/lab

实测回显：

sent to lab+news@
via 465 SMTP_SSL

变体二（. 丢弃字符）：

python3 -c "
import smtplib
from email.message import EmailMessage
msg = EmailMessage()
msg['From'] = 'admin@chasquid.example'
msg['To'] = 'l.a.b@chasquid.example'
msg['Subject'] = 'drop characters test'
msg.set_content('u.se_r style test')
s = smtplib.SMTP('127.0.0.1', 25)
s.ehlo('client.chasquid.example')
s.send_message(msg)
print('send to l.a.b@ OK')
s.quit()"
tail -1 /var/mail/lab

实测回显：

send to l.a.b@ OK
u.se_r style test

两次变体地址（lab+news@、l.a.b@）都精准落进了 lab 用户的邮箱——归一化在收信、认证、别名匹配各环节全局生效。安全提醒：drop_characters 会扩大「同名不同写法」的攻击面（攻击者可用变体名冒充），语义上等价的地址应视为同一身份。

5.7 日志组：mail_log_path

默认 <syslog>，即邮件投递日志走 syslog（MAIL|INFO 优先级），systemd 环境下随 journalctl 可查（本篇所有投递日志均来自 journalctl）。另两个内置去向：

• mail_log_path: "<stdout>" / "<stderr>"：前台运行时输出到标准流（适合前台调试或未用 systemd 托管的场景）；
• mail_log_path: "/var/log/chasquid/mail.log"：写文件（目录需运行用户可写，建议配 logrotate）。

💡 技术拓展：MTA 日志通常分两类——协议日志（SMTP 会话、命令、应答）与投递日志（队列 ID、投递结果、重试计划）。chasquid 把投递日志集中到 mail_log_path，把进程级日志（启动配置转储、监听、错误栈）交给 systemd/标准流，二者不要混为一谈。

5.8 Dovecot 桥接组：dovecot_auth / dovecot_userdb_path / dovecot_client_path

dovecot_auth: true 时，chasquid 自己的用户库查不到的用户会转交 Dovecot 认证——典型用法是 IMAP（Dovecot）与 SMTP（chasquid）共用一套账号口令。两个路径参数留空即自动探测标准位置（如 /var/run/dovecot/auth-userdb 与 auth-client），非标安装才需要显式指定：

dovecot_auth: true
#dovecot_userdb_path: "/var/run/dovecot/auth-userdb"
#dovecot_client_path: "/var/run/dovecot/auth-client"

启动日志会回显当前状态：Dovecot auth: false ("", "")（未启用时），启用后为 Dovecot auth: true (<路径>, <路径>)。注意 Dovecot 侧需开启 auth socket 服务，且 chasquid 运行用户要有套接字读权限。

5.9 HAProxy 组：haproxy_incoming

chasquid 部署在 HAProxy 后面时，HAProxy 的 proxy protocol 会把客户端真实 IP 前置到连接流里；haproxy_incoming: true 让 chasquid 解析它，否则所有来信看起来都来自 HAProxy 本机，SPF 检查、日志与 fail2ban 封禁全部失真。官方在早期版本标注过 EXPERIMENTAL（可能向后不兼容变更），上生产前在自己版本上验证一遍：

haproxy_incoming: false

5.10 队列组：max_queue_items 与 give_up_send_after（1.15+ 新增）

max_queue_items（默认 200）：队列在内存中持有全部未完成信件，达到上限后拒收新邮件（给发送方返回临时错误）。默认值偏保守，抬高前先评估内存（每封信在内存中持有信封与信体）。验证：

journalctl -u chasquid.service --no-pager -b | grep 'Max queue items'

实测回显：

Oct 21 02:23:46 mail.chasquid.example chasquid[8389]: _ config.go:173        Max queue items: 200

give_up_send_after（默认 "20h"）：对每个收件人重试外发的总时长上限，超时放弃并向发件人回 DSN。格式是 Go duration 字符串（"48h"、"360m"；不支持天单位）。实测日志中格式化为 Give up send after: 20h0m0s。

重试与放弃的实测观察（本地 MDA 持续失败期间）：

Oct 21 02:14:13 mail.chasquid.example chasquid[1085]: _ queue.go:326       Queue.SendLoop az_TncfNqfo: waiting for 1m15s
Oct 21 02:14:13 mail.chasquid.example chasquid[1085]: az_TncfNqfo from=root@chasquid.example completed loop, next in 1m15s

队列逐次递增等待（1m15s → 更长），期间信件持久化在 data_dir，重启不丢。

六、目录型配置：domains/、certs/、hooks/

chasquid 的一半「配置」不在主文件里，而在三个目录中。

6.1 domains/：域名、用户库与别名

每个邮件域一个子目录，目录名即域名：

/etc/chasquid/domains/chasquid.example/
├── users              # 用户口令库（chasquid-util user-add 维护）
├── aliases            # 别名表（纯文本）
└── dkim:20261021.pem  # DKIM 私钥（1.14+，文件名 dkim:<selector>.pem）

users 由 chasquid-util 全权管理，勿手改；aliases 是可手编的经典格式：

# /etc/chasquid/domains/chasquid.example/aliases
support: admin, lab
abuse: admin

别名生效需重启（或至少保证服务启动后文件在位），用运行时查询验证：

chasquid-util aliases-resolve support@chasquid.example

实测回显：

(email)  admin@chasquid.example
(email)  lab@chasquid.example

启动日志同步显示域加载结果：

Oct 21 02:23:46 mail.chasquid.example chasquid[8389]: _ chasquid.go:338      chasquid.example (2 users, 0 aliases, 0 DKIM keys)

DKIM 密钥文件名中的 selector 会出现在 DNS 记录与签名头里（<selector>._domainkey.<域名>），用 chasquid-util dkim-keygen <域名> 生成时以当天日期为默认 selector，轮换密钥时自然去重。

6.2 certs/：TLS 证书目录

结构与 certbot 完全一致：certs/<证书名>/fullchain.pem + privkey.pem，证书名匹配 SNI/连接名。上游骨架直接把 certs 做成指向 /etc/letsencrypt/live/ 的软链——有 certbot 的机器零配置接入；没有时删除软链建真实目录（见 《Ubuntu 22.04 安装 chasquid 指南》5.4 节）。加载结果看启动日志：

Oct 21 02:23:46 mail.chasquid.example chasquid[8389]: _ chasquid.go:91     Loading certificates:
Oct 21 02:23:46 mail.chasquid.example chasquid[8389]: _ chasquid.go:264      mail.chasquid.example

多证书场景（一台机器服务多个域名）就是把多个目录并排放，chasquid 按连接名自动选证书。

6.3 hooks/：post-data 钩子

hooks/post-data 是 DATA 收完后的外部检查点：脚本以环境变量拿到会话上下文（如 AUTH_AS 认证身份、SPF_PASS 检查结果），信件内容从 stdin 读入。退出码 20 = 永久拒收，其他非零 = 临时错误。官方示例脚本串联了 greylistd 灰名单、SpamAssassin/rspamd 反垃圾与 ClamAV 杀毒（探测到哪个装了就启用哪个）。这是 chasquid 扩展反垃圾能力的主要入口。

七、生产配置模板

适用场景：2~8GB 内存、SSD、单域名或少数几个自有域名的个人/小团队服务器，Dovecot 同机提供 IMAP，证书来自 certbot。

# /etc/chasquid/chasquid.conf —— 生产基线模板

hostname: "mail.example.com"

# 信件上限按业务定；50MB 默认已覆盖绝大多数场景
max_data_size_mb: 50

# 源码安装（上游 systemd 单元）用直连形态：
smtp_address: ":25"
submission_address: ":587"
submission_over_tls_address: ":465"
# Ubuntu/Debian apt 包安装则保持默认（三行注释掉或删掉）：
#smtp_address: "systemd"
#submission_address: "systemd"
#submission_over_tls_address: "systemd"

# 监控只对内网/本机开放，绝不放公网
monitoring_address: "127.0.0.1:1099"

# 本地投递：procmail 稳（maildrop 需 authdaemon）
mail_delivery_agent_bin: "procmail"
mail_delivery_agent_args: "-f"
mail_delivery_agent_args: "%from%"
mail_delivery_agent_args: "-d"
mail_delivery_agent_args: "%to_user%"

# 数据与归一化保持默认即可
data_dir: "/var/lib/chasquid"
suffix_separators: "+"
drop_characters: "."

# 邮件投递日志落文件（配 logrotate），进程日志在 journal
mail_log_path: "/var/log/chasquid/mail.log"

# 同机 Dovecot 共用账号时打开
dovecot_auth: true

# 小队列入门值；日邮件量大时再评估抬升
max_queue_items: 500
give_up_send_after: "48h"

要点回顾：hostname 必须可反解；monitoring_address 不出回环/管理网；队列参数按内存预算调；give_up_send_after 对「收件方偶发故障但最终可达」的场景给足 48h 比 20h 温和。

八、常见问题（FAQ）

Q1：改了配置没生效？ chasquid 无热重载。流程必须是「改文件 → systemctl restart chasquid.service → chasquid-util print-config 核对」。print-config 读文件即可核对，不必等服务。

Q2：restart 后服务起不来了？ 九成是参数拼写或值格式错误（如时长写成 "2d"——不支持天单位，应写 "48h"）。先 journalctl -u chasquid.service --no-pager -n 20 看报错行，修正后重启。全新安装起不来另见 《Ubuntu 22.04 安装 chasquid 指南》8.1 节（domains/ 为空、certs/ 为空两类启动失败）。

Q3：如何确认某参数的默认值？ 两个权威来源：源码骨架 etc/chasquid/chasquid.conf（每个参数的注释里写明 Default）与 chasquid-util print-config（回显生效值，未写即默认）。man 手册 man chasquid.conf 亦有全集。

Q4：监听参数写 "systemd" 但服务起不来？ 说明没有配套的 socket 单元。该形态只适用于 apt 安装（包自带三个 socket 单元）；源码安装请用 ":25" 直连形态，或自己写 socket 单元并保证 FileDescriptorName 与参数对应（smtp / submission / submission_tls）。

Q5：想给不同域名用不同证书？ certs/ 下每个子目录一张证书（目录名即证书名），chasquid 按连接名自动选。无需在 chasquid.conf 里声明。

Q6：max_queue_items 满了会发生什么？ 新来信被拒（临时错误），发送方会稍后重试——这是自我保护而非丢信。监控端点 /metrics 的 chasquid_queue_putCount 可观测队列流速。

九、参考链接

• chasquid.conf 官方骨架（逐参数注释）：https://github.com/albertito/chasquid/blob/main/etc/chasquid/chasquid.conf
• man 手册在线版：https://blitiri.com.ar/p/chasquid/man/chasquid.conf.5
• 配置 how-to：https://blitiri.com.ar/p/chasquid/howto
• 别名文件格式：https://github.com/albertito/chasquid/blob/main/docs/aliases.md
• DKIM 集成：https://github.com/albertito/chasquid/blob/main/docs/dkim.md
• Dovecot 集成：https://github.com/albertito/chasquid/blob/main/docs/dovecot.md
• HAProxy 集成：https://github.com/albertito/chasquid/blob/main/docs/haproxy.md
• 本站相关篇章：《chasquid 1.19.0 介绍与选型指南》、《Ubuntu 22.04 安装 chasquid 指南》，以及本专栏 《chasquid 1.19.0 常用 CLI 命令详解》（监控端点实操）