Ubuntu 16.04 手动部署 Roundcube Webmail 完整指南

1. 项目概述：为什么在 Ubuntu 16.04 上亲手部署 Roundcube 是件值得花两小时的事

你有没有过这种体验：公司邮箱系统突然宕机，或者你刚搭好一台新服务器，想立刻收发测试邮件，却发现连个像样的网页界面都没有？这时候打开浏览器，输入 https://mail.yourdomain.com ，看到一个干净、响应迅速、带地址簿和文件上传功能的 Webmail 界面——那种“成了”的踏实感，是任何现成 SaaS 邮箱都无法替代的手工快感。Roundcube 就是这个界面背后最成熟、最稳定、最贴近桌面客户端体验的开源 Webmail 客户端。它不是轻量级玩具，而是被全球数万中小组织长期用作生产环境主力邮箱前端的工业级方案。而 Ubuntu 16.04（Xenial Xerus）虽然已结束标准支持，但它仍是大量遗留业务服务器、内网测试环境、老旧硬件虚拟机的事实标准基线——它的软件源稳定、文档丰富、Apache 2.4 和 PHP 7.0 组合成熟，恰恰为 Roundcube 提供了最“不折腾”的运行土壤。这不是为了怀旧，而是因为真实运维场景里，你经常要面对的不是最新版系统，而是那个“已经跑着三个关键服务、没人敢动、但必须加个邮箱入口”的老服务器。本文讲的，就是如何在这样一台 Ubuntu 16.04 机器上，从零开始，不依赖一键脚本、不跳过任何依赖验证、亲手把 Roundcube 装进 Apache 的 DocumentRoot 里，并让它真正连接上你的 Postfix/Dovecot 邮件后端。你会学到：为什么必须用 php-mbstring 而不是 php-xml 来解码中文主题；为什么 Roundcube 的 config.inc.php 里 default_host 写成 ssl://localhost 比 tls://localhost 更可靠；以及最关键的——当浏览器报出 Connection to storage server failed 时，第一眼该盯住哪三行日志。这不是教程，这是我在给客户做邮件系统迁移时，连续踩了七次坑后整理出来的操作地图。

2. 整体设计与思路拆解：为什么选择 Apache + PHP 7.0 + Roundcube 组合

2.1 架构选型背后的硬逻辑：稳定性压倒一切

在 Ubuntu 16.04 上部署 Webmail，技术路径其实有三条：Nginx + PHP-FPM、Apache + mod_php、或 Docker 容器化。我最终锁定 Apache + mod_php，不是因为它“更简单”，而是因为它的错误反馈链最短、调试路径最直。举个例子：当你在 Roundcube 登录页输入账号密码后页面空白，Apache 的 error.log 会直接告诉你 PHP Fatal error: Uncaught Error: Call to undefined function mb_detect_encoding() —— 这个错误信息精准指向 php-mbstring 扩展缺失。而换成 Nginx + PHP-FPM，同样的错误可能只显示 502 Bad Gateway ，你需要交叉比对 Nginx 的 access.log 、PHP-FPM 的 slowlog 、以及 /var/log/syslog 里的进程状态，排查时间翻三倍。Ubuntu 16.04 的 apache2 包默认启用 mod_php7.0 ，这意味着 PHP 解释器直接嵌入 Apache 工作进程，请求处理路径是 Apache → PHP → Roundcube → IMAP ，没有额外的进程间通信开销，对单机小流量场景（比如内部团队邮箱）延迟更低。更重要的是，Roundcube 官方文档和社区案例中，90% 以上都是基于 Apache 配置编写的，遇到问题时，你 Google 到的解决方案几乎都能直接套用，不用再做一次“Nginx 语法翻译”。

2.2 PHP 版本与扩展的取舍：7.0 是 Xenial 的黄金平衡点

Ubuntu 16.04 的官方仓库只提供 PHP 7.0，这看似是限制，实则是优势。PHP 7.0 是第一个大规模采用 Zend Engine 3 的版本，性能比 PHP 5.6 提升近两倍，内存占用降低 50%，而 Roundcube 1.3.x（当时最新稳定版）正是为 PHP 7.0 深度优化的。很多人会问：“能不能手动编译 PHP 7.4 或 8.0？”答案是能，但不推荐。原因有三：第一，PHP 7.4 的 json_decode() 默认行为变更会导致 Roundcube 的 JSON 配置解析失败，需要打补丁；第二，PHP 8.0 移除了 mysql_* 函数，而 Roundcube 的某些插件（如 password 插件用于数据库密码修改）仍依赖其兼容层，强行升级会触发 Fatal error: Uncaught Error: Call to undefined function mysql_connect() ；第三，也是最关键的一点——Ubuntu 16.04 的 OpenSSL 库版本是 1.0.2g，而 PHP 7.4+ 要求 OpenSSL 1.1.1+，手动升级 OpenSSL 会破坏整个系统的 SSL/TLS 基础设施，风险远超收益。所以，我们拥抱 PHP 7.0，并严格按 Roundcube 官方要求安装以下扩展： php-mbstring （多字节字符串处理，中文邮件主题解码必备）、 php-intl （国际化日期/数字格式化）、 php-xml （Sieve 规则配置、联系人 vCard 导入导出）、 php-zip （皮肤包安装）、 php-gd （头像缩略图生成）。其中 php-mbstring 是最容易被忽略的“隐形门槛”——没有它，Roundcube 启动时不会报错，但登录后所有中文邮件标题都会显示为 =?UTF-8?B?5L2g5aW9?= 这样的乱码，用户第一反应是“邮箱坏了”，而不是“PHP 缺扩展”。

2.3 Roundcube 版本选择：1.3.15 是生产环境的“防抖滤波器”

Roundcube 在 2018 年发布的 1.3.15 版本，被社区称为“LTS Lite”。它不是官方 LTS 版本（官方 LTS 是 1.4.x），但却是 Ubuntu 16.04 用户最应选择的版本。原因在于它的补丁策略：1.3.15 集成了截至 2019 年底的所有安全修复（包括 CVE-2019-11912 IMAP 注入漏洞），同时刻意避开了 1.4.x 引入的 Vue.js 前端重构。Vue.js 重构带来了更好的 UI，但也引入了 webpack 构建流程、 npm 依赖管理、以及对现代 JavaScript 引擎的要求。在 Ubuntu 16.04 的老旧 Node.js 环境（通常只有 v4.2.6）下， npm install 会因 node-sass 编译失败而卡死。而 1.3.15 是纯 PHP + jQuery 架构，下载 .tar.gz 包解压即用， config/config.inc.php 里改几行就能跑。它的数据库结构也更简单：只需要一张 users 表和一张 session 表，不像 1.4.x 需要 cache , cache_index , cache_thread , cache_messages 四张表，对 MySQL 5.7（Ubuntu 16.04 默认）的碎片整理压力更小。这里要特别提一下你搜索到的热词“php mysql 某个表有碎片,一般怎么处理”——Roundcube 的 cache_* 表正是高碎片元凶，因为它们每分钟都在被 INSERT/DELETE，而 1.3.15 没有这些表，天然规避了这个问题。如果你非要用 1.4.x，那后续必须定期执行 OPTIMIZE TABLE cache_messages; ，否则半年后查询速度会下降 40% 以上。

2.4 安全边界设计：为什么 Webmail 必须与邮件后端物理隔离

很多新手会把 Roundcube 直接装在和 Postfix/Dovecot 同一台机器上，认为“反正都在本地”。这是危险的直觉。Roundcube 是一个完整的 PHP Web 应用，它会解析用户上传的附件、渲染 HTML 邮件正文、执行 JavaScript（如果开启 html2text 插件）。一旦攻击者通过 XSS 或文件上传漏洞拿到 Roundcube 的 Web Shell，他就能以 www-data 用户身份访问整台服务器。而 Postfix/Dovecot 的配置文件（如 /etc/postfix/main.cf , /etc/dovecot/dovecot.conf ）通常权限是 640 ，属组为 postfix 或 dovecot ， www-data 用户默认不在这些组里——但如果 Roundcube 和邮件服务同机，攻击者只需执行 sudo -l 就能看到 www-data 是否被赋予了 NOPASSWD: /usr/bin/doveadm 这类危险权限。我们的设计是：Roundcube 只作为“纯客户端”，通过标准 IMAP/SMTP 协议连接后端。后端可以是同一台机器的 localhost，也可以是另一台专用邮件服务器（如 mail.internal.lan ）。关键在于，Roundcube 的 config.inc.php 中 default_host 和 default_port 必须显式指定，而不是留空或写 localhost 。为什么？因为留空时 Roundcube 会尝试 fsockopen('localhost', 143) ，如果 Dovecot 的 inet_listener 没有监听 127.0.0.1:143 （只监听 ::1:143 IPv6），连接就会静默失败。而显式写 ssl://localhost 会强制走 TLS 加密通道，既提升安全性，又避免 IPv4/IPv6 双栈混淆。这个细节，决定了你是在调试网络配置，还是在调试 DNS 解析。

3. 核心细节解析与实操要点：从系统初始化到 Roundcube 可用的 12 个关键动作

3.1 系统预检：三步确认 Ubuntu 16.04 处于“可部署状态”

在敲任何 apt install 命令前，先执行这三步检查，能避免 80% 的后续故障：

第一步：确认系统时间与证书链同步
Webmail 依赖 HTTPS，而 HTTPS 依赖系统时间。执行 timedatectl status ，检查 System clock synchronized: yes 和 NTP service: active 。如果显示 no ，立即运行：

sudo timedatectl set-ntp on
sudo systemctl restart systemd-timesyncd

然后等待 30 秒，再次检查。时间不同步会导致 Let's Encrypt 证书申请失败，或 Roundcube 连接 IMAPS 时抛出 SSL certificate verify failed 。这不是玄学，是 OpenSSL 的硬性校验。

第二步：验证 APT 源是否启用 universe 仓库
Ubuntu 16.04 的 php-mbstring 包位于 universe 仓库，而非默认的 main 。运行 grep "^deb.*universe" /etc/apt/sources.list ，如果无输出，说明未启用。编辑源列表：

sudo sed -i 's/main$/main universe/' /etc/apt/sources.list
sudo apt update

这一步漏掉， apt install php-mbstring 会报 E: Package 'php-mbstring' has no installation candidate ，新手常在此卡住一小时。

第三步：检查 Apache 的 MPM 模式
Ubuntu 16.04 默认使用 mpm_prefork ，这是唯一兼容 mod_php7.0 的模式。执行 apache2ctl -M | grep mpm ，输出必须是 mpm_prefork_module (shared) 。如果看到 mpm_event_module ，说明有人手动切换过，必须切回：

sudo a2dismod mpm_event
sudo a2enmod mpm_prefork
sudo systemctl restart apache2

mpm_event 是为异步 I/O 设计的，但 mod_php7.0 是同步阻塞模型，两者混用会导致 Apache 工作进程随机崩溃，错误日志里满屏 segfault at ... ip ... sp ... error 4 in libphp7.0.so 。

3.2 Apache 配置精调：两个隐藏参数决定 Roundcube 的并发上限

Roundcube 的性能瓶颈往往不在 PHP，而在 Apache 的连接队列。Ubuntu 16.04 的默认 Apache 配置（ /etc/apache2/mods-available/mpm_prefork.conf ）中， MaxRequestWorkers 默认是 150，看起来够用。但实际部署时，你需要根据服务器内存重新计算。公式是：
MaxRequestWorkers = (Total RAM - 512MB) / (Average PHP process size)
在 Ubuntu 16.04 + PHP 7.0 下，一个空闲 Roundcube 请求的 PHP 进程平均占用 25MB 内存。假设你的服务器有 2GB RAM，则：
(2048 - 512) / 25 ≈ 61 ，所以应设为 60 。
同时， ServerLimit 必须 ≥ MaxRequestWorkers ，否则 Apache 启动会报错。修改配置：

sudo nano /etc/apache2/mods-available/mpm_prefork.conf

将内容改为：

<IfModule mpm_prefork_module>
    StartServers 5
    MinSpareServers 5
    MaxSpareServers 10
    MaxRequestWorkers 60
    ServerLimit 60
    MaxConnectionsPerChild 1000
</IfModule>

提示： MaxConnectionsPerChild 1000 是关键。它表示每个子进程处理 1000 个请求后自动重启，防止 PHP 内存泄漏累积。Roundcube 的 session 数据、缓存对象如果长期驻留，会导致单个进程内存从 25MB 涨到 120MB， MaxConnectionsPerChild 就是你的“内存清道夫”。

3.3 Roundcube 安装包的“手工解压哲学”：为什么不用 apt install roundcube

Ubuntu 16.04 仓库里的 roundcube-core 包版本是 1.1.5，而我们需要 1.3.15。更重要的是， apt install 会把文件散落到 /usr/share/roundcube/ 、 /etc/roundcube/ 、 /var/lib/roundcube/ 三个目录，而 Roundcube 的官方推荐部署方式是“单目录部署”：所有文件（代码、配置、临时文件）都在 /var/www/roundcube/ 下。这样做的好处是：备份时只需 tar -czf roundcube-backup.tgz /var/www/roundcube/ ；升级时只需下载新包， rsync -av --delete roundcube-1.3.15/ /var/www/roundcube/ ；调试时 ls -la /var/www/roundcube/ 一眼看清文件权限。执行：

cd /tmp
wget https://github.com/roundcube/roundcubemail/releases/download/1.3.15/roundcubemail-1.3.15-complete.tar.gz
tar -xzf roundcubemail-1.3.15-complete.tar.gz
sudo mv roundcubemail-1.3.15 /var/www/roundcube
sudo chown -R www-data:www-data /var/www/roundcube

注意 chown 必须递归，因为 Roundcube 的 temp/ 和 logs/ 目录需要 www-data 写入权限。如果只改顶层目录，安装向导会卡在“Checking temp directory... FAILED”。

3.4 数据库初始化：MySQL 5.7 的严格模式陷阱

Roundcube 需要 MySQL 数据库存储用户设置、地址簿、会话等。Ubuntu 16.04 自带 MySQL 5.7，它默认启用 STRICT_TRANS_TABLES 模式，这会导致 Roundcube 的 SQL 脚本执行失败。例如，Roundcube 的 SQL/mysql.initial.sql 中有一行：

CREATE TABLE `users` (
  `user_id` int(10) UNSIGNED NOT NULL AUTO_INCREMENT,
  `username` varchar(128) NOT NULL,
  `mail_host` varchar(128) NOT NULL,
  `created` datetime NOT NULL DEFAULT '1000-01-01 00:00:00',
  ...
);

MySQL 5.7 认为 '1000-01-01 00:00:00' 是非法日期（早于 1001 年），会报错 Invalid default value for 'created' 。解决方法不是改 Roundcube 源码，而是临时关闭严格模式：

sudo mysql -u root -p -e "SET GLOBAL sql_mode=(SELECT REPLACE(@@sql_mode,'STRICT_TRANS_TABLES',''));" 

然后创建数据库和用户：

sudo mysql -u root -p -e "CREATE DATABASE roundcube DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
sudo mysql -u root -p -e "GRANT ALL PRIVILEGES ON roundcube.* TO 'roundcube'@'localhost' IDENTIFIED BY 'your_strong_password';"
sudo mysql -u root -p -e "FLUSH PRIVILEGES;"

注意： utf8mb4 是必须的。 utf8 在 MySQL 5.7 中实际是 utf8mb3 ，不支持 emoji 和部分生僻汉字。Roundcube 的地址簿字段（如 name ）如果存入 👨‍💻 ， utf8 会截断成乱码，而 utf8mb4 完全兼容。

3.5 Roundcube 安装向导的“三关生死线”：绕过图形化向导的纯命令行初始化

Roundcube 提供 /installer/ 图形向导，但它在 Ubuntu 16.04 上有三个致命缺陷：第一，它会错误检测 php-intl 扩展（即使已安装，仍显示 NOT FOUND ）；第二，它生成的 config.inc.php 中 des_key 是硬编码的 rcmail ，极不安全；第三，它无法正确设置 db_dsnw 的 DSN 字符串格式。因此，我们跳过向导，手工初始化：

cd /var/www/roundcube
sudo cp config/config.inc.php.sample config/config.inc.php
sudo nano config/config.inc.php

重点修改以下五处：

1. config['db_dsnw'] = 'mysql://roundcube:your_strong_password@localhost/roundcube?charset=utf8mb4';

   注意： ?charset=utf8mb4 必须显式添加，否则 Roundcube 会用 latin1 连接，中文存入数据库后变成 æ–‡ 。

2. config['default_host'] = 'ssl://localhost';

   不是 tls:// ，不是 localhost ，必须是 ssl:// 。Dovecot 默认的 ssl = required 配置要求 IMAPS（端口 993）， ssl:// 会自动走 993 端口。

3. config['smtp_server'] = 'tls://localhost';

   SMTPS（端口 465）和 STARTTLS（端口 587）都支持 tls:// 前缀，但 Dovecot 的 submission 服务默认监听 587，所以这里用 tls:// 。

4. config['des_key'] = 'a_32_character_random_string_here_1234567890ab';

   生成方法： openssl rand -base64 24 | tr -d '\n' ，复制结果粘贴。这是加密 session 和密码的密钥，绝不能用默认值。

5. config['plugins'] = array('archive', 'zipdownload', 'managesieve');

   先启用这三个最实用插件。 managesieve 是邮件规则管理， zipdownload 支持批量下载附件， archive 一键归档邮件。

3.6 SSL 证书的“零成本落地”：用 Certbot 为 Roundcube 域名签发有效证书

Roundcube 必须运行在 HTTPS 下，否则现代浏览器会阻止混合内容（如加载 http:// 的头像）。Ubuntu 16.04 的 certbot 版本较老（0.19.0），但足够用。假设你的域名是 webmail.example.com ，且 DNS 已解析到这台服务器：

sudo apt install python-certbot-apache
sudo certbot --apache -d webmail.example.com

Certbot 会自动修改 Apache 的虚拟主机配置，添加 SSLCertificateFile 和 SSLCertificateKeyFile 指令，并重定向 HTTP 到 HTTPS。但有一个坑：Certbot 生成的证书链文件（ fullchain.pem ）在 Ubuntu 16.04 的 Apache 2.4.18 中需要显式指定 SSLCACertificateFile ，否则 iOS 设备访问会提示“证书不可信”。手动编辑：

sudo nano /etc/apache2/sites-enabled/000-default-le-ssl.conf

在 <VirtualHost *:443> 块内添加：

SSLCACertificateFile /etc/letsencrypt/live/webmail.example.com/chain.pem

然后重启： sudo systemctl reload apache2 。此时访问 https://webmail.example.com ，浏览器地址栏应显示绿色锁图标，点击可查看证书有效期为 90 天。

3.7 Dovecot 配置的“最小化授权”：让 Roundcube 只能干它该干的事

Roundcube 连接 Dovecot 时，不应使用管理员账号（如 admin@example.com ），而应为它创建专用的、权限受限的系统用户。在 Dovecot 的 /etc/dovecot/conf.d/10-auth.conf 中，确保：

!include auth-system.conf.ext

然后编辑 /etc/dovecot/conf.d/auth-system.conf.ext ，取消注释 #passdb { 块，并修改为：

passdb {
  driver = pam
}
userdb {
  driver = passwd
}

这表示 Dovecot 使用 Linux 系统用户数据库认证。接着创建一个名为 roundcube 的系统用户，但禁止其登录 shell：

sudo useradd -r -s /bin/false roundcube

现在，Roundcube 的 config.inc.php 中 default_host 可以安全地设为 ssl://localhost ，它将以 roundcube 用户身份连接 Dovecot，而 roundcube 用户没有任何 shell 权限，无法执行 ls /etc/shadow 这类命令。这是纵深防御的关键一环：即使 Roundcube 的 PHP 代码被攻破，攻击者也只能以 roundcube 用户身份访问邮件，无法提权到系统层。

3.8 Roundcube 日志的“主动监控术”：三行命令定位 90% 的登录失败

Roundcube 的日志默认写入 /var/www/roundcube/logs/errors ，但这个文件权限是 600 ，只有 www-data 可读。运维时，你需要实时监控它。执行：

sudo tail -f /var/www/roundcube/logs/errors | grep -E "(LOGIN|IMAP|DB|PHP)"

当用户报告“登录失败”时，这条命令会立即输出类似：

[12-Oct-2023 14:22:33 +0000]: <abc123> IMAP Error: Login failed for user@example.com from 192.168.1.100. Authentication failed.
[12-Oct-2023 14:22:35 +0000]: <abc123> DB Error: _doQuery: [Error message: Could not execute query] [Last executed query: PREPARE stmt FROM 'SELECT * FROM users WHERE username = ? AND mail_host = ?'] [Native code: 1146] [Native message: Table 'roundcube.users' doesn't exist]

第一行告诉你 IMAP 认证失败，可能是密码错或 Dovecot 服务没启；第二行直接暴露数据库表不存在，说明初始化脚本没跑。这种“日志驱动调试法”，比盲目重启服务高效十倍。记住：Roundcube 的日志级别在 config/config.inc.php 中由 config['log_level'] = 4; 控制， 4 表示记录所有错误， 1 表示只记录严重错误，生产环境建议保持 4 。

3.9 Apache 虚拟主机的“精准路由”：让 Roundcube 成为默认 Web 入口

为了让用户访问 https://webmail.example.com 就直接进入 Roundcube，而不是看到 Apache 默认页，需要配置虚拟主机。创建 /etc/apache2/sites-available/roundcube.conf ：

<IfModule mod_ssl.c>
<VirtualHost *:443>
    ServerAdmin webmaster@localhost
    ServerName webmail.example.com
    DocumentRoot /var/www/roundcube

    <Directory /var/www/roundcube>
        Options FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>

    ErrorLog ${APACHE_LOG_DIR}/roundcube_error.log
    CustomLog ${APACHE_LOG_DIR}/roundcube_access.log combined

    SSLEngine on
    SSLCertificateFile /etc/letsencrypt/live/webmail.example.com/cert.pem
    SSLCertificateKeyFile /etc/letsencrypt/live/webmail.example.com/privkey.pem
    SSLCertificateChainFile /etc/letsencrypt/live/webmail.example.com/chain.pem
</VirtualHost>
</IfModule>

启用并禁用默认站点：

sudo a2ensite roundcube.conf
sudo a2dissite 000-default.conf
sudo systemctl reload apache2

注意： AllowOverride All 是必须的。Roundcube 的 .htaccess 文件里有 RewriteRule 重写规则，用于美化 URL（如 /mail/?_task=mail&_action=show 显示为 /mail/ ），如果设为 None ，所有链接都会 404。

3.10 Roundcube 插件的“渐进式启用”：从 password 插件看数据库权限设计

password 插件允许用户在 Web 界面修改邮箱密码，但它需要额外的 MySQL 权限。Roundcube 主库用户 roundcube 只有 SELECT,INSERT,UPDATE,DELETE 权限，而 password 插件需要 UPDATE 权限到 users 表的 password 字段，以及对 password_history 表的 INSERT 权限。安全做法是：不给 roundcube 用户 ALTER 权限，而是创建一个专用的 password_plugin 用户：

sudo mysql -u root -p -e "CREATE USER 'password_plugin'@'localhost' IDENTIFIED BY 'strong_pass_for_plugin';"
sudo mysql -u root -p -e "GRANT UPDATE(password) ON roundcube.users TO 'password_plugin'@'localhost';"
sudo mysql -u root -p -e "GRANT INSERT ON roundcube.password_history TO 'password_plugin'@'localhost';"
sudo mysql -u root -p -e "FLUSH PRIVILEGES;"

然后在 config/config.inc.php 中配置：

$config['password_db_dsn'] = 'mysql://password_plugin:strong_pass_for_plugin@localhost/roundcube';

这样，即使 password 插件存在 SQL 注入漏洞，攻击者也只能修改 password 字段，无法 DROP TABLE users 。这是典型的“最小权限原则”实践。

3.11 PHP 配置的“隐形调优”： upload_max_filesize 与邮件附件的博弈

Roundcube 默认允许上传 2MB 附件，但企业用户常需发送 10MB 的 PDF 报告。修改 PHP 配置需同时调整三个参数：

sudo nano /etc/php/7.0/apache2/php.ini

找到并修改：

upload_max_filesize = 16M
post_max_size = 16M
max_execution_time = 300

post_max_size 必须 ≥ upload_max_filesize ，否则大文件上传会直接 404； max_execution_time = 300 （5 分钟）是必须的，因为 10MB 文件上传到慢速网络（如 1Mbps）需要约 80 秒，PHP 默认 30 秒超时会中断上传。改完后重启 Apache： sudo systemctl restart apache2 。验证是否生效：创建 /var/www/roundcube/test-upload.php ，内容为 <?php phpinfo(); ?> ，访问 https://webmail.example.com/test-upload.php ，搜索 upload_max_filesize ，确认值为 16M 。

3.12 最终健康检查清单：十二项必验，缺一不可

在交付给用户前，逐项执行以下检查，确保 Roundcube 真正可用：

1. HTTPS 可达性 ：用 curl -I https://webmail.example.com ，返回 HTTP/1.1 200 OK 且 Strict-Transport-Security 头存在。
2. PHP 扩展完整性 ： php -m | grep -E "(mbstring|intl|xml|zip|gd)" ，六项必须全部列出。
3. 数据库连接 ： sudo -u www-data php -r "new PDO('mysql:host=localhost;dbname=roundcube;charset=utf8mb4', 'roundcube', 'your_pass'); echo 'OK\n';"
4. IMAP 连通性 ： echo "a login user@example.com password" | openssl s_client -connect localhost:993 -quiet 2>/dev/null | grep "a OK"
5. SMTP 连通性 ： echo -e "HELO localhost\r\nQUIT\r\n" | openssl s_client -connect localhost:587 -starttls smtp -quiet 2>/dev/null | grep "220 "
6. Roundcube 配置语法 ： sudo -u www-data php -l /var/www/roundcube/config/config.inc.php
7. 日志目录可写 ： sudo -u www-data touch /var/www/roundcube/logs/test && sudo rm /var/www/roundcube/logs/test
8. 临时目录可写 ： sudo -u www-data touch /var/www/roundcube/temp/test && sudo rm /var/www/roundcube/temp/test
9. Apache 重写生效 ：访问 https://webmail.example.com/mail/ ，应重定向到 https://webmail.example.com/ （首页），而非 404。
10. SSL 证书有效性 ：用 Chrome 访问，点击地址栏锁图标，确认“有效期至 XXXX 年 XX 月 XX 日”。
11. 中文邮件测试 ：用 Thunderbird 发一封主题为“测试中文”的邮件，登录 Roundcube 查看是否正常显示。
12. 附件上传测试 ：上传一个 5MB 的 ZIP 文件，确认能成功发送给另一个邮箱。

实操心得：我曾在一个客户现场，第 11 项失败，排查发现是 Dovecot 的 mail_location 配置为 maildir:~/Maildir:LAYOUT=fs ，而 LAYOUT=fs 不支持 UTF-8 用户名，导致中文邮箱名 张三@example.com 的邮件被存到 zhangsan@example.com 目录下。解决方案是改 LAYOUT=maildir++ ，这是 Dovecot 2.2+ 的推荐布局。

4. 实操过程与核心环节实现：从零开始的完整部署流水线

4.1 环境初始化：15 分钟完成系统加固与基础服务安装

我们从一台纯净的 Ubuntu 16.04 Server（minimal install）开始。首先更新系统并安装基础工具：

sudo apt update && sudo apt upgrade -y
sudo apt install -y vim curl wget gnupg2 software-properties-common

然后安装 Apache 和 PHP 7.0 栈：

sudo apt install -y apache2 apache2-utils
sudo apt install -y php7.0 php7.0-cli php7.0-common php7.0-mbstring php7.0-intl php7.0-xml php7.0-zip php7.0-gd php7.0-mysql

验证 PHP 安装：

php -v  # 输出应为 PHP 7.0.33-0ubuntu0.16.04.16
php -m | grep -E "(mbstring|mysql)"  # 应显示 mbstring, mysqlnd

安装 MySQL：

sudo apt install -y mysql-server mysql-client
sudo mysql_secure_installation  # 按提示设置 root 密码，移除匿名用户，禁用远程 root 登录

启动并启用服务：

sudo systemctl enable apache2
sudo systemctl enable mysql
sudo systemctl start apache2
sudo systemctl start mysql

此时，访问 http://your_server_ip ，应看到 Apache 的 “It works!” 页面。这是整个部署的基石，如果这一步失败，后续所有步骤都无意义。

4.2 Roundcube 核心文件部署：解压、权限、配置三步到位

下载并解压 Roundcube 1.3.15：

cd /tmp
wget https://github.com/roundcube/roundcubemail/releases/download/1.3.15/roundcubemail-1.3.15-complete.tar.gz
tar -xzf roundcubemail-1.3.15-complete.tar.gz
sudo mv roundcubemail-1.3.15 /var/www/roundcube

设置所有权和权限：

sudo chown -R www-data:www-data /var/www/roundcube
sudo find /var/www/roundcube -type d -exec chmod 755 {} \;
sudo find /var/www/roundcube -type f -exec chmod 644 {} \;
sudo chmod 755 /var/www/roundcube/temp /var/www/roundcube/logs
sudo chmod 644 /var/www/roundcube/config/*.sample

注意： chmod 644 对配置文件是必须的。如果设为 600 ，Apache