changemakerstudiosus/papercut-smtp

Papercut SMTP Docker镜像文档

!https://raw.githubusercontent.com/ChangemakerStudios/Papercut/develop/graphics/PapercutLogo.png
简单的桌面邮件助手

问题背景

在开发过程中从应用程序或网站发送邮件时，您可能会担心测试邮件意外发送到真实地址（如同事或客户）。虽然可以搭建测试邮件服务器，但维护繁琐且查看邮件的延迟会拖慢开发周期。

Papercut SMTP解决方案

Papercut SMTP是一个二合一工具：快速邮件查看器和内置SMTP服务器（仅用于接收邮件）。它不对邮件的准备方式施加任何限制，但允许您查看完整邮件内容：正文、HTML、头信息和附件。此Docker镜像运行Papercut SMTP服务，并包含用于查看邮件的嵌入式Web UI。

---

快速开始

bash
# 拉取最新镜像
docker pull changemakerstudiosus/papercut-smtp:latest

# 使用默认配置运行
docker run -d \
  --name papercut \
  -p 37408:8080 \
  -p 2525:2525 \
  changemakerstudiosus/papercut-smtp:latest

访问Web UI： http://localhost:37408

发送测试邮件到： localhost:2525

---

端口配置

Docker镜像默认使用非特权端口，允许容器在无需root权限的情况下安全运行：

为什么使用非特权端口？

1024以下的端口（如25和80）在Linux中需要特殊权限。通过使用2525和8080端口，Papercut可以安全运行，无需：

• root/管理员权限
• --sysctl标志
• 特殊容器功能

映射到传统端口

如果需要在主机上使用传统端口，可以进行如下映射：

bash
# 映射到主机的传统端口
docker run -d \
  --name papercut \
  -p 80:8080 \
  -p 25:2525 \
  changemakerstudiosus/papercut-smtp:latest

访问： http://localhost（端口80）| SMTP： localhost:25

---

配置

使用环境变量

通过环境变量覆盖默认配置：

bash
docker run -d \
  --name papercut \
  -e SmtpServer__IP=0.0.0.0 \
  -e SmtpServer__Port=2525 \
  -e Urls=http://0.0.0.0:8080 \
  -p 8080:8080 \
  -p 2525:2525 \
  changemakerstudiosus/papercut-smtp:latest

可用环境变量：

• SmtpServer__IP - SMTP监听地址（默认："Any" = 0.0.0.0）
• SmtpServer__Port - SMTP监听端口（默认：2525，使用587启用STARTTLS）
• SmtpServer__MessagePath - 邮件存储路径（默认：/app/Incoming）
• SmtpServer__LoggingPath - 日志文件路径（默认：/app/logs）
• Urls - HTTP服务器URLs（默认：[***]

TLS/STARTTLS配置（可选）：

• SmtpServer__CertificateFindType - 证书搜索方法（默认："FindBySubjectName"）
• SmtpServer__CertificateFindValue - 证书标识符（为空则禁用TLS）
• SmtpServer__CertificateStoreLocation - 存储位置："LocalMachine"或"CurrentUser"（默认："LocalMachine"）
• SmtpServer__CertificateStoreName - 存储名称："My"、"Root"等（默认："My"）

使用自定义配置文件

挂载自定义appsettings.Production.json：

bash
docker run -d \
  --name papercut \
  -v /path/to/your/appsettings.Production.json:/app/appsettings.Production.json:ro \
  -p 8080:8080 \
  -p 2525:2525 \
  changemakerstudiosus/papercut-smtp:latest

示例appsettings.Production.json：

json
{
  "Urls": "http://0.0.0.0:8080",

  "SmtpServer": {
    "IP": "Any",
    "Port": 2525,
    "MessagePath": "/app/Incoming",
    "LoggingPath": "/app/logs"
  }
}

---

持久化邮件消息

默认情况下，邮件存储在容器内部，容器删除后会丢失。要持久化邮件，可挂载卷：

使用Docker命名卷

bash
docker run -d \
  --name papercut \
  -p 37408:8080 \
  -p 2525:2525 \
  -v papercut-messages:/app/Incoming \
  changemakerstudiosus/papercut-smtp:latest

使用主机目录

bash
docker run -d \
  --name papercut \
  -p 37408:8080 \
  -p 2525:2525 \
  -v /path/on/host/messages:/app/Incoming \
  changemakerstudiosus/papercut-smtp:latest

---

Docker Compose

创建docker-compose.yml：

yaml
version: '3.8'

services:
  papercut:
    image: changemakerstudiosus/papercut-smtp:latest
    container_name: papercut-smtp
    ports:
      - "37408:8080"  # Web UI
      - "2525:2525"   # SMTP
    volumes:
      - papercut-messages:/app/Incoming
      - papercut-logs:/app/logs
    environment:
      - SmtpServer__IP=0.0.0.0
      - SmtpServer__Port=2525
      - Urls=http://0.0.0.0:8080
    restart: unless-stopped

volumes:
  papercut-messages:
  papercut-logs:

运行：

bash
docker compose up -d

---

TLS/STARTTLS和SMTP认证

Papercut SMTP支持可选的TLS/STARTTLS加密和SMTP认证，用于安全的邮件测试。

快速TLS设置

通过环境变量启用STARTTLS：

bash
docker run -d \
  --name papercut-tls \
  -p 8080:8080 \
  -p 587:587 \
  -e SmtpServer__Port=587 \
  -e SmtpServer__CertificateFindType=FindBySubjectName \
  -e SmtpServer__CertificateFindValue=localhost \
  changemakerstudiosus/papercut-smtp:latest

证书要求

TLS/STARTTLS需要X.509证书。证书必须安装在Windows证书存储中（LocalMachine或CurrentUser）。

创建测试用自签名证书（Windows主机）：

powershell
# 创建证书
$cert = New-SelfSignedCertificate `
    -Subject "CN=localhost" `
    -DnsName "localhost" `
    -CertStoreLocation "cert:\LocalMachine\My" `
    -NotAfter (Get-Date).AddYears(2)

# 获取配置用的指纹
$cert.Thumbprint

使用指纹配置Docker：

bash
docker run -d \
  --name papercut-tls \
  -p 8080:8080 \
  -p 587:587 \
  -e SmtpServer__Port=587 \
  -e SmtpServer__CertificateFindType=FindByThumbprint \
  -e SmtpServer__CertificateFindValue=YOUR_THUMBPRINT_HERE \
  changemakerstudiosus/papercut-smtp:latest

Docker Compose配置TLS

yaml
version: '3.8'

services:
  papercut-tls:
    image: changemakerstudiosus/papercut-smtp:latest
    container_name: papercut-smtp-tls
    ports:
      - "8080:8080"
      - "587:587"  # STARTTLS端口
    volumes:
      - papercut-messages:/app/Incoming
      - papercut-logs:/app/logs
    environment:
      # 基本配置
      - SmtpServer__IP=0.0.0.0
      - SmtpServer__Port=587
      - Urls=http://0.0.0.0:8080
      # TLS配置
      - SmtpServer__CertificateFindType=FindByThumbprint
      - SmtpServer__CertificateFindValue=YOUR_CERT_THUMBPRINT
      - SmtpServer__CertificateStoreLocation=LocalMachine
      - SmtpServer__CertificateStoreName=My
    restart: unless-stopped

volumes:
  papercut-messages:
  papercut-logs:

在appsettings.json中配置

也可在自定义appsettings.Production.json中配置TLS：

json
{
  "Urls": "http://0.0.0.0:8080",

  "SmtpServer": {
    "IP": "Any",
    "Port": 587,
    "MessagePath": "/app/Incoming",
    "LoggingPath": "/app/logs",
    "CertificateFindType": "FindByThumbprint",
    "CertificateFindValue": "YOUR_CERT_THUMBPRINT_HERE",
    "CertificateStoreLocation": "LocalMachine",
    "CertificateStoreName": "My"
  }
}

SMTP端口说明

证书搜索方法

SMTP认证

使用TLS/STARTTLS时自动启用SMTP AUTH。默认情况下，Papercut接受所有凭据，用于开发/测试目的。

使用认证测试：

bash
# 使用openssl
openssl s_client -connect localhost:587 -starttls smtp

# 在EHLO响应中应看到：
# 250-STARTTLS
# 250-AUTH PLAIN LOGIN

使用MailKit发送邮件（C#）：

csharp
using var client = new SmtpClient();
client.Connect("localhost", 587, SecureSocketOptions.StartTls);
client.Authenticate("anyuser", "anypass");  // 接受任何凭据
client.Send(message);
client.Disconnect(true);

测试TLS连接

bash
# 测试STARTTLS连接
openssl s_client -connect localhost:587 -starttls smtp

# 预期输出应包含：
# - EHLO响应中的STARTTLS
# - 证书详情
# - "Verify return code: 0 (ok)"或自签名警告

TLS故障排除

证书未找到：

Error: No certificate found matching FindByThumbprint='...'

• 验证证书安装在正确的存储中
• 检查指纹是否正确（移除空格）
• 确保容器可访问主机证书存储

找到多个证书：

Error: Multiple certificates (3) found matching...

• 使用更具体的搜索方法（如指纹而非主题名称）

587端口连接被拒绝：

• 确保端口映射包含587: -p 587:587
• 验证TLS已配置（CertificateFindValue非空）
• 查看日志：docker logs papercut-tls | grep TLS

---

高级示例

IPv6支持

监听IPv6：

bash
docker run -d \
  --name papercut \
  -e SmtpServer__IP=::0 \
  -e Urls=http://[::]:8080 \
  -p 8080:8080 \
  -p 2525:2525 \
  changemakerstudiosus/papercut-smtp:latest

自定义端口

使用完全自定义的端口：

bash
docker run -d \
  --name papercut \
  -e SmtpServer__Port=3025 \
  -e Urls=http://0.0.0.0:9080 \
  -p 9080:9080 \
  -p 3025:3025 \
  changemakerstudiosus/papercut-smtp:latest

带持久存储和自定义配置

bash
docker run -d \
  --name papercut \
  -p 37408:8080 \
  -p 2525:2525 \
  -v papercut-messages:/app/Incoming \
  -v papercut-logs:/app/logs \
  -v $(pwd)/appsettings.Production.json:/app/appsettings.Production.json:ro \
  changemakerstudiosus/papercut-smtp:latest

---

Kubernetes部署

Kubernetes部署示例：

yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: papercut-smtp
  labels:
    app: papercut-smtp
spec:
  replicas: 1
  selector:
    matchLabels:
      app: papercut-smtp
  template:
    metadata:
      labels:
        app: papercut-smtp
    spec:
      containers:
      - name: papercut
        image: changemakerstudiosus/papercut-smtp:latest
        ports:
        - containerPort: 8080
          name: http
          protocol: TCP
        - containerPort: 2525
          name: smtp
          protocol: TCP
        env:
        - name: SmtpServer__Port
          value: "2525"
        - name: Urls
          value: "http://0.0.0.0:8080"
        volumeMounts:
        - name: messages
          mountPath: /app/Incoming
        - name: logs
          mountPath: /app/logs
      volumes:
      - name: messages
        emptyDir: {}
      - name: logs
        emptyDir: {}
---
apiVersion: v1
kind: Service
metadata:
  name: papercut-smtp
  labels:
    app: papercut-smtp
spec:
  type: ClusterIP
  selector:
    app: papercut-smtp
  ports:
  - name: http
    port: 8080
    targetPort: 8080
    protocol: TCP
  - name: smtp
    port: 2525
    targetPort: 2525
    protocol: TCP

应用：

bash
kubectl apply -f papercut-deployment.yaml

测试时通过端口转发访问：

bash
kubectl port-forward svc/papercut-smtp 37408:8080 2525:2525

---

故障排除

端口权限错误

错误： 绑定端口时Permission denied

解决方案： 使用默认非特权端口（2