Django类视图对接Gmail重置密码报SMTPConnectError解决方案

问题背景 #

• 访问/password_reset/路由触发密码重置流程时，抛出SMTPConnectError异常，错误信息为(421, b'Service not available')
• 已完成Gmail账号侧配置：开启两步验证、生成应用专用密码，已将应用密码填入Django配置
• 现有密码重置路由配置：

path('password_reset/', auth_view.PasswordResetView.as_view(), name = 'password_reset'),
path('password_reset_done/', auth_view.PasswordResetDoneView.as_view(), name ='password_reset_done'),
path('password_reset_confirm/<uidb64>/<token>/', auth_view.PasswordResetConfirmView.as_view(), name = 'password_reset_confirm'),
path('reset_password_complete/', auth_view.PasswordResetCompleteView.as_view(), name = 'password_reset_complete'),

• 现有邮件服务配置：

EMAIL_BACKEND = 'django.core.mail.backends.smtp.EmailBackend'
EMAIL_HOST = 'smtp.gmail.com'
EMAIL_USE_TLS = True
EMAIL_PORT =  587
EMAIL_HOST_USER = 'my_googlemail@gmail.com'
EMAIL_HOST_PASSWORD = 'my_gmail_account_app_password'
EMAIL_USE_SSL = False
DEFAULT_FROM_EMAIL = 'Support Team <noreply@support.org>'

修复步骤 #

按优先级依次排查以下问题：

1. 修正发件人地址配置
   Gmail SMTP服务默认强制要求发件人地址必须和SMTP认证使用的账号一致，当前配置中DEFAULT_FROM_EMAIL使用了不属于该Gmail账号的noreply@support.org地址，会被Gmail直接拒绝连接，返回421错误。
   将配置修改为：

   DEFAULT_FROM_EMAIL = 'Support Team <my_googlemail@gmail.com>'
   

   如果需要使用自定义域名作为发件人，需要先在Gmail账号的「发送邮件为」配置中完成该域名邮箱的所有权验证，否则无法通过Gmail SMTP代发。

2. 排查端口连通性问题
   本地网络、服务器防火墙拦截587端口时，也会返回服务不可用错误。先在部署环境执行命令测试连通性：

   telnet smtp.gmail.com 587
   

   如果连接失败，先开放服务器出站方向587端口的访问规则；如果网络规则无法调整，切换为Gmail SSL连接模式，对应配置修改为：

   EMAIL_USE_TLS = False
   EMAIL_PORT = 465
   EMAIL_USE_SSL = True
   

   注意：EMAIL_USE_TLS和EMAIL_USE_SSL不可同时设置为True，否则会触发连接协议冲突。

3. 校验应用密码有效性
   检查EMAIL_HOST_PASSWORD填入的是否为Gmail生成的16位应用专用密码，不要填入Gmail账号的原始登录密码。应用密码生成后仅展示一次，若遗忘需要在Gmail账号安全页重新生成，填入时不要带多余空格或换行。

4. 排除配置覆盖问题
   检查settings.py中是否存在重复定义的邮件配置项，确认没有其他配置文件、环境变量覆盖上述SMTP参数，修改配置后必须重启Django服务才能生效。

验证方法 #

配置修改完成后，先通过Django shell测试邮件发送能力，确认SMTP连接正常：

# 终端执行python manage.py shell进入交互环境
from django.core.mail import send_mail
from django.conf import settings
send_mail(
    subject='SMTP连接测试',
    message='这是一封测试邮件',
    from_email=settings.DEFAULT_FROM_EMAIL,
    recipient_list=['你的测试收件邮箱@example.com'],
    fail_silently=False,
)

测试邮件正常送达后，再访问/password_reset/提交密码重置请求即可正常触发邮件发送，不会再抛出SMTP连接错误。

内容的提问来源于stack exchange，提问作者apollos