chasquid 1.19.0 常用 CLI 命令详解

chasquid 全套命令行工具逐个实测：chasquid-util 9 个子命令（用户/别名/DKIM/配置/域记忆）、smtp-check 外发诊断、mda-lmtp 投递桥、dovecot-auth-cli 认证桥，及 /metrics、/debug/queue 等 7 个监控 HTTP 端点的实操与 Prometheus 对接，含 1.8/1.19 子命令差异与运行时查询语义。

chasquid邮件服务器chasquid2026/10/21

chasquid 1.19.0 常用 CLI 命令详解

目标：一文讲清 chasquid 全套命令行工具与监控 HTTP 端点——chasquid-util 的 9 个子命令逐个实测（用户/别名/DKIM/配置），smtp-check 外发路径诊断、mda-lmtp 投递桥、dovecot-auth-cli 认证桥的用法，以及 /metrics、/debug/queue 等监控端点的实操与 Prometheus 对接。全部命令与回显均在 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（源码编译安装，chasquid-util 位于 /usr/local/bin/；apt 安装为 1.8-1ubuntu0.3，差异见 3.2 节标注）
  • 主机名：mail.chasquid.example；示例邮件域：chasquid.example
  • 实验前置：已建域 chasquid.example，用户 admin@（可收发认证）与 lab@（系统用户，本地收件），别名文件含 support: admin, lab 与 abuse: admin
  • 监控端点已按 《chasquid 1.19.0 配置参数详解》5.3 节开启（monitoring_address: "127.0.0.1:1099"）

二、前置条件与 CLI 工具总览

chasquid 的命令面由 1 个服务主程序 + 4 个工具程序组成：

命令角色典型场景
chasquid守护进程本体（一般由 systemd 拉起）手动前台调试时用
chasquid-util用户/别名/DKIM/配置管理日常管理主力
smtp-check模拟完整外发投递路径的诊断器收不到信、TLS 握手失败时定位
mda-lmtp本地投递转 LMTP 的小代理与 Dovecot LMTP 对接
dovecot-auth-cli对 chasquid 用户库做 exists/auth 的 CLI其他守护进程借用 chasquid 认证

先确认工具在位与版本：

chasquid --version && chasquid-util --help 2>&1 | head -20

实测回显：

chasquid v1.19.0 (source date: 2026-10-17 18:17:53 +0000 UTC)
chasquid-util: chasquid 工具

Usage:
        chasquid-util user-add <user@domain> [--password=...] [--receive_only]
        chasquid-util user-remove <user@domain>
        chasquid-util authenticate <user@domain> [--password=...]
        chasquid-util check-userdb <domain>
        chasquid-util aliases-resolve <address>
        chasquid-util domaininfo-remove <domain>
        chasquid-util print-config
        chasquid-util dkim-keygen <domain> [<selector> <pem>] [--algo=rsa3072|rsa4096|ed25519]
        chasquid-util dkim-dns <domain> [<selector> <pem>]

全局选项：

chasquid-util -h 2>&1 | grep -A3 Options

实测回显：

Options:
  -C=<path>, --config_dir=<path>  Configuration directory
  -v                              Verbose mode

💡 注意：非默认配置目录（自建测试环境等）务必带 --config_dir 指向对应目录，否则 chasquid-util 找不到用户库。

三、chasquid-util 子命令详解

3.1 user-add：建用户

chasquid-util user-add lab@chasquid.example --password=q1w2e3r4

实测回显：

Added user

首次使用（库文件还不存在）时会先打印一行 Creating database 再 Added user。用户库是 per-domain 的：/etc/chasquid/domains/chasquid.example/users，命令会自动创建域目录。

不带 --password 则交互式输密码（终端不回显）。

receive-only 用户（只收不发，不能认证提交）：

chasquid-util user-add archive@chasquid.example --receive_only
chasquid-util authenticate archive@chasquid.example --password=q1w2e3r4
echo rc=$?
chasquid-util user-remove archive@chasquid.example

实测回显：

Added user
Authentication failed
rc=1
Removed user

⚠️ 注意：--receive_only 与 --password 互斥（同时给会报 Cannot specify both --password and --receive_only）；receive-only 用户创建时同样要交互输入口令，但该口令不能用于认证——上例 authenticate 失败即语义验证。

3.2 user-remove：删用户

chasquid-util user-remove archive@chasquid.example

实测回显：

Removed user

删除不存在的用户会报 No such user，退出码 1。

3.3 authenticate：验证口令

运维排障时先验证「用户名+密码」本身对不对，再查 SMTP 层：

chasquid-util authenticate admin@chasquid.example --password=q1w2e3r4; echo rc=$?
chasquid-util authenticate admin@chasquid.example --password=wrongpass; echo rc=$?

实测回显：

Authentication succeeded
rc=0
Authentication failed
rc=1

3.4 check-userdb：用户库自检

chasquid-util check-userdb chasquid.example

实测回显：

Database loaded (2 users)

改动 users 库或迁移目录后先跑一遍，确认库文件可解析、条目数符合预期。

3.5 aliases-resolve：别名解析（运行时查询）

这个子命令不走文件，而是连到运行中的 chasquid（LocalRPC 套接字 /var/lib/chasquid/localrpc-v1）做实时查询——它回答的是「服务此刻会怎么投递」：

chasquid-util aliases-resolve support@chasquid.example
chasquid-util aliases-resolve nosuchuser@chasquid.example; echo rc=$?

实测回显：

(email)  admin@chasquid.example
(email)  lab@chasquid.example
(email)  nosuchuser@chasquid.example
rc=0

解读：support 别名命中别名表，展开为 admin 与 lab 两个邮件收件目标；不存在的用户按「原样返回」处理——chasquid 在 SMTP 层对不存在用户返回 550，这里看到原地址展开只说明别名链无命中，不代表该地址可投递。别名文件改动后需重启服务生效（测试时典型表现：改 aliases 前解析仍是旧结果，重启后更新）。

3.6 domaininfo-remove：清除远端域 TLS 能力记忆

chasquid 会记住每个远端域的历史 TLS 能力（per-domain security level，防降级攻击）。若某远端服务器升级/更换证书导致 chasquid 记忆与现状不符（收不到对某域的信时），可清除该域记忆：

chasquid-util domaininfo-remove nonexistent.example; echo rc=$?

实测回显：

Error removing domaininfo entry: does not exist
rc=1

对存在记忆的域名执行则返回删除成功。日常排障前可先看监控端点的 domaininfo 指标（见第五节）确认是否真的有「降级被拒」记录。

3.7 print-config：打印生效配置

chasquid-util print-config

实测回显（本篇实验环境）：

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"

参数含义见 《chasquid 1.19.0 配置参数详解》。它是「读配置文件 + 目录结构」的核对工具，改配置后、重启前先跑一遍最稳。

3.8 dkim-keygen：生成 DKIM 密钥

chasquid-util dkim-keygen chasquid.example

实测回显（密钥体已节选）：

Key written to "/etc/chasquid/domains/chasquid.example/dkim:20261021.pem"

20261021._domainkey.chasquid.example    TXT     "v=DKIM1; k=rsa; p=MIIBojANBgkqhkiG9w0BAQEFAAOCAY8AMIIBigKCAYEAu1cVzyS7S0cnhPtkwH6FBaGs/UsOqqRVcYSKEZNvWGwTH+D/pI6NL1eNH7412EAqbMtaIqe6ejlS0BmrpmJxZmR+AXDQbgPUw76X9lrYklOKeHSBfzDxxKlAdzXd/gMwmapFbA+vnEQS+i/ilKzBp8kJE+3vtL+CRJxcEbGfUzUbHuarIAKEDWoav3fSshlX7RFhOvXxO7XaYJrrO7a5+CEI8wJclbhNsiVJ83gVlYcTkKWvVb1O53w9sm1FjPOMnw+ZI4dmbsHcFstmqeOHCXdokFfqAmP/GCUkkgOWfDRxSGbrsmglbef/bZbKILM56d+gw9crFHbVtDI7qjFLGCLr93iPDY3yiM6Gq0aEoO4LppXSxDKT+Q+Usx+lQ0HQeNdPr7vO8r40mpZcuo5d6iR/24/0Ya/5NQ3KvlNuoc0b3Tb/ahyW+KvQVCqGgoLKs82SxFygIyqtGEIcje/gBr5vW2FU3A+FJH1HlkslseQ36fyo8K058KGjIjv85AEDAgMBAAE="

解读：

  • 私钥落在域目录，文件名 dkim:<selector>.pem；selector 默认取当天日期（20261021），轮换密钥时指定新日期即可共存过渡；
  • 第二段输出就是要发布到 DNS 的 TXT 记录，主机名 20261021._domainkey.chasquid.example；
  • 重启 chasquid 后密钥即被加载（启动日志出现 DKIM keys 计数），认证用户对本域发出的信自动带 DKIM-Signature 头（实测见 《Ubuntu 22.04 安装 chasquid 指南》7.5 节）。

自定义 selector 与算法：

chasquid-util dkim-keygen chasquid.example mysel /tmp/key.pem --algo=ed25519

⚠️ 注意：密钥文件属主要与运行用户一致（源码安装为 mail:mail），否则重启后加载失败、签名静默跳过。

3.9 dkim-dns：重新输出 DKIM 的 DNS 记录

丢了解析记录或换算法后，用已有密钥重新生成 TXT 值：

chasquid-util dkim-dns chasquid.example

实测回显（与 dkim-keygen 第二段相同，密钥体节选）：

20261021._domainkey.chasquid.example    TXT     "v=DKIM1; k=rsa; p=MIIBojANBgkqhkiG9w0BAQEFAAOCAY8AMIIBigKCAYEAu1cVzyS7S0cnhPtkwH6FBaGs/UsOqqRVcYSKEZNvWGwTH+D/pI6NL1eNH7412EAqbMtaIqe6ejlS0BmrpmJxZmR+AXDQbgPUw76X9lrYklOKeHSBfzDxxKlAdzXd/gMwmapFbA+vnEQS+i/ilKzBp8kJE+3vtL+CRJxcEbGfUzUbHuarIAKEDWoav3fSshlX7RFhOvXxO7XaYJrrO7a5+CEI8wJclbhNsiVJ83gVlYcTkKWvVb1O53w9sm1FjPOMnw+ZI4dmbsHcFstmqeOHCXdokFfqAmP/GCUkkgOWfDRxSGbrsmglbef/bZbKILM56d+gw9crFHbVtDI7qjFLGCLr93iPDY3yiM6Gq0aEoO4LppXSxDKT+Q+Usx+lQ0HQeNdPr7vO8r40mpZcuo5d6iR/24/0Ya/5NQ3KvlNuoc0b3Tb/ahyW+KvQVCqGgoLKs82SxFygIyqtGEIcje/gBr5vW2FU3A+FJH1HlkslseQ36fyo8K058KGjIjv85AEDAgMBAAE="

3.10 版本差异：1.8（Ubuntu 包）的子命令面

Ubuntu 1.8-1ubuntu0.3 的 chasquid-util 是 8 个子命令（无 DKIM 两个子命令），且全局选项拼写不同（-C/--configdir，无下划线）：

chasquid-util --help 2>&1 | tail -12

实测回显（1.8-1ubuntu0.3）：

Usage:
        chasquid-util user-add <user@domain> [--password=...] [--receive_only]
        chasquid-util user-remove <user@domain>
        chasquid-util authenticate <user@domain> [--password=...]
        chasquid-util check-userdb <domain>
        chasquid-util aliases-resolve <address>
        chasquid-util domaininfo-remove <domain>
        chasquid-util print-config
        chasquid-util aliases-add <source> <target>

Options:
  -C=<path>, --configdir=<path>  Configuration directory
  -v                              Verbose mode

1.8 多一个 aliases-add 子命令（直接写别名），1.19 起改为手编 aliases 文件 + aliases-resolve 运行时验证的组合；DKIM 子命令（dkim-keygen/dkim-dns）为 1.14+ 新增，1.8 没有。

四、辅助工具

4.1 smtp-check：外发投递路径诊断器

它把「查 MTA-STS 策略 → MX 解析 → TLS 握手 → SMTP 会话」整条外发链路走一遍，是「某域名发不出去」时的第一诊断器：

smtp-check --help 2>&1 | head -20

实测回显：

Usage of /usr/local/bin/smtp-check:
  -alsologtostderr
        also log to stderr, in addition to the file
  -localname string
        specify the local name for the EHLO command (default "localhost")
  -logfile string
        file to log to (enables logtime)
  -logtime
        include the time when writing the log to stderr
  -logtosyslog string
        log to syslog, with the given tag
  -port string
        port to use for connecting to the MX servers (default "smtp")
  -skip_tls_check
        skip TLS check (useful if connections are blocked)
  -v int
        verbosity level (1 = debug)

基本用法：smtp-check someone@remote.example（对远端域做全链路检查），-localname 可指定 EHLO 名，-v 1 看调试细节。

⚠️ 注意：smtp-check 面向远端域诊断——对本地域执行会卡在 MX 解析阶段失败（实验环境中对本地域 chasquid.example 执行返回 MX 查询错误退出）。它不能替代本地投递测试，本地收信用第五节的监控端点或真实发信验证。

4.2 mda-lmtp：本地投递转 LMTP

chasquid.conf 的 mail_delivery_agent_bin 指向它时，本地投递从「写 mbox/Maildir 的 MDA」切换为「LMTP 转交」——最终投递交给 Dovecot 等专业收件引擎：

mda-lmtp --help 2>&1 | head -8

实测回显：

mda-lmtp: chasquid LMTP mail delivery agent.

Usage:
        mda-lmtp [options] --address=127.0.0.1:24 ...

配套的 chasquid.conf 写法（逐参数含义见 《chasquid 1.19.0 配置参数详解》5.4 节）：

mail_delivery_agent_bin: "mda-lmtp"
mail_delivery_agent_args: "-address=127.0.0.1:24"
mail_delivery_agent_args: "-f"
mail_delivery_agent_args: "%from%"
mail_delivery_agent_args: "-d"
mail_delivery_agent_args: "%to_user%"

4.3 dovecot-auth-cli：认证桥 CLI

给「想借用 chasquid 用户库做认证」的其他守护进程用（如让某个 IMAP/应用网关直接问 chasquid 要认证结果）：

dovecot-auth-cli 2>&1

实测回显（build 目录执行）：

Usage:
        dovecot-auth-cli <path prefix> exists user@domain
        dovecot-auth-cli <path prefix> auth user@domain password

它按 Dovecot checkpassword/auth 协议对外暴露 chasquid 的用户库，<path prefix> 指向 chasquid 数据目录前缀。与 chasquid.conf 里 dovecot_auth: true（chasquid 反向借用 Dovecot 账号）方向相反，别混淆。

五、监控 HTTP 端点实操

chasquid 内置一个监控 HTTP 服务，由 monitoring_address 参数开启（默认关闭；开启方法见 《chasquid 1.19.0 配置参数详解》5.3 节）。以下全部为 http://127.0.0.1:1099 上的实测。

5.1 端点总览

请求根路径拿目录：

curl -s http://127.0.0.1:1099/ | grep -oE 'href="/[a-z/_]+"[^>]*>[a-z/._-]+' | head -10

实测回显：

href="/debug/queue">/debug/queue
href="/debug/traces">/debug/traces
href="/debug/vars">/debug/vars
href="/metrics">/metrics
href="/debug/flags">/debug/flags
href="/debug/config">/debug/config
href="/debug/pprof">/debug/pprof

各端点用途速查：

端点用途对接方式
/metricsOpenMetrics/Prometheus 指标Prometheus 抓取
/debug/varsexpvar 格式（同一批指标）排障人工查看
/debug/queue队列即时状态（信封级）排障人工查看
/debug/traces请求级追踪排障人工查看
/debug/flags启动命令行参数排障人工查看
/debug/config生效配置 JSON排障人工查看
/debug/pprofGo 性能剖析pprof 工具

⚠️ 注意：官方文档明确警告端点含敏感信息，绝不可暴露公网；monitoring_address 只绑回环或管理网段。Ubuntu 1.8 包的端点集合略有不同（为 /debug/requests、/debug/events、/debug/vars 等），1.19 起调整为 /debug/traces 与 /debug/queue、/debug/config。

5.2 /debug/queue：队列即时状态

curl -s http://127.0.0.1:1099/debug/queue

实测回显（空队列）：

date: 2026-10-21 02:26:42
length: 0

有未完成投递时，每封信的信封（发件人、收件人、重试计划、上次错误）都会列出——「信发不出去」时先看这里：队列在涨说明收信正常、投递受阻；队列空说明外发根本没进队列（多半是 RCPT 阶段被拒）。

5.3 /metrics：Prometheus 指标

指标以 chasquid_ 为前缀，实测共 41 条（1.19.0）。看几条有代表性的：

curl -s http://127.0.0.1:1099/metrics | grep '^chasquid' | head -8

实测回显（节选）：

chasquid_aliases_hookResults{result="resolve:skip"} 5
chasquid_courier_deliverCount{result="local:ok"} 3
chasquid_courier_deliverInProgress 0
chasquid_queue_deliverAttempts{recipient_type="email:local"} 1
chasquid_queue_getCount 1
chasquid_queue_putCount{from="email:local"} 1
chasquid_smtpIn_answerCount{answer="220"} 2
chasquid_smtpIn_commandCount{command="EHLO"} 2

指标分组解读：

指标前缀覆盖内容
chasquid_queue_*队列进出（putCount/getCount）、投递尝试、失败
chasquid_courier_*本地投递结果（ok/error）、进行中数量
chasquid_smtpIn_*入站 SMTP 命令/应答计数（按命令与码分桶）
chasquid_smtpOut_*出站连接/投递结果计数
chasquid_aliases_*别名解析结果分桶
chasquid_domaininfo_* / chasquid_sts_*域 TLS 记忆与 MTA-STS 缓存命中
chasquid_dkim_*DKIM 签名/验证结果

Prometheus 对接（抓取端配置示意）：

scrape_configs:
  - job_name: chasquid
    static_configs:
      - targets: ["mail.example.com:1099"]

告警思路：chasquid_queue_length 持续高位 → 投递受阻；chasquid_courier_deliverCount{result=~".*error.*"} 速率上升 → 本地投递故障；chasquid_smtpOut_* 失败分桶 → 外发链路问题。

5.4 /debug/vars、/debug/config 与 /debug/flags

curl -s http://127.0.0.1:1099/debug/vars | head -c 200; echo
curl -s http://127.0.0.1:1099/debug/config | head -c 200; echo

实测回显（各 200 字符节选）：

{
 "cmdline": ["/usr/local/bin/chasquid"],
 "chasquid/courier/deliverCount/local:ok": 3,
{
 "configdir": "/etc/chasquid",
 "queue": {

/debug/vars 与 /metrics 内容同源（expvar 与 OpenMetrics 双格式）；/debug/config 是JSON 版生效配置，核对配置时比日志转储更精确。

六、服务管理速查（systemd/journalctl）

日常运维中最常用的几条（与命令行工具配合）：

systemctl status chasquid.service --no-pager | head -5
systemctl restart chasquid.service
journalctl -u chasquid.service --no-pager -n 20
journalctl -u chasquid.service --no-pager -b | grep -E 'ERROR|☠'

实测回显（status 节选）：

● chasquid.service - chasquid mail daemon (service)
     Loaded: loaded (/etc/systemd/system/chasquid.service; enabled; vendor preset: enabled)
     Active: active (running)

投递类日志（含失败原因）走 mail_log_path（默认 <syslog>），所以 journalctl -u chasquid 同时能看到协议日志与投递日志；另外邮件投递日志带 Queue. / Courier. / MDA 等组件前缀，排障时可按前缀过滤。

七、常见问题（FAQ）

Q1：chasquid-util 子命令报 connection refused？ aliases-resolve、domaininfo-remove 需要连运行中的服务（LocalRPC 套接字在 data_dir 下）。服务未运行或套接字权限不对（运行用户不符）时失败；先确认 systemctl is-active chasquid.service 与 data_dir 属主。

Q2：user-add 报 Creating database 失败？ 域目录或配置目录不可写。源码安装运行用户为 mail，/etc/chasquid/domains 需要写权限（命令行下用 sudo 执行，然后 chown -R mail:mail 收尾）。

Q3：DKIM 签了但外域报验签失败？ 三步排查：DNS TXT 是否发布成功（dig TXT <selector>._domainkey.<域>）；selector 与私钥文件名是否一致；公网出口是否把信体改写（尾部加行等破坏 canonical 化）。监控端点 chasquid_dkim_* 指标可看签名侧错误。

Q4：哪里看当前生效的完整配置？ 三条路：chasquid-util print-config（CLI）、/debug/config（JSON）、启动日志转储（journalctl grep Configuration）。内容一致，选顺手的。

Q5：Ubuntu 1.8 包用户怎么用本篇？ 子命令面差异见 3.10 节：1.8 无 dkim-keygen/dkim-dns（DKIM 功能 1.14 才有），多一个 aliases-add；全局选项是 --configdir（无下划线）。监控端点集合略有不同（无 /debug/queue 与 /debug/traces，对应为 /debug/requests、/debug/events）。

八、参考链接

  • chasquid-util 手册：https://blitiri.com.ar/p/chasquid/man/chasquid-util.1
  • smtp-check 手册：https://blitiri.com.ar/p/chasquid/man/smtp-check.1
  • mda-lmtp 手册：https://blitiri.com.ar/p/chasquid/man/mda-lmtp.1
  • 监控与指标官方文档：https://github.com/albertito/chasquid/blob/main/docs/monitoring.md
  • DKIM 官方文档：https://github.com/albertito/chasquid/blob/main/docs/dkim.md
  • 别名文件官方文档：https://github.com/albertito/chasquid/blob/main/docs/aliases.md
  • Dovecot 集成官方文档：https://github.com/albertito/chasquid/blob/main/docs/dovecot.md
  • 本站相关篇章：《chasquid 1.19.0 介绍与选型指南》、《Ubuntu 22.04 安装 chasquid 指南》、《chasquid 1.19.0 配置参数详解》