loopingz/smtp-relay

smtp-relay 镜像文档

!https://raw.githubusercontent.com/loopingz/aws-smtp-relay/master/docs/aws-smtp-relay-logo.png

镜像概述

smtp-relay 是一个动态SMTP服务器镜像，旨在替代原 aws-smtp-relay 项目。它支持多种功能模式：作为本地调试SMTP服务器将邮件存储到文件夹；将SMTP协议转发至AWS SES API；模拟AWS SES的入站功能（如mail2s3、mail2sqs）及GCP对应功能（如mail2gcpstorage、mail2gcppubsub）。

核心功能与特性

主要功能

• SMTP协议转换：支持将SMTP请求转换为AWS SES API调用
• 多平台集成：可发送至AWS SQS、GCP Pub/Sub等云服务
• 本地存储：将接收的邮件保存到文件系统，用于调试
• 灵活过滤：通过IP白名单、HTTP认证等过滤器控制访问

核心组件

• 过滤器（Filters）：控制是否接受邮件，支持白名单、HTTP认证、静态认证等类型
• 处理器（Processors）：处理已接受的邮件，支持aws（SES/SQS）、gcp（Pub/Sub）、file（文件存储）等类型
• 流程（Flows）：定义过滤器和输出规则的组合，可配置多个流程
• 核心（Core）：协调各组件，负责邮件流捕获与处理

使用场景

• 本地调试：运行本地SMTP服务器，将邮件存储到文件夹查看内容
• AWS SES集成：作为SMTP中继，将邮件通过SES API发送
• 云服务对接：将邮件转发至AWS SQS或GCP Pub/Sub进行后续处理
• 多环境适配：通过配置文件灵活切换开发、测试、生产环境的邮件处理逻辑

详细使用方法

快速启动

替换 aws-smtp-relay

使用Docker命令启动，映射端口并指定配置文件：

bash
docker run -p 10025:10025 loopingz/smtp-relay:latest configs/aws-smtp-relay.jsonc

配置文件格式

配置文件可引用官方JSON Schema验证格式：

json
{
  "$schema": "https://raw.githubusercontent.com/loopingz/smtp-relay/main/config.schema.json"
}

提示：将URL中的main替换为具体版本标签（如v1.0.0），可获取对应版本的配置格式。

配置示例（替换aws-smtp-relay）

json
{
  "$schema": "https://raw.githubusercontent.com/loopingz/smtp-relay/main/config.schema.json",
  "flows": {
    "localhost": {
      "filters": [
        {
          "type": "whitelist",
          "ips": ["regexp:.*"] // 允许所有IP访问SMTP
        }
      ],
      "outputs": [
        {
          "type": "aws",
          "ses": {} // 发送至AWS SES
        }
      ]
    }
  },
  "options": {
    "disableReverseLookup": false,
    "authOptional": true, // 无需认证
    "loggers": [
      {
        "level": "INFO",
        "type": "CONSOLE" // 控制台日志
      },
      {
        "level": "INFO",
        "type": "FILE",
        "filepath": "./smtp.log" // 文件日志
      }
    ]
  }
}

本地开发运行

将邮件存储到本地文件夹：

bash
# 无认证模式
docker run -p 10025:10025 -v `pwd`/emails:/smtp-relay/received_emails loopingz/smtp-relay:latest ./configs/fake-smtp.jsonc

# 带认证模式
docker run -e SMTP_USERNAME=test -e SMTP_PASSWORD=plain:test -p 10025:10025 -v `pwd`/emails:/smtp-relay/received-emails loopingz/smtp-relay:latest configs/fake-smtp-with-auth.jsonc

SMTP 2 GCP Storage配置示例

json
{
  "flows": {
    "localhost": {
      "filters": [
        {
          "type": "whitelist",
          "to": ["regexp:.*@mydomain.com"] // 过滤收件人为指定域名的邮件
        }
      ],
      "outputs": [
        {
          "type": "gcp",
          "path": "gs://myemail/", // 存储至GCP Storage桶
          "pubsub": "" // 可选：发送消息至Pub/Sub队列
        }
      ]
    }
  },
  "options": {
    "disableReverseLookup": false,
    "authOptional": true
  }
}

配置详解

通用变量替换

配置中可使用以下变量（处理器内可用）：

• _iso8601_：日期时间（YYYYmmddHHiiss格式）
• _timestamp_：UNIX时间戳
• _id_：会话ID
• _from_：发件人***
• _messageId_：邮件ID
• _subject_：邮件主题
• _to_：收件人列表（逗号分隔）

日志配置

支持CONSOLE（控制台）和FILE（文件）类型日志，配置示例：

json
"loggers": [
  {
    "level": "INFO", // 日志级别：DEBUG/INFO/WARN/ERROR
    "type": "CONSOLE"
  },
  {
    "level": "INFO",
    "type": "FILE",
    "filepath": "./smtp.log", // 日志文件路径
    "sizeLimit": 50000000 // 文件大小限制（字节），超过自动分割
  }
]

过滤器配置

白名单过滤器（whitelist）

允许指定IP或收件人：

json
{
  "type": "whitelist",
  "ips": ["regexp:192\\.168\\..*"], // 允许192.168网段IP
  "to": ["regexp:.*@example\\.com"] // 允许发往example.com的邮件
}

HTTP认证过滤器（http-auth）

将认证请求转发至HTTP端点：

json
{
  "type": "http-auth",
  "url": "http://localhost:16662/smtp/filter", // 认证端点URL
  "method": "POST",
  "credentialsMethod": "BASIC_AUTH", // 使用Basic Auth传递凭据
  "json_result": { // 可选：验证响应JSON内容
    "path": "$.allowed",
    "value": "true"
  }
}

静态基本认证（Static Basic Auth）

通过配置文件或环境变量设置用户名密码，示例配置：

json
{
  "type": "static-auth"
}

环境变量设置：

• SMTP_USERNAME：用户名
• SMTP_PASSWORD：密码（格式：哈希算法:哈希值，如sha256:abc123...）
• SMTP_PASSWORD_SALT：可选盐值

密码加密命令

生成加密密码（以sha256为例）：

bash
HASH="sha256" PASSWORD="TEST" node -e 'console.log(`${process.env.HASH}:${require("crypto").createHash(process.env.HASH).update(process.env.PASSWORD).digest("hex")}`)'

处理器配置

AWS处理器

发送至SES或SQS：

json
{
  "type": "aws",
  "ses": {}, // 发送至SES
  "sqs": { "queueUrl": "https://sqs.us-east-1.amazonaws.com/123456789012/my-queue" } // 可选：发送至SQS
}

文件处理器

存储邮件到文件系统：

json
{
  "type": "file",
  "path": "./received_emails/${_iso8601_}_${_id_}.eml" // 使用变量生成文件名
}

CloudEvent数据结构

邮件的CloudEvent表示格式：

typescript
interface SmtpCloudEvent {
  email: {
    from?: AddressObject; // 发件人
    attachments: { filename: string; size: number }[]; // 附件
    subject?: string; // 主题
    to?: AddressObject[]; // 收件人
    cc?: AddressObject[]; // 抄送
    bcc?: AddressObject[]; // 密送
    replyTo?: string; // 回复地址
    date?: Date; // 日期
    text?: string; // 文本内容
    html?: string; // HTML内容
  };
  server: {
    clientHostname: string; // 客户端主机名
    remoteAddress: string; // 客户端IP
    remotePort: number; // 客户端端口
    hostNameAppearAs: string; // 服务器显示名称
    id: string; // 会话ID
    secure: boolean; // 是否加密传输
    transmissionType: string; // 传输类型
    username: string; // 认证用户名
  };
}

手动测试SMTP协议

使用openssl连接SMTP服务器，手动发送邮件：

1. 启动容器并映射端口：

bash
docker run -p 10025:10025 loopingz/smtp-relay:latest

2. 连接SMTP服务器：

bash
openssl s_client -connect localhost:10025

3. 发送SMTP命令（示例）：

EHLO client.example.com
AUTH LOGIN
<base64编码的用户名>
<base64编码的密码>
MAIL FROM: <sender@example.com>
RCPT TO: <recipient@example.com>
DATA
Subject: Test Email

Hello World!
.
QUIT

提示：使用base64 <<< "username"命令生成base64编码的凭据。