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 = "[email protected]" # 管理员邮箱（首次初始化后无法更改）
jwt_secret = "your-secret" # JWT 签名密钥（至少 32 位随机字符串）
全局 API Token
系统设置 → 安全 → 全局 API Token 中开启并生成 Token 后，可通过以下接口无需登录查询邮件：
GET /api/admin/mails?limit=20&offset=0&[email protected]
x-admin-auth: <your-token>
响应格式：
{
"results": [...],
"count": 100
}
项目地址