sublimesec/render-email-html

Email Previewer Docker镜像文档

镜像概述和主要用途

Email Previewer 是一个轻量级Docker镜像，提供邮件内容在用户端呈现效果的预览功能。其核心用途是模拟各类邮件客户端（如Gmail、Outlook、Apple Mail等）的渲染环境，帮助开发者、测试人员及产品人员直观查看HTML/CSS邮件在不同客户端的实际显示效果，确保邮件格式一致性和兼容性。

核心功能和特性

核心功能

• 多客户端渲染模拟：支持模拟主流邮件客户端（Gmail、Outlook、*** Mail、Apple Mail等）的HTML/CSS解析规则，还原真实渲染效果。
• HTML/CSS邮件解析：完整支持标准HTML5和内联CSS邮件语法，处理邮件特有的CSS限制（如不支持外部样式表、部分CSS属性）。
• 实时预览：提交邮件内容后即时生成预览结果，支持动态调整邮件内容并刷新预览。
• 响应式布局支持：模拟不同设备（桌面、移动端）屏幕尺寸下的邮件响应式布局渲染效果。
• 渲染问题提示：自动检测常见邮件渲染问题（如不兼容CSS属性、图片加载失败）并给出提示。

特性

• 轻量级：镜像体积小（<200MB），启动速度快，资源占用低。
• 易于集成：支持HTTP API和Web界面两种交互方式，可快速集成到现有开发/测试流程。
• 跨平台兼容：基于Docker容器化，支持Linux、macOS、Windows等主流操作系统。
• 无状态设计：不存储邮件内容，仅临时处理预览请求，保障数据安全。

使用场景和适用范围

典型使用场景

• 邮件模板开发：开发者测试HTML邮件模板在不同客户端的渲染效果，验证样式兼容性。
• QA流程验证：测试团队在邮件发送前，通过预览功能确认邮件内容、格式、图片等元素的显示正确性。
• 产品预览：产品/运营人员预览邮件最终呈现效果，确认文案、排版符合设计要求。
• CI/CD集成：作为自动化测试环节，在邮件模板更新后自动触发预览检查，拦截渲染异常。

适用范围

• 目标用户：邮件模板开发者、QA工程师、产品经理、邮件营销团队。
• 使用规模：个人开发者、中小企业、大型企业的邮件开发/测试流程。

使用方法和配置说明

前提条件

• 已安装Docker Engine（20.10+）或Docker Desktop。
• 网络环境可访问Docker Hub（用于拉取镜像）。

获取镜像

通过Docker Hub拉取最新版本镜像：

bash
docker pull emailpreviewer:latest

运行容器

基础运行命令

bash
docker run -d \
  --name email-preview \
  -p 8080:8080 \
  emailpreviewer:latest

• -p 8080:8080：将容器内8080端口映射到主机8080端口，用于访问Web服务。
• --name email-preview：指定容器名称为email-preview。

配置参数

环境变量

通过-e参数设置环境变量，配置服务行为：

卷挂载

如需持久化存储预览历史记录或加载本地邮件模板，可挂载主机目录到容器内/data路径：

bash
docker run -d \
  --name email-preview \
  -p 8080:8080 \
  -v /local/mail-templates:/data/templates \  # 挂载本地邮件模板目录到容器
  -e PORT=80 \                                # 自定义服务端口为80
  emailpreviewer:latest

网络配置

如需集成到现有Docker网络（如与邮件发送服务联动），可通过--network指定网络：

bash
docker run -d \
  --name email-preview \
  --network my-network \  # 加入现有网络
  -p 8080:8080 \
  emailpreviewer:latest

使用示例

Web界面预览

1. 容器启动后，访问http://<主机IP>:8080打开Web预览界面。
2. 在输入框中粘贴HTML邮件代码（或上传本地HTML文件）。
3. 选择目标邮件客户端（如Gmail、Outlook）和设备类型（桌面/移动端）。
4. 点击“生成预览”，界面将展示模拟渲染效果。

API调用预览

通过HTTP POST请求提交邮件内容，获取JSON格式的预览结果：

bash
curl -X POST http://localhost:8080/api/preview \
  -H "Content-Type: text/html" \
  -d @"path/to/email.html"  # 本地HTML邮件文件

响应示例：

json
{
  "previewId": "abc123",
  "clients": {
    "gmail": "http://localhost:8080/preview/abc123/gmail",  // Gmail预览图URL
    "outlook": "http://localhost:8080/preview/abc123/outlook" // Outlook预览图URL
  },
  "warnings": ["CSS property 'flex' is not supported in Outlook 2016"]  // 渲染警告
}

Docker部署方案示例

docker run命令示例（完整配置）

bash
docker run -d \
  --name email-preview \
  -p 8080:8080 \
  -v /opt/email-templates:/data/templates \
  -e PORT=8080 \
  -e LOG_LEVEL=debug \
  -e CORS_ALLOW_ORIGIN="https://mail-dev.example.com" \
  -e MAX_EMAIL_SIZE=10485760 \  # 10MB
  --restart unless-stopped \
  emailpreviewer:latest

docker-compose.yml示例

yaml
version: '3.8'

services:
  email-preview:
    image: emailpreviewer:latest
    container_name: email-preview
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      - PORT=8080
      - LOG_LEVEL=info
      - CORS_ALLOW_ORIGIN="https://mail-dev.example.com,https://qa.example.com"
      - MAX_EMAIL_SIZE=5242880
    volumes:
      - /opt/email-templates:/data/templates
    networks:
      - mail-dev-network

networks:
  mail-dev-network:
    driver: bridge

配置参数详解