Docker+Roundcube：团队Web邮箱免授权码部署方案

DockerRoundcubeWebmail

于 2026-10-02 06:30:55 修改

·本内容遵循CC 4.0 BY-SA版权协议

如果你也遇到过这种场景——几个人共用一个 QQ 邮箱，需要同时看邮件，轮流登录网页版，账号密码在群里传来传去，最后谁改了密码所有人都要重新同步一次——那这篇文章值得你看完。我最近用 Docker 把 Roundcube 部署成了一个小团队的共用 Web 邮箱入口，收信走 QQ 邮箱的 IMAP，发信切成 Resend 的 SMTP 通道，再配合自动登录把授权码和密钥全部收敛到后台，最终的效果是：打开浏览器就是邮箱界面，不需要任何人记忆授权码，发信也不再依赖 QQ 的 SMTP 授权。这篇文章就把整个部署过程、配置要点和踩坑记录完整梳理一遍。

1. 为什么我用 Roundcube + Docker 而不是直接用网页版邮箱

1.1 自建 Webmail 到底解决了什么问题

很多人第一反应是：QQ 邮箱网页版都做得那么完整了，为什么还要自建一个邮箱客户端？我一开始也是这么想的，但实际用下来有几个痛点绕不过去。

第一是多人共用的体验。团队里有一个统一的对外联系邮箱，比如 service@qq.com，需要三个人轮流处理邮件。如果用网页版，账号只能同时在线一个会话，而且腾讯的安全策略会在异地登录时频繁触发验证，直接把账号踢下线。用 Roundcube 自建一个入口后，每个人用自己的账号登录这个 Web 界面，IMAP 连接统一由 Roundcube 维持，相当于把"多用户访问同一邮箱"这件事从协议层解决了。

第二是界面和流程的定制空间。网页版邮箱能做什么功能，完全取决于腾讯想给你什么。而 Roundcube 是一套完整的开源 Webmail，插件机制成熟，像是自动归档、邮件加密、自定义过滤器、甚至后续想接一个 AI 摘要服务，都可以通过插件或 API 实现。数据界面在自己的服务器上，想怎么改都行。

第三是发信通道的独立性。QQ 邮箱的网页版发信只能走 QQ 的 SMTP 服务，有频率限制、有内容审计，而且第三方客户端接入必须使用授权码。我把发信切到 Resend 之后，发件通道和收件通道彻底解耦，日志、送达率、退信原因全部可见，这在维护对外服务邮箱时非常有用。

1.2 Roundcube、SnappyMail、RainLoop 怎么选

自建 Webmail 的开源方案不算少，但我最终选了 Roundcube。简单对比一下我当时考虑过的三个项目。

项目	技术栈	优点	缺点
Roundcube	PHP	插件生态最丰富、文档全、官方 Docker 镜像维护积极	界面偏传统，上一次大版本升级后功能才比较现代
SnappyMail	JavaScript	加载速度快、界面接近原生 App、资源占用低	插件机制不如 Roundcube 成熟
RainLoop	PHP	轻量、配置简单	社区活跃度明显下降，更新节奏慢

选 Roundcube 的核心原因是长期维护性。我要的是一个能稳定跑几年的服务，不是追求界面炫酷。Roundcube 背后的社区活跃了二十年，官方 Docker 镜像一直在更新，遇到问题很容易搜到解决方案。SnappyMail 我也搭过，确实快，但一旦需要深度定制，能查到的资料明显少一截。

1.3 "自动登录告别授权"到底是什么意思

标题里这几个词我需要先解释清楚，因为很容易被误解成"绕过腾讯安全机制"之类的东西。没有的事。

"告别授权"的本意是：在传统方案里，用户要在邮件客户端里输入自己的 QQ 邮箱授权码，授权码就是 16 位字母的客户端专用密码，很多人记不住、搞混、还会过期。在我这套部署里，授权码只出现在服务器端配置里，由管理员一次性写入，普通用户打开浏览器进入的是已经登录好的 Roundcube 界面，根本接触不到授权码这三个字。

发信侧则彻底和 QQ 授权码无关。Roundcube 的 SMTP 发信服务器指向 Resend，认证用的是 Resend 的 API Key，同样只在后台配置。对终端用户来说，整个邮箱的使用体验就是"打开页面就能收发邮件"，全程无感。

2. 环境准备与 docker-compose 编排：一个可复用的部署模板

2.1 前置环境：Docker 与 Docker Compose

部署前需要的环境很常规，一台能跑 Docker 的 Linux 服务器就行，2 核 4G 内存是舒服的底线，硬盘建议 SSD。我用的是 Ubuntu 22.04 服务器，Docker Engine 版本 24.0，Docker Compose v2。

如果你的服务器还没有 Docker，先执行这几步：

BASH

apt update

apt install -y docker.io docker-compose-plugin

systemctl enable --now docker

注意现在官方更推荐直接装 docker-ce 仓库版本，但 Ubuntu 自带的 docker.io 包在大多数场景下也够用。装完之后确认一下版本：

BASH

docker --version

docker compose version

如果 docker compose（带空格）这个命令不可用，说明 Compose 插件没装好，可以用 docker-compose（带横线）替代，但建议统一用新版的 Compose v2 语法。

2.2 服务编排：Roundcube + 数据库 + 反向代理

我直接给出完整的 docker-compose.yml，这份配置我在两套环境上各跑过一遍，属于比较稳妥的模板。

YAML

services:

roundcubemail:

image: roundcube/roundcubemail:1.6.7

container_name: roundcubemail

restart: unless-stopped

environment:

ROUNDCUBEMAIL_DB_TYPE: pgsql

ROUNDCUBEMAIL_DB_HOST: db

ROUNDCUBEMAIL_DB_USER: roundcube

ROUNDCUBEMAIL_DB_PASSWORD: change_this_db_pass

ROUNDCUBEMAIL_DB_NAME: roundcube

ROUNDCUBEMAIL_DEFAULT_HOST: ssl://imap.qq.com

ROUNDCUBEMAIL_DEFAULT_PORT: '993'

ROUNDCUBEMAIL_SMTP_SERVER: ssl://smtp.resend.com

ROUNDCUBEMAIL_SMTP_PORT: '465'

ROUNDCUBEMAIL_SMTP_USER: resend

ROUNDCUBEMAIL_SMTP_PASS: re_xxxxxxxxxxxx

ROUNDCUBEMAIL_DES_KEY: 32位随机字符串

TZ: Asia/Shanghai

volumes:

- roundcube_data:/var/www/html

ports:

- "127.0.0.1:8080:80"

depends_on:

db:

condition: service_healthy

db:

image: postgres:14-alpine

container_name: roundcube_db

restart: unless-stopped

environment:

POSTGRES_USER: roundcube

POSTGRES_PASSWORD: change_this_db_pass

POSTGRES_DB: roundcube

volumes:

- postgres_data:/var/lib/postgresql/data

healthcheck:

test: ["CMD-SHELL", "pg_isready -U roundcube -d roundcube"]

interval: 10s

timeout: 5s

retries: 5

volumes:

roundcube_data:

postgres_data:

有几个设计点需要说明。

第一，Roundcube 容器我映射到了 127.0.0.1:8080，而不是直接暴露到公网。因为后面还要加一层 Nginx 反向代理来做 HTTPS 和登录入口的访问控制，这样可以避免 Roundcube 自带的内置 Web 服务器直接面对公网。

第二，数据库用了 PostgreSQL 14。Roundcube 官方镜像支持 MySQL、PostgreSQL 和 SQLite，但 SQLite 只适合纯个人单用户玩，多人共用一定上独立数据库，否则会话并发一上来就会经常报锁超时。

第三，ROUNDCUBEMAIL_DES_KEY 是 Roundcube 用来加密数据库里部分敏感字段的密钥，随便生成一串 32 位随机字符就好，建议用 openssl rand -base64 32 生成。这个密钥一旦定了就别改，改了之后已存的会话和加密数据全部解不开。

官方镜像支持用环境变量注入大量配置，像上面这样直接写 IMAP、SMTP 参数确实很方便，但有一个坑：环境变量只能覆盖默认配置，无法表达数组和对象。如果后面要配多套 IMAP 主机、要设置插件参数，环境变量就不够用了。我的建议是环境变量只用来完成"能跑起来"这一步，真正的精细化配置还是挂载自定义 config 文件。

2.3 挂载自定义 config 文件

在 compose 文件同目录下创建一个 config.inc.php，挂载到容器内：

YAML

volumes:

- roundcube_data:/var/www/html

- ./config.inc.php:/var/www/html/config/config.inc.php

config.inc.php 内容大致如下：

PHP

<?php

$config['db_dsnw'] = 'pgsql://roundcube:change_this_db_pass@db/roundcube';

$config['default_host'] = 'ssl://imap.qq.com';

$config['default_port'] = 993;

$config['smtp_server'] = 'ssl://smtp.resend.com';

$config['smtp_port'] = 465;

$config['smtp_user'] = 'resend';

$config['smtp_pass'] = 're_xxxxxxxxxxxx';

$config['des_key'] = '你的32位随机字符串';

$config['plugins'] = [

'archive',

'zipdownload',

'autologon',

];

$config['upload_max_filesize'] = '20M';

初始化流程也很简单：compose 起来之后，先访问一次 http://服务器IP:8080/installer，按界面引导初始化数据库，然后把 installer 目录删掉。Roundcube 的初始化主要是建表，不涉及什么复杂步骤。初始化完成后，installer 目录建议立刻移除，避免留下配置接口暴露在网络上。

3. 收信侧：QQ 邮箱 IMAP 的正确接入姿势

3.1 QQ 邮箱的 IMAP 参数与授权码机制

QQ 邮箱的收信服务器参数是固定的：

参数	值
IMAP 服务器	imap.qq.com
SSL/TLS 端口	993
加密方式	SSL

要使用 IMAP 收信，前提是必须在 QQ 邮箱网页版里开启 IMAP 服务。路径是：设置 -> 账号 -> 开启 IMAP/SMTP 服务。开启时腾讯会要求你用手机扫码验证，验证通过后会给一个 16 位字母的授权码。

这个授权码就是 IMAP 登录时的密码，不是你的 QQ 登录密码。

腾讯为什么强制用授权码？因为它不想让第三方客户端拿到你密码的明文。授权码可以单独撤销，就算客户端那边泄露了，你只需要在网页版重新生成一个，QQ 登录密码完全不受影响。这种机制本身没问题，问题在于它对普通用户不友好——大部分人根本不知道"在邮件客户端里密码要填授权码"这件事，于是这一步就劝退了很多想接第三方客户端的人。

3.2 在 Roundcube 中配置 QQ 收信

有了授权码之后，配置就简单了。Roundcube 的 default_host 和 default_port 已经指向 IMAP，所以用户在登录页输入两个信息即可：

用户名：完整的 QQ 邮箱地址，比如 123456@qq.com
密码：16 位 IMAP 授权码

登录后 Roundcube 会通过 SSL 连接到 imap.qq.com 的 993 端口拉取邮件目录。QQ 邮箱的 IMAP 支持常规的文件夹列表，收件箱、已发送、草稿箱、垃圾邮件都会同步过来。

如果你希望用户登录时少打几个字，可以在 config.inc.php 里加一行：

PHP

$config['username_domain'] = 'qq.com';

这样用户只需要输入 123456，Roundcube 会自动补全 @qq.com 后缀。这个设置对内部团队使用很友好。

3.3 部分用户收信失败的原因

收信环节我遇到过几类报错，整理一下。

第一类：Authentication failed。最常见的原因是授权码填错，或者授权码在别处被重新生成过。QQ 邮箱每次重新生成授权码，旧授权码会立即失效。如果你有多台设备、多个客户端同时用同一个 QQ 邮箱，建议让它们统一使用同一个授权码，不要各生成各的。

第二类：连接超时。公司网络把 993 端口封了，或者服务器防火墙没放行出方向流量。可以用这个命令自查：

BASH

openssl s_client -connect imap.qq.com:993 -crlf

能进入 IMAP 的协议交互就说明网络通。

第三类：证书报错。容器里的 ca-certificates 太旧时，连接 imap.qq.com 会提示证书校验失败。更新一下就正常了：

BASH

docker exec roundcubemail apt update && docker exec roundcubemail apt install -y ca-certificates

第四类：腾讯侧的限制。同一个 QQ 邮箱如果被同时建立太多 IMAP 连接，腾讯会临时拒绝新连接。多人同时用同一个邮箱时，Roundcube 本身会做连接复用，但如果设置了特别短的长连接超时，还是可能触发限制。建议不要把 IMAP 的连接超时调得太短，默认的 120 秒左右比较合适。

4. 发信侧：Resend 作为 SMTP 发信通道的完整接入

4.1 为什么用 Resend 替代 QQ 的 SMTP 授权

收信用 QQ IMAP 是天经地义的，毕竟邮件就在那里。但发信这一路，我坚决没有用 QQ 的 SMTP，原因有三个。

首先是授权码的额外负担。QQ 的 SMTP 和 IMAP 虽然可以共用同一个授权码，但一旦配置了发信功能，这个授权码就同时暴露在 IMAP 和 SMTP 两条链路上，风险面扩大了一倍。而在我的方案里，用户根本不需要知道授权码，发信服务器又指向另一个服务商，相当于把 QQ 授权码的暴露面压缩到最小。

其次是发信量的限制。QQ 邮箱对 SMTP 发信有比较严格的频率控制，日常少量发信没问题，但如果这个邮箱会用来处理批量通知、给客户群发邮件，很容易触发限流，甚至被暂时冻结发信功能。

第三是运维侧的可观测性。Resend 提供完整的发送日志、退信原因分类、送达率统计，每封邮件发出去之后都能查到状态。QQ 的 SMTP 是一个黑盒，发出去之后没有日志，出了问题你只能猜。

需要特别说明：Resend 要求发件域名必须是你在后台验证过的自有域名，所以你发出去的邮件发件人地址不可能是 @qq.com。如果你需要发件人显示为 QQ 邮箱地址，那这条路走不通，只能用 QQ 自己的 SMTP。我的实际用法是：收件地址仍然是 QQ 邮箱，但对外发出的业务邮件统一使用自己购买的域名，比如 mail.example.com 作为发件域，语义明确、可管理性也高。

4.2 注册 Resend、验证域名、拿到 API Key

在 Resend 后台注册后，第一步是添加发件域名。添加之后，后台会给出一组 DNS 记录，包括 SPF、DKIM 这些 TXT 记录。去你的域名 DNS 服务商那边把记录加好，DKIM 记录对送达率影响极大，必须全部配上。

第二步是创建 API Key。在 API Keys 页面生成一个以 re_ 开头的密钥。Resend 的 API Key 用途不止 SMTP 认证，它还可以直接调 HTTP API 发信。我的场景里主要用它做 SMTP 认证，所以创建时选了 SMTP 这个权限范围，避免不必要的风险。

第三步是记录 SMTP 连接参数：

参数	值
SMTP 服务器	smtp.resend.com
SSL/TLS 端口	465
STARTTLS 端口	587
认证用户名	resend
认证密码	你的 API Key（re_ 开头）

关于认证字段有一点先提醒一下：Resend 的 SMTP 认证有时候因为控制台版本不同，要求会略有差异。多数场景下用户名填 resend、密码填 API Key 即可；也有老文档写的是用户名和密码都填 API Key。建议以你当前 Resend 控制台里面的说明为准，两种方式都花不了几分钟就能试出来。

4.3 Roundcube 的 SMTP 配置

我在 compose 文件里已经写好了环境变量的版本：

YAML

ROUNDCUBEMAIL_SMTP_SERVER: ssl://smtp.resend.com

ROUNDCUBEMAIL_SMTP_PORT: '465'

ROUNDCUBEMAIL_SMTP_USER: resend

ROUNDCUBEMAIL_SMTP_PASS: re_xxxxxxxxxxxx

如果是用 config.inc.php 挂载，则是：

PHP

$config['smtp_server'] = 'ssl://smtp.resend.com';

$config['smtp_port'] = 465;

$config['smtp_user'] = 'resend';

$config['smtp_pass'] = 're_xxxxxxxxxxxx';

这里有个细节：Roundcube 的 smtp_user 指的是发信时的认证身份。因为发信通道是 Resend，所以这个用户跟收信时的 QQ 邮箱用户没有任何关系。Roundcube 在发信时会用 SMTP AUTH 和 Resend 完成认证，认证通过后邮件就从 Resend 的服务器发往收件方。

如果你在测试阶段无所谓发件人地址，可以先用 Resend 的默认发送域名来验证链路通不通；正式使用一定要用验证过的自有域名，否则发出去基本全进垃圾箱。

4.4 SPF、DKIM 与发信到达率

很多自建邮箱最后死在送达率上，不是服务商的问题，而是域名信用不够。Resend 给了你配置 SPF 和 DKIM 的入口，但不会替你做。

SPF 记录告诉收件方"这个域名允许哪些服务器代发邮件"。DKIM 则是对邮件内容做数字签名，证明邮件在传输过程中没有被篡改。Resend 后台会给出具体需要添加的记录，通常是：

一条 SPF TXT 记录，内容类似 v=spf1 include:amazonses.com ~all
两三条 DKIM TXT 记录，主机名和值都在后台

DNS 生效有延迟，用 dig 命令可以随时确认记录是否生效：

BASH

dig TXT mail.example.com +short

实测下来，SPF 和 DKIM 都配置正常之后，发到 QQ 邮箱、163 邮箱、Gmail 的送达率差异很大。尤其是发给 QQ 邮箱用户时，如果域名从来没有过发信记录，第一封很可能直接被吞进垃圾箱。这不是配置错误，是域名信用需要慢慢积累。小批量试发、保持正常频率、不要突然大量发信，是唯一靠谱的加速方式。

5. 自动登录与免授权：把账号密码藏到后台

5.1 "自动登录"到底怎么落地

先说结论：Roundcube 本质是一个 IMAP 客户端，它要连接 QQ 的 IMAP 就必然需要拿到用户的身份凭证。所以"自动登录"不是让 Roundcube 凭空获取权限，而是把凭证从"用户每次输入"变成"系统后台代管"。我落地了两套方案，分别应对不同场景。

5.2 方案A：单用户预置登录，适合个人专用邮箱

如果你的 Roundcube 实例只服务一个 QQ 邮箱，比如个人专用邮箱，那最简单的方式是让 Roundcube 在用户访问时直接用后台配置好的账号和授权码发起登录。

具体做法是：在服务器的环境变量里设置好账号和授权码，然后写一个极简的登录代理层，用户在浏览器访问入口 URL 时，由代理层向 Roundcube 的登录接口发起一次带凭证的请求，拿到会话 Cookie 后透传给浏览器。相当于把"打开页面输入账号密码"这步固化成了服务器端的自动行为。

核心逻辑示意（PHP 伪代码风格）：

PHP

$user = getenv('QQ_IMAP_ACCOUNT');

$pass = getenv('QQ_IMAP_AUTH_CODE');

$postData = [

'_user' => $user,

'_pass' => $pass,

'_task' => 'login',

'_action' => 'login',

];

// 通过 cURL 向 Roundcube 登录接口提交，保存返回的 Cookie

// 然后把 Cookie 写入用户的浏览器会话

这个方式对用户来说体验是最好的：打开网址直接就是邮箱界面，完全感知不到凭证的存在。代价是它只适用于单邮箱场景，而且所有用户看到的是同一个邮箱的内容。多人同时使用时需要小心操作冲突，不建议这样搞。

更稳妥的做法是在这个代理层入口做一层白名单控制，比如只允许内网 IP 访问，或者加一个简单的访问口令。因为一旦入口泄露，任何人打开都会直接进入邮箱，凭证等于裸奔。

5.3 方案B：autologon 插件，适合已有统一认证的团队

如果团队里已经有了一套身份认证体系，比如公司门户、OA 系统，那用 Roundcube 官方生态里的 autologon 插件会更合理。

autologon 插件的思路是：由前置认证网关负责确认"这个用户是谁"，然后把身份信息通过 HTTP 头或服务器变量传给 Roundcube。Roundcube 发现用户已经通过认证，就从自己的 users 表里找到对应账号的 IMAP 凭证，直接建立会话。

开启方式就是在 config.inc.php 的 plugins 数组里加入：

PHP

$config['plugins'] = [

'archive',

'zipdownload',

'autologon',

];

前置网关要在认证通过后设置用户标识变量，Roundcube 就能识别。实际部署中，我用 Nginx 的 auth_request 模块配合一个简单的认证脚本，认证成功后在反向代理阶段注入用户标识，再转发给 Roundcube 容器。

这条路更适合 5 人以上的团队，因为每新增一个成员，管理员只需要在 Roundcube 后台数据库里预置一条账号记录，把该成员的 QQ 邮箱账号和授权码存好，不用再一对一教他配置客户端。

5.4 安全边界与建议

把凭证全部放后台托管，便利性上去了，安全性也必须跟上，否则等于把鸡蛋放进同一个篮子。我实践下来的几条底线：

授权码和 Resend API Key 只放在服务器端环境变量或配置文件中，绝不写入前端页面，也绝不通过 URL 传递。
API Key 创建时选择最小必要权限，SMTP 场景只给 SMTP 权限，不顺手开通完整的发送 API 权限。
自动登录入口必须做网络层或网关层访问控制，不要裸奔在公网。
授权码和 Key 定期轮换，换完更新容器环境变量并重启容器。
Roundcube 的 installer 目录部署后立刻删除。

6. 部署实测：常见报错、性能表现与调优心得

6.1 我踩过的几个坑

整套部署下来，最耗时的不是配置本身，而是环境细节。逐个说一下。

第一个坑是 Postfix 残留端口冲突。如果你的服务器之前装过邮件服务，80 和 25 端口可能被占用。Roundcube 用 8080 端口，问题不大，但 Resend 的 SMTP 走 465 端口，如果云厂商默认封了 465，发信就会一直超时。浙江、江苏一带的云服务器对 25 端口普遍封锁，465 一般没问题，但个别厂商会连 465 一起限制，遇到超时先确认端口通不通。

第二个坑是 PHP 上传大小限制。Roundcube 默认允许的附件大小通常是几 MB，我在 config 里一行 $config['upload_max_filesize'] = '20M'; 解决，但还需要同步调整容器内 PHP 的 upload_max_filesize 和 post_max_size 两个参数。如果你用的官方镜像，直接修改挂载的 php.ini，或者在 compose 里用环境变量覆盖。这个问题只在别人给你发大附件、然后你想转发时才会暴露，很容易被忽略。

第三个坑是数据库连接超时导致的"页面转圈"。PostgreSQL 默认空闲会话一段时间后会断开，Roundcube 连接池如果没处理好，用户操作时偶发卡顿。我最后是给 compose 里的 db 服务加了一条健康检查，并且在 Roundcube 侧把数据库连接超时调长，问题基本消失。

第四个坑是删除 installer 目录。Roundcube 镜像初始化完成后，installer 会留在容器里。如果这个实例暴露在公网上，installer 页面是可以被访问的。虽然它不会直接泄露密码，但会给攻击者提供一条探测路径。删除命令：

BASH

docker exec roundcubemail rm -rf /var/www/html/installer

每次镜像升级后，installer 会重新出现，升级后记得再删一次。

6.2 性能与资源表现

我用的是一台 2C4G 的轻量云服务器，同时跑 PostgreSQL 和 Roundcube 容器。空闲状态下内存占用约 600MB，其中 PostgreSQL 占大头。Roundcube 的 PHP 进程本身并不重，10 个以内用户同时在线，操作很流畅，没有任何可感知的延迟。邮件索引和拖拽附件、搜索这些操作，响应都在一两秒内。

如果用户量继续往上走，下一步应该把数据库和 Roundcube 分开部署，再引入 Memcached 做会话缓存，可以显著降低数据库压力。不过对于小团队来说，当前这套单机 Compose 方案已经足够稳定跑几年。

6.3 后续可以扩展的方向

这套架构的可扩展性其实不错。Roundcube 的插件系统支持得很完善，我目前日常在用的有：

archive 插件：一键归档，避免收件箱累积成山
zipdownload 插件：批量下载邮件附件，很适合团队里需要留存客户附件的场景
autologon 插件：把自动登录做进团队认证体系

后续如果想给这个邮箱入口加更多能力，比如自动分类、定期生成邮件摘要、把邮件归档到对象存储，Roundcube 的 API 和插件机制都能接上。Resend 的发送日志也可以单独拉出来做统计报表，看看每周邮件发送量和送达失败原因。

这套方案做完之后，我很确定一点：别被"授权码"三个字吓退，它只是腾讯在客户端接入场景下的专用密码形态。把它和发信通道拆开，再通过 Docker 把整个入口标准化，普通人也完全可以拥有一套顺手、可控、不用记密码的 Web 邮箱。