Kurulumsudo npm i -g signalbird-cli && sudo signalbird agent install --token=sba_live_…

Sunucu Ajanı - kurulum ve kullanım kılavuzu

Bu belge, sunucunuza kurduğunuz Signalbird ajanını anlatır. Ajan, signalbird-cli npm paketinin agent rolüdür: sunucunuzun durumunu okur ve Signalbird'e gönderir. Sunucunuzda hiçbir şeyi değiştirmez.

Hiç sunucu yönetmediyseniz de okuyabilirsiniz. Her adımda ne yazacağınız, ne göreceğiniz ve bir şey ters giderse ne yapacağınız yazıyor. Terminal ekranını hiç açmadıysanız bile 5 dakikada kurulur.

Kaynak kod: https://github.com/Pariette-Inc/signalbird.cli (MIT)

Eski bash ajanını kullanıyorsanız: bash ve PowerShell ajan betikleri emekliye ayrıldı. Aşağıdaki kurulumu aynı sunucuda çalıştırmanız yeterli: yeni ajan eskisinin yerine geçer, ayar dosyanızı (anahtar, izinli yollar, veritabanı satırları) korur.

1. Bu ne işe yarar? (30 saniyede)

Sitenizin ayakta olup olmadığını dışarıdan bakarak anlayabilirsiniz. Ama şunları dışarıdan göremezsiniz:

Diskiniz %97 dolmuş, yarın dolacak.
Veritabanı bağlantıları tavan yapmış, ilk yoğunlukta site duracak.
MySQL servisi durmuş, uygulama önbellekten idare ediyor.
Gece yedeğiniz üç gündür alınmıyor ve kimsenin haberi yok.

Ajan bunları sunucunun içinden görür ve panele taşır. Bir de "beklenen sinyal" vardır: yedekleme betiğiniz her saat "aldım" der; demezse alarm çalar.

2. Sözlük - burada geçen kelimeler

Kelime	Ne demek
Ajan	Sunucunuza kurduğunuz program (`signalbird agent`). Sürekli arka planda çalışır.
signalbird-cli	Ajanı taşıyan npm paketi. Kurulunca sunucuda `signalbird` komutu olur.
Node.js	Ajanın üzerinde çalıştığı ortam. 20 ya da daha yeni sürüm gerekir.
Terminal / SSH	Sunucuya yazı yazarak komut verdiğiniz siyah ekran.
root / sudo	Sunucudaki yönetici yetkisi. Kurulum için gerekir.
Anahtar (token)	`sba_live_…` ile başlayan uzun şifre. Ajanın kimliğidir.
Ölçüm (metrik)	CPU, bellek, disk gibi sayısal durum bilgileri.
Telsiz	Signalbird'ün log toplama modülü. Ajanın gönderdiği log satırları oraya düşer.
Beklenen sinyal	"Bu iş bitti" haberi. Gelmezse Signalbird alarm verir.
Servis (systemd)	Sunucu açıldığında kendiliğinden başlayan program. Ajan böyle çalışır.

3. Başlamadan önce elinizde ne olmalı?

Bir Linux sunucu. systemd kullanan bir dağıtım: Ubuntu, Debian, Rocky, AlmaLinux… (Windows Server şimdilik desteklenmiyor, bkz. §5.)
Sunucuya bağlanma yolu. SSH.
Yönetici yetkisi. sudo (ya da doğrudan root).
Node.js 20 veya daha yenisi. Aşağıda nasıl kontrol edileceği yazıyor.
Signalbird hesabınızda Sunucu İzleme modülü. Yoksa panelde Sunucular ekranı bir kilit gösterir ve modülü oradan ekleyebilirsiniz.
Giden internet erişimi. Sunucunuzun dışarıya 443 portundan çıkabilmesi yeter. Dışarıdan sunucunuza hiçbir port açmanız gerekmez.

Node.js kurulu mu, bakın:

bash

node --version

v20.… ya da daha büyük bir sayı görüyorsanız hazırsınız. "command not found" diyorsa ya da sürüm 20'den küçükse, Ubuntu/Debian'da NodeSource paketini kurun. Kurulum betiğini önce indirip okuyun, sonra çalıştırın:

bash

curl -fsSL https://deb.nodesource.com/setup_20.x -o nodesource_setup.sh
less nodesource_setup.sh
sudo bash nodesource_setup.sh && sudo apt-get install -y nodejs

(less ekranından q ile çıkarsınız.) Rocky / AlmaLinux gibi dağıtımlarda dağıtımın kendi Node.js 20 paketini ya da https://nodejs.org adresindeki yolu kullanın.

4. Kurulum - Ubuntu / Debian / Linux

Adım 1 · Panelde sunucu kaydı açın

Signalbird panelinde soldaki menüden Sunucular'a girin.
Sağ üstteki Sunucu ekle düğmesine basın.
Bir ad yazın. Bu ad yalnız sizin için: web-01, veritabani, kargo-api gibi hatırlayacağınız bir şey olsun.
İzinli log köklerini yazın: ajanın okuyabileceği klasörler. Emin değilseniz varsayılan /var/log kalsın (bkz. "İsteğe bağlı" bölümü).
Oluştur'a basın.

Karşınıza sba_live_… ile başlayan anahtar çıkar, ardından panel sizi sunucunun kurulum sayfasına (/servers/<id>/install) götürür. Bu sayfada kopyalayacağınız komutlar ve canlı bir "ilk mesaj bekleniyor" kutusu vardır: ajan ilk kez seslendiğinde kutu kendiliğinden yeşile döner.

Anahtar bir kez gösterilir. Pencereyi kapatmadan önce kopyalayın. Kaybederseniz dünyanın sonu değil: sunucu kaydının içinden Anahtarı tazele diyebilirsiniz (eski anahtar o anda geçersiz olur).

Adım 2 · Sunucuya bağlanın

Kendi bilgisayarınızın terminalinden:

bash

ssh kullanici@sunucu-adresiniz

Adım 3 · Paketi kurun ve ajanı başlatın

Kurulum sayfasındaki komutları olduğu gibi yapıştırın:

bash

sudo npm install -g signalbird-cli
signalbird --version
sudo signalbird agent install --token=sba_live_BURAYA_KENDI_ANAHTARINIZ

İlk satır paketi sunucuya kalıcı olarak kurar, ikincisi signalbird komutunun geldiğini gösterir (bir sürüm numarası yazar), üçüncüsü ajanı kurar.

npx ile kurmayın. npx signalbird-cli agent install gibi bir komut paketi geçici bir klasörden çalıştırır; o klasör silinince servis de çalışmaz. Ajan bunu fark eder ve kurmayı reddeder. Önce sudo npm install -g signalbird-cli.

install sırasıyla şunları yapar:

Anahtarı önce Signalbird'e sorar. Anahtar reddedilirse hiçbir dosya yazılmaz, kurulum durur.
/etc/signalbird/agent.conf ayar dosyasını yazar. Dosyayı yalnız root okuyabilir (0600).
signalbird-agent adlı systemd servisini kurar ve başlatır.
Sunucuda eski bash ajanı kuruluysa onun yerine geçer; mevcut agent.conf korunur, yalnız anahtar ve API adresi güncellenir.

Şunu görürseniz kurulum tamamdır:

text

✓ Signalbird anahtarı kabul etti.

Kurulum tamam.

  Ayar dosyası : /etc/signalbird/agent.conf
  Servis       : systemctl status signalbird-agent
  Günlük       : /var/log/signalbird-agent.log  ·  journalctl -u signalbird-agent
  Sinyal örneği: signalbird agent signal db-backup ok "yedek bitti"

Adım 4 · Çalıştığını doğrulayın

bash

sudo signalbird agent status

Ajan önce ayarını ve servis durumunu yazar, sonra Signalbird'e bağlanmayı dener:

text

Signalbird ajanı 1.1.0 (signalbird-cli …, protokol 1)
  API        : https://live.signalbird.io/api
  Anahtar    : sba_live_xxxxxxx…
  İzinli yol : /var/log
  Veritabanı : yerel ayarda yok
  Ayar sürümü: …
  Servis     : active

Bağlantı deneniyor...
Bağlantı tamam.

Son satırda "Bağlantı tamam." yazmalı. Bir de servise bakalım:

bash

systemctl status signalbird-agent

Yeşil active (running) görüyorsanız iş bitti. Paneldeki kurulum sayfasında "ilk mesaj bekleniyor" kutusu yeşile döner; Sunucular ekranında sunucunuz "Çevrimiçi" görünür ve bir dakika içinde CPU, bellek, disk değerleri dolar.

İsteğe bağlı · okunacak log klasörlerini genişletin

Ajan varsayılan olarak yalnız /var/log altındaki dosyaları okuyabilir. Uygulamanızın logu başka yerdeyse kurulumda söyleyin:

bash

sudo signalbird agent install \
  --token=sba_live_xxx \
  --allow=/var/log,/srv/uygulamam/storage/logs

Bu liste sunucuda durur. Panelden başka bir yol seçilse bile ajan onu okumaz. Yani Signalbird hesabınız çalınsa bile kimse sunucunuzdan yeni bir dosya okuyamaz.

Kendi Signalbird kurulumunuza ya da bir test adresine bağlanacaksanız --api=https://…/api ekleyin; aksi hâlde bu seçeneğe dokunmayın.

5. Windows Server

Windows Server için ajan şimdilik yok. Eski PowerShell betiği emekliye ayrıldı ve yerine yeni bir sürüm henüz yayınlanmadı. Windows desteği geldiğinde panelde Sunucu ekle ekranında seçenek olarak görünür ve bu belge güncellenir.

O zamana kadar Windows sunucunuzdaki işler için beklenen sinyali ajan olmadan, tek bir HTTP çağrısıyla kullanabilirsiniz (bkz. §11, "Ajan kurmak istemiyorsanız").

6. Panelde ne göreceksiniz?

Sunucular ekranında her sunucu bir kart olur: çevrimiçi mi, CPU, bellek, disk ve son görülme zamanı. Karta tıklayınca ayrıntı açılır:

Bölüm	İçinde ne var
Üst kartlar	CPU, bellek, çalışma süresi, veritabanı durumu
Diskler	Her disk için doluluk çubuğu ve inode oranı
Servisler	İzlemesini istediğiniz servisler yeşil/kırmızı
Socket.io	Bağlı istemci, oda, saniyedeki olay
Süreçler	En çok CPU kullanan ilk N süreç
Ölçüm ayarı	Neyin ölçüleceğini seçtiğiniz yer
İzlenen loglar	Hangi dosyanın Telsiz'e akacağı
Beklenen sinyaller	Yedek gibi işlerin takvimi ve durumu

Panelde "komut çalıştır" kutusu yoktur ve olmayacaktır. Panelden ajana giden şey komut değil ayardır. Bu bir eksiklik değil, tasarım kararıdır: Signalbird hesabınızı ele geçiren biri, sunucunuzda komut çalıştırabilseydi hesap parolanız sunucu parolanız olurdu.

7. Ölçüm ayarı - hangi kutu ne yapar?

Ayar	Ne yapar	Öneri
Ölçüm aralığı	Kaç saniyede bir ölçüm gönderileceği	60 saniye. Çok küçük değer sunucuya yük bindirir; alt sınır 30.
Listelenecek süreç sayısı	En çok CPU yiyen kaç süreç listelensin	5. 0 yazarsanız süreç listesi hiç gönderilmez.
Disk ölçümü	Disk doluluğu ve inode	Açık kalsın. Kesintilerin sessiz sebeplerinden biri dolu disktir.
Dinlenen portlar	Sunucuda hangi portlar dinleniyor	İsteğe bağlı. "Bu port ne zamandır kapalı" sorusunu cevaplar.
Servisler	İzlenecek servis adları (virgülle)	`nginx, mysql, redis` gibi. Adı bilmiyorsanız `systemctl list-units --type=service` ile bulursunuz.
Veritabanı ölçümü	Bağlantı sayısı, yanıt süresi, boyut	Açarsanız sunucudaki ayar dosyasına bağlantı bilgisi yazmanız gerekir (bkz. §9).
Socket.io ölçümü	Bağlı istemci ve oda sayısı	Kendi socket sunucunuzun `/metrics` adresini verirsiniz (bkz. §10).

Ayarı kaydettiğinizde ajan bunu en geç 5 dakika içinde kendiliğinden çeker. Beklemek istemiyorsanız sunucuda:

bash

sudo systemctl restart signalbird-agent

8. Log izleme - hangi dosya, hangi satır?

Ajan log dosyalarını bulunduğu yerden okur, dosyayı taşımaz veya silmez. Yalnız yeni eklenen satırları gönderir; nerede kaldığını hatırlar.

Panelde ekleme

Sunucu detayında İzlenen loglar → Log ekle:

Alan	Ne yazılır	Örnek
Dosya yolu	Tam yol	`/var/log/nginx/error.log`
Kanal	Telsiz'de hangi kanala düşecek	`sunucu`
Filtre	Yalnız eşleşen satırlar gider (düzenli ifade)	`\[error\]\|\[crit\]`

Kaydet'e basmayı unutmayın.

Sık kullanılan filtreler

Amaç	Filtre
nginx hataları	`\[error\]\|\[crit\]\|\[alert\]`
Laravel hataları	`ERROR\|CRITICAL\|EMERGENCY`
PHP-FPM çökmeleri	`child exited\|segfault`
MySQL sorunları	`\[ERROR\]`
Hepsi (filtresiz)	boş bırakın

Üç önemli kural

İlk kurulumda geçmiş log gönderilmez. Ajan dosyanın sonuna atlar ve oradan itibaren dinler. Yoksa bir yıllık nginx logu ilk dakikada Telsiz kotanızı bitirirdi.
Yol izinli olmalı. Sunucudaki allow_paths listesinin dışındaki bir dosya okunmaz; ajanın kendi günlüğüne "izinli değil" diye yazar. Sembolik bağ ile listenin dışına çıkmak da engellenir.
Loglar Telsiz kotasından düşer. Ajan yalnız taşıyıcıdır; saklama ve bildirim kuralları Telsiz modülündedir.

9. Veritabanı izleme

Bağlantı bilgileri yalnız sunucudaki ayar dosyasında durur. Panelde görünmez, panelden değiştirilemez ve Signalbird'e hiç gönderilmez. Desteklenen veritabanları: MySQL, MariaDB ve PostgreSQL.

Adım 1 · Salt okunur bir kullanıcı açın

MySQL / MariaDB:

sql

CREATE USER 'signalbird_ro'@'localhost' IDENTIFIED BY 'guclu-bir-parola';
GRANT PROCESS, REPLICATION CLIENT ON *.* TO 'signalbird_ro'@'localhost';
GRANT SELECT ON information_schema.* TO 'signalbird_ro'@'localhost';
FLUSH PRIVILEGES;

PostgreSQL:

sql

CREATE USER signalbird_ro WITH PASSWORD 'guclu-bir-parola';
GRANT pg_monitor TO signalbird_ro;

Ajan ölçümü sunucudaki mysql ya da psql istemcisiyle alır; istemci kurulu değilse kurun (Ubuntu'da sudo apt install -y mysql-client, Debian'da default-mysql-client; PostgreSQL için postgresql-client).

Adım 2 · Ayar dosyasına yazın

bash

sudo nano /etc/signalbird/agent.conf

Dosyada # ile kapatılmış hazır db_* satırları vardır. Başlarındaki #'yi silip doldurun:

ini

db_driver=mysql          # mysql | mariadb | pgsql
db_host=127.0.0.1
db_port=3306
db_user=signalbird_ro
db_pass=guclu-bir-parola
db_name=uygulama_veritabani

Kaydedip çıkın (nano'da Ctrl+O, Enter, Ctrl+X), sonra:

bash

sudo systemctl restart signalbird-agent

Adım 3 · Panelden açın

Sunucu detayında Veritabanı ölçümü anahtarını açın. Bir dakika içinde üst kartlarda bağlantı sayısı ve yanıt süresi görünür.

Parola komut satırına yazılmaz. Ajan parolayı yalnız o çağrının ortamına MYSQL_PWD / PGPASSWORD olarak verir; aksi hâlde parolanız sunucudaki ps çıktısında herkese görünürdü.

10. Socket.io izleme

Ajan yalnız localhost adreslerine bakar (http://127.0.0.1:…, http://localhost:…, http://[::1]:…) ve yönlendirmeleri izlemez. Bu bilinçlidir: panelden rastgele bir adres verilebilseydi, ajan müşterinin iç ağını tarayan bir araca dönüşebilirdi.

Socket sunucunuza küçük bir sayaç ucu ekleyin:

// Node.js + socket.io
const http = require('http')

http.createServer((req, res) => {
  if (req.url !== '/metrics') { res.writeHead(404); return res.end() }

  res.writeHead(200, { 'Content-Type': 'application/json' })
  res.end(JSON.stringify({
    clients: io.engine.clientsCount,          // bağlı istemci
    rooms: io.sockets.adapter.rooms.size,     // oda sayısı
    events_per_second: eventsPerSecond,       // kendi sayacınız
  }))
}).listen(3001, '127.0.0.1')                  // YALNIZ localhost

Panelde Socket.io ölçümü'nü açın ve adresi yazın: http://127.0.0.1:3001/metrics.

11. Beklenen sinyal - "yedek alınmadı" alarmı

Bu, ürünün en çok işe yarayan parçalarından biridir. Mantığı ters kurulmuştur: bir şeyin olmaması alarm üretir.

Senaryo

Veritabanı yedeğiniz her saat başı alınıyor. Bir gün cron bozuluyor ve yedekleme hiç çalışmıyor. Hiçbir hata mesajı yok - çünkü çalışmayan bir iş hata da üretmez. Diskiniz çöktüğünde son yedeğinizin üç haftalık olduğunu öğreniyorsunuz.

Kurulumu (3 adım)

1. İzlemeyi oluşturun. Panelde İzleyiciler → Yeni → tür olarak Beklenen sinyal seçin.

2. Zamanı söyleyin. "Beklenen sinyalin zamanı" bölümünde:

Seçenek	Ne zaman beklenir
Kayan pencere	Son sinyalden itibaren sayar (eski davranış)
Her saat başı	00:00, 01:00, 02:00 …
Her 15 / 30 dakikada	:00, :15, :30, :45
Her 6 saatte	00:00, 06:00, 12:00, 18:00
Her gün belirli saatte	Örneğin her gün 03:30
Özel (cron)	Kendi ifadeniz, örneğin `0 4 * * 1` (her pazartesi 04:00)

Tolerans kaç dakika bekleneceğidir: "her saat başı + 5 dakika" derseniz, 14:05'e kadar sinyal gelmezse alarm çalar.

Ajan kurulu bir sunucu seçtiyseniz bir de sinyal anahtarı yazın: db-backup gibi.

3. Betiğinize tek satır ekleyin.

bash

#!/bin/bash
if mysqldump --all-databases | gzip > /var/backups/db.sql.gz; then
    signalbird agent signal db-backup ok "$(du -h /var/backups/db.sql.gz | cut -f1)"
else
    signalbird agent signal db-backup fail "mysqldump hata verdi"
fi

Betik root olarak çalışmalı. signalbird agent signal anahtarı /etc/signalbird/agent.conf dosyasından okur ve o dosyayı yalnız root okuyabilir. Betiği root'un cron tablosuna koyun (sudo crontab -e), elle denerken başına sudo ekleyin. Root olmayan bir kullanıcıyla çalışırsa "izin yok, sudo ile çalıştırın" hatası alırsınız.

Ajan kurmak istemiyorsanız (ya da betik root olmayan bir kullanıcıyla çalışıyorsa), izleme size giriş istemeyen bir adres verir:

bash

curl -fsS "https://live.signalbird.io/api/heartbeat/JETONUNUZ"
# başarısızlıkta:
curl -fsS "https://live.signalbird.io/api/heartbeat/JETONUNUZ?status=fail&message=mysqldump+hata"

Bilmeniz gereken üç kural

Takvim çapası gece yarısıdır, kurulum saatiniz değil. İzlemeyi 14:26'da kurup "her saat başı" derseniz beklenen anlar XX:00'dır, XX:26 değil.
Erken gelen sinyal saymaz. 14:00 beklenirken 13:58'de gelen sinyal 14:00 slotunu karşılamaz. Bu kural olmasaydı, saatte bir çalışması gereken bir iş 59 dakika erken çalıştığında sistem "geldi" der ve gerçek kaçırmayı hiç görmezdiniz.
fail beklemez. İş çalışıp başarısız olduysa alarm anında çalar. Sessizlik yalnız "sunucu tamamen öldü" hâlini yakalar.

Betiğe dokunmadan: dosya modu

Yedekleme betiğini değiştiremiyorsanız, izlemede Dosya ile sinyal alanına yedek dosyasının yolunu yazın (/var/backups/db.sql.gz). Ajan dosyanın değişme zamanına bakar; dosya tazeyse sinyali kendisi atar, bayatsa hiçbir şey göndermez ve alarm normal şekilde çalar. Dosya hiç yoksa fail gönderir.

12. Komut referansı

Tüm komutlar signalbird agent <komut> biçimindedir. Ayar dosyası yalnız root tarafından okunabildiği için çoğu sudo ister.

Komut	Ne yapar
`sudo signalbird agent install --token=… [--allow=…] [--api=…]`	Anahtarı önce Signalbird'e dener, sonra ayar dosyasını yazar, servisi kurar ve başlatır. Yeniden çalıştırılabilir: mevcut ayarınız korunur, yalnız anahtar ve API adresi (verildiyse izinli yollar da) güncellenir. Eski bash ajanının yerine geçer. `npx` önbelleğinden çalıştırılırsa kurmayı reddeder.
`sudo signalbird agent status`	Ayarı, servis durumunu gösterir ve bağlantıyı dener; "Bağlantı tamam." ile biter. Bir sorunda ilk bakılacak yer.
`sudo signalbird agent once`	Tek tur çalışır: ayarı çeker, logları ve dosya sinyallerini iletir, ölçüm gönderir. Sınamak için.
`sudo signalbird agent signal <anahtar> [ok\|fail] [mesaj]`	Beklenen sinyali iletir. Durum verilmezse `ok` sayılır.
`signalbird agent run`	Sürekli çalışır. Servis bunu kullanır, elle çağırmanız gerekmez.
`sudo signalbird agent uninstall`	Servisi kaldırır. `/etc/signalbird/agent.conf` ve `/var/lib/signalbird` durur; yeniden kurulumda ayarınız ve log konumlarınız kaybolmaz.
`signalbird agent version`	Ajan sürümü (ör. `1.1.0`). Paket sürümünden ayrıdır; paket sürümü için `signalbird --version`.

Örnekler:

bash

sudo signalbird agent signal db-backup ok "2.4 GB, 51 sn"
sudo signalbird agent signal gece-raporu fail "rapor üretilemedi"
sudo signalbird agent once

Servisin günlüğü:

bash

systemctl status signalbird-agent
journalctl -u signalbird-agent -f
sudo tail -f /var/log/signalbird-agent.log

Tamamen kaldırmak

bash

sudo signalbird agent uninstall && sudo npm uninstall -g signalbird-cli && sudo rm -rf /etc/signalbird /var/lib/signalbird

Bu komut servisi, paketi, ayar dosyasını ve log konumlarını siler. Panelden de sunucu kaydını silmeyi unutmayın (bkz. §19).

Aynı paket, başka bir rol: `signalbird fix`

signalbird-cli paketi geliştirici bilgisayarlarında kod düzeltici (signalbird fix) olarak da kullanılır. O rol root olarak çalışmayı reddeder ve sunucuda gerekmez: sunucular yalnız signalbird agent kullanır.

13. Ayar dosyası referansı

Yol: /etc/signalbird/agent.conf

ini

# Ajanın kimliği. Panelde sunucu kaydı açılırken verilir.
token=sba_live_xxxxxxxxxxxxxxxxxxxx

# Signalbird adresi. Kendi kurulumunuz yoksa değiştirmeyin.
api_base=https://live.signalbird.io/api

# Panelden seçilen log yolları YALNIZ bu köklerin altındaysa okunur.
# Virgülle çoğaltılır.
allow_paths=/var/log,/srv/uygulama/storage/logs

# Veritabanı izleme açıksa kullanılır. Panele GÖNDERİLMEZ.
db_driver=mysql
db_host=127.0.0.1
db_port=3306
db_user=signalbird_ro
db_pass=guclu-bir-parola
db_name=uygulama

Dosya anahtar=değer satırlarından oluşur; hiçbir zaman çalıştırılmaz, yalnız satır satır okunur. Yalnız root okuyabilir (0600). Değişiklikten sonra servisi yeniden başlatın: sudo systemctl restart signalbird-agent.

Durum dosyası: /var/lib/signalbird/state - log dosyalarında nerede kaldığını tutar. Silerseniz ajan dosyaların sonundan devam eder (geçmişi göndermez). Son bilinen panel ayarı /var/lib/signalbird/config.json dosyasındadır. Ajanın kendi günlüğü: /var/log/signalbird-agent.log (anahtarlar maskelenir).

14. SDK ile kullanım

Sunucu ajanı bir programdır, kütüphane değil: SDK'ya paket olarak girmez ve girmemelidir. Ama çevresindeki her şey SDK ile yapılabilir:

İhtiyaç	Yol
Uygulamanızın kendi hata ve olaylarını göndermek	Telsiz SDK'sı (`signalbird` paketi, 12 dil). Ajanın taşıdığı sunucu logları da aynı yere düşer.
Ajanın gönderdiği logları okumak / raporlamak	Yönetim yüzeyi (`radio:read` kapsamı): `management.radioEvents({...})`
Beklenen sinyali kod içinden atmak	Ajan gerekmez, tek HTTP çağrısı yeter (`/api/heartbeat/<jeton>`).
Sunucu kayıtlarını listelemek/yönetmek	Panel uçları (`/v1/panel/agents`), Sanctum oturumuyla. SDK metodu henüz yok.

Telsiz ile uygulama içinden log yazmak:

import { Signalbird } from 'signalbird'

const log = new Signalbird({ domainKey: process.env.SB_RADIO_KEY })

await log.error('Yedekleme betiği hata verdi', {
  channel: 'sunucu',
  meta: { host: 'web-01', exit_code: 2 },
})

Kendi ajanınızı yazmak isterseniz protokolün tamamı açıktır: AGENT-PROTOCOL.md.

15. Ajanın konuştuğu uçlar (kendi aracınızı yazacaksanız)

Hepsi tek yönlüdür: ajan getirir, Signalbird kabul eder. Kimlik tek bir başlıktır.

text

Authorization: Bearer sba_live_…
Content-Type: application/json
Accept: application/json

Uç	Ne yapar
`POST /v1/agent/hello`	Kimliğini bildirir; ayarı ve sürüm durumunu alır.
`GET /v1/agent/config`	Yalnız ayarı alır.
`POST /v1/agent/metrics`	Ölçüm gönderir.
`POST /v1/agent/logs`	Log satırlarını gönderir (tek istekte en çok 100).
`POST /v1/agent/signal`	Beklenen sinyali iletir (`ok` / `fail`).

Örnek:

bash

curl -X POST https://live.signalbird.io/api/v1/agent/signal \
  -H "Authorization: Bearer sba_live_xxx" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"key":"db-backup","status":"ok","message":"2.4 GB"}'

Alan sınırları: mesaj 4000, kaynak (source) 120 karakter. Accept başlığını unutmayın - yoksa doğrulama hatası JSON yerine yönlendirme olarak döner.

16. Güvenlik - ne yapar, ne yapamaz

Ajan şunları YAPAMAZ:

Servis başlatamaz, durduramaz (kurulum ve kaldırma sırasında kendi servisi hariç).
Dosya silemez, değiştiremez, oluşturamaz (kendi durum klasörü ve günlüğü hariç).
Paket kuramaz, sistem ayarı değiştiremez.
Signalbird'den komut alamaz. Böyle bir uç yoktur.
Kendini güncelleyemez. Yeni sürümü yalnız haber verir.
İzin verilen kökler dışındaki dosyaları okuyamaz.
Signalbird API'si ve localhost dışındaki adreslere istek atamaz (socket ölçümü yalnız localhost'a gider).

Çalıştırdığı programlar sabit bir listedir: df, systemctl, ss, ps, mysql, psql. Liste kodun içindedir; listede olmayan bir program çağrılırsa ajan hata verir. Komutlar kabuk olmadan çalışır, panelden gelen hiçbir değer kabukta yorumlanmaz. Tam argümanlarıyla liste: AGENT-COMMANDS.md. Ayar okuma, log okuma ve Signalbird'e gönderim Node.js'in kendisiyle yapılır; curl, python3 ya da jq gerekmez.

Signalbird'e giden veri: ölçüm sayıları, servis adları ve durumları, seçtiğiniz log dosyalarındaki eşleşen satırlar, sinyaller. Gitmeyen veri: veritabanı parolanız, ayar dosyanız, seçmediğiniz dosyaların içeriği.

Anahtar sızarsa yapılabilecek en kötü şey sahte ölçüm ve sahte log göndermektir; anahtar takımınızın başka hiçbir verisine erişemez. Panelden Anahtarı tazele deyip sudo signalbird agent install --token=… komutunu yeni anahtarla tekrar çalıştırın.

Anahtar reddedilirse (401) ajan durur ve systemd onu yeniden başlatmaz; sonsuz döngüde istek atmaz. Modül kapalıysa (403 MODULE_DISABLED) ajan bekler, modül açıldığında kendiliğinden devam eder.

Ajan hangi yetkiyle çalışır? Kurulum ve servis root ister (servis kaydı, 0600 ayar dosyası ve /var/log okuma için). systemd birimi ProtectSystem=strict ile korunur: yazabildiği tek yerler kendi durum klasörü (/var/lib/signalbird) ve /var/log'daki kendi günlüğüdür.

17. Sürüm ve güncelleme

Ajan kendini güncellemez. Yeni ajan sürümü yayınlandığında panelde sunucu satırında "Güncelleme var" rozeti çıkar ve size bir bildirim düşer (sürüm başına bir kez; güvenlik sürümlerinde ayrıca telefonunuza). Ajan da kendi günlüğüne "Yeni ajan sürümü var" satırı yazar.

Güncellemek için:

bash

sudo npm install -g signalbird-cli@latest && sudo systemctl restart signalbird-agent

Ayar dosyanız korunur, log okuma noktalarınız kaybolmaz.

Ajan sürümü paket sürümünden ayrı bildirilir: panelin gösterdiği sürüm signalbird agent version çıktısıdır (şu an 1.1.0), signalbird --version ise paketin sürümünü yazar.

18. Sorun giderme

Belirti	Sebep ve çözüm
Panelde sunucu "Çevrimdışı"	`systemctl status signalbird-agent` ile servise bakın. Durmuşsa `sudo systemctl start signalbird-agent`.
`signalbird: command not found`	Paket kurulmamış: `sudo npm install -g signalbird-cli`.
"Node 20+ gerekli"	Node.js eski. §3'teki NodeSource adımlarıyla 20'ye yükseltin.
"Kurulum root gerektirir"	Komutun başına `sudo` ekleyin.
"npx ile servis kurulmaz"	Önce `sudo npm install -g signalbird-cli`, sonra `sudo signalbird agent install …`.
"Ayar dosyası okunamadı … izin yok"	Ayar dosyası yalnız root'a açık. Komutu `sudo` ile çalıştırın; betikse root'un cron tablosuna taşıyın.
`status` / `install` "Anahtar reddedildi" diyor	Anahtar yanlış ya da tazelenmiş. Panelden yenisini alıp `sudo signalbird agent install --token=…` komutunu tekrar çalıştırın.
Kurulum "Bağlantı doğrulanamadı; kurulum yine de yapılıyor" diyor	Sunucu o an Signalbird'e ulaşamadı (giden 443, DNS, vekil sunucu). Kurulum tamamlanır, servis tekrar dener. Ağı düzeltip `sudo signalbird agent status` ile bakın.
`MODULE_DISABLED` hatası	Sunucu İzleme modülü paketinizde yok ya da aboneliğiniz bitmiş. Panelden modülü ekleyin; ajan kendiliğinden devam eder.
Ölçüm geliyor, log gelmiyor	Yol `allow_paths` altında mı? Filtre satırlara uyuyor mu? `/var/log/signalbird-agent.log` dosyasına bakın.
"log yolu izinli değil" uyarısı	`allow_paths` satırını genişletip servisi yeniden başlatın.
Veritabanı `ok:false`	Ayar dosyasındaki `db_*` satırları, kullanıcının yetkisi ve `mysql`/`psql` istemcisinin kurulu olup olmadığı.
Socket ölçümü gelmiyor	Adres `127.0.0.1` ile mi başlıyor? Uç JSON dönüyor mu? `curl http://127.0.0.1:3001/metrics` ile deneyin.
Sinyal gönderdim ama alarm çaldı	Sinyal pencerenin dışında gelmiş olabilir (bkz. §11, ikinci kural). İzleme kayıtlarında "pencere dışında geldi" satırını görürsünüz.
"… anahtarıyla bir izleme yok"	Paneldeki sinyal anahtarı ile komuttaki anahtar aynı değil.

Hiçbiri işe yaramadıysa şu iki çıktıyı alıp destek ekibine gönderin:

bash

sudo signalbird agent status
sudo tail -50 /var/log/signalbird-agent.log

19. Sık sorulanlar

Ajan sunucumu yavaşlatır mı? Hayır. Dakikada bir birkaç dosya okur ve tek bir HTTP isteği atar; ölçülebilir bir yük oluşturmaz. CPU ölçümü için 1 saniye bekler, o kadar.

İnternet kesilirse ne olur? Ölçümü atar, log konumunu ilerletmez ve bir sonraki turda tekrar dener. Bağlantı geri geldiğinde kaçan log satırları gönderilir.

Aynı sunucuya iki ajan kurabilir miyim? Gerekmez ve önerilmez. Bir sunucu bir kayıt, bir anahtar.

Eski bash ajanı kuruluydu, ne yapmalıyım? Hiçbir şeyi silmenize gerek yok: §4'teki kurulumu çalıştırın. Servis adı ve dosyalar aynıdır; yeni ajan eskisinin yerine geçer, ayar dosyanızı ve log konumlarınızı devralır. Eski /usr/local/bin/signalbird-agent dosyası artık kullanılmaz, isterseniz silebilirsiniz.

Sunucumu sildim, ne olur? Panelden sunucu kaydını silin. O sunucuya bağlı beklenen sinyaller pasife alınır, yani ajan gittiği için alarm çalmaz.

Ölçüm geçmişini grafikte görebilir miyim? Şu an panel "şu anki durumu" gösterir. Geçmiş grafikleri yol haritasındadır; loglar ve alarm geçmişi bugün de saklanıyor.

Docker konteynerlerini izler mi? Konteynerlerin süreçleri ve kaynak kullanımı sunucu ölçümlerine dahildir. Konteyner bazlı ayrı ölçüm henüz yok.

Windows Server'a kurabilir miyim? Şimdilik hayır (bkz. §5). Desteği geldiğinde panelde görünür.

Ücretlendirme nasıl? Sunucu başınadır, gönderdiğiniz ölçüm sayısına bakılmaz. Loglar Telsiz modülünün kotasından düşer.

Sunucu Ajanı - kurulum ve kullanım kılavuzu

1. Bu ne işe yarar? (30 saniyede)

2. Sözlük - burada geçen kelimeler

3. Başlamadan önce elinizde ne olmalı?

4. Kurulum - Ubuntu / Debian / Linux

Adım 1 · Panelde sunucu kaydı açın

Adım 2 · Sunucuya bağlanın

Adım 3 · Paketi kurun ve ajanı başlatın

Adım 4 · Çalıştığını doğrulayın

İsteğe bağlı · okunacak log klasörlerini genişletin

5. Windows Server

6. Panelde ne göreceksiniz?

7. Ölçüm ayarı - hangi kutu ne yapar?

8. Log izleme - hangi dosya, hangi satır?

Panelde ekleme

Sık kullanılan filtreler

Üç önemli kural

9. Veritabanı izleme

Adım 1 · Salt okunur bir kullanıcı açın

Adım 2 · Ayar dosyasına yazın

Adım 3 · Panelden açın

10. Socket.io izleme

11. Beklenen sinyal - "yedek alınmadı" alarmı

Senaryo

Kurulumu (3 adım)

Bilmeniz gereken üç kural

Betiğe dokunmadan: dosya modu

12. Komut referansı

Tamamen kaldırmak

Aynı paket, başka bir rol: signalbird fix

13. Ayar dosyası referansı

14. SDK ile kullanım

15. Ajanın konuştuğu uçlar (kendi aracınızı yazacaksanız)

16. Güvenlik - ne yapar, ne yapamaz

17. Sürüm ve güncelleme

18. Sorun giderme

19. Sık sorulanlar

Aynı paket, başka bir rol: `signalbird fix`