Docker 部署 Roundcube 邮箱：Resend 发信 + QQ 收信，自动登录告别授权码

type

Post

status

Published

date

Feb 12, 2026

slug

Roundcube 邮箱自动登录：Resend 发信 + QQ 收信，告别授权码

summary

Roundcube 邮箱自动登录：Resend 发信 + QQ 收信，告别授权码

前言

花了 3 天，终于和 AI 一起整完了个人邮箱的 Cloudflare 认证和自动登录。

演示视频

起因其实很简单：

发件（SMTP）和收件（IMAP）在我这是两套不同的服务。

收信用 Cloudflare 邮箱的 catch‑all 转发到 QQ，

发信则通过 Resend 平台，

这里还得感谢一下UP主@技术爬爬虾

正是刷到了他的几个视频，才把域名和邮箱的底层配通的：

1.【2024最新免费域名教程，可托管CF，零失败率，解决所有坑点。】

2.【如何低成本获得一个域名，托管Cloudflare免费DNS】

3.【白嫖Cloudflare无限多企业邮箱，可收发邮件】

不过爬爬虾那期邮箱视频教的是用 API 发信，我试下来还是觉得有点重。

后来发现 Resend 其实也提供 SMTP 服务，配置更简单——索性直接改用 SMTP 了。

省去了自己写代码调 API 的麻烦，配齐了整个个人邮箱。爽了一下子。

然后就被那个登录折腾了。

QQ 邮箱用的是「账号 + 授权码」，

授权码老长一串（其实也就16位，但我记不住就是记不住），又不能自定义。

记不住，也不想每次登录都复制粘贴一次。

于是干脆研究了一下：

给域名套上 Cloudflare Zero Trust 认证，

再让 AI 写了个自动登录页面。

部署完后，默认主页直接指向这个自动登录页——

认证通过 → 后台自动填表 → 跳进邮箱。

原来的登录页也没删，特意保留在 /index.php，

需要时仍可手动登录。

两全其美。

操作步骤

在开始之前，请确保你已经准备好了以下东西：

一个域名（已托管 Cloudflare）

~~Cloudflare 账户（废话）~~

Resend 账号

支持容器的运行环境（例如 Docker、Kubernetes、ClawCloud 等）

一个能收信的邮箱（如 QQ 邮箱）

至于域名怎么搞、Cloudflare 邮箱转发和 Resend 发信怎么配，那几个视频已经手把手教了，我这儿就不啰嗦啦。

1. 部署Roundcube

1.1 准备工作

在开始部署之前，你需要先拿到一个关键凭证：

🔑 邮箱密码或授权码

💡

不同邮箱有不同的验证方式，大部分主流邮箱在登录第三方客户端时，都需要使用“授权码”或“客户端专用密码”。例如：QQ、网易、Outlook、Gmail等

本教程将以QQ为例，其他邮箱可自行查找对应的获取方式。

少数邮箱支持直接使用密码登录。

📮 QQ 邮箱授权码获取步骤

在左侧导航栏点击 安全设置，然后找到 “生成授权码” 按钮

💡

如果之前未开启授权码功能，请按页面指引完成短信验证即可开启（如图二所示）

完成短信验证

点击“生成授权码”后，需短信验证。

微信扫码 → 自动发送 → 点击 “我已发送”

无法扫码？可手动发送或选其他方式

验证通过后，系统生成 16 位授权码，复制保存好——这就是后续登录的“密码”。

1.2 配置Docker Compose

首先，您需要创建一个目录来存放Roundcube的配置文件和Docker Compose文件。可以使用以下命令创建目录：

接下来，创建一个名为docker-compose.yml的文件，并在其中添加以下内容：

💡

关于 PHP 内存限制 PHP_MEMORY_LIMIT 控制着 PHP 脚本可用的最大内存。Roundcube 官方要求至少 16MB，但实际使用中，如果发送带附件的邮件或处理复杂邮件内容，建议调高。

如果你使用的是 ClawCloud 等有免费额度的容器平台，其最低要求可能是 64M，但推荐设为 128M（即本文示例值），以获得更好的兼容性。

如果你在自己服务器上部署，可根据需要设置为 128M、256M 甚至更高，只要确保不超出系统可用内存即可。

1.3 启动容器

在终端中，运行以下命令启动服务：

首次启动会拉取镜像，稍等片刻。运行成功后，可以用以下命令查看服务状态：

如果一切正常，你应该能看到 roundcube 容器状态为 Up。

1.4 验证 Roundcube

容器跑起来之后，先别急着高兴——得试试能不能真的收发邮件。

打开浏览器，访问你的 Roundcube 地址（比如 http://你的服务器IP:8080），你会看到这样的登录页面：

💡

如果遇到无法访问的情况：

如果你使用的是云服务器，请检查云平台的安全组是否放行了映射的端口（本例为 8080）。

如果你在本地部署，请先确认容器是否正常运行，或在服务器内执行 curl http://localhost:8080 测试

输入：

用户名：你的完整 QQ 邮箱地址（例如 495923517@qq.com）

密码：上一节生成的 16 位授权码（不是 QQ 密码！）

点击登录，如果能顺利进入收件箱，恭喜你，IMAP 配置没问题。

测试发信

点击页面上方的 “写邮件”，给自己常用的另一个邮箱（如 Gmail、Outlook 等）发一封测试邮件。稍等片刻，去那个邮箱查看是否收到。

如果能收到，说明 Resend SMTP 配置正确，发信通道也通了。

💡

当然，也可以直接发给用于登录的邮箱

至此，Roundcube 邮箱已经部署完成，你可以通过 QQ 邮箱和授权码正常登录使用了。

不过每次登录都要复制那串 16 位授权码还是有点烦——

接下来我们给它加一道 Cloudflare 认证，再配上自动登录页，彻底告别手动填码。

2. 配置Cloudflare Zero Trust认证

2.0 配置域名

在配置 Cloudflare Zero Trust 认证之前，你需要先让域名（如 mail.你的域名）能够正确访问到你的 Roundcube 服务。因为 Zero Trust 是基于域名来保护的，如果域名解析不到位，后续的步骤将无法执行。

2.0.1 配置dns记录

进入 Cloudflare，点击对应域名进入域名配置界面

点击左侧“DNS”，进入“记录”页面，点击”添加记录”

“类型”选择A，“名称”填写mail，“IPv4地址”填你服务器的地址，然后点击“保存”

⚠️

注意：本教程假设你的服务器拥有公网IPv4地址。如果你在本地虚拟机或家庭内网测试（无公网IP），需要自行配置内网穿透（如FRP、Cloudflare Tunnel）或使用IPv6，这部分请参考其他网络教程，本文不展开。

4. 验证域名解析

保存后等待1-2分钟让DNS生效。然后在浏览器中访问 http://mail.你的域名:8080，如果能正常显示Roundcube登录页，说明解析和端口都已就绪。

2.0.2 配置 Nginx（可选）

如果你不想在域名后加 :8080 访问，希望直接通过 http://mail.你的域名 打开邮箱，可以用 Nginx 反向代理将 80 端口的请求转发到本地的 8080 端口。

安装 Nginx

根据你的系统执行对应命令：

Debian/Ubuntu：sudo apt install nginx -y

CentOS/RHEL：sudo yum install nginx -y

启动并检查状态

（可选）设置开机自启：sudo systemctl enable nginx

3. 创建配置文件

新建 /etc/nginx/conf.d/mail.conf，内容如下（将域名替换为你的）：

4. 测试配置并重启

5. 验证

打开浏览器，访问 http://mail.你的域名，如果出现了邮箱登录页，则代表配置成功。

关于 Zero Trust 的入门，可以参考@技术爬爬虾的另一期视频：

【没有公网IP? 免费域名搭建cloudflare内网穿透，不限流量，不用绑卡支付】

⚠️

视频中提到的“跳过绑卡”技巧有弹幕反馈可能已失效，我自己因为之前已经配置过，无法验证，建议直接按 Cloudflare 的常规流程操作——如果遇到绑卡要求，按页面提示完成即可。

不过，视频的重点是 Tunnel内网穿透，没有涉及“访问策略”和“应用程序”的配置，而这正是我们需要的核心。所以下面我会直接给出关键步骤。

2.1 创建访问策略与应用（小号页面）

进入 Zero Trust 面板，展开左侧”访问控制”，进入”策略”，点击“添加策略”。

配置策略

基本信息

策略名称：Roundcube Mail
操作：Allow

添加规则

包括

选择器：Emails ending in
值：你的域名，例如:example.com

💡

你也可以使用 Emails 单独指定允许的邮箱地址，这里用 Emails ending in 只是我的习惯，按需选择即可。

点击页面底部的 “保存”，进入左侧“概述”。

切换到“概述”选型卡，点击“添加应用程序”

选择”自托管”

配置应用程序

基本信息

应用程序名称：输入一个易识别的名称，例如 Roundcube Mail。

公共主机名：

子域：mail
域：选择你绑定的主域名，例如：example.com

往下滑，找到“Access 策略”，点击“选择现有策略”（忘截图了，在编辑页面截的图）

选择刚刚创建的策略，点击“确认”

点击页面底部的 “下一步”，直至保存完成。

2.2 验证 Zero Trust 认证

配置完成后，我们需要验证 Zero Trust 是否已成功保护你的邮箱域名。

打开浏览器的无痕模式（避免缓存影响），访问 https://mail.你的域名 ，如果配置正确，页面应自动跳转到 Cloudflare 的登录页，如图：

输入允许的邮箱

在登录页输入你策略中允许的邮箱（如 xx@你的域名），然后点击“Send me a code”或通过配置的身份提供商登录。

完成认证

查收邮件中的验证码（或通过身份提供商授权），输入后即可完成认证。

认证成功后，页面如果自动跳转回 Roundcube 的登录页，则证明 Zero Trust 已经生效。

💡

如果你使用 Emails ending in 规则，任何以你域名结尾的邮箱均可登录；若使用 Emails 规则，则只有指定的邮箱才能通过。

3. 部署自动登录页面

3.1 原理简介

自动登录页面（auto_login.php）的核心逻辑如下：

检查 CF 认证状态：读取请求头中的 CF-Access-Jwt-Assertion，确认用户已通过 Zero Trust 认证。

获取 CSRF 令牌：向 Roundcube 的登录页发送请求，从 HTML 中提取 _token 字段。

💡

为什么需要获取 CSRF 令牌？

Roundcube 使用 CSRF（跨站请求伪造）令牌来防止恶意请求。每次登录时，服务器都会生成一个一次性的隐藏令牌嵌入登录表单。自动登录脚本必须先获取这个令牌，然后在提交登录信息时带上它，否则服务器会拒绝登录。

提交登录表单：用环境变量中的用户名和授权码构造 POST 请求，模拟登录。

跳转至邮箱：登录成功后，将页面重定向到收件箱。

3.2 配置自动登录

在你的服务器上，创建一个文件夹用于存放自定义配置文件，例如 ~/roundcube-mail/config

在 config 文件夹中新建文件 auto_login.php，将以下代码完整复制进去：

💡

脚本中的 ROUNDCUBE_USERNAME 和 ROUNDCUBE_PASSWORD 会从容器环境变量中读取，请确保之前在 docker-compose.yml 中已正确设置。

3.3 配置 Apache 传递 CF 认证头部

为了让 PHP 脚本能获取到 Cloudflare 的认证信息（CF-Access-Jwt-Assertion），需要在 Apache 中配置将请求头传递给后端。

创建一个 cloudflare-headers.conf 文件，也放在 config 目录中，并在其中粘贴以下内容：

3.4 设置默认主页和重写规则

Roundcube 默认的首页是 index.php，为了让用户在通过 Cloudflare 认证后直接进入自动登录流程，我们需要将默认主页修改为 auto_login.php。同时，为了确保 Roundcube 的其他功能（如带查询参数的 URL、AJAX 请求、静态资源访问等）能够正常工作，还需要配置一套 URL 重写规则。这些规则会集成在 .htaccess 文件中，由 Apache 自动处理。

创建一个.htaccess 文件，同样放在config 目录中，并将如下代码粘贴进去：

3.5 挂载配置文件到容器

现在需要修改 docker-compose.yml，将这些文件挂载到容器内的正确位置。编辑你的 docker-compose.yml，在 roundcube 服务的 volumes 部分添加以下内容：

⚠️

注意缩进，确保 volumes 下的条目与之前的对齐。

3.6 重启容器

保存文件后，重新创建容器以使挂载生效：

3.7 验证自动登录

打开浏览器的无痕模式，访问 https://mail.你的域名

页面应该首先跳转到 Cloudflare 的登录页（Zero Trust 认证）。

输入你策略中允许的邮箱，完成认证。

认证通过后，会进入自动登录页面，看到四个步骤依次变亮：

步骤1：检查 Cloudflare 认证 ✅

步骤2：获取 CSRF 令牌 ✅

步骤3：提交登录信息 ⚙️ → ✅

步骤4：进入邮箱 ⚙️ → 跳转

最后自动跳转至 Roundcube 收件箱，整个过程无需手动输入授权码。

结语

到此，整套邮箱系统就折腾完了。

回头看看，其实起因特别简单——就是嫌 API 太重，想偷个懒用 SMTP；结果搭好 Roundcube，又被那串 16 位授权码烦到了。于是给域名套上 Cloudflare Zero Trust，再写个自动登录页，让浏览器替我把密码填了。

整个过程不算复杂，但踩的坑也不少：CF 头部的传递、重定向循环、重定向次数过多、静态资源的修正还有AJAX请求，好在最后跑通了，现在进入网站认证完就是收件箱，这大概就是折腾的意义吧。

如果你也受够了每次登录都要复制授权码，希望这套配置能给你一点启发。代码和步骤都在上面了，你可以根据自己的环境调整——无论是换用其他邮箱、改改自动登录页的样式，还是把这套“CF 认证 + 前置登录页”的模式用到别的 Web 应用（比如 Nextcloud、WordPress）上，都行。

技术嘛，本来就是拿来折腾的。

最后，再次感谢 @技术爬爬虾 的视频，没有那些基础教程，我连域名都不知道怎么搞。也感谢读到这里的你，如果有任何问题或想法，欢迎在评论区留言交流。

两全其美，收工。 🚀

附录：

1. 在ClawCloud上部署的差异点

如果你使用的是 ClawCloud 这类容器平台，部署方式和挂载配置文件会有些不同，但核心配置（环境变量和配置文件）是相通的。

1. 创建应用

不需要写 docker-compose.yml，直接在 ClawCloud 控制台创建一个新应用，配置一下就行了，以下是我的配置图：

💡

ROUNDCUBEMAIL_CONFIG_SMTP_USER ROUNDCUBEMAIL_CONFIG_SMTP_PASS 和ROUNDCUBEMAIL_CONFIG_SMTP_AUTH_TYPE 三个配置并不正确，当时因为通过环境变量设置SMTP失败，放弃并更换使用了smtp.php配置文件，当时害怕删除这三个环境变量会出问题，然后这几个错误的环境变量就被意外保留了

容器端口设置为 80（HTTP），平台会自动分配一个访问域名（如 xxx.claw.cloud），在此基础上绑定自己域名并配置CNAME记录实现解析就行了，如下图：

2. 挂载配置文件

在 ClawCloud 这类 Kubernetes 平台上，可以通过 ConfigMap 将配置文件挂载到容器内，而不是直接挂载宿主机文件

持久化存储

Roundcube 的临时文件和日志建议使用平台的持久化存储卷，分别挂载到 /var/www/html/temp 和 /var/www/html/logs。

2. 环境变量与配置文件的关系

在 Docker 部署 Roundcube 时，你有两种方式配置系统：环境变量 和 配置文件。理解两者的关系及优先级，能帮你更灵活地管理设置。

1. 环境变量（适合基础配置）

Roundcube 官方 Docker 镜像支持以 ROUNDCUBEMAIL_ 为前缀的环境变量。镜像启动时会扫描所有以该前缀开头的变量，并将其自动写入 config/config.inc.php 中。例如：

环境变量	生成的配置项
`ROUNDCUBEMAIL_DEFAULT_HOST=ssl://imap.qq.com`	`$config['default_host'] = 'ssl://imap.qq.com';`
`ROUNDCUBEMAIL_SMTP_SERVER=ssl://smtp.resend.com`	`$config['smtp_server'] = 'ssl://smtp.resend.com';`
`ROUNDCUBEMAIL_SMTP_PORT=465`	`$config['smtp_port'] = 465;`

优点：

简单直观，适合快速部署。

敏感信息（如密码）可通过容器编排工具（如 Docker Compose 的 .env 文件、Kubernetes Secret）管理，避免硬编码。

在 ClawCloud 等平台，可以直接在控制台填写，无需手动创建文件。

局限：

仅支持 Roundcube 官方镜像预定义的配置项，并非所有 $config 选项都能通过环境变量设置（例如 smtp_helo_host、identities_level 等）。

变量名必须严格匹配，多一个单词或少一个前缀都会导致配置不生效

2. 配置文件（适合高级自定义）

Roundcube 原生通过 PHP 配置文件（如 config/config.inc.php 或你自定义的 smtp.php）进行配置。你可以将任何 $config 选项写入这些文件，它们会被 Roundcube 加载。

优点：

覆盖所有配置项，无任何限制。

可以按功能拆分文件（如 smtp.php、db.php），便于管理。

配置文件中的设置优先级更高（见下文）。

缺点：

需要手动创建文件并挂载到容器内，稍显繁琐。

敏感信息需注意权限保护。

3. 优先级：谁覆盖谁？

Roundcube 的配置加载顺序是：

首先加载 config/config.inc.php（镜像内置或挂载的文件）。

然后加载 config/*.php（按字母顺序，你挂载的 smtp.php 等文件）。

最后，环境变量生成的配置会覆盖上述文件中已存在的同名项。

也就是说，环境变量的优先级最高。如果同一个配置项既在环境变量中设置，又在配置文件中定义，环境变量的值最终生效。这有时会带来困扰——例如你尝试用 smtp.php 覆盖某个环境变量时，需要确保该环境变量不存在，或者其值不是预期的。

前言