# FastAPI-Task

**Repository Path**: zhujinrun/fastapi-task

## Basic Information

- **Project Name**: FastAPI-Task
- **Description**: FastAPI + AI 视频处理的长任务
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-23
- **Last Updated**: 2026-03-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FastAPI + AI 视频处理的长任务

┌─────────────┐     提交任务      ┌─────────────┐     写入状态      ┌─────────────┐
│   客户端     │ ───────────────→ │  FastAPI    │ ───────────────→ │  Redis      │
│  (任意节点)  │                  │  (任意节点)   │                  │ (任务状态中心) │
└─────────────┘                  └─────────────┘                  └─────────────┘
       ↑                              ↓                                ↓
       └──────────────────────────────┘                         ┌─────────────┐
              轮询查询结果 (任意节点都能查)                        │  Celery     │
                                                                  │  Worker     │
                                                                  │ (实际执行)   │
                                                                  └─────────────┘


## 项目结构

project/
├── api/
│   ├── __init__.py
│   ├── tasks.py          # 任务相关接口
│   └── models.py         # Pydantic 模型
├── core/
│   ├── __init__.py
│   ├── config.py         # 配置
│   └── celery_app.py     # Celery 配置
├── worker/
│   └── video_processor.py # 实际处理逻辑
└── main.py               # FastAPI 入口


## 运行

**安装项目依赖**

```bash
# miniconda3
conda create -n fastapi-env python=3.10 -y
conda activate fastapi-env
# pip install fastapi[standard]
# pip install celery redis
pip install -r requirements.txt

# python3.10-venv

# 添加 deadsnakes PPA（专门提供旧版本 Python）
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
# 安装 Python 3.10 及配套工具
sudo apt install python3.10 python3.10-venv
# 验证 python3.10 版本
python3.10 --version

python3.10 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```


**启动 FastAPI 服务**

```bash
# 节点1
uvicorn main:app --host 0.0.0.0 --port 8000

# 节点2（另一个终端）
uvicorn main:app --host 0.0.0.0 --port 8001

# 节点3（再开一个）
uvicorn main:app --host 0.0.0.0 --port 8002
```

**启动 Celery Worker**

```bash
# Worker 1（可以开多个进程）
celery -A core.celery_app worker --loglevel=info --concurrency=2 -n worker1@%h

# Worker 2（另一个终端，不同机器也可以）
celery -A core.celery_app worker --loglevel=info --concurrency=2 -n worker2@%h
```


## Debian 打包安装

项目支持打包为 Debian 安装包（`.deb`），安装后即可作为系统服务运行。

### 打包目录结构

deb 包的展开文件结构位于 `fastapi-task-deb/` 目录：

```
fastapi-task-deb/
├── DEBIAN/                      # 控制信息和脚本
│   ├── control                  # 包元数据（名称、版本、依赖等）
│   ├── changelog                # 版本历史
│   ├── compat                   # debhelper 兼容性
│   ├── copyright                # 版权信息
│   ├── postinst                 # 安装后脚本（创建用户、启动服务）
│   ├── prerm                    # 卸载前脚本（停止服务）
│   └── md5sums                  # 文件校验和（构建时自动生成）
├── etc/fastapi-task/
│   └── config.json              # 默认配置文件
├── usr/bin/
│   ├── fastapi-task-start       # 服务启动快捷命令
│   ├── fastapi-task-stop        # 服务停止快捷命令
│   └── fastapi-task-status      # 状态查看快捷命令
├── usr/share/fastapi-task/
│   ├── api/models.py            # Pydantic 模型
│   ├── api/tasks.py             # 任务接口
│   ├── core/celery_app.py       # Celery 配置
│   ├── core/config.py           # 应用配置
│   ├── worker/video_processor.py # 任务处理器
│   ├── main.py                  # FastAPI 入口
│   └── requirements.txt         # Python 依赖
└── lib/systemd/system/
    ├── fastapi-task-api.service     # API 服务配置
    └── fastapi-task-worker.service  # Worker 服务配置
```

### 快速构建

```bash
# 在项目根目录执行
./build-deb-direct.sh

# 或手动构建
cd fastapi-task-deb
find usr etc lib -type f | xargs md5sum > DEBIAN/md5sums
cd ..
dpkg-deb --build fastapi-task-deb fastapi-task_1.0.0-1_amd64.deb
```

构建完成后生成：`fastapi-task_1.0.0-1_amd64.deb`

### 安装 deb 包

```bash
# 方法 1: 使用 dpkg
sudo dpkg -i fastapi-task_1.0.0-1_amd64.deb
sudo apt-get install -f  # 修复依赖问题

# 方法 2: 使用 gdebi（推荐，自动处理依赖）
sudo apt-get install gdebi
sudo gdebi fastapi-task_1.0.0-1_amd64.deb
```

### 服务管理

安装后会创建两个 systemd 服务：

| 服务名 | 说明 |
|--------|------|
| `fastapi-task-api` | FastAPI HTTP API 服务 |
| `fastapi-task-worker` | Celery Worker 服务 |

**快捷命令**

```bash
sudo fastapi-task-start   # 启动服务
sudo fastapi-task-stop    # 停止服务
sudo fastapi-task-status  # 查看状态
```

**systemctl 命令**

```bash
# 启动/停止/重启/查看状态
sudo systemctl start fastapi-task-api
sudo systemctl stop fastapi-task-api
sudo systemctl restart fastapi-task-api
sudo systemctl status fastapi-task-api

sudo systemctl start fastapi-task-worker
sudo systemctl stop fastapi-task-worker
sudo systemctl status fastapi-task-worker

# 查看日志
sudo journalctl -u fastapi-task-api -f
sudo journalctl -u fastapi-task-worker -f

# 禁用/启用开机自启
sudo systemctl disable fastapi-task-api
sudo systemctl enable fastapi-task-api
```

### 访问服务

- API 地址: http://localhost:8000
- API 文档: http://localhost:8000/docs
- 健康检查: http://localhost:8000/health

### 配置文件

配置文件位置：`/etc/fastapi-task/config.json`

修改配置后需重启服务：

```bash
sudo systemctl restart fastapi-task-api
sudo systemctl restart fastapi-task-worker
```

### 卸载

```bash
# 卸载但保留配置
sudo dpkg -r fastapi-task

# 完全卸载（包括配置）
sudo dpkg -P fastapi-task
```

### 安装后特性

- ✅ 自动创建 `fastapi-task` 系统用户和组
- ✅ 自动创建虚拟环境并安装 Python 依赖
- ✅ 自动启动并启用 systemd 服务
- ✅ 支持开机自启动
- ✅ API 默认运行在 http://localhost:8000

### 依赖说明

- Python 3.8+
- Redis Server（deb 包会作为依赖推荐安装）
- systemd