From 0049f23909fc298036fb5c84ba788b09a9816d86 Mon Sep 17 00:00:00 2001
From: xiaji <rembme@163.com>
Date: Sun, 18 Jan 2026 15:53:00 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=E9=82=AE=E4=BB=B6?=
 =?UTF-8?q?=E5=8A=9F=E8=83=BD=E6=B5=8B=E8=AF=95=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

添加详细的邮件功能测试说明文档，包括基础邮件测试和Celery异步邮件测试的测试内容、运行方式、结果说明以及常见问题排查步骤，方便用户验证邮件功能是否正常工作
---
 README.md | 104 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 104 insertions(+)

diff --git a/README.md b/README.md
index d9fcb3d..fc3e10f 100644
--- a/README.md
+++ b/README.md
@@ -1241,6 +1241,109 @@ REPORTS_ROOT = BASE_DIR / 'reports'  # 可以修改为其他路径
    - 检查模板文件 `core/templates/core/report_pdf.html` 是否完整
    - 确保所有依赖的 CSS 和图像资源都能正常访问
 
+## 邮件功能测试
+
+项目提供了两个专门的测试脚本，用于验证邮件发送功能是否正常工作：
+
+### 1. 基础邮件测试（test_email.py）
+
+用于测试直接邮件发送功能，验证SMTP配置是否正确。
+
+#### 测试内容
+- ✅ 邮件配置验证
+- ✅ SMTP连接测试
+- ✅ 发送简单文本邮件
+- ✅ 发送HTML邮件（带附件）
+- ✅ 邮件发送性能测试
+
+#### 运行方式
+
+```bash
+# 运行基础邮件测试
+python test_email.py
+```
+
+#### 测试结果说明
+- 所有测试通过：邮件系统配置正确，可以正常工作
+- 3项以上通过：邮件系统基本可用，部分功能可能需要优化
+- 少于3项通过：邮件系统存在严重问题，需要检查配置
+
+### 2. Celery异步邮件测试（test_celery_email.py）
+
+用于测试通过Celery异步发送邮件的功能，验证整个异步任务链是否正常。
+
+#### 测试内容
+- ✅ Celery邮件配置验证
+- ✅ Celery Worker状态检查
+- ✅ Celery异步邮件任务执行
+- ✅ 同步发送测试邮件（用于对比）
+
+#### 运行方式
+
+```bash
+# 运行Celery异步邮件测试
+python test_celery_email.py
+```
+
+#### 测试结果说明
+- 所有测试通过：Celery邮件功能正常
+- 2项以上通过：Celery邮件功能基本可用
+- 少于2项通过：存在严重问题，需要检查配置
+
+### 3. 常见问题排查
+
+#### 测试失败时的检查步骤
+
+1. **检查SMTP配置**
+   ```bash
+   # 查看Django邮件配置
+   python -c "import os; os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'diary_family.settings'); import django; django.setup(); from django.conf import settings; print('EMAIL_HOST:', getattr(settings, 'EMAIL_HOST', None)); print('EMAIL_PORT:', getattr(settings, 'EMAIL_PORT', None)); print('EMAIL_HOST_USER:', getattr(settings, 'EMAIL_HOST_USER', None))"
+   ```
+
+2. **检查Redis服务**
+   ```bash
+   sudo systemctl status redis-server
+   redis-cli ping
+   ```
+
+3. **检查Celery Worker状态**
+   ```bash
+   # 查看Celery Worker状态
+   celery -A diary_family status
+   
+   # 如果Worker未运行，启动它
+   celery -A diary_family worker -l info
+   ```
+
+4. **查看日志文件**
+   ```bash
+   # 查看邮件测试日志
+   tail -f /var/log/celery/test_email.log
+   tail -f /var/log/celery/test_celery_email.log
+   
+   # 查看Celery日志
+   tail -f /var/log/celery/worker.log
+   tail -f /var/log/celery/beat.log
+   ```
+
+5. **验证网络连通性**
+   ```bash
+   # 测试SMTP服务器连通性
+   telnet smtp.example.com 587
+   
+   # 测试DNS解析
+   nslookup smtp.example.com
+   ```
+
+#### 常见错误及解决方案
+
+| 错误信息 | 可能原因 | 解决方案 |
+|---------|---------|---------|
+| 连接被拒绝 | SMTP服务器地址/端口错误 | 检查SMTP配置，确认服务器地址和端口 |
+| 认证失败 | 用户名或密码错误 | 检查邮箱账号和密码，确认是否开启了SMTP服务 |
+| Celery连接失败 | Redis未运行或配置错误 | 检查Redis服务状态，验证CELERY_BROKER_URL配置 |
+| 任务超时 | Worker未运行或任务执行时间过长 | 启动Celery Worker，检查任务代码 |
+
 ## Celery 监控（可选）
 
 使用 Flower 监控 Celery 任务：
@@ -1261,6 +1364,7 @@ celery -A diary_family flower --port=5555
 2. 生产环境建议使用PostgreSQL或MySQL数据库
 3. 定期清理过期数据
 4. 保持依赖包更新
+5. 定期运行邮件测试脚本，确保邮件功能正常
 
 ## 许可证