BelgelerGeliştirici KılavuzuSık Karşılaşılan Sorunlar ve Çözümleri

Sorun Giderme ve Hata Çözüm Kılavuzu (Troubleshooting)

Geliştirme veya sunucu dağıtımı sırasında en sık karşılaşılan teknik sorular ve pratik çözüm yolları.

1. Strapi'de Kaydettikten Sonra Mağazada Değişikliğin Görünmemesi

Strapi Webhook ayarlarını kontrol edin ve x-strapi-secret değerinin .env dosyasındaki REVALIDATE_SECRET ile eşleştiğinden emin olun.

.env

env

STORE_CORS=http://localhost:8000,https://store.yourdomain.com
ADMIN_CORS=http://localhost:9000,https://api.yourdomain.com
AUTH_CORS=http://localhost:8000,http://localhost:9000,https://store.yourdomain.com

2. Medusa Bağlantı Hatası veya Ürünlerin Listelenmemesi

Publishable API Key Kontrolü

.env dosyasında doğru yayınlanabilir anahtarın tanımlandığından ve Medusa panelinde Satış Kanalının (Sales Channel) ürünlere bağlı olduğundan emin olun.

3. Caddy Otomatik SSL Sertifikası Sorunları

Alan adınızın A kaydının sunucunuzun genel IP adresine doğru yönlendiğini ve güvenlik duvarında 80 ile 443 numaralı portların açık olduğunu doğrulayın.

4. PostgreSQL veya Redis Konteynerine Bağlantı Reddedildi Hatası

Tüm konteynerlerin aynı Docker ağında çalıştığından ve sunucuda yeterli disk alanı bulunduğundan emin olun.

Konteyner Sağlık Kontrol Komutları

bash

sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

5. Merkezi Logları İnceleme ve Hata Teşhisi

Portainer CE yönetim panelini veya docker compose logs -f komutunu kullanarak hataları anında teşhis edin.

Canlı Konteyner Loglarını İzleme

bash

docker compose logs -f storefront
docker compose logs -f medusa
docker compose logs -f strapi

6. Diğer Servisleri Durdurmadan Tek Bir Konteyneri Yeniden Derleme

Ön yüz veya arka yüz kodunu güncellediğinizde diğer servislere dokunmadan sadece ilgili konteyneri yeniden derlemek için:

Tek Konteyner Yeniden Derleme Komutu

bash

docker compose up -d --build storefront

7. Veritabanını Sıfırlama ve Örnek Verileri Yükleme

Geliştirme ortamında örnek ürünleri ve başlangıç verilerini yeniden yüklemek için:

Örnek Veri Tohumlama Komutu

env

docker compose exec medusa yarn seed

8. HTTP 403 Forbidden during Translation Sync from Strapi

If clicking Sync Translations from Strapi yields an HTTP 403 Forbidden error, the Public role lacks permission to read storefront settings. Go to Settings > Users & Permissions > Roles > Public, enable the find permission for both Storefront-setting and Media Library, and save.

9. Arama Girişi Kilitleniyor / Modalda Yazı Yazılamıyor

Neden: Mağaza arama çubuğu React InstantSearch kullanır ve doğrudan istemci tarayıcısından Meilisearch'e sorgu gönderir. Eğer search.yourdomain.com alt alanı Cloudflare DNS'e eklenmemişse veya tarayıcı Meilisearch'e bağlanamazsa (DNS, SSL veya CORS hatası), arama alanı kilitlenir ve hiçbir şey yazılamaz.

Çözüm:
1. Cloudflare kontrol panelinde (DNS > Records), search için sunucu IP adresinizi gösteren bir A kaydı ekleyin.
2. Meilisearch sağlık durumunu doğrulayın:
curl -I https://search.yourdomain.com/health
3. Storefront Docker imajı derlenirken NEXT_PUBLIC_MEILISEARCH_HOST ve NEXT_PUBLIC_MEILISEARCH_SEARCH_KEY değişkenlerinin tanımlandığından emin olun.

Meilisearch Sağlık Kontrolü

bash

curl -I https://search.yourdomain.com/health
# Beklenen yanıt: HTTP 200 OK