cloud-mail

English

维护与自动部署以本 Forgejo 仓库为主：main push → Forgejo Actions → Wrangler → 现有生产 Worker。配置保护、Runner 认证、验证与故障处理见部署说明。

部署在 Cloudflare 上的自托管网页邮箱。用自己的域名接收邮件，在浏览器中管理多个邮箱地址、阅读和回复邮件，并按收件地址将通知转发到 Telegram。

这是基于 maillab/cloud-mail 维护的定制分支，包含独立收件转发规则，并在开发分支同步了上游 d115f4c 的应用功能。仓库没有与应用版本对应的 Release，不应将它视为上游完整版本镜像。

本轮 AI 模型、上游功能、schema 迁移、回归与发布限制见实施报告。已有生产部署必须先审批增量迁移；CI 会拒绝缺列的 schema。

邮件与管理能力

• 多域名、多邮箱地址，收件箱、发件箱、草稿、星标和附件管理；高级搜索、关键词高亮和详情缓存。
• 用户、角色、域名权限、邀请码和发件额度管理。
• Telegram 邮件通知，以及按收件地址设置的目标聊天、发件人和关键词筛选规则；通知关闭链接预览。
• 可选 Workers AI 验证码提取、Turnstile 验证及第三方登录。
• 中文和英文界面、深浅色主题及 PWA 安装入口。

收件由 Cloudflare Email Routing 投递到 Worker。站外发信需要配置 Cloudflare 发件绑定或 Resend；两者都配置时优先使用 Cloudflare。附件可按设置使用 KV、R2 或 S3 兼容存储。收信成功不代表已具备站外发信能力。

部署到自己的账号

准备 Node.js 22、pnpm 9.14.4、Cloudflare 账号，以及托管在 Cloudflare 并可启用 Email Routing 的域名。

1. 安装并创建资源

git clone https://code.inklazy.com/Inklazy/cloud-mail.git
cd cloud-mail/mail-worker
pnpm install --frozen-lockfile
pnpm exec wrangler login
pnpm exec wrangler d1 create mail
pnpm exec wrangler kv namespace create mail-kv

在 mail-worker/wrangler.toml 中替换为自己创建的 D1 / KV ID，保留绑定名 db、kv 和 assets。仓库中的资源 ID 属于现有部署，不能直接用于你的账号。若启用可选存储或发件服务，再配置 r2 / email 绑定；AI 功能使用 ai 绑定。

2. 设置域名和身份

Worker 配置需要以下运行时变量，名称区分大小写：

变量	内容
domain	邮箱域名数组，例如 ["example.com"]
admin	管理员邮箱，例如 admin@example.com，域名应在上面的数组中
jwt_secret	自行生成的高强度随机字符串，用于令牌签名及初始化校验

将 domain、admin 配置到 [vars]，通过 Cloudflare 的 Secret 管理设置 jwt_secret，不要提交真实密钥。初始化地址将密钥作为路径参数使用，应选择不含 URL 路径分隔符的随机值，并避免分享该地址。

配置启用 keep_vars = true，后续部署需保留平台上已有变量。Resend、Telegram、注册策略及角色权限等选项在初始化后的管理界面设置。

3. 构建、部署并初始化

在 mail-worker/ 执行：

pnpm run deploy

Wrangler 的构建钩子会安装前端依赖并构建 Vue，将静态资源输出到 mail-worker/dist/，与 API 一起部署。默认前端 API 路径为 /api，无需单独部署 Pages。

仅对自己的新部署，访问 https://<Worker域名>/api/init/<jwt_secret>，确认返回 success。随后打开站点，用 admin 指定的邮箱注册账号并登录；管理员身份按邮箱匹配，没有仓库预设密码。

在 Cloudflare Email Routing 中把所需地址或 Catch-all 路由到该 Worker，并按平台提示完成域名记录配置。需要站外发送时，再完成所选发件服务的域名验证。已有生产部署更新前应先备份数据、核对迁移内容，不要把初始化接口当作每次发布的固定步骤。

本地开发与检查

mail-worker/ 是 Hono API、邮件事件和定时任务，使用 D1 与 Drizzle ORM；mail-vue/ 是 Vue 3、Vite、Element Plus 和 Pinia 界面。

后端单元测试：

cd mail-worker
pnpm install --frozen-lockfile
pnpm exec vitest run --config vitest.unit.config.js

pnpm test / pnpm run test:unit 现已运行相同的本地测试，不再部署远端。使用项目固定的 pnpm 9.14.4；完整构建后可在仓库根目录运行 node ci/test-worker-local.mjs（隔离 D1/KV）和 node ci/test-browser.mjs（本地浏览器回归）。

本地联调前，将 wrangler-dev.toml 改为隔离测试资源、测试域名和自己的开发密钥，并按初始化流程准备本地数据库。前端需先构建一次以提供 Worker 静态资源目录：

cd mail-vue
pnpm install --frozen-lockfile
pnpm run build
pnpm run dev

另一个终端在 mail-worker/ 执行 pnpm run dev。前端默认为 http://localhost:3001，开发 API 指向 http://127.0.0.1:8787/api。本地页面与单元测试不能代替真实邮件投递、Telegram 通知或站外发信验收。

正文清洗另有浏览器用例，前端开发服务启动后访问 /test/email-html.browser.html。当前分支的修复范围、验证方法和已知问题见维护记录：邮件处理 CPU 超限、重试重复入库及未完成保存状态的恢复仍需后续处理。

项目采用 MIT 许可证。