Xi-Mail 是基于 Cloudflare Workers / D1 / KV / R2 构建的全栈自托管邮箱服务，在 cloud-mail 开源项目基础上进行二次开发，带来全面 UI 重设计与一系列新功能。
只需一个托管于 Cloudflare 的域名，即可免费部署支持多账户、多域名、层级权限的完整邮箱平台。
- 采用 TailwindCSS 4 + @vueuse/motion 动画库重构前端样式系统
- 登录 / 注册页：磨砂玻璃卡片 + 动态渐变背景光晕 + 网格装饰
- 侧边栏：深色极简风格，图标统一
- 顶栏：紧凑布局，渐变 Compose 按钮，用户信息面板优化
- 全局设计 Token：indigo-violet 渐变色系、彩色阴影、统一圆角
- 顶栏语言切换按钮：一键切换中文 / 英文界面，实时生效并持久化保存
- Display ID：用户 ID 改为随机字母数字组合（
xxxx-xxxx-xxxx），不再使用纯数字自增 - Display ID 展示于：用户详情面板、个人设置页、顶栏头像悬浮卡片
- 邮箱转移：用户可将邮箱账户及其全部邮件转移给其他用户（通过 Display ID 指定），接收方可确认或拒绝
- 收件箱 / 已发送页侧边栏账号列表：新增搜索过滤，显示完整邮件地址（便于多账号区分）
- 账号操作下拉菜单始终可见（含邮箱转移入口）
- 已发送 / 草稿箱：无发送权限或角色被禁止发送时，侧边栏自动隐藏这两个菜单项
- 独立侧边栏页面，支持发起转移、查看待处理 / 已发送转移请求
- 顶栏 Badge 实时显示待处理数量
- 角色新增
level字段（数值越大权限越高） - 用户只能为权限等级低于自身的角色生成邀请码
- 邀请码生成时服务端严格校验等级约束
- 支持批量封禁、批量解封、批量删除选中用户
- 用户关联邮箱账号支持批量删除
- 全局 API Token：管理员可开启并生成全局 Token，通过
x-admin-auth请求头无需登录直接查询指定邮箱的邮件（GET /api/admin/mails） - 邮件地址关键词黑名单：防止普通用户注册含
admin等敏感词的邮箱地址（管理员可跳过检查） - 发件人域名黑名单：屏蔽来自指定域名的发件人，系统直接拒绝其邮件，有效防御邮件轰炸
- Turnstile 人机验证管理员免验：开启 Turnstile 后管理员注册 / 添加邮箱无需完成人机验证
- 注册码提示与获取链接：启用注册码后可配置提示文字（如"联系管理员获取"）及跳转链接，方便新用户了解如何获取注册码
- 公告弹窗美化：居中 Dialog 展示，自定义标题 / 宽度 / 内容，移除冗余的位置 / 偏移等过时配置
- 域名映射 UI 优化（展示系统已有域名供快速选择）
- 自动封禁设置对齐修复，移除冗余的"登录背景"和"登录透明度"配置
- 所有操作图标（搜索、刷新、排序、批量操作等）统一补全 Tooltip 悬浮提示
| 层级 | 技术 |
|---|---|
| 运行时 | Cloudflare Workers |
| Web 框架 | Hono |
| ORM | Drizzle ORM |
| 数据库 | Cloudflare D1 (SQLite) |
| 缓存 / 会话 | Cloudflare KV |
| 文件存储 | Cloudflare R2 |
| 前端框架 | Vue 3 + Vite |
| UI 组件库 | Element Plus |
| CSS 工具 | TailwindCSS 4 |
| 动画库 | @vueuse/motion |
| 状态管理 | Pinia |
| 路由 | Vue Router |
| 国际化 | vue-i18n（中文 / 英文） |
xi-mail/
├── mail-worker/ # Cloudflare Worker 后端
│ ├── src/
│ │ ├── api/ # 接口路由层
│ │ ├── service/ # 业务逻辑层
│ │ ├── entity/ # Drizzle 数据库实体
│ │ ├── security/ # JWT 身份认证 + 权限中间件
│ │ ├── init/ # 数据库初始化 / 版本迁移
│ │ └── index.js # Worker 入口
│ └── wrangler.example.toml # 配置模板（复制为 wrangler.toml 后填写）
│
└── mail-view/ # Vue 3 前端
├── src/
│ ├── layout/ # 布局组件（侧边栏 / 顶栏 / 账号栏）
│ ├── views/ # 页面组件
│ ├── components/ # 通用组件
│ ├── store/ # Pinia 状态管理
│ ├── i18n/ # 国际化（zh / en）
│ └── style.css # 全局样式 / 设计 Token
└── vite.config.js
- 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>[vars]
domain = ["mail.example.com"] # 邮箱域名列表（JSON 数组）
admin = "admin@example.com" # 管理员邮箱（首次初始化后无法更改）
jwt_secret = "your-secret" # JWT 签名密钥（至少 32 位随机字符串）部署更详细的说明请参考上游项目：cloud-mail 部署文档
系统设置 → 安全 → 全局 API Token 中开启并生成 Token 后，可通过以下接口无需登录查询邮件：
GET /api/admin/mails?limit=20&offset=0&address=user@domain.com
x-admin-auth: <your-token>响应格式：
{
"results": [...],
"count": 100
}| 渠道 | 链接 |
|---|---|
| GitHub | PastKing/xi-mail |
| Telegram 频道 | @pk_oa |
| 上游项目 | eoao/cloud-mail |
如果本项目对你有帮助，欢迎捐款支持持续开发：
| 网络 | 地址 |
|---|---|
| BEP20 (BSC) | 0x555390f5c07cf76cc344f42612196e8669e3586b |
| TRC20 (TRON) | TVqK4thJCsaaVvp1Dah9F5CFZ1iqw75f4G |
本项目基于 MIT License 开源。
原项目 eoao/cloud-mail 同样采用 MIT 许可证，本项目保留原始版权声明。