docs: 添加 Celery 定时发送邮件任务配置文档

添加详细的 Celery 定时任务配置指南,包括邮件设置、Celery 启动方式、定时任务配置方法、问题排查和生产环境优化建议
This commit is contained in:
2026-01-09 19:58:45 +08:00
parent 5b32692e66
commit 23ca4fbee2

155
README.md
View File

@@ -282,6 +282,161 @@ sudo systemctl restart nginx
- 邮件发送时间
- 收件人邮箱
## Celery 定时发送邮件任务配置
### 1. 邮件配置设置
在系统配置页面设置完邮件信息后,还需要在 Django 项目的 settings.py 中添加基础邮件配置:
```python
# 邮件基础配置
EMAIL_BACKEND = 'django.core.mail.backends.smtp.EmailBackend'
EMAIL_PORT = 587 # 或根据你的 SMTP 服务器设置
EMAIL_USE_TLS = True # 或根据你的 SMTP 服务器设置
```
### 2. 启动 Celery Worker 和 Beat
#### 开发环境
```bash
# 启动 Celery Worker
celery -A diary_family worker -l info
# 启动 Celery Beat用于定时任务调度
celery -A diary_family beat -l info --scheduler django_celery_beat.schedulers:DatabaseScheduler
```
#### 生产环境
建议使用 supervisor 管理 Celery 进程。创建两个 supervisor 配置文件:
1. **celery_worker.conf**
```ini
[program:celery_worker]
command=/path/to/venv/bin/celery -A diary_family worker -l info
directory=/path/to/diary-family
user=www-data
group=www-data
autostart=true
autorestart=true
stdout_logfile=/var/log/celery/worker.log
stderr_logfile=/var/log/celery/worker_error.log
```
2. **celery_beat.conf**
```ini
[program:celery_beat]
command=/path/to/venv/bin/celery -A diary_family beat -l info --scheduler django_celery_beat.schedulers:DatabaseScheduler
directory=/path/to/diary-family
user=www-data
group=www-data
autostart=true
autorestart=true
stdout_logfile=/var/log/celery/beat.log
stderr_logfile=/var/log/celery/beat_error.log
```
启动 supervisor 服务:
```bash
sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start celery_worker
sudo supervisorctl start celery_beat
```
### 3. 配置定时任务
系统使用 `django_celery_beat` 进行定时任务管理,支持两种方式配置:
#### 方式一:通过 Django 管理后台(推荐)
1. 登录 Django 管理后台(/houtai
2. 找到 **Periodic tasks**(周期性任务)
3. 点击 **Add** 按钮添加新任务
4. 配置任务:
- **Name**: 任务名称(如:每日报告发送)
- **Task (registered)**: 选择 `core.tasks.send_daily_report`
- **Interval**: 设置执行间隔(如:每天)
- **Enabled**: 勾选启用
5. 点击 **Save** 保存
#### 方式二:通过代码配置
在 `core/tasks.py` 中添加定时任务配置:
```python
from celery import shared_task
from django_celery_beat.models import PeriodicTask, IntervalSchedule
# 创建或更新定时任务
def setup_daily_report_task():
# 创建每天执行的间隔
schedule, created = IntervalSchedule.objects.get_or_create(
every=1,
period=IntervalSchedule.DAYS,
)
# 创建或更新定时任务
task, created = PeriodicTask.objects.update_or_create(
name='Daily Report Task',
defaults={
'interval': schedule,
'task': 'core.tasks.send_daily_report',
},
)
return task
```
然后在 Django 启动时调用此函数(如在 `core/apps.py` 中)。
### 4. 验证任务执行
- 查看 Celery 日志:`tail -f /var/log/celery/worker.log`
- 检查邮件是否正常发送
- 在 Django 管理后台查看任务执行记录
### 5. 常见问题排查
1. **任务不执行**
- 检查 Celery worker 和 beat 是否正常运行
- 检查 Redis 服务是否正常
- 检查任务是否已启用
- 检查系统时间是否正确
2. **邮件发送失败**
- 检查 SMTP 服务器配置是否正确
- 检查邮箱账号密码是否正确
- 检查收件人邮箱格式是否正确
- 查看 Celery 日志中的错误信息
3. **任务执行延迟**
- 检查系统负载是否过高
- 考虑增加 Celery worker 数量
- 检查 Redis 性能
### 6. 生产环境优化建议
- 使用独立的 Redis 服务器
- 配置合适的 worker 数量建议CPU 核心数 × 2
- 定期清理 Celery 任务结果
- 配置监控系统(如 Prometheus + Grafana
- 启用 Celery 监控工具(如 Flower
## Celery 监控(可选)
使用 Flower 监控 Celery 任务:
```bash
# 安装 Flower
pip install flower
# 启动 Flower
celery -A diary_family flower --port=5555
```
访问 http://your-server:5555 查看任务监控界面。
## 注意事项
1. 定期备份数据库