7.0 KiB

Raw Blame History

新建 Celery 和对象存储规范文档

日期: 2026-02-11
类型: 文档新建
影响范围: jointo-tech-stack skill

变更概述

新建两个关键基础设施规范文档，补充项目架构中已实现但文档缺失的核心功能。

新建文档

1. celery.md - Celery 异步任务规范

路径: .claude/skills/jointo-tech-stack/references/celery.md

文档规模: ~700 行

必要性: ⭐⭐⭐⭐⭐

Docker Compose 已配置完整（3 个 worker 容器 + RabbitMQ + Beat）
项目大量使用 Celery 异步任务（AI 生成、导出、定时任务）
原 backend.md 仅简略提及（<10% 内容）

主要内容:

✅ Celery 架构概览（队列分离策略）
✅ RabbitMQ 配置和管理
✅ 任务编写规范
- 基础任务定义
- 自定义任务类（AITask）
- 异步任务（数据库操作）
- 重试策略和超时设置
✅ 队列设计模式
- ai 队列（AI 生成任务）
- export 队列（导出任务）
- maintenance 队列（维护任务）
- 队列路由配置
- 任务限流
- Worker 并发配置
✅ Celery Beat 定时任务
- Beat 调度器配置
- Crontab 表达式示例
- 定时任务示例（清理、统计、通知）
✅ 任务监控和调试
- 查看队列状态
- 查看 Worker 状态
- 查看 Beat 调度器
- 日志查看
- Flower 监控（可选）
✅ 常见问题排查
- 任务 PENDING 状态
- 任务执行失败无日志
- 数据库连接池耗尽
- 任务重复执行
✅ 事件循环处理
- ForkPoolWorker event loop 冲突
- 解决方案（run_async_task）
- Worker 启动时初始化
✅ 最佳实践
- 任务设计原则（幂等性、原子性）
- 错误处理
- 资源清理
- 日志规范

实际代码引用:

server/app/core/celery_app.py - Celery 配置
server/app/tasks/ai_tasks.py - AI 任务实现
server/docker-compose.yml - 容器配置

2. storage.md - 对象存储规范

路径: .claude/skills/jointo-tech-stack/references/storage.md

文档规模: ~600 行

必要性: ⭐⭐⭐⭐⭐

项目核心功能依赖对象存储（剧本、图片、视频）
支持多云切换（MinIO/OSS/S3/COS）
infrastructure.md 完全未提及

主要内容:

✅ 对象存储架构
- boto3 S3 兼容协议
- 多云支持设计
- 架构图
✅ 本地开发配置
- MinIO 手动启动（Docker Compose 已移除容器）
- 创建 Bucket
- 环境变量配置
- 使用阿里云 OSS（团队开发推荐）
✅ 生产环境配置
- 阿里云 OSS（推荐）
  - 创建 Bucket
  - 配置 CORS
  - 配置 CDN
  - 访问控制（RAM 子账号）
- AWS S3（备选）
- 腾讯云 COS（备选）
✅ StorageService 使用指南
- 初始化
- 文件上传（Content-Type 处理）
- 文件下载
- 预签名 URL
- 文件删除
- 检查文件是否存在
✅ URL 生成策略
- build_file_url 函数（相对路径 → 完整 URL）
- extract_object_name 函数（完整 URL → 相对路径）
- 向后兼容性
✅ 最佳实践
- 文件命名规范（UUID + 扩展名）
- 内容类型映射
- 错误处理
- 批量操作
- 文件清理策略
✅ 常见问题排查
- 文件上传后无法访问（403）
- 文本文件乱码
- 连接超时
- CDN 缓存未更新

实际代码引用:

server/app/core/storage.py - StorageService 实现
server/.env.example - S3 配置示例

技术亮点

1. 事件循环修复方案

问题: Celery ForkPoolWorker 子进程继承父进程 event loop，导致 RuntimeError: Task got Future attached to a different loop

解决方案:

def run_async_task(coro):
    """在新的 event loop 中运行异步任务"""
    loop = asyncio.new_event_loop()
    asyncio.set_event_loop(loop)
    try:
        return loop.run_until_complete(coro)
    finally:
        loop.close()

2. 数据库连接管理

问题: 全局数据库引擎导致连接池耗尽

解决方案:

def get_async_session():
    """为当前 event loop 创建独立的数据库会话"""
    engine = create_async_engine(
        settings.DATABASE_URL,
        poolclass=None  # ✅ 禁用连接池，每次创建新连接
    )
    return sessionmaker(engine, class_=AsyncSession), engine

# 使用后确保释放
finally:
    await engine.dispose()

3. Content-Type 自动处理

问题: 文本文件上传后下载乱码

解决方案:

# StorageService 自动为文本文件添加 charset
if content_type.startswith('text/'):
    extra_args['ContentType'] = f"{content_type}; charset=utf-8"

文档结构优化

更新 SKILL.md

在主 skill 文件中添加两个新文档的引用：

### [celery.md](references/celery.md)
Celery 异步任务规范，包括：
- Celery 架构概览（队列分离策略）
- RabbitMQ 配置
- 任务编写规范...

### [storage.md](references/storage.md)
对象存储规范，包括：
- 对象存储架构（boto3 S3 兼容协议）
- 本地开发配置（MinIO/OSS）
- 生产环境配置...

影响范围

新建文件

✅ .claude/skills/jointo-tech-stack/references/celery.md
✅ .claude/skills/jointo-tech-stack/references/storage.md

更新文件

✅ .claude/skills/jointo-tech-stack/SKILL.md

代码

❌ 无代码变更（仅文档新建）

验证要点

✅ celery.md 涵盖完整的 Celery 架构和使用规范
✅ 包含事件循环修复方案（项目关键技术点）
✅ storage.md 涵盖多云存储配置
✅ 明确 MinIO 需手动启动（Docker Compose 已移除）
✅ 补充生产环境配置（阿里云 OSS/AWS S3）
✅ 提供完整的 StorageService 使用示例
✅ 涵盖常见问题和排查方法

后续行动

P1 - 近期创建（建议下次会话）

middleware.md - 中间件规范
- 请求追踪（request_id）
- 日志中间件
- CORS 配置
- 中间件开发规范
ai-providers.md - AI Provider 架构
- Provider 抽象层架构
- 工厂模式设计
- Provider 开发指南
- API 速率限制处理

P2 - 可选补充

resources.md - 资源目录管理
- AI 提示词管理
- 邮件/短信模板规范

备注

本次新建文档填补了项目架构规范的两个关键空白，确保开发者能够：

正确编写和调试 Celery 异步任务
理解事件循环冲突问题及解决方案
配置和使用多云对象存储
在本地开发和生产环境间无缝切换

文档结合实际代码实现，提供完整的示例和最佳实践。

7.0 KiB Raw Blame History

新建 Celery 和对象存储规范文档

变更概述

新建文档

1. celery.md - Celery 异步任务规范

2. storage.md - 对象存储规范

技术亮点

1. 事件循环修复方案

2. 数据库连接管理

3. Content-Type 自动处理

文档结构优化

更新 SKILL.md

影响范围

新建文件

更新文件

代码

验证要点

后续行动

P1 - 近期创建（建议下次会话）

P2 - 可选补充

相关文档

备注

7.0 KiB

Raw Blame History