6.1 KiB

Raw Blame History

Celery 应用路径标准化

日期: 2026-01-28
类型: 架构优化
影响范围: Celery 应用配置、文档规范

概述

统一 Celery 应用配置路径，删除冗余文件，确保项目架构清晰。将 Celery 应用配置从 app/tasks/celery_app.py 迁移到 app/core/celery_app.py，符合核心基础设施的架构设计。

问题背景

项目中存在两个 celery_app.py 文件：

app/core/celery_app.py: 配置完整，包含任务路由、限流、BaseTask 等高级配置
app/tasks/celery_app.py: 配置简单，功能较少

问题:

路径不一致导致混淆
大部分任务文件使用 app.core.celery_app，但 ai_service.py 使用 app.tasks.celery_app
文档中路径不统一
时区配置不一致（Asia/Shanghai vs UTC）

解决方案

1. 统一使用 `app/core/celery_app`

理由:

符合架构: core/ 目录存放核心基础设施（database, config, security, celery_app）
配置完整: 包含任务路由、限流、BaseTask 等高级配置
使用广泛: 5 个文件使用 vs 1 个文件使用
职责清晰: core/ 存放基础设施，tasks/ 存放任务实现

项目结构:

app/core/
├── config.py          # 配置管理（全局单例）
├── database.py        # 数据库连接（全局单例）
├── security.py        # 安全工具（全局单例）
├── cache.py           # 缓存配置（全局单例）
├── celery_app.py      # Celery 应用（全局单例）✅
└── storage.py         # 存储配置（全局单例）

app/tasks/
├── ai_tasks.py        # AI 任务实现
├── export_tasks.py    # 导出任务实现
└── credit_tasks.py    # 积分任务实现

2. 修复时区配置

问题: app/core/celery_app.py 使用 timezone="Asia/Shanghai"，不符合项目 UTC 规范。

修复:

# ❌ 错误
celery_app.conf.update(
    timezone="Asia/Shanghai",
    enable_utc=True,
)

# ✅ 正确
celery_app.conf.update(
    timezone="UTC",
    enable_utc=True,
)

理由: 项目统一使用 UTC 时区，数据库和后端均使用 UTC，Celery 也应保持一致。

执行步骤

1. 删除冗余文件

# 删除 app/tasks/celery_app.py
rm server/app/tasks/celery_app.py

2. 修复代码导入路径

修复 ai_service.py:

# ❌ 错误
from app.tasks.celery_app import celery_app

# ✅ 正确
from app.core.celery_app import celery_app

3. 修复时区配置

修复 app/core/celery_app.py:

celery_app.conf.update(
    timezone="UTC",  # 修改为 UTC
    enable_utc=True,
)

4. 更新文档

修复 backend.md:

更新 Celery 应用配置路径
更新 Docker Compose 命令
更新常用命令

修复 infrastructure.md:

已使用正确路径，无需修改

修改文件清单

代码文件

文件	操作	说明
`server/app/tasks/celery_app.py`	删除	冗余文件
`server/app/core/celery_app.py`	修改	修复时区配置
`server/app/services/ai_service.py`	修改	修复导入路径

文档文件

文件	操作	说明
`.claude/skills/jointo-tech-stack/references/backend.md`	修改	更新 Celery 路径
`.claude/skills/jointo-tech-stack/references/infrastructure.md`	无需修改	已使用正确路径

标准用法

导入方式

# 在任务文件中
from app.core.celery_app import celery_app

@celery_app.task(name="app.tasks.ai_tasks.generate_image")
def generate_image(prompt: str):
    pass

# 在 Service 中
from app.core.celery_app import celery_app

task = generate_image.delay("测试")

命令行使用

# 启动 Worker
celery -A app.core.celery_app worker -Q ai -l info

# 启动 Beat
celery -A app.core.celery_app beat -l info

# 查看任务列表
celery -A app.core.celery_app inspect registered

# 查看活跃任务
celery -A app.core.celery_app inspect active

Docker Compose 配置

celery-ai:
  build: .
  command: celery -A app.core.celery_app worker -Q ai -l info -n ai-worker@%h
  depends_on:
    - postgres
    - redis
    - rabbitmq

celery-beat:
  build: .
  command: celery -A app.core.celery_app beat -l info
  depends_on:
    - postgres
    - redis
    - rabbitmq

验证结果

代码验证

# 验证导入路径
grep -r "from app.tasks.celery_app import" server/app/
# 结果：无匹配（✅ 已全部修复）

grep -r "from app.core.celery_app import" server/app/
# 结果：6 个文件使用正确路径

文档验证

# 验证文档路径
grep -r "app.tasks.celery_app" .claude/skills/jointo-tech-stack/references/
# 结果：无匹配（✅ 已全部修复）

grep -r "app.core.celery_app" .claude/skills/jointo-tech-stack/references/
# 结果：所有文档使用正确路径

影响评估

正面影响

架构清晰: 核心基础设施统一放在 core/ 目录
路径统一: 所有代码和文档使用相同路径
时区一致: Celery 时区与项目规范一致
减少混淆: 删除冗余文件，避免开发者困惑

潜在影响

需要重启服务: 修改 Celery 配置后需要重启 Worker 和 Beat
文档更新: 需要通知团队成员使用新路径

后续建议

CI/CD 检查: 添加 pre-commit hook 检查 app.tasks.celery_app 导入
团队通知: 通知团队成员使用 app.core.celery_app
文档审查: 定期审查文档确保路径一致

总结

本次优化统一了 Celery 应用配置路径，删除了冗余文件，修复了时区配置，确保项目架构清晰、规范一致。所有代码和文档现在使用统一的 app.core.celery_app 路径，符合核心基础设施的架构设计。

6.1 KiB Raw Blame History