服务器上跑起了 Postfix 和 Dovecot,邮件能收发,但对不习惯配置客户端的同事来说还是不够友好:手机 Outlook 设置一堆服务器地址、端口、加密方式,稍有不慎就连不上。这时候一套 Webmail 就显出价值了——打开浏览器输账号密码就能收发,和用网页版邮箱一样简单。Roundcube 是自建 Webmail 里最成熟的选择之一,功能完整、界面清爽、插件生态丰富。
这篇文章从零带你把 Roundcube 装起来:先讲清楚它的架构和前置依赖,再一步步走完下载、建库、配置 Web 服务器、填写 config.inc.php、对接 Dovecot 的全过程,最后给出安全加固和常见坑。命令区分 RHEL/CentOS/Rocky 与 Debian/Ubuntu 两套发行版,配置路径都标注清楚。
Roundcube 本身不存邮件,也不做认证,它只是"前端壳子":邮件存在 Dovecot 的 Maildir 里,认证由 Dovecot 负责,Roundcube 通过 IMAP 连接 Dovecot 读写邮件,会话和联系人等少量数据存在自己的数据库里。理解这一点,配置时就不会把问题搞混。下面开始动手。
一、架构与前置条件
Roundcube 是 PHP 应用,需要 Web 服务器(Nginx 或 Apache)、PHP 运行环境、一个数据库(MySQL/MariaDB 或 PostgreSQL)。它连接 Dovecot 用的是 IMAP 和 SMTP。
| 组件 | 作用 | 推荐版本量级(经验值) |
|---|---|---|
| Web 服务器 | 提供 HTTP 访问 | Nginx 1.20+ 或 Apache 2.4+ |
| PHP | 运行 Roundcube 代码 | PHP 7.4 及以上,8.x 更佳 |
| 数据库 | 存会话、联系人、设置 | MariaDB 10.5+ 或 MySQL 8.0+ |
| Dovecot | IMAP 收信 + SMTP 认证 | 与 Postfix 配套 |
| Postfix | SMTP 发信 | 与 Dovecot 配套 |
资源量级参考:几百人的中小团队,2 核 4GB 的机器足以承载 Webmail 加邮件服务本体;纯 Webmail 站点内存占用主要看并发会话数,空闲时 PHP-FPM 常驻进程通常占用一两百 MB。
PHP 需要以下扩展,缺一不可,很多"白屏"故障都是扩展没装全:
# 需要的扩展:pdo、pdo_mysql、mbstring、intl、xml、gd、zip、curl、json、
# openssl、fileinfo,另外 IMAP 支持用 php-imap 或新版 PHP 的 imap 扩展
# RHEL/CentOS/Rocky(PHP 建议用 Remi 源装 8.x,这里以系统自带包示意)
dnf install -y nginx php php-fpm php-mysqlnd php-mbstring php-intl \
php-xml php-gd php-zip php-curl php-json php-opcache php-imap php-pear
# Debian 12 / Ubuntu 22.04+
apt install -y nginx php-fpm php-mysql php-mbstring php-intl \
php-xml php-gd php-zip php-curl php-imap php-cli
二、下载与解压
从官网获取最新稳定版压缩包(不要用来源不明的二次打包版),解压到 Web 根目录。
# 以 nginx 默认站点目录为例 /var/www
cd /var/www
# 下载官方发布的 tar.gz(版本号以官网为准,这里用占位)
# wget https://github.com/roundcube/roundcubemail/releases/download/x.y.z/roundcubemail-x.y.z-complete.tar.gz
tar -xf roundcubemail-*.tar.gz
mv roundcubemail-* /var/www/roundcube
也可以直接用发行版仓库安装(版本通常偏旧,适合求稳的场景):
# Debian/Ubuntu
apt install -y roundcube roundcube-mysql
# RHEL 系在 EPEL 有 roundcubemail 包
dnf install -y epel-release && dnf install -y roundcubemail
仓库版会自动生成配置目录(通常在 /etc/roundcube/),与手动解压的路径不同,配置时注意区分。
三、创建数据库
Roundcube 需要一个数据库存自己的表,和邮件数据无关。
# 登录数据库
mysql -u root -p
# 建库建用户(按需改密码,密码用强口令)
CREATE DATABASE roundcube CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
CREATE USER 'roundcube'@'localhost' IDENTIFIED BY 'StrongPass_ChangeMe';
GRANT ALL PRIVILEGES ON roundcube.* TO 'roundcube'@'localhost';
FLUSH PRIVILEGES;
EXIT;
然后导入初始化表结构,脚本在 SQL/ 目录下:
cd /var/www/roundcube
mysql -u roundcube -p roundcube < SQL/mysql.initial.sql
# PostgreSQL 用 SQL/postgres.initial.sql
如果这一步报"表已存在"或字符集错误,通常是数据库字符集不是 utf8mb4,重建即可。
四、配置 Web 服务器
Nginx 方式
server {
listen 443 ssl http2;
server_name mail.example.com;
ssl_certificate /etc/ssl/certs/mail.example.com.crt;
ssl_certificate_key /etc/ssl/private/mail.example.com.key;
root /var/www/roundcube;
index index.php;
# 禁止直接访问敏感目录
location ~ ^/(config|temp|logs|SQL)/ {
deny all;
}
location / {
try_files $uri $uri/ /index.php$is_args$args;
}
location ~ \.php$ {
include fastcgi_params;
fastcgi_pass unix:/run/php/php8.1-fpm.sock; # 路径按实际 PHP 版本调整
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
}
client_max_body_size 32m; # 允许的最大附件上传,需与邮件大小上限配合
}
Apache 方式
ServerName mail.example.com
DocumentRoot /var/www/roundcube
SSLEngine on
SSLCertificateFile /etc/ssl/certs/mail.example.com.crt
SSLCertificateKeyFile /etc/ssl/private/mail.example.com.key
Options -Indexes
AllowOverride All
Require all granted
Require all denied
Roundcube 解压包自带 .htaccess,Apache 下 AllowOverride All 会让它生效,能自动保护 config 等目录。Nginx 不吃 .htaccess,必须像上面那样手动写 deny all。
五、配置 config.inc.php
主配置文件是 config/config.inc.php(仓库安装版可能在 /etc/roundcube/)。首次安装从模板复制:
cd /var/www/roundcube/config
cp config.inc.php.sample config.inc.php
关键配置项:
生成随机 des_key 用:
openssl rand -base64 24
配置完成后,注意 temp 和 logs 目录必须对 Web 用户可写,否则登录会报错:
# 属主按 Web 服务器用户调整:Nginx 常见 www-data(Debian)或 nginx(RHEL)
chown -R www-data:www-data /var/www/roundcube/temp /var/www/roundcube/logs
chmod 775 /var/www/roundcube/temp /var/www/roundcube/logs
# RHEL 系 Selinux 开启时还要放行
chcon -Rv --type=httpd_sys_rw_content_t /var/www/roundcube/temp /var/www/roundcube/logs
六、对接 Dovecot 与验证
Roundcube 通过 IMAP 连 Dovecot,所以 Dovecot 必须允许来自 Roundcube 所在主机的 IMAP 连接,且支持 SSL。若 Roundcube 和 Dovecot 在同一台机器,用 ssl://mail.example.com:993 即可;证书的域名要和 mail.example.com 匹配,否则 PHP 会拒绝连接。
发信走 Postfix 的 587 提交端口,要求 SASL 认证。Roundcube 把登录用户的账号密码透传给 Postfix,所以用户能在 Webmail 里登录,就能发信,无需额外配置。
启动并访问:
systemctl enable --now nginx php-fpm
systemctl reload nginx
# 检查配置是否有明显错误
php -l /var/www/roundcube/config/config.inc.php
浏览器打开 https://mail.example.com/,用 Dovecot 里的邮箱账号登录。如果登录界面出不来(白屏或 500),先看 PHP 错误日志:
# Debian/Ubuntu
tail -n 50 /var/log/nginx/error.log
tail -n 50 /var/log/php*-fpm.log
# RHEL
tail -n 50 /var/log/nginx/error.log
journalctl -u php-fpm -n 50 --no-pager
七、安全加固要点
Webmail 直接暴露在公网,是重点攻击目标,加固不能省。
- 强制 HTTPS:所有明文 HTTP 请求 301 跳转到 HTTPS,登录会话不走明文。
- 保护 config 目录:Nginx 用
deny all,Apache 靠.htaccess,务必确认https://mail.example.com/config/config.inc.php返回 403 而不是下载到文件内容。 - 限制安装程序访问:安装完成后删除或禁用
installer/目录,防止被重新初始化。 - 部署防暴力破解:在 Web 服务器层或 Roundcube 插件层对登录失败次数做限制,避免被撞库。经验上前端加一层限速能挡住绝大部分暴力尝试。
- 及时更新:Webmail 是漏洞高发组件,订阅官方安全公告,有补丁尽快升级。
- 数据库最小权限:Roundcube 的库账号只授予
roundcube库的权限,不给全局权限。 - 错误信息不外泄:生产环境关闭 PHP 的
display_errors,把错误写进日志而非显示给用户。
风险提示:删除 installer/ 目录不可逆,删除前确认安装已完成、配置已生效。若不放心,可以先重命名为 installer.disabled,观察一段时间无异常后再彻底删除。回滚方式:保留一份解压包副本,需要重装时从副本恢复。
八、插件、备份与升级
Roundcube 的功能很大程度上靠插件扩展,安装包自带一批常用插件,位于 plugins/ 目录。启用插件只需在 config.inc.php 里把它们加进 plugins 数组。常用的有:管理邮件过滤规则的 managesieve、密码修改的 password、日历与任务的 calendar 和 tasklist、以及允许用户修改个人设置的扩展。启用后记得按插件的说明在 plugins/<名字>/config.inc.php 里做对应配置,并检查所需的 PHP 扩展是否齐全。
// config.inc.php 中启用插件
$config['plugins'] = ['archive', 'zipdownload', 'managesieve', 'password', 'markasjunk'];
Webmail 的数据要纳入备份:config/config.inc.php 含数据库凭据,属于敏感文件;Roundcube 自己的数据库(用户设置、联系人)需要定期导出。升级时先备份配置与数据库,再解压新版本覆盖程序文件,最后运行安装程序完成数据库结构升级。
# 备份配置与数据库
cp /var/www/roundcube/config/config.inc.php /root/roundcube-config-$(date +%F).bak
mysqldump -u root -p roundcube > /root/roundcube-$(date +%F).sql
# 升级:解压新版本后,访问 https://mail.example.com/installer/ 完成结构升级
# 升级完成后务必删除或禁用 installer 目录
九、性能与容量参考
以下是经验值,仅供参考,实际以你的并发量和硬件为准:
- Roundcube 是 PHP 应用,性能瓶颈通常在 PHP-FPM 进程数和 IMAP 连接数上,而非磁盘。
- 单个用户打开一封带大量附件的邮件时,IMAP 拉取的数据量可能达到数 MB,邮箱大的用户首屏加载会略慢。
client_max_body_size、upload_capacity、Postfix 的message_size_limit三处大小限制要协调一致,任何一处偏小都会导致大附件发送失败。- OPcache 对 PHP 应用提升明显,开启后响应时间通常有可感知的改善;并发量大时把
pm.max_children按内存余量适当上调。 - 会话存储建议放在数据库或 Redis 里,避免多台 Web 节点间的会话不一致。
- 若并发用户较多,建议把 Roundcube 独立部署到单独的 Web 节点,与邮件存储节点分离,通过负载均衡对外提供服务。
- 一个中小团队的部署,2 核 4GB 通常足够;用户数上千、附件平均体积较大时,优先扩内存并拆分离 Mail 存储节点。
常见问题
Q:登录后一直转圈或提示"无法连接 IMAP 服务器"。
先确认 Dovecot 的 IMAP 服务在监听(ss -lntp | grep 993),再确认 Roundcube 配置里的 imap_host 域名与证书域名一致。如果证书是自签的,PHP 会因校验失败拒绝连接,需要换成受信任证书或谨慎配置跳过校验(不推荐在生产用)。
Q:能收邮件但发不出去。
检查 smtp_host 是否指向 587 提交端口、是否用 tls:// 前缀、Postfix 的 SASL 认证是否正常。用 swaks 单独测一遍 587 端口认证,能快速定位是 Roundcube 配置问题还是 Postfix 的问题。
Q:上传附件报错或超过大小限制。
三处限制要同时放开:PHP 的 upload_max_filesize 与 post_max_size、Web 服务器的 client_max_body_size、以及 Roundcube 的 upload_capacity/max_message_size。三处都调大后重启 PHP-FPM 和 Web 服务。
Q:页面白屏,日志里没有明显错误。
多半是 PHP 扩展缺失。用 php -m 列出已加载扩展,对照第一节的清单检查 mbstring、intl、pdo_mysql、gd 等是否齐全。生产环境关闭了 display_errors,白屏时错误其实写在 PHP 日志里。
Q:能不能和 Postfix、Dovecot 装在同一台机器上?
可以,中小规模很常见。但要留意资源竞争,尤其在大附件高并发时,Web 进程和邮件进程会抢 CPU 与内存。规模上来后建议拆分。
总结
Roundcube 只是前端壳子,邮件存储靠 Dovecot、认证靠 Dovecot、发信靠 Postfix,配置前先理解这个分工,排障时就不会找错方向。
安装顺序是"依赖齐全 → 解压到 Web 根 → 建库导表 → 配 Web 服务器 → 填 config.inc.php → 对接 Dovecot 与 Postfix",其中 PHP 扩展缺失是白屏的头号原因。
config.inc.php 里 imap_host 和 smtp_host 是最关键的两项,前者指向 Dovecot 的 993,后者指向 Postfix 的 587,账号密码用 %u/%p 透传。
temp 和 logs 目录必须对 Web 用户可写,SELinux 开启时还要额外放行,这两点经常被漏掉导致登录失败。
安全加固不能省:强制 HTTPS、保护 config 目录、删除 installer、限速防爆破、及时打补丁;三处大小限制要协调一致,改配置前先备份,留好回滚路径。
企业QQ咨询




