Cloudflare mail-worker 部署与邮箱恢复问题完整笔记

一、关于 mail-worker 部署的核心问题

1.1 根目录设置问题

问题： 在 Cloudflare 上部署两个 GitHub 上的 mail-worker，根目录都写 /mail-worker 是否正确？

结论： 不正确。

• 同一个 GitHub 仓库中的 mail-worker 文件夹只能作为一个 Worker 的构建源
• 部署两个 Worker 指向相同根目录会导致资源冲突和路由冲突
• cloud-mail 项目的目录结构中，mail-worker 是后端代码所在文件夹，包含 Worker 入口文件 src/index.js 和配置文件 wrangler.toml

1.2 正确部署方式

• 只需要创建一个 Worker
• 根目录设置为 /mail-worker
• 使用 mail-worker/wrangler.toml 中的 name 字段作为 Worker 名称

错误尝试： 将第二个 Worker 根目录改为 /zmail-worker 会报错 "root directory not found"，因为仓库中不存在该文件夹。

1.3 Wrangler 配置提示

系统提示：在 Wrangler v3.109.0+ 版本，如果 wrangler.toml 中的 name 与 Cloudflare 上的 Worker 名称不匹配，系统会自动生成 PR 来修复配置。

示例配置：

name = 'zcloud-mail'
main = "src/index.ts"
compatibility_date = "2024-12-18"

1.4 补救措施

如果误部署了两个 Worker：

1. 确认哪个 Worker 是有效的（检查名称、部署状态、路由绑定）
2. 删除第二个 Worker
3. 验证剩余 Worker 正常工作

二、API Token 权限问题

错误提示：

Note: This API token is missing the following permissions:
    email_routing_account_rule_read
    email_routing_rule_write

含义： 当前使用的 API 令牌缺少管理邮件路由（Email Routing）所需的权限。

解决方法：

1. 登录 Cloudflare Dashboard → My Profile → API Tokens
2. 找到正在使用的令牌，点击 Edit

3. 添加以下权限：

   • Account 类别 → Email Routing Addresses → Read
   • Zone 类别 → Email Routing Rules → Edit
4. 保存更新后的令牌

三、多域名部署问题

3.1 是否需要为每个域名部署一次

问题： 有两个域名，要使用 cloud-mail 配合 Resend 实现域名邮箱，是否需要部署两次？

结论： 不需要。一个 Worker 实例可以统一处理所有域名的邮件。

3.2 配置方法

环境变量 admin：

• 类型：纯文本
• 值示例：admin@example.com
• 作用：指定唯一的超级管理员登录账号，与域名数量无关

环境变量 domain：

• 类型：JSON
• 值示例：["example.com", "example2.com"]
• 作用：声明系统需要管理哪些域名下的邮箱

操作步骤：

1. 部署一个 Worker，根目录设置为 /mail-worker
2. 创建并绑定 D1 数据库和 KV 空间
3. 配置 admin、jwt_secret、domain 等环境变量
4. 为每个域名在 Cloudflare 中设置 Email Routing 的 Catch-all 规则，指向该 Worker
5. 在 Resend 中验证主域名，获取 API Key 并在系统设置中填入

四、邮箱恢复问题

4.1 删除邮箱后无法重建

问题： 在 cloud-mail 上删除一个邮箱后，想再次使用时提示"该邮箱已被注销"。

原因分析： 系统执行了"软删除"，邮箱记录在数据库中仍存在，但被标记为已删除状态。

4.2 数据库表结构

执行 SELECT * FROM account 后显示的表结构：

4.3 恢复方法

将 is_del 字段从 1 改回 0：

UPDATE account 
SET is_del = 0 
WHERE email = 'contact@zhaopengpeng.com';

验证修改：

SELECT account_id, email, is_del FROM account WHERE email = 'contact@zhaopengpeng.com';

4.4 恢复后操作

1. 清理缓存： 在 Cloudflare Dashboard 中触发 Worker 重新部署，或等待缓存自动过期
2. 检查关联表： 如果 user 表中也有该邮箱的关联记录且状态异常，需同步更新
3. 备份建议： 操作前在 D1 的"备份"页面创建手动备份

4.5 查询错误处理

如果执行 SELECT id, email, deleted_at, status FROM user 报错 no such column: id：

1. 先查看表结构：

   PRAGMA table_info(user);

2. 根据实际列名修改查询语句（例如使用 uid 而非 id）

3. 检查关联表是否有残留记录：

   SELECT * FROM verify_record WHERE email = '要恢复的邮箱地址';
   SELECT * FROM oauth WHERE email = '要恢复的邮箱地址';

五、更新已部署 Worker 的方法

方案一：Cloudflare 自动构建（推荐）

• 在 Worker 的 Settings > Builds 中连接 GitHub 仓库
• 推送代码到指定分支后，Cloudflare 自动触发构建和部署
• 可在 Deployments 标签页查看构建历史

方案二：手动触发 GitHub Actions

• 打开 GitHub 仓库的 Actions 标签页
• 找到部署工作流（如 Deploy）
• 点击 Run workflow 手动启动部署

方案三：Wrangler CLI 手动部署

npx wrangler login
npx wrangler deploy

注意： 不要重新点击项目的"一键部署"按钮，这可能会创建新的 Worker 及关联资源，导致数据丢失。