【Voocii-Portal v1.0.5 更新】可配置的邮件服务

摘要：Voocii-Portal 作为一个现代化的开源自托管博客平台，正式推出了全新的动态可配置邮件服务 (Pluggable Email Service)。本文将详细介绍该服务的功能特性、使用场景以及配置方法，帮助每位博主轻松构建更具互动性的个人站点。

1. 引言与背景

之前友情链接申请，或者在文章下方评论，但由于评论和友链需要站长审核，访客在提交后往往无法第一时间获知审核结果，导致互动流失。Voocii-Portal v1.0.5 此次更新，正式上线动态可配置邮件服务系统，现在友链申请、评论通过审核后都有自动通知邮件发出。同时，有人评论了用户或访客的文章或评论也会收到通知。

2. 核心架构与功能亮点

🔌 真正可插拔（Pluggable & Zero-Overhead）

按需开启：在配置文件中控制开关。若未开启，邮件服务处于静默关闭状态，不产生任何额外网络请求与性能开销。
无缝回退：即使配置错误或第三方邮件 API 服务中断，审核与数据更新流程依然正常完成，确保站点核心业务绝不崩溃。
轻量解耦：采用原生 fetch 与轻量级 API 封装，无须额外引入庞大的第三方 SDK。

🌐 多厂商支持 (Multi-Provider)

目前系统原生内置并支持两大主流邮件服务提供商：

Mailgun：支持自定义 Domain、API Key 以及 Base URL（方便兼容不同区域节点）。
SendGrid：基于 SendGrid v3 Mail Send API 与 Bearer Auth，支持快速对接。

架构设计解耦，未来可无缝扩展 SMTP、Resend、Postmark 等服务商。

🗣️ 智能多语言适配 (Locale-Aware Templates)

系统会在访客提交申请或评论时，自动持久化记录访客当前的语言环境（如 zh / en）。当站长在后台审核通过时，系统会自动匹配对应语言的 HTML / Plain-Text 邮件模板，确保海外与本土访客均能获得最佳体验。

3. 已支持的服务场景

目前邮件服务已在以下互动场景中启用：

个人中心通知偏好控制：
- 站点开启邮件服务后，已登录用户可在个人中心（/profile）自主选择是否接收邮件通知。
- 若站点未开启邮件服务，通知控制选项自动隐藏，无感保持界面清爽。
文章作者与评论回复提醒：
- 读者在文章下方发表新评论后，系统实时向文章作者发送邮件通知。
- 当评论收到其他人的回复时，系统自动向原评论作者发送回复提醒邮件。
友情链接申请审核通知：
- 访客在 /links 页面提交友链申请并留下联系邮箱。
- 站长在后台审核通过该申请后，系统自动向申请人邮箱发送审核通过通知邮件，附带站点链接与上线提示。
游客评论审核通知：
- 未登录游客在文章下方发表评论并留存邮箱。
- 评论通过站长审核后，系统自动发送发布成功通知，并附带文章引用与直达评论位置的链接。

4. 快速上手配置指南

只需两步即可在博客上启用邮件通知服务。

步骤 1：在 `site.config.ts` 中开启服务

打开项目中的 apps/web/src/site.config.ts 文件，添加 email 配置段落：

import { defaultAboutConfig, defineConfig } from '@portal/config';

const siteConfig = defineConfig({
  // ...

  // 开启可插拔邮件服务配置
  email: {
    enabled: true,        // 设置为 true 以启用邮件通知
    provider: 'mailgun',  // 可选 'mailgun' 或 'sendgrid'
  },

  // ...
});

export default siteConfig;

步骤 2：在 `.env` 中配置环境变量

在站点根目录的 .env 文件中补充发件人信息与 API 凭证：

基础发件人配置

# 发件人显示名称与发件地址
EMAIL_SERVICE_SENDER_NAME="Voocii Support"
EMAIL_SERVICE_SENDER_ADDRESS="support@voocii.com"

选项 A：使用 Mailgun (推荐)

Mailgun有永久免费额度，每月免费3000封邮件，对于大多数个人博客来说，这个额度是完全足够的了。

EMAIL_SERVICE_BASE_URL="https://api.mailgun.net"
EMAIL_SERVICE_DOMAIN="voocii.com"
EMAIL_SERVICE_API_KEY="your-mailgun-api-key"

选项 B：使用 SendGrid

SendGrid 只有 2 个月的免费额度，但付费计划比 Mailgun 便宜，如果博客日均访问量大，邮件发送量大的话，这个更划算。

EMAIL_SERVICE_API_KEY="SG.your-sendgrid-api-key"

Appendix: 邮件服务商关键配置指南

💡 注意：使用 Mailgun 或 SendGrid 发送邮件完全无需任何额外的邮件/ICP备案手续。无论您的域名是在国内还是海外注册，只需在域名 DNS 服务商（如 Cloudflare、阿里云 DNS 等）中添加对应的 DKIM/SPF 解析记录即可完成验证并开始发信。

在您完成 Mailgun/ SendGrid 注册并创建 API Key 后，需要在控制台完成以下关键配置，以确保邮件能够正常送达：

添加自定义域名 (Add a Sending Domain)：
- 添加域名（二选一）
  - Mailgun 官网：找到 Sending -> Domains，点击 Add Domain。
  - SendGrid 官网：找到 Settings -> Sender Authentication，点击 Authenticate Your Domain。
- 输入您的域名（例如 yourdomain.com）。
- 按照页面指引，将 Mailgun/SendGrid 提供的 MX 记录、TXT 记录（SPF/DKIM）和 CNAME 记录添加到您的域名 DNS 服务商（如 Cloudflare）中。
验证 API Key：
- 创建域名后，Mailgun/SendGrid 会生成一个 API Key。
- 将该 Key 填入本站环境变量中的 EMAIL_SERVICE_API_KEY。
设置转发邮箱：

Mailgun API 发邮件时，只要认证域名一致，就可以使用任意地址作为发件人，例如 support@yourdomain.com。那么访客回复邮件时，会回复到这个地址
- Mailgun：在控制台中设置转发规则，将访客的回复转发到您的常用邮箱
  
  Receiving → Routes → Create Route → Match all email 或者设置特定的一个地址 → Forward to your personal email.
- SendGrid：使用Reply-to
  
  SendGrid 配置转发比较麻烦，其中相对简单一点就是在代码里加 replyTo 参数，设置为你的一个真实邮箱地址。
```
const payload = {
   personalizations: [
     {
       to: [{ email: options.to }],
     },
   ],
   from: {
     email: senderAddress,
     name: senderName,
   },
   // --- 添加在这里 ---
   reply_to: {
     email: 'your-real-email@gmail.com', // 用户的回复将发送到这里
     name: 'Support',            // 可选：回复时显示的名称
   },
   // ------------------
   subject: options.subject,
   
   // ...
 };
```

Appendix: 效果图

摘要：Voocii-Portal 作为一个现代化的开源自托管博客平台，正式推出了全新的动态可配置邮件服务 (Pluggable Email Service)。本文将详细介绍该服务的功能特性、使用场景以及配置方法，帮助每位博主轻松构建更具互动性的个人站点。

1. 引言与背景

2. 核心架构与功能亮点

🔌 真正可插拔（Pluggable & Zero-Overhead）

按需开启：在配置文件中控制开关。若未开启，邮件服务处于静默关闭状态，不产生任何额外网络请求与性能开销。
无缝回退：即使配置错误或第三方邮件 API 服务中断，审核与数据更新流程依然正常完成，确保站点核心业务绝不崩溃。
轻量解耦：采用原生 fetch 与轻量级 API 封装，无须额外引入庞大的第三方 SDK。

🌐 多厂商支持 (Multi-Provider)

目前系统原生内置并支持两大主流邮件服务提供商：

Mailgun：支持自定义 Domain、API Key 以及 Base URL（方便兼容不同区域节点）。
SendGrid：基于 SendGrid v3 Mail Send API 与 Bearer Auth，支持快速对接。

架构设计解耦，未来可无缝扩展 SMTP、Resend、Postmark 等服务商。

🗣️ 智能多语言适配 (Locale-Aware Templates)

3. 已支持的服务场景

目前邮件服务已在以下互动场景中启用：

个人中心通知偏好控制：
- 站点开启邮件服务后，已登录用户可在个人中心（/profile）自主选择是否接收邮件通知。
- 若站点未开启邮件服务，通知控制选项自动隐藏，无感保持界面清爽。
文章作者与评论回复提醒：
- 读者在文章下方发表新评论后，系统实时向文章作者发送邮件通知。
- 当评论收到其他人的回复时，系统自动向原评论作者发送回复提醒邮件。
友情链接申请审核通知：
- 访客在 /links 页面提交友链申请并留下联系邮箱。
- 站长在后台审核通过该申请后，系统自动向申请人邮箱发送审核通过通知邮件，附带站点链接与上线提示。
游客评论审核通知：
- 未登录游客在文章下方发表评论并留存邮箱。
- 评论通过站长审核后，系统自动发送发布成功通知，并附带文章引用与直达评论位置的链接。

4. 快速上手配置指南

只需两步即可在博客上启用邮件通知服务。

步骤 1：在 `site.config.ts` 中开启服务

打开项目中的 apps/web/src/site.config.ts 文件，添加 email 配置段落：

import { defaultAboutConfig, defineConfig } from '@portal/config';

const siteConfig = defineConfig({
  // ...

  // 开启可插拔邮件服务配置
  email: {
    enabled: true,        // 设置为 true 以启用邮件通知
    provider: 'mailgun',  // 可选 'mailgun' 或 'sendgrid'
  },

  // ...
});

export default siteConfig;

步骤 2：在 `.env` 中配置环境变量

在站点根目录的 .env 文件中补充发件人信息与 API 凭证：

基础发件人配置

# 发件人显示名称与发件地址
EMAIL_SERVICE_SENDER_NAME="Voocii Support"
EMAIL_SERVICE_SENDER_ADDRESS="support@voocii.com"

选项 A：使用 Mailgun (推荐)

Mailgun有永久免费额度，每月免费3000封邮件，对于大多数个人博客来说，这个额度是完全足够的了。

EMAIL_SERVICE_BASE_URL="https://api.mailgun.net"
EMAIL_SERVICE_DOMAIN="voocii.com"
EMAIL_SERVICE_API_KEY="your-mailgun-api-key"

选项 B：使用 SendGrid

SendGrid 只有 2 个月的免费额度，但付费计划比 Mailgun 便宜，如果博客日均访问量大，邮件发送量大的话，这个更划算。

EMAIL_SERVICE_API_KEY="SG.your-sendgrid-api-key"

Appendix: 邮件服务商关键配置指南

💡 注意：使用 Mailgun 或 SendGrid 发送邮件完全无需任何额外的邮件/ICP备案手续。无论您的域名是在国内还是海外注册，只需在域名 DNS 服务商（如 Cloudflare、阿里云 DNS 等）中添加对应的 DKIM/SPF 解析记录即可完成验证并开始发信。

在您完成 Mailgun/ SendGrid 注册并创建 API Key 后，需要在控制台完成以下关键配置，以确保邮件能够正常送达：

添加自定义域名 (Add a Sending Domain)：
- 添加域名（二选一）
  - Mailgun 官网：找到 Sending -> Domains，点击 Add Domain。
  - SendGrid 官网：找到 Settings -> Sender Authentication，点击 Authenticate Your Domain。
- 输入您的域名（例如 yourdomain.com）。
- 按照页面指引，将 Mailgun/SendGrid 提供的 MX 记录、TXT 记录（SPF/DKIM）和 CNAME 记录添加到您的域名 DNS 服务商（如 Cloudflare）中。
验证 API Key：
- 创建域名后，Mailgun/SendGrid 会生成一个 API Key。
- 将该 Key 填入本站环境变量中的 EMAIL_SERVICE_API_KEY。
设置转发邮箱：

Mailgun API 发邮件时，只要认证域名一致，就可以使用任意地址作为发件人，例如 support@yourdomain.com。那么访客回复邮件时，会回复到这个地址
- Mailgun：在控制台中设置转发规则，将访客的回复转发到您的常用邮箱
  
  Receiving → Routes → Create Route → Match all email 或者设置特定的一个地址 → Forward to your personal email.
- SendGrid：使用Reply-to
  
  SendGrid 配置转发比较麻烦，其中相对简单一点就是在代码里加 replyTo 参数，设置为你的一个真实邮箱地址。
```
const payload = {
   personalizations: [
     {
       to: [{ email: options.to }],
     },
   ],
   from: {
     email: senderAddress,
     name: senderName,
   },
   // --- 添加在这里 ---
   reply_to: {
     email: 'your-real-email@gmail.com', // 用户的回复将发送到这里
     name: 'Support',            // 可选：回复时显示的名称
   },
   // ------------------
   subject: options.subject,
   
   // ...
 };
```

1. 引言与背景

2. 核心架构与功能亮点

🔌 真正可插拔（Pluggable & Zero-Overhead）

🌐 多厂商支持 (Multi-Provider)

🗣️ 智能多语言适配 (Locale-Aware Templates)

3. 已支持的服务场景

4. 快速上手配置指南

步骤 1：在 `site.config.ts` 中开启服务

步骤 2：在 `.env` 中配置环境变量

基础发件人配置

选项 A：使用 Mailgun (推荐)

选项 B：使用 SendGrid

Appendix: 邮件服务商关键配置指南

Appendix: 效果图

Comments (0)