Sorun Giderme

Önce sorunun hangi katmanda yaşadığını belirleyin: Multica servisi, daemon, runtime veya yapay zekâ kodlama aracı. Bu komutlar genellikle ilk anlamlı hatayı ortaya çıkarmaya yeter:

multica version
multica auth status
multica daemon status --output json
multica daemon logs --lines 100

Kendi sunucunuzda barındırılan örnekler, servisi doğrudan da kontrol edebilir:

curl -i https://api.example.com/health
curl -i https://api.example.com/readyz

/health yalnızca API sürecinin yanıt verdiğini söyler; /readyz veritabanını ve migration'ları da kontrol eder. Bir sorunu bildirirken hatayı, ilgili günlükleri, CLI sürümünü ve işletim sistemini ekleyin; göndermeden önce token'ları, e-posta adreslerini ve diğer hassas bilgileri kaldırın.

Daemon bağlanamıyor

Önce şunları çalıştırın:

multica auth status
multica daemon status --output json
multica daemon logs --lines 100

Yaygın nedenler arasında şunlar var:

• CLI giriş yapmamış, veya bu makinede saklanan token'ın süresi dolmuş.
• Daemon yanlış Multica servisine bağlı.
• Yürüten bilgisayar API'ye ulaşamıyor, veya DNS, TLS ya da bir güvenlik duvarı bağlantıyı engelliyor.
• Geçerli hesap artık hedef çalışma alanının üyesi değil.
• Bu makinede desteklenen bir yapay zekâ kodlama aracı kurulu değil, bu yüzden daemon başlayamıyor.

Yeniden giriş yapın ve daemon'ı yeniden başlatın:

multica login
multica daemon restart

Kendi sunucunuzda barındırılan dağıtımlar, API'nin /health'ini yürüten bilgisayardan da istemelidir — sunucunun kendisinde test etmek, yürüten bilgisayar tarafındaki DNS, TLS veya güvenlik duvarı sorunlarını ortaya çıkaramaz. Adresi değiştirmek için multica setup self-host'u yeniden çalıştırın, veya geçerli profilin server_url'ini kontrol edin:

multica config show

İş yürütülmeye başlamıyor

İşin yürütme günlüğünü açın ve çalıştırmanın geçerli durumunu ve neyi beklediğini kontrol edin.

queued durumu

queued, çalıştırmanın hâlâ bir runtime'ın onu üstlenmesini beklediği anlamına gelir. Sırayla kontrol edin:

1. Agent'ın bağlı olduğu runtime çevrimiçi mi?
2. Runtime, agent'ın yapılandırıldığı yapay zekâ kodlama aracını algıladı mı?
3. Agent'ın hâlâ eşzamanlılık payı var mı?
4. Daemon'ın hâlâ global yürütme kapasitesi var mı?

Bir agent varsayılan olarak en fazla 6 çalıştırmayı eşzamanlı yürütür; tek bir daemon en fazla 20'yi yürütür. Sınırda, yeni çalıştırmalar aktif biri bitene kadar kuyrukta kalır. Runtime çevrimdışıyken de çalıştırmalar kuyruklanmaya devam eder; yalnızca o runtime yeniden bağlanma toleransından daha uzun süre kalp atışı göndermeyi bıraktığında ve çalıştırmanın kendisi de o kadar beklediğinde başarısız olurlar, bu yüzden meşgul bir runtime'ın arkasındaki uzun bir kuyruk beklediği için asla süresi dolmaz, ve halihazırda çevrimdışı olan bir makineye iş atamak yine de onu geri getirmek için tam bir tolerans süresi bırakır.

multica daemon status --output json
multica agent get <agent-id>
multica issue runs <issue-id>

Runtime listesinde beklenen bir araç eksikse, önce aracın aynı sistem hesabı ve PATH altında çalıştığını ve giriş yaptığını doğrulayın, sonra multica daemon restart çalıştırın.

waiting_local_directory durumu

Bu, devam eden başka bir çalıştırmanın aynı yerel dizini kullandığı anlamına gelir. Multica, iki agent'ın aynı dosyaları aynı anda değiştirmemesi için dizin kilidinin serbest kalmasını bekler.

Bu bekleme yalnızca dizinin in_place ("Doğrudan") modunda vardır. Dizin bir git deposuysa, kaynağı worktree ("Paralel") moduna geçirmek kuyruğu tamamen ortadan kaldırır: her çalıştırma kendi worktree'sini alır ve işini bir dal (branch) olarak geri teslim eder, böylece hiçbir şey hiçbir şeyi beklemez. Bkz. Proje kaynakları.

Aksi hâlde önceki çalıştırmanın bitmesini bekleyin. Takılı kalırsa, yürütme günlüğünden durdurun veya geçerli agent için farklı bir yerel dizin seçin. Bu dizin muteksi daemon'ın belleğinde yaşar — diske hiçbir kilit dosyası yazılmaz. Eski (stale) kilit durumundan şüpheleniyorsanız, multica daemon restart onu serbest bırakır; elle silinecek bir şey yoktur.

Yapay zekâ kodlama aracı başlamıyor

Çevrimiçi bir daemon, aracın kendisinin çalıştığı anlamına gelmez. Çalıştırmanın ayrıntılı kaydını açın ve şunlara odaklanın:

• Aracın girişi tamamlayıp tamamlamadığı.
• API anahtarının, kotanın veya model izinlerinin mevcut olup olmadığı.
• Agent'ın seçtiği model ve düşünme düzeyinin araç tarafından desteklenip desteklenmediği.
• Yerel çalışma dizininin var olup olmadığı ve yazılabilir olup olmadığı.
• Agent'ın özel argümanlarının veya ortam değişkenlerinin geçerli olup olmadığı.

Önce aynı aracı yürüten bilgisayarda doğrudan bir terminalde çalıştırın. Araç kendi başına başlayamıyorsa, girişini veya yapılandırmasını düzeltin, sonra çalıştırmayı yürütme günlüğünden yeniden deneyin.

Gerçek zamanlı güncellemeler çalışmayı durduruyor

Çalıştırmalar hâlâ yürütülüyor ama yorumlar ve durum değişiklikleri artık canlı görünmüyorsa, WebSocket genellikle bağlı değildir.

Tarayıcının geliştirici araçlarında Network → WS altında /ws bağlantısını kontrol edin. Kendi sunucunuzda barındırılan dağıtımlar için şunlara odaklanın:

• FRONTEND_ORIGIN'in tarayıcının gerçekten açtığı adresle eşleşip eşleşmediği.
• Bir HTTPS sayfasının wss:// üzerinden bağlanıp bağlanmadığı.
• Ters proxy'nin WebSocket Upgrade isteğini iletip iletmediği.
• Tarayıcı girişinin süresinin dolup dolmadığı.

/ws'e karşı çıplak bir curl'ün HTTP 400 döndürmesi beklenir: uç nokta çalışma alanı kapsamlı sorgu parametreleri gerektirir ve herhangi bir WebSocket yükseltmesi gerçekleşmeden önce çıplak bir el sıkışmayı reddeder. Arka uç günlüklerine düşen bir 400/401, bu yüzden yalnızca sıradan HTTP yönlendirmesinin arka uca ulaştığını kanıtlar — proxy'nin WebSocket Upgrade başlıklarını koruduğunu kanıtlamaz. Gerçek bağlantıyı doğrulamak için tarayıcı DevTools → Network → WS sekmesini açın (veya WebSocket destekli bir istemci kullanın) ve bir 101 el sıkışması arayın.

Kendi sunucunuzda barındırma notu: daemon'lar uzun bağlantıları için /ws değil /api/daemon/ws'i çevirir — bunu da aynı şekilde arka uca yönlendirin. El sıkışma orada başarısız olursa daemon sessizce yoklamaya (polling) döner; arka uç günlüğünde bu yolda tekrar eden status=400 satırları bunun belirtisidir.

docker compose -f docker-compose.selfhost.yml up -d

Tam bir ters proxy örneği için bkz. kendi sunucunuzda hızlı başlangıç.

multica setup, sunucuya ulaşılamadığını bildiriyor

CLI'ın erişilebilirlik yoklaması <server-url>/health'e bir GET yapar ve bir 200 gerektirir. Bu yolu sunan bileşen arka uçtur. Güncel web sürümleri /health'i arka uca yönlendirir, ama daha eski sürümler yönlendirmez — her isteği böyle eski bir ön uca ileten bir ters proxy 404 döner ve yığın aslında sağlıklıyken CLI sunucunun çalışmadığı sonucuna varır.

/health'i proxy'nizde açıkça arka uca (port 8080) yönlendirmek tüm sürümlerde işe yarar — kendi sunucunuzda hızlı başlangıç rehberindeki her iki Caddy örneği de bunu yapar. Şununla doğrulayın:

curl -fsS <server-url>/health

Doğrulama kodu ve davet e-postaları teslim edilmiyor

Önce arka uç başlangıç günlüğünü kontrol edin. Sunucunun SMTP relay, Resend API veya DEV mode kullandığını belirtir:

docker compose -f docker-compose.selfhost.yml logs backend \
  | grep "EmailService:"

• DEV mode: hiçbir e-posta gönderilmez; doğrulama kodları ve davet bağlantıları yalnızca arka uç günlüğüne yazılır.
• Resend: API anahtarının geçerli olduğunu ve gönderen adresinin alan adının doğrulandığını onaylayın.
• SMTP: host'u, portu, kimlik bilgilerini ve gönderen adresini onaylayın, ve başarısızlığın bağlantı, TLS, kimlik doğrulama veya teslim aşamasında mı olduğunu anlamak için hata günlüğünü kullanın.

SMTP_HOST ve Resend ikisi de yapılandırıldığında, Multica SMTP'yi tercih eder. Yapılandırma için bkz. Giriş ve kayıt.

Ek yüklemeleri veya indirmeleri başarısız oluyor

Önce arka uç günlüğünü ve yanıt durum kodunu kontrol edin. Yaygın nedenler:

• Ters proxy istek gövdesi boyutunu sınırlıyor.
• Yerel yükleme dizini yazılabilir değil veya kalıcı bir birim bağlı değil.
• S3 bucket'ı, bölgesi, uç noktası veya kimlik bilgileri eşleşmiyor.
• İndirme URL'si, bir proxy'den geçtikten sonra yanlış herkese açık alan adını veya protokolü kullanıyor.

Docker Compose ile, varsayılan backend_uploads birimi yerel ekleri saklar. Container'ları yeniden oluşturmak onu silmez, ama docker compose down -v veri birimini siler. S3 yapılandırması için bkz. Ortam değişkenleri.

Kullanım sıfır gösteriyor

Kullanım sayfası, her çalıştırmanın ham kullanımını değil saatlik toplulaştırmaları okur. Önce ham veriyi ve toplulaştırma tablosunu kontrol edin:

SELECT count(*) FROM task_usage;
SELECT count(*) FROM task_usage_hourly;

SELECT plan_time, status, error_code, error_msg
FROM sys_cron_executions
WHERE job_name = 'rollup_task_usage_hourly'
ORDER BY plan_time DESC
LIMIT 20;

task_usage'ta satırlar varsa, toplulaştırma tablosu boşsa ve zamanlayıcı kayıtları başarısızlık gösteriyorsa, önce tüm migration'ların uygulandığını doğrulayın; migration 103 yükseltmeyi reddettiyse, sonraki bölüme bakın. SQL sorunlarını zamanlama sorunlarından ayırmak için elle bir toplulaştırma da çalıştırabilirsiniz:

SELECT rollup_task_usage_hourly();

Elle bir çalıştırmadan sonra sayılar doğru görünüyorsa, toplulaştırma fonksiyonu çalışıyor demektir ve sorun arka ucun yerleşik zamanlamasındadır; elle SQL yalnızca bir toplulaştırmayı doldurur ve zamanlamayı geri yüklemez. Saatlik toplulaştırmalar arka ucun yerleşik zamanlayıcısı tarafından yürütülür — pg_cron'u kendiniz yapılandırmanız gerekmez.

Migration 103 bir yükseltmeyi engelliyor

Normal bir yükseltme 103 için hiçbir eylem gerektirmez: migrate up, onu uygulamadan önce geçmiş kullanım verisini otomatik olarak geriye doldurur — boş bir veritabanı doğrudan geçer, ve geçmişi olan örnekler devam etmeden önce ay ay geriye doldurulur.

Arka uç hâlâ refusing to drop legacy daily rollups ile başlamayı başaramıyorsa, otomatik geriye doldurma tamamlanmamıştır (örneğin, yarıda başarısız oldu, veya SQL migrate up yerine doğrudan uygulandı). Geriye doldurma komutunu elle çalıştırın, sonra arka ucu yeniden başlatın:

cd server
DATABASE_URL='postgres://...' go run ./cmd/backfill_task_usage_hourly

Yararlı bayraklar: --dry-run yazmadan önizler; --sleep-between-slices meşgul bir örnekte okuma baskısını azaltmak için dilimler arasına bir duraklama ekler. Komut aylık dilimlerde çalışır ve idempotenttir — bir kesintiden sonra doğrudan yeniden çalıştırın. Bir danışma kilidi tutar ve sunucunun zamanlanmış toplulaştırmasıyla karşılıklı dışlanır, bu yüzden yinelenen veya tutarsız toplulaştırma verisi üretemez. Bittiğinde, arka ucu yeniden başlatın ve /readyz'de migrations'ın ok olduğunu doğrulayın.

Port zaten kullanımda

Yaygın yerel portlar API için 8080, web uygulaması için 3000 ve daemon sağlık kontrolü portudur. Önce portu tutan süreci bulun:

lsof -nP -iTCP:8080 -sTCP:LISTEN   # macOS / Linux
netstat -ano | findstr :8080       # Windows

Bu başka bir Multica checkout'uysa, önce o dizinde make stop çalıştırın. Aksi hâlde suçlu programı normal şekilde durdurun, veya geçerli servisin portunu değiştirin. Herkese açık 80/443 portları Caddy veya Nginx gibi bir ters proxy tarafından dinlenir.

Günlük konumları

Bu dosyalardan hangisinin güncel olduğu, daemon'ın hangi profille başlatıldığına bağlıdır ve önceki bir daemon'dan kalma eski bir günlük dosyası sorunsuzca okunmaya devam eder — bu da yanlış dosyayı hata ayıklamanın en kolay yoludur. Tahmin ederek dosya açmayın: multica daemon logs, akışa başlamadan önce çözümlediği mutlak yolu yazdırır. Adlandırılmış bir profilin günlüğünü okumak için --profile <name> ekleyin.

Daemon'ın başlangıcını doğrudan gözlemlemek için, onu ön planda çalıştırın:

multica daemon stop
multica daemon start --foreground

Yine de sorunu belirleyemiyorsanız, mevcut işleri arayın veya GitHub Issues'da yeni bir tane açın.

Sırada

• Daemon ve runtime'lar — runtime'ların nasıl kaydolduğu ve çevrimiçi durumu nasıl bildirdiği.
• Çalıştırmalar — durum, zaman aşımı ve başarısızlık referansı.
• Ortam değişkenleri — tam kendi sunucunuzda barındırma yapılandırma referansı.