Supabase GoTrue服务SMTP配置错误排查指南

问题现象分析

在自托管Supabase环境中，用户配置GoTrue服务的SMTP邮件发送功能时，系统报错dial tcp: lookup supabase-mail on 127.0.0.11:53: no such host。该错误表明Docker容器内部DNS解析失败，无法找到名为"supabase-mail"的主机。

核心问题定位

这种DNS解析错误通常由以下原因导致：

1. 网络模式配置不当：Docker容器默认使用桥接网络，可能导致内部DNS解析异常
2. 服务命名错误：在docker-compose文件中可能错误引用了不存在的服务名称
3. 环境变量传递失败：虽然用户已配置.env文件，但变量可能未被正确加载

解决方案详解

网络配置修正方案

1. 显式网络声明：在docker-compose.yml中明确定义bridge网络

networks:
  supabase-network:
    driver: bridge
    internal: true

2. 服务关联网络：确保所有相关服务都连接到该网络

services:
  gotrue:
    networks:
      - supabase-network

SMTP配置最佳实践

1. 直接使用IP地址：对于内部服务，建议直接使用容器IP而非主机名
2. 完整环境检查：验证所有SMTP参数是否完整：
   • SMTP_HOST应为可解析的域名或IP
   • SMTP_PORT需与服务端配置一致（通常587或465）
   • 认证方式需与服务端匹配（plain/login/cram-md5）

配置验证步骤

1. 进入GoTrue容器执行DNS测试：

docker exec -it gotrue_container nslookup your-smtp-host

2. 测试SMTP连接：

telnet smtp.example.com 587

3. 检查环境变量是否生效：

docker exec -it gotrue_container env | grep SMTP

深度技术原理

Docker的DNS解析机制在用户自定义网络中会自动为每个容器创建DNS记录。当使用默认bridge网络时，这种自动解析不可用，必须通过links或extra_hosts手动配置。对于关键服务，建议：

1. 使用自定义的bridge网络而非默认bridge
2. 为关键服务配置静态IP地址
3. 在容器内部使用/etc/hosts文件进行静态解析

预防措施

1. 在docker-compose中启用健康检查：

healthcheck:
  test: ["CMD", "nc", "-z", "smtp-host", "587"]
  interval: 30s
  timeout: 10s
  retries: 3

2. 使用配置验证工具：

docker-compose config

通过以上系统化的配置和验证方法，可以确保Supabase的邮件服务在自托管环境中稳定运行。