emirhanmamak-blueforce e28783e563 feat(offline-repo): build the APT index so installs work without network

The package pool was committed but the installer still stopped at "no local
package repository": it requires the compiled bundle (Packages, Packages.gz,
packages.lock.tsv, SHA256SUMS), and building that had never run.

The bundle
- 1321 packages, 884 MiB, Ubuntu 26.04 amd64, built with apt-ftparchive on the
  fleet's own release so the closure matches the devices.
- built/pool/ is gitignored: those .deb files are already tracked once under
  provisioning/offline-repo/packages/, and the same ~890 MB does not need a
  second path. What the installer reads from the bundle is the index.
- The output directory is chmod 0755: mktemp -d created it 0700 and left it
  so, which made a valid bundle unreadable to the installer's probe.

dpkg-deb output was parsed wrong in four places
- `dpkg-deb -f <file> Package Version` prints "<Field>: <value>", and the
  callers kept the whole line, so the value carried its label. build-index.sh
  therefore accepted no package at all and reported an empty pool;
  add-packages.sh rejected every real .deb as an invalid name, missed version
  conflicts, and copied a duplicate; build-offline-repo.sh never matched a pin.
- The test suite could not see any of this: its dpkg-deb stub emitted bare
  values. The stub now prints the labels exactly as the real tool does, which
  is what surfaced the remaining three sites.

Tests
- The secret scan covers the files we author, not apt-ftparchive's index over
  third-party packages: polkit's own description reads "...asked for their
  password:", which is prose in the packages, not a leak. Any secret reaching a
  manifest, README or tool is still caught.
- The "test build must not touch the bundle" assertion now compares the
  directory before and after instead of demanding it be empty, so a
  maintainer's real build is not reported as test spill.

2026-09-16 21:42:27 +03:00

14 KiB

Raw Blame History

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

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):

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):

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?)

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)"]

14 KiB Raw Blame History Unescape Escape