在 Cloudflare Pages 部署 Xi-Mail（KV + D1，无 R2）

1. 前置准备

  • 域名 你的域名 已托管在 Cloudflare
  • Node.js ≥ 20，本地已执行 npx wrangler login
  • 一个 Resend 免费账号，并完成 你的域名 的域名验证（Resend 会给出需要添加的 TXT/MX 记录），拿到 API Key
  • GitHub 账号（用于 Fork 仓库和连接 Pages）

说明：Xi-Mail 和其上游 Cloud Mail 默认依赖 R2 存放附件。本教程只使用 KV + D1，不创建、不绑定 R2。邮件正文和元数据可正常存储在 D1 中，纯文本邮件收发不受影响；附件功能不可用或严重受限。如果附件是刚需，需要引入其他免费对象存储作为替代。

2. 创建 Cloudflare 资源（只建 KV + D1）

在本地终端执行：

1
2
3
4
5
npx wrangler d1 create xi-mail
# 记录输出的 database_id

npx wrangler kv namespace create kv
# 记录输出的 id

不要执行 npx wrangler r2 bucket create，整个部署过程中都不创建 R2。

3. 获取代码并配置后端

1
2
3
4
git clone https://github.com/PastKing/xi-mail.git
cd xi-mail/mail-worker
npm install
cp wrangler.example.toml wrangler.toml

编辑 wrangler.toml，填入 D1 和 KV 的 ID，保持 R2 相关段落的注释状态或直接删除。关键配置结构如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
name = "xi-mail"
main = "src/index.ts"
compatibility_date = "2024-09-23"

[[d1_databases]]
binding = "DB"
database_name = "xi-mail"
database_id = "你记录的 database_id"

[[kv_namespaces]]
binding = "KV"
id = "你记录的 KV id"

[vars]
domain = ["你的域名"]
admin = "admin@你的域名"

domain 使用 你的域名 作为邮件主域名，Web 访问入口后面单独绑定 mail.你的域名 到 Pages。

环境变量 / Secrets（在 Cloudflare 控制台的 Worker 设置中填入，不要写进 wrangler.toml）：

变量名用途
JWT_SECRET一个随机的长字符串，用于登录会话和后续数据库初始化
RESEND_TOKENResend 的 API Key

Xi-Mail 通过 Resend 免费额度发信，不依赖 Cloudflare 的付费发信服务。

4. 部署后端 Worker

1
npx wrangler deploy

部署完成后，记下 Worker 的地址（形如 https://xi-mail.xxx.workers.dev）。然后立即访问以下 URL 初始化 D1 数据库表结构：

1
https://你的worker地址/api/init/你的JWT_SECRET

看到初始化成功的响应后，后端就绪。

5. 配置 Email Routing 收信

进入 Cloudflare 控制台，选中 你的域名，进入 Email Routing：

  1. 如果之前有旧的 MX 记录，先清理避免冲突。
  2. 启用 Email Routing。
  3. 在 Routes 或 Catch-all 规则中，将动作设置为 Send to a Worker，选择刚刚部署的 xi-mail Worker。

这一步完成后，发往任意 xxx@你的域名 的邮件都会被路由到 Worker，写入 D1。

6. 构建前端并部署到 Pages

进入前端目录：

1
2
cd ../mail-view
npm install

Xi-Mail 支持 build:standalone 构建纯静态前端，用于部署到 Pages。构建时需要把 API 地址指向刚才的 Worker：

1
VITE_BASE_URL=https://你的worker地址/api npm run build:standalone

构建输出在 dist/ 目录（以实际输出为准）。

在 Cloudflare 控制台进入 Workers & Pages → 创建 → Pages → 上传资源，将 dist/ 目录整体上传。也可以在 Pages 中连接 GitHub 仓库进行自动构建，构建命令设为 npm run build:standalone，输出目录设为 dist，并在环境变量中设置 VITE_BASE_URL。

7. 绑定自定义域 mail.你的域名

Pages 部署完成后，进入该 Pages 项目 → 自定义域，添加：

1
mail.你的域名

Cloudflare 会自动创建对应的 CNAME 记录。生效后，通过 https://mail.你的域名 即可访问邮箱界面。

8. 验证收发

收信测试：用任意外部邮箱向 任意前缀@你的域名 发送一封纯文本邮件，刷新 https://mail.你的域名，确认邮件出现在收件箱中。

发信测试：在 Web 界面写信，收件人填一个真实邮箱，发送后检查是否通过 Resend 成功投递。Resend 免费额度为每月 3,000 封，每天最多 100 封。

附件测试：无 R2 部署下，尝试添加附件可能会失败，或邮件虽然发出但附件无法存储。这是预期内的限制，不是配置错误。

9. 无 R2 的附件替代思路（可选）

如果确实需要附件功能，又坚持不启用 R2，可以考虑：

  • 把附件直接存入 D1：部分邮件系统支持将小附件以 base64 形式写入 D1。D1 免费额度为 5 GB，适合偶尔的小文件，但不宜存放大量或大体积附件，否则会快速消耗数据库空间。
  • 只保留文字邮件：把该邮箱定位为“验证码 / 通知接收专用”，附件需求交给另一个邮箱处理。
  • 使用其他免费对象存储：例如 IBM Cloud Object Storage 等提供免费额度的服务，替换附件存储后端。

按以上步骤，即可在 mail.你的域名 上运行一个基于 Pages + Workers + D1 + KV 的邮箱，全程不创建 R2，不绑定支付方式（域名年费除外）。核心取舍是：附件功能让位于“零 R2 依赖”；如果未来对附件的需求变强，再考虑引入无需绑卡的免费对象存储或迁移到支持 R2 的完整部署。