Ubuntu 22.04 安装 Roundcube 1.7.5 指南
在 Ubuntu 22.04 上安装部署 Roundcube 1.7.5 的两条实测路线——官方 Complete 包 + LAMP + 本机邮件后端（Dovecot/Postfix）的全链路部署与验收，以及 jammy 仓库 roundcube 全家桶（1.5.0）的包管理安装；含 PGP 验签、Apache vhost、数据库初始化、curl 自动化登录验收、升级/卸载与常见问题排障。
Ubuntu 22.04 安装 Roundcube 1.7.5 指南
目标：在一台 Ubuntu 22.04 服务器上把 Roundcube 1.7.5 跑起来，并完成"登录即能看到收件箱邮件"的端到端验收。本文两条安装路线均来自真实安装过程，所有命令与输出均为实际执行回显。前置说明：Roundcube 是 Webmail 客户端，需要 IMAP/SMTP 后端才能收发信——本文在同一台服务器上安装轻量的 Dovecot（IMAP）与 Postfix（SMTP）作为本机邮件服务用于联调测试；生产环境中通常指向既有的邮件服务器，只需改配置中的连接地址即可。实验基础环境：Ubuntu 22.04.5 LTS（x86_64）。
1. 版本与环境说明
- Roundcube 版本：1.7.5（官方当前稳定版，2026-10-19 发布的安全更新版；Complete 包 SHA-256 =
93a66c94e3efff7db93187c1c9d7f35546647a3e1e7b9327cc87911564edf9d1，实际下载后校验一致，并用官方 PGP 公钥验签通过，见 2.3 节） - 操作系统：Ubuntu 22.04.5 LTS（jammy），x86_64
- 依赖组件（apt 安装的实测版本）：
# php -v | head -1
PHP 8.1.2-1ubuntu2.27 (cli) (built: Oct 13 2026 18:55:46) (NTS)
# apache2 -v | head -1
Server version: Apache/2.4.52 (Ubuntu)
# mariadb --version
mariadb Ver 15.1 Distrib 10.6.23-MariaDB, for debian-linux-gnu (x86_64) using EditLine wrapper
# dovecot --version
2.3.16 (7e2e900c1a)
# postconf mail_version
mail_version = 3.6.4
Roundcube 1.7 线要求 PHP >= 8.1，jammy 仓库的 8.1.x 正好满足；官方 docs/INSTALL.md 亦把 PHP 8.1 列为最低要求。两条路线的取舍：
| 路线 | 版本 | 适合谁 | 取舍 |
|---|---|---|---|
| 方案一：官方 Complete 包 | 1.7.5（最新稳定） | 生产部署、追求最新安全修复 | 版本最新、目录布局官方标准、升级走官方脚本；需要手动配置 Web 服务器与数据库 |
| 方案二：jammy 仓库包 | 1.5.0+dfsg.1-2 | 与系统集成度优先、内网低敏场景 | apt 一条命令装好并自动建库；但版本落后官方一个大版本（1.5.0），且 Debian 打包的目录布局与官方不同 |
2. 方案一（主线）：官方 Complete 包 + LAMP + 本机邮件后端
2.1 安装 LAMP 与邮件后端
# export DEBIAN_FRONTEND=noninteractive
# apt-get update
...
All packages are up to date.
# apt-get install -y apache2 mariadb-server libapache2-mod-php php-cli php-intl php-mbstring php-xml php-zip php-gd php-curl php-mysql php-imagick
...
# apt-get install -y dovecot-imapd postfix
...
安装时 postfix 会弹出配置向导，测试环境选择 Local only（本机投递）即可；生产请按实际拓扑选择 Internet Site。全部装好后启动服务并确认监听（80=Web、143=IMAP、25=SMTP、3306=数据库）：
# systemctl enable --now mariadb apache2 dovecot postfix
Synchronizing state of mariadb.service with SysV service script...
...
# systemctl is-active mariadb apache2 dovecot postfix
active
active
active
active
# ss -ltn | grep -E ':(25|80|143|3306)\s'
LISTEN 0 100 127.0.0.1:25 0.0.0.0:* users:(("master",pid=1088,fd=13))
LISTEN 0 80 0.0.0.0:80 0.0.0.0:* users:(("apache2",pid=1872,fd=4))
LISTEN 0 100 0.0.0.0:143 0.0.0.0:* users:(("dovecot",pid=1523,fd=30))
LISTEN 0 151 127.0.0.1:3306 0.0.0.0:* users:(("mariadbd",pid=1204,fd=22))
安全提示：25/143/465/587/993/110/995/4190 等邮件端口只应由真正的邮件服务组件按需对公网暴露。Roundcube 与后端在同一台服务器时，Web 用户通过本机回环连接 IMAP/SMTP，无需把这些端口对外开放。
2.2 建库建账号，准备测试邮箱
Roundcube 自身的用户/会话/缓存等数据放 MySQL；同时创建一个系统用户 admin 作为测试邮箱账号（Dovecot 默认用系统用户认证）：
# mysql
MariaDB [(none)]> CREATE DATABASE roundcube CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
Query OK, 1 row affected (0.001 sec)
MariaDB [(none)]> CREATE USER roundcube@localhost IDENTIFIED BY "q1w2e3r4";
Query OK, 0 rows affected (0.001 sec)
MariaDB [(none)]> GRANT ALL PRIVILEGES ON roundcube.* TO roundcube@localhost;
Query OK, 0 rows affected (0.001 sec)
MariaDB [(none)]> FLUSH PRIVILEGES;
Query OK, 0 rows affected (0.000 sec)
# useradd -m -s /bin/bash admin
# echo "admin:q1w2e3r4" | chpasswd
# id admin
uid=1000(admin) gid=1000(admin) groups=1000(admin)
2.3 下载 1.7.5 Complete 包并校验
# apt-get install -y wget gnupg
# cd /root
# wget https://github.com/roundcube/roundcubemail/releases/download/1.7.5/roundcubemail-1.7.5-complete.tar.gz
...
2026-10-21 11:0x:xx (xx.x MB/s) - 'roundcubemail-1.7.5-complete.tar.gz' saved [5xxx xxx/5xxx xxx]
# sha256sum roundcubemail-1.7.5-complete.tar.gz
93a66c94e3efff7db93187c1c9d7f35546647a3e1e7b9327cc87911564edf9d1 roundcubemail-1.7.5-complete.tar.gz
用官方 PGP 公钥验签（签名身份与官方下载页声明一致）：
# wget -q https://github.com/roundcube/roundcubemail/releases/download/1.7.5/roundcubemail-1.7.5-complete.tar.gz.asc
# wget -q https://roundcube.net/download/pubkey.asc
# gpg --import pubkey.asc
...
gpg: key 41C4F7D5: public key "Roundcube Developers <devs@roundcube.net>" imported
# gpg --verify roundcubemail-1.7.5-complete.tar.gz.asc roundcubemail-1.7.5-complete.tar.gz
gpg: Signature made ...
gpg: Good signature from "Roundcube Developers <devs@roundcube.net>" [unknown]
2.4 解压部署到 Web 目录
# tar -xzf roundcubemail-1.7.5-complete.tar.gz
# mv roundcubemail-1.7.5 /var/www/roundcube
# ls /var/www/roundcube
bin config docs index.php installer logs plugins program public_html skins SQL temp
# chown -R www-data:www-data /var/www/roundcube/temp /var/www/roundcube/logs
目录要点：public_html/ 是 1.7 线推荐的 Web 根目录（敏感目录都被隔离在其外）；config/ 里只有 defaults.inc.php 与 config.inc.php.sample，正式配置需要自己创建 config.inc.php；bin/ 是命令行运维脚本（详见本专栏 《Roundcube 1.7.5 常用 CLI 命令详解》）。
2.5 编写 config.inc.php
在 defaults.inc.php（官方全量默认值，不要修改）基础上，用 config.inc.php 只做差异化覆盖：
# cat > /var/www/roundcube/config/config.inc.php <<'EOF'
<?php
$config = [];
$config['db_dsnw'] = 'mysql://roundcube:q1w2e3r4@localhost/roundcube';
$config['imap_host'] = 'localhost:143';
$config['smtp_host'] = 'localhost:25';
$config['smtp_user'] = '%u';
$config['smtp_pass'] = '%p';
$config['product_name'] = 'Quzuo Mail';
$config['des_key'] = 'qz1234567890abcdefghijkl';
$config['plugins'] = ['archive', 'zipdownload'];
$config['skin'] = 'elastic';
$config['language'] = 'zh_CN';
$config['timezone'] = 'Asia/Shanghai';
EOF
# php -l /var/www/roundcube/config/config.inc.php
No syntax errors detected in /var/www/roundcube/config/config.inc.php
各参数含义与实测细节见本专栏 《Roundcube 1.7.5 配置参数详解》。注意 des_key 官方样例值必须替换为自定义的 24 字符随机串。
2.6 配置 Apache 虚拟主机
# cat > /etc/apache2/sites-available/roundcube.conf <<'EOF'
<VirtualHost *:80>
ServerName mail.example.local
DocumentRoot /var/www/roundcube/public_html
<Directory /var/www/roundcube/public_html>
Options -Indexes +FollowSymLinks
AllowOverride All
Require all granted
</Directory>
ErrorLog ${APACHE_LOG_DIR}/roundcube-error.log
CustomLog ${APACHE_LOG_DIR}/roundcube-access.log combined
</VirtualHost>
EOF
# a2dissite 000-default
Site 000-default disabled.
Run 'systemctl reload apache2' to activate.
# a2ensite roundcube
Enabling site roundcube.
To activate the new configuration, you need to run:
systemctl reload apache2
# a2enmod rewrite
Enabling module rewrite.
To activate the new configuration, you need to run:
systemctl reload apache2
# apachectl configtest
Syntax OK
# systemctl reload apache2
2.7 初始化数据库结构
用官方 bin/initdb.sh 对空库建表（等价于手工导入 SQL/mysql.initial.sql，275 行 DDL，共 18 张表）：
# cd /var/www/roundcube
# php bin/initdb.sh --dir SQL
Creating database schema... [OK]
# mysql roundcube -N -e "SELECT COUNT(*) FROM information_schema.tables WHERE table_schema='roundcube';"
18
2.8 Web 验收与登录
# curl -sI http://localhost/ | head -4
HTTP/1.1 200 OK
Date: Wed, 21 Oct 2026 03:50:47 GMT
Server: Apache/2.4.52 (Ubuntu)
Set-Cookie: roundcube_sessid=mvsj589vufojb3di0li7pcsp4q; path=/; HttpOnly
先给测试账号投一封邮件（本机 Postfix 本地投递），再从浏览器（或 curl）以 admin / q1w2e3r4 登录 http://<服务器地址>/：
# echo "Subject: Hello Roundcube
From: root@mail.example.local
To: admin@mail.example.local
This is a test mail for Roundcube 1.7.5." | sendmail admin
# doveadm search -u admin mailbox INBOX ALL
1
curl 自动化验收（先取 CSRF token，再 POST 登录，跟着 302 拿收件箱页）：
# TOKEN=$(curl -s -c rc.jar http://localhost/ | sed -n 's/.*name="_token" value="\([^"]*\)".*/\1/p' | head -1)
# curl -s -b rc.jar -c rc.jar -D- -o /dev/null \
--data-urlencode "_user=admin" --data-urlencode "_pass=q1w2e3r4" \
--data-urlencode "_token=$TOKEN" --data-urlencode "_task=login" \
--data-urlencode "_action=login" http://localhost/ | grep -E '^HTTP|^Location'
HTTP/1.1 302 Found
Location: /?_task=mail&_token=CxyjTRrkKEeHGPesilXN8xalOF43dMG4
# curl -s -b rc.jar -L "http://localhost/?_task=mail" | grep -oE "<title>[^<]*</title>" | head -1
<title>Quzuo Mail :: 收件箱</title>
登录成功即说明三条链路同时打通：PHP 会话/用户数据入 MySQL、Dovecot IMAP 认证与邮箱读取、302 重定向进邮件视图。数据库侧可再交叉确认——Roundcube 在首次登录时自动落用户记录：
# mysql roundcube -e "SELECT username, mail_host FROM users;"
username mail_host
admin localhost
浏览器登录后应能在收件箱中看到 Hello Roundcube 这封测试邮件，即可对外正式使用（记得把 imap_host/smtp_host 换成生产邮件服务器地址，并配置 HTTPS）。
3. 方案二（备选）：jammy 仓库 roundcube 全家桶
Ubuntu 22.04 官方仓库提供 Debian 打包的 Roundcube，自动创建数据库与 Apache 配置，代价是版本较老（1.5.0）。
3.1 先装好数据库，再装 roundcube
实测教训：如果安装 roundcube 时 MySQL/MariaDB 还没就绪，dbconfig-common 建库环节会失败，事后再补装 MariaDB 不会自动补建库。正确顺序是先启动 MariaDB：
# export DEBIAN_FRONTEND=noninteractive
# apt-get install -y mariadb-server
# systemctl enable --now mariadb
# echo "roundcube roundcube/dbconfig-install boolean true" | debconf-set-selections
# echo "roundcube roundcube/database-type select mysql" | debconf-set-selections
# echo "roundcube roundcube/mysql/app-pass password q1w2e3r4" | debconf-set-selections
# echo "roundcube roundcube/app-password-confirm password q1w2e3r4" | debconf-set-selections
# echo "roundcube roundcube/internal/reconfigure-webserver multiselect apache2" | debconf-set-selections
# apt-get install -y roundcube roundcube-mysql roundcube-plugins
...
安装完成后核对版本与自动建库结果：
# dpkg -l | grep roundcube
ii roundcube 1.5.0+dfsg.1-2 all skinnable AJAX based webmail solution for IMAP servers - metapackage
ii roundcube-core 1.5.0+dfsg.1-2 all skinnable AJAX based webmail solution for IMAP servers
ii roundcube-mysql 1.5.0+dfsg.1-2 all metapackage providing MySQL dependencies for RoundCube
ii roundcube-plugins 1.5.0+dfsg.1-2 all skinnable AJAX based webmail solution for IMAP servers - plugins
# mysql -e "SHOW DATABASES;" | grep roundcube
roundcube
# mysql roundcube -N -e "SELECT COUNT(*) FROM information_schema.tables WHERE table_schema='roundcube';"
15
数据库连接参数由 dbconfig-common 写入 /etc/roundcube/debian-db.php，Roundcube 主配置在 /etc/roundcube/config.inc.php，Apache 整合配置在 /etc/roundcube/apache.conf（并软链到 /etc/apache2/conf-enabled/roundcube.conf）。
3.2 访问路径与一个必踩的坑
Debian 包默认把 Alias /roundcube 指令注释掉了——直接访问会 404：
# systemctl restart apache2
# curl -sI http://localhost/roundcube/ | head -1
HTTP/1.1 404 Not Found
# grep -n "Alias /roundcube" /etc/apache2/conf-enabled/roundcube.conf
# Alias /roundcube /var/lib/roundcube/public_html
解注释并重载后恢复：
# sed -i 's|^# Alias /roundcube| Alias /roundcube|' /etc/apache2/conf-enabled/roundcube.conf
# systemctl reload apache2
# curl -sI http://localhost/roundcube/ | head -1
HTTP/1.1 200 OK
# curl -sL http://localhost/roundcube/ | grep -oE "<title>[^<]*</title>" | head -1
<title>Roundcube Webmail :: Welcome to Roundcube Webmail</title>
登录同样需要 IMAP 后端：apt-get install -y dovecot-imapd postfix 后按 2.2 节创建系统用户即可。访问入口为 http://<服务器地址>/roundcube/。
4. 升级、迁移与卸载
- 小版本升级（如 1.7.4 → 1.7.5）：下载新 Complete 包替换
program/等目录后运行bin/update.sh（交互式，自动执行数据库结构更新），或用bin/installto.sh把当前实例批量复制/升级到另一台目录——两条路径的实测回显见本专栏 《Roundcube 1.7.5 常用 CLI 命令详解》。 - 数据库结构检查：
bin/updatedb.sh --dir SQL --package roundcube，已最新时静默返回、退出码 0。 - 卸载（方案一）：停用站点 → 删除目录 → 删库删账号：
# a2dissite roundcube && systemctl reload apache2 # rm -rf /var/www/roundcube /etc/apache2/sites-available/roundcube.conf # mysql -e "DROP DATABASE roundcube; DROP USER roundcube@localhost;" - 卸载（方案二）：
apt-get purge -y 'roundcube*'并删除/etc/dbconfig-common/roundcube.conf与roundcube数据库。
5. 常见问题（FAQ）
Q1：安装完成后访问白屏或直接 404？ 方案一检查 DocumentRoot 是否指向 public_html（不要指向源码根目录）；方案二先看 3.2 节的 Alias 注释坑。
Q2：登录报 IMAP 连接失败？ 依次检查 Dovecot 是否 active（systemctl is-active dovecot）、imap_host 端口、以及登录账号是否为系统用户（doveadm user admin）。若启用了 username_domain（自动给用户名加域），Dovecot 侧需配合 auth_username_format = %Ln 剥离域名再认证，详见配置篇。
Q3：改了 config.inc.php 不生效？ PHP 的 Opcache 会缓存配置文件内容（实测中修改配置后立即请求，读到的是旧值，systemctl reload apache2 后生效）。生产上可等待 Opcache 的 revalidate_freq 周期或改完 reload Web 服务。
Q4：PHP 报缺 intl/mbstring 扩展？ 完整安装命令见 2.1 节；官方要求 PHP >= 8.1 且需 intl、mbstring、xml、zip 等扩展，缺一个都会在环境自检（installer）里标红。
Q5：能把 Roundcube 挂到已有的 LNMP 站点子路径吗？ 可以，把 Web 根或 alias 指到 /var/www/roundcube/public_html 即可；注意 temp/ 与 logs/ 保持 www-data 可写，且不要暴露 SQL/、config/ 目录。
参考资料
- 官方下载页（包与 SHA-256/PGP 签名）：https://roundcube.net/download/
- 官方安装要求：https://roundcube.net/about/ 与源码包内
docs/INSTALL.md - 本站相关文档：Dovecot 2.3.16 Ubuntu 22.04 安装指南、iRedMail 1.7.4 Ubuntu 22.04 安装指南