Flask 与后端模式 on 扎塔-Zata

Celery

Mon, 20 Oct 2025 17:12:13 +0800

Celery 详细使用教程：从入门到实践

什么是 Celery？

Celery 是一个强大、简单、灵活的分布式异步任务队列 (Asynchronous Task Queue)。它主要用于处理那些耗时较长或者可以稍后执行的任务，从而避免阻塞主程序（例如一个 Web 请求）。

主要使用场景：

异步任务： 用户注册后发送欢迎邮件、处理用户上传的图片（缩放、加水印）、生成复杂的报表。
定时任务： 每天凌晨清理一次数据、每小时从第三方 API 同步一次信息。

核心概念

要理解 Celery，你必须先了解它的四个核心组件：

生产者 (Producer)： 也就是你的主程序（例如 Flask/Django 应用）。它负责创建任务并将其发送到任务队列中。
Broker (消息中间件)： 任务的“信箱”或“中转站”。生产者将任务放入 Broker，Worker 从 Broker 中取出任务。最常用的 Broker 是 RabbitMQ（功能最全，官方推荐）和 Redis（轻量，易于上手）。
Worker (消费者)： 真正执行任务的进程。它会持续监控 Broker，一旦发现新任务，就取出并执行它。你可以同时运行多个 Worker 来实现分布式处理。
Backend (结果存储)： （可选）用于存储任务执行结果的地方。如果你需要稍后查询任务的状态或返回值（例如，在网页上显示“报表已生成”），你就需要配置 Backend。常用的 Backend 包括 Redis、RabbitMQ (amqp) 或数据库 (SQLAlchemy)。

工作流程： 生产者 (App) -> 发送任务 -> Broker (Redis/RabbitMQ) -> Worker (领取任务) -> 执行任务 -> (可选) 存入结果 -> Backend (Redis/DB)

第一部分：快速入门 (Hello, World)

我们将使用 Redis 作为 Broker 和 Backend，因为它安装简单，配置方便。

第1步：环境准备

确保你已经安装了 Python 和 Redis。

安装 Redis：
- (macOS) brew install redis，然后 redis-server
- (Linux) sudo apt install redis-server
- (Windows) 建议使用 WSL2 或 Docker。
- 确保 Redis 服务正在 localhost:6379 上运行。
安装 Python 库：
```
pip install celery redis
```

第2步：创建 Celery 应用和任务

创建一个名为 tasks.py 的文件。

import time
from celery import Celery

# 1. 创建 Celery 实例
# 第一个参数 'tasks' 是当前模块的名称，这在自动生成任务名时很重要。
# broker 和 backend 都指向我们的 Redis 服务。
# /0 和 /1 代表 Redis 的不同数据库 (db)，避免数据混淆。
app = Celery('tasks',
 broker='redis://localhost:6379/0',
 backend='redis://localhost:6379/1')

# 2. 定义一个任务
# @app.task 装饰器将这个函数注册为 Celery 任务
@app.task
def add(x, y):
 print(f"开始执行任务: {x} + {y}")
 time.sleep(5) # 模拟一个耗时的操作
 result = x + y
 print(f"任务执行完毕: {result}")
 return result

@app.task
def send_email(to, subject, body):
 print(f"向 {to} 发送邮件...")
 time.sleep(3) # 模拟I/O操作
 print(f"邮件发送成功: 主题 {subject}")
 return "Success"

第3步：运行 Celery Worker

打开一个终端，cd 到 tasks.py 所在的目录，然后运行 Worker 进程：

# -A tasks: 指定 Celery 实例 (app) 在 'tasks' 模块中
# worker: 启动 worker 进程
# --loglevel=info: 设置日志级别为 INFO，方便我们观察
celery -A tasks worker --loglevel=info

如果一切正常，你会看到一个 ASCII art 组成的 Celery Logo，并提示 [tasks]... ready.。这表示 Worker 已经连接到 Redis 并准备好接收任务了。

第4步：调用任务

打开第二个终端（保持 Worker 终端运行），进入 Python 交互环境（如 ipython 或 python）：

>>> from tasks import add, send_email

# 1. 异步调用任务
# .delay() 是 .apply_async() 的快捷方式
# 注意：这行代码会 *立即* 返回，不会等待 5 秒
print("准备调用 add(4, 4)...")
task_result = add.delay(4, 4)
print("任务已发送，ID:", task_result.id)

# 2. 尝试调用另一个任务
print("准备发送邮件...")
email_task = send_email.delay("user@example.com", "你好", "这是一封测试邮件。")
print("邮件任务已发送，ID:", email_task.id)

# 3. 查看 Worker 终端
# 此时，你应该能在第一个终端（Worker 终端）看到任务开始执行的日志。

第5步：获取任务结果

在第二个终端（Python 交互环境）中，我们可以使用 task_result 对象（它是一个 AsyncResult 实例）来检查任务状态和获取结果：

>>> # 检查任务是否完成
>>> task_result.ready()
False # (可能还是 False，因为任务在 sleep(5))

# (等待几秒钟)

>>> task_result.ready()
True

>>> # 获取任务状态
>>> task_result.status
'SUCCESS'

>>> # 获取任务的返回值
>>> # .get() 会阻塞当前进程，直到拿到结果
>>> result_value = task_result.get()
>>> print(result_value)
8

>>> # 检查邮件任务
>>> email_task.get()
'Success'

>>> # 如果任务执行出错
>>> # 你可以通过 .status 查看
# 假设我们定义了一个出错的任务
# task_error = error_task.delay()
# task_error.status
# 'FAILURE'
# task_error.get() # 这将会抛出异常

第二部分：与 Web 框架集成 (以 FastAPI 为例)

在真实项目中，你通常会在 Web 应用（如 FastAPI）中调用 Celery 任务。FastAPI 是一个现代、高性能的 Python Web 框架，基于 ASGI，支持异步操作，与 Celery 集成非常自然。

项目结构

my_fastapi_project/
├── main.py # FastAPI 应用
├── celery_app.py # Celery 实例和配置
├── tasks.py # 任务定义
└── requirements.txt

requirements.txt 示例（添加 FastAPI 相关依赖）：

fastapi==0.104.1
uvicorn[standard]==0.24.0
celery==5.3.6
redis==5.0.1

第1步：配置 Celery (celery_app.py)

创建一个中心化的 Celery 实例。由于 FastAPI 没有内置的 app.config，我们使用一个配置字典来传递参数。

# celery_app.py
from celery import Celery

# 创建 Celery 实例
celery = Celery(__name__)

# 从配置中加载 Celery 配置
def init_celery(app, config):
 celery.conf.update(config)

 # (可选) 让任务可以使用 FastAPI 的 app context（如果任务需要访问 app 状态）
 # FastAPI 没有传统的 app_context，但我们可以用类似方式处理依赖
 class ContextTask(celery.Task):
 def __call__(self, *args, **kwargs):
 # 这里可以注入 FastAPI 的依赖，如果需要
 # 对于简单任务，可省略
 return self.run(*args, **kwargs)

 celery.Task = ContextTask

第2步：定义任务 (tasks.py)

任务定义与 Flask 示例相同，几乎无需改动。

# tasks.py
import time
from celery_app import celery

# 注意：我们现在从 celery_app 导入 celery 实例
@celery.task
def long_running_simulation(user_id):
 print(f"开始为用户 {user_id} 运行模拟...")
 time.sleep(10) # 模拟一个非常耗时的操作
 print(f"用户 {user_id} 的模拟运行完毕。")
 return f"Report for {user_id}"

第3步：配置 FastAPI (main.py)

# main.py
from fastapi import FastAPI, Query
from celery_app import celery, init_celery
from tasks import long_running_simulation

app = FastAPI()

# 配置（这里直接定义，也可以用环境变量或 pydantic-settings）
config = {
 # Celery Broker
 "CELERY_BROKER_URL": "redis://localhost:6379/0",
 # Celery Backend
 "CELERY_RESULT_BACKEND": "redis://localhost:6379/1"
}

# 初始化 Celery
init_celery(app, config)

@app.get("/")
def index():
 return {"message": "你好, Celery 和 FastAPI!"}

@app.get("/start-task")
def start_task(user_id: str = Query("default_user", description="用户 ID")):
 # 这是一个 Web 请求，我们不想让它等待 10 秒
 # 我们立即将任务推送到队列
 task = long_running_simulation.delay(user_id)

 # 立即返回，并告诉前端任务 ID
 return {
 "message": "任务已启动",
 "task_id": task.id
 }, 202 # 202 Accepted 表示请求已被接受，正在处理

@app.get("/task-status/{task_id}")
def task_status(task_id: str):
 # 从 Backend 查询任务状态
 task_result = long_running_simulation.AsyncResult(task_id)

 if task_result.state == "PENDING":
 # 任务还在队列中，或刚开始
 response = {
 "state": task_result.state,
 "status": "Pending..."
 }
 elif task_result.state != "FAILURE":
 response = {
 "state": task_result.state,
 "status": "In progress...",
 }
 if task_result.state == "SUCCESS":
 response["result"] = task_result.get() # 获取最终结果
 else:
 response["result"] = task_result.info # 如果任务正在进行，.info 可能包含中间状态
 else:
 # 任务失败
 response = {
 "state": task_result.state,
 "status": str(task_result.info), # 失败的异常信息
 }
 return response

注意：

FastAPI 支持自动生成 OpenAPI 文档，你可以访问 /docs 查看交互式 API 文档。
如果需要异步路由，可以将 @app.get 改为 async def，但这里任务是同步的 Celery 调用，无需。

第4步：运行

你需要运行两个服务（确保 Redis 已启动）：

终端 1 (Celery Worker)：
```
# -A 参数指向 celery 实例所在的模块
# 指向 tasks.py 中导入的 celery 实例
celery -A tasks.celery worker --loglevel=info
```
（注：更健壮的方式是使用 celery -A celery_app.celery worker，取决于你的 __name__ 设置。指向 tasks.celery 通常可行。）

终端 2 (FastAPI App)：

uvicorn main:app --reload --host 127.0.0.1 --port 8000

测试：

访问 http://127.0.0.1:8000/start-task?user_id=123
- 你会立即收到一个 JSON 响应，包含 task_id。
- 同时，观察 Worker 终端，你会看到它开始执行 long_running_simulation。
复制那个 task_id。
访问 http://127.0.0.1:8000/task-status/{your_task_id}
- 一开始，你可能会看到 “Pending” 或 “In progress”。
- 等待 10 秒后刷新，你会看到 “SUCCESS” 和 result: "Report for 123"。
额外：访问 http://127.0.0.1:8000/docs 查看 Swagger UI，方便测试 API。

这个示例保持了与 Flask 版本的相似性，便于迁移。如果你的项目需要数据库集成或其他依赖，可以在 Celery 任务中使用 FastAPI 的依赖注入系统进一步扩展。

第三部分：定时任务 (Celery Beat)

Celery Beat 是一个调度器 (Scheduler)。它负责按计划将任务发送到 Broker，而 Worker 负责执行它们。

第1步：配置 Beat

在你的 Celery 配置中（例如 celery_app.py 或 tasks.py）添加 beat_schedule：

# 在 tasks.py 中
from celery.schedules import crontab

# ... (app = Celery(...) 的定义) ...

@app.task
def periodic_task():
 print("这是一个每 30 秒执行一次的定时任务！")

# 配置定时任务
app.conf.beat_schedule = {
 # 任务名称
 'run-every-30-seconds': {
 'task': 'tasks.periodic_task', # 任务的完整路径名
 'schedule': 30.0, # 每 30 秒
 'args': () # 任务参数（这里没有）
 },
 # 也可以使用 crontab
 'run-every-midnight': {
 'task': 'tasks.add',
 'schedule': crontab(minute=0, hour=0), # 每天午夜
 'args': (100, 200),
 }
}

# (可选) 设置时区，确保 crontab 按你期望的时区执行
app.conf.timezone = 'Asia/Shanghai'

第2步：运行 Beat

要运行定时任务，你至少需要两个进程：

Worker 进程（用于执行任务）：
```
celery -A tasks worker --loglevel=info
```
Beat 进程（用于调度任务）：
```
celery -A tasks beat --loglevel=info
```

快捷方式（开发时用）：

你也可以在一个命令中同时启动 Worker 和 Beat（不推荐在生产环境中使用 -B）：

# -B 选项表示同时启动一个嵌入的 Beat 进程
celery -A tasks worker -B --loglevel=info

启动后，你将看到 Worker 终端每 30 秒打印一次 “这是一个每 30 秒执行一次的定时任务！"。

第四部分：监控与最佳实践

1. 监控：Flower

Flower 是一个基于 Web 的 Celery 监控工具。

安装：
```
pip install flower
```

运行：

# 指向你的 Celery app，并启动 flower
celery -A tasks flower --port=5555

访问 http://localhost:5555，你将看到一个仪表盘，显示所有 Worker 的状态、已完成的任务、队列中的任务等。

2. 任务重试

网络抖动或临时性错误很常见。Celery 允许你轻松地重试任务。

import requests

# bind=True: 将任务实例 (self) 作为第一个参数注入
# max_retries: 最大重试次数
# default_retry_delay: 默认重试间隔（秒）
@app.task(bind=True, max_retries=3, default_retry_delay=60)
def fetch_api_data(self, url):
 try:
 response = requests.get(url, timeout=5)
 response.raise_for_status() # 如果是 4xx/5xx 错误，抛出异常
 return response.json()
 except requests.exceptions.RequestException as exc:
 print(f"请求失败: {exc}。正在重试...")
 # self.retry() 会抛出一个 Retry 异常，Celery 会捕获它并稍后重试
 # exc=exc 会将原始异常信息传递下去
 raise self.retry(exc=exc)

3. 关键配置项

在生产环境中，你可能需要调整一些配置：

task_serializer: 推荐使用 json 或 pickle。json 更安全，但支持的数据类型有限。
result_serializer: 同上。
task_track_started: (True) 是否在任务开始执行时就将其状态报告为 “STARTED”。
worker_concurrency: Worker 进程数，默认是 CPU 核心数。可以根据任务是 I/O 密集型还是 CPU 密集型来调整。
task_acks_late: (False) 默认情况下，Worker 在收到任务后立即向 Broker 发送确认（ack），然后才执行。如果 Worker 在执行中崩溃，任务会丢失。
- 如果设置为 True，Worker 会在任务 执行完毕 后才发送 ack。如果 Worker 崩溃，Broker 会将任务重新分配给其他 Worker。这保证了任务至少被执行一次（但可能重复执行），称为“at-least-once delivery”。

其他知识点

shared_task与app.task的区别

@shared_task 是 Celery 中一个非常重要且常用的装饰器。它的核心作用是创建可复用的、不依赖于任何特定 Celery 应用实例（app instance）的任务。

这使得它在编写可插拔的 Django、fastapi 应用、库或任何希望与项目主 Celery 应用解耦的模块时，成为首选的工具。

核心理念：为什么需要 shared_task？在标准的 Celery 设置中，你可能会这样定义一个任务：


# myproject/celery.py
from celery import Celery
app = Celery('myproject')
app.config_from_object('django.conf:settings', namespace='CELERY')

# myproject/myapp/tasks.py
from myproject.celery import app

@app.task
def add(x, y):
 return x + y

这种方法的问题在于，myapp/tasks.py 模块硬编码了对 myproject.celery.app 实例的导入。

想象一下，如果你正在编写一个希望被多个项目（比如一个开源的 Django 插件）使用的 myapp，你并不知道其他项目的 Celery 实例会叫什么名字，或者在哪里定义。如果强行导入 myproject.celery.app，这个应用在其他项目中将无法使用。

@shared_task 解决了这个问题。它创建的任务是一个“懒加载”的代理，它会在运行时自动绑定到当前项目配置的 Celery 实例上。

详细用法使用 @shared_task 非常简单，只需从 celery 模块中导入它即可。


from celery import shared_task

@shared_task
def add(x, y):
 print(f'Adding {x} + {y}')
 return x + y

当然！@shared_task 的核心优势在于解耦，它允许你定义的任务不依赖任何具体的 Celery 应用（app）实例。这在 FastAPI 项目中尤其有用，可以让你将任务逻辑（tasks.py）与应用实例配置（celery_app.py）和 Web 服务（main.py）完全分开，避免循环导入问题。下面是一个以 FastAPI 为例的详细教程。

核心理念：为什么在 FastAPI 中使用 shared_task？

想象一个场景：

你在 main.py 中创建了 FastAPI app 和 Celery celery_app。
你在 tasks.py 中定义了一个任务，这个任务需要从 main.py 导入某个工具函数或配置。
同时，你的 main.py 中的 Celery celery_app 需要导入 tasks.py 来注册任务。这就造成了循环导入（Circular Import），你的应用将无法启动。 @shared_task 解决了这个问题。你可以在 tasks.py 中定义任务，而无需从任何地方导入 Celery app 实例。然后，你创建一个单独的 celery_app.py 文件来实例化 Celery，并告诉它去哪里发现这些 shared_task。

Part 1: 项目结构

一个清晰的 FastAPI + Celery 项目结构如下：

fastapi_celery_project/
├── main.py # 你的 FastAPI 应用
├── celery_app.py # Celery 实例和配置
├── tasks/
│ ├── __init__.py
│ └── email_tasks.py # 使用 @shared_task 定义任务
└── requirements.txt

Part 2: 依赖安装

requirements.txt:

fastapi
uvicorn[standard]
celery
redis
* celery[redis] 也可以，它会捆绑 redis 库。

Part 3: 配置 Celery 实例 (celery_app.py)

这是连接所有部分的关键文件。它创建 Celery 实例，并告诉 Celery 去哪里查找任务。 celery_app.py:




from celery import Celery

# 1. 定义 Broker 和 Backend 的 URL
# 你应该使用环境变量来存储这些敏感信息，这里为了演示而硬编码
BROKER_URL = "redis://localhost:6379/0"
RESULT_BACKEND = "redis://localhost:6379/1"

# 2. 创建 Celery 实例
# 'tasks' 是这个 Celery 实例的默认名称
celery = Celery(
 'tasks',
 broker=BROKER_URL,
 backend=RESULT_BACKEND,

 # 3. 关键！指定 Celery 应该自动发现任务的模块
 # 这里我们指向 'tasks.email_tasks' 模块。
 # 这替代了 Django 的 `autodiscover_tasks()`。
 include=['tasks.email_tasks']
)

# 4. (可选) 更多 Celery 配置
celery.conf.update(
 task_serializer='json',
 accept_content=['json'],
 result_serializer='json',
 timezone='America/Los_Angeles', # 建议使用 UTC
 enable_utc=True,
 broker_connection_retry_on_startup=True,
)

Part 4: 使用 @shared_task 定义任务

现在，我们在 tasks/email_tasks.py 中定义任务，注意这里不需要导入 celery_app.py 中的 celery 实例。 tasks/email_tasks.py:




import time
from celery import shared_task

# @shared_task 装饰器让这个函数成为一个 Celery 任务
# 它不依赖于任何特定的 Celery app 实例
@shared_task
def send_welcome_email(email: str):
 """
 一个模拟发送欢迎邮件的耗时任务
 """
 print(f"Task started: Sending welcome email to {email}...")

 # 模拟一个 5 秒钟的 I/O 操作 (例如 API 调用或 SMTP 通信)
 time.sleep(5)

 print(f"Task finished: Email sent to {email}")
 return f"Successfully sent welcome email to {email}"

Part 5: 在 FastAPI 中调用任务

最后，我们在 main.py 中创建 API 端点。当端点被调用时，它会将任务推送到 Celery 队列中，然后立即返回响应。 main.py:




from fastapi import FastAPI
from tasks.email_tasks import send_welcome_email
from celery.result import AsyncResult
from celery_app import celery as celery_app_instance # 导入用于查询结果的 app 实例

app = FastAPI()

@app.get("/")
def read_root():
 return {"message": "Welcome to FastAPI + Celery"}

@app.post("/register")
def register_user(email: str):
 """
 一个注册端点，它会异步触发一个欢迎邮件任务
 """
 # .delay() 是 .apply_async() 的快捷方式
 # 它将任务发送到 Celery 队列，并立即返回
 task = send_welcome_email.delay(email)

 # 立即返回响应，告诉客户端任务已加入队列
 return {
 "message": "User registration successful. Welcome email is being sent in the background.",
 "task_id": task.id # 返回任务 ID，以便客户端稍后查询状态
 }

@app.get("/tasks/{task_id}")
def get_task_status(task_id: str):
 """
 根据任务 ID 查询任务的状态和结果
 """
 # 使用从 celery_app.py 导入的实例来创建 AsyncResult
 task_result = AsyncResult(task_id, app=celery_app_instance)

 if task_result.ready():
 # 任务已完成
 if task_result.successful():
 return {
 "task_id": task_id,
 "status": task_result.status,
 "result": task_result.get() # 获取任务的返回值
 }
 else:
 # 任务失败
 return {
 "task_id": task_id,
 "status": task_result.status,
 "result": str(task_result.info) # 获取异常信息
 }
 else:
 # 任务仍在进行中
 return {
 "task_id": task_id,
 "status": task_result.status,
 "result": None
 }

Part 6: 如何运行

你需要启动三个独立的进程：

消息代理 (Message Broker)：这里我们使用 Redis。
Celery Worker：执行任务的进程。
FastAPI 应用：接收 HTTP 请求的 Web 服务器。
启动 Redis (使用 Docker)




docker run -d -p 6379:6379 --name my-redis redis

启动 Celery Worker 在你的项目根目录 (fastapi_celery_project/) 运行：




# -A celery_app.celery 指向 '文件名.Celery实例变量名'
# worker 是命令
# --loglevel=info 是日志级别
celery -A celery_app.celery worker --loglevel=info

你会看到 Worker 启动，并成功发现了 tasks.email_tasks.send_welcome_email 任务。 3. 启动 FastAPI 服务器在另一个终端中运行：




uvicorn main:app --reload

Part 7: 测试

调用任务：curl -X POST “http://127.0.0.1:8000/register?email=example@test.com"你会立即收到响应：{“message”:“User registration successful. Welcome email is being sent in the background.”,“task_id”:”…”}
查看 Worker：在 Celery Worker 的终端中，你会看到任务在 5 秒后被执行：[… INFO/MainProcess] Task tasks.email_tasks.send_welcome_email[…] received
Task started: Sending welcome email to example@test.com…
Task finished: Email sent to example@test.com
[… INFO/MainProcess] Task tasks.email_tasks.send_welcome_email[…] succeeded in 5.01s: ‘Successfully sent email…’
查询结果 (使用你收到的 task_id)：curl http://127.0.0.1:8000/tasks/YOUR_TASK_ID_HERE
- （5秒内）状态：{“task_id”:"…",“status”:“PENDING”,“result”:null}
- （5秒后）状态：{“task_id”:"…",“status”:“SUCCESS”,“result”:“Successfully sent welcome email to example@test.com”}

shared_task 常用参数详解

@shared_task 接受所有 @app.task 的参数。

bind=True (绑定任务实例)

最常用的参数之一。它告诉 Celery 将任务实例（self）作为第一个参数传递给你的函数。这允许你访问任务的上下文（如请求ID）并执行重试。




from celery import shared_task
import requests

@shared_task(bind=True, max_retries=3)
def fetch_external_api(self, url):
 """
 一个带自动重试的任务
 self 是任务实例，不是类的 self
 """
 try:
 response = requests.get(url, timeout=10)
 response.raise_for_status() # 4xx 或 5xx 会抛出异常
 return response.json()
 except requests.RequestException as exc:
 print(f"API call failed for {url}. Retrying... (Attempt {self.request.retries + 1})")
 # self.retry() 会抛出一个异常，Celery 会捕获它并稍后重试
 # countdown=15 表示 15 秒后重试
 raise self.retry(exc=exc, countdown=15)

autoretry_for (自动重试)

bind=True 和 self.retry() 的简化版。你只需指定一个异常元组，Celery 会在捕获到这些异常时自动重试。




@shared_task(
 autoretry_for=(requests.RequestException, KeyError),
 retry_kwargs={'max_retries': 5},
 retry_backoff=True # 启用指数退避 (如 2s, 4s, 8s...)
)
def fetch_api_simple(url):
 # 不需要 try/except，也不需要 self
 # 如果 requests.get 抛出 RequestException，Celery 会自动重试
 response = requests.get(url, timeout=10)
 response.raise_for_status()
 # 如果 response.json() 中缺少某个键，抛出 KeyError，也会重试
 return response.json()['some_key']

ignore_result=True (忽略结果)

如果你的任务是“即发即忘”型（fire-and-forget），你根本不关心它的返回值（比如一个简单的日志记录任务），将此设为 True。Celery 将不会在结果后端（Redis）中存储任何结果，从而节省内存和提高性能。




@shared_task(ignore_result=True)
def log_user_action(user_id, action):
 # 这个任务只是写入日志，不需要返回任何值
 print(f"[LOG] User {user_id} performed action: {action}")

rate_limit (速率限制)

限制任务的执行频率，例如 “10/m” (每分钟 10 次) 或 “1/s” (每秒 1 次)。这对于防止对外部 API 造成过大压力非常有用。




@shared_task(rate_limit="5/m")
def call_rate_limited_api():
 # 这个任务在所有 worker 上加起来，每分钟最多执行 5 次
 ...

总结：@shared_task vs @app.task

特性	`@shared_task` (来自 `from celery import shared_task`)	`@app.task` (来自 `from celery_app import celery`)
依赖性	不依赖任何特定的 Celery app 实例。	强依赖于你导入的 `celery` 实例。
适用场景	推荐在所有项目中（包括 FastAPI）使用。 - 在 `tasks/` 模块中定义任务。 - 编写可重用库、插件。	- 仅在定义 Celery app 的主文件（`celery_app.py`）中使用。 - 非常简单的、所有代码都在一个文件中的项目。
主要优势	避免循环导入，实现代码解耦和模块化。	简单直接，但容易导致项目结构混乱。

celery调用任务的方式

在 Celery 中，调用任务（Task）的方式主要有 三种核心方法，此外还有一些辅助或高级用法。下面为你完整列出所有调用方式，并详细说明它们的作用、适用场景和区别。

✅ 一、核心调用方法（最常用）

.delay(*args, **kwargs)

作用：最简单的异步调用方式，直接将任务发送到消息队列（如 Redis）。
特点：
- 语法简洁
- 只支持传递任务参数（args 和 kwargs）
- 不支持设置执行时间、队列、重试策略等高级选项
底层实现：其实是 apply_async 的快捷封装

示例：

result = add.delay(4, 5)
result = translate_file.delay(file_path="/tmp/a.pdf", lang="zh")

✅ 适用场景：快速原型、简单任务、参数少、无需控制执行策略。

.apply_async(args=[], kwargs={}, **options)

作用：功能最全的异步调用方式，支持所有 Celery 任务调度选项。

可选参数（**options）：

参数	说明
`countdown`	多少秒后执行（如 `countdown=10` 表示 10 秒后）
`eta`	指定具体执行时间（`datetime` 对象）
`expires`	任务过期时间（秒数或 `datetime`），过期后不再执行
`queue`	发送到指定队列（需提前配置）
`routing_key`	自定义路由键（配合 RabbitMQ 使用）
`serializer`	序列化格式（如 `'json'`, `'pickle'`）
`retry`	是否自动重试（布尔值）
`retry_policy`	重试策略字典（如 `{'max_retries': 3, 'interval_start': 0}`）
`time_limit`	任务硬性超时时间（秒）
`soft_time_limit`	软超时（抛异常但可捕获）

示例：

from datetime import datetime, timedelta

 5秒后执行，60秒后过期，发到 high_priority 队列
result = translate_file.apply_async(
 kwargs={'file_path': '/tmp/doc.pdf', 'lang': 'en'},
 countdown=5,
 expires=60,
 queue='high_priority'
)

 指定时间执行
eta = datetime.utcnow() + timedelta(hours=1)
result = backup_db.apply_async(eta=eta)

✅ 适用场景：生产环境、需要精确控制任务行为（延迟、队列、过期、重试等）。

.apply(args=[], kwargs={}, **options)

作用：同步执行任务（在当前进程中立即运行，不经过消息队列！）
特点：
- 不会发送到 Broker（如 Redis）
- 不会被 Worker 执行
- 直接调用任务函数，返回结果（类似普通函数调用）
- 主要用于测试或调试

示例：

result = add.apply(args=[2, 3]) 立即执行，返回 5
print(result.get()) 5

⚠️ 警告：不要在生产 Web 请求中使用 .apply()，因为它会阻塞当前进程，失去异步意义！

✅ 适用场景：单元测试、本地调试、确保任务逻辑正确。

✅ 二、通过任务名动态调用（解耦用法）

celery_app.send_task(task_name, args=[], kwargs={}, **options)

作用：不导入任务函数，仅通过任务名字符串调用任务。
优点：
- 完全解耦：调用方不需要知道任务定义在哪个模块
- 适合微服务、插件系统、动态调度
前提：任务必须已注册（Worker 能识别该名字）

示例：

from myproject.celery import app 获取 Celery 实例

result = app.send_task(
 "doc2x.translate_file",
 kwargs={
 "file_path": "/tmp/x.pdf",
 "target_lang": "fr"
 },
 queue="translation"
)

✅ 适用场景：

调度系统不知道具体任务实现

多团队协作，任务名作为接口契约

动态决定调用哪个任务（如根据用户输入）

✅ 三、组调用与工作流（高级用法）

这些不是“单个任务调用”，而是组合多个任务的方式：

group() — 并行执行多个任务

from celery import group

jobs = group(add.s(1, 1), add.s(2, 2), add.s(3, 3))
result = jobs.apply_async()
print(result.get()) [2, 4, 6]

chain() — 串行执行（前一个输出作为后一个输入）

from celery import chain

result = chain(add.s(2, 2), mul.s(4), div.s(2)).apply_async()
 等价于: div(mul(add(2,2), 4), 2) → div(mul(4,4),2) → 16/2 = 8

chord() — 先并行执行一组任务，再回调一个任务

from celery import chord

callback = finalize.s()
header = [add.s(i, i) for i in range(4)] [0+0, 1+1, 2+2, 3+3]
result = chord(header)(callback) callback 接收 [0,2,4,6] 作为参数

✅ 这些用于复杂任务编排，属于 Celery Canvas 功能。

✅ 四、签名（Signatures）— 任务的“可调用对象”

task.s(*args, **kwargs) — 创建任务签名

作用：将任务和参数打包成一个“可传递的对象”，用于组合（如 group/chain）
不会立即执行

示例：

sig = add.s(2, 2) 签名
result = sig.delay() 现在才异步执行

常用于工作流构建。

✅ 总结：所有调用方式一览表

方法	是否异步	是否走 Broker	是否支持高级选项	典型用途
`.delay()`	✅ 是	✅ 是	❌ 否	快速调用
`.apply_async()`	✅ 是	✅ 是	✅ 是	生产环境标准调用
`.apply()`	❌ 否	❌ 否	⚠️ 部分	测试/调试
`send_task()`	✅ 是	✅ 是	✅ 是	动态/解耦调用
`group/chain/chord`	✅ 是	✅ 是	✅ 是	复杂任务编排
`.s()`（签名）	❌（需配合 delay/apply_async）	取决于后续调用	✅	构建工作流

🔒 重要提醒

所有 异步调用（.delay, .apply_async, send_task）都依赖 Broker（如 Redis） 和 Worker 进程。
如果没启动 Worker，任务会堆积在队列中，永远不会执行。
不要在 Web 请求中使用 .get() 阻塞等待结果（除非你明确知道后果）。

如何调整同时执行的任务数

这是一个非常好的问题。在生产环境中，根据负载情况动态调整 Worker 的并发数（即同时执行的任务数）是运维和资源管理的关键部分。

Celery 提供了两种主要的方式来实现这一点：

手动远程控制 (Manual Remote Control)： 你可以向正在运行的 Worker 发送命令，要求它增加或减少工作进程数。
自动伸缩 (Autoscaling)： 你可以设置一个最小和最大进程数，Celery Worker 会根据队列中的任务压力自动调整。

下面我们详细讲解这两种方法。

方法一：使用 celery control 手动调整（即时生效）

这是最直接的“我想动态调整”的答案。你可以使用 Celery 的远程控制命令 pool_grow (增加) 和 pool_shrink (减少) 来实时调整。

这要求你的 Worker 进程正在运行。

适用场景：

你预知到一波大流量即将到来（例如，市场活动开始），需要立即增加处理能力。
你发现服务器负载过高，需要立即减少并发数来“降温”。

前提条件：

Worker 必须使用支持动态伸缩的执行池 (Pool)。默认的 prefork（多进程）池是支持的。gevent 和 eventlet 也支持。
（如果你在 Windows 上运行，默认池可能不支持，你需要显式使用 -P gevent 或 -P eventlet）。

1. 增加并发数 (pool_grow)

这个命令告诉 Worker 增加 N 个工作进程。

# 语法: celery -A <app_name> control pool_grow <N>
# 假设你的应用在 tasks.py 中
# 增加 3 个工作进程
celery -A tasks control pool_grow 3

Worker 会立即响应（在日志中可以看到），并启动新的子进程来接收任务。

2. 减少并发数 (pool_shrink)

这个命令告诉 Worker 减少 N 个工作进程。Celery 会优雅地关闭这些进程，意味着它们会先完成手中正在执行的任务，然后再退出。

# 语法: celery -A <app_name> control pool_shrink <N>
# 减少 2 个工作进程
celery -A tasks control pool_shrink 2

3. 针对特定的 Worker

在生产环境中，你可能运行了多个 Worker。你可以通过 -d (destination) 参数指定要控制的 Worker：

# 1. 首先，查看所有正在运行的 Worker
celery -A tasks status

# 2. 假设你看到一个名为 worker1@my-server 的 Worker
# 只给它增加并发
celery -A tasks control pool_grow 2 -d worker1@my-server

方法二：使用 --autoscale 自动伸缩（推荐）

这是一种更“自动化”的动态调整。你不需要手动干预，Celery Worker 会自己监控任务队列的压力，并在你设定的范围内自动增加或减少工作进程。

适用场景：

任务负载波动很大且难以预测（例如，白天任务多，晚上任务少）。
你希望“设置好就不用管了”，让系统自动优化资源。

1. 启动 Worker 时开启 Autoscaling

你需要在启动 Worker 时使用 --autoscale 选项，并提供最大并发数和最小并发数。

# 语法: celery -A <app_name> worker --autoscale=<max_concurrency>,<min_concurrency>
#
# 启动一个 Worker，它最少保留 2 个工作进程，
# 但在负载高时，最多可以扩展到 10 个进程
celery -A tasks worker --autoscale=10,2 --loglevel=info

工作原理： Worker 启动时会以 min_concurrency (2个) 进程开始。当它发现队列中等待的任务增多时，它会逐渐增加进程数（pool_grow），直到达到 max_concurrency (10个)。
当队列变空，任务处理完毕后，它会逐渐减少进程数（pool_shrink），直到回到 min_concurrency (2个)，以节省系统资源。

2. 动态调整 Autoscaler 的边界

最强大的功能是：你可以将方法一和方法二结合起来。

你可以在运行时动态调整那个开启了 --autoscale 的 Worker 的最大/最小边界！

这是通过 autoscale 控制命令完成的：

# 假设 Worker 以 --autoscale=10,2 启动
# 现在是高峰期，我们希望它最多能扩展到 20 个进程，最少保持 5 个
celery -A tasks control autoscale 20,5

Worker 收到命令后，会立即更新它的自动伸缩策略。

方法三：静态调整（需要重启）

这不算是“动态”调整，但作为对比也提一下。这就是你在启动时使用 -c (concurrency) 参数来固定并发数。

# 启动一个固定 8 个工作进程的 Worker
celery -A tasks worker -c 8

如果你用这种方式启动，你仍然可以使用 pool_grow 和 pool_shrink 来临时调整它。但是，一旦这个 Worker 重启，它又会回到固定的 -c 8。

总结与建议

方法	命令	效果	最佳场景
手动调整	`celery control pool_grow <N>`	立即增加 N 个进程	应对已知的突发流量
	`celery control pool_shrink <N>`	立即（优雅地）减少 N 个进程	立即降低服务器负载
自动伸缩	`celery worker --autoscale=<max>,<min>`	Worker 根据负载自动在 max 和 min 之间调整	生产环境中最推荐的常用方式
动态调参	`celery control autoscale <new_max>,<new_min>`	实时修改 `--autoscale` 的边界	运维时根据大趋势调整策略
静态设置	`celery worker -c <N>`	启动时固定 N 个进程	开发或负载恒定的简单场景

给你的建议：

在生产环境中，始终使用 --autoscale 启动你的 Worker。

celery -A tasks worker --autoscale=16,4

然后，当你需要根据全局策略（例如，知道接下来一周是旺季）调整时，使用 celery control autoscale 来调整边界。

celery -A tasks control autoscale 32,8

这样你就能同时获得自动化的便利性和手动调控的灵活性。

Building asynchronous APIs for handling long-term tasks and dynamic resources

Mon, 20 Oct 2025 15:59:14 +0800

教程：构建处理长时间任务和动态资源的异步 API

这是一个关于如何构建一个健壮的后端系统的教程，该系统用于处理你所描述的场景：一个API接口，用于调用一个可能执行很久、并且需要动态管理并发资源（例如，受限于CPU/内存/GPU）的函数。

我们将使用异步任务队列架构，这是解决此类问题的行业标准。

核心问题

为什么不能直接在API接口中调用这个耗时函数？

HTTP 超时：客户端（浏览器、APP）等待HTTP响应的时间是有限的（通常是30-60秒）。如果你的函数执行5分钟，客户端将收到一个“超时”错误，即使用户的任务最终成功了。
服务器资源耗尽：Web服务器（如 Uvicorn, Gunicorn）的工作进程是有限的。如果5个用户同时请求这个耗时5分钟的接口，你的5个Web进程将被全部占用，导致服务器在接下来的5分钟内无法响应任何其他请求（例如登录、获取数据等），服务器会“假死”。

解决方案：异步任务队列

我们将系统拆分为三个组件：

API 服务器 (Web Server)：一个轻量级的接口。它只负责接收请求，验证参数，然后把“任务”丢进一个队列，最后立即返回一个任务ID给客户端。
任务队列 (Message Broker)：一个中间件（我们使用 Redis）。它像一个“待办事项”列表，负责存储API服务器发来的任务。
工作单元 (Worker)：一个（或多个）独立于API服务器运行的进程。它唯一的工作就是盯着任务队列，一旦有新任务，就取出来执行。

这种架构如何解决你的问题：

长时间执行：API在1毫秒内就返回了响应（{"task_id": "xxx"}），客户端不需等待。客户端可以稍后使用task_id来轮询另一个接口查询结果。
动态资源：你可以根据服务器的资源（CPU、内存）来决定启动多少个Worker进程，或者配置每个Worker同时执行多少个任务。这就是你的“动态并发控制”。

技术栈

API 服务器: FastAPI (高性能Python Web框架)
任务队列系统: Celery (Python中最流行的任务队列)
消息中间件 / 结果存储: Redis (速度极快，Celery的完美搭档)

第 1 步：环境准备

安装 Python 库:
```
pip install "fastapi[all]" celery redis
```
- fastapi[all]：安装FastAPI及Uvicorn服务器。
- celery：Celery 框架。
- redis：Celery连接Redis所需的Python客户端。
启动 Redis: 最简单的方式是使用 Docker。如果你没有Docker，请从官网下载并运行。
```
# 这将在后台启动一个Redis服务器，端口为 6379
docker run -d -p 6379:6379 redis
```

第 2 步：项目结构

创建两个文件：


/your\_project
├── tasks.py \# 定义 Celery 应用和“耗时函数”
└── main.py \# 定义 FastAPI 接口

第 3 步：编写 Worker 和任务 (`tasks.py`)

这是你“耗时函数”的真正定义之处。

# tasks.py

import time
from celery import Celery

# 1. 初始化 Celery
# 'tasks' 是当前模块的名称
# broker 是任务队列，使用 Redis 的 0 号数据库
# backend 是结果存储，使用 Redis 的 1 号数据库
celery_app = Celery(
 'tasks',
 broker='redis://localhost:6379/0',
 backend='redis://localhost:6379/1'
)

# 2. 定义你那个“耗时很长、需要动态资源”的函数
# @celery_app.task 装饰器将其注册为 Celery 任务

@celery_app.task
def run_long_analysis(dataset_id: str, complexity: int) -> dict:
 """
 这是一个模拟的耗时任务。
 在真实世界中，这里可能是：
 - 运行一个复杂的AI模型
 - 生成一份巨大的报表
 - 转码一个视频文件
 - 调用第三方的慢速 API
 """

 print(f"[任务开始] 正在分析数据集 {dataset_id}，复杂度 {complexity}...")

 try:
 # 模拟长时间工作
 # 复杂度越高，工作时间越长
 duration = complexity * 5
 time.sleep(duration)

 # 模拟资源消耗... (这部分由 Celery 的并发设置来控制)

 # 任务执行完毕，返回结果
 result = {
 "status": "success",
 "dataset_id": dataset_id,
 "analysis_time_sec": duration,
 "result_url": f"[http://example.com/results/](http://example.com/results/){dataset_id}.zip"
 }
 print(f"[任务成功] {dataset_id} 分析完毕。")
 return result

 except Exception as e:
 # 异常处理
 print(f"[任务失败] {dataset_id} 分析失败: {e}")
 return {"status": "failed", "error": str(e)}

第 4 步：编写 API 接口 (`main.py`)

这是客户端唯一能“看到”的部分。

# main.py

from fastapi import FastAPI, status
from pydantic import BaseModel
from celery.result import AsyncResult

# 1. 导入在 tasks.py 中定义的任务和app
from tasks import run_long_analysis, celery_app

# 初始化 FastAPI
app = FastAPI(title="异步任务API", description="使用 FastAPI 和 Celery")

# 2. 定义 API 的请求体（Pydantic模型）
class TaskRequest(BaseModel):
 dataset_id: str
 complexity: int # 复杂度，1-10

# 3. 定义 API 的响应体
class TaskResponse(BaseModel):
 message: str
 task_id: str


# === 接口 1: 启动任务 ===
# 状态码 202 (Accepted) 表示“已接受，正在处理”
@app.post("/api/v1/start-analysis", status_code=status.HTTP_202_ACCEPTED, response_model=TaskResponse)
def start_analysis(request: TaskRequest):
 """
 接收分析请求，将其放入任务队列，并立即返回任务ID。
 """

 # 关键: .delay()
 # 这不会在当前进程中执行函数，而是将任务消息发送到 Redis 队列
 task = run_long_analysis.delay(request.dataset_id, request.complexity)

 # 立即返回响应
 return {
 "message": "任务已接收，正在后台处理",
 "task_id": task.id
 }


# === 接口 2: 查询任务状态/结果 ===
@app.get("/api/v1/task-status/{task_id}")
def get_task_status(task_id: str):
 """
 根据任务ID查询任务的状态和结果。
 """

 # 使用 Celery 的 AsyncResult 从 Backend (Redis) 中获取结果
 task_result = AsyncResult(task_id, app=celery_app)

 if task_result.ready():
 # 任务已完成
 if task_result.successful():
 # 任务成功
 return {
 "task_id": task_id,
 "status": task_result.status, # "SUCCESS"
 "result": task_result.result # run_long_analysis 返回的字典
 }
 else:
 # 任务失败
 return {
 "task_id": task_id,
 "status": task_result.status, # "FAILURE"
 "error": str(task_result.info) # 异常信息
 }
 else:
 # 任务仍在进行中
 return {
 "task_id": task_id,
 "status": task_result.status # "PENDING" 或 "STARTED"
 }

第 5 步：运行系统（关键）

你需要启动 3 个独立的进程（打开 3 个终端窗口）。

终端 1: 运行 Redis (如果你还没启动)

docker run -d -p 6379:6379 redis

终端 2: 运行 Celery Worker (耗时函数的执行者) 这是管理你“动态资源”的地方。

# -A tasks: 指定 Celery 应用在 tasks.py 文件中的 celery_app
# worker: 启动工作单元
# --loglevel=info: 打印日志
# --concurrency=4: !!! 核心控制 !!! 
# 这表示这个 Worker 进程“同时”最多执行 4 个任务。
# 如果你的机器有 16 核 CPU，并且资源充足，可以设为 16。
# 如果你的函数非常吃内存，可能只能设为 2。
# 这就是你的“动态资源管理”。
celery -A tasks worker --loglevel=info --concurrency=4

如何扩展? 如果一台机器的 concurrency=4 不够用，你可以在另一台机器上也运行这个命令，它们会连接同一个Redis，自动分担任务！

终端 3: 运行 API 服务器

# uvicorn 会运行 main.py 中的 app
uvicorn main:app --reload

--reload 模式会在你修改代码后自动重启，方便开发。

第 6 步：测试

现在你的整套系统都跑起来了。

1. 启动一个任务 (POST) 我们请求一个复杂度为 3 的任务（即 3 * 5 = 15 秒）。

curl -X POST "[http://127.0.0.1:8000/api/v1/start-analysis](http://127.0.0.1:8000/api/v1/start-analysis)" \
 -H "Content-Type: application/json" \
 -d '{"dataset_id": "data_xyz", "complexity": 3}'

你将立即收到响应：

{
 "message": "任务已接收，正在后台处理",
 "task_id": "a9b1c8d2-....."
}

同时，在终端 2 (Worker) 的日志中，你会看到它打印了 [任务开始] ...。

2. 查询任务状态 (GET) - 5秒后 使用上一步中获取的 task_id。

curl "[http://127.0.0.1:8000/api/v1/task-status/a9b1c8d2-](http://127.0.0.1:8000/api/v1/task-status/a9b1c8d2-)....."

因为任务还在运行（总共要15秒），你会收到：

{
 "task_id": "a9b1c8d2-.....",
 "status": "PENDING"
}

3. 查询任务状态 (GET) - 20秒后 再次运行上一个命令：

curl "[http://127.0.0.1:8000/api/v1/task-status/a9b1c8d2-](http://127.0.0.1:8000/api/v1/task-status/a9b1c8d2-)....."

现在任务完成了，你会收到：

{
 "task_id": "a9b1c8d2-.....",
 "status": "SUCCESS",
 "result": {
 "status": "success",
 "dataset_id": "data_xyz",
 "analysis_time_sec": 15,
 "result_url": "[http://example.com/results/data_xyz.zip](http://example.com/results/data_xyz.zip)"
 }
}

总结

你已经成功构建了一个可扩展、健壮的异步任务系统。

API 接口 (main.py)：轻量且响应迅速。
耗时函数 (tasks.py)：在后台的 Worker 中独立运行。
资源管理：通过 celery worker --concurrency=N 来精确控制并发数，N就是你根据“动态资源”决定的数量。

flask-构建一个简单的文件同步系统

Mon, 12 May 2025 09:59:01 +0800

使用Python构建文件同步系统：步骤指南

在当今互联网时代，能够在本地机器和远程服务器之间同步文件的能力变得至关重要。无论是备份重要文档、与团队成员共享大文件，还是在多个设备间保持数据一致性，一个强大的文件同步系统都能发挥重要作用。在这篇博客文章中，我们将逐步介绍如何使用Python构建一个简单而强大的文件同步系统，并为大文件传输添加进度条功能。

挑战

我们的目标是创建一个系统，能够：

将本地文件上传到远程服务器
从服务器下载文件到本地机器
检查服务器上是否存在某个文件
处理大文件传输并提供可视化反馈

解决方案

我们将分两部分构建我们的解决方案：一个使用Flask的服务器端应用程序，和一个与服务器交互的客户端脚本。

第一部分：服务器

首先，让我们使用Flask创建一个简单的服务器，它可以处理文件上传、下载和存在性检查。

from flask import Flask, request, send_file, jsonify
import os

app = Flask(__name__)
UPLOAD_FOLDER = 'uploads'
if not os.path.exists(UPLOAD_FOLDER):
 os.makedirs(UPLOAD_FOLDER)

@app.route('/upload', methods=['POST'])
def upload_file():
 if 'file' not in request.files:
 return jsonify({"error": "没有文件部分"}), 400
 file = request.files['file']
 if file.filename == '':
 return jsonify({"error": "没有选择文件"}), 400
 if file:
 filename = os.path.join(UPLOAD_FOLDER, file.filename)
 file.save(filename)
 return jsonify({"message": "文件上传成功"}), 200

@app.route('/download/<filename>', methods=['GET'])
def download_file(filename):
 filepath = os.path.join(UPLOAD_FOLDER, filename)
 if os.path.exists(filepath):
 return send_file(filepath, as_attachment=True)
 else:
 return jsonify({"error": "文件未找到"}), 404

@app.route('/check/<filename>', methods=['GET'])
def check_file(filename):
 filepath = os.path.join(UPLOAD_FOLDER, filename)
 if os.path.exists(filepath):
 return jsonify({"exists": True}), 200
 else:
 return jsonify({"exists": False}), 200

if __name__ == '__main__':
 app.run(host='0.0.0.0', port=5000)

这个服务器提供了三个主要端点：

/upload 用于文件上传
/download/<filename> 用于文件下载
/check/<filename> 用于检查服务器上是否存在某个文件

第二部分：客户端

现在，让我们创建一个客户端脚本，它可以与我们的服务器交互并处理文件同步。我们将使用 requests 库进行HTTP通信，使用 tqdm 库来显示进度条。

import requests
import os
from tqdm import tqdm

SERVER_URL = "http://your_server_ip:5000"

def upload_file(filename):
 file_size = os.path.getsize(filename)
 with open(filename, 'rb') as f:
 with tqdm(total=file_size, unit='B', unit_scale=True, desc=f"正在上传 {filename}") as pbar:
 response = requests.post(
 f"{SERVER_URL}/upload",
 files={"file": f},
 data={"filename": os.path.basename(filename)},
 headers={"Content-Length": str(file_size)},
 stream=True
 )
 for chunk in response.iter_content(chunk_size=8192):
 if chunk:
 pbar.update(len(chunk))
 print(response.json())

def download_file(filename):
 with requests.get(f"{SERVER_URL}/download/{filename}", stream=True) as response:
 if response.status_code == 200:
 total_size = int(response.headers.get('content-length', 0))
 with open(filename, 'wb') as f, tqdm(
 total=total_size, unit='B', unit_scale=True, desc=f"正在下载 {filename}"
 ) as pbar:
 for chunk in response.iter_content(chunk_size=8192):
 if chunk:
 size = f.write(chunk)
 pbar.update(size)
 print(f"文件 {filename} 下载成功")
 else:
 print(response.json())

def check_file(filename):
 response = requests.get(f"{SERVER_URL}/check/{filename}")
 return response.json()['exists']

def sync_file(filename):
 if os.path.exists(filename) and not check_file(filename):
 print(f"正在将 {filename} 上传到服务器...")
 upload_file(filename)
 elif check_file(filename) and not os.path.exists(filename):
 print(f"正在从服务器下载 {filename}...")
 download_file(filename)
 elif not check_file(filename) and not os.path.exists(filename):
 print(f"文件 {filename} 在本地和服务器上都不存在")
 else:
 print(f"文件 {filename} 在本地和服务器上都已存在")

# 使用示例
sync_file("large_file.zip")

这个客户端脚本提供了几个关键功能：

文件上传：将文件发送到服务器，并显示进度条。
文件下载：从服务器检索文件，并显示进度条。
文件检查：验证服务器上是否存在某个文件。
同步逻辑：根据文件在本地和服务器上的存在情况，决定是上传、下载还是跳过该文件。

sync_file 函数封装了我们的同步逻辑：

如果文件在本地存在但服务器上不存在，则上传。
如果文件在服务器上存在但本地不存在，则下载。
如果文件在两个位置都不存在，我们会得到通知。
如果文件在两个位置都存在，我们会得到通知，无需采取任何操作。

整合使用

要使用这个文件同步系统：

在您的远程机器上启动Flask服务器。
在客户端脚本中更新 SERVER_URL，使其指向您的服务器。
运行客户端脚本，指定您想要同步的文件。

此外，如果你是本地服务器，进行了内网穿透，可以使用以下代码，优先使用本地ip地址，下面代码做了优化，将函数封装成为一个类

import requests
import os
from tqdm import tqdm
import time

class FileSync:
 def __init__(self, server_url1, server_url2):
 self.SERVER_URL1 = server_url1
 self.SERVER_URL2 = server_url2
 self.server_url = None

 def check_server(self, url):
 try:
 response = requests.get(url, timeout=5)
 return response.status_code == 200
 except requests.RequestException:
 return False

 def get_server_url(self):
 if self.check_server(self.SERVER_URL1 + "check/test.txt"):
 self.server_url = self.SERVER_URL1
 return self.SERVER_URL1
 elif self.check_server(self.SERVER_URL2 + "check/test.txt"):
 self.server_url = self.SERVER_URL2
 return self.SERVER_URL2
 else:
 raise Exception("无法连接到任何服务器")

 def upload_file(self, filename):
 self.get_server_url()
 file_size = os.path.getsize(filename)
 with open(filename, 'rb') as f:
 with tqdm(total=file_size, unit='B', unit_scale=True, desc=f"正在上传 {filename}") as pbar:
 response = requests.post(
 f"{self.server_url}upload",
 files={"file": (os.path.basename(filename), f)},
 data={"filename": os.path.basename(filename)},
 stream=True
 )
 for chunk in iter(lambda: f.read(8192), b''):
 if chunk:
 pbar.update(len(chunk))
 print(response.json())

 def download_file(self, filename):
 self.get_server_url()
 with requests.get(f"{self.server_url}download/{os.path.basename(filename)}", stream=True) as response:
 if response.status_code == 200:
 total_size = int(response.headers.get('content-length', 0))
 block_size = 8192
 with open(filename, 'wb') as f, tqdm(
 total=total_size, unit='B', unit_scale=True, desc=f"正在下载 {filename}"
 ) as pbar:
 for chunk in response.iter_content(block_size):
 size = f.write(chunk)
 pbar.update(size)
 print(f"文件 {filename} 下载成功")
 else:
 print(response.json())

 def check_file(self, filename):
 self.get_server_url()
 basename = os.path.basename(filename)
 response = requests.get(f"{self.server_url}check/{basename}")
 return response.json()['exists']

 def sync_file(self, filename):
 try:
 self.get_server_url() # 确保使用可用的服务器
 basename = os.path.basename(filename)
 if os.path.exists(filename) and not self.check_file(basename):
 print(f"正在将 {filename} 上传到服务器...")
 self.upload_file(filename)
 elif self.check_file(basename) and not os.path.exists(filename):
 print(f"正在从服务器下载 {filename}...")
 self.download_file(filename)
 elif not self.check_file(basename) and not os.path.exists(filename):
 print(f"文件 {filename} 在本地和服务器上都不存在")
 else:
 print(f"文件 {filename} 在本地和服务器上都已存在")
 except Exception as e:
 print(f"同步过程中发生错误: {str(e)}")

# 使用示例
if __name__ == "__main__":
 sync = FileSync("http://你弟内网ip/:5000", "http://你的公网ip:5000")
 # print(sync.check_file("test.txt"))
 sync.sync_file(r"C:\BaiduSyncdisk\code&note\0A-ZATA\data\光谱数据\MZI酒精数据_21&27&79&30_.xlsx")

结论

这个简单而有效的文件同步系统展示了我们如何利用Python创建强大的工具来管理不同位置的数据。添加进度条使其特别适用于处理大文件，在可能较长的传输操作期间提供视觉反馈。

虽然这个系统是一个很好的起点，但还有许多方式可以扩展它：

添加身份验证以实现安全的文件传输
实现文件版本控制
创建监视系统，自动同步更改
开发图形用户界面，便于交互

祝您编码愉快，愿您的文件永远保持同步！

Jinja是什么？可以用在做什么？

Thu, 08 May 2025 22:00:28 +0800

Jinaja的基础概念

Jinja 是一款强大且流行的 Python 模板引擎。简单来说，它允许你创建包含占位符和逻辑的文本文件（模板），然后用动态数据填充这些占位符，最终生成新的文本文件。

Jinja 可以用来做什么？

Jinja 的用途非常广泛，尤其在以下领域：

Web 开发 (最常见的用途):
- 动态生成 HTML 页面: 这是 Jinja 最核心的应用。你可以创建 HTML 模板，其中包含动态内容（如用户信息、文章列表、产品详情等）的占位符。当用户请求页面时，Jinja 会将从数据库或其他来源获取的数据填充到模板中，生成最终的 HTML 页面发送给用户的浏览器。许多流行的 Python Web 框架，如 Flask 和 Django (虽然 Django 有自己的模板系统，但也可以集成 Jinja)，都广泛使用 Jinja。
- 生成其他 Web 内容: 除了 HTML，Jinja 也可以用来生成 XML、JSON、CSS、JavaScript 等任何基于文本的 Web 内容。
配置文件生成:
- 当需要为不同的环境（开发、测试、生产）或不同的服务器生成相似但略有差异的配置文件时，Jinja 非常有用。你可以创建一个基础的配置文件模板，然后根据具体需求传入不同的变量来生成特定的配置文件。
代码生成:
- 在某些情况下，Jinja 可以用来根据元数据或模型定义自动生成重复性的代码片段，甚至是整个代码文件。
邮件模板:
- 生成个性化的邮件内容。你可以创建邮件模板，其中包含问候语、用户特定的信息等占位符，然后用实际数据填充，发送给不同的用户。
报告生成:
- 生成基于文本的报告，例如 CSV 文件或纯文本报告，其中包含动态数据。
任何需要基于模板生成文本的场景:
- 只要你需要根据一些动态数据来生成结构化的文本输出，Jinja 都可以派上用场。

Jinja 的核心特性与优势：

易于理解和使用: Jinja 的语法设计简洁明了，借鉴了 Django 模板语言和 Python 的一些特性，对于有 Python 基础的开发者来说很容易上手。
功能强大:
- 变量插值: 使用 {{ variable_name }} 将变量的值插入到模板中。
- 控制结构: 支持 {% for %} 循环、{% if %} 条件判断等逻辑控制，使得模板具有动态行为。
- 模板继承 (Template Inheritance): 允许你创建一个基础模板 (layout)，其中包含网站的通用结构（如页眉、页脚、导航栏），然后其他子模板可以继承这个基础模板并覆盖或扩展特定的区块 (blocks)。这极大地提高了代码的复用性和可维护性。
- 宏 (Macros): 类似于编程语言中的函数，允许你定义可重用的模板片段，可以接收参数并返回值。
- 过滤器 (Filters): 使用管道符 | 对变量进行处理和转换，例如格式化日期 ({{ my_date|dateformat('%Y-%m-%d') }}), 首字母大写 ({{ my_string|capitalize }}), 计算长度 ({{ my_list|length }}) 等。Jinja 内置了许多有用的过滤器，也支持自定义过滤器。
- 测试 (Tests): 用于检查变量的特定状态，例如判断一个变量是否已定义 ({% if name is defined %}), 是否为偶数 ({% if number is even %}) 等。
- 包含 (Includes): 使用 {% include 'template_name.html' %} 可以将一个模板的内容包含到另一个模板中，方便组织和重用小的模板片段。
- 转义 (Escaping): 默认情况下，Jinja 会对输出的变量进行 HTML 转义，以防止跨站脚本攻击 (XSS)。这是非常重要的安全特性。你可以使用 |safe 过滤器来显式禁止转义（但要确保内容是安全的）。
- 沙箱执行 (Sandboxed Execution): Jinja 模板在受限的环境中执行，可以防止模板作者执行不安全的操作。
高性能: Jinja 会将模板编译成 Python 字节码来执行，从而获得较好的性能。
可扩展性: 允许开发者自定义过滤器、测试、全局函数和扩展。
广泛的社区支持和文档: 作为一款流行的工具，Jinja 拥有庞大的用户社区和完善的官方文档，遇到问题时很容易找到解决方案。

Jinja 模板基本语法示例：

<!DOCTYPE html>
<html>
<head>
 <title>{{ page_title }}</title>
</head>
<body>
 <h1>Hello, {{ username|capitalize }}!</h1>

 {% if items %}
 <h2>Here are your items:</h2>
 <ul>
 {% for item in items %}
 <li>{{ item }}</li>
 {% endfor %}
 </ul>
 {% else %}
 <p>You have no items.</p>
 {% endif %}

 {% include 'footer.html' %}
</body>
</html>

在这个例子中：

{{ page_title }} 和 {{ username|capitalize }} 是变量插值，|capitalize 是一个过滤器。
{% if items %} … {% else %} … {% endif %} 是条件判断。
{% for item in items %} … {% endfor %} 是循环。
{% include 'footer.html' %} 包含了另一个模板文件。

总结来说，Jinja 是一个功能丰富、灵活且高效的 Python 模板引擎，它通过将数据与模板分离，使得动态生成文本内容（尤其是 HTML）变得更加简单、清晰和可维护。它是 Python Web 开发中不可或缺的工具之一，并且在其他需要文本生成的场景中也表现出色。

Flask使用教程

Mon, 10 Mar 2025 16:00:15 +0800

Flak的基础语法和使用

1. 安装 Flask

首先，你需要安装 Flask。确保你已经安装了 Python（推荐使用 Python 3.7 或以上版本）。可以通过 pip 安装 Flask：

pip install flask

安装完成后，你可以在 Python 解释器中验证是否成功安装：

import flask
print(flask.__version__)

如果没有报错并输出版本号，说明 Flask 已成功安装。

2. 创建一个简单的 Flask 应用

让我们创建一个最基本的 Flask 应用。以下是一个简单的示例代码，保存为 app.py：

from flask import Flask

# 创建 Flask 应用实例
app = Flask(__name__)

# 定义路由和视图函数
@app.route('/')
def home():
 return '欢迎使用 Flask!'

# 运行应用
if __name__ == '__main__':
 app.run(debug=True)

代码解释：

Flask(__name__)：创建一个 Flask 应用实例，__name__ 是 Python 的内置变量，表示当前模块的名称。
@app.route('/')：定义一个路由，当用户访问根路径（/）时，触发下面的函数。
app.run(debug=True)：启动 Flask 内置的开发服务器，debug=True 启用调试模式，方便开发时查看错误。

运行应用：

在终端中进入文件所在目录，运行以下命令：

python app.py

然后在浏览器中访问 http://127.0.0.1:5000/，你会看到页面显示“欢迎使用 Flask!”。

3. 添加更多路由

Flask 允许你定义多个路由。例如，我们可以添加一个新的路由 /hello：

from flask import Flask

app = Flask(__name__)

@app.route('/')
def home():
 return '欢迎使用 Flask!'

@app.route('/hello')
def hello():
 return '你好，世界!'

if __name__ == '__main__':
 app.run(debug=True)

访问 http://127.0.0.1:5000/hello，你会看到“你好，世界!”。

动态路由：

你还可以通过路由参数传递动态值，例如：

@app.route('/user/<name>')
def user(name):
 return f'你好，{name}!'

访问 http://127.0.0.1:5000/user/Alice，页面会显示“你好，Alice!”。

from flask import Flask, request

app = Flask(__name__)

@app.route('/greet')
def greet():
 # Access query string parameters using request.args
 name = request.args.get('name', 'Guest') # Default to 'Guest' if 'name' is not provided
 return f'你好，{name}!'

if __name__ == '__main__':
 app.run(debug=True)

在浏览器中访问 URL_ADDRESS在浏览器中访问 http://127.0.0.1:5000/greet?name=Alice`，页面会显示“你好，Alice!”。

4. 使用模板渲染 HTML

直接返回字符串不适合复杂的页面。Flask 支持使用 Jinja2 模板引擎来渲染 HTML 文件。首先，创建一个 templates 文件夹，并在其中创建一个文件 index.html：

<!DOCTYPE html>
<html>
<head>
 <title>Flask 教程</title>
</head>
<body>
 <h1>欢迎，{{ name }}!</h1>
</body>
</html>

然后修改 app.py 使用模板：

from flask import Flask, render_template

app = Flask(__name__)

@app.route('/user/<name>')
def user(name):
 return render_template('index.html', name=name)

if __name__ == '__main__':
 app.run(debug=True)

render_template：渲染模板并传入变量（这里是 name）。

文件结构：

项目文件夹/
├── app.py
└── templates/
 └── index.html

访问 http://127.0.0.1:5000/user/Bob，页面会显示“欢迎，Bob!”。

5. 使用过滤器

Jinja2 提供了许多内置过滤器，用于在模板中处理变量。你也可以自定义过滤器。以下是一些常见的用法。

修改 `app.py`

我们将传递更多数据到模板中，以便展示过滤器的效果：

from flask import Flask, render_template

app = Flask(__name__)

@app.route('/user/<name>')
def user(name):
 user_data = {
 'name': name,
 'age': 25,
 'bio': '这是一个简单的介绍。',
 'join_date': '2023-10-15'
 }
 return render_template('index.html', **user_data)

if __name__ == '__main__':
 app.run(debug=True)

修改 `templates/index.html`

添加一些过滤器示例：

<!DOCTYPE html>
<html>
<head>
 <title>Flask 教程</title>
</head>
<body>
 <h1>欢迎，{{ name | upper }}!</h1>
 <p>年龄: {{ age | default('未知') }}</p>
 <p>简介: {{ bio | truncate(10) }}</p>
 <p>加入日期: {{ join_date | replace('-', '/') }}</p>
 <p>名字长度: {{ name | length }}</p>
</body>
</html>

过滤器说明

| upper：将字符串转换为大写，例如“alice”变成“ALICE”。
| default('未知')：如果变量未定义或为空，则显示默认值“未知”。
| truncate(10)：截断字符串到指定长度（这里是 10 个字符），超出部分用省略号表示。
| replace('-', '/')：将字符串中的“-”替换为“/”，例如“2023-10-15”变成“2023/10/15”。
| length：返回变量的长度，例如“Alice”的长度是 5。

运行结果

访问 http://127.0.0.1:5000/user/Alice，页面显示：

欢迎，ALICE!
年龄: 25
简介: 这是一个简...
加入日期: 2023/10/15
名字长度: 5

自定义过滤器

如果内置过滤器不够用，可以定义自己的过滤器。例如，我们添加一个反转字符串的过滤器：

修改 app.py：

from flask import Flask, render_template

app = Flask(__name__)

# 自定义过滤器：反转字符串
@app.template_filter('reverse')
def reverse_filter(s):
 return s[::-1]

@app.route('/user/<name>')
def user(name):
 user_data = {
 'name': name,
 'age': 25,
 'bio': '这是一个简单的介绍。',
 'join_date': '2023-10-15'
 }
 return render_template('index.html', **user_data)

if __name__ == '__main__':
 app.run(debug=True)

修改 index.html，添加自定义过滤器：

<!DOCTYPE html>
<html>
<head>
 <title>Flask 教程</title>
</head>
<body>
 <h1>欢迎，{{ name | upper }}!</h1>
 <p>年龄: {{ age | default('未知') }}</p>
 <p>简介: {{ bio | truncate(10) }}</p>
 <p>加入日期: {{ join_date | replace('-', '/') }}</p>
 <p>名字长度: {{ name | length }}</p>
 <p>反转名字: {{ name | reverse }}</p>
</body>
</html>

访问 http://127.0.0.1:5000/user/Alice，页面会多一行：

反转名字: ecilA

@app.template_filter('reverse')：注册一个名为 reverse 的自定义过滤器。
s[::-1]：Python 切片语法，反转字符串。

6. 处理表单数据

Flask 可以轻松处理用户提交的表单数据。以下是一个简单的例子，包含 GET 和 POST 请求：

修改 `templates/index.html`：

<!DOCTYPE html>
<html>
<head>
 <title>Flask 表单</title>
</head>
<body>
 <h1>提交你的名字</h1>
 <form method="POST">
 <input type="text" name="username">
 <input type="submit" value="提交">
 </form>
 {% if name %}
 <h2>你好，{{ name }}!</h2>
 {% endif %}
</body>
</html>

修改 `app.py`：

from flask import Flask, render_template, request

app = Flask(__name__)

@app.route('/', methods=['GET', 'POST'])
def home():
 name = None
 if request.method == 'POST':
 name = request.form['username']
 return render_template('index.html', name=name)

if __name__ == '__main__':
 app.run(debug=True)

request：从 Flask 中导入，用于获取表单数据。
methods=['GET', 'POST']：允许该路由处理 GET 和 POST 请求。
request.form['username']：获取表单中 name="username" 的输入值。

运行后，访问 http://127.0.0.1:5000/，输入名字并提交，会显示欢迎信息。

7. 使用控制语句

Jinja2 模板支持控制语句，主要包括条件语句（if、elif、else）和循环语句（for）。这些语句可以根据传入的数据动态渲染内容。

修改 `app.py`

我们将传递一个包含用户列表的数据，并添加一些条件判断的变量：

from flask import Flask, render_template

app = Flask(__name__)

# 自定义过滤器：反转字符串
@app.template_filter('reverse')
def reverse_filter(s):
 return s[::-1]

@app.route('/users')
def users():
 user_list = [
 {'name': 'Alice', 'age': 25, 'active': True},
 {'name': 'Bob', 'age': 30, 'active': False},
 {'name': 'Charlie', 'age': 15, 'active': True}
 ]
 show_details = True # 用于条件语句
 return render_template('users.html', users=user_list, show_details=show_details)

if __name__ == '__main__':
 app.run(debug=True)

创建 `templates/users.html`

在 templates 文件夹中新建 users.html，添加条件语句和循环语句：

<!DOCTYPE html>
<html>
<head>
 <title>用户列表</title>
</head>
<body>
 <h1>用户列表</h1>

 <!-- 循环语句：遍历用户列表 -->
 <ul>
 {% for user in users %}
 <li>
 {{ user.name }} (年龄: {{ user.age }})
 <!-- 条件语句：根据 active 显示状态 -->
 {% if user.active %}
 <span style="color: green;">活跃</span>
 {% else %}
 <span style="color: red;">不活跃</span>
 {% endif %}
 </li>
 {% endfor %}
 </ul>

 <!-- 条件语句：是否显示详细信息 -->
 {% if show_details %}
 <h2>额外信息</h2>
 <p>总用户数: {{ users | length }}</p>
 <p>第一个用户: {{ users[0].name | upper }}</p>
 {% else %}
 <p>详细信息已隐藏</p>
 {% endif %}

 <!-- 多条件示例 -->
 {% for user in users %}
 {% if user.age >= 18 and user.active %}
 <p>{{ user.name }} 是成年活跃用户</p>
 {% elif user.age < 18 %}
 <p>{{ user.name }} 是未成年</p>
 {% endif %}
 {% endfor %}
</body>
</html>

控制语句说明

循环语句 for：
- {% for user in users %}：遍历 users 列表，user 是每次循环的单个元素。
- 在 <ul> 中动态生成每个用户的 <li> 标签。
条件语句 if：
- {% if user.active %}：检查用户是否活跃，显示不同颜色状态。
- {% if show_details %}：根据 show_details 的值决定是否显示额外信息。
- {% elif %} 和 {% else %}：支持多条件分支。
结合过滤器：
- {{ users | length }}：计算用户列表长度。
- {{ users[0].name | upper }}：将第一个用户的名字转换为大写。

运行结果

访问 http://127.0.0.1:5000/users，页面显示：

用户列表
- Alice (年龄: 25) 活跃
- Bob (年龄: 30) 不活跃
- Charlie (年龄: 15) 活跃

额外信息
总用户数: 3
第一个用户: ALICE

Alice 是成年活跃用户
Charlie 是未成年

修改条件

如果你将 app.py 中的 show_details = True 改为 False，则“额外信息”部分会变为：

详细信息已隐藏

嵌套控制语句

你还可以在循环中嵌套条件语句，或者在条件中嵌套循环。例如，添加一个嵌套示例到 users.html：

<!-- 嵌套示例：列出活跃用户 -->
<h2>活跃用户</h2>
<ul>
{% for user in users if user.active %}
 <li>{{ user.name }}</li>
{% endfor %}
</ul>

这会输出：

活跃用户
- Alice
- Charlie

{% for user in users if user.active %}：直接在 for 循环中过滤，只遍历活跃用户。

8. 添加静态文件

Flask 支持静态文件（如 CSS、图片等）。创建一个 static 文件夹，并在其中添加 style.css：

h1 {
 color: blue;
}

修改 index.html 引入样式：

<!DOCTYPE html>
<html>
<head>
 <title>Flask 表单</title>
 <link rel="stylesheet" href="{{ url_for('static', filename='style.css') }}">
</head>
<body>
 <h1>提交你的名字</h1>
 <form method="POST">
 <input type="text" name="username">
 <input type="submit" value="提交">
 </form>
 {% if name %}
 <h2>你好，{{ name }}!</h2>
 {% endif %}
</body>
</html>

url_for('static', filename='style.css')：生成静态文件的 URL。

文件结构：

项目文件夹/
├── app.py
├── static/
│ └── style.css
└── templates/
 └── index.html

重新运行应用，标题会变成蓝色。

9. 模板继承

模板继承通过定义一个基础模板（包含通用结构），然后在子模板中扩展特定部分，非常适合构建具有一致布局的网站。

创建基础模板 `templates/base.html`

在 templates 文件夹中创建 base.html：

<!DOCTYPE html>
<html>
<head>
 <title>{% block title %}默认标题{% endblock %}</title>
 <link rel="stylesheet" href="{{ url_for('static', filename='style.css') }}">
</head>
<body>
 <header>
 <h1>欢迎使用 Flask</h1>
 <nav>
 <a href="{{ url_for('home') }}">首页</a> |
 <a href="{{ url_for('users') }}">用户列表</a>
 </nav>
 </header>

 <!-- 内容块，子模板可以覆盖 -->
 {% block content %}
 <p>这是默认内容</p>
 {% endblock %}

 <footer>
 <p>&copy; 2025 Flask 教程</p>
 </footer>
</body>
</html>

{% block title %} 和 {% block content %}：定义可被子模板覆盖的块。
{{ url_for('xxx') }}：动态生成路由链接。
静态文件 style.css 已在上文提到，确保 static 文件夹中有该文件。

修改 `app.py`

添加首页路由，并更新用户路由以使用模板继承：

from flask import Flask, render_template

app = Flask(__name__)

# 自定义过滤器：反转字符串
@app.template_filter('reverse')
def reverse_filter(s):
 return s[::-1]

@app.route('/')
def home():
 return render_template('home.html')

@app.route('/users')
def users():
 user_list = [
 {'name': 'Alice', 'age': 25, 'active': True},
 {'name': 'Bob', 'age': 30, 'active': False},
 {'name': 'Charlie', 'age': 15, 'active': True}
 ]
 show_details = True
 return render_template('users.html', users=user_list, show_details=show_details)

if __name__ == '__main__':
 app.run(debug=True)

创建子模板 `templates/home.html`

继承 base.html，覆盖特定块：

{% extends "base.html" %}

{% block title %}首页{% endblock %}

{% block content %}
 <h2>欢迎来到首页</h2>
 <p>这是一个简单的 Flask 应用示例。</p>
{% endblock %}

{% extends "base.html" %}：指定继承的基础模板。
{% block title %}：覆盖标题块。
{% block content %}：覆盖内容块。

修改 `templates/users.html` 使用继承

将之前的 users.html 修改为继承 base.html：

{% extends "base.html" %}

{% block title %}用户列表{% endblock %}

{% block content %}
 <h2>用户列表</h2>
 <ul>
 {% for user in users %}
 <li>
 {{ user.name }} (年龄: {{ user.age }})
 {% if user.active %}
 <span style="color: green;">活跃</span>
 {% else %}
 <span style="color: red;">不活跃</span>
 {% endif %}
 </li>
 {% endfor %}
 </ul>

 {% if show_details %}
 <h3>额外信息</h3>
 <p>总用户数: {{ users | length }}</p>
 <p>第一个用户: {{ users[0].name | upper }}</p>
 {% else %}
 <p>详细信息已隐藏</p>
 {% endif %}

 <h3>活跃用户</h3>
 <ul>
 {% for user in users if user.active %}
 <li>{{ user.name }}</li>
 {% endfor %}
 </ul>
{% endblock %}

文件结构

项目文件夹/
├── app.py
├── static/
│ └── style.css
└── templates/
 ├── base.html
 ├── home.html
 └── users.html

运行结果

访问 http://127.0.0.1:5000/（首页）：

欢迎使用 Flask
首页 | 用户列表
欢迎来到首页
这是一个简单的 Flask 应用示例。
© 2025 Flask 教程

访问 http://127.0.0.1:5000/users（用户列表）：

欢迎使用 Flask
首页 | 用户列表
用户列表
- Alice (年龄: 25) 活跃
- Bob (年龄: 30) 不活跃
- Charlie (年龄: 15) 活跃
额外信息
总用户数: 3
第一个用户: ALICE
活跃用户
- Alice
- Charlie
© 2025 Flask 教程

扩展说明

保留父模板内容：如果想在子模板中保留父模板的块内容，可以使用 {{ super() }}。例如：
```
{% block content %}
 {{ super() }}
 <p>追加的内容</p>
{% endblock %}
```
这会在子模板中保留 base.html 的默认内容 <p>这是默认内容</p> 并追加新内容。
多级继承：你可以让一个子模板再被其他模板继承，形成多级结构。

10. 部署（简单说明）

开发完成后，你可能想将应用部署到服务器上。常用方法：

使用 gunicorn（生产环境 Web 服务器）：

pip install gunicorn
gunicorn --bind 0.0.0.0:8000 app:app

配合 Nginx 或其他反向代理服务器。

在本地调试时，app.run() 就足够了。

总结

这是一个 Flask 的基础教程，涵盖了安装、路由、模板、表单和静态文件的使用。你可以根据需求扩展功能，例如连接数据库（如 Flask-SQLAlchemy）、添加用户认证等。如果需要更深入的讲解或特定功能，请告诉我！

Flask操作数据库

下面是一个使用 Flask 操作数据库的教程，基于 Python 的 Flask 框架和常见的 SQLite 数据库（也可以扩展到其他数据库如 MySQL 或 PostgreSQL）。我会逐步介绍如何设置 Flask 应用、连接数据库、执行 CRUD 操作（创建、读取、更新、删除），并提供示例代码。

Flask 操作数据库教程

Flask 是一个轻量级的 Python Web 框架，结合数据库操作可以快速构建动态网站或 API。本教程将使用 SQLite 作为数据库，因为它是 Python 内置的，无需额外安装。你也可以根据需要替换为其他数据库。

环境准备

在开始之前，确保你已安装 Python，并准备好以下工具：

安装 Flask
在终端运行以下命令：
```
pip install flask
```
数据库工具
本教程使用 SQLite，无需额外安装。如果想使用 MySQL 或 PostgreSQL，可以安装对应驱动，例如 pip install pymysql 或 pip install psycopg2。

项目结构
创建一个项目文件夹，结构如下：

flask_db_demo/
├── app.py
├── templates/
│ └── index.html
└── database.db (稍后生成)

步骤 1：初始化 Flask 和数据库

创建一个简单的 Flask 应用并连接 SQLite 数据库。

代码示例：app.py

from flask import Flask, render_template, request, redirect, url_for
import sqlite3

app = Flask(__name__)

# 数据库连接函数
def get_db_connection():
 conn = sqlite3.connect('database.db')
 conn.row_factory = sqlite3.Row # 返回字典形式的行数据
 return conn

# 初始化数据库和表
def init_db():
 conn = get_db_connection()
 conn.execute('''CREATE TABLE IF NOT EXISTS users (
 id INTEGER PRIMARY KEY AUTOINCREMENT,
 name TEXT NOT NULL,
 email TEXT NOT NULL UNIQUE)''')
 conn.commit()
 conn.close()

# 在应用启动时初始化数据库
init_db()

@app.route('/')
def index():
 return "Hello, Flask with Database!"

if __name__ == '__main__':
 app.run(debug=True)

说明

数据库连接：get_db_connection() 函数建立与 SQLite 文件 database.db 的连接。
表创建：init_db() 函数创建一个名为 users 的表，包含 id、name 和 email 字段。
启动应用：运行 python app.py，访问 http://127.0.0.1:5000/ 查看结果。

步骤 2：实现 CRUD 操作

接下来，我们将实现数据库的增删改查功能，并通过网页展示。

1. 创建（Create）数据

添加一个路由，允许用户通过表单提交数据。

修改 app.py

@app.route('/add', methods=['GET', 'POST'])
def add_user():
 if request.method == 'POST':
 name = request.form['name']
 email = request.form['email']
 conn = get_db_connection()
 conn.execute('INSERT INTO users (name, email) VALUES (?, ?)', (name, email))
 conn.commit()
 conn.close()
 return redirect(url_for('index'))
 return render_template('add_user.html')

创建 templates/add_user.html

<!DOCTYPE html>
<html>
<head>
 <title>Add User</title>
</head>
<body>
 <h2>Add New User</h2>
 <form method="POST">
 <label>Name:</label><input type="text" name="name" required><br>
 <label>Email:</label><input type="email" name="email" required><br>
 <button type="submit">Add</button>
 </form>
 <a href="{{ url_for('index') }}">Back to Home</a>
</body>
</html>

2. 读取（Read）数据

修改首页路由，显示所有用户信息。

修改 app.py

@app.route('/')
def index():
 conn = get_db_connection()
 users = conn.execute('SELECT * FROM users').fetchall()
 conn.close()
 return render_template('index.html', users=users)

创建 templates/index.html

<!DOCTYPE html>
<html>
<head>
 <title>User List</title>
</head>
<body>
 <h2>User List</h2>
 <table border="1">
 <tr>
 <th>ID</th>
 <th>Name</th>
 <th>Email</th>
 <th>Actions</th>
 </tr>
 {% for user in users %}
 <tr>
 <td>{{ user['id'] }}</td>
 <td>{{ user['name'] }}</td>
 <td>{{ user['email'] }}</td>
 <td>
 <a href="{{ url_for('edit_user', id=user['id']) }}">Edit</a> |
 <a href="{{ url_for('delete_user', id=user['id']) }}" onclick="return confirm('Are you sure?')">Delete</a>
 </td>
 </tr>
 {% endfor %}
 </table>
 <br>
 <a href="{{ url_for('add_user') }}">Add New User</a>
</body>
</html>

3. 更新（Update）数据

添加编辑用户的路由和页面。

修改 app.py

@app.route('/edit/<int:id>', methods=['GET', 'POST'])
def edit_user(id):
 conn = get_db_connection()
 if request.method == 'POST':
 name = request.form['name']
 email = request.form['email']
 conn.execute('UPDATE users SET name = ?, email = ? WHERE id = ?', (name, email, id))
 conn.commit()
 conn.close()
 return redirect(url_for('index'))
 user = conn.execute('SELECT * FROM users WHERE id = ?', (id,)).fetchone()
 conn.close()
 return render_template('edit_user.html', user=user)

创建 templates/edit_user.html

<!DOCTYPE html>
<html>
<head>
 <title>Edit User</title>
</head>
<body>
 <h2>Edit User</h2>
 <form method="POST">
 <label>Name:</label><input type="text" name="name" value="{{ user['name'] }}" required><br>
 <label>Email:</label><input type="email" name="email" value="{{ user['email'] }}" required><br>
 <button type="submit">Update</button>
 </form>
 <a href="{{ url_for('index') }}">Back to Home</a>
</body>
</html>

4. 删除（Delete）数据

添加删除用户的路由。

修改 app.py

@app.route('/delete/<int:id>')
def delete_user(id):
 conn = get_db_connection()
 conn.execute('DELETE FROM users WHERE id = ?', (id,))
 conn.commit()
 conn.close()
 return redirect(url_for('index'))

步骤 3：运行和测试

保存所有文件。
在终端运行 python app.py。
打开浏览器访问 http://127.0.0.1:5000/。
测试添加、编辑、删除用户功能。

注意事项

安全性
- 当前示例未处理表单验证和 SQL 注入防护（已使用参数化查询避免基本注入）。
- 生产环境中建议使用 Flask-WTF 和 CSRF 保护。
扩展性
- 可替换 SQLite 为 MySQL 或 PostgreSQL，只需修改连接字符串和驱动。
- 推荐使用 ORM（如 SQLAlchemy）简化数据库操作。
调试
- app.run(debug=True) 仅用于开发，生产环境需使用 WSGI 服务器（如 Gunicorn）。

总结

通过本教程，你学会了如何在 Flask 中连接 SQLite 数据库并实现基本的 CRUD 操作。你可以根据需求扩展功能，例如添加用户认证、分页或 API 接口。如果有疑问，欢迎提问！

Flask 与后端模式 on 扎塔-Zata

Celery

Celery 详细使用教程：从入门到实践

什么是 Celery？

核心概念

第一部分：快速入门 (Hello, World)

第二部分：与 Web 框架集成 (以 FastAPI 为例)

第三部分：定时任务 (Celery Beat)

第四部分：监控与最佳实践

其他知识点

shared_task与app.task的区别

celery调用任务的方式

如何调整同时执行的任务数

Building asynchronous APIs for handling long-term tasks and dynamic resources

教程：构建处理长时间任务和动态资源的异步 API

核心问题

解决方案：异步任务队列

技术栈

第 1 步：环境准备

第 2 步：项目结构

第 3 步：编写 Worker 和任务 (tasks.py)

第 4 步：编写 API 接口 (main.py)

第 5 步：运行系统（关键）

第 6 步：测试

总结

flask-构建一个简单的文件同步系统

使用Python构建文件同步系统：步骤指南

挑战

解决方案

第一部分：服务器

第二部分：客户端

整合使用

结论

Jinja是什么？可以用在做什么？

Jinaja的基础概念

Jinja 可以用来做什么？

Jinja 的核心特性与优势：

Jinja 模板基本语法示例：

Flask使用教程

Flak的基础语法和使用

1. 安装 Flask

2. 创建一个简单的 Flask 应用

代码解释：

运行应用：

3. 添加更多路由

动态路由：

4. 使用模板渲染 HTML

5. 使用过滤器

修改 app.py

修改 templates/index.html

过滤器说明

运行结果

自定义过滤器

6. 处理表单数据

修改 templates/index.html：

修改 app.py：

7. 使用控制语句

修改 app.py

创建 templates/users.html

控制语句说明

运行结果

修改条件

嵌套控制语句

8. 添加静态文件

9. 模板继承

创建基础模板 templates/base.html

修改 app.py

创建子模板 templates/home.html

修改 templates/users.html 使用继承

文件结构

运行结果

扩展说明

10. 部署（简单说明）

总结

Flask操作数据库

Flask 操作数据库教程

环境准备

步骤 1：初始化 Flask 和数据库

代码示例：app.py

说明

第 3 步：编写 Worker 和任务 (`tasks.py`)

第 4 步：编写 API 接口 (`main.py`)

修改 `app.py`

修改 `templates/index.html`

修改 `templates/index.html`：

修改 `app.py`：

修改 `app.py`

创建 `templates/users.html`

创建基础模板 `templates/base.html`

修改 `app.py`

创建子模板 `templates/home.html`

修改 `templates/users.html` 使用继承