# 19 — Sorun Giderme (Troubleshooting)

> Kısa özet: Sahada ve merkezde en sık görülen arızaların belirti → neden → komut → çözüm tablosu. 17-RECOVERY "hangi seviye" sorusunu, bu doküman "o seviyede hangi komut" sorusunu cevaplar.

- Dosya: `docs/19-TROUBLESHOOTING.md`
- İlgili kararlar: `24-DECISION-LOG.md#K-03` (xRDP/GUI), `#K-04` (erişim kanalları), `#K-05` (WireGuard), `#K-10` (Docker), `#K-14` (`bf-status`, support-bundle)
- Durum: [ ] Taslak

---

## 1. Amaç

Tekrar eden arızalarda teşhisi hızlandırmak: belirtiyi bulan teknisyen/admin, tabloya bakıp ilk komutu 30 saniyede çalıştırır. Her girdide "ne zaman üst seviyeye çık" notu vardır.

## 2. Kapsam

- Kapsam içi: boot, ağ/VPN, SSH, RDP/GUI, RustDesk, MeshCentral, Docker/MEG, disk, monitoring ve operatör arayüzü (grafik/terminal konsol, paket deposu keşfi) belirti tabloları.
- Kapsam dışı: seviye kararları (17), adım-adım kurulum (20), merkez onay akışı (21), arayüzün tüm ekranları (33).

## 3. Kararlar

```text
KARAR:    Her arıza girdisi aynı formatta yazılır: Belirti → Olası nedenler (olasılık sırasıyla) → Tanı komutları → Çözüm → Yükseltme kriteri.
GEREKÇE:  Standart format, acemi teknisyenin bile doğru sırayla (tanıdan önce çözüm yok) ilerlemesini sağlar; her çözüm denenebilir komutla verilir.
ALTERNATİF: Serbest-anlatım sorun listesi — komutlar dağınık kalır, otomasyona çevrilemez; elendi.
RİSK:     Tablo eskirse yanlış yönlendirir; azaltma: her PİLOT dalgası sonrası tablo gözden geçirilir.
MALİYET:  Ücretsiz.
LİSANS:   Yok.
```

## 4. Neden Bu Karar?

Sorun giderme, kurtarma merdiveninin (17) "içini" doldurur: 17 hangi LEVEL, 19 o LEVEL'de hangi komut. Olasılık sırası önemlidir — en yaygın neden önce yazılır, teknisyen zamanı boşa harcanmaz. Yükseltme kriteri her girdinin sigortasıdır (inatla aynı komutu tekrarlamak yasak).

## 5. Alternatifler

| Alternatif | Artı | Eksi | Sonuç |
|---|---|---|---|
| Harici bilgi tabanı (Wiki araması) | Aranabilir | Çevrimdışı sahada erişilemez, Git akışı yok | Elendi (22'de Docusaurus içinde bu dosya zaten aranabilir) |
| Her arıza için ayrı sayfa | Detaylı | 700 cihazda 100 sayfa yönetilemez | Elendi (gerekirse Ek'e taşınır) |

## 6. Avantajlar

- Tek dosya, çevrimdışı da okunur (USB'de veya basılı).
- Komutlar kopyala-yapıştırılabilir; açıklamalar Türkçe, komut adları İngilizce orijinal.

## 7. Dezavantajlar

- 26.04.1'e özgü çıktı farkları LAB'da güncellenmelidir (kesin servis adları, log yolları).
- MEG'e özgü arızalar 13-MEG-ACCEPTANCE'tan beslenmelidir; bu dosya iskelettir.

## 8. Riskler

| Risk | Olasılık | Etki | Azaltma |
|---|---|---|---|
| Eski komut (servis adı değişti) | Orta | Orta | LAB'da her komut çalıştırılıp doğrulanır |
| Secret'lı komut geçmişe düşer | Düşük | Yüksek | Support-bundle kuralı (K-14); komutlarda secret yazılmaz |

## 9. Uygulama Planı

Önce genel tanı (her arızada ilk 60 saniye):

```bash
bf-status
systemctl --failed
ip -brief addr; ip route show default
wg show wg0 2>&1 | head -20
docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.RestartPolicy}}'
df -h / /var/lib/docker | cat
```

Aynı raporlar operatör arayüzünden de okunur (komut ezberi gerekmez):

```text
Arayüzden:  sudo bf  →  `Durum` düğmesi (Durum özeti)   ya da Detaylı mod → Cihaz bilgisi sekmesi
            (kimlik, ağ/WireGuard, kaynaklar, servisler, son journal hataları — hepsi salt-okunur)
Komutla (yedek):  sudo bf --tui  →  Cihaz bilgisi menüsü
```

### T-1 — Cihaz açılmıyor / ekranda hiçbir şey yok

| # | Neden (olasılık sırası) | Tanı | Çözüm |
|---|---|---|---|
| 1 | Elektrik yok / BIOS güç ayarı | Priz, adaptör, güç LED'i | BIOS "Restore on AC Power Loss = Power On" (16) |
| 2 | Monitör/kablo | Başka kablo/ekran dene | Değiştir |
| 3 | Disk ölmüş | BIOS diski görmüyor | Donanım değişimi → L8 yeni diskte |

Yükseltme: donanım sağlamsa ama OS açılmıyorsa T-2'ye geç.

### T-2 — Boot terminale düşmüyor / servisler kalkmıyor

| # | Neden | Tanı | Çözüm |
|---|---|---|---|
| 1 | Failed servis var | `systemctl --failed`, `journalctl -xb -p err` | İlgili servis girdisine git (T-3…T-6) |
| 2 | Disk dolu | `df -h /` | Docker log temizliği + rotasyon kontrolü (T-7) |
| 3 | Bozuk çekirdek/paket | `dpkg --audit`, `apt --fix-broken install` | 17-L7; olmazsa L8 |

### T-3 — WireGuard tüneli yok (`wg show` boş / handshake eski)

| # | Neden | Tanı | Çözüm |
|---|---|---|---|
| 1 | Servis inaktif | `systemctl status wg-quick@wg0` | `sudo systemctl enable --now wg-quick@wg0` |
| 2 | Anahtar/config hatası | `journalctl -u wg-quick@wg0 --no-pager`, `wg show wg0 latest-handshakes` | Config'i merkezden yeniden bas (17-L5); peer adı `bf-<no>` mi kontrol et |
| 3 | Saha interneti yok / CGNAT | `ping -c3 8.8.8.8`, modem arayüzü | Yerel ağ düzeltilir; kopma sayacı not edilir (P1 görevi) |
| 4 | Merkez hub down | Başka cihazdan hub'a bak | 17-L9 kolu işletilir |

Yükseltme: WG kalkmıyorsa RustDesk/MeshCentral ile devam (17-L4); onlar de yoksa saha ziyareti.

### T-4 — SSH bağlanmıyor (WG ayaktayken)

| # | Neden | Tanı | Çözüm |
|---|---|---|---|
| 1 | sshd down / anahtar eşleşmiyor | `systemctl status ssh`, `ssh -vvv blueforce@bf-<no>` | Anahtarı merkezden yeniden dağıt (K-13); password denemesi YOK |
| 2 | Yanlış IP/hostname | `ip -brief addr`, envanter karşılaştır | 02-NAMING'e göre düzelt |
| 3 | Güvenlik duvarı | `sudo ufw status`, `ss -tlnp` | 11-HARDENING standardına döndür |

### T-5 — RDP açılmıyor / siyah ekran / hemen kopuyor

| # | Neden | Tanı | Çözüm |
|---|---|---|---|
| 1 | GUI katmanı kapalı | `systemctl status display-manager xrdp xrdp-sesman` | `bf-gui-on`, tekrar dene |
| 2 | Oturum çakışması (yerel + RDP aynı kullanıcı) | `who`, `loginctl list-sessions` | Ayrı kullanıcı/oturum; eski oturumu kapat |
| 3 | xRDP config bozulmuş | `journalctl -u xrdp --no-pager` | Bilinen-iyi config'i bas (17-L5) |

### T-6 — RustDesk bağlanmıyor

| # | Neden | Tanı | Çözüm |
|---|---|---|---|
| 1 | İstemci servis/uygulama kapalı | RustDesk durumu, ID görünüyor mu | Servisi başlat; ID+röle adresi merkez değerlerle aynı mı |
| 2 | Key uyuşmazlığı | İstemci key vs hbbs key | Merkezi key'i yeniden bas (07-REMOTE-ACCESS) |
| 3 | hbbs/hbbr down | Merkezden konteyner/servis durumu | Merkez tarafını ayağa kaldır; health monitörü (Kuma) ne diyor |

### T-7 — Docker/MEG kalkmıyor veya sürekli restart

| # | Neden | Tanı | Çözüm |
|---|---|---|---|
| 1 | Restart loop (config/entrypoint) | `docker ps`, `docker logs --tail 100 <ad>` | Config düzelt + `docker compose up -d` (17-L6) |
| 2 | Disk dolu (rotasyonsuz log) | `df -h /var/lib/docker`, `du -sh /var/lib/docker/containers/*` | `daemon.json` rotasyonu uygula; taşan logu buda |
| 3 | `latest` çekilmiş / sürüm kaymış | `docker images`, compose tag kontrolü | Sabit tag'e döndür (K-10); Watchtower varsa kaldır |
| 4 | Port çakışması / UFW bypass | `ss -tlnp`, `docker port <ad>` | `127.0.0.1`-bind standardına döndür (K-10) |

### T-8 — Disk doluyor

| # | Neden | Tanı | Çözüm |
|---|---|---|---|
| 1 | Docker json-file logları | `du -sh /var/lib/docker/containers/*` | Rotasyon + budama, `docker system prune` (dikkatli) |
| 2 | journald şişmiş | `journalctl --disk-usage` | `SystemMaxUse` limiti + `journalctl --vacuum-size=` |
| 3 | Prometheus retention (merkez) | `df -h`, retention ayarı | 30–90 gün bandına çek (K-07) |

### T-9 — Monitoring'de cihaz gri/kayıp

| # | Neden | Tanı | Çözüm |
|---|---|---|---|
| 1 | Node Exporter down | `systemctl status node_exporter`, hedef scrape logu | Servisi başlat; textfile dizin izni |
| 2 | Uptime Push gelmiyor | Kuma "last seen" | Cihaz interneti + push job'ı (T-3'e dön) |
| 3 | Etiket yanlış (`BF-<no>`) | Prometheus target etiketleri | Envanterle eşitle (02) |

### T-10 — Grafik operatör arayüzü açılmıyor (`sudo bf` pencere açmıyor / hemen kapanıyor)

| # | Neden (olasılık sırası) | Tanı | Çözüm |
|---|---|---|---|
| 1 | Ekran yok (SSH/başsız oturum) | Ekranda "Grafik ekran bulunamadı (DISPLAY ve WAYLAND_DISPLAY tanımlı değil)" + yönlendirme; çıkış kodu `3` | `sudo bf --tui` ile aynı işlemleri terminal konsolunda yürüt; yerel ekranda pencereli kullanmak için oturum açık bir makinede `sudo bf` |
| 2 | `python3-tk` kurulu değil (minimal imaj) | "tkinter bulunamadı; masaüstü arayüzü başlatılamıyor" + paket ipucu; çıkış kodu `3` | Çevrimdışı sahada paket kurulmaz: paket offline depoda pinlidir (`manifests/base-packages.txt`) ve normal kurulumla gelir. Eksikse `sudo bf --tui` ile devam et ve merkeze bildir; kurulum sonu kapısı (`18-final-check`) bu durumda **WARN** yazar ve kurulumu düşürmez |
| 3 | `DISPLAY` var ama X/Wayland erişilemiyor (ssh -X yok, oturum kilitli) | "Pencere açılamadı; grafik oturumuna erişilemiyor" + teknik ayrıntı; çıkış kodu `3` | `sudo bf --tui`; yerel oturumda çalıştırıyorsan kilitli ekranı aç veya `ssh -X` yerine yerel konsolu kullan |
| 4 | Uygulama açıldı ama yazma işlemleri kapalı | Arayüzde "Yönetici yetkisi yok: salt-okunur raporlar çalışır, kurulum ve değişiklik gerektiren işlemler kapalıdır. Tam yetki için: sudo bf" | Komutu `sudo` ile çalıştır; aynı işlem root olmadan çalıştırma katmanında da reddedilir |

Yükseltme: pencere hiç açılmıyorsa ve `sudo bf --tui` de çalışmıyorsa (Python 3.8+ yok veya `bfos` paketi bulunamıyor) merkeze telefon aç; yedek bash menü `sudo admin/bf-menu` ana yol değildir, yalnız acil yedektir.

### T-11 — "Yerel paket deposu bulunamadı" (kurulum paket adımlarına geçmiyor)

| # | Neden (olasılık sırası) | Tanı | Çözüm |
|---|---|---|---|
| 1 | Depo cihazda hiç yok | Ekranda `HATA: Yerel paket deposu yok. Repo sorumlusuna başvurun: provisioning/offline-repo/README.md` + **aranan yollar** + `ÇIKIŞ NEDENİ: yerel paket deposu bulunamadı.`; çıkış kodu `1`, sistem değişmez | Paket setini git ile tam olarak getir (paketler Git LFS ile gelir) ya da repo sorumlusunun bıraktığı kopyayı `/opt/blueforce/offline-repo` altına koy; kurulumu tekrar çalıştır |
| 2 | `packages/` dolu ama indeks (`built/`) yok | Aynı "depo yok" hatası: aday eksiksiz sayılmaz | Kurucu `Packages`, `Packages.gz`, `packages.lock.tsv`, `SHA256SUMS` dosyalarının **hepsini** arar; yalnız `.deb` havuzu yetmez. Repo sorumlusu `build-index.sh` ile `built/` dizinini üretip commit eder |
| 3 | Depo bulundu ama bozuk/eksik | `OFFLINE BLOCKED: <sebep>` + Türkçe çıkış nedeni (ör. checksum doğrulaması başarısız, kilit biçimi bozuk, pinlenen paket depoda yok); çıkış kodu `1` | Sahada onarılmaz: repo sorumlusu seti `add-packages.sh` + `build-index.sh` ile yeniden üretir, güncel git tarafı çekilir ve komut tekrarlanır. Cihazda hiçbir değişiklik yapılmadı |
| 4 | `BF_OFFLINE_REPO` yanlış | `OFFLINE BLOCKED: BF_OFFLINE_REPO mutlak bir yerel dizin olmalıdır.` | Değişkeni kaldır (varsayılan arama sırası kullanılır) veya geçerli bir mutlak dizin ver |
| 5 | "--offline bayrağını vermedim" kuşkusu | — | Bayrak **zorunlu değil**: kurucu depoyu her durumda otomatik arar (sıra: `BF_OFFLINE_REPO` → `<repo>/provisioning/offline-repo/built` → `/opt/blueforce/offline-repo`) |

Yükseltme: paket seti sahada üretilmez/onarılmaz. İki denemede de aynı hata varsa cihazda hata ayıklamayı bırak, repo sorumlusuna başvur; kurulum paket adımlarına geçmediği için cihaz yarım durumda **kalmaz** (fail-closed).

## 10. Test Planı

| Test | Beklenen sonuç | Ortam |
|---|---|---|
| Her T girdisindeki ilk tanı komutu LAB'da çalışır | Komut + örnek çıktı bu dosyada | LAB(2) |
| WG-kill → T-3 → L4 onarım tatbikatı | < hedef sürede tünel döner | P1(5) |
| Disk-doldur simülasyonu → T-8 | Alarm + temizlik çalışır | LAB(2) |
| `DISPLAY` yok + `python3-tk` yok senaryoları → T-10 | Her iki durumda Türkçe yönlendirme, çıkış kodu 3, `--tui` önerisi | LAB(2) |
| Depo dizini kaldırılmış cihazda kurulum → T-11 | Türkçe hata + aranan yollar + çıkış nedeni, exit 1, sistem değişmez | LAB(2) |
| Yalnız `packages/`, indeks yok → T-11/2 | Kurulum "depo yok" diyerek durur (fail-closed) | LAB(2) |

## 11. Rollback

Yanlış çözüm uygulandıysa 17-L3 (son değişikliği geri alma) işletilir; tanı komutlarının kendisi read-only'dir, rollback gerektirmez.

## 12. Kontrol Listesi

- [ ] Her girdide Yükseltme kriteri var.
- [ ] Komutların tamamı LAB 26.04.1 imajında denendi.
- [ ] Hiçbir girdide secret/şifre yazılmıyor.
- [ ] MEG'e özgü satırlar 13 ile çapraz linkli.
- [ ] T-10/T-11 çıkış kodları (3 / 1) ve hata metinleri gerçek çıktıyla doğrulandı.
- [ ] Arayüz yolu belirtilen her girdide "Arayüzden" + "Komutla (yedek)" satırı var.

## 13. Açık Sorular

- [ ] Kesin `bf-gui-*` birim adları + GNOME oturum satırı — LAB çıktısı (sahibi: Faz 3).
- [ ] MEG log hacmi ölçümü → T-8 eşikleri (sahibi: 12-DOCKER yazarı).
- [ ] Turkcell CGNAT tanı notları — P1 verisi (sahibi: 08-WIREGUARD yazarı).
- [ ] `python3-tk` dışındaki grafik bağımlılıklarının da offline pinde gerekli olup olmadığı — LAB doğrulaması (sahibi: 27 + 33 yazarları).

---

## Ek: Triyaj Akışı (hangi T girdisi?)

```mermaid
flowchart TB
    SORUN["Arıza bildirimi<br/>bf-status + systemctl --failed"] --> ARAC{"Sorun cihaz mı,<br/>operatör arayüzü mü?"}
    ARAC -->|"Arayüz açılmıyor"| T10["T-10: DISPLAY / tkinter → sudo bf --tui"]
    ARAC -->|"Kurulum paket adımına geçmiyor"| T11["T-11: yerel paket deposu"]
    ARAC -->|Cihaz| ACILIR{"Cihaz açılıyor mu?"}
    ACILIR -->|Hayır| T1["T-1: güç / BIOS / disk"]
    ACILIR -->|Evet| BOOTOK{"Servisler kalkıyor mu?"}
    BOOTOK -->|Hayır| T2["T-2: failed servis / disk dolu"]
    BOOTOK -->|Evet| WG{"wg show handshake güncel mi?"}
    WG -->|Hayır| T3["T-3: WireGuard + L4 yedek kanal"]
    WG -->|Evet| SSH{"SSH oluyor mu?"}
    SSH -->|Hayır| T4["T-4: sshd / anahtar / UFW"]
    SSH -->|Evet| RDP{"RDP açılıyor mu?"}
    RDP -->|Hayır| T5["T-5: bf-gui-on / xRDP"]
    RDP -->|Evet| DERIN["T-6+: Docker / MEG / disk (T-7/T-8)"]
```