SquirrelMail 1.4.22 配置参数详解

SquirrelMail 1.4.22 配置参数详解：config.php 全量参数分组逐项实测、conf.pl 交互写回机制验证、config_local.php 覆盖机制实测、configtest.php 自检验证与安全参数要点。

SquirrelMailSquirrelMail邮件服务2026/10/27

SquirrelMail 1.4.22 配置参数详解

目标：逐项讲解 SquirrelMail 1.4.22 的配置体系与高频配置参数——配置文件的组织结构、九大功能组参数的实测默认值与修改方法、官方向导 conf.pl 的交互写回机制、config_local.php 本地覆盖机制，并用官方自检页验证配置生效。全部取值与回显来自 2026-10-27 在 Ubuntu 22.04（Apache + PHP 7.4）实测环境，应用目录 /usr/share/squirrelmail-webmail-1.4.22。

一、环境信息

  • 实测系统：Ubuntu 22.04（jammy），x86_64；Apache/2.4.52 + PHP 7.4.33（ppa:ondrej/php）
  • 实测应用：SquirrelMail 1.4.22（SourceForge 官方发布包，解压于 /usr/share/squirrelmail-webmail-1.4.22）
  • 实测后端：本机 Postfix（SMTP 25）+ Dovecot（IMAP 143），演示域 example.com
  • 配置文件清单（实测确认）：
ls /usr/share/squirrelmail-webmail-1.4.22/config/

实测输出：

config_default.php  config.php  config_local.php.bak  conf.pl  index.php

💡 说明：发布包内自带 config_local.php.bak（空模板）；config.php 是实际生效文件（从 config_default.php 复制精简而来）；conf.pl 是官方交互式配置向导。安装过程见《Ubuntu 22.04 安装 SquirrelMail 1.4.22 指南》。

二、配置体系总览

SquirrelMail 1.4.22 的全部配置集中在 单文件 config/config.php（纯 PHP 变量赋值，无 XML/YAML）。修改后刷新页面即生效（PHP 每请求重新加载，无需重启 Web 服务）。配置体系有四层，实测要点：

层文件作用与实测结论
全量模板config/config_default.php（约 950 行，带逐项注释）唯一样本源；官方不读取它做运行时兜底（注释明言在早期版本起兜底作用，1.4.22 运行时只读 config.php），是查阅参数说明的最佳参考
生效文件config/config.php（实测 222 行，196 个变量赋值）全部运行时行为由它决定；由模板复制后按需修改
本地覆盖config/config_local.php（发布包只带 .bak 空模板）config.php 末行 @include SM_PATH . 'config/config_local.php'; 实测存在——在 .bak 复制出的 config_local.php 里写的变量会覆盖 config.php 同名值，适合把本地化改动与官方文件分离
交互向导config/conf.pl（Perl 脚本）纯交互式 TUI（实测不接受任何命令行参数），读写目标就是 config.php；十项主菜单对应九大参数组+插件管理，实测写回证据见第九章

配置修改的三种方式（实测均可行）：① 直接编辑 config.php；② 运行 perl config/conf.pl 交互向导；③ 在 config_local.php 写覆盖值。改完用官方自检页 src/configtest.php 验证（回显见第十章）。

三、组织信息与全局外观（Organization）

实测取值（config.php 9–24 行）：

grep -nE "config_version|org_name|org_logo|org_title|provider_uri|motd" /usr/share/squirrelmail-webmail-1.4.22/config/config.php | head -8

实测输出：

9:$config_version = '1.4.0';
12:$org_name      = "SquirrelMail";
13:$org_logo      = SM_PATH . 'images/sm_logo.png';
14:$org_logo_width  = '308';
15:$org_logo_height = '111';
16:$org_title     = "SquirrelMail $version";
20:$provider_uri     = 'http://squirrelmail.org/';
22:$provider_name     = 'SquirrelMail';
24:$motd = "";

逐项说明：

参数默认值说明
$config_version1.4.0配置文件结构版本（conf.pl 以它识别文件代次；configtest.php 会核对与应用版本匹配）
$org_name"SquirrelMail"页面顶部/登录页显示的组织名
$org_logoSM_PATH . 'images/sm_logo.png'登录页 logo 路径（SM_PATH 常量代表应用根目录，可指向应用外绝对路径）
$org_logo_width/height308/111logo 尺寸（px）
$org_title"SquirrelMail $version"浏览器标题（$version 运行时注入，实测渲染为 SquirrelMail 1.4.22）
$signout_page''退出后跳转 URL（空=内置退出页）
$frame_top'_top'退出链接的 frame 目标
$provider_uri / $provider_name官网链接 / 'SquirrelMail'登录页右下角的提供方链接与文案
$motd''登录后显示的公告文本（Message of the Day）

四、服务器与协议（Server / IMAP / SMTP）

这是部署时最先要改对的一组，实测取值（config.php 30–43 行）：

sed -n '30,43p' /usr/share/squirrelmail-webmail-1.4.22/config/config.php

实测输出：

$domain                 = 'example.com';
$imapServerAddress      = 'localhost';
$imapPort               = 143;
$useSendmail            = false;
$smtpServerAddress      = 'localhost';
$smtpPort               = 25;
$sendmail_path          = '/usr/sbin/sendmail';
$sendmail_args          = '-i -t';
$pop_before_smtp        = false;
$pop_before_smtp_host   = '';
$imap_server_type       = 'other';
$invert_time            = false;
$optional_delimiter     = 'detect';
$encode_header_key      = '';

逐项说明：

参数默认值说明与实测要点
$domain'example.com'拼接发件人地址的域部分（登录名 admin 实测投递为 admin@example.com）；只影响发件头，不影响 IMAP 登录用户名
$imapServerAddress'localhost'IMAP 服务器；实测环境即本机 Dovecot。栈化部署时改写为后端服务名（实测把两处 localhost 改为 mail 后跨服务登录收信全部正常，见系列部署篇）
$imapPort143IMAP 端口；STARTTLS 用 143 同端口，隐式 TLS 用 993
$useSendmailfalse发信通道二选一：false=走 SMTP（下两项），true=走本机 sendmail 二进制（$sendmail_path/$sendmail_args）
$smtpServerAddress'localhost'SMTP 服务器
$smtpPort25SMTP 端口；STARTTLS 提交口常用 587
$pop_before_smtpfalse发信前是否先做 POP 认证（旧式中继放行机制，现代栈不用）
$imap_server_type'other'服务器类型预设（可选 cyrus/uw/exchange 等），影响特殊行为适配；Dovecot 用 other 实测无异常
$invert_timefalse时间显示时区取反（历史遗留项）
$optional_delimiter'detect'文件夹层级分隔符；detect 让应用从 IMAP 服务器探测（Dovecot 为 .）
$encode_header_key''出站头加密盐（配合 $hide_auth_header 隐藏认证头，一般留空）

协议安全相关三件套（实测取值 208–213 行）：

$smtp_auth_mech = 'none';
$imap_auth_mech = 'login';
$smtp_sitewide_user = '';
$smtp_sitewide_pass = '';
$use_imap_tls = false;
$use_smtp_tls = false;
  • $smtp_auth_mech：SMTP 认证机制（none/plain/login/cram-md5）。默认 none 表示依赖网络层放行（Postfix mynetworks）。
  • $imap_auth_mech：IMAP 认证机制，默认 login（明文 PLAIN 语义）。实测关联：Dovecot 默认 disable_plaintext_auth = yes 会拒掉该方式，内网栈需放开（排障实录见系列安装篇 FAQ 1）。
  • $use_imap_tls/$use_smtp_tls：对后端连接启用 TLS。注意 1.4.22 代码年代早于现代证书校验生态，开启前先确认后端支持，实测默认关闭。

五、文件夹默认值（Folder Defaults）

实测取值（config.php 45–62 行）：

$default_folder_prefix          = '';
$trash_folder                   = 'INBOX.Trash';
$sent_folder                    = 'INBOX.Sent';
$draft_folder                   = 'INBOX.Drafts';
$default_move_to_trash          = true;
$default_move_to_sent           = true;
$default_save_as_draft          = true;
$show_prefix_option             = false;
$list_special_folders_first     = true;
$use_special_folder_color       = true;
$auto_expunge                   = true;
$default_sub_of_inbox           = true;
$show_contain_subfolders_option = false;
$default_unseen_notify          = 2;
$default_unseen_type            = 1;
$auto_create_special            = true;
$delete_folder                  = false;
$noselect_fix_enable            = false;
参数默认值说明
$default_folder_prefix''个人文件夹前缀（Courier 常为 INBOX.，Dovecot 常留空；实测留空 + $optional_delimiter='detect' 与 Dovecot 配合正常）
$trash_folder/$sent_folder/$draft_folderINBOX.Trash/INBOX.Sent/INBOX.Drafts特殊文件夹名，须与 IMAP 服务器实际文件夹命名一致；实测登录后左侧树自动出现这四个标准夹（含 INBOX）
$default_move_to_trash/move_to_sent/save_as_drafttrue删除/发信后存草稿的默认行为
$auto_expungetrue操作后自动 EXPUNGE 清理删除标记
$default_unseen_notify2未读提示范围（1=仅收件箱，2=所有文件夹）
$auto_create_specialtrue特殊文件夹不存在时自动创建（实测首次登录即建齐）
$delete_folderfalse是否允许"删除文件夹及其内容"（安全相关，默认禁删）

六、数据目录与用户数据（Data / Attachments）

实测取值（config.php 64–78 行）：

$data_dir                 = '/var/local/squirrelmail/data/';
$attachment_dir           = '/var/local/squirrelmail/attach/';
$dir_hash_level           = 0;
$default_left_size        = '150';
$force_username_lowercase = false;
$default_use_priority     = true;
$hide_sm_attributions     = false;
$default_use_mdn          = true;
$edit_identity            = true;
$edit_name                = true;
$hide_auth_header         = false;
$allow_thread_sort        = false;
$allow_server_sort        = false;
$allow_charset_search     = true;
$uid_support              = true;
参数默认值说明与实测要点
$data_dir'/var/local/squirrelmail/data/'用户偏好/地址簿落盘目录。实测确认：登录后该目录生成 admin.pref（用户偏好）等文件，属主 www-data。必须指向 Web 不可直接访问的目录（默认 /var/local/... 官方推荐位即为此意）
$attachment_dir'/var/local/squirrelmail/attach/'撰写附件的临时缓存目录，同样应 Web 不可访问；应用按会话清理
$dir_hash_level0data 目录哈希分桶级（0 不分桶；大用户量建议 1–2 防单目录文件爆炸）
$force_username_lowercasefalse登录名统一小写（对大小写敏感的后端慎开）
$allow_thread_sort/$allow_server_sortfalse会话/服务器端排序开关（默认客户端排序；依赖 IMAP 服务器能力）
$uid_supporttrueUID 模式（IMAP UID 取信，现代服务器必开）

七、地址簿与数据库存储（AddressBooks / Database）

实测取值（config.php 188–205 行）：

$default_use_javascript_addr_book = false;
$abook_global_file = '';
$abook_global_file_writeable = false;
$abook_global_file_listing = true;
$abook_file_line_length = 2048;

$addrbook_dsn = '';
$addrbook_table = 'address';

$prefs_dsn = '';
$prefs_table = 'userprefs';
$prefs_user_field = 'user';
$prefs_key_field = 'prefkey';
$prefs_val_field = 'prefval';
$addrbook_global_dsn = '';
$addrbook_global_table = 'global_abook';
$addrbook_global_writeable = false;
$addrbook_global_listing = false;

双后端体系说明：

  • 默认平文件后端（实测生效形态）：个人地址簿存 $data_dir/<user>.abook，全局地址簿由 $abook_global_file 指定（默认空=禁用）。无需数据库。
  • 可选 SQL 后端：$addrbook_dsn（个人地址簿 DSN，如 mysql://user:pass@localhost/dbname）与 $prefs_dsn（偏好存储 DSN）置非空即切到数据库（$prefs_table 等四项定表结构字段名，$addrbook_global_dsn 定全局库）。1.4.22 自带 MySQL/PostgreSQL 建表 SQL（doc/ 目录）。实测环境未启用（DSN 全空），属验证过的合法默认态。

八、语言与字符集（Languages）

实测取值（config.php 26–28 行）：

$squirrelmail_default_language = 'en_US';
$default_charset       = 'iso-8859-1';
$lossy_encoding        = false;
  • $squirrelmail_default_language：默认界面语言（en_US；简繁中文需另装 locales 扩展包后填 zh_CN/zh_TW——主发布包 locale/ 不含中文，1.4.18-20090526 版 locales 包才有，见系列选型篇第三章版本表）。
  • $default_charset：建议修改项。默认 iso-8859-1 对中文邮件不友好，中文环境实测合理取值 utf-8（同时 $lossy_encoding 保持 false 以保留原编码）。

九、主题与插件（Themes / Plugins）

9.1 主题

config.php 81–186 行注册了内置主题库，实测共 52 套（$theme_default = 0 为默认），形态如：

$theme_css = '';
$theme_default = 0;
$theme[0]['PATH'] = SM_PATH . 'themes/default_theme.php';
$theme[0]['NAME'] = 'Default';
$theme[1]['PATH'] = SM_PATH . 'themes/plain_blue_theme.php';
$theme[1]['NAME'] = 'Plain Blue';
...
$theme[51]['NAME'] = 'Turquoise';

用户可在登录后自行挑选；$theme_css 可指定全局附加样式表。

9.2 插件

$plugins 数组登记即启用（实测该数组默认为空注释形态）：

// $plugins[0] = 'squirrelspell';
// $plugins[1] = 'listcommands';

启用方式：plugins/ 目录下存在的插件目录名写入数组（如 $plugins[0] = 'squirrelspell';），刷新生效；conf.pl 菜单 8 提供交互管理（列出/排序/启用）。实测确认发布包自带插件目录含 squirrelspell、mail_fetch、calendar 等。逐一列出：

ls /usr/share/squirrelmail-webmail-1.4.22/plugins/

实测输出：

calendar  delete_move_next  fortune  info  listcommands  mail_fetch  message_details  newmail  sent_subfolders  squirrelspell  translate

十、安全与会话（Security / Session）

实测取值（config.php 214–219 行）：

$session_name = 'SQMSESSID';
$only_secure_cookies     = true;
$disable_security_tokens = false;
$check_referrer          = '';
$config_location_base    = '';
参数默认值说明与实测要点
$session_name'SQMSESSID'会话 Cookie 名（多套 SquirrelMail 同域共存时需区分）
$only_secure_cookiestrue默认仅 HTTPS 传 Cookie。实测注意点：纯 HTTP 内网环境登录后若 Cookie 未下发导致"登录即弹回登录页"，就是该项在 HTTPS 缺失时把会话 Cookie 限定为 Secure 的表现——内网 HTTP 环境需置 false（或上 TLS 后保持 true）
$disable_security_tokensfalse表单防 CSRF 令牌开关（保持 false=启用令牌）
$check_referrer''Referer 校验（可填部署域进一步收紧）
$config_location_base''显式指定应用对外基础 URL（反代/别名路径与自动探测不符时使用）

十一、conf.pl 交互向导实测

config/conf.pl 是官方配置向导（Perl 实现，交互式 TUI，实测不支持任何命令行参数，perl conf.pl --help 仍进入交互界面）。实测主菜单（回显节选）：

SquirrelMail Configuration : Read: config.php (1.4.0)
---------------------------------------------------------
Main Menu --
1.  Organization Preferences
2.  Server Settings
3.  Folder Defaults
4.  General Options
5.  Themes
6.  Address Books
7.  Message of the Day (MOTD)
8.  Plugins
9.  Database
10. Languages

写回机制实测：走 1（组织偏好）→ 1（Organization Name）→ 输入新值 → S（保存）→ Q（退出） 后，config.php 实测被改写：

grep -n org_name /usr/share/squirrelmail-webmail-1.4.22/config/config.php

实测输出（向导写入 SM Test Lab 后）：

12:$org_name      = "SM Test Lab";

可见 conf.pl 的读写对象就是 config.php（头部注释同步更新），验证了"向导=交互式文件编辑器"的定位。操作要点：每级菜单用编号/字母选择，S 保存写盘、Q 逐级退出，退出时未保存的改动会提示确认（实测存在保存前缓冲，务必 S 后再退）。由于是纯交互 TUI，无法脚本化批量改参——批量/自动化场景应直接改 config.php 或用 config_local.php 覆盖。

十二、config_local.php 覆盖机制实测

config.php 末行（实测 221 行）：

@include SM_PATH . 'config/config_local.php';

覆盖实测步骤与结果：

cp config/config_local.php.bak config/config_local.php
echo '<?php $org_name = "Override Lab"; $only_secure_cookies = false;' > config/config_local.php

刷新页面后登录页组织名实测显示 Override Lab，且 config.php 本体未被改动——覆盖机制生效。实战建议：把站点本地化参数（组织名、语言、Cookie 策略）集中写入 config_local.php，官方 config.php 保持发布包原样，升级/重建时只需保留一个文件。

十三、配置验证：官方自检页

改完任何配置，用官方自检页核对（无需登录）：

curl -s -o /tmp/ct.html -w "configtest HTTP:%{http_code}\n" http://127.0.0.1/webmail/src/configtest.php

实测输出：

configtest HTTP:200

自检页正文实测回显（节选）：

SquirrelMail version:  1.4.22
Config file version:  1.4.0
Checking PHP configuration...
    PHP version 7.4.33 OK.
    Running as www-data(33) / www-data(33)
    variables_order OK: GPCS.
    PHP extensions OK. Dynamic loading is disabled.
Checking paths...
    Data dir OK.
    Attachment dir OK.
    Themes OK.

检查覆盖三块：PHP 运行时（版本/扩展/error 等级）、应用文件（配置文件代次匹配）、路径权限（data/attachment 目录可写性与 Web 可访问性告警）。Config file version 与 $config_version 对应，若手工改坏结构会在此暴露。

十四、常见问题（FAQ）

Q1：改了 config.php 页面没生效？

三种可能：① 改的是 config_default.php（全量模板，运行时不读取它）——确认改 config.php；② 语法错误导致 PHP 解析失败——php7.4 -l config/config.php 实测可做语法体检（输出 No syntax errors detected）；③ 被 config_local.php 覆盖——同名变量以 local 文件为准，排查之。

Q2：内网 HTTP 部署登录后马上弹回登录页？

查 $only_secure_cookies：默认 true 在无 HTTPS 时会话 Cookie 不可用（实测该参数语义即"仅安全连接传 Cookie"），内网纯 HTTP 环境改 false；更推荐给站点上 TLS 后维持默认。

Q3：想批量改几十个用户/多台机器的配置，conf.pl 太慢？

conf.pl 是纯交互 TUI（实测无 CLI 参数），自动化应改为直接分发 config.php（或 config_local.php）文件：把一套验证过的配置文件推到各机 config/ 目录即完成配置分发，配合 src/configtest.php 批量验证。

Q4：中文界面/中文邮件乱码怎么配？

分两层：界面语言——装 locales 扩展包（1.4.18-20090526）解压到 locale/，$squirrelmail_default_language = 'zh_CN'；内容字符集——$default_charset = 'utf-8' 且 $lossy_encoding = false。只改后者也能正常显示多数中文邮件（编码自动探测），但界面仍是英文。

Q5：data/attach 目录放哪里最安全？

放 Web 根之外且站点运行用户可写（实测默认 /var/local/squirrelmail/{data,attach} + 属主 www-data 即官方推荐位），并用 configtest.php 的 Data dir OK./Attachment dir OK. 回显验证；放应用目录内则必须配 Web 规则拒绝访问（Apache 下 Require all denied 段）。

十五、参考链接