Cloudflare Workers Cron Triggers Kurulum Rehberi

Cloudflare Workers cron kurarken yalnızca bir zaman ifadesi yazmak yeterli değildir. Worker içinde zamanlanmış olayları karşılayan scheduled() işleyicisi bulunmalı, tetikleyici doğru Worker'a dağıtılmalı ve saat hesabı UTC üzerinden yapılmalıdır. Tarayıcıda Worker adresini açmanız ise bu olayı çalıştırmaz; bu istek varsa fetch() işleyicisine gider.

Bu rehberde küçük bir HTTP erişilebilirlik kontrolünü zamanlayacak, Wrangler yapılandırmasını hazırlayacak ve yerelde sınayacaksınız. Ardından aynı iş mantığını gizli header ile korunan HTTP yoluna bağlayacaksınız. Örnek, Workers projesine sahip ve JavaScript düzenleyebilen geliştiriciler içindir; üretim işlemini bağlamadan önce zararsız bir test adresiyle başlayın.

Cron Triggers çalışma modeli

Cron Trigger, Cloudflare'ın zamanlanmış olay üreterek Worker'ınızı çağırmasını sağlar. Sunucu içinde crontab dosyası veya sürekli açık bir Node.js işlemi yönetmezsiniz. Buna karşılık işletim sistemi komutlarına dayalı bir yedekleme betiğini aynen taşıyamazsınız; işinizi Workers çalışma ortamının sunduğu API'lerle uyarlamanız gerekir.

Örneğin amacı, belirlediğiniz HTTPS adresine HEAD isteği gönderip durumu loglamaktır. HEAD gövdeyi indirmeden yanıt başlıklarını ister; uygulamanız bu metodu desteklemiyorsa kendi gereksiniminize göre GET kullanabilirsiniz. HTTP yanıtı alınması iş verisinin doğru olduğunu tek başına göstermez. Sipariş aktarımı gibi bir işlemde ayrıca iş sonucunu ve tekrar çağrıların etkisini tasarlayın. Temel zamanlama kavramları için cron job rehberinden yararlanabilirsiniz.

scheduled handler ve ortak iş mantığı

Projenizde src/index.js dosyasına aşağıdaki kodu koyun. runCheck ortak işlevdir; scheduled zamanı ve kullanılan ifadeyi ona aktarır. Dış isteğin HTTP 500 vermesi JavaScript fetch çağrısını kendiliğinden hata durumuna geçirmez; bu yüzden response.ok denetimi özellikle yapılır.

async function runCheck(env, source, scheduledTime) {
  const response = await fetch(env.CHECK_URL, {
    method: "HEAD",
    redirect: "manual"
  });
  console.log(JSON.stringify({
    source,
    scheduledTime,
    status: response.status
  }));
  if (!response.ok) {
    throw new Error("Check failed: HTTP " + response.status);
  }
}

export default {
  async scheduled(controller, env, ctx) {
    ctx.waitUntil(runCheck(env, controller.cron, controller.scheduledTime));
  }
};

controller.cron tetikleyen ifadeyi, controller.scheduledTime planlanan zamanı milisaniye cinsinden taşır. Loglarda planlanan zamanı ve işin başladığı anı ayrı tutmak gecikmeyi incelemeyi kolaylaştırır. Örnek yönlendirmeleri otomatik izlemez; 3xx yanıtı hata sayar. Bu bilinçli tercih, bir sağlık adresinin giriş sayfasına yönlenerek başarılı görünmesini engeller.

ctx.waitUntil() verilen asenkron işlemin sonucunu çalışma yaşam döngüsüne bağlar. Sadece runCheck() çağırıp dönen Promise'i takip etmeden bırakmayın. Tek görevde await runCheck(...) kullanımı da mümkündür. İşleyicinin olay alanları ve tamamlanma davranışı Scheduled Handler referansında açıklanır.

Wrangler yapılandırması ve adım adım kurulum

1. Mevcut Workers projenizde Wrangler'ın erişilebilir ve hesabınızın yetkili olduğunu doğrulayın. Aşağıdaki wrangler.toml dosyasını proje köküne ekleyin; zaten JSONC yapılandırmanız varsa eşdeğer alanları mevcut dosyada düzenleyin, iki ayrı kaynak oluşturmayın.
2. CHECK_URL değerini test edilecek herkese açık HTTPS adresiyle değiştirin. Bu örnekte sır gerektirmeyen bir adres kullanılır; parola veya token'ı vars alanına yazmayın.
3. Kaynak dosyasını önceki bölümdeki kodla hazırlayın. Giriş dosyasının yolu ile main alanının aynı olduğundan emin olun.
4. Yerel testi tamamladıktan sonra npx wrangler deploy ile kendi hesabınıza dağıtın. Worker adı ve varsa ortam seçimini denetleyerek yanlış projeyi güncellemekten kaçının.

name = "scheduled-health-check"
main = "src/index.js"
compatibility_date = "2026-10-15"

[vars]
CHECK_URL = "https://example.com/"

[triggers]
crons = ["*/15 * * * *"]

Buradaki compatibility date, kullanacağınız Workers çalışma zamanı davranışları için seçilen tarihtir; bir paket sürüm numarası değildir. Var olan uygulamada bu alanı gereksiz yere değiştirmeyin. İsim, giriş dosyası, değişken ve tetikleyici tanımlarını Wrangler yapılandırma referansıyla karşılaştırın. Ortam kullanıyorsanız dağıttığınız ortamın değişkenlerini ve tetikleyicilerini ayrıca doğrulayın.

UTC zamanlama ve iki somut kullanım senaryosu

Native Cron Triggers UTC ile çalışır; Europe/Istanbul seçerek yerel saat tanımlamazsınız. Türkiye saati için UTC+3 hesabıyla 09:00 hedefi 06:00 UTC olur. Gece yarısına yakın dönüşümlerde takvim günü de değişebilir. Başka ülkelere hizmet veriyorsanız yaz saati uygulamasını ayrıca değerlendirin; sabit UTC ifadesi her yerde sabit yerel saat demek değildir.

Senaryo 1: Her 15 dakikada */15 * * * * ile sitenizin sağlık adresini kontrol edin. Örneğin son dağıtım sonrasında uygulamanın yanıt verdiğini gözlemek için uygundur. Bu kontrol yalnızca HTTP erişilebilirliğini ölçer; ödeme sağlayıcısı veya veri tabanı sağlığını kapsamak istiyorsanız sağlık adresiniz bu bağımlılıkları güvenli biçimde değerlendirmelidir.

Senaryo 2: Hafta içi Türkiye saatiyle 09:00'da 0 6 * * MON-FRI kullanarak ofis açılmadan tedarikçi API'sinin erişilebilirliğini denetleyin. Aynı kodda CHECK_URL tedarikçinin izin verdiği kontrol adresidir. Böylece gün içinde seyrek kullanılan bir bağlantının arızası ilk kullanıcı işlemi beklenmeden görünür olur. Sonucun bildirim sisteminize nasıl aktarılacağını ayrıca uygulamalısınız; console.log tek başına e-posta göndermez.

Yerel saat dönüşümlerini cron saat dilimi örnekleriyle kontrol edin. Bu iki senaryoyu aynı Worker'a ekliyorsanız her tetikleyicinin ortak işlevi çağıracağını hesaba katın; farklı iş gerekiyorsa controller.cron üzerinden açık bir eşleştirme yapın.

Aynı sunucusuz işlevi Vercel üzerinde çalıştırıyorsanız rota ve proje yapılandırmasındaki farkları Vercel Cron Jobs kurulum adımlarıyla karşılaştırın; Cloudflare'daki scheduled handler ve UTC ifadesini değiştirmeden taşımayın.

Hafta günü sözdizimi: Linux ifadesini aynen taşımayın

Cloudflare hafta günlerini 1–7 aralığında tanımlar: 1 Pazar, 7 Cumartesidir. Bazı Linux cron kullanımında Pazar için 0 kullanılır. Taşınan bir ifadede sayılar sessizce yanlış günü seçebilir; okunabilirlik için MON, FRI, SUN gibi adları tercih edin. Beş alanlı yapı korunur; başına saniye alanı eklemeyin.

Genel alan sırasını crontab sözdizimi rehberinde inceleyebilirsiniz; platforma özel gün numaraları için Cloudflare belgesini esas alın. Özellikle ayın günü ile haftanın gününü birlikte daraltan kuralları taşırken beklentinizi takvim üzerinde sınayın; farklı zamanlayıcıların genişletmelerini birbirine eşit varsaymayın.

Yerel test: gerçek saati beklemeden olayı üretin

Güncel Wrangler geliştirme sunucusu, scheduled olayını yerelde denemek için özel bir yol sağlar. Bir terminalde geliştirme sunucusunu açın, ikinci terminalde örnekteki curl çağrısını gönderin. İfadedeki boşluklar sorgu parametresinde artı işaretiyle kodlanmıştır. Terminal başka port gösteriyorsa URL'yi ona göre düzeltin.

npx wrangler dev

curl "http://localhost:8787/cdn-cgi/local/scheduled?cron=*/15+*+*+*+*"

Bu URL geliştirme aracının test yoludur; dağıtılmış Worker'da internete açık native cron tetikleme adresi değildir. Logda kaynak ifadesini ve HTTP durumunu görün. CHECK_URL değerini kontrollü olarak hata veren bir test adresine çevirip başarısızlık yolunu da inceleyin; ardından doğru adresi geri koyun. Kullandığınız Wrangler sürümüne göre test arayüzü farklıysa resmi yerel test komutunu takip edin.

Dağıtım, olay geçmişi ve sık hataların çözümü

Dağıtımdan sonra Cron Events geçmişini ve Worker loglarını birlikte inceleyin. Trigger değişikliklerinin yayılması 15 dakikaya kadar sürebilir. İlk kaydı göremediğinizde arka arkaya yeni tetikleyiciler eklemek yerine doğru Worker ve ortamı kontrol edip yayılımı bekleyin. Zamanlayıcı yapılandırmasını Wrangler üzerinden yönetiyorsanız panelde yapılan geçici değişiklikleri kalıcı kaynak sanmayın.

Tarayıcıdan açınca görev çalışmıyor

Normal HTTP isteği scheduled olayını üretmez. Yerelde özel test yolunu, üretimde native tetikleyiciyi veya aşağıdaki korumalı fetch işleyicisini kullanın. Worker yalnızca scheduled içeriyorsa tarayıcıdaki yanıtı cron'un bozuk olduğuna kanıt saymayın.

Görev doğru görünüyor ama yanlış saatte çalışıyor

Önce UTC dönüşümünü, sonra hafta günü alanını kontrol edin. Loglarda zaman damgasının gösterildiği saat dilimini de inceleyin. Türkiye 09:00 hedefi için native ifadeye 09 yazılması üç saat kaymaya yol açar; bu örnekte doğru saat alanı 6'dır.

İstek 500 dönüyor fakat çalışma başarılı görünüyor

Fetch Promise'i HTTP hata kodunda da çözümlenebilir. Örnekteki response.ok kontrolünü kaldırmayın ve hatayı yakalayıp sessizce başarılı sonuç döndürmeyin. Dış servis yanıtını sınırlı, sır içermeyen alanlarla loglayın; token, kişisel veri veya tam istek gövdesi kaydetmeyin.

Log göremiyorum veya yanlış Worker'ı izliyorum

npx wrangler tail ile doğru Worker'ın canlı loglarını açın ve yeni bir deneme yapın. Canlı izleme, geçmiş kayıtları saklayan bir arşiv değildir. Ortam seçimi yaptıysanız tail komutunda da aynı ortamı kullanın. Gerçek zamanlı log belgesi izleme ve filtreleme davranışını açıklar.

Uzun iş yarıda kesiliyor

CPU süresi, toplam süre ve dış istek sınırlarını birbirinden ayırın. Yerel testin başarılı olması üretim limitlerine uyulduğunu garanti etmez. Büyük bir veri kümesini tek çalışmada bitirmek yerine parçalara bölün, ilerleme bilgisini kalıcı saklayın ve Workers limitlerini kullandığınız planla karşılaştırın. Bellekte tutulan bir bayrak kalıcı kilit yerine geçmez.

HTTP fetch üzerinden cronjob.com.tr ile alternatif tetikleme

İş bazında saat dilimi seçmek veya HTTP yanıtını dışarıdan izlemek istiyorsanız ortak işlevi fetch yoluna bağlayabilirsiniz. Önceki dosyanın export bölümünü aşağıdakiyle değiştirin; üstteki runCheck işlevi kalır. Hem native hem HTTP yöntemi kodda bulunur, fakat aynı iş için hangi zamanlayıcının sorumlu olduğunu seçmeniz gerekir.

export default {
  async scheduled(controller, env, ctx) {
    ctx.waitUntil(runCheck(env, controller.cron, controller.scheduledTime));
  },
  async fetch(request, env) {
    const url = new URL(request.url);
    if (url.pathname !== "/tasks/check") return new Response("Not found", { status: 404 });
    if (request.method !== "POST") return new Response("Method not allowed", { status: 405 });
    if (!env.CRON_SECRET) return new Response("Missing secret", { status: 500 });
    if (request.headers.get("Authorization") !== "Bearer " + env.CRON_SECRET) {
      return new Response("Unauthorized", { status: 401 });
    }
    try {
      await runCheck(env, "http", Date.now());
      return Response.json({ ok: true });
    } catch {
      return new Response("Check failed", { status: 502 });
    }
  }
};

npx wrangler secret put CRON_SECRET ile uzun, rastgele bir sır tanımlayın; değeri depoya yazmayın. Yerel denemede sırrı sürüm kontrolüne alınmayan .dev.vars dosyasında sağlayabilirsiniz. Sırların yönetimini Cloudflare secrets belgesinden doğrulayın. Bu handler native scheduled olayını HTTP'ye dönüştürmez; yalnızca aynı işlevi çağıran ayrı bir giriş oluşturur. Fetch parametreleri için Fetch Handler referansını kullanabilirsiniz.

1. Worker'ı dağıtın ve https://scheduled-health-check.ornek.workers.dev/tasks/check adresini kendi Worker alan adınızla değiştirin. Yetkisiz POST isteğinin 401 verdiğini doğrulayın.
2. cronjob.com.tr panelinde URL'yi girin, POST seçin, özel header olarak Authorization: Bearer GERCEK_SIR_DEGERI ekleyin. Örnek endpoint istek gövdesi istemez.
3. Türkiye'de hafta içi 09:00 için 0 9 * * MON-FRI ve Europe/Istanbul seçin. Bu, native tetikleyicideki UTC hesabından farklıdır; panelin iş bazındaki saat dilimi kullanılır.
4. Panelden manuel çalıştırıp HTTP durumunu ve Worker logunu karşılaştırın. Yalnız dış takvimi kullanacaksanız Wrangler yapılandırmasındaki crons listesini boş dizi yaparak native tetikleyicileri kaldırın ve yeniden dağıtın.

Cron ifadeli işlerde yanıt 290 saniyeye kadar beklenir. Hazır bir dakikalık aralıkta bu süre 55 saniyedir; en kısa aralık 60 saniyedir. Serviste HTTP 200–399 ve bağlantı hatası olmaması başarı ölçütüdür. Örnekte görev await ile tamamlanır, hata 502 olarak dışarı aktarılır; yanıtı erkenden 200 döndürürseniz arka plandaki sonucu bu HTTP kaydıyla doğrulayamazsınız.

Varsayılan ardışık hata eşiği 3'tür; eşik aşılınca erişim sorunu, düzelince kesinti süresiyle düzeldi e-postası gönderilir. Aynı iş için bildirimler arasında en az 60 dakika vardır. Çalışma kayıtları 7 gün tutulur. Native ve dış zamanlayıcıyı birlikte kullanmak tekrar çalışmaya yol açabilir; veri değiştiren işlerde kalıcı tekilleştirme anahtarı ve uygun kilitleme tasarlayın.

Sıkça Sorulan Sorular (SSS)

Cloudflare Cron Triggers hangi saat diliminde çalışır?

Native Cron Triggers UTC ile çalışır. Türkiye saatiyle 09:00 için UTC+3 hesabıyla saat alanı 6 olmalıdır. İş bazında yerel saat dilimi seçen bir dış zamanlayıcı kullanıyorsanız onun ayarını ayrıca değerlendirin.

Worker URL adresini açmak scheduled olayını tetikler mi?

Hayır. Normal HTTP isteği fetch işleyicisine gider. Scheduled olayını native Cron Trigger üretir; HTTP alternatifi için ortak iş mantığını çağıran ayrı ve korumalı bir fetch yolu oluşturmalısınız.

Cloudflare cron ifadesinde Pazar günü hangi sayıdır?

Cloudflare hafta günlerini 1 ile 7 arasında tanımlar; 1 Pazar, 7 Cumartesidir. Farklı cron sistemlerinden taşırken karışıklığı önlemek için SUN ve MON gibi gün adlarını kullanabilirsiniz.

Cron Trigger ekledim, neden hemen olay görünmüyor?

Trigger değişikliklerinin küresel ağa yayılması 15 dakikaya kadar sürebilir. Doğru Worker ve ortamı kontrol edin, yerel testi tamamlayın ve çalışma sonucunu olay geçmişiyle birlikte loglardan inceleyin.

İlgili Rehberler