# 新建 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`

**解决方案**:
```python
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. 数据库连接管理

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

**解决方案**:
```python
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 自动处理

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

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

---

## 文档结构优化

### 更新 SKILL.md

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

```markdown
### [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`

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

---

## 验证要点

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

---

## 后续行动

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

1. **middleware.md** - 中间件规范
   - 请求追踪（request_id）
   - 日志中间件
   - CORS 配置
   - 中间件开发规范

2. **ai-providers.md** - AI Provider 架构
   - Provider 抽象层架构
   - 工厂模式设计
   - Provider 开发指南
   - API 速率限制处理

### P2 - 可选补充

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

---

## 相关文档

- [Celery 异步任务规范](../../../.claude/skills/jointo-tech-stack/references/celery.md)
- [对象存储规范](../../../.claude/skills/jointo-tech-stack/references/storage.md)
- [jointo-tech-stack SKILL.md](../../../.claude/skills/jointo-tech-stack/SKILL.md)
- [后端技术栈规范](../../../.claude/skills/jointo-tech-stack/references/backend.md)
- [基础设施规范](../../../.claude/skills/jointo-tech-stack/references/infrastructure.md)

---

## 备注

本次新建文档填补了项目架构规范的两个关键空白，确保开发者能够：
1. 正确编写和调试 Celery 异步任务
2. 理解事件循环冲突问题及解决方案
3. 配置和使用多云对象存储
4. 在本地开发和生产环境间无缝切换

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