Sorun Giderme

Güncellendi 2 Eki 2026 Markdown

İlgili dokümanlar: admin-user-guide.md · installation.md

Bir şey çalışmayı durdurduğunda sistem yöneticisinin ilk başvuracağı kılavuz budur. Daha derin mimari dokümanlara yapılan çapraz referanslar gerekli yerlerde satır içinde verilmiştir.

1. Log yolları özeti

metin

/var/log/whost/agent.log                # Agent logu, stdout/stderr dahil (agent kendisi döndürür: logging.max_size 100M, logging.keep 10)
/var/log/whost/frontend-debug.log       # Tarayıcı tarafı debug beacon (opt-in; logrotate ile günlük, 7 kopya)
/var/log/whost/audit.jsonl              # Denetim kaydı, JSON satırları (eski kayıtlar audit.jsonl.1 / .2'ye taşınır)
/var/log/nginx/{access,error}.log       # Nginx — global
/home/<kullanıcı>/logs/                 # Hesap başına web logları (<domain>-access.log, <domain>-error.log)
/var/log/apache2/                       # Debian/Ubuntu Apache backend
/var/log/httpd/                         # RHEL Apache backend
/var/log/mail.log    /var/log/maillog   # Postfix / Dovecot
journalctl -u pdns -n 100               # PowerDNS (WHost ona ayrı log dosyası tanımlamaz)
/var/log/fail2ban.log                   # Fail2Ban aksiyonları
/var/log/modsecurity/audit.log          # ModSecurity kurallarına takılan istekler
tail -f /var/log/whost/agent.log        # Agent logunun canlı takibi
journalctl -u whost-agent -n 50         # systemd'nin kaydettiği agent başlatma / durdurma / çıkış olayları
journalctl -u nginx -n 100              # Nginx journal

Herhangi bir sorunda en yararlı ilk komut

tail -n 100 /var/log/whost/agent.log

Agent çıktısını journal'a değil bu dosyaya yazar: journalctl -u whost-agent systemd'nin başlatma, durdurma ve çıkış satırlarını ve agent'ın çalıştırdığı komutların (useradd, userdel gibi) sistem günlüğü satırlarını gösterir; agent'ın kendi günlük satırlarını asla göstermez.

2. Agent yaşam döngüsü komutları

kabuk

systemctl status whost-agent           # Durum; gösterdiği satırlar yalnız systemd olaylarıdır
systemctl restart whost-agent          # Graceful yeniden başlatma (lifespan temiz şekilde durur)
systemctl reload  whost-agent          # Kullanmayın — aşağıya bakın; restart kullanın
systemctl is-active whost-agent        # Boolean
tail -f /var/log/whost/agent.log       # Canlı takip
curl -k https://127.0.0.1:2000/health  # Sağlık probu (kimlik doğrulama gerekmez)

systemctl reload bir yeniden yükleme değildir: birim onu bir SIGHUP'a çevirir, agent bu sinyali işlemez; süreç düzgün durmadan sonlanır ve systemd onu 5 saniye sonra yeniden başlatır. restart kullanın.

Config: /etc/whost/agent.conf (YAML, mod 0600, root sahipli). Düzenledikten sonra agent'ı yeniden başlatın. YAML sözdizimi hatası ya da geçersiz bir değer başlatmayı durdurur: hata (sözdizimi hatasında satır ve sütunuyla) /var/log/whost/agent.log'a yazılır ve systemd dosya düzeltilene kadar her 5 saniyede bir yeniden dener.

3. Lisansla ilgili sorunlar

Belirti	Tanı	Kurtarma
Girişten sonra pano yerine lisans sayfası açılıyor veya mevcut admin oturumu lisans sayfasına yönlendiriliyor	Durum `NOT_ACTIVATED` veya `SUSPENDED`	Mevcut lisansın geçerliliğini veya bağlantısını geri getirin ve nedeni lisans sayfasında inceleyin; bu durumlarda giriş reddedilmez, oturum yalnız lisans sayfasına ulaşır. Yeni kurulumda kurulum aracının yazdırdığı yönetici parolasıyla giriş yapın ve açılan lisans sayfasında anahtarı girin.
Ayarlar → Lisans sayfasında sunucu uyarısı ve kalan saat gösteriliyor	Lisans doğrulama servisine erişilemiyor veya host'a hız sınırı uygulanıyor (örneğin art arda çok sayıda agent yeniden başlatmasından sonra); önbellekli durum hâlâ geçerli	Giden HTTPS (port 443) erişimini doğrulayın. Grace'e geçiş doğrulamayı 9–18 dakika içinde yeniden planlar; toparlanma için restart gerekmez. Kalan pencere son başarılı doğrulamadan itibaren `license.grace_period` ile hesaplanır.
Aktivasyon formu "Bu lisans anahtarı zaten bir kuruluma kayıtlı" yanıtını veriyor (400 `LICENSE_ACTIVATION_FAILED`, `details.vendor_code` `AUTH_FAILED`; `agent.log`: `app_secret required`)	Anahtar daha önce aktive edilmiş — tipik olarak bu sunucu yeniden kurulmadan önce — ve o kurulumun aldığı kimlik bilgileri artık diskte yok. Form bunları sağlayamadığı için lisans servisi anahtarı reddeder. Ret iki tarafta da hiçbir şeyi değiştirmez	Lisansı lisans sağlayıcınızda yeniden düzenletin (reissue; WISECP lisanslarında wisecp.com Hizmet Yönetim ekranı) ve anahtarı yeniden girin. Önceki kurulum hâlâ çalışıyorsa önce onun agent'ını durdurun: reissue, lisans servisine ulaşan ilk isteğe verilir ve çalışan bir agent onu bir sonraki denetiminde alır
Aktivasyon 400 `LICENSE_ACTIVATION_FAILED` yanıtını başka bir mesajla döndürüyor	Lisans servisi anahtarı reddetti: bilinmeyen, iptal edilmiş ya da süresi dolmuş anahtar veya lisanstaki domain/IP kilidinin bu sunucuyla uyuşmaması (mesaj servisin kendi gerekçesini, `details.vendor_code` kodunu taşır; `activation_secret` aktivasyon formunda rol oynamaz)	Anahtarı ve kilit ayarlarını wisecp.com Hizmet Yönetim ekranında karşılaştır; lisansın IP/domain bilgisini orada güncelle ya da lisansı yeniden düzenlet; mesaj donanım izini ya da önyükleme belirtecini anıyorsa (sunucunun donanımı değişti ya da WHost yeniden kuruldu) wisecp.com hizmet sayfasında Lisansı Yeniden Düzenle'yi seç — donanım kilidini de bırakır — ve yeniden etkinleştir; WISECP desteği donanım kilidini ayrıca sıfırlayabilir
`agent.log`'da lisans sunucuları için `CERTIFICATE_VERIFY_FAILED` ya da hostname uyuşmazlığı görünüyor	Lisans servisinin sertifika zinciri ya da adı host'un CA deposuna göre doğrulanamadı: değiştirilmiş `/etc/hosts` ya da DNS yanıtı, araya giren bir proxy ya da eski `ca-certificates` paketi	Agent doğrulanmamış bir uçla hiç konuşmaz; o sunucuyu erişilemez sayar (grace) ve denemeye devam eder. Çözümleme yolunu ya da proxy'yi düzeltin veya CA deposunu yenileyin (Debian/Ubuntu'da `update-ca-certificates`, EL9'da `update-ca-trust`). Yeniden başlatma gerekmez.
Grace süresi doluyor ve korumalı API'ler 403 `LICENSE_SUSPENDED` döndürüyor	`license.grace_period` içinde başarılı doğrulama yapılamadı	Lisans servisi bağlantısını geri getirin ve Ayarlar → Lisans üzerinden doğrulayın. Agent sonraki denemeyi beklemeden pencere sonunda erişimi kısıtlar. Doğrulama kotasını tüketen art arda restart'lardan kaçının.
`/api/v1/accounts` gibi korumalı API'ler 403 `LICENSE_SUSPENDED` döndürüyor	Lisans kapısı devrede	Ayarlar → Lisans'tan nedeni kontrol edin ve lisans geçerliliğini geri getirin. Health, auth, license ve seçili salt okunur sistem uçları erişilebilir kalır; normal kimlik doğrulama şartları korunur.

Tanılama:

Aşağıdaki örnekler varsayılan durum yolunu kullanır. agent.conf içindeki license.state_file değiştirildiyse seçilen dosyayı ve .hmac eşini inceleyin.

kabuk

cat /etc/whost/license.state                 # mevcut durum + token_valid_until (girintili JSON)
grep -i license /var/log/whost/agent.log | tail -30
# Bir verify'ı zorla: Ayarlar → Lisans → Şimdi Doğrula ya da API üzerinden,
# yönetici oturum çereziyle veya HMAC imzalı istekle. Agent yalnız
# 127.0.0.1:2000'de dinler; başka bir makineden panelin HTTPS adresini kullanın.
curl -X POST -H "X-WHost-Key: ..." -H "X-WHost-Timestamp: ..." \
     -H "X-WHost-Nonce: ..." -H "X-WHost-Signature: ..." \
     https://<panel-host>/api/v1/license/verify

4. Kimlik doğrulama / 2FA

Belirti	Aksiyon
Parola doğru olduğu hâlde "Geçersiz kullanıcı adı veya parola"	Yönetici girişi yönetici kullanıcı adını (büyük/küçük harfe duyarlı) ya da yönetici e-posta adresini kabul eder. `grep 'Admin login failed' /var/log/whost/agent.log` hangi parçanın reddedildiğini gösterir (`unknown identifier` ya da `wrong password`). Beş başarısız denemeden sonra ad 15 dakika kilitlenir ve form bunun yerine geri sayım gösterir. Fail2Ban'in yasakladığı adres giriş formuna ulaşmadan reddedilir, yani bu mesajı üretmez: `fail2ban-client status whost-agent` (ve `recidive`) ile bakın, yasağı `fail2ban-client unban <ip>` ile ya da Fail2Ban sayfasından kaldırın.
2FA kodu tekrar tekrar reddediliyor	Sunucu geçerli 30 saniyelik adımın ya da hemen önceki/sonraki adımın kodunu kabul eder; saat yaklaşık 30 sn'den fazla kaymışsa kod reddedilir: `timedatectl status` çalıştırın; gerekirse NTP'yi etkinleştirin. Her kod bir kez kabul edilir; beş yanlış koddan sonra giriş 30 dakika kilitlenir.
2FA cihazı kaybedildi	Kayıt sırasında verilen yedek kodlardan birini kullanın (her biri bir kez geçer). Hiçbiri kalmadıysa shell erişimi olan bir sistem yöneticisi `/etc/whost/agent.conf` içinde `admin:` → `two_factor:` altındaki `enabled` değerini `false` yapar, agent'ı yeniden başlatır, parolayla giriş yapar ve Profil sayfasından yeniden kaydolur.
Ayarlar kaydedildikten sonra tüm oturumlar çıkış yaptı	Yeni ve boş olmayan bir Admin Panel IP Beyaz Listesi kaydetmek (Ayarlar → Güvenlik) tüm yönetici oturumlarını sonlandırır; parola değişikliği diğer oturumları sonlandırır. Yönetici paneli ayrıca tek oturum tutar; başka yerden giriş yapmak önceki oturumu sonlandırır. Beklenen davranış — izin verilen bir adresten yeniden giriş yapın.
Bir API anahtarı değiştirildikten sonra her API isteğinde 401 `AUTH_FAILED`	Entegrasyon hâlâ eski anahtarla imzalıyor: iptal edilen ya da silinen anahtar hemen çalışmaz olur ve anahtarın secret'ı yalnız oluşturulurken gösterilir (anahtarlar yerinde döndürülmez). Yeni anahtar kimliğini ve secret'ı entegrasyona girin; yeniden başlatma gerekmez. `agent.log` reddi adlandırır (`Revoked API key used from …`, `Invalid API key from …`, `Invalid HMAC signature from …`) ve bu satırlar çağıranın Fail2Ban yasağına sayılır (`whost-agent` jail'i).
Giriş "Güvenlik doğrulaması başarısız" diyor (captcha)	Ayarlar → Güvenlik → CAPTCHA Koruması: seçili sağlayıcı site anahtarı / gizli anahtar çiftiyle eşleşmeli, anahtar panelin host adına kayıtlı olmalı; Skor Eşiği'nin (varsayılan 0.5) altında kalan reCAPTCHA v3 skoru reddedilir. Kimse giriş yapamıyorsa `/etc/whost/agent.conf` içinde `admin:` → `recaptcha:` altındaki `enabled` değerini `false` yapıp agent'ı yeniden başlatın.

5. Hesap sağlama

Belirti	Olası neden	Çözüm
`POST /api/v1/accounts` 409 `ACCOUNT_EXISTS` döndürüyor	Kullanıcı adı mevcut bir hesaba ait (`/etc/whost/accounts/<username>.json`), bu adda bir Linux kullanıcısı zaten var (bir sistem kullanıcısı ya da yarıda kalmış bir oluşturmadan artakalan) veya domain başka bir hesap tarafından sunuluyor — mesaj kullanıcı adını ya da domaini adlandırır	Başka bir kullanıcı adı ya da domain seçin. Artakalan bir Linux kullanıcısını yalnız ona ait hesap kaydı yoksa ve bir sistem ya da başka bir kullanıcı değilse kaldırın: önce `id <username>` ve `ls -la /home/<username>` ile bakın, gerekenleri kopyalayın, sonra `userdel -r <username>` (home dizinini siler) ve tekrar deneyin
422 `VALIDATION_ERROR`: "Invalid username … Must be 3-16 lowercase alphanumeric, starting with a letter."	Kullanıcı adı kuralı `^[a-z][a-z0-9]{2,15}$`; ayrılmış adlar (`root`, `admin`, `mysql`, `test`, …) da reddedilir	3–16 karakter, yalnız küçük harf ve rakam, harfle başlar
Hesap paketinin izin verdiğinden fazla disk kullanıyor	`/` üzerinde dosya sistemi kotası etkin değil: paketin disk limiti kaydedilir ve gösterilir, ama `setquota` başarısız oldu (`agent.log`: `disk quota not applied for <username>`)	`quotaon -p /` ve `quota -u <username>`; kotayı Disk kotası bölümündeki gibi etkinleştirin. Disk limitleri `/` üzerindeki dosya sistemi kotasıyla uygulanır; CPU, bellek, süreç ve I/O limitleri hesabın cgroup v2 slice'ıyla (`whost-<username>.slice`)
Askıya alınan hesap hâlâ mail alıyor	Askıya alma hesabın posta kutularını ve yönlendiricilerini posta veritabanında kapatır; Postfix ve Dovecot bu veritabanını her sorguda okur — reload gerekmez. O adım başarısız olduysa `agent.log` `Mailboxes of <username> not disabled: …` gösterir	Orada adı geçen nedeni giderin, sonra hesabın askıya alınmasını kaldırıp yeniden askıya alın (zaten askıdaki bir hesabı yeniden askıya almak hiçbir şeyi değiştirmez)
Bayi alt hesap oluşturamıyor: 403 `RESELLER_LIMIT`	Bayinin bir limiti (hesap, disk, bant genişliği, domain, veritabanı, e-posta ya da FTP hesabı) aşılacak; mesaj hangisi olduğunu söyler	O limiti bayi üzerinde yükseltin (Bayiler sayfası) ya da overselling'e izin verin

Bozuk bir hesabı tamamen sıfırlama (sistem yöneticisi): hesabı Hesaplar sayfasından silin, sonra yeniden oluşturun. Silme işlemi Linux kullanıcısını ve home dizinini, veritabanlarını, FTP ve e-posta hesaplarını, DNS zone'larını, SSL dosyalarını, vhost'ları, cron işlerini, barındırılan uygulamaları ve hesabın yerel yedeklerini kaldırır — hâlâ gereken arşivleri önce /var/whost/backups/<username>/ dışına kopyalayın. Başarısız olan bir temizlik adımı loglanır (Failed to … for <username>) ve diğerleri yine çalışır.

6. Web sunucusu (Nginx / Apache)

Belirti	Aksiyon
Ayarlar kaydedildikten sonra `nginx -t` başarısız	Vhost değişiklikleri kalıcı olmadan önce test edilir: test başarısız olursa agent önceki dosyaları geri koyar ve kayıt hatayı bildirir. `nginx -t` hâlâ başarısızsa neden o değişikliğin dışındadır — çıktısı dosyayı ve satırı adlandırır (vhost'lar Debian/Ubuntu'da `/etc/nginx/sites-available/`, RHEL ailesinde `/etc/nginx/conf.d/` altındadır); düzeltin, sonra `systemctl reload nginx`
PHP sayfasından 502 Bad Gateway	PHP-FPM havuzu kapalı → `systemctl status php<sürüm>-fpm` (Debian/Ubuntu, örn. `php8.3-fpm`) ya da `php<noktasız sürüm>-php-fpm` (RHEL ailesi, örn. `php83-php-fpm`); o birimi yeniden başlatın
Yeni eklenen subdomain'de 404	Vhost oluşturuldu ama Nginx reload edilmedi — servis kodundaki `reload` adımı başarısız olduysa olur. Manuel: `systemctl reload nginx`
ModSecurity meşru trafiği engelliyor	Kural ID'sini ModSecurity WAF → Denetim Günlüğü'nde bulun (dosya: `/var/log/modsecurity/audit.log`). Kuralı ModSecurity WAF → Kurallar'dan sunucu genelinde kapatın ya da API üzerinden yalnız bir hesap için hariç tutun (`POST /api/v1/accounts/{username}/waf/rules/exclude`, isteğe bağlı olarak tek bir URI için)
LiteSpeed WebAdmin konsolu yüklenmiyor	Konsol 7080 portunda dinler (`webserver.ols_admin_port`); kurulum aracının güvenlik duvarı bu portu açmaz — yalnız kendi adresiniz için izin verin. LiteSpeed Web Server (Enterprise) ayrıca geçerli bir deneme ya da lisans ister (OpenLiteSpeed istemez): seri anahtarı Eklentiler → LiteSpeed Web Server altında etkinleştirin
`fail2ban-client status whost-<kullanıcı>-webscan` bir ban listeliyor ama adres siteye hâlâ ulaşıyor	fail2ban yalnız isteği kuyruğa yazar; `systemctl status whost-http-ban.path` aktif olmalı ve `journalctl -u whost-http-ban-apply` uygulama koşumunu gösterir — listeyi reddeden web sunucusu (configtest) değişikliği geri alır ve bunu orada söyler. `whost-http-ban list` uygulananı gösterir; `whost-http-ban sync` elle yeniden uygular. `fail2ban-client get whost-<kullanıcı>-webscan actions` `whost-http-deny` göstermeli (aksiyonunu yitirmiş jail'i agent yeniden başlatıldığında onarır). OpenLiteSpeed sunucunun kendi adresini ve 127.0.0.1'i hiç engellemez.

7. Veritabanları (MariaDB)

Panelden phpMyAdmin girişi başarısızİki panel de agent.conf içinde saklanan MariaDB root parolasıyla (mysql.root_password) giriş yapar: yönetici bağlantısı onu doğrudan kullanır, müşteri bağlantısı onunla kısa ömürlü bir veritabanı kullanıcısı oluşturur. Root parolası WHost dışında değiştirildiyse güncelini oraya yazın ve agent'ı yeniden başlatın. grep -i -e phpmyadmin -e pma /var/log/whost/agent.log denemeleri gösterir.

Veritabanı işlemleri MariaDB "Too many connections" hatasıyla başarısızSunucunun max_connections sınırına ulaşıldı. Ayarlar → Genel → Veritabanı Ayarları'nda Maks Bağlantı değerini yükseltin: değer canlı uygulanır ve 99-whost-tuning.cnf'te tutulur (Debian/Ubuntu'da /etc/mysql/mariadb.conf.d/, RHEL ailesinde /etc/my.cnf.d/); panelden yapılan bir sonraki kayıt bu dosyayı yeniden yazar — elle düzenleme kalıcı olmaz.

Uzak veritabanı host'u eklendi ama istemci bağlanamıyorYetki hemen geçerli olur, ama MariaDB varsayılan olarak yalnız 127.0.0.1'de dinler (aynı dizindeki 99-whost.cnf içinde bind-address) ve güvenlik duvarı 3306'yı açmaz; host eklenirken panel bu konuda uyarır. Uzak bağlantıya izin vermek için bind-address'i istemcinin ulaşabileceği bir adrese ayarlayın, MariaDB'yi yeniden başlatın ve 3306'yı güvenlik duvarında yalnız istemci adreslerine açın.

InnoDB The table is full bildiriyorGenellikle disk doludur: df -h /var/lib/mysql ile bakın ve yer açın. WHost innodb_data_file_path değerini MariaDB varsayılanında bırakır; bu varsayılan gerektikçe büyür.

8. E-posta (Postfix / Dovecot / Rspamd)

Giden mail kuyrukta takılı (mailq)mailq ertelenen her mesajın yanında nedenini yazar; teslimat logu /var/log/mail.log (Debian/Ubuntu) ya da /var/log/maillog'dur (RHEL ailesi) — genellikle DNS / SPF / DKIM sorunu. Giden 25 portunun açık olduğunu doğrulayın (bulut sağlayıcıları sıklıkla bloklar).

Gelen mail "user unknown" ile bounce ediyorPosta kutusu posta veritabanında yok ya da kapalı (askıya alınmış hesap). E-posta sayfasından veya POST /api/v1/accounts/{username}/emails üzerinden oluşturun.

Rspamd tüm mailleri spam olarak işaretliyorSpam Filtresi → Genel Bakış ve Yapılandırma — varsayılanlar Reddetme 15, Başlık Ekleme 6, Greylist 4 (greylist ≤ başlık ekleme ≤ reddetme). Spam olarak işaretlenen mail Başlık Ekleme Skoru'nu aşmıştır: onu yükseltin (greylist yalnız teslimi erteler); güvenilen gönderenler Beyaz Liste sekmesine eklenebilir.

Panelden Webmail (Roundcube) girişi başarısızGiriş bağlantıları tek kullanımlıktır ve 5 dakikada süresi dolar; agent'ın belleğinde tutulurlar, bu yüzden agent yeniden başlatması ondan önce açılmış bağlantıları geçersiz kılar. Webmail'i panelden yeniden açın; yine başarısızsa agent'ı yeniden başlatın — her başlangıçta Roundcube giriş betiklerini yeniden yazar.

Hesap başına email_hourly_limit aşıldıHesap başına hız sınırı, Postfix policy servisi (whost-policyd) uygular; email_hourly_limit değerini pakette ya da hesabın kendi limitlerinde yükseltin.

9. DNS (PowerDNS)

Belirti	Aksiyon
`POST /api/v1/accounts/{username}/dns/{domain}/records` 500 `DNS_ERROR` döndürüyor	PowerDNS API kapalı veya erişilemez. `systemctl status pdns` ; `journalctl -u pdns -n 50`.
Kayıtlar eklendi ama `dig` NXDOMAIN döndürüyor	Önce bu sunucuya sorun: `dig @<sunucu-ip> <ad>`. Yanıt veriyorsa neden, domainin kayıt kuruluşundaki NS yetkilendirmesi ya da bir resolver'ın önbellekteki negatif yanıtıdır: negatif TTL'i bekleyin ya da yönettiğiniz resolver'ı temizleyin (BIND'de `rndc flush`). Bozuk bir DNSSEC zinciri NXDOMAIN değil SERVFAIL olarak görünür.
AXFR reddediliyor (kasıtlı)	Tüm zone'lar varsayılan olarak AXFR'yi reddeder (WHost `allow-axfr-ips` ayarlamaz, PowerDNS varsayılanı geçerlidir). Belirli peer'ları `pdnsutil set-meta <zone> ALLOW-AXFR-FROM <ip>` üzerinden ekleyin.
Düzenlemeden sonra zone serial artmıyor	PowerDNS, panelin API üzerinden gönderdiği her değişiklikte serial'ı ilerletir; hiçbir şeyi değiştirmeyen bir kayıt değişiklik göndermez. Elle ilerletmek için: `pdnsutil increase-serial <zone>`. Zone'lar Native olarak oluşturulur, bu yüzden PowerDNS ikincil sunuculara NOTIFY göndermez.

10. SSL / Let's Encrypt

Let's Encrypt sertifika üretimi hız sınırıyla başarısızLE kayıtlı domain başına haftada 50 ile sınırlandırır. Bekleyin veya farklı bir ana domain kullanın.

ssl_failed denetim kaydı (webhook olayı ssl.failed)certbot trace için /var/log/letsencrypt/letsencrypt.log kontrol edin. Genellikle DNS sunucuya yönlenmiyor demektir.

Özel sertifika yüklemesi 422 döndürüyorYanıt reddedilen alanı adlandırır: certificate (PEM değil, süresi dolmuş ya da henüz geçerli değil — ilk blok ara sertifika değil sitenin kendi sertifikası olmalı), private_key (PEM değil, parolalı ya da sertifikanın anahtarı değil) veya ca_bundle. Yüklemeden önce denetleyin: openssl verify -CAfile chain.pem cert.pem.

Otomatik yenileme tetiklenmiyorYenilemeler agent'tan değil certbot'tan çalışır: paketin timer getirdiği yerde (Debian/Ubuntu) systemctl status certbot.timer ve journalctl -u certbot.service; diğerlerinde (RHEL ailesi) kurulum aracı root'a günlük bir cron satırı ekler — crontab -l | grep certbot. Log: /var/log/letsencrypt/letsencrypt.log.

11. Yedekler / geri yükleme

Yedek tamamlanıyor ama 0 bytes boyutYedeklerin yazıldığı yerde disk baskısı. df -h /var/whost/backups ile bakın (backup.local_path; çalışma kopyası /tmp'de değil aynı klasörün içinde oluşturulur) ve çalıştırmanın uyarıları için agent.log'a bakın.

Geri yükleme yarıda kalıyor, hesap bozukGeri yükleme arşivin dosyalarını, veritabanlarını ve postalarını hesabın üzerine yerinde yazar ve yazdığını geri almaz; başarısızlık bildirimi ve agent.log nedeni taşır. Nedeni giderin ve aynı geri yüklemeyi yeniden çalıştırın. Tek tek dosyalar için arşivden elle çıkarın (tar -xzf /var/whost/backups/<username>/<arşiv> -C <boş dizin>). Mevcut durum hâlâ gerekebilecekse geri yüklemeden önce yeni bir yedek alın.

Uzak hedef (örn. SFTP) yükleme başarısızYedeklemeler → Uzak Depolama — kimlik bilgilerini yeniden girin ve Doğrula'ya basın; test aynı ayarlarla bu sunucudan çalışır.

Zamanlanmış yedek hiç çalışmıyorYedeklemeler → Ayarlar: Yedekleme Sistemi ve Zamanlama Sistemi açık olmalı, zamanlamanın kendisi de etkin olmalı (Zamanlamalar sekmesi). Zamanlayıcı agent ile birlikte yalnız iki anahtar da açıksa başlar — agent başladığında biri kapalıysa, açtıktan sonra agent'ı yeniden başlatın. Başlangıçta agent.log Backup scheduler started ya da Backup scheduler disabled by configuration yazar; bir güncelleme kurulurken zamanı gelen çalıştırmalar bekler (Scheduled backups wait: an update is being installed).

Eski yedekler temizlenmiyorEski yedekleri iki kural kaldırır: her çalıştırmadan sonra bir zamanlama en yeni yedeklerini Saklama Sayısı kadar tutar, Saklama Süresi (Yedeklemeler → Ayarlar, varsayılan 7) ise daha eski yedekleri günde bir kez, zamanlayıcının 04:00 UTC'den sonraki ilk turunda kaldırır. İkisi de yedekleme zamanlayıcısının içinde çalışır (bir üstteki satıra bakın); klasöre elle kopyalanan dosyalara dokunulmaz.

12. Python / Node app hosting

pip install (veya npm install) takılıyorKurulum agent'tan hesabın kullanıcısı olarak çalışır; agent onu 10 dakika (pip) ya da 15 dakika (npm) sonra durdurur; paket deposuna ulaşamayan bir sunucu o süre dolana kadar bekler. Giden HTTPS'i denetleyin: curl -sI https://pypi.org/simple/, curl -sI https://registry.npmjs.org/.

App "Başarısız" gösteriyorGünlükler sekmesi → exception'ı belirleyin (dosyalar: Python için /home/<kullanıcı>/logs/<app>-error.log, Node için <app>-stderr.log) → kodu ya da ayarları düzeltin → Yeniden Başlat. systemctl status whost-pyapp-<kullanıcı>-<app> (Node: whost-nodeapp-<kullanıcı>-<app>) birimin çıkış durumunu gösterir.

App oluşturma reddedildi: 403 PYTHON_APP_LIMIT / NODE_APP_LIMITPaketin max_python_apps / max_node_apps sınırına ulaşıldı (0 = sınırsız); yükseltin ya da kullanılmayan bir app'i kaldırın. App'lere TCP portu atanmaz — her biri /run/whost/<kullanıcı>/ altında bir Unix soketinde dinler — bu yüzden tükenecek bir port havuzu yoktur.

nginx proxy_pass 502 döndürüyorApp çalışmıyor ya da soketi yok: app'in durumuna, systemctl status whost-pyapp-<kullanıcı>-<app> (Node: whost-nodeapp-<kullanıcı>-<app>) çıktısına ve ls -l /run/whost/<kullanıcı>/<app>.sock'a bakın

App OOM tarafından öldürüldüdmesg | grep -i kill. Node app'inin kendi bellek sınırı vardır (app üzerinde max_memory_mb, paketin node_max_memory_mb değeriyle sınırlı); Python app'i paketten gelen hesap bellek sınırı içinde çalışır — hangisi geçerliyse onu yükseltin.

Derinlemesine bilgi: docs/developer/python-apps.md.

13. Webhook'lar

Abone endpoint hiç event almıyorWebhook'lar → Teslimat geçmişi'ni kontrol edin. Yaygın nedenler: endpoint devre dışı, event abonelik listesinde yok, SSRF blok (URL özel bir adrese çözülüyor; böyle bir teslimat doğrudan dead letter'a düşer).

Tüm teslimatlar connection refused ile başarısızAbone URL'si bayat veya kapalı. DNS, port, TLS doğrulayın. Yönetici panelinden Test olayı gönder'i kullanın.

Abone tarafında imza doğrulama başarısızAbone HMAC'i yanlış hesaplıyor. Kanonik formül: HMAC-SHA256(secret, "{timestamp}.{raw_body}"); timestamp X-WHost-Webhook-Timestamp'ten alınır, sonuç X-WHost-Webhook-Signature (sha256=<hex>) ile karşılaştırılır. SDK'daki WHost\Http\WebhookVerifier'ı kullanın veya tarifi docs/developer/webhooks.md içinden kopyalayın.

Dead-letter kuyruğu büyüyorTeslimat geçmişi → durumu Dead letter olarak filtreleyin → aboneyi düzelttikten sonra her teslimatı Tekrar dene ile yeniden gönderin. 5 denemeden sonra teslimat dead_letter'a düşer ve elle yeniden denenene kadar orada kalır.

Eşlenmiş audit event'i var ama hiç teslimat enqueue edilmediYalnız bir webhook olayına eşlenmiş denetim olayları teslim edilir — GET /api/v1/system/webhooks/events kataloğu listeler. Sizin event'iniz orada yoksa, kasıtlıdır (sadece-okuma audit).

Derinlemesine bilgi: docs/developer/webhooks.md.

14. Güncellemeler (WHost + OS paketleri)

Tıklamadan sonra UPDATE_INSTALL_FAILEDGeçmiş sekmesi hatayı + otomatik rollback'in tamamlandığını gösterir. Kök neden için o zaman aralığında /var/log/whost/agent.log'u okuyun.

UPDATE_IN_PROGRESS yeniden install'ı bloklarBir kurulum sürüyor: bu işaret kurulumun ilk adımından onu bitiren yeniden başlatmaya kadar agent'ın belleğinde tutulur (bu sırada yedek ve geri yükleme reddedilir). Kaldırılacak bir lock dosyası yoktur; kurulumun bitmesini bekleyin — Güncellemeler sayfası ilerlemesini gösterir.

Bilinen yeni bir sürüm için UPDATE_ALREADY_LATESTKurulum son güncelleme kontrolüne göre davranır; Güncellemeler → Güncelleme Kontrol Et ile yeniden kontrol edin (GET /api/v1/system/update/check). Beta kanalındaki bir sürüm yalnız o kanala ayarlı sunucuya sunulur (Güncellemeler → Ayarlar).

OS yükseltmesi "running" durumunda sonsuza takılıBaşka bir paket yöneticisi çalışması (elle çalıştırılan apt / dnf, unattended-upgrades ya da dnf-automatic) paket kilidini tutuyor olabilir: ps -C apt,apt-get,dpkg,dnf -o pid,etime,cmd (Debian/Ubuntu'da ayrıca lsof /var/lib/dpkg/lock-frontend). Bitmesini bekleyin, sonra tekrar deneyin. Çalışan bir dpkg ya da rpm'i öldürmeyin — yarıda kalan dpkg dpkg --configure -a ister — ve agent'ın OS yükseltmesi sürerken agent'ı yeniden başlatmayın: paket yöneticisi agent servisinin içinde çalışır ve onunla birlikte durdurulur.

Otomatik güncelleme hiç tetiklenmiyorGüncellemeler → Ayarlar: Otomatik Güncellemeler açık olmalı; bir sürüm yalnız seçilen türle eşleşirse (Tüm Güncellemeler, Küçük, Yalnızca yama ya da varsayılan olan Yalnızca güvenlik düzeltmeleri) ya da "Üreticinin kritik güncellemeleri zorlamasına izin ver" açıkken (varsayılan) üretici onu kritik olarak işaretlediyse kurulur. Agent günde bir kez kontrol eder, ilk kez başladıktan 5 dakika sonra; ayrı bir timer birimi yoktur. agent.log bir sürümün neden atlandığını (does not match auto_update_type) ya da ertelendiğini (Auto-install of … deferred, örn. yedekler çalışırken) yazar.

Derinlemesine bilgi: docs/operator/update-flow.md.

15. Frontend (yönetici / müşteri paneli)

Bir güncellemeden sonra boş sayfaSekme ya da tarayıcı önbelleği önceki sürümün sayfalarını tutuyor; güncelleme onların betik dosyalarını değiştirdi. Hard-refresh (Ctrl+Shift+R) yapın veya site verilerini temizleyin.

Her API çağrısında BUNDLE_MISMATCHSayfa başka bir agent derlemesinin parmak izini taşıyor (genellikle bir güncellemeden önce açılmış sekme); panel bu kodu alınca kendini bir kez yeniler. Sürüyorsa hard-refresh yapın; yine sürüyorsa systemctl restart whost-agent — agent her başlangıçta kendi derlemesinin parmak izini panelin /config.json dosyasına yazar. SDK / HMAC client'lar muaftır ve bunu asla görmez.

Sidebar / topbar dil değişmiyorPanel dilini çerezde değil tarayıcının yerel depolamasında (whost_locale) tutar; Profil sayfasında seçilen dil de her girişte yeniden uygulanır. Dili dil seçiciden seçin ya da profil dilini "Otomatik (giriş yaptığım dili koru)" yapın.

Toast yalnız "İstek başarısız" ya da "Bilinmeyen hata" diyorBaşarısız istek için tarayıcı DevTools → Console + Network sekmelerini açın. Network paneli agent'ın error_code + message JSON'unu gösterir.

Frontend debug log hiçbir şey yakalamıyorYayımlanan paneller tarayıcı hata ayıklama beacon'ı kapalı derlenir; bu yüzden agent.conf içinde frontend.debug_log: true olsa da /var/log/whost/frontend-debug.log boş kalır. Bunun yerine tarayıcının DevTools'unu (Console ve Network sekmeleri) kullanın.

16. Yaygın hata kodları → aksiyon

error_code alanı kararlı tanımlayıcıdır; herhangi bir işlemi buna eşleyin (yerelleştirilmiş message'a değil).

Kod	HTTP	Sistem yöneticisi aksiyonu
`AUTH_FAILED`	401	API anahtarı + imzayı doğrulayın (bozuk biçimli bir zaman damgası da burada reddedilir)
`AUTH_EXPIRED`	401	HMAC: isteğin zaman damgası sunucu saatinden 300 sn'den fazla uzak — `timedatectl`, NTP'yi etkinleştirin. Panel: oturum sona erdi (zaman aşımı, daha yeni bir giriş, parola değişikliği) — yeniden giriş yapın
`BUNDLE_MISMATCH`	403	Sayfa başka bir agent derlemesi için yüklenmiş — yenileyin (panel bir kez kendisi yapar); bkz. Frontend
`CROSS_ORIGIN_DENIED`	403	Çerezle kimliği doğrulanmış bir yazma isteği yabancı bir `Origin` ile geldi. Panel dışındaki bir sayfa API'ye gönderi yapıyorsa beklenir; panelin kendisi ikinci bir host adıyla sunuluyorsa o adı `security.trusted_origins`'e ekleyin
`PAYLOAD_TOO_LARGE`	413	Gövde sınırı aştı: `/api/v1/auth/` altındaki giriş ve çıkış yollarında 1 MB, diğerlerinde 10 MB, yükleme uçlarında 300 MB
`INVALID_JSON`	400	İstek gövdesi boş ya da geçerli JSON değil
`LICENSE_NOT_ACTIVATED` / `LICENSE_SUSPENDED`	403	Giriş yapın: lisans sayfası (`/admin/license`) açılır. Önce Şimdi Doğrula'yı kullanın; anahtarı yalnız yeni kurulumda ya da reissue'dan sonra girin (bkz. Lisansla ilgili sorunlar)
`RATE_LIMIT`	429	`Retry-After` header'ına uyun; sürüyorsa `agent.conf` içindeki `rate_limit` bloğunda ilgili tier'i yükseltip agent'ı yeniden başlatın
`PERMISSION_DENIED`	403	Çağıran kimlik doğrulanmış ama scope eksik — bayi ACL'ini kontrol edin
`PATH_TRAVERSAL`	403	Client bir path'te `..` veya null byte denedi; genellikle bir partner bug'ı
`IDEMPOTENCY_KEY_REUSED`	409	Aynı anahtar farklı body ile gönderildi — partner her mantıksal işlem için UUID'yi yeniden üretir
`VALIDATION_ERROR`	422	`details` alanı saha-düzeyinde nedenleri taşır; partner payload'ı düzeltir
`UPDATE_IN_PROGRESS`	409	Süren kurulumu bekleyin; agent'ın yeniden başlatmasıyla biter (elle kaldırılacak bir şey yoktur)
`OS_UPGRADE_IN_PROGRESS`	409	Panelden başlatılan bir OS paket çalışması hâlâ sürüyor; bitmesini bekleyin
`SYSTEM_ERROR`	500	Genel — trace `/var/log/whost/agent.log` içindedir (`Unhandled exception`)

Tam katalog: docs/developer/api-reference.md → Ek A.

17. Ne zaman eskalasyon yapılır

WISECP desteğine wisecp.com müşteri panelinizden bir destek talebiyle (talep açamadığınızda [email protected] adresine e-postayla) eskalasyon yapın ve aşağıdaki paketi ekleyin:

Ne oldu, ne zaman — UTC zaman damgası, aldığınız aksiyon, görünür belirti.
Agent log kesiti — tail -n 2000 /var/log/whost/agent.log > agent.log.txt, ayrıca başlatma / durdurma olayları için journalctl -u whost-agent --since '30 minutes ago' > agent-journal.txt
Lisans durumu — yapılandırılmış license.state_file yolunu kullanın (varsayılan /etc/whost/license.state); bir kesit paylaşmadan önce secret ve key alanlarını maskeleyin.
Sürüm — curl -k https://127.0.0.1:2000/health (sürüm + ok durumu döndürür).
OS — cat /etc/os-release | head -3.
Tekrar üretim — belirtiyi yeniden tetikleyen minimum adımlar.

Asla paylaşmayın /etc/whost/agent.conf ham hâliyle — dinlenme halinde şifresi çözülmüş gizli anahtarları içerir. Bir config parçası gerekliyse password, secret, key alanlarını redact edin.

Güvenlik-hassas konular için (şüpheli RCE, lisans bypass, multi-tenant kırılma) [email protected] adresine e-posta gönderin ve bunları herkese açık bir yerde bildirmeyin.

Hâlâ Yardıma mı İhtiyacınız Var?

Yukarıda bulamadığınız her şey için destek ekibimiz her zaman yanınızda.

Bize Ulaşın Destek Talebi Oluştur