Domain ve DNS Bilgi Rehberi
İki sokak kapısından aynı sahneye açılan kukla tiyatrosu

Cloudflare Workers ile Custom Domain Yönlendirmesi

Cloudflare Workers ile bir uygulama veya API yazdınız; ama tarayıcı adres çubuğu hâlâ workers.dev gösteriyor. Kendi domain'inizi bu Worker'a bağlamak, hem kullanıcı güveni hem de arama motoru değerlendirmesi açısından önemli bir adımdır. Yönlendirme mantığı basit görünse de apex domain ile www alt alanını aynı anda ele almak, eski URL'leri düzgün taşımak ve DNS kayıtlarını doğru konumlandırmak birbirinden farklı kararlar gerektirir.

Workers, Cloudflare'in uç ağında (edge) çalışan bir JavaScript ve WebAssembly ortamıdır; reverse proxy kullanırken DNS planı burada da geçerlidir. Bir isteğin sunucunuza ulaşmadan önce yakalanmasını sağlar; bu sayede yönlendirme, başlık değişikliği ve önbellek kontrolü gibi işlemleri merkezi bir kod tabanında toplayabilirsiniz. Custom domain bağlamak için iki farklı yol vardır: Workers Routes ve Custom Domains. Her birinin uygun olduğu senaryo farklıdır; ikisini karıştırmak beklenmez bir davranışa yol açabilir.

Sahip olduğunuz domain Cloudflare'de aktifse, yani nameserver'larını Cloudflare'e yönlendirdiyseniz, Cloudflare DNS ekleme adımlarından sonra Workers Routes üzerinden tam kontrole sahip olursunuz. Domain başka bir sağlayıcıda duruyorsa Custom Domains özelliği devreye girer ve Cloudflare, o domain için otomatik DNS kaydı oluşturur. Hangisini seçeceğiniz, DNS yönetiminin nerede yapıldığına bağlıdır.

Workers Routes ile Custom Domains Arasındaki Fark

Workers Routes, Cloudflare Zone'unuzda belirli URL kalıpları için bir Worker'ı tetikler. Kalıplar example.com/* veya api.example.com/v2/* gibi glob sözdizimi kullanır. İstek önce DNS'e ulaşır, Cloudflare oradan yanıt üretir; Routes bu noktada devreye girer. Bu yöntemde Zone'unuzun Cloudflare'de aktif olması zorunludur.

Custom Domains ise wrangler.toml veya Dashboard üzerinden doğrudan bir Worker'ı bir domain'e bağlar. Platform doğrulaması Vercel/Netlify custom domain ile aynı CNAME tuzağına düşebilir. DNS yönetimi Cloudflare'de olmak zorunda değildir; Cloudflare, gerekli CNAME kaydını kendi altyapısında oluşturur. Proxy katmanı proxied / DNS only ayrımını taşır. Ancak bu yöntemde route örüntüsü kullanamazsınız: Worker tüm trafiği yakalar. Alt yol bazlı seçici davranış istiyorsanız Routes tercih etmeniz gerekir.

Karar basit bir kurala dayanır: DNS yönetimi Cloudflare'deyse ve URL bazlı seçici yönlendirme gerekiyorsa Workers Routes kullanın. Yalnızca tek bir Worker'ın tüm domain trafiğini alması gerekiyorsa ve DNS esnekliği önemliyse Custom Domains yeterlidir. İki yöntem aynı Zone üzerinde çakışmamalıdır; çakışma durumunda Custom Domains öncelik alır.

Workers Routes, Zone'a özgü bir ayardır ve Zone silindiğinde kaybolur. Custom Domains, Worker'a bağlıdır ve Worker kopyalanırken aktarılmaz. Bu fark, çok ortamlı (staging/production) yapılarda ciddi bir etken olabilir.

Apex Domain ile www'yi Aynı Worker'a Bağlamak

example.com ve www.example.com adreslerini aynı Worker'a yönlendirmek, en sık sorulan konulardan biridir. Apex tarafı ALIAS/ANAME kısıtına takılabilir. Workers Routes kullanıyorsanız iki ayrı route tanımlamanız gerekir. Yalnızca birini eklemek, diğer adrese gelen isteklerin Worker'ı atlamasına neden olur. Apex domain'i unutmak özellikle yaygındır.

CNAME kaydı, RFC standardı gereği apex domain (@) üzerinde doğrudan kullanılamaz. Cloudflare'in CNAME Flatten özelliği bu sorunu çözer: @ için eklediğiniz CNAME, DNS yanıtında otomatik olarak bir IP adresine dönüştürülür. Bu sayede standart DNS kuralları çiğnenmeden apex domain de proxy üzerinden Workers'a yönlendirilebilir. Alt alan ve apex domain kayıtlarının DNS davranışı konusunun bağlamını daha önce ele aldık.

Orange Cloud (proxy modu) açık olduğunda Workers Routes bu CNAME üzerinden çalışır. Grey cloud ile Routes tetiklenmez; trafik doğrudan origin'e gider. İki adresin de düzgün çalıştığını doğrulamak için Worker deploy edildikten sonra hem example.com hem de www.example.com ayrı ayrı test edilmelidir. Ortak kör nokta buradadır.

Route Örüntüleri: Tam Domain mi, Alt Yol mu?

example.com yazarsanız yalnızca o tam URL eşleşir; alt yollar yakalanmaz. example.com/* yazarsanız tüm alt yollar dahil olur. *.example.com/* ise bütün alt alan adlarını ve yolları kapsar. Joker karakterin konumu, kapsama alanını doğrudan belirler.

Alt yol tabanlı yönlendirme, tek bir domain üzerinde birden fazla Worker çalıştırmak istediğinizde işe yarar. Örneğin /api/* için bir Worker, /statik/* için farklı bir Worker tanımlayabilirsiniz; Workers Routes eşleşmeyi en spesifik kalıba göre yapar, çakışma durumunda daha uzun eşleşen kalıp öncelik alır. Bu davranış belgelenmiştir ve tutarlıdır.

Ne zaman tam domain, ne zaman alt yol seçilmeli? Mevcut bir CDN veya sunucu ana trafiği taşıyorken yalnızca belirli yolları Workers'a devretmek istiyorsanız alt yol yaklaşımı uygundur. Tamamen Workers'a geçiş yapıyorsanız domain genelinde tek bir route daha temiz ve yönetilebilir bir yapı sunar. İkisi arasındaki seçim, mevcut altyapınızın durumuna ve kaç Worker'ın birlikte çalışacağına bağlıdır.

Küçük ama kritik bir fark: example.com ile example.com/* farklı örüntülerdir. Yalnızca example.com eklerseniz kök URL (https://example.com/) eşleşir ama https://example.com/hakkimizda eşleşmez. Çoğu senaryo için /* soneki zorunludur.

Eski URL'leri Worker ile Yönlendirme

Site taşıma veya URL yapısı değişikliğinde kalıcı yönlendirme (301) zorunludur. Workers bu yönlendirmeleri edge'de, sunucuya hiç ulaşmadan yapmanıza olanak tanır. Sonucu doğrudan söylemek gerekirse: sunucu tabanlı yönlendirmeye kıyasla gecikme azalır ve origin yükü düşer.

export default {
  async fetch(request) {
    const url = new URL(request.url);
    const redirects = {
      "/eski-sayfa": "/yeni-sayfa",
      "/blog/kategori/yazi-adi": "/blog/yazi-adi",
      "/urunler": "/magaza"
    };
    const target = redirects[url.pathname];
    if (target) {
      return Response.redirect(new URL(target, url).toString(), 301);
    }
    return fetch(request);
  }
};

Yönlendirme listesi büyüdükçe bu tabloyu Workers KV deposuna taşıyabilirsiniz. KV, Workers ile birlikte çalışan dağıtık bir depolama katmanıdır; yüzlerce kuralı JSON olarak saklayıp Worker'dan okuyabilirsiniz. Sık kullanılan yolları başlangıçta belleğe (in-memory Map) alarak KV çağrısından kaçınılabilir; bu yöntem, her istek için depo çağrısı yapmanın getirdiği gecikmeyi ortadan kaldırır.

Workers yönlendirmesinin yetersiz kaldığı durumlar da vardır. Kurallar regex gerektiriyorsa, dinamik URL parametreleri içeriyorsa veya harici bir sistemden beslenmesi gerekiyorsa Cloudflare Transform Rules daha uygun bir araçtır. Workers, onlarca sabit kurala kadar pratik bir çözümdür; kural sayısı ve karmaşıklığı arttığında Transform Rules tarafına geçmek daha sürdürülebilir olur. Farklı deployment platformlarında custom domain yönlendirme sorunları da benzer karar noktaları içerir.

DNS Kayıtları ve Orange Cloud Zorunluluğu

Workers Routes çalışması için Cloudflare proxy'sinin aktif olması zorunludur. Proxy kapalıysa istek doğrudan origin sunucusuna gider ve Workers Routes devreye girmez. DNS kaydı oluşturulmuş ama orange cloud işaretlenmemişse Worker sanki yokmuş gibi davranır; bu durum logda da görünmeyebilir.

Apex domain için şu DNS kaydını oluşturun:

Tür   : A
Ad    : @
Değer : 192.0.2.1   (placeholder; Workers trafiği kendi ağına çeker)
Proxy : Açık (orange cloud)

Değer olarak girilen IP adresi önemli değildir; Cloudflare, orange cloud modunda tüm trafiği kendi ağına alır ve Workers Routes burada çalışır. www için ise:

Tür   : CNAME
Ad    : www
Değer : example.com
Proxy : Açık (orange cloud)

TTL değerini el ile ayarlamanıza gerek yoktur; proxy modunda Cloudflare bunu yönetir. Proxy modunu değiştirdikten sonra DNS önbelleğinin temizlenmesi birkaç dakika sürebilir. DNS zone yönetiminde kayıt türleri ve proxy davranışı konusunda daha kapsamlı bir değerlendirme bulabilirsiniz.

Orange cloud'u kapattıktan sonra Workers Routes artık çalışmaz; DNS kaydı origin IP'ye işaret eder ve Worker devre dışı kalır. Sorun giderme sırasında grey cloud'a geçmek geçici bir çözüm olsa da testi tamamladıktan sonra proxy modunu açmayı unutmak yaygın bir hatadır.

Wrangler ile Routes ve Custom Domains Yapılandırması

wrangler.toml dosyası üzerinden Workers Routes ve Custom Domains tanımlanabilir; bu sayede yapılandırma kod tabanında sürüm kontrolü altında kalır. Dashboard üzerindeki manuel değişiklikler izlenmesi güç bir sapma yaratır; kod olarak yönetmek tekrarlanabilirliği artırır.

Workers Routes için şu yapıyı kullanın:

[[ routes ]]
pattern = "example.com/*"
zone_name = "example.com"

[[ routes ]]
pattern = "www.example.com/*"
zone_name = "example.com"

Custom Domains için:

[[ custom_domains ]]
hostname = "app.example.com"

zone_name yerine zone_id de kullanılabilir; büyük hesaplarda zone ID daha güvenilirdir çünkü domain adı değiştiğinde zone_name güncellemesi gözden kaçabilir. wrangler deploy çalıştığında bu tanımlar Cloudflare API üzerinden uygulanır. CI/CD hattınıza eklemek için CLOUDFLARE_API_TOKEN ortam değişkenini tanımlamak yeterlidir; Custom Domains kullanıyorsanız bu token'in Zone.DNS:Edit iznine sahip olduğundan ayrıca emin olun.

Birden fazla ortam (staging, production) yönetiyorsanız wrangler.toml içinde ortam bloklarını ([env.staging], [env.production]) kullanarak her ortam için ayrı route tanımlayabilirsiniz. Özel nameserver kurulumu gibi DNS yönetiminin temel katmanlarına hâkim olmak, çok ortamlı yapıların sorun giderilmesini de kolaylaştırır.

Sık Karşılaşılan Yapılandırma Hataları

Worker tetiklenmiyor: Proxy modu kapalıdır. Orange cloud yoksa Workers Routes çalışmaz; önce DNS kaydını kontrol edin.

Apex domain yönlendirmesi eksik: Yalnızca www.example.com/* için route var, example.com/* için yok. Apex üzerinden gelen istekler Worker'ı atlar ve bu durum çoğunlukla logda görünmez.

Sonsuz yönlendirme döngüsü: Worker içindeki fetch(request) çağrısı, aynı Worker'ın tetiklendiği bir URL'ye yapılırsa döngü oluşur. İsteğin yönlendirildiği URL, mevcut route örüntüsüyle eşleşmemelidir. Tarayıcı geliştirici araçlarının ağ sekmesinde kısa sürede çok sayıda özdeş istek görünmesi bu hatanın belirtisidir.

Custom Domains SSL hatası: Domain Cloudflare'de aktifse ve orange cloud açıksa SSL sertifikası otomatik atanır. Hata devam ediyorsa "SSL/TLS" bölümünden Universal SSL sertifikasının "Active" durumda olduğunu doğrulayın. Yeni eklenen bir domain için sertifika aktivasyonu birkaç dakika alabilir.

wrangler deploy sonrası route görünmüyor: Token izinleri yetersizdir. Workers Routes:Edit izni, Zone.DNS:Edit izninden bağımsızdır; ayrıca kontrol edin.

Workers Routes ve Custom Domains birbirini tamamlayan iki yapıdır. Domain üzerinde tam, yol bazlı kontrol için Routes; DNS bağımsızlığı veya tek Worker mantığı için Custom Domains tercih edilir. Her iki senaryoda da orange cloud zorunluluğu ve apex domain için ayrı route tanımı, atlanmaması gereken iki temel noktadır.

Eski URL taşıma, www-apex uyumu veya alt yol tabanlı dağıtım gibi konular yüzey görünümde basit, ancak yanlış yapılandırıldığında sessiz hatalara zemin hazırlar. Yönlendirme Worker'ı deploy etmeden önce en azından apex ve www adresleri için ayrı ayrı test etmek, olası kör noktaları önceden ortaya koyar.

İlgili Yazılar