n8n Community Node Kurulumu ve Kullanımı

Yazar:komut.io ekibi n8n ile Görsel İş Akışı Otomasyonu
0 Yorum

Otomasyon dünyasında n8n ile biraz zaman geçirdiyseniz, er ya da geç şu soruyla karşılaşırsınız: “Bu entegrasyon neden yok?” Ya da daha kötüsü: “Bu node tam istediğimi yapmıyor.” İşte tam bu noktada community node’lar devreye giriyor. Bugün bu konuyu derinlemesine ele alacağız çünkü community node kurulumu, göründüğü kadar basit ama göründüğünden daha fazla dikkat gerektiren bir konu.

Community Node Nedir, Neden Önemlidir?

n8n’in resmi node kütüphanesi oldukça geniş. Slack, GitHub, PostgreSQL, HTTP Request… Bunlar yeterli geldiği sürece hayat güzel. Ama gerçek dünya senaryolarında, özellikle Türkiye’deki iş ortamında çalışıyorsanız, ihtiyaç duyduğunuz bazı entegrasyonların resmi listede olmadığını görürsünüz. Parasut, Logo, Netsis gibi yerli ERP sistemleri, Türk bankalarının API’leri, kurumsal yazılımlar…

Community node’lar, n8n’in npm ekosistemiyle entegrasyonu sayesinde hayatımıza giriyor. Temelde n8n-nodes- prefix’iyle npm’e yayınlanmış paketler bunlar. Birisi bir entegrasyon geliştirmiş, paketlemiş, npm’e koymuş. Siz de n8n arayüzünden veya komut satırından kuruyorsunuz.

Ancak burada bir uyarı vermem gerekiyor: Community node’lar denetlenmemiş kod içerir. Üretim ortamınıza kurmadan önce ne yaptığını anlamak, en azından kaynak koduna göz atmak kritik önem taşıyor. Bu bir paranoya değil, temel güvenlik hijyeni.

Kurulum Öncesi Gereksinimler

Community node kurulumu için n8n’in doğru mod ve versiyonda çalışıyor olması gerekiyor. Önce ortamınızı kontrol edelim.

# n8n versiyonunu kontrol et
n8n --version

# npm'in kurulu olduğunu doğrula
npm --version
node --version

# n8n process'inin çalışıp çalışmadığını gör
systemctl status n8n
# veya Docker kullanıyorsanız
docker ps | grep n8n

n8n’i Docker ile çalıştırıyorsanız, community node’lar için özel bir konfigürasyon gerekiyor. Vanilla kurulumda community node’lar varsayılan olarak devre dışı.

Önemli environment variable’lar:

  • N8N_COMMUNITY_PACKAGES_ENABLED: Community node kurulumunu aktif eder, varsayılan değeri false
  • N8N_COMMUNITY_PACKAGES_REGISTRY: Özel npm registry kullanmak istiyorsanız buraya yazarsınız
  • N8N_USER_FOLDER: n8n’in kullanıcı verilerini sakladığı dizin, node’lar buraya kurulur
  • NODE_FUNCTION_ALLOW_EXTERNAL: Function node’lardan dış modüllere erişim için

Docker Compose ile çalışıyorsanız, docker-compose.yml dosyanıza şunu eklemeniz gerekiyor:

version: '3.8'
services:
  n8n:
    image: n8nio/n8n:latest
    environment:
      - N8N_COMMUNITY_PACKAGES_ENABLED=true
      - N8N_USER_FOLDER=/home/node/.n8n
      - NODE_FUNCTION_ALLOW_EXTERNAL=*
    volumes:
      - n8n_data:/home/node/.n8n
      - /var/run/docker.sock:/var/run/docker.sock:ro
    ports:
      - "5678:5678"

volumes:
  n8n_data:

/var/run/docker.sock mount’unu eklemek zorunlu değil ama bazı community node’lar Docker API’sine erişmek isteyebiliyor, önceden eklemek acı çektiriyor bana göre.

Arayüzden Community Node Kurulumu

n8n 0.187 ve sonrasında, arayüz üzerinden community node kurulumu destekleniyor. Adımlar şöyle:

Settings > Community Nodes > Install a community node yolunu izliyorsunuz. Buraya npm paket adını yazıp kurulum yapabiliyorsunuz.

Ama ben size dürüst söyleyeyim: Arayüzden kurulum, özellikle Docker ortamlarında bazen sorun çıkarıyor. Package yüklenmiş görünüyor, n8n yeniden başlatılması isteniyor, ama node workflow editöründe görünmüyor. Bu durumun çözümü genellikle manuel kuruluma geçmek oluyor.

Manuel Kurulum Yöntemi

Manuel kurulum benim tercih ettiğim yöntem. Daha kontrollü, daha öngörülebilir.

# n8n'in kullanıcı dizinine geç
cd ~/.n8n

# Eğer dizin yoksa oluştur
mkdir -p ~/.n8n

# npm init (package.json yoksa)
# Bu adım kritik, atlamayın
npm init -y

# Community node'u kur
# Örnek olarak n8n-nodes-evolution-api kullanalım
npm install n8n-nodes-evolution-api

# Kurulumu doğrula
ls node_modules/ | grep n8n-nodes

Docker ortamında bunu biraz farklı yapıyorsunuz:

# Çalışan container'a bağlan
docker exec -it n8n sh

# Container içinde
cd /home/node/.n8n
npm init -y
npm install n8n-nodes-evolution-api --prefix /home/node/.n8n

# Container'dan çık ve yeniden başlat
exit
docker restart n8n

Bazı community node’lar native addon içeriyor ve derleme gerektiriyor. Bu durumda container image’ınızda build tools kurulu olması lazım. Resmi n8n imajında bunlar genellikle yok. Bu durumu şöyle çözebilirsiniz:

FROM n8nio/n8n:latest

USER root

RUN apk add --no-cache 
    python3 
    make 
    g++ 
    git

USER node

RUN cd /home/node/.n8n && 
    npm init -y && 
    npm install n8n-nodes-your-package

WORKDIR /data

Bu custom Dockerfile’ı build edip kullanmanız gerekiyor bu senaryoda.

Gerçek Dünya Senaryosu: Türkiye’de Whatsapp Otomasyonu

Türkiye’de birçok firma WhatsApp Business API’yi otomasyon için kullanıyor. Evolution API, bu alanda popüler bir açık kaynak çözüm. n8n community node’u da mevcut.

Senaryo: E-ticaret sitenizde sipariş tamamlandığında otomatik WhatsApp mesajı göndereceksiniz.

Önce Evolution API’nin n8n node’unu kuralım:

cd ~/.n8n
npm install n8n-nodes-evolution-api

Kurulumdan sonra n8n’i yeniden başlatın ve workflow editöründe “Evolution” araması yapın. Node görünüyorsa kurulum başarılı demektir.

Workflow mantığı şu şekilde:

Webhook (POST /siparis-tamamlandi)
  --> IF node (Siparis durumu "completed" mi?)
    --> Evolution API node (WhatsApp mesajı gönder)
      --> HTTP Request (Siparis sistemine başarı bildirimi)

Webhook payload örneği:

{
  "order_id": "12345",
  "customer_phone": "905551234567",
  "customer_name": "Ahmet Bey",
  "total_amount": "450.00",
  "status": "completed"
}

WhatsApp mesajı için Evolution API node konfigürasyonu template expression kullanıyor:

Merhaba {{ $json.customer_name }}, 
{{ $json.order_id }} numaralı siparişiniz tamamlandı. 
Toplam tutar: {{ $json.total_amount }} TL. 
İyi günler dileriz!

Community Node Geliştirme: Kendi Node’unuzu Yazın

Eğer ihtiyacınız olan node npm’de yoksa, kendiniz yazabilirsiniz. Bu biraz daha ileri seviye ama temel TypeScript bilgisiyle yapılabilir.

n8n, node geliştirme için resmi bir starter template sunuyor:

# n8n community node template'ini klonla
git clone https://github.com/n8n-io/n8n-nodes-starter.git
cd n8n-nodes-starter

# Bağımlılıkları kur
npm install

# TypeScript'i derle
npm run build

Basit bir HTTP tabanlı node iskelet yapısı:

import {
  IExecuteFunctions,
  INodeExecutionData,
  INodeType,
  INodeTypeDescription,
  NodeOperationError,
} from 'n8n-workflow';

export class BenimNode implements INodeType {
  description: INodeTypeDescription = {
    displayName: 'Benim Custom Node',
    name: 'benimNode',
    icon: 'fa:plug',
    group: ['transform'],
    version: 1,
    description: 'Şirket içi API entegrasyonu',
    defaults: {
      name: 'Benim Node',
    },
    inputs: ['main'],
    outputs: ['main'],
    properties: [
      {
        displayName: 'API URL',
        name: 'apiUrl',
        type: 'string',
        default: '',
        placeholder: 'https://api.sirketim.com',
        description: 'Şirket API adresi',
      },
    ],
  };

  async execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]> {
    const items = this.getInputData();
    const returnData: INodeExecutionData[] = [];

    for (let i = 0; i < items.length; i++) {
      const apiUrl = this.getNodeParameter('apiUrl', i) as string;
      
      const response = await this.helpers.request({
        method: 'GET',
        url: apiUrl,
        json: true,
      });

      returnData.push({
        json: response,
      });
    }

    return [returnData];
  }
}

Geliştirme sırasında local test için node’u n8n’e linklemeniz gerekiyor:

# Node dizininde
npm run build
npm link

# n8n kullanıcı dizininde
cd ~/.n8n
npm link n8n-nodes-benimpaket

# n8n'i dev modda başlat
n8n start

Güvenlik Denetimi: Community Node’u İncelemek

Daha önce bahsettiğim güvenlik konusuna geri dönelim. Bir community node kurmadan önce şu kontrolleri yapmanızı öneririm:

# npm paket bilgilerini gör
npm info n8n-nodes-paketadi

# Paket indirmelerini kontrol et (popülerlik göstergesi)
npm info n8n-nodes-paketadi downloads

# Paketi indir ama kurma, içeriğe bak
npm pack n8n-nodes-paketadi
tar -tf n8n-nodes-paketadi-*.tgz

# Kaynak kodu GitHub'daysa klonla ve incele
git clone https://github.com/gelistirici/n8n-nodes-paketadi
grep -r "exec|spawn|eval|child_process" src/

exec, spawn, eval ve child_process kullanımları mutlaka incelenmeli. Meşru kullanımları var tabii ama bunların ne için kullanıldığını anlamak kritik. Ayrıca fs modülü kullanımına da dikkat edin, dosya sisteminize erişim açabiliyor.

Kurumsal ortamlarda, özel npm registry kullanmanızı şiddetle tavsiye ederim. Verdeon, Nexus veya JFrog Artifactory ile iç registry kurabilir, sadece denetlenmiş paketlerin kurulmasını zorlayabilirsiniz.

Güncellemeler ve Bakım

Community node’ları güncel tutmak önemli. Hem güvenlik açısından hem de n8n’in kendisi güncellendiğinde uyumluluk sorunlarını önlemek için.

# Kurulu community node'ları listele
cd ~/.n8n
npm list --depth=0

# Güncel olmayan paketleri kontrol et
npm outdated

# Belirli bir paketi güncelle
npm update n8n-nodes-evolution-api

# Tüm paketleri güncelle (dikkatli kullanın)
npm update

# n8n'i yeniden başlat
systemctl restart n8n

Otomatik güncelleme için bir cron job yazabilirsiniz, ama ben production ortamında bunu tavsiye etmiyorum. Güncellemeler test ortamında denenmeli, ardından production’a alınmalı.

# /etc/cron.d/n8n-node-check dosyası
# Her Pazartesi sabah bildirim gönder
0 9 * * 1 n8n-user cd /home/n8n-user/.n8n && npm outdated --json > /tmp/n8n-outdated.json 2>&1 && python3 /opt/scripts/notify-outdated.py

Sorun Giderme

Community node kurulumunda en sık karşılaşılan sorunlar ve çözümleri:

Node görünmüyor:

# n8n log'larını kontrol et
journalctl -u n8n -f
# veya
docker logs -f n8n

# package.json'da n8n alanını kontrol et
cat ~/.n8n/node_modules/n8n-nodes-paketadi/package.json | python3 -m json.tool | grep -A5 '"n8n"'

Bazı paketlerin package.json içinde n8n.nodes alanı eksik olabiliyor. Bu durumda paket yanlış yapılandırılmış demektir, geliştiriciyle iletişime geçmek gerekiyor.

Peer dependency hataları:

# n8n-workflow versiyonu uyumsuz olabilir
npm install n8n-nodes-paketadi --legacy-peer-deps

# Veya forced kurulum (son çare)
npm install n8n-nodes-paketadi --force

--force kullanmak riskli. Versiyon uyumsuzluklarını maskeler ve çalışma zamanı hatalarına yol açabilir. Mümkünse --legacy-peer-deps ile deneyin, o da olmuyorsa node’u farklı bir n8n versiyonuyla test edin.

Permission hataları:

# n8n kullanıcısının dizine yazma izni var mı?
ls -la ~/.n8n/
stat ~/.n8n/node_modules

# Gerekirse sahipliği düzelt
sudo chown -R $(whoami):$(whoami) ~/.n8n
chmod 755 ~/.n8n

Node çalışıyor ama hata veriyor:

# n8n'i debug modda başlat
N8N_LOG_LEVEL=debug n8n start 2>&1 | tee /tmp/n8n-debug.log

# Hata mesajlarını filtrele
grep -i "error|fatal|exception" /tmp/n8n-debug.log

Üretim Ortamı İçin En İyi Pratikler

Birkaç yılın deneyiminden çıkan pratik öneriler:

  • Sürüm sabitle: npm install [email protected] şeklinde kesin versiyon belirt. latest kullanmak production’da sürpriz güncelleme demek.
  • Backup al: Node kurulmadan önce ~/.n8n dizinini yedekle. Kurulum bir şeyleri bozabilir.
  • Test ortamında dene: Her yeni community node önce staging’de çalışmalı. Production’da “acaba çalışır mı” oynamayın.
  • Bağımlılık ağacını izle: Bir community node onlarca npm paketi çekebilir. npm ls ile bağımlılık ağacını görün.
  • Kaynak kod erişimi olmayan paketlerden kaçının: npm’de kaynak kod yok, GitHub yok, sadece compiled dosyalar varsa o pakete güvenmeyin.
  • n8n güncellemelerinden önce uyumluluğu kontrol edin: n8n güncellemesi community node’ları bozabilir. Güncelleme öncesi community node geliştiricisinin son aktivitesine bakın.

Sonuç

Community node’lar, n8n’i gerçek anlamda güçlü bir otomasyon platformuna dönüştüren özelliğin ta kendisi. Resmi entegrasyonların yetersiz kaldığı noktalarda, özellikle Türkiye’ye özgü sistemlerle çalışırken, bu ekosistem büyük kolaylık sağlıyor.

Ancak bu güç, beraberinde sorumluluk getiriyor. Denetlenmemiş kodu üretim sistemlerinize kurmak, güvenlik açığı davet etmek demek olabilir. Bu yüzden her community node’u bir “yazılım tedarik zinciri riski” olarak değerlendirmenizi, kaynak kodunu incelemenizi ve mümkünse özel npm registry kullanarak erişim kontrolü yapmanızı öneririm.

Kendi node’unuzu yazmak ise başlangıçta göz korkutucu görünebilir ama n8n’in iyi dokümante edilmiş TypeScript API’si sayesinde birkaç günde temel bir node çıkarabilirsiniz. Şirkete özgü ERP entegrasyonları, muhasebe yazılımları veya sektörel sistemler için bu yatırım kesinlikle değer.

n8n topluluğu büyüyor, Türkiye’deki kullanıcı sayısı da artıyor. Yazdığınız node’ları npm’e yayınlamaktan çekinmeyin. Birinin yaşadığı sorunu siz çoktan çözmüş olabilirsiniz.

Bir yanıt yazın

E-posta adresiniz yayınlanmayacak. Gerekli alanlar * ile işaretlenmişlerdir