smtp4dev Docker镜像文档

镜像概述

smtp4dev 是一个轻量级虚拟SMTP服务器镜像，专为开发和测试环境设计。它接收所有发送至其的电子邮件但不实际投递，提供Web界面和API用于查看、管理接收的邮件，帮助开发者在不影响真实邮件系统的情况下测试邮件功能。

核心功能与特性

• 虚拟SMTP服务：模拟标准SMTP服务器接收邮件，支持SMTP协议标准命令
• Web管理界面：通过浏览器直观查看所有接收邮件，包括完整邮件头、正文、附件
• API支持：提供RESTful API接口，支持程序化查询和管理邮件数据
• 数据持久化：支持通过数据卷存储邮件数据，容器重启后数据不丢失
• 零实际发送：所有接收邮件仅本地存储，不会转发至真实邮箱，避免垃圾邮件
• 灵活配置：支持通过环境变量自定义端口、存储路径等核心参数

使用场景

• 开发环境中测试邮件发送功能，无需配置真实SMTP服务器
• 验证邮件模板格式、动态内容渲染效果和附件处理逻辑
• 测试邮件发送触发条件、收件人过滤规则和错误处理机制
• 集成CI/CD流程，自动化验证邮件功能正确性
• 教学环境演示邮件传输原理和SMTP协议交互

使用方法

Docker Run 命令示例

基本运行配置（默认端口与数据持久化）：

docker run -d \
  --name smtp4dev \
  -p 3000:80 \          # Web界面端口映射（主机:容器）
  -p 25:25 \            # SMTP服务端口映射
  -v smtp4dev-data:/app/data \  # 挂载数据卷保存邮件
  rnwood/smtp4dev:latest

自定义端口配置示例：

docker run -d \
  --name smtp4dev \
  -p 8080:8080 \        # 自定义Web端口
  -p 587:587 \          # 自定义SMTP端口（如使用TLS提交端口）
  -v ./smtp-data:/app/data \  # 本地目录挂载
  -e SMTP_PORT=587 \     # 设置容器内SMTP端口
  -e WEB_PORT=8080 \     # 设置容器内Web端口
  rnwood/smtp4dev:latest

Docker Compose 配置示例

创建docker-compose.yml文件：

version: '3.8'

services:
  smtp4dev:
    image: rnwood/smtp4dev:latest
    container_name: smtp4dev
    restart: unless-stopped
    ports:
      - "3000:80"       # Web界面访问端口
      - "25:25"         # SMTP服务端口
    volumes:
      - smtp4dev-data:/app/data  # 命名卷存储数据
    environment:
      - LOG_LEVEL=Info  # 日志级别(Debug/Info/Warn/Error)
      - API_ENABLED=true  # 启用API功能
    networks:
      - dev-network     # 可选：连接到应用网络

volumes:
  smtp4dev-data:        # 持久化邮件数据的命名卷

networks:
  dev-network:          # 可选：与其他开发服务共享网络

启动服务：

docker-compose up -d

配置参数与环境变量

Web界面访问

容器启动后，通过浏览器访问 http://localhost:3000（或映射的Web端口），可查看：

• 接收邮件列表（按时间倒序）
• 邮件详情（发件人、收件人、主题、完整内容）
• 附件下载
• API文档与测试界面
• 服务器状态与配置信息

API使用示例

启用API后可通过HTTP请求操作邮件数据：

• 获取所有邮件列表：

  GET http://localhost:3000/api/emails
  

• 获取指定邮件详情（{id}为邮件ID）：

  GET http://localhost:3000/api/emails/{id}
  

• 删除所有邮件：

  DELETE http://localhost:3000/api/emails
  

完整API文档可通过Web界面的"API"选项卡查看。