Mailpit项目中TLS/SSL证书配置问题的解决方案

问题背景

在使用Mailpit邮件测试工具时，许多开发者会遇到TLS/SSL证书配置问题。一个典型错误是容器日志中显示"TLS key not found or readable"（TLS密钥未找到或不可读）。这个问题通常与Docker Compose配置和证书文件权限有关。

错误分析

从实际案例来看，用户遇到的主要问题是：

1. 证书文件虽然存在但容器无法读取
2. Docker Compose配置中存在语法错误
3. TLS相关环境变量设置冲突

解决方案详解

1. 修正YAML语法错误

最常见的错误是在Docker Compose文件中使用了错误的YAML语法。例如：

# 错误写法（包含=:）
MP_SMTP_TLS_KEY=: '/certs/localhostKey.pem'

# 正确写法
MP_SMTP_TLS_KEY: '/certs/localhostKey.pem'

这个细微的语法差异会导致路径解析错误，使Mailpit无法正确找到证书文件。

2. 合理的TLS配置选项

Mailpit提供了多个TLS相关配置选项，但不应该同时启用冲突的设置：

• MP_SMTP_REQUIRE_STARTTLS：要求使用STARTTLS
• MP_SMTP_REQUIRE_TLS：要求直接使用TLS
• 两者不应同时设置为true

对于测试环境，推荐使用STARTTLS，因为它更接近实际邮件服务器的常见配置。

3. 认证配置

同样需要注意认证相关的配置选项：

• MP_SMTP_AUTH_ACCEPT_ANY：接受任何认证
• MP_SMTP_AUTH：指定具体的用户名密码组合
• 两者也不应同时设置

4. 推荐配置示例

基于实际测试需求，推荐以下配置：

services:
  mailpit:
    image: axllent/mailpit
    volumes:
      - './docker/mailpit/data:/data'
      - './docker/certs:/certs'
    ports:
      - 8025:8025
      - 1025:1025
    environment:
      MP_MAX_MESSAGES: 5000
      MP_DATABASE: /data/mailpit.db
      MP_SMTP_TLS_KEY: '/certs/localhostKey.pem'
      MP_SMTP_TLS_CERT: '/certs/localhostCert.pem'
      MP_SMTP_REQUIRE_STARTTLS: true
      MP_SMTP_AUTH: "webmaster:password info:password"

5. 自签名证书注意事项

在测试环境中使用自签名证书时，需要注意：

1. 确保证书文件具有正确的权限，容器用户可以读取
2. 在客户端配置中信任自签名证书
3. 证书文件路径在容器内可访问

总结

通过修正YAML语法错误、合理配置TLS选项、正确设置认证参数，可以解决Mailpit中的TLS/SSL证书问题。对于测试环境，使用自签名证书配合STARTTLS是一个实用的解决方案。开发者应根据实际测试需求选择合适的配置组合，避免设置冲突的选项。