phpList 3.6.17 配置参数详解

目标：系统梳理 phpList 3.6.17 的三层配置体系（代码层 config.php、数据库层 phplist_config 表、后台设置界面），给出参数总览与核心参数分类详解（数据库、邮件发送、队列批量、退信处理、安全、前台界面、附件扩展七大类），并提供可直接落地的生产配置模板与 DB 层默认值修复实录。

一、环境信息

phpList 版本：3.6.17（官方最新稳定版，2026-10-26 实查 GitHub Releases）
配置文件规模实测：源码包内置最小配置 config/config.php 约 110 行；完整参考配置 config/config_extended.php 共 926 行，含 111 条配置语句（wc -l 与 grep -cE 实测），覆盖本文全部参数
实测环境：Ubuntu 22.04 + PHP 8.1 + MariaDB 10.6，安装方式见《Ubuntu 22.04 安装 phpList 3.6.17 指南》
演示账号：管理员 admin / q1w2e3r4

二、参数体系与查看方式

2.1 三层配置体系

phpList 3.6.17 的配置分布在三层，优先级与职责各不相同：

层	载体	职责	修改方式
代码层	`lists/config/config.php`	连接信息、发送引擎、队列、退信、安全等运行参数（PHP 常量与变量）	直接编辑文件
数据库层	`phplist_config` 表（实测 41 项）	初始化时写入的默认发件人、站点地址、订阅页 URL、页脚模板、密钥等业务默认值	后台设置页或 SQL
界面层	后台 Settings / config 页面	数据库层参数的图形化入口，改动的仍是 `phplist_config`	浏览器操作

注意：代码层与数据库层同名参数各自独立（例如 message_from_address 在代码层是 $message_from_address 变量，在数据库层是 phplist_config 表条目），命令行发送的 From 头取自数据库层，而退信信封（Sender）回退链才走代码层 $message_envelope——两层职责混淆是发送故障的常见根因（实录见 6.2 节）。

2.2 config.php 与 config_extended.php

源码包中 config/config.php 是必须存在的最小配置；config/config_extended.php 是完整参考手册（官方注释明确说明：要用其中选项，需把对应段落复制进 config.php）。官方推荐做法：保持 config.php 存量内容不动，把需要的参数段落从 config_extended.php 复制进去。

2.3 查看数据库层配置

数据库层参数直接查 phplist_config 表（实测回显，节选）：

mysql phplistdb -e "select item,value from phplist_config order by item"

item	value
admin_address	webmaster@[DOMAIN]
campaignfrom_default	 
confirmationurl	http://127.0.0.1:8130/lists/?p=confirm
domain	127.0.0.1:8130
message_from_address	noreply@[DOMAIN]
message_from_name	Webmaster
message_replyto_address	noreply@[DOMAIN]
subscribeurl	http://127.0.0.1:8130/lists/?p=subscribe
unsubscribeurl	http://127.0.0.1:8130/lists/?p=unsubscribe
version	3.6.17
website	127.0.0.1:8130
...（共 41 项，此处节选）

其中 [DOMAIN] 占位符与 domain/website 值由初始化时访问的主机名生成；secret、hmackey、xormask 为初始化时自动生成的随机密钥，不可随意改动。

三、参数总览

下表按类别汇总核心参数（默认值取自 config_extended.php 原文，查询自 3.6.17 源码）：

类别	代表参数	默认值	作用
数据库连接	`$database_host` / `$database_name` / `$database_user` / `$database_password`	`localhost` / `phplistdb` / `phplist` / `phplist`	数据库连接四要素
数据库连接	`$database_port` / `$database_socket`	注释状态	非标准端口/socket 连接
表与路径	`$table_prefix` / `$usertable_prefix` / `$pageroot`	`phplist_` / `user_` / `/lists`	表前缀与应用 URL 路径
邮件发送	`PHPMAILERHOST`	`''`（走 PHP mail()）	SMTP 主机，支持 `host:port;host2:port2` 多服务器
邮件发送	`PHPMAILERPORT` / `PHPMAILER_SECURE`	25 / 注释状态	SMTP 端口与 ssl/tls 加密
邮件发送	`$phpmailer_smtpuser` / `$phpmailer_smtppassword`	注释状态	SMTP 认证凭证
邮件发送	`$message_envelope`	注释状态	退信信封地址（Sender 来源）
发送模式	`TEST`	1	1=模拟发送不投递，0=真实发送
队列批量	`MANUALLY_PROCESS_QUEUE`	1	1=后台手动跑队列，0=cron 自动
队列批量	`MAILQUEUE_BATCH_SIZE` / `MAILQUEUE_BATCH_PERIOD`	0 / 3600	每周期发送量（0=不限速）
队列批量	`MAILQUEUE_THROTTLE` / `MAILQUEUE_AUTOTHROTTLE`	0 / 0	消息间隔秒数 / 自动节流
队列批量	`MAX_PROCESSQUEUE_TIME` / `MAX_PROCESS_MESSAGE`	0 / 999	单次队列运行时限 / 单次处理活动数
退信处理	`$bounce_protocol`	`pop`	退信回收协议（pop 或 mbox）
退信处理	`MANUALLY_PROCESS_BOUNCES`	1	1=后台手动处理退信
退信处理	`$bounce_mailbox_host` / `$bounce_mailbox_port`	`localhost` / `110/pop3/notls`	POP3 服务器与端口
退信处理	`$bounce_unsubscribe_threshold`	5	连续退信次数阈值，达到即停发
安全	`$commandline_users`	`array()`	命令行白名单（空数组=不限制）
安全	`HASH_ALGO`	`sha256`	订阅者密码哈希算法
安全	`CHECK_REFERRER`	1	后台登录来源校验
安全	`EMAIL_ADDRESS_VALIDATION_LEVEL`	注释状态	邮箱地址校验严格度
前台界面	`$installation_name` / `$default_system_language`	`phpList` / 注释状态	站点名称 / 默认语言
附件扩展	`ALLOW_ATTACHMENTS`	0	允许活动附件
附件扩展	`CLICKTRACK`	1	点击追踪
附件扩展	`$attachment_repository` / `$tmpdir`	`uploaded` / `/tmp`	附件仓库名 / 临时目录

四、核心参数分类详解

4.1 数据库连接参数

位于 config.php 顶部，是最先要改的四行：

$database_host = 'localhost';     // 数据库主机，远程库填 IP 或主机名
$database_name = 'phplistdb';     // 库名
$database_user = 'phplist';       // 专用账号（勿用 root）
$database_password = 'q1w2e3r4';

配套可选参数（默认注释，按需启用）：

$database_port = 3306;            // 非标准端口时指定（默认按 socket/3306）
$database_socket = '/var/run/mysqld/mysqld.sock';  // 走 socket 连接时指定
$database_connection_compression = false;  // 远程库可开压缩
$database_connection_ssl = false;          // 数据库 TLS 连接

表前缀与站点路径：

$table_prefix = 'phplist_';       // 全部业务表前缀，同库多实例时区分
$usertable_prefix = 'phplist_user_';  // 订阅者表前缀
$pageroot = '/lists';             // 应用在站点下的 URL 路径（影响生成的订阅/退订链接）

4.2 邮件发送参数

phpList 3.6.17 仅通过 PHPMailer 发信（官方注释：phpList now only uses phpMailer for sending）。SMTP 基础三项：

// SMTP 主机；留空则使用 PHP mail() 函数。
// 支持多服务器写法：'smtp1.example.com:25;smtp2.example.com:2500'
define('PHPMAILERHOST', 'smtp.example.com');

// SMTP 端口（默认 25）
define('PHPMAILERPORT', 25);

// 加密方式："ssl"（隐式 TLS，通常 465）或 "tls"（STARTTLS，通常 587），
// 或 false（明文）。默认注释状态=不加密
define('PHPMAILER_SECURE', 'tls');

// SMTP 认证（服务器要求时启用）
$phpmailer_smtpuser = 'smtpuser';
$phpmailer_smtppassword = 'smtppassword';

// SMTP 连接超时，默认 5 秒
define('SMTP_TIMEOUT', 5);

发件人三元组（强烈建议显式配置，缺失时的故障实录见 6.2 节）：

// 退信信封地址（Envelope Sender）：系统邮件与退信回收的发件人，
// 必须是合法邮箱且指向一个无人阅读、由 phpList 定期清空的邮箱
$message_envelope = 'listbounces@example.com';

测试与正式发送分离（可选）：

// 测试信走单独 SMTP 主机/端口，正式批量走另一套；未设置时共用上面两项
define('PHPMAILERTESTHOST', 'testsmtp.example.com');
define('PHPMAILERBLASTHOST', 'livesmtp.example.com');
define('PHPMAILERBLASTPORT', 25);

// 创建活动时在 Compose 页显示 Reply-To 字段（默认 false，回复地址取发件人）
define('USE_REPLY_TO', false);

4.3 队列与批量发送参数

先记住总开关 TEST——发布包默认值为 1（模拟发送，只显示不发），上线前必须改 0：

define('TEST', 0);

队列驱动方式：

// 1（默认）：在后台手动点「处理队列」；
// 0：禁止后台触发，队列完全交给命令行/cron（无人值守部署的推荐值，镜像版默认即为 0）
define('MANUALLY_PROCESS_QUEUE', 1);

// 单次队列运行最多处理的活动数（默认 999）
define('MAX_PROCESS_MESSAGE', 999);

// 单次队列运行时限（秒）；超时即停，下次 cron 从断点继续。0=不限
define('MAX_PROCESSQUEUE_TIME', 0);

批量与节流三件套（共享主机/有限流 ESP 的核心参数）：

// 每个周期最多发送 N 封；0=不限速全速发
define('MAILQUEUE_BATCH_SIZE', 0);
// 一个批量的周期长度（秒），3600=每小时一批
define('MAILQUEUE_BATCH_PERIOD', 3600);
// 两封邮件之间的固定间隔（秒），支持小数如 0.5；与批量配合使用
define('MAILQUEUE_THROTTLE', 0);
// 自动节流：让批量在周期内均匀分布而不是开局猛发；仅当 THROTTLE=0 且 PERIOD>0 时生效
define('MAILQUEUE_AUTOTHROTTLE', 0);

按收件域节流（防止对同一大域名发送过快被拉黑）：

define('USE_DOMAIN_THROTTLE', 0);   // 1=启用
define('DOMAIN_BATCH_SIZE', 1);     // 单域名每周期最多 N 封
define('DOMAIN_BATCH_PERIOD', 120); // 周期秒数（示例：每 2 分钟 1 封）
define('DOMAIN_AUTO_THROTTLE', 0);  // 1=单次队列内自动加延时（避免多次跑队列）

4.4 退信处理参数

退信（bounce）处理的协议与邮箱：

// 退信回收协议：'pop'（从 POP3 邮箱拉取）或 'mbox'（读本地 mbox 文件）
$bounce_protocol = 'pop';

// 1（默认）=后台手动处理退信；0=只允许命令行/cron 处理（推荐）
define('MANUALLY_PROCESS_BOUNCES', 1);

// pop 协议三要素
$bounce_mailbox_host = 'pop.example.com';
$bounce_mailbox_user = 'listbounces@example.com';
$bounce_mailbox_password = 'q1w2e3r4';

// 端口写法是"端口/协议/选项"字符串：
$bounce_mailbox_port = '110/pop3/notls';          // 明文 POP3（默认）
//$bounce_mailbox_port = '995/pop3/ssl/novalidate-cert';  // POP3S
// pop 协议下的邮箱名（默认 INBOX），多个邮箱逗号分隔
$bounce_mailbox_name = 'INBOX';
// 单次最多拉取的退信数（默认 100000，处理超时可调小）
$bounce_mailbox_maximum = 100000;

// mbox 协议时指定本地 mbox 文件（需 Web 运行用户可读写）
//$bounce_mailbox = '/var/spool/mail/listbounces';

退信清理与阈值：

$bounce_mailbox_purge = 1;                 // 1=处理后从邮箱删除
$bounce_mailbox_purge_unprocessed = 1;     // 1=未匹配订阅者的退信也删除
$bounce_unsubscribe_threshold = 5;         // 连续 5 次退信→订阅者标记 unconfirmed
$blacklist_gracetime = 5;                  // 退订确认邮件的宽限分钟数
$bounce_rules_batch_size = 500;            // 退信规则批处理大小
define('REPORT_DELETED_BOUNCES', 0);       // 1=邮件通报被删除的退信
define('USE_ADVANCED_BOUNCEHANDLING', 0);  // 1=启用高级退信处理（自定义规则）

⚠️ 实测提醒：$bounce_protocol = 'pop' 而本机没有对应 POP3 服务时，processbounces 直接报 Cannot create POP3 connection ... Connection refused——这是默认配置下的正常现象，说明退信邮箱三要素尚未配置或服务不可达。

4.5 安全相关参数

// 命令行白名单：允许运行 CLI 的系统用户。
// 空数组=不限制（适合专用部署账号）；显式列出则仅白名单用户可运行
$commandline_users = array();

// 每个管理员可创建的列表数（默认 1）
define('MAXLIST', 1);

// 订阅者密码功能：1=订阅/退订/偏好页要求邮箱+密码
define('ASKFORPASSWORD', 0);
// 密码哈希算法（默认 sha256；改动后旧密码需走找回流程）
define('HASH_ALGO', 'sha256');
// 1=退订也要求密码（需 ASKFORPASSWORD=1）
define('UNSUBSCRIBE_REQUIRES_PASSWORD', 0);
// 1=点个人退订链接立即退订；0=先展示确认页。官方注释警告置 1 可能被
// 邮件安全网关"预览链接"触发误退订，默认 1，遇误退订改 0
define('UNSUBSCRIBE_JUMPOFF', 1);
define('UNSUBSCRIBE_CONFIRMATION', true);   // 退订后发送确认邮件

// 后台登录来源（HTTP Referer）校验：1=开启（默认），代理环境下误拦可关闭
define('CHECK_REFERRER', 1);
// CHECK_REFERRER 拦截时的白名单（主机名数组）
// $allowed_referrers = array('www.example.com');

// 邮箱地址校验严格度：0=无，1=域名 MX 检查，2=MX+A 记录，3=RFC 全量
// 默认注释（基础格式校验）；对接严格 ESP 前建议≥2
define('EMAIL_ADDRESS_VALIDATION_LEVEL', 2);

4.6 前台与界面参数

$installation_name = 'phpList';        // 站点名称（页面标题与系统邮件署名）
$default_system_language = 'zh_CN';    // 后台默认语言（默认注释=英语）
define('LANGUAGE_SWITCH', true);       // 允许后台切换语言

// 订阅者页脚链接显示开关（默认均为 1）
define('SHOW_SUBSCRIBELINK', 1);
define('SHOW_PREFERENCESLINK', 1);
define('SHOW_UNSUBSCRIBELINK', 1);

define('EMPTY_VALUE_PREFIX', '-');     // 订阅者列表中空值的显示前缀
define('USE_ADMIN_DETAILS_FOR_MESSAGES', 0);  // 1=活动发件人自动取当前管理员信息
define('NOSTATSCOLLECTION', 0);        // 1=关闭匿名统计收集上报
define('PAGETEXTCREDITS', 1);          // 前台页脚 phpList 署名
define('EMAILTEXTCREDITS', 1);         // 邮件页脚 phpList 署名（AGPL 保留建议保留）

// Google Analytics 追踪：1=活动链接自动附加 UTM 参数
define('GOOGLE_SENDERID', 0);
// 点击追踪（默认开启）：重写链接统计点击
define('CLICKTRACK', 1);
define('CLICKTRACK_SHOWDETAIL', 0);    // 1=后台显示点击明细
// 远程图片内嵌进邮件（默认 0=直接引用远程 URL）
define('EMBEDEXTERNALIMAGES', 0);

4.7 附件与扩展参数

// 1=允许活动带附件。官方注释：附件会使邮件变大，
// 更推荐正文放下载链接；按需开启
define('ALLOW_ATTACHMENTS', 0);
define('FILESYSTEM_ATTACHMENTS', 0);        // 1=允许从服务器文件系统添加附件
define('MIMETYPES_FILE', '/etc/mime.types'); // mime.types 路径
define('DEFAULT_MIMETYPE', 'application/octet-stream'); // 未知类型回退值
$attachment_repository = 'uploaded';         // 附件仓库名
$tmpdir = '/tmp';                            // 临时目录（导入导出/生成文件）

// 插件目录（建议指向 phpList 目录之外，升级不丢）
define('PLUGIN_ROOTDIR', '/var/www/phplist-plugins');

// 上传图片目录（相对应用 images 目录），对应 B 篇部署中的持久化卷
define('UPLOADIMAGES_DIR', 'images');

五、生产环境配置模板

以下是一份整合上述核心参数、可直接落地的生产 config.php 追加段（在最小配置基础上追加，按环境替换域名与凭证）：

<?php
// ===== 数据库连接 =====
$database_host = 'localhost';
$database_name = 'phplistdb';
$database_user = 'phplist';
$database_password = 'q1w2e3r4';
$table_prefix = 'phplist_';
$usertable_prefix = 'phplist_user_';
$pageroot = '/lists';

// ===== 发送引擎 =====
define('TEST', 0);                              // 上线必须 0
define('PHPMAILERHOST', 'smtp.example.com');    // 真实 SMTP 服务器
define('PHPMAILERPORT', 587);
define('PHPMAILER_SECURE', 'tls');
$phpmailer_smtpuser = 'news@example.com';
$phpmailer_smtppassword = '替换为SMTP密码';

// ===== 发件人与退信信封 =====
$message_envelope = 'listbounces@example.com';  // 退信信封，指向专用退信邮箱

// ===== 队列与批量 =====
define('MANUALLY_PROCESS_QUEUE', 0);            // 队列交给 cron
define('MAILQUEUE_BATCH_SIZE', 2000);           // 每小时 2000 封
define('MAILQUEUE_BATCH_PERIOD', 3600);
define('MAILQUEUE_THROTTLE', 0);                // 间隔交给批量控制
define('MAILQUEUE_AUTOTHROTTLE', 1);            // 周期内均匀发送

// ===== 退信处理 =====
$bounce_protocol = 'pop';
define('MANUALLY_PROCESS_BOUNCES', 0);          // 退信交给 cron
$bounce_mailbox_host = 'pop.example.com';
$bounce_mailbox_user = 'listbounces@example.com';
$bounce_mailbox_password = '替换为退信邮箱密码';
$bounce_mailbox_port = '995/pop3/ssl/novalidate-cert';
$bounce_unsubscribe_threshold = 5;

// ===== 安全 =====
$commandline_users = array();                   // 或指定运行 cron 的系统用户
define('HASH_ALGO', 'sha256');
define('EMAIL_ADDRESS_VALIDATION_LEVEL', 2);
?>

配套的 crontab 示例（每 10 分钟跑一次队列与退信）：

*/10 * * * * /usr/local/bin/phplist -pprocessqueue >/dev/null 2>&1
*/30 * * * * /usr/local/bin/phplist -pprocessbounces >/dev/null 2>&1

CLI 包装脚本与 cron 的部署细节见《phpList 3.6.17 常用 CLI 命令详解》。

六、数据库层参数与占位符机制

6.1 [DOMAIN] 占位符

初始化时，phpList 按访问主机名生成数据库层默认值：domain、website 存主机名本身，admin_address/message_from_address/message_replyto_address 则存 noreply@[DOMAIN]、webmaster@[DOMAIN] 形式的占位符地址。若初始化时使用的主机名带端口（如 127.0.0.1:8130）或为 IP，这些默认值就是非法邮箱，是命令行/后台默认发件人故障的直接根源（修复实录见 6.2 节）。

6.2 修复实录：默认发件人为非法地址

背景：CLI 发送全军覆没，phplist_eventlog 中记录 Invalid address: (Sender): webmaster@127.0.0.1:8130（完整排障过程见《Ubuntu 22.04 安装 phpList 3.6.17 指南》第七节）。数据库层确认（实测回显）：

item                  value
domain                127.0.0.1:8130
message_from_address  noreply@[DOMAIN]
message_from_name     Webmaster

代码层修复：在 config.php 配置 $message_envelope（合法邮箱），解决 Sender 回退问题；命令行发送用 -f admin@example.com 显式指定 From。

数据库层修复（实测通过）：将默认发件人改写为合法地址：

mysql phplistdb -e "update phplist_config set value='admin@example.com' where item='message_from_address'"
mysql phplistdb -e "update phplist_config set value='admin@example.com' where item='message_replyto_address'"

验证（实测回显）：

item	value
domain	127.0.0.1:8130
message_from_address	admin@example.com
message_from_name	Webmaster
message_replyto_address	admin@example.com

生产上更稳妥的入口是后台 Settings 页面（图形化改写同一张表）；domain/website 等站点地址项如需同步修正，也可按同样方式改写。

七、注意事项与常见问题

Q1：改了 config.php 不生效？ ① 确认改的是应用实际加载的 lists/config/config.php（不是 config_extended.php）；② PHP 常量以先定义为准，确认没有在文件更早位置重复定义同名常量；③ 数据库层参数（发件人、站点地址）不在 config.php 里，需走后台设置或 SQL。

Q2：队列显示发送成功但收不到？ 按序检查：TEST 是否仍为 1（模拟发送）；PHPMAILERHOST/PORT 是否可达；message_envelope 缺失导致的 Sender 非法问题（见 6.2 节）；最后查 phplist_eventlog 表定位真实错误。

Q3：SMTP 认证配置了却不生效？ $phpmailer_smtpuser/$phpmailer_smtppassword 是变量不是常量，写法必须是 $ 开头；PHPMAILER_SECURE 只接受 ssl/tls/false 三种值，465 端口配 ssl、587 端口配 tls，配反会握手失败。

Q4：$bounce_mailbox_port 能直接写 995 吗？ 不能。该参数是「端口/协议/选项」复合字符串（如 995/pop3/ssl/novalidate-cert），只写数字会导致 POP3 连接参数解析异常。

Q5：如何双实例共用一个库？ 通过 $table_prefix/$usertable_prefix 区分表前缀即可，两实例的业务数据互不干扰；注意数据库层的站点地址参数是全局的，双实例需各自独立数据库。

Q6：部署方式的配置差异？ 镜像部署的配置载体是环境变量（DB_HOST、MAILHOST 等）+ /etc/phplist/config.php 模板，默认值与源码包不同（如 TEST=0、队列自动处理），差异清单见《phpList 3.6.17 Docker Compose 部署指南》第五节。