【Xi-Mail】基于 Cloudflare 全家桶的自托管临时邮箱服务

Xi-Mail 是基于 Cloudflare Workers / D1 / KV / R2 构建的全栈自托管邮箱服务，在 cloud-mail 开源项目基础上进行二次开发，带来全面 UI 重设计与一系列新功能。

只需一个托管于 Cloudflare 的域名，即可免费部署支持多账户、多域名、层级权限的完整邮箱平台。

---

✨ 相比上游新增 / 改动

🎨 UI 全面重设计（Linear 风格）

• 采用 TailwindCSS 4 + @vueuse/motion 动画库重构前端样式系统
• 登录 / 注册页：磨砂玻璃卡片 + 动态渐变背景光晕 + 网格装饰
• 侧边栏：深色极简风格，图标统一
• 顶栏：紧凑布局，渐变 Compose 按钮，用户信息面板优化
• 全局设计 Token：indigo-violet 渐变色系、彩色阴影、统一圆角
• 顶栏语言切换按钮：一键切换中文 / 英文界面，实时生效并持久化保存

👤 用户系统增强

• Display ID：用户 ID 改为随机字母数字组合（xxxx-xxxx-xxxx），不再使用纯数字自增
• Display ID 展示于：用户详情面板、个人设置页、顶栏头像悬浮卡片
• 邮箱转移：用户可将邮箱账户及其全部邮件转移给其他用户（通过 Display ID 指定），接收方可确认或拒绝

📬 账号管理优化

• 收件箱 / 已发送页侧边栏账号列表：新增搜索过滤，显示完整邮件地址（便于多账号区分）
• 账号操作下拉菜单始终可见（含邮箱转移入口）
• 已发送 / 草稿箱：无发送权限或角色被禁止发送时，侧边栏自动隐藏这两个菜单项

🔄 转移功能页（/transfer）

• 独立侧边栏页面，支持发起转移、查看待处理 / 已发送转移请求
• 顶栏 Badge 实时显示待处理数量

🛡️ 权限系统重设计

• 角色新增 level 字段（数值越大权限越高）
• 用户只能为权限等级低于自身的角色生成邀请码
• 邀请码生成时服务端严格校验等级约束

🗂️ 批量操作（用户管理）

• 支持批量封禁、批量解封、批量删除选中用户
• 用户关联邮箱账号支持批量删除

⚙️ 系统设置增强

• 全局 API Token：管理员可开启并生成全局 Token，通过 x-admin-auth 请求头无需登录直接查询指定邮箱的邮件（GET /api/admin/mails）
• 邮件地址关键词黑名单：防止普通用户注册含 admin 等敏感词的邮箱地址（管理员可跳过检查）
• 发件人域名黑名单：屏蔽来自指定域名的发件人，系统直接拒绝其邮件，有效防御邮件轰炸
• Turnstile 人机验证管理员免验：开启 Turnstile 后管理员注册 / 添加邮箱无需完成人机验证
• 注册码提示与获取链接：启用注册码后可配置提示文字（如”联系管理员获取”）及跳转链接，方便新用户了解如何获取注册码
• 公告弹窗美化：居中 Dialog 展示，自定义标题 / 宽度 / 内容，移除冗余的位置 / 偏移等过时配置
• 域名映射 UI 优化（展示系统已有域名供快速选择）
• 自动封禁设置对齐修复，移除冗余的”登录背景”和”登录透明度”配置

🔍 操作提示完善

• 所有操作图标（搜索、刷新、排序、批量操作等）统一补全 Tooltip 悬浮提示

---

🚀 快速部署

前置要求

• Node.js ≥ 20
• 已登录 Cloudflare 账户：npx wrangler login
• 一个托管在 Cloudflare 的域名，并配置好邮件路由（Email Routing）

步骤

# 1. 克隆项目
git clone https://github.com/PastKing/xi-mail.git
cd xi-mail/mail-worker

# 2. 安装依赖
npm install

# 3. 创建 Cloudflare 资源
npx wrangler d1 create xi-mail          # 记录输出的 database_id
npx wrangler kv namespace create kv     # 记录输出的 id
npx wrangler r2 bucket create xi-mail

# 4. 配置 wrangler.toml
cp wrangler.example.toml wrangler.toml
# 编辑 wrangler.toml，填入上一步获得的 ID、域名列表、管理员邮箱、JWT 密钥

# 5. 构建前端
cd ../mail-view
npm install
npm run build

# 6. 初始化数据库并部署
cd ../mail-worker
npx wrangler deploy

# 7. 初始化数据库表结构（首次部署后访问）
# 在浏览器中访问：https://your-worker.workers.dev/api/init/<JWT_SECRET>

wrangler.toml 关键字段说明

[vars]
domain      = ["mail.example.com"]   # 邮箱域名列表（JSON 数组）
admin       = "admin@example.com"    # 管理员邮箱（首次初始化后无法更改）
jwt_secret  = "your-secret"          # JWT 签名密钥（至少 32 位随机字符串）

---

📡 全局 API Token

系统设置 → 安全 → 全局 API Token 中开启并生成 Token 后，可通过以下接口无需登录查询邮件：

GET /api/admin/mails?limit=20&offset=0&address=user@domain.com
x-admin-auth: <your-token>

响应格式：

{
  "results": [...],
  "count": 100
}

🛠️ 项目地址

https://github.com/PastKing/xi-mail