Statik Site Yayınlama Mimarisi

Yazar: Caner Serbest
Kategori: Teknoloji
Konu: Statik site yayınlama mimarisi

1. Giriş

Web uygulamaları giderek daha karmaşık bir hâle geliyor. Ancak birçok içerik odaklı proje, dinamik bir arka uç yerine statik dosyalar üzerinden hızlı, güvenli ve düşük maliyetli bir deneyim sunabiliyor. Statik site jeneratörleri (SSG) sayesinde HTML, CSS ve JavaScript önceden derlenerek bir paket haline getiriliyor. Bu paket, bir CDN’ye yerleştirilip son kullanıcıya coğrafi olarak en yakın noktadan sunuluyor.

Bu makalede, statik site üretiminden dağıtıma kadar tüm bileşenleri bir araya getiren tam bir mimari sunacağız. Örnek olarak Astro ile bir site oluşturup, GitHub Actions aracılığıyla Cloudflare Pages ve Amazon S3 + CloudFront kombinasyonuna dağıtacağız.

Not: Yazının tamamı gerçek konfigürasyonlara dayanıyor; kopyalayıp doğrudan kullanabilirsiniz.

2. Neden Statik Site?

Özellik	Geleneksel Dinamik Site	Statik Site
Sunucu yanıt süresi	Veritabanı ve iş mantığı nedeniyle milisaniyeler	CDN önbelleği sayesinde milisaniyeler altında
Güvenlik	SQL enjeksiyon, XSS gibi riskler	Sunucu tarafı kod yok, saldırı yüzeyi çok düşük
Ölçeklenebilirlik	Yük dengeleyici ve sunucu artırımı gerekir	CDN otomatik ölçeklenir, ek maliyet yok
Maliyet	VM/Container maliyeti ve lisans	Depolama ve veri transferi başına düşük ücret

Statik site tercihinin temel nedeni, basitlik ve hızdır. İçerik değişikliği dışında arka uç mantığına ihtiyaç duymayan projeler (blog, dokümantasyon, portföy) bu modelde en verimli şekilde çalışır.

3. Mimari Bileşenleri

Kaynak Kontrol (Git) – Tüm kod ve içerik bir Git deposunda tutulur. Branch‑based geliştirme, pull‑request incelemesi ve etiketleme süreçleri burada gerçekleşir.
Statik Site Jeneratörü – Astro, Hugo, Jekyll vb. SSG, Markdown ya da MDX dosyalarını HTML’ye dönüştürür.
CI/CD Pipelines – GitHub Actions, GitLab CI, CircleCI gibi araçlar, her push’ta derleme ve test adımlarını otomatikleştirir.
Depolama – Derlenmiş dosyalar bir nesne depolama servisine (Amazon S3, Azure Blob, Google Cloud Storage) aktarılır.
CDN – Cloudflare, Fastly, CloudFront gibi CDN’ler, dosyaları küresel ağda önbelleğe alır.
İzleme & Analitik – HTTP durum kodlarını izlemek için Cloudflare Analytics veya external hizmetler (Google Analytics, Plausible) eklenir.

4. Örnek Mimari Diagramı

Git Repository (GitHub)
   |
   |  GitHub Actions (CI)
   v
Astro Build → dist/
   |
   |  Deploy Step
   v
Amazon S3 (static bucket)  <--->  CloudFront (CDN)

Alternatif olarak aynı dist/ klasörü Cloudflare Pages’a da gönderilebilir; bu durumda Cloudflare hem depolama hem de CDN görevi görür.

5. Gerçekleşen Aşamalar

5.1. Proje Oluşturma

npm create astro@latest my-static-site
cd my-static-site
npm install

Astro, src/pages içinde *.mdx dosyalarını otomatik olarak HTML’ye çevirir. Projenin temel yapılandırması astro.config.mjs dosyasında yer alır.

5.2. Build Script’i

package.json içinde aşağıdaki script eklenir:

"scripts": {
  "dev": "astro dev",
  "build": "astro build",
  "preview": "astro preview"
}

astro build komutu çalıştırıldığında dist/ klasörü oluşur; içinde index.html, assets, ve JavaScript bundle’ları bulunur.

5.3. GitHub Actions Workflow

.github/workflows/deploy.yml dosyası:

name: Deploy static site
on:
  push:
    branches: [ main ]
  workflow_dispatch:

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: "20"
          cache: npm

      - name: Install dependencies
        run: npm ci

      - name: Build site
        run: npm run build

      # ---- Deploy to Amazon S3 ----
      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v2
        with:
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          aws-region: us-east-1

      - name: Sync to S3
        run: |
          aws s3 sync dist/ s3://my-static-site-bucket --delete --acl public-read

      - name: Invalidate CloudFront cache
        env:
          DISTRIBUTION_ID: ${{ secrets.CLOUDFRONT_DISTRIBUTION_ID }}
        run: |
          aws cloudfront create-invalidation --distribution-id $DISTRIBUTION_ID --paths "/*"

Bu workflow üç temel adımı içerir:

Derleme – npm run build.
S3’e senkronizasyon – aws s3 sync komutu yalnızca değişen dosyaları aktarır.
Cache invalidation – CloudFront önbelleği temizlenerek yeni dosyaların anında yayınlanması sağlanır.

Güvenlik İpucu: AWS kimlik bilgileri mutlaka GitHub Secrets içinde saklanmalı, kodda düz metin olarak bulunmamalıdır.

5.4. Cloudflare Pages Alternatifi

Cloudflare Pages, dist/ klasörünü doğrudan bir “build output directory” olarak kabul eder. wrangler.toml dosyası aşağıdaki gibi yapılandırılır:

name = "my-static-site"
compatibility_date = "2024-01-01"

[build]
command = "npm run build"
[build.upload]
format = "directory"
path = "dist"

GitHub Actions içinde sadece wrangler publish komutu çalıştırılır; Cloudflare otomatik olarak CDN ve SSL sertifikasını yönetir.

6. Güvenlik ve En İyi Pratikler

Alan	Öneri
HTTPS	CDN üzerinden otomatik TLS (Let’s Encrypt) kullanın.
HTTP Güvenlik Başlıkları	`Content‑Security‑Policy`, `X‑Content‑Type‑Options`, `Referrer-Policy` ekleyin.
S3 Bucket Politikası	`PublicRead` yerine CloudFront origin‑access‑identity (OAI) kullanın.
Cache‑Control	Statik varlıklar için uzun `max‑age` (1y) ve `immutable` ekleyin; HTML için kısa `max‑age` (5m) ayarlayın.

6.1. Cloudflare Workers ile Header Ekleme

addEventListener('fetch', event => {
  event.respondWith(handleRequest(event.request))
})

async function handleRequest(request) {
  const response = await fetch(request)
  const newHeaders = new Headers(response.headers)
  newHeaders.set('Content-Security-Policy', "default-src 'self'; script-src 'self' 'unsafe-inline'")
  newHeaders.set('X-Content-Type-Options', 'nosniff')
  return new Response(response.body, {
    status: response.status,
    statusText: response.statusText,
    headers: newHeaders
  })
}

Bu worker, tüm yanıtları güvenlik başlıklarıyla zenginleştirir ve Cloudflare Dashboard’da “Workers” sekmesinden dağıtılabilir.

7. Performans Optimizasyonu

Resim Optimizasyonu – astro-imagetools gibi eklentilerle WebP/AVIF üretin.
CSS‑in‑JS yerine ayrı dosya – @astrojs/css kullanarak kritikal CSS’i head içinde, geri kalanını async yükleyin.
Lazy‑Loading – <img loading="lazy"> ve IntersectionObserver ile görselleri tembel yükleyin.
Preload ve Prefetch – Kritik JavaScript bundle’ları için <link rel="preload" as="script" href="/assets/main.js"> ekleyin.
Gzip/Brotli – CDN otomatik olarak sıkıştırma yapar; S3’de Content‑Encoding başlığını manuel ayarlamaya gerek yok.

8. Ölçeklenebilirlik ve Maliyet Kontrolü

Nesne Depolama Ücretleri: S3 için ilk 50 TB/ay 0.023 USD/GB. Statik dosyalar genellikle birkaç GB’ı geçmez; bu yüzden aylık maliyet düşük kalır.
Veri Transferi: CloudFront üzerinden yapılan veri çıkışı, bölgeye göre değişir fakat çoğu zaman 0‑10 USD/TB aralığında olur.
CI Süresi: GitHub Actions ücretsiz planı ayda 2000 dakika sunar; basit bir build bu limitin çok altında kalır.

Bu sayede, trafiği 10 000 ziyaretçiden 1 M’ye çıkarsa bile maliyet artışı lineer ve öngörülebilir olur.

9. Sorun Giderme İpuçları

Sorun	Çözüm
“404 Not Found” CDN hatası	S3 bucket‑policy’nin doğru olduğundan emin olun; CloudFront origin‑path ayarını kontrol edin.
“Stale content” – eski dosya gösteriyor	CloudFront invalidation komutunu çalıştırın veya `Cache‑Control: no‑cache` ekleyin.
“Build fails on CI” – node_modules eksik	`actions/setup-node` içinde `cache: npm` satırının bulunduğundan emin olun; `npm ci` yerine `npm install` deneyin.
“Mixed content” – https içinde http kaynak	Tüm dış bağlantıları `https://` ile güncelleyin; `astro.config.mjs` içinde `base` değerini `/` tutun.

10. Sonuç

Statik site yayınlama mimarisi, basit, hızlı, güvenli ve ekonomik bir çözüm sunar. Doğru araç seti (Astro, GitHub Actions, S3/CloudFront veya Cloudflare Pages) ile koddan dağıtıma kadar tüm süreç otomatikleşir. Bu sayede geliştirme ekibi sadece içerik ve kullanıcı deneyimine odaklanabilir; altyapı yönetimi ise birkaç satır konfigürasyonla halledilir.

Uygulamada gördüğünüz gibi, bir CI/CD pipeline ve CDN entegrasyonu birleştirildiğinde, milyonlarca kullanıcıya aynı anda milisaniyeler içinde hizmet vermek mümkün olur. Statik site mimarisini projelerinizde değerlendirerek, bakım yükünü azaltabilir ve performans avantajlarından tam anlamıyla yararlanabilirsiniz.

Bu makale, 2026‑10‑03 tarihli en güncel araç ve fiyatlandırma bilgilerinin ışığında hazırlanmıştır.

Bu yazı Groq ile otomatik oluşturulmuştur.