آموزش ساخت و اجرای ورکر پایتونی روی Cloudflare Workers

خیلی‌ها هنوز تصور می‌کنند Cloudflare Workers فقط برای JavaScript و TypeScript ساخته شده است؛ اما Cloudflare حالا از Python Workers هم به‌صورت رسمی پشتیبانی می‌کند.

یعنی می‌توانید API، وب‌سرویس، ابزارهای اتوماسیون و سرویس‌های Serverless خود را با Python بنویسید و آن‌ها را روی شبکه جهانی Cloudflare اجرا کنید؛ بدون اینکه نیاز به VPS یا مدیریت مستقیم Server داشته باشید.

در این آموزش از معین گیفت یاد می‌گیریم چطور یک Worker پایتونی بسازیم، آن را روی سیستم خودمان تست کنیم، داخل GitHub قرار دهیم و در نهایت روی Cloudflare Deploy کنیم.

Cloudflare Workers چیست؟

Cloudflare Workers یک پلتفرم Serverless و Edge Computing است.

به‌جای اینکه برنامه شما فقط روی یک Server مشخص اجرا شود، Cloudflare می‌تواند Worker را در شبکه Edge خود اجرا کند تا Requestها در نزدیک‌ترین Location ممکن پردازش شوند.

برای مثال می‌توانید از Worker برای این موارد استفاده کنید:

• ساخت REST API
• Redirect و Rewrite URL
• ساخت Backend سبک
• پردازش Form
• اتصال به Database
• Authentication
• ساخت Webhook
• ساخت AI API
• اتصال به Cloudflare AI

آیا Cloudflare Workers واقعاً Python اجرا می‌کند؟

بله.

Python Workers با کمک Pyodide اجرا می‌شوند.

Pyodide در واقع نسخه‌ای از CPython است که به WebAssembly کامپایل شده و داخل Runtime کلودفلر اجرا می‌شود.

از دید برنامه‌نویس، شما کد Python معمولی می‌نویسید و Cloudflare بخش Runtime را مدیریت می‌کند.

اولین Worker پایتونی ما

ساده‌ترین Worker Python می‌تواند فقط چند خط باشد.

یک فایل با نام:

main.py

بسازید و کد زیر را داخل آن قرار دهید:

from workers import WorkerEntrypoint, Response


class Default(WorkerEntrypoint):
    async def fetch(self, request):
        return Response("Hello from Python on Cloudflare Workers!")

این Worker هر Request ورودی را دریافت می‌کند و یک متن ساده برمی‌گرداند.

ساخت فایل wrangler.toml

در کنار فایل Python باید تنظیمات Worker را هم مشخص کنیم.

فایل:

wrangler.toml

را بسازید و این محتوا را داخل آن قرار دهید:

name = "my-python-worker"
main = "main.py"
compatibility_date = "2026-10-12"
compatibility_flags = ["python_workers"]

این تنظیمات چه معنایی دارند؟

گزینه:

name = "my-python-worker"

نام Worker شماست.

گزینه:

main = "main.py"

به Cloudflare می‌گوید Entry Point پروژه فایل main.py است.

و:

compatibility_flags = ["python_workers"]

پشتیبانی Python Workers را برای پروژه فعال می‌کند.

درباره compatibility_date

در بعضی آموزش‌های قدیمی ممکن است چیزی مثل:

compatibility_date = "2024-03-20"

ببینید.

بهتر است برای پروژه جدید از تاریخ جدید و متناسب با زمان ساخت پروژه استفاده کنید.

Compatibility Date مشخص می‌کند Worker از چه رفتارها و قابلیت‌های Runtime کلودفلر استفاده کند.

ساختار ساده پروژه

my-python-worker/
│
├── main.py
└── wrangler.toml

برای Worker بسیار ساده همین دو فایل می‌توانند کافی باشند.

اما روش رسمی جدید Cloudflare چیست؟

Cloudflare برای پروژه‌های Python ابزار اختصاصی:

Pywrangler

را پیشنهاد می‌کند.

Pywrangler مدیریت:

• Python Worker
• Dependencyها
• Development Server
• Deployment

را ساده‌تر می‌کند.

پیش‌نیازها

برای روش جدید بهتر است روی سیستم این موارد نصب باشند:

• Node.js
• uv

سپس داخل Terminal اجرا کنید:

uvx --from workers-py pywrangler init

این دستور پروژه Python Worker را برای شما آماده می‌کند.

pyproject.toml چیست؟

اگر پروژه شما Dependency داشته باشد، Pywrangler از فایل:

pyproject.toml

برای مدیریت Packageهای Python استفاده می‌کند.

برای مثال:

[project]
name = "my-python-worker"
version = "0.1.0"
requires-python = ">=3.13"
dependencies = []

[dependency-groups]
dev = [
    "workers-py",
    "workers-runtime-sdk"
]

اجرای Worker روی کامپیوتر

قبل از Deploy بهتر است Worker را Local تست کنید.

در Terminal:

uv run pywrangler dev

بعد Worker معمولاً روی آدرسی مشابه این اجرا می‌شود:

http://localhost:8787

حالا کافی است Browser را باز کنید.

باید خروجی زیر را ببینید:

Hello from Python on Cloudflare Workers!

ساخت API JSON با Python Worker

مثلاً اگر می‌خواهید یک API ساده بسازید:

from workers import WorkerEntrypoint, Response


class Default(WorkerEntrypoint):
    async def fetch(self, request):

        data = {
            "status": "ok",
            "message": "Hello from Moein Gift",
            "language": "Python"
        }

        return Response.json(data)

حالا Worker به‌جای Text یک JSON Response می‌دهد.

خواندن JSON از Request

برای ساخت Endpointهای POST هم می‌توانید Body را بخوانید:

from workers import WorkerEntrypoint, Response


class Default(WorkerEntrypoint):

    async def fetch(self, request):

        if request.method == "POST":

            body = await request.json()

            name = body.get("name", "Guest")

            return Response.json({
                "message": f"Hello {name}"
            })

        return Response("Send a POST request")

دیپلوی مستقیم Worker بدون GitHub

ساده‌ترین روش Deploy این است که از همان Terminal استفاده کنید.

ابتدا وارد حساب Cloudflare شوید و سپس:

uv run pywrangler deploy

را اجرا کنید.

Pywrangler فایل‌های Python و Dependencyهای موردنیاز را آماده و Worker را به Cloudflare ارسال می‌کند.

پس از Deployment یک URL مشابه این دریافت می‌کنید:

https://my-python-worker.username.workers.dev

از این لحظه API شما روی اینترنت فعال است.

روش دوم؛ قرار دادن پروژه روی GitHub

اگر می‌خواهید هر بار با Push کردن Code پروژه به‌صورت خودکار Deploy شود، می‌توانید از GitHub و Workers Builds استفاده کنید.

ابتدا داخل GitHub یک Repository جدید ایجاد کنید.

فایل‌های پروژه را داخل Repository قرار دهید:

main.py
wrangler.toml
pyproject.toml

سپس Commit و Push کنید.

اتصال GitHub به Cloudflare

وارد Cloudflare Dashboard شوید.

سپس وارد:

Workers & Pages

شوید.

روی:

Create application

بزنید.

در نسخه فعلی Dashboard گزینه مربوط به:

Import a repository

را انتخاب کنید.

دادن دسترسی GitHub

اگر اولین بار است GitHub را به Cloudflare وصل می‌کنید، Cloudflare از شما می‌خواهد GitHub App آن را Authorize کنید.

می‌توانید مشخص کنید Cloudflare:

• به همه Repositoryها
• یا فقط Repositoryهای انتخاب‌شده

دسترسی داشته باشد.

برای امنیت بیشتر معمولاً بهتر است فقط Repository موردنیاز را انتخاب کنید.

انتخاب Repository

بعد از اتصال حساب GitHub:

1. Repository پایتونی خود را انتخاب کنید.
2. Production Branch را مشخص کنید.
3. تنظیمات Build و Deploy را بررسی کنید.
4. Worker Name را تعیین کنید.
5. Deployment را شروع کنید.

Workers Builds بعد از اتصال Repository می‌تواند با هر Push جدید، Build و Deployment تازه ایجاد کند.

مزیت اتصال GitHub چیست؟

فرض کنید Code را تغییر داده‌اید:

git add .
git commit -m "update api"
git push

Cloudflare تغییر جدید Repository را تشخیص می‌دهد و Workflow مربوط به Build/Deploy را اجرا می‌کند.

در نتیجه دیگر لازم نیست برای هر تغییر Deployment را دستی انجام دهید.

GitHub تنها گزینه نیست

Workers Builds در نسخه فعلی علاوه بر GitHub از GitLab و برخی Source Controlهای دیگر پشتیبانی می‌کند.

بنابراین اگر Workflow تیم شما روی GitLab باشد، لازم نیست Repository را به GitHub منتقل کنید.

استفاده از Packageهای Python

یکی از مهم‌ترین پیشرفت‌های Python Workers پشتیبانی بهتر از Packageهاست.

Pywrangler می‌تواند Packageهای سازگار را براساس pyproject.toml هنگام Deployment داخل Worker Bundle قرار دهد.

برای مثال امکان استفاده از Packageهایی مثل:

• FastAPI
• Pydantic
• LangChain

وجود دارد.

مثال FastAPI روی Cloudflare Workers

یک پروژه می‌تواند Dependency زیر را داشته باشد:

[project]
name = "fastapi-worker"
version = "0.1.0"
requires-python = ">=3.13"

dependencies = [
    "fastapi"
]

[dependency-groups]
dev = [
    "workers-py",
    "workers-runtime-sdk"
]

و سپس FastAPI را داخل Worker اجرا کنید.

آیا هر Package پایتونی کار می‌کند؟

خیر.

این نکته مهم است:

Cloudflare Workers یک VPS لینوکسی معمولی نیست.

Python داخل Runtime مبتنی بر Pyodide و WebAssembly اجرا می‌شود.

در نتیجه بعضی Packageهایی که وابستگی Native یا Binary خاص دارند ممکن است قابل استفاده نباشند.

Cloudflare از:

• Pure Python Packages
• PyEmscripten Packages
• بسیاری از Packageهای موجود در Pyodide

پشتیبانی می‌کند.

پس Python Worker جای VPS را می‌گیرد؟

برای بعضی پروژه‌ها بله، اما برای همه پروژه‌ها نه.

Workers برای Taskهایی مثل:

• API سبک
• Webhook
• Edge Processing
• Authentication
• AI Gateway
• Serverless Backend

بسیار مناسب هستند.

اما اگر نرم‌افزار شما نیاز به Process دائمی، دسترسی کامل به Linux یا Packageهای Native خاص دارد، VPS ممکن است انتخاب مناسب‌تری باشد.

اتصال Python Worker به Database

Python Workers می‌توانند به سرویس‌های دیگر Cloudflare نیز متصل شوند.

از جمله:

• D1
• KV
• R2
• Durable Objects
• Queues
• Vectorize
• Workers AI
• Hyperdrive

در نتیجه می‌توانید یک Backend نسبتاً کامل را بدون Server سنتی بسازید.

مثال کاربردی برای AI

فرض کنید می‌خواهید API ساده‌ای بسازید که:

1. از کاربر Text دریافت کند.
2. آن را پردازش کند.
3. به یک مدل AI ارسال کند.
4. نتیجه را به‌صورت JSON برگرداند.

Python Worker می‌تواند نقش Backend سبک این سرویس را داشته باشد.

Environment Variable و Secret

اطلاعات حساسی مثل:

• API Key
• Token
• Password

را مستقیماً داخل main.py قرار ندهید.

برای این موارد از Secrets و Environment Variables کلودفلر استفاده کنید.

در Worker نیز می‌توانید آن‌ها را از Environment دریافت کنید.

Python Workers و Cold Start

ممکن است تصور کنید اجرای Python روی WebAssembly باعث Cold Start بسیار سنگین می‌شود.

Cloudflare برای کاهش این مشکل بخش بزرگی از Initialization را هنگام Deployment انجام می‌دهد.

هنگام Deploy، Runtime کد و Importهای اصلی را آماده می‌کند و از Memory Snapshot استفاده می‌کند تا Startup هنگام Request سریع‌تر شود.

آیا برای Python Workers هزینه جداگانه وجود دارد؟

Python Worker همان مدل کلی Cloudflare Workers را دنبال می‌کند.

محدودیت تعداد Request، CPU Time و Resourceها به Plan حساب Workers شما بستگی دارد.

برای پروژه‌های کوچک می‌توان ابتدا از سطح رایگان Workers شروع کرد و در صورت افزایش Usage به پلن بالاتر ارتقا داد.

خطاهای رایج هنگام Deploy

خطای مربوط به python_workers

بررسی کنید داخل Wrangler Config وجود داشته باشد:

compatibility_flags = ["python_workers"]

پیدا نشدن Entry Point

مطمئن شوید مقدار:

main = "main.py"

با مسیر واقعی فایل Python یکی باشد.

اگر فایل داخل src است:

main = "src/main.py"

Package نصب نمی‌شود

ممکن است Package موردنظر با Runtime Python Workers سازگار نباشد.

فهرست Packageهای پشتیبانی‌شده و مستندات Pywrangler را بررسی کنید.

روش پیشنهادی برای شروع پروژه جدید

اگر امروز می‌خواهید Python Worker جدید بسازید، Workflow پیشنهادی به این شکل است:

Install Node.js + uv
        ↓
pywrangler init
        ↓
Write Python Code
        ↓
pywrangler dev
        ↓
Test Locally
        ↓
Push to Git
        ↓
Deploy with pywrangler or Workers Builds

مستندات رسمی Python Workers

برای مشاهده مستندات رسمی Cloudflare:

مستندات رسمی Cloudflare Python Workers →

مستندات اتصال GitHub

برای تنظیم CI/CD و اتصال Repository:

راهنمای رسمی Git Integration در Cloudflare Workers →

جمع‌بندی

Cloudflare Workers دیگر فقط مخصوص JavaScript و TypeScript نیست.

با Python Workers می‌توانید Backend، API، Webhook و سرویس‌های Serverless را مستقیماً با Python توسعه دهید و روی شبکه Cloudflare اجرا کنید.

روش فعلی و پیشنهادی Cloudflare استفاده از Pywrangler برای Development و Deployment است و برای پروژه‌های دارای Dependency نیز pyproject.toml استفاده می‌شود.

اگر پروژه را به GitHub متصل کنید، Workers Builds می‌تواند فرآیند Deployment را با Pushهای جدید خودکار کند.

اگر Python بلد هستید، برای ساخت APIهای کوچک و Serverless دیگر الزاماً لازم نیست فقط به‌خاطر Cloudflare Workers سراغ JavaScript بروید.

آموزش برنامه‌نویسی و ابزارهای توسعه در معین گیفت

در معین گیفت آموزش ابزارهای برنامه‌نویسی، Cloudflare، GitHub، هوش مصنوعی و سرویس‌های Serverless را منتشر می‌کنیم تا بتوانید پروژه‌های خود را سریع‌تر توسعه و Deploy کنید.