Cloud Mail 项目部署完整教程—界面部署与 Action 部署指南
Cloud Mail 项目部署完整教程—界面部署与 Action 部署指南
三水番项目简介
Cloud Mail 是一个基于 Cloudflare 的开源邮箱服务项目，只需一个域名就可以创建多个不同的邮箱，类似各大邮箱平台。该项目支持部署到 Cloudflare Workers，能有效降低服务器成本。
主要特性：
- 💰 低成本部署到 Cloudflare Workers
- 📧 集成 Resend 邮件发送服务
- 📦 支持附件收发
- 🛡️ 完整的管理员权限管理
- 📈 数据可视化展示
- 🎨 个性化自定义配置
- 🤖 集成 Turnstile 人机验证
技术栈：
- 平台：Cloudflare Workers
- 后端：Hono + Drizzle ORM
- 前端：Vue3 + Element Plus
- 邮件：Resend
- 存储：Cloudflare KV、D1、R2
部署方式1：界面部署（Dashboard）
界面部署是通过 Cloudflare 控制面板直接操作部署项目，适合不太熟悉 GitHub Actions 的用户。
第一步：准备账号
1. 注册 Cloudflare 账号
首先需要访问 Cloudflare 官网，注册一个账号。
2. 添加域名到 Cloudflare
如果你对如何接入域名不熟悉，可以参考这个教程：域名接入Cloudflare
第二步：创建and配置项目
1. Fork 项目到你的 GitHub 账号
访问 Cloud Mail GitHub 仓库，点击 Fork 按钮将项目克隆到自己的账号中。
2. 在 Cloudflare 中创建 Worker 项目
在 Cloudflare 控制台中找到 Workers & Pages 选项，点击创建应用程序。
3. 选择 GitHub 导入
在创建 Worker 项目的过程中，选择通过 GitHub 导入的方式连接你刚才 Fork 的仓库。
4. 配置项目路径
在部署配置中，设置项目目录为 mail-worker，然后点击部署。
第三步：设置环境变量
部署完成后，需要在 Worker 项目的设置 > 环境变量中配置以下必需的环境变量：
| 环境变量名 | 必需 | 说明 | 示例 |
|---|---|---|---|
domain |
✅ | 邮箱服务使用的域名，多域名用逗号分隔 | ["example.com","example2.com"] |
admin |
✅ | 管理员邮箱地址 | admin@example.com |
jwt_secret |
✅ | JWT 密钥（随意输入，不要包含特殊字符） | your_random_secret_string |
project_link |
❌ | 是否在登录界面显示项目链接 (true/false) | false |
配置步骤：
- 在 Worker 项目页面点击设置
- 找到环境变量选项
- 添加上述环境变量及其对应的值
- 保存配置
第四步：绑定数据库
Cloud Mail 需要使用 Cloudflare 的 KV（键值存储）和 D1（数据库）服务。
1. 创建 KV 和 D1 数据库
在 Cloudflare 控制台中：
- 创建一个 Cloudflare KV 命名空间
- 创建一个 Cloudflare D1 数据库
2. 绑定到 Worker 项目
在 Worker 项目的设置 > 绑定中添加：
- 将 KV 命名空间绑定为
kv（注意：变量名必须是kv） - 将 D1 数据库绑定为
db（注意：变量名必须是db）
第五步：设置自定义域名
为了能通过自己的域名访问 Cloud Mail，需要配置自定义域名：
- 在 Worker 项目页面点击设置 > 自定义域
- 输入你的自定义域名（例如
mail.example.com） - 验证域名所有权并完成配置
第六步：设置邮件转发
Cloud Mail 需要配置 Cloudflare Email Routing 来接收邮件。
- 在 Cloudflare 控制台找到 Email Routing
- 创建转发规则，将目标域名的邮件转发到你的 Worker 应用处理
第七步：初始化数据库和登录
1. 初始化数据库
在浏览器中访问以下 URL（将相关参数替换为你的实际信息）：
1 | https://你的worker自定义域/api/init/你的jwt_secret |
例如：
1 | https://mail.example.com/api/init/mysecret123456 |
看到初始化成功提示后，数据库就配置完成了。
2. 访问网站并注册管理员账号
在浏览器中访问你的自定义域名，系统会自动重定向到登录/注册页面。使用你配置的管理员邮箱地址注册账号，该账号将获得管理员权限。
部署方式2：GitHub Actions 部署
GitHub Actions 提供了自动化部署流程，使用此方式可以一键部署，更加便捷。
第一步：创建 Cloudflare API 令牌
1. 访问 API 令牌管理页面
2. 选择模板创建令牌
点击创建令牌，选择预设的模板，这样能快速配置必需的权限。
3. 配置权限
根据部署需求，确保令牌拥有以下权限：
- Worker 脚本读写权限
- Cloudflare D1 和 KV 的管理权限
- 自定义域名管理权限
4. 复制令牌
创建完成后，复制 API 令牌备用。
5. 获取账户 ID
在 Cloudflare 控制台的账户详情页面中，复制你的 Cloudflare 账户 ID。
第二步：准备 GitHub 环境
1. Fork 项目仓库
访问 Cloud Mail GitHub 仓库，点击 Fork 将项目克隆到你的账号。
2. 配置 GitHub Secrets 和 Variables
在 Fork 后的仓库中，进入 Settings > Secrets and variables > Actions：
添加 Secrets（机密信息）：
| Secret 名称 | 说明 | 获取方式 |
|---|---|---|
CLOUDFLARE_API_TOKEN |
Cloudflare API 令牌 | 从第一步获得 |
CLOUDFLARE_ACCOUNT_ID |
Cloudflare 账户 ID | 从 Cloudflare 控制台获取 |
添加 Variables（普通变量）：
| 变量名 | 必需 | 说明 | 示例 |
|---|---|---|---|
CUSTOM_DOMAIN |
✅ | 用于访问网站的自定义域名 | mail.example.com |
DOMAIN |
✅ | 邮箱服务的域名，多域名用逗号分隔 | ["example.com","example2.com"] |
ADMIN |
✅ | 管理员邮箱地址 | admin@example.com |
JWT_SECRET |
✅ | JWT 密钥（随意输入，不要包含特殊字符） | your_random_secret_string |
NAME |
❌ | Worker 项目名字，默认值为 cloud-mail |
cloud-mail |
D1_DATABASE_ID |
❌ | D1 数据库 ID，默认使用 Worker 同名数据库 | - |
KV_NAMESPACE_ID |
❌ | KV 命名空间 ID，默认使用 Worker 同名数据库 | - |
PROJECT_LINK |
❌ | 是否在登录界面显示项目链接 (true/false) | false |
配置步骤详解：
- 在仓库首页点击 Settings 选项卡
- 左侧菜单选择 Secrets and variables > Actions
- 点击 New repository secret 添加 Secrets
- 点击 New repository variable 添加 Variables
- 逐一添加上述所有配置项
第三步：运行 GitHub Actions 工作流
1. 触发工作流
在仓库中找到 Actions 选项卡，你会看到预定义的工作流程（Workflows）。选择相应的工作流程后点击 Run workflow 按钮。
2. 等待部署完成
工作流将自动执行，包括以下步骤：
- 检出代码
- 安装依赖
- 构建项目
- 部署到 Cloudflare Workers
- 创建必需的绑定和数据库
你可以在 Actions 页面查看实时执行日志，等待流程完全完成（通常需要 5-10 分钟）。
3. 验证部署
部署完成后 Actions 会显示 ✅ 标记。如果出现 ❌ 标记，可以点击查看详细日志来排查问题。
第四步：配置邮件转发
部署完成后，需要配置 Cloudflare Email Routing 来接收邮件，步骤与界面部署方式相同：
- 在 Cloudflare 控制台找到 Email Routing
- 创建转发规则，将你的域名邮件转发到 Worker 应用处理
具体配置请参考前面的界面部署文档中的第五步：设置邮件转发部分。
第五步：初始化并访问网站
1. 初始化数据库
在浏览器中访问初始化 URL：
1 | https://你的自定义域名/api/init/你的jwt_secret |
2. 注册管理员账号
访问你的自定义域名，注册管理员账号并登录网站。
🎉 部署完成！
两种部署方式对比
| 对比项 | 界面部署 | GitHub Actions 部署 |
|---|---|---|
| 难度 | ⭐ 中等 | ⭐ 简单 |
| 部署速度 | ⭐ 较慢 | ⭐⭐ 快 |
| 自动化程度 | ⭐ 基础 | ⭐⭐ 高度自动化 |
| 更新迭代 | 需要手动重新部署 | 可通过 Action 自动更新 |
| 适合人群 | 偏好手工配置的用户 | 追求自动化的用户 |
| 错误排查难度 | ⭐ 容易 | ⭐ 较难 |
常见问题排查
Q1: 初始化数据库时出现错误
原因：
- 域名配置不正确
- JWT Secret 包含特殊字符
- 数据库绑定未完成
解决方案：
- 检查 Worker 自定义域名配置
- 确保 JWT Secret 只包含字母、数字和下划线
- 重新检查 KV 和 D1 的绑定是否正确
Q2: 无法通过域名访问 Cloud Mail
原因：
- 域名 DNS 记录未正确配置
- Worker 自定义域名未生效
- 防火墙或安全规则阻止
解决方案：
- 等待 DNS 记录生效（通常需要几分钟到 24 小时）
- 在 Cloudflare 控制台验证自定义域名状态
- 检查 Cloudflare 的防火墙规则设置
Q3: 邮件接收不到
原因：
- Email Routing 未正确配置
- 域名 MX 记录不正确
- Worker 处理邮件时出错
解决方案：
- 验证 Cloudflare Email Routing 中的转发规则
- 确保 MX 记录指向 Cloudflare
- 查看 Worker 日志中的错误信息
Q4: GitHub Actions 部署失败
原因：
- Secrets 或 Variables 配置不完整或错误
- API 令牌权限不足
- Worker 名称冲突
解决方案：
- 重新检查所有 Secrets 和 Variables 的配置
- 确保 API 令牌拥有必需的权限
- 尝试修改 Worker 项目名称
部署后的进一步配置
1. 配置邮件发送服务
集成 Resend 或其他邮件服务商，实现邮件发送功能。
2. 配置人机验证
集成 Cloudflare Turnstile，防止滥用注册。
3. 配置文件存储
基于 Cloudflare R2 对象存储配置附件的存储和下载。
4. 配置邮件转发通知
设置邮件接收后的转发策略，可转发到 Telegram 或其他邮箱。
参考资源
总结
通过本教程，你已经学会了 Cloud Mail 的两种部署方式：
- 界面部署 提供了更细粒度的控制，适合需要自定义配置的用户
- GitHub Actions 部署 提供了更高的自动化程度，适合追求快速部署的用户
无论选择哪种方式，都能在几十分钟内搭建起自己的邮箱服务。如遇问题，可参考官方文档或社区讨论。
祝部署顺利！🚀
