Apache SpamAssassin 配置参数详解

详解 Apache SpamAssassin 3.4.6 站点主配置文件 local.cf 的核心参数:判定阈值、垃圾邮件改写标记、信任网段、报告附件形态、贝叶斯自适应学习与协同过滤开关,默认值均取自本机 perldoc 手册并逐项实测生效,附生产配置模板与 lint 语法校验排障。

Apache SpamAssassinApache SpamAssassin2026/10/12

Apache SpamAssassin 配置参数详解

目标:详解 Apache SpamAssassin 3.4.6 站点主配置文件 /etc/mail/spamassassin/local.cf 的核心参数——判定阈值、垃圾邮件改写、信任网段、报告形态、Bayes 自适应学习与协同过滤开关,全部默认值取自本机离线手册 perldoc Mail::SpamAssassin::Conf,每个参数的生效效果均在 Ubuntu 22.04.5 真实环境实测验证。

一、环境信息

  • 操作系统:Ubuntu 22.04.5 LTS(x86_64)
  • 主机名:mail01.example.com
  • Apache SpamAssassin:3.4.6-1ubuntu0.22.04.1(Ubuntu 官方软件源安装)
  • Perl:5.34.0
  • 站点配置目录:/etc/mail/spamassassin/
  • 主配置文件:/etc/mail/spamassassin/local.cf
  • 参数离线手册:perldoc Mail::SpamAssassin::Conf
  • 规则状态目录:/var/lib/spamassassin/3.004006/
  • 守护进程:spamd(systemd 服务名 spamassassin,默认监听 127.0.0.1:783)

二、前置条件

  • 已按《Apache SpamAssassin 安装指南》完成 SpamAssassin 3.4.6 安装,spamassassin --version 输出正常。
  • 已安装 perl-doc 软件包用于离线查阅参数手册(安装命令与回显见 3.1 节)。
  • 每次修改配置后的生效三步:spamassassin --lint 校验语法 → systemctl restart spamassassin 重启守护进程 → 用 spamc 实测判定确认行为。

三、参数查看与修改方式

3.1 离线参数手册 perldoc

SpamAssassin 全部配置指令的权威说明在本机手册 Mail::SpamAssassin::Conf 中。最小化安装的 Ubuntu 22.04 需先补装 perl 文档包:

apt-get install -y perl-doc

未安装时直接查阅会得到提示:

# perldoc -T Mail::SpamAssassin::Conf 2>&1 | head -6
You need to install the perl-doc package to use this program.

安装后即可离线查阅全部参数(手册开头):

# perldoc -T Mail::SpamAssassin::Conf 2>/dev/null | head -6
NAME
    Mail::SpamAssassin::Conf - SpamAssassin configuration file

SYNOPSIS
      # a comment

3.2 站点配置文件与插件加载清单

ls /etc/mail/spamassassin/

真实回显:

65_debian.cf
init.pre
local.cf
local.cf.orig
sa-compile.pre
sa-update-hooks.d
sa-update-keys
v310.pre
v312.pre
v320.pre
v330.pre
v340.pre
v341.pre
v342.pre
v343.pre
  • local.cf:站点主配置文件,管理员编辑入口;local.cf.orig 是带注释的原始模板(摘录):
# This is the right place to customize your installation of SpamAssassin.
#
# See 'perldoc Mail::SpamAssassin::Conf' for details of what can be
# tweaked.
#
# Only a small subset of options are listed below
#
###########################################################################

#    A 'contact address' users should contact for more info. (replaces
#    _CONTACTADDRESS_ in the report template)
# report_contact youremailaddress@domain.tld


#   Add *****SPAM***** to the Subject header of spam e-mails
#
# rewrite_header Subject *****SPAM*****


#   Save spam messages as a message/rfc822 MIME attachment instead of
#   modifying the original message (0: off, 2: use text/plain instead)
#
# report_safe 1


#   Set which networks or hosts are considered 'trusted' by your mail
#   server (i.e. not spammers)
#
# trusted_networks 212.17.35.
  • init.pre、v310.pre ~ v343.pre:插件加载清单。指令只对已 loadplugin 的插件有效,各 pre 文件中的加载行(grep 实测):
/etc/mail/spamassassin/init.pre:loadplugin Mail::SpamAssassin::Plugin::URIDNSBL
/etc/mail/spamassassin/init.pre:loadplugin Mail::SpamAssassin::Plugin::SPF
/etc/mail/spamassassin/v310.pre:loadplugin Mail::SpamAssassin::Plugin::Pyzor
/etc/mail/spamassassin/v310.pre:loadplugin Mail::SpamAssassin::Plugin::Razor2
/etc/mail/spamassassin/v310.pre:loadplugin Mail::SpamAssassin::Plugin::SpamCop
/etc/mail/spamassassin/v310.pre:loadplugin Mail::SpamAssassin::Plugin::AutoLearnThreshold
/etc/mail/spamassassin/v310.pre:loadplugin Mail::SpamAssassin::Plugin::WhiteListSubject
/etc/mail/spamassassin/v310.pre:loadplugin Mail::SpamAssassin::Plugin::MIMEHeader
/etc/mail/spamassassin/v310.pre:loadplugin Mail::SpamAssassin::Plugin::ReplaceTags

3.3 用 --lint 校验语法、用 -D config 观察加载顺序

任何 .cf 修改后先校验语法,退出码 0 且无输出即通过:

spamassassin --lint

排查配置不生效问题时,用 -D config 打印配置加载顺序(摘录):

spamassassin --lint -D config 2>&1 | grep -E "config: read file|config: using"

真实回显:

dbg: config: using "/etc/mail/spamassassin" for site rules pre files
dbg: config: read file /etc/mail/spamassassin/init.pre
dbg: config: read file /etc/mail/spamassassin/sa-compile.pre
dbg: config: read file /etc/mail/spamassassin/v310.pre
dbg: config: read file /etc/mail/spamassassin/v312.pre
dbg: config: read file /etc/mail/spamassassin/v320.pre
dbg: config: read file /etc/mail/spamassassin/v330.pre
dbg: config: read file /etc/mail/spamassassin/v340.pre
dbg: config: read file /etc/mail/spamassassin/v341.pre
dbg: config: read file /etc/mail/spamassassin/v342.pre
dbg: config: read file /etc/mail/spamassassin/v343.pre
dbg: config: using "/var/lib/spamassassin/3.004006" for sys rules pre files
dbg: config: using "/var/lib/spamassassin/3.004006" for default rules dir
dbg: config: read file /var/lib/spamassassin/3.004006/updates_spamassassin_org.cf
dbg: config: using "/etc/mail/spamassassin" for site rules dir
dbg: config: read file /etc/mail/spamassassin/65_debian.cf
dbg: config: read file /etc/mail/spamassassin/local.cf
dbg: config: using "/root/.spamassassin/user_prefs" for user prefs file
dbg: config: read file /root/.spamassassin/user_prefs
dbg: config: using "/var/lib/spamassassin/3.004006/updates_spamassassin_org/10_default_prefs.cf" for included file

💡 加载顺序:插件 pre 清单 → sa-update 规则 → 站点目录 65_debian.cf、local.cf → 用户偏好 user_prefs。后加载的同名指令覆盖先加载的值。

3.4 用 --cf 做命令行内联覆盖(临时验证)

不改动配置文件,直接在命令行追加配置行验证行为(实测):

spamassassin --cf="required_score 2000" -t gtube.eml | grep X-Spam-Status
spamassassin --cf="rewrite_header Subject [CUSTOM-MARK]" -t gtube.eml | grep "^Subject"

真实回显:

X-Spam-Status: No, score=1000.8 required=2000.0 tests=BAYES_50,GTUBE,
Subject: [CUSTOM-MARK] Test spam mail (GTUBE)

3.5 修改后的生效流程

vi /etc/mail/spamassassin/local.cf
spamassassin --lint && systemctl restart spamassassin
systemctl is-active spamassassin

真实回显:

active

四、参数总览

以下默认值均摘自本机 perldoc Mail::SpamAssassin::Conf 手册原文:

参数默认值说明
required_score5判定为垃圾邮件所需的分数阈值
rewrite_header不改写命中垃圾邮件时在 Subject/From/To 上追加标记
report_safe1垃圾邮件报告与原邮件的组装方式(0/1/2)
report_wrap_width70X-Spam-Report 头描述行的折行宽度
trusted_networksnone信任网段(不会对其做 DNSBL 查询)
internal_networksnone内部网段(本域 MX 与内部中继)
msa_networksnoneMSA(邮件提交代理)网段
use_bayes1启用贝叶斯分类器
use_bayes_rules1启用 BAYES_* 评分规则
bayes_auto_learn1自动学习(垃圾/正常各达到阈值才生效)
bayes_auto_learn_threshold_spam12.0自动学习垃圾邮件的分数下限
bayes_auto_learn_threshold_nonspam0.1自动学习正常邮件的分数上限
bayes_min_ham_num200贝叶斯参与评分所需最少正常样本数
bayes_min_spam_num200贝叶斯参与评分所需最少垃圾样本数
bayes_path~/.spamassassin/bayes贝叶斯数据库文件路径前缀
bayes_journal_max_size102400journal 文件大小上限(字节)
bayes_expiry_max_db_size150000贝叶斯词库条目数上限(过期清理触发)
bayes_auto_expire1自动过期清理旧词频
bayes_use_hapaxes1统计仅出现一次的低频词
ok_localesall视为正常的字符集/语言区域
use_razor21启用 Razor2 协同过滤
use_pyzor1启用 Pyzor 协同过滤
dns_availableyesDNS 可用性判定(在线检测依赖)

五、local.cf 核心参数分类详解

5.1 判定阈值:required_score

手册原文(本机 perldoc -T Mail::SpamAssassin::Conf 摘录):

required_score n.nn (default: 5)
    Set the score required before a mail is considered spam. "n.nn" can
    be an integer or a real number. 5.0 is the default setting, and is
    quite aggressive; it would be suitable for a single-user setup, but
    if you're an ISP installing SpamAssassin, you should probably set
    the default to be more conservative, like 8.0 or 10.0. It is not
    recommended to automatically delete or discard messages marked as
    spam, as your users will complain, but if you choose to do so, only
    delete messages with an exceptionally high score such as 15.0 or
    higher. This option was previously known as "required_hits" and that
    name is still accepted, but is deprecated.

站点配置与实测生效:

required_score 5.0

GTUBE 测试邮件实测(阈值改写为 2000 时邮件不再判为垃圾,见 3.4 节回显 required=2000.0);默认 5.0 时 spamc -c 输出 1000.0/5.0,分子为得分、分母即 required_score。

⚠️ 手册明确:多用户/ISP 场景建议收紧到 8.0 或 10.0;不建议自动删除垃圾邮件,确要删除只处理 15.0 以上的极高分类。旧名 required_hits 仍被接受但已废弃。

5.2 垃圾邮件改写标记:rewrite_header

手册要点(本机手册摘录):默认不改写 Subject/From/To;设置后 Subject 在原主题前追加标记串,From/To 以括号注释形式追加(括号会被转成方括号);STRING 置空可移除已有改写;邮件本无 Subject 头时会自动创建。

站点配置与实测生效:

rewrite_header Subject *****SPAM*****

GTUBE 邮件实测:

spamc < /var/mailtest/gtube.eml | grep -E "^Subject|X-Spam-Status"

真实回显:

Subject: *****SPAM***** Test spam mail (GTUBE)
X-Spam-Status: Yes, score=1000.0 required=5.0 tests=GTUBE,NO_RECEIVED,

内联覆盖为自定义标记同样即时生效(见 3.4 节回显 Subject: [CUSTOM-MARK] Test spam mail (GTUBE))。正常邮件主题保持原样:

Subject: Weekly project meeting minutes

⚠️ 手册提示:仅在 report_safe 0 时才建议在 Subject 中使用 _REQD_/_SCORE_ 模板标签,否则可能无法按常规方法去除标记。

5.3 信任网段:trusted_networks / internal_networks / msa_networks

手册要点(本机手册摘录):信任网段内的中继主机被视为非垃圾邮件源头、非开放代理,DNS 黑名单(DNSBL)检查不会查询这些网络;本域 MX 与内部中继应写入 internal_networks;写法支持 CIDR 掩码(/24 等)、带尾点的隐式掩码(212.17.35. 等价 /24)、! 前缀排除子网。

站点配置与实测生效:

trusted_networks 192.168.1.0/24

spamassassin --lint 校验通过(退出码 0,无输出)。

⚠️ 回环网段 127.0.0.1/8 默认已包含在信任网络内,重复声明会触发告警(真实踩坑回显见第七章 Q2)。

5.4 报告与附件形态:report_safe / report_wrap_width

手册原文(本机手册摘录,值域 0/1/2):

report_safe ( 0 | 1 | 2 ) (default: 1)
    if this option is set to 1, if an incoming message is tagged as
    spam, instead of modifying the original message, SpamAssassin will
    create a new report message and attach the original message as a
    message/rfc822 MIME part (ensuring the original message is
    completely preserved, not easily opened, and easier to recover).

    If this option is set to 2, then original messages will be attached
    with a content type of text/plain instead of message/rfc822. ...

    If this option is set to 0, incoming spam is only modified by adding
    some "X-Spam-" headers and no changes will be made to the body. In
    addition, a header named X-Spam-Report will be added to spam. ...
取值行为适用场景
0仅追加 X-Spam-* 头与 X-Spam-Report 头,正文不动邮件客户端自带过滤规则、用户自行处理
1(默认)生成报告邮件,原邮件作为 message/rfc822 MIME 附件通用生产取值,原邮件完整保留便于取回
2原邮件以 text/plain 附件附带邮件客户端会自动加载附件的问题环境

report_wrap_width 默认 70,控制 X-Spam-Report 头描述行的折行宽度。

站点配置与实测生效:

report_safe 1

GTUBE 邮件经 spamassassin -t 改写后,输出头部出现 MIME 封装(即原邮件作为附件组装):

Content-Type: multipart/mixed; boundary="----------=_6ACC2D5B.B5448E95"

5.5 贝叶斯自适应学习:use_bayes 参数组

参数默认值实测取值说明
use_bayes11启用贝叶斯分类器
use_bayes_rules11启用 BAYES_* 评分规则
bayes_auto_learn11评分后自动把邮件入库学习
bayes_auto_learn_threshold_spam12.012.0得分不低于该值才作为垃圾样本自动学习
bayes_auto_learn_threshold_nonspam0.10.1得分不高于该值才作为正常样本自动学习
bayes_min_ham_num200200参与评分所需最少正常样本
bayes_min_spam_num200200参与评分所需最少垃圾样本
bayes_path~/.spamassassin/bayes/var/lib/spamassassin/bayes数据库文件路径前缀
bayes_journal_max_size102400102400journal 上限(字节)
bayes_expiry_max_db_size150000150000词库条目上限,触发过期清理
bayes_auto_expire11自动过期旧词频
bayes_use_hapaxes11统计低频词

站点配置与实测生效:

use_bayes 1
bayes_auto_learn 1
bayes_min_ham_num 200
bayes_min_spam_num 200

样本量未达 200+200 时,判定结果中 autolearn=no、autolearn=unavailable,且看不到 BAYES 系列规则。用 sa-learn 训练语料超过阈值并重启 spamd 后,BAYES 规则开始参与评分(实测,语料训练方法见《Apache SpamAssassin 常用 CLI 命令与工具详解》第七章):

systemctl restart spamassassin
spamc -t < /var/mailtest/bayes-test.eml | grep -E "BAYES|X-Spam-Status"

真实回显:

X-Spam-Status: Yes, score=6.6 required=5.0 tests=BAYES_99,BAYES_999,
spamassassin -t /var/mailtest/bayes-test.eml | grep -E "pts rule|BAYES_9"

真实回显:

 0.2 BAYES_999              BODY: Bayes spam probability is 99.9 to 100%
 3.5 BAYES_99               BODY: Bayes spam probability is 99 to 100%

⚠️ bayes_path 默认随运行用户 HOME 变化:spamd 由 systemd 以 root 启动时数据库落在 /root/.spamassassin/bayes*。需要集中存储时显式指定(如 bayes_path /var/lib/spamassassin/bayes),并保证目录属主与 spamd 运行用户一致。

5.6 语言与字符集:ok_locales

手册原文(本机手册摘录):

ok_locales xx [ yy zz ... ] (default: all)
    This option is used to specify which locales are considered OK for
    incoming mail. Mail using the character sets that are allowed by
    this option will not be marked as possibly being spam in a foreign
    language.

    If you receive lots of spam in foreign languages, and never get any
    non-spam in these languages, this may help. Note that all ISO-8859-*
    character sets, and Windows code page character sets, are always
    permitted by default.

    Set this to "all" to allow all character sets. This is the default.

    The rules "CHARSET_FARAWAY", "CHARSET_FARAWAY_BODY", and
    "CHARSET_FARAWAY_HEADERS" are triggered based on how this is set.

默认 all 不做语言过滤。只收特定语言邮件的站点可按 ok_locales xx [ yy zz ... ] 语法列出区域代码以收紧 CHARSET_FARAWAY 系列规则;所有 ISO-8859-* 与 Windows 代码页字符集始终放行。

5.7 协同过滤与在线检测:use_razor2 / use_pyzor / dns_available

  • use_razor2(默认 1)、use_pyzor(默认 1):Razor2/Pyzor 协同过滤数据库查询开关,对应插件已在 v310.pre 中 loadplugin(见 3.2 节)。未部署这两个组件的环境直接关闭,避免每次判定都产生无效网络查询:
use_razor2 0
use_pyzor 0
  • dns_available { yes | no | test[: domain1 domain2...] }(默认 yes):在线检测(DNSBL、SPF、URIDNSBL)依赖 DNS;test 模式按给定域名探测 DNS 可用性后再启用在线检测。

⚠️ 指令只对已加载的插件有效:DCC 插件默认未在任何 .pre 中 loadplugin,在 local.cf 写 use_dcc 0 会导致 lint 解析失败(真实踩坑回显见第七章 Q1)。

六、生产配置模板

适用场景:8GB 内存、SAS 磁盘、日均数万封的邮件网关前置过滤;内网 192.168.1.0/24 为可信 MSA 来源;启用 Bayes 自适应学习;未部署 Razor2/Pyzor/DCC;可解析公网 DNS。

# ===== 判定与改写 =====
required_score 5.0
rewrite_header Subject *****SPAM*****
report_safe 1

# ===== 信任网段 =====
trusted_networks 192.168.1.0/24

# ===== 贝叶斯自适应学习 =====
use_bayes 1
use_bayes_rules 1
bayes_auto_learn 1
bayes_auto_learn_threshold_spam 12.0
bayes_auto_learn_threshold_nonspam 0.1
bayes_min_ham_num 200
bayes_min_spam_num 200
bayes_path /var/lib/spamassassin/bayes
bayes_journal_max_size 102400
bayes_expiry_max_db_size 150000
bayes_auto_expire 1

# ===== 协同过滤(未部署即关闭)=====
use_razor2 0
use_pyzor 0

写入并生效(三步流程实测):

spamassassin --lint
systemctl restart spamassassin && systemctl is-active spamassassin
spamc -c < /var/mailtest/gtube.eml

真实回显:

active
1000.0/5.0
Subject: *****SPAM***** Test spam mail (GTUBE)

💡 内存说明:spamd 单进程常驻约 100MB(systemctl status 实测 Memory 97-100MB),--max-children 5 时峰值按子进程数线性增长;8GB 内存的网关足够,更大流量优先调大 --max-children 而非阈值参数。

七、常见问题

Q1:spamassassin --lint 报 config: failed to parse line ... use_dcc 0 怎么办? use_dcc 对应的 DCC 插件默认未在 .pre 文件中 loadplugin,未加载插件时写该指令会解析失败。真实回显:

Oct 12 00:47:25.798 [5573] warn: config: failed to parse line, skipping, in "/etc/spamassassin/local.cf": use_dcc 0
Oct 12 00:47:26.422 [5573] warn: lint: 1 issues detected, please rerun with debug enabled for more information

处理:删除 use_dcc 0 行(DCC 未部署时无需配置),重新 spamassassin --lint 直至退出码 0、无输出。

Q2:--lint 报 netset: cannot include 127.0.0.1/8 as it has already been included 怎么办? 回环网段默认已包含在信任网络内,在 trusted_networks/internal_networks 中重复声明 127.0.0.1/8 会触发告警。真实回显:

Oct 12 00:47:25.798 [5573] warn: netset: cannot include 127.0.0.1/8 as it has already been included

处理:从信任网段配置中去掉 127.0.0.1/8,只保留业务内网段(如 trusted_networks 192.168.1.0/24)。

Q3:lint 提示 lint: 1 issues detected 但看不出哪行错? 按提示打开调试重跑,定位具体配置区域:

spamassassin --lint -D config 2>&1 | less

结合回显中的文件名与行内容逐条修正;修正后 spamassassin --lint 无输出即干净。

Q4:改了 local.cf 但判定行为没变? 三个常见原因:未重启 spamd(local.cf 在进程启动时读取,改完必须 systemctl restart spamassassin);改错文件(确认 -D config 回显中实际读取的是 /etc/mail/spamassassin/local.cf,用户级 ~/.spamassassin/user_prefs 后加载、会覆盖站点值);被命令行 --cf 或 spamd 启动参数覆盖。核对顺序见 3.3 节。

Q5:perldoc -T Mail::SpamAssassin::Conf 提示 You need to install the perl-doc package? 最小化安装的 Ubuntu 22.04 未带 perl 文档包,apt-get install -y perl-doc 后即可离线查阅全部参数手册(见 3.1 节回显)。

八、参考链接