skip to content
Logo Warming Space

MoeMail GitHub Actions 部署图文教程

/ 12 min read

教程，github

本文档将提供一个详细的分步指南，帮助你使用 GitHub Actions 将 MoeMail 项目部署到 Cloudflare Pages。我们将重点介绍如何获取部署过程中所需的每一个环境变量。

Github Actions 部署

前期准备

  1. 一个 Cloudflare 账户: 如果没有，请先注册。

  2. 一个 GitHub 账户: 你将在这里完成所有操作。

  3. Fork 项目: 打开 MoeMail 项目主页，点击右上角的 “Fork” 按钮，将项目复刻到你自己的 GitHub 仓库中。后续所有操作都在你 Fork 的仓库里进行。

第一步：获取 Cloudflare 账户 ID (CLOUDFLARE_ACCOUNT_ID)

  1. 登录到 Cloudflare 仪表板。

  2. 在主页的右侧栏，你可以直接找到并复制你的 账户 ID。

第二步：创建并获取 Cloudflare API 令牌 (CLOUDFLARE_API_TOKEN)

这个令牌将授权 GitHub Actions 操作你的 Cloudflare 账户资源。此步骤至关重要，请确保权限正确。

  1. 在 Cloudflare 仪表板，点击右上角的头像，选择 “我的个人资料”。

  2. 在左侧菜单中选择 “API 令牌”。

  3. 点击 “创建令牌”。

  4. 在“自定义令牌”部分，点击 “创建自定义令牌” 旁边的 “开始使用” 按钮。

  5. 令牌命名: 给你的令牌起一个容易识别的名字，例如 moemail-deploy-token。

  6. 配置权限 (Permissions): 这是最关键的一步。你需要为令牌添加以下四项权限，全部选择账户(Account)类型，并赋予编辑(Edit)权限：

    • Cloudflare Pages: 编辑(Edit)

    • Workers & Pages D1: 编辑(Edit)

    • Workers KV Storage: 编辑(Edit)

    • Workers Scripts: 编辑(Edit)

  7. 账户资源 (Account Resources): 确保设置为 包括 (Include) -> 特定账户 (Specific account) -> 你的账户。

  8. 继续以生成摘要: 点击页面底部的蓝色按钮。

  9. 创建令牌: 在摘要页面，确认信息无误后，点击 “创建令牌”。

  10. 复制令牌: Cloudflare 会生成一个令牌。这是你唯一一次看到这个令牌的机会，请立即复制并妥善保管。如果丢失，只能重新生成。

第三步：创建 GitHub OAuth App 并获取 ID 和 Secret

这将用于 MoeMail 的 GitHub 登录功能。

  1. 登录 GitHub，点击右上角你的头像，选择 “Settings”。

  2. 在左侧菜单最下方，选择 “Developer settings”。

  3. 选择 “OAuth Apps”，然后点击 “New OAuth App”。

  4. 填写 App 信息:

    • Application name: 任意填写，例如 MoeMail。

    • Homepage URL: 你的网站主页。这里可以先预估一个地址，部署成功后再来修改。

      • 如果你打算使用自定义域名（例如 moemail.yourdomain.com），就填写 https://moemail.yourdomain.com。

      • 如果你不使用自定义域名，可以预估为 https://moemail.pages.dev (这里的 moemail 是你计划使用的 PROJECT_NAME)。

    • Authorization callback URL: 这是最重要的一步。格式为 [你的主页 URL]/api/auth/callback/github。

      • 例如：https://moemail.pages.dev/api/auth/callback/github

  5. 获取 ID 和 Secret:

    • 创建成功后，页面会显示 Client ID。这就是 AUTH_GITHUB_ID。

    • 点击 “Generate a new client secret” 生成一个客户端密码。这个密码也只显示一次，请立即复制。这就是 AUTH_GITHUB_SECRET。

第四步：生成 NextAuth Secret (AUTH_SECRET)

这是一个用于加密会话（Session）的随机字符串，你可以通过以下任何一种方式生成。

  • 使用在线工具: 搜索 “random string generator” 或 “password generator” 生成一个 32 位以上的随机字符串。

  • 使用命令行 (推荐):

    • 在 Linux 或 macOS 的终端中，运行以下命令：

      openssl rand -hex 32

    • 这会生成一个 64 个字符的十六进制字符串，复制它即可。

第五步：整理所有变量值

现在，你应该已经获得了以下所有值：

  • CLOUDFLARE_API_TOKEN: 从第二步获得的 Cloudflare API 令牌。

  • CLOUDFLARE_ACCOUNT_ID: 从第一步获得的 Cloudflare 账户 ID。

  • AUTH_GITHUB_ID: 从第三步获得的 GitHub OAuth App Client ID。

  • AUTH_GITHUB_SECRET: 从第三步获得的 GitHub OAuth App Client Secret。

  • AUTH_SECRET: 从第四步生成的随机字符串。

以下变量是可选的，如果你不设置，将使用项目默认值。

  • CUSTOM_DOMAIN: 你的自定义域名 (例如 moemail.yourdomain.com)。如果留空，将使用 Cloudflare Pages 的默认域名 (<PROJECT_NAME>.pages.dev)。

  • PROJECT_NAME: Cloudflare Pages 项目名，默认是 moemail。

  • DATABASE_NAME: D1 数据库名称，默认是 moemail-db。

  • KV_NAMESPACE_NAME: KV 存储的名称，默认是 moemail-kv。

第六步：在你的 GitHub 仓库中设置 Secrets

这是最后一步，将你获取的所有密钥安全地存储到你的 GitHub 仓库中，以便 GitHub Actions 可以使用它们。

  1. 进入你 Fork 的 MoeMail 仓库。

  2. 点击 “Settings” -> “Secrets and variables” -> “Actions”。

  3. 在 “Repository secrets” 部分，点击 “New repository secret”。

  4. 逐一添加所有上一步中提到的变量。请确保名称完全匹配。

    • 例如，创建一个名为 CLOUDFLARE_API_TOKEN 的 secret，然后将你复制的令牌粘贴到 “Value” 框中。

    • 重复这个过程，添加所有必需和可选的变量。

    你需要添加的 Secret 列表：

    • CLOUDFLARE_API_TOKEN

    • CLOUDFLARE_ACCOUNT_ID

    • AUTH_GITHUB_ID

    • AUTH_GITHUB_SECRET

    • AUTH_SECRET

    • CUSTOM_DOMAIN (如果不用自定义域名，可以留空或不创建此 secret)

    • PROJECT_NAME (建议添加，即使是默认值)

    • DATABASE_NAME (建议添加，即使是默认值)

    • KV_NAMESPACE_NAME (建议添加，即使是默认值)

第七步：运行 GitHub Actions 进行部署

  1. 在你的仓库中，点击顶部的 “Actions” 标签。

  2. 在左侧选择 “Deploy to Cloudflare Pages” 工作流。

  3. 点击 “Run workflow” 下拉菜单，然后再次点击绿色的 “Run workflow” 按钮。

  4. 部署过程会自动开始。你可以点击工作流来查看实时日志和部署进度。整个过程大约需要几分钟。

第八步：完成和验证

  1. 检查部署: 当 Action 显示绿色对勾时，表示部署成功。

  2. 访问网站:

    • 如果你配置了 CUSTOM_DOMAIN，访问你的自定义域名。

    • 否则，访问 https://<PROJECT_NAME>.pages.dev。

  3. 更新回调 URL: 回到你之前创建的 GitHub OAuth App 设置页面，确保 “Homepage URL” 和 “Authorization callback URL” 与你最终的网站地址完全一致。如果不一致，请更新它们。

至此，整个部署过程就完成了！现在你应该可以正常访问和使用你的 MoeMail 实例了。

在 MoeMail 个人中心页面，可以配置网站的邮箱域名，支持多域名配置，多个域名用逗号分隔 image.png

Cloudflare 邮件路由配置

首次设置电子邮件路由,直接跳过新手指南，然后按照下面步骤部署。

为了使邮箱域名生效，还需要在 Cloudflare 控制台配置邮件路由，将收到的邮件转发给 Email Worker 处理。

  1. 登录 Cloudflare 控制台
  2. 选择您的域名
  3. 点击左侧菜单的 “电子邮件” -> “电子邮件路由”
  4. 如果显示 “电子邮件路由当前被禁用，没有在路由电子邮件”，请点击 “启用电子邮件路由” <image.png
  5. 点击后，会提示你添加电子邮件路由 DNS 记录，点击 “添加记录并启用” 即可 image.png
  6. 配置路由规则：
    • Catch-all 地址: 启用 “Catch-all”
    • 编辑 Catch-all 地址
    • 操作: 选择 “发送到 Worker”
    • 目标位置: 选择刚刚部署的 “email-receiver-worker”
    • 保存image.png

注意事项

  • 确保域名的 DNS 托管在 Cloudflare
  • Email Worker 必须已经部署成功
  • 如果 Catch-All 状态不可用(一直 loading)，请点击路由规则旁边的目标地址, 进去绑定一个邮箱

常见问题与排错 (FAQ)

Q: 部署时遇到 AuthenticationError: 401 错误怎么办？

A: 这个错误明确表示你的 CLOUDFLARE_API_TOKEN 身份验证失败。请按以下步骤排查：

  1. 检查 GitHub Secrets: 确保你在 GitHub 仓库的 Settings -> Secrets 中设置的 CLOUDFLARE_API_TOKEN 和 CLOUDFLARE_ACCOUNT_ID 的名称和值都完全正确，没有多余的空格或字符。

  2. 检查令牌权限: 这是最常见的原因。请严格按照本教程第二步的指示，创建一个自定义令牌，并确保它包含了 Pages、D1、KV 和 Workers Scripts 的 编辑(Edit) 权限。使用模板创建的令牌权限可能不足。

  3. 重新生成令牌: 如果以上两步都无法解决问题，请尝试删除 Cloudflare 上的旧令牌，重新生成一个新令牌，并更新到 GitHub Secrets 中，然后再次运行部署。 Q:我绑定的自定义域名一直处于“验证中”状态，怎么办？

A: 这通常意味着 Cloudflare 无法验证你的域名所有权，根本原因在于 DNS 配置。分两种情况讨论：

如果你的主域名（例如 yourdomain.com）没有托管在 Cloudflare: 你需要去你购买域名的服务商（如 GoDaddy）那里，为你的子域名（如 moemail）添加一条指向 <你的项目名>.pages.dev 的 CNAME 记录。

如果你的主域名（例如 loveximi.de）已经托管在 Cloudflare (即 NameServer 已指向 Cloudflare): 这是最常见的情况。你不需要去域名购买商那里操作，而是应该直接在 Cloudflare 内部完成设置。

登录 Cloudflare 仪表板，选择你的主域名（例如 loveximi.de）。

在左侧菜单中找到并点击 “DNS”。

点击 “添加记录 (Add record)”。

类型 (Type): 选择 CNAME。

名称 (Name): 填写你的子域名，例如 moemail。

目标 (Target): 填写你的 Cloudflare Pages 默认地址，例如 moemail.pages.dev。

代理状态 (Proxy status): 请确保云朵图标是灰色的（仅限 DNS）。等验证通过后，你可以再把它点亮（橙色，代理）。

点击 “保存 (Save)”。

保存后，回到 Pages 项目的自定义域页面，验证应该很快就会通过。

Q: 部署时遇到 Catch-All无法加载出来？ 如果电子邮箱服务Catch-All无法加载出来可以绑定一下目标地址刷新试试。（绑定一个邮箱，验证一下即可）