Sorun giderme, güncelleme ve yedekleme

Bir şey ters gittiğinde bu sayfayı baştan sona sırayla izleyin. Önce sorunun ne olduğunu (hata kodu, sistem olayları, log'lar), sonra sık karşılaşılan sorunlar tablosundaki çözümü bulursunuz. Çözemezseniz destek ekibine neyi göndermeniz gerektiği en sonda yazar.

#Sorun olduğunda ilk 5 adım

1. Ekranda bir Hata kodu görüyorsanız kopyalayın (aşağıya bakın). Destek ile her konuşmada bu kod en değerli bilgidir.
2. Kurulum yöneticisiyseniz Sistem olayları sayfasını açın ve aynı saatteki uyarı ve hataları okuyun.
3. Sorun bir runner'la ilgiliyse Runner'lar sayfasında durumuna bakın.
4. Aşağıdaki sık karşılaşılan sorunlar tablosunda belirtiyi arayın.
5. Hâlâ çözülmediyse Destek paketi indir ile paketi alın ve destek ekibine e-posta ile gönderin.

#Hata kodları ve request id

Arayüzde bir sunucu hatası (5xx) olduğunda mesajın altında Hata kodu görünür, yanında bir kopyala düğmesiyle. Bu kod isteğin X-Request-ID'sidir ve:

• o isteğin controller log'undaki her satırında request_id olarak,
• Sistem olayları sayfasındaki olayında Request id sütununda

da yer alır. Yani tek bir kodla o isteğin başına ne geldiğini uçtan uca bulabilirsiniz.

Adım adım:

1. Hata mesajındaki Hata kodu'nun yanındaki kopyala düğmesine basın.
2. Sistem olayları sayfasında arama kutusuna (mesaj ya da request id) yapıştırın ve Filtrele'ye basın.
3. Olayın satırını açın: mesaj, kaynak ve varsa Stack trace görünür.
4. Log'da aramak için: grep <hata kodu> controller.log (log'un yeri aşağıda).
5. Desteğe yazarken bu kodu mutlaka ekleyin.

#Sistem olayları

Sistem olayları (kurulum yöneticileri, sol menüde Altyapı → Sistem olayları) controller'ın fark ettiklerini listeler: panic'ler (yakalanmış, stack trace'leriyle), sunucu hataları (5xx), runner'ların bağlanması ve kopması, başarısız koşular, lisans, güncelleme denetimi, veritabanı, SSO/LDAP ve bildirim kanalı hataları. Olaylar 30 gün, en çok 20 000 tane tutulur.

Sistem olayları sayfası

Sayfanın üstü:

• Yakalanan panic: N — controller'ın kendi hatalarından yakalayıp kurtardığı panic sayısı. Sıfırdan büyükse destek paketini mutlaka gönderin.
• "Controller log'u veri birimine de yazılıyor (döndürülerek, 20 MiB × 5)." ya da "Controller log'u yalnızca stdout'a yazılıyor (SPITFIRE_LOG_FILE yok): container yeniden oluşturulunca kaybolur." — log'un kalıcı olup olmadığını söyler.
• "N olay veritabanı yetişemediği için kaydedilemedi." — veritabanı aşırı yüklüyse görünür.

Filtreleme, adım adım:

1. Başlangıç ve Bitiş ile zaman aralığını sorunun olduğu saatlere daraltın.
2. Seviye: Tümü, Uyarı ve hatalar ya da Yalnız hatalar.
3. Kaynak: Panic, API (5xx), Runner, Koşu, Lisans, Güncelleme denetimi, Veritabanı, SSO / LDAP, Bildirim kanalları, Entegrasyonlar, Controller, Zamanlayıcı, Sentetik izleme, Mobil bildirim ya da Tüm kaynaklar.
4. Ara: mesajdan bir parça ya da bir request id.
5. Filtrele'ye basın; Filtreleri temizle her şeyi sıfırlar.

Listede her satırda Zaman, Seviye (bilgi, uyarı, hata), Kaynak, Olay ve Request id vardır. Aynı olay bir dakika içinde tekrarladıysa yanında kaç kez olduğu yazar. Ayrıntılar ve Stack trace satır açılınca görünür.

Sayfanın altında Bellekteki son uyarı ve hatalar controller'ın bu çalışmasında log'a düşen son uyarı ve hata satırlarını, en yenisi üstte ve gizli değerleri temizlenmiş olarak gösterir. Controller yeniden başlayınca sıfırlanır; bu yüzden yeniden başlatmadan önce bakın.

#Destek paketi

Destek paketi, sorunu anlamak için gerekenleri tek bir zip'te toplar. Spitfire bu paketi hiçbir yere kendiliğinden göndermez: indirirsiniz, isterseniz içine bakarsınız ve destek ekibine e-posta ile siz iletirsiniz.

#Arayüzden

1. Sistem olayları sayfasında sağ üstteki Destek paketi indir'e basın.
2. Pencere pakete girecek Dosya'ları ve Boyut'larını gösterir (zip sıkıştırıldığı için genelde çok daha küçüktür).
3. Pakete konmayanlar bölümünü okuyun.
4. İndir'e basın.

Destek paketi penceresi

#Arayüz açılmıyorsa (komut satırından)

Controller sürekli yeniden başlıyorsa ya da kimse giremiyorsa, kurulum dizininde (varsayılan ~/spitfire):

./install.sh --support-bundle                 # Docker (bu dizindeki kurulum)
./install.sh kubernetes --support-bundle      # Kubernetes (--namespace / --context)

Windows'ta (Docker Desktop), PowerShell'de:

.\install.ps1 -SupportBundle

Kurulum betikleri container log'larını (docker compose logs / kubectl logs, çökme sonrası önceki container'ınkini de), docker compose ps / kubectl get pods çıktısını ve gizli değerleri silinmiş ayarları toplar ve controller'a verir; controller bunları aynı zip'in cli/ klasörüne ekler. Controller bunu yapamazsa zip yalnız betiğin topladıklarını içerir. Betik dosyanın yerini yazar; dosya o makinede kalır.

#Pakette ne var

Pakete konmayanlar: test tanımları, istek/yanıt gövdeleri, veri dosyaları, bağlantı ayrıntıları, kullanıcı adları ve e-postaları, lisans anahtarı ve imzası. Zararsız ayarların izin listesinde olmayan her ayar [redacted] olur. Log'larda gizli değerler ve kimlik bilgisine benzeyen her şey (URL'deki parola, bearer ve Spitfire token'ları, password=, client_secret=, sohbet webhook adresleri) [redacted], e-posta adresleri [e-mail] olur.

#Log'lar

#Nerede

Controller log'u ayrıca veri birimindeki bir dosyaya da yazılır ve container yeniden oluşturulunca kaybolmaz (Docker: logs volume'ü; Kubernetes: container yeniden başlamasından sağ çıkan ama pod'la giden bir emptyDir):

Canlı izlemek için (Docker):

cd ~/spitfire
docker compose -p spitfire -f deploy/docker/docker-compose.yml logs -f --tail 200 controller

#Nasıl okunur

Varsayılan text biçiminde her satır anahtar=değer çiftleridir:

time=2026-10-08T09:41:12.318+03:00 level=ERROR msg="…" request_id=4f1c…

• level: INFO, WARN, ERROR. Önce ERROR satırlarına bakın.

• msg: ne oldu.

• request_id: arayüzdeki Hata kodu ile aynı; o isteğin tüm satırlarını bulmak için:

  bashKopyala

  docker compose -p spitfire -f deploy/docker/docker-compose.yml logs controller | grep 4f1c

Ayrıntı gerekiyorsa controller'da SPITFIRE_LOG_LEVEL=debug ayarlayıp yeniden başlatın; sorun çözülünce info'ya geri alın.

#Sık karşılaşılan sorunlar

#Runner çevrimdışı

Runner'lar sayfasında durumlar: Boşta, Koşuda, Boşaltılıyor, Çevrimdışı.

Runner'lar sayfası

#Lisans limitleri

#Bağlantı ve ağ hataları

#Yazma koruması retleri

Veri değiştiren adımları (SQL/Mongo yazma, riskli Redis komutu, veri değiştirdiği işaretli HTTP isteği) olan bir test her yerde açık onay ister:

#Güncelleme sorunları

#Veritabanı

#Güncelleme

Yeni sürüm çıktığında kurulum yöneticileri üstte bir bant görür ("Spitfire … çıktı"); Neler yeni, nasıl güncellenir? komutu gösterir. Aynı bilgi her zaman Lisans sayfasındaki Sürüm ve güncellemeler kartındadır: Kurulu sürüm, Kurulum, Güncelleme kontrolü, Çıkış proxy'si ve Güncelleme komutu.

Sürüm ve güncellemeler kartı

Adım adım:

1. Koşu sürerken güncellemeyin. Süren koşuların bitmesini bekleyin.

2. Lisans sayfasında Sürüm ve güncellemeler kartındaki komutu kopyalayın (ya da Şimdi kontrol et ile yeniden kontrol edin).

3. Controller'ın kurulu olduğu sunucuda çalıştırın:

   bashKopyala

   # Linux / macOS (Docker)
   curl -fsSL https://spitfire.tr/install.sh | bash -s -- docker
   # Kubernetes
   curl -fsSL https://spitfire.tr/install.sh | bash -s -- kubernetes

   powershellKopyala

   # Windows (PowerShell)
   irm https://spitfire.tr/install.ps1 | iex

   Kurulumu başka bir klasöre yaptıysanız kart komutu SPITFIRE_DIR=… ile verir.

4. Komut önce veritabanını yedekler (sürüm değişiyorsa), ayarlarınızı (deploy/docker/.env ya da spitfire-secrets Secret'ı) ve verilerinizi korur, yeni sürümü kurar.

5. Başka lokasyonlardaki runner sunucuları için kartta ayrı komut vardır (curl -fsSL https://spitfire.tr/install.sh | bash -s -- runner). Uzak runner'ları controller ile aynı sürümde tutun; Runner'lar sayfası farklı sürümü sarıyla işaretler. Docker'sız (systemd, Windows hizmeti) runner'larda Güncelle düğmesi ya da Runner'ları otomatik güncelle yeterlidir.

#Yedekleme ve geri yükleme

#Ne otomatik yedeklenir

• Sürüm değiştiren her güncellemede veritabanı önce ~/spitfire/backups/*.dump olarak yedeklenir. Son 5 yedek kalır. --no-backup (Windows: -NoBackup) bu adımı atlar; önerilmez.
• Ayrıca anahtarları kendiniz yedekleyin: deploy/docker/.env dosyası (Docker) ya da spitfire-secrets Secret'ı (Kubernetes). İçindeki SPITFIRE_SECRET_KEY kaybolursa kayıtlı bağlantı sırları okunamaz.

#Geri alma

Bir güncelleme ters gittiyse, kurulum dizininde:

~/spitfire/install.sh docker --rollback          # Docker
~/spitfire/install.sh kubernetes --rollback      # Kubernetes
~/spitfire/install.sh docker --rollback ~/spitfire/backups/<yedek>.dump   # belirli bir yedek

.\install.ps1 -Rollback                          # Windows
.\install.ps1 -Rollback -RollbackDump <dosya>

Ne olur:

1. Şimdiki veritabanı da önce yedeklenir.
2. Seçilen (varsayılan en yeni) yedek geri yüklenir.
3. O yedeği alan sürüm başlatılır.

O yedekten sonra yapılan değişiklikler geri gelmez. Komutu yeniden çalıştırmak ileri sarar. Terminalsiz çalışırken (ör. bir script'ten) --yes gerekir.

#Destekle iletişim

Yukarıdakiler sorunu çözmediyse destek ekibine yazın:

• Türkçe: iletisim@spitfire.tr
• İngilizce: contact@spitfire.tr

E-postaya şunları ekleyin (eksiksiz bir e-posta çözümü günlerce hızlandırır):

1. Ne oldu? Beklediğiniz ve gördüğünüz, kısa ve somut.
2. Ne zaman? Tarih, saat ve saat dilimi.
3. Hata kodu (varsa) — arayüzdeki Hata kodu / request id.
4. Destek paketi — Sistem olayları → Destek paketi indir ya da ./install.sh --support-bundle. Göndermeden önce içine bakabilirsiniz.
5. Sürüm ve kurulum türü — Lisans sayfasındaki Kurulu sürüm ve Kurulum (Docker, Kubernetes, Windows).
6. Adımlar — sorunu yeniden üretmek için ne yaptınız; ekran görüntüsü yardımcı olur.
7. Bir koşuyla ilgiliyse koşunun bağlantısı ya da kimliği; CI ile ilgiliyse CLI'ın çıktısı (token'ı silerek) ve exit code.

#İlgili sayfalar

• CI/CD entegrasyonu — exit code'lar ve CI hataları
• Zamanlama ve izleme — bildirim kanalı ve zamanlama sorunları
• Gözlemlenebilirlik — backend verisi gelmiyorsa
• Mock, chaos ve kapasite
• Sistem olayları Spitfire'da: /system-events · Runner'lar Spitfire'da: /runners · Lisans Spitfire'da: /license