目录

Cloud Mail 部署与使用教程：基于 Cloudflare Workers 搭建自己的邮箱服务

4

一、Cloud Mail 是什么

Cloud Mail 是一个基于 Cloudflare 的简约响应式邮箱服务，可以部署到 Cloudflare Workers，用较低成本搭建自己的邮箱系统。项目支持邮件发送、附件收发、用户管理、权限控制、多邮箱模式、数据可视化和个性化设置。

官方文档：

text

https://doc.skymail.ink/

项目仓库：

text

https://github.com/maillab/cloud-mail

适合使用 Cloud Mail 的场景：

  • 想用自己的域名搭建邮箱服务

  • 需要低成本收发邮件

  • 需要给多个用户创建域名邮箱

  • 需要把邮箱服务部署在 Cloudflare Workers 上

  • 需要附件收发、邮件转发、管理员管理和开放 API

二、功能概览

功能

说明

邮件接收

通过 Cloudflare Email Routing 接收域名邮件

邮件发送

集成 Resend 发送邮件

附件收发

可使用 KV 或 R2 对象存储保存附件

多号模式

一个用户可以添加多个邮箱

管理员功能

管理用户、邮件、权限和资源限制

数据可视化

使用图表展示邮件和系统数据

Turnstile

接入 Cloudflare Turnstile 防止批量注册

开放 API

支持 Token、邮件查询、添加用户等接口

三、部署前准备

部署前需要准备以下内容：

项目

用途

Cloudflare 账号

部署 Worker、D1、KV、R2，并接入域名

已托管到 Cloudflare 的域名

用作邮箱域名和访问域名

GitHub 账号

Fork 项目或使用 GitHub Actions 部署

Node.js

命令部署时需要，官方文档要求 Node.js v20.19.6

pnpm

安装依赖和执行部署命令

Resend 账号

用于发送邮件

Telegram Bot

可选，用于邮件转发到 Telegram

建议提前准备两个域名或子域名：

域名

示例

用途

邮箱域名

example.com

用户邮箱后缀，例如 admin@example.com

访问域名

mail.example.com

访问 Cloud Mail 网站

也可以使用同一个域名，但生产环境更建议用子域名单独访问后台。

四、部署方式选择

Cloud Mail 官方文档提供多种部署方式：

部署方式

适合人群

Cloudflare 界面部署

不熟悉命令行的新手

GitHub Actions 部署

希望自动化部署、后续更新方便的用户

命令部署

熟悉 Node.js、pnpm、Wrangler 的用户

如果你是第一次部署，建议优先选择 GitHub Actions 或 Cloudflare 界面部署；如果你需要完全控制配置文件和本地构建流程，可以选择命令部署。

五、方式一：Cloudflare 界面部署

1. Fork 项目仓库

打开项目仓库：

text

https://github.com/maillab/cloud-mail

点击 Fork，把项目复制到自己的 GitHub 账号下。

2. 在 Cloudflare 创建 Worker 项目

进入 Cloudflare 控制台，找到 Workers & Pages，创建新的 Worker 或 Pages 项目。

选择从 GitHub 导入项目，并授权 Cloudflare 访问你 Fork 后的仓库。

部署目录填写：

text

mail-worker

然后继续部署。

3. 设置环境变量

官方文档列出的必需变量如下：

变量名

必需

说明

domain

是

邮箱域名。多域名可填写类似 ["example.com","example2.com"]

admin

是

管理员邮箱，例如 admin@example.com

jwt_secret

是

JWT 密钥，填写一串随机字符串，不建议包含特殊字符

示例：

text

domain=["example.com"] admin=admin@example.com jwt_secret=change-this-random-string

4. 创建并绑定 KV、D1

在 Cloudflare 中创建：

  • KV 命名空间

  • D1 数据库

然后在 Worker 绑定中添加：

绑定名

类型

说明

kv

KV

变量名必须为 kv

db

D1

变量名必须为 db

绑定名不要随意修改，否则项目可能无法正常读取数据。

5. 配置邮件路由

进入 Cloudflare 域名管理页面：

text

域名 -> 电子邮件 -> 电子邮件路由

开启 Email Routing，并在路由规则中设置 Catch-all 地址，把邮件转发到 Worker。

这样发送到你域名的邮件，才会进入 Cloud Mail 系统。

6. 初始化数据库

部署完成后，在浏览器访问：

text

https://你的Worker自定义域/api/init/你的jwt_secret

把 你的Worker自定义域 替换成实际访问域名，把 你的jwt_secret 替换成环境变量里的密钥。

看到初始化成功后，再访问网站首页注册管理员账号。

六、方式二：GitHub Actions 部署

GitHub Actions 部署适合长期维护，后续更新也更方便。

1. 创建 Cloudflare API Token

进入 Cloudflare API Token 页面，创建用于部署 Workers、D1、KV 等资源的 API Token。

你还需要复制 Cloudflare Account ID。

2. Fork 项目并配置 Secrets

Fork 项目后，进入 GitHub 仓库：

text

Settings -> Secrets and variables -> Actions

添加以下变量：

变量名

必需

说明

CLOUDFLARE_API_TOKEN

是

Cloudflare API 令牌

CLOUDFLARE_ACCOUNT_ID

是

Cloudflare 账户 ID

CUSTOM_DOMAIN

是

网站访问域名，例如 mail.example.com

DOMAIN

是

邮箱域名，可填写 ["example.com"]

ADMIN

是

管理员邮箱，例如 admin@example.com

JWT_SECRET

是

JWT 密钥

NAME

否

Worker 项目名，默认 cloud-mail

D1_DATABASE_ID

否

D1 数据库 ID，默认使用同名数据库

KV_NAMESPACE_ID

否

KV 命名空间 ID，默认使用同名 KV

3. 运行工作流

进入 GitHub 仓库的 Actions 页面，选择部署工作流并手动运行。

等待工作流执行完成后，回到 Cloudflare 检查 Worker、KV、D1 和自定义域名是否创建成功。

4. 设置邮件转发并初始化

GitHub Actions 部署完成后，仍然需要在 Cloudflare Email Routing 中设置 Catch-all 到 Worker。

然后访问：

text

https://你的访问域名/api/init/你的JWT_SECRET

初始化完成后，打开访问域名注册管理员账号并登录。

七、方式三：命令行部署

如果你熟悉本地命令行，可以使用命令部署。

1. 克隆项目

bash

git clone https://github.com/maillab/cloud-mail cd cloud-mail/mail-worker

2. 安装依赖

bash

pnpm i

3. 配置 wrangler.toml

编辑：

text

mail-worker/wrangler.toml

核心配置示例：

toml

[[d1_databases]] binding = "db" database_name = "cloud-mail" database_id = "你的D1数据库ID" [[kv_namespaces]] binding = "kv" id = "你的KV命名空间ID" [[r2_buckets]] binding = "r2" bucket_name = "你的R2桶名称" [assets] binding = "assets" directory = "./dist" [triggers] crons = ["0 16 * * *"] [vars] orm_log = false domain = ["example.com"] admin = "admin@example.com" jwt_secret = "change-this-random-string"

注意：db、kv、r2、assets 这些绑定名建议按官方默认值配置，不要随意改名。

4. 执行部署

bash

pnpm run deploy

部署完成后，配置 Cloudflare 邮件路由，然后访问初始化地址：

text

https://worker自定义域/api/init/你的jwt_secret

八、配置邮件发送

Cloudflare Workers 当前不能直接作为传统 SMTP 发件服务使用，官方文档也提示 Cloudflare 封禁 25 端口，因此 Cloud Mail 发件需要接入第三方服务。

官方推荐使用 Resend：

  1. 注册 Resend 账号。

  2. 在 Resend 添加你的发件域名。

  3. 按 Resend 提示完成 DNS 验证。

  4. 创建 API Key。

  5. 在 Resend 中设置发送状态回调：

text

https://worker自定义域/api/webhooks

  1. 登录 Cloud Mail 后台，在系统设置中填入 Resend API Key 和相关发件配置。

配置完成后，可以尝试给外部邮箱发送一封测试邮件。

九、配置附件存储

Cloud Mail 支持附件收发。官方文档说明，附件默认可使用 KV 存储，也可以切换到 R2 或兼容 S3 协议的对象存储。

推荐使用 Cloudflare R2 保存附件：

  1. 在 Cloudflare 创建 R2 Bucket。

  2. 为 R2 设置自定义域名。

  3. 在 Worker 中绑定 R2，绑定名使用：

text

r2

  1. 如果使用 GitHub Actions，配置对应 Secret：

text

R2_BUCKET_NAME=你的R2桶名称

  1. 登录 Cloud Mail 后台，在系统设置中切换附件存储配置。

十、配置 Turnstile 人机验证

Turnstile 可以降低批量注册和机器人滥用风险。

配置流程：

  1. 进入 Cloudflare Turnstile。

  2. 创建一个新组件。

  3. 复制 Site Key 和 Secret Key。

  4. 登录 Cloud Mail 后台。

  5. 在系统设置中填入 Turnstile 配置并保存。

如果你的站点开放注册，建议开启 Turnstile。

十一、配置邮件转发

Cloud Mail 支持把邮件转发到 Telegram 或其他邮箱。

1. 转发到 Telegram

配置思路如下：

  1. 在 Telegram 中找到 BotFather。

  2. 创建机器人并复制 Bot Token。

  3. 给机器人发送一条消息。

  4. 在浏览器访问：

text

https://api.telegram.org/bot你的机器人Token/getUpdates

  1. 从返回结果中找到 chat_id。

  2. 登录 Cloud Mail 后台，在系统设置中填入 Bot Token 和 chat_id。

如果获取不到 chat_id，可以再给机器人发送几条消息后重新访问 getUpdates。

2. 转发到其他邮箱

如果要转发到外部邮箱，需要先在 Cloudflare 中完成目标邮箱验证，然后进入 Cloud Mail 系统设置中配置转发规则。

十二、日常使用教程

1. 注册管理员账号

初始化数据库后，打开 Cloud Mail 访问域名。

使用环境变量 admin 中配置的管理员邮箱注册账号。注册完成后登录后台。

2. 创建普通用户

管理员登录后，可以进入用户管理页面，创建普通用户并分配权限。

如果开启多号模式，一个用户可以添加多个邮箱地址。

3. 收取邮件

当 Cloudflare Email Routing 配置正确后，发送到域名邮箱的邮件会进入 Cloud Mail。

用户登录后，可以在邮件列表中查看收件箱、邮件详情和附件。

4. 发送邮件

配置 Resend 后，进入写信页面：

  1. 选择发件邮箱。

  2. 填写收件人。

  3. 输入主题和正文。

  4. 按需添加附件。

  5. 点击发送。

发送后可以在系统中查看发送状态。

5. 管理邮件

管理员可以对用户和邮件进行管理。常见操作包括：

  • 查看邮件列表

  • 搜索邮件

  • 删除邮件

  • 管理用户

  • 设置权限角色

  • 查看统计数据

6. 使用开放 API

Cloud Mail 提供开放 API。使用前需要先生成 Token。

生成 Token 接口：

http

POST /api/public/genToken

请求参数：

参数

类型

必填

说明

email

string

是

管理员邮箱

password

string

是

邮箱密码

获取 Token 后，把它放到后续请求的 Authorization 请求头中。

常见接口：

接口

用途

POST /api/public/genToken

生成身份令牌

POST /api/public/emailList

查询邮件列表

POST /api/public/addUser

添加用户

官方文档说明，部分查询参数支持模糊匹配，例如 admin% 表示开头匹配，%@example.com 表示结尾匹配。

十三、可选环境变量

官方文档还提供了一些可选变量：

Worker Secret

GitHub Actions 变量

默认值

说明

ai_model

AI_MODEL

llama-3.1-8b-instruct

AI 模型

analysis_cache

ANALYSIS_CACHE

false

是否开启分析页数据缓存

project_link

PROJECT_LINK

true

是否显示登录页 GitHub 图标

这些变量不是基础部署必需项，可以等主流程部署完成后再调整。

十四、常见问题

访问网站后无法注册管理员怎么办？

先确认是否已经访问初始化地址：

text

https://你的域名/api/init/你的jwt_secret

再检查 admin 环境变量是否与你注册时使用的邮箱一致。

能收邮件但不能发邮件怎么办？

Cloudflare Workers 不能直接走传统 SMTP 发信，需要配置 Resend。请检查 Resend 域名验证、API Key 和 Webhook 地址是否正确。

收不到邮件怎么办？

重点检查 Cloudflare Email Routing：

  • 域名是否已接入 Cloudflare

  • Email Routing 是否启用

  • Catch-all 是否转发到 Worker

  • MX 记录是否按 Cloudflare 要求配置

  • Worker 是否绑定了正确的 D1 和 KV

附件无法上传或下载怎么办？

检查存储配置：

  • 是否创建了 R2 Bucket

  • Worker 绑定名是否为 r2

  • R2 自定义域名是否可访问

  • 后台系统设置是否选择了正确存储方式

更新后功能异常怎么办？

重新访问初始化地址通常可以完成数据库更新：

text

https://你的域名/api/init/你的jwt_secret

更新前建议备份 D1、KV 和重要配置。

十五、总结

Cloud Mail 适合用 Cloudflare 生态快速搭建低成本域名邮箱。基础部署需要 Worker、D1、KV、域名和 Email Routing；如果要完整使用发件、附件和防滥用功能，还需要配置 Resend、R2 和 Turnstile。

建议部署顺序如下：

  1. 接入 Cloudflare 域名。

  2. 部署 Cloud Mail Worker。

  3. 配置 domain、admin、jwt_secret。

  4. 绑定 D1 和 KV。

  5. 配置 Email Routing 到 Worker。

  6. 初始化数据库。

  7. 注册管理员并登录后台。

  8. 配置 Resend、R2、Turnstile 和转发规则。

按这个顺序操作，最容易定位问题，也方便后续维护。