Windows Servis Kurulumu¶
Üretim Önerisi
Yerel Windows Servisi, Windows üretim ortamları için önerilen dağıtım yöntemidir. Windows üzerinde Docker ayrı bir dağıtım türüdür — konteyner tercih ediyorsanız Docker Kurulumu sayfasına bakın.
Doğrulama kanıtı
IMPLEMENTED = YES · AUTOMATED TESTED = YES · LIVE E2E VALIDATED = YES (Windows lab, Ağustos 2026).
Ayrıntı: Windows Service E2E · Yükleyici doğrulama matrisi · Test matrisi.
Ön Koşullar¶
- Windows Server 2016+ veya Windows 10/11 (64-bit)
- Bu sunucudan erişilebilir MongoDB 6.0+
- PowerShell 5.1+ (Windows ile birlikte gelir)
- Yönetici (Administrator) yetkileri
- Uygulama sürüm arşivi (
.zip)
MongoDB Ayrı Bir Servistir
Kurulum betiği MongoDB kurmaz veya yönetmez. IQV Integration API'yi kurmadan önce MongoDB kurulu ve çalışır durumda olmalıdır. Kuruluşunuzun veritabanı operasyon dokümantasyonuna bakın.
Çalışma Zamanı Dizin Yapısı¶
Kurulum sonrasında servis şu yolları kullanır:
text
C:\IQVizyon\IQVIntegrationAPI\
bin\ # Uygulama ikili dosyası
config\ # Yapılandırma
.env # Ortam dosyası (kendiniz oluşturmalısınız)
logs\ # Uygulama günlükleri
backups\ # Güncelleme öncesi yedekler
deployment\ # Dağıtım meta verileri
Kurulum¶
1. Ortam Dosyasını Hazırlayın¶
Kurulum betiği .env dosyasını asla otomatik oluşturmaz. Kurulumdan önce .env.example dosyasından elle oluşturmalısınız:
powershell
Copy-Item .\config\.env.example C:\IQVizyon\IQVIntegrationAPI\config\.env
Dosyayı düzenleyin ve tüm zorunlu değerleri ayarlayın — en azından MONGODB_URI, AUTH_CLIENT_SECRET, AUTH_JWT_SECRET.
Gizli Bilgiler
.env dosyasının içeriğini asla günlüğe yazmayın veya paylaşmayın. Gizli bilgiler uygulama günlüklerine asla yazılmaz.
2. Kurulum Betiğini Çalıştırın¶
Yönetici olarak açılmış bir PowerShell istemcisinde çalıştırın:
powershell
powershell.exe -ExecutionPolicy Bypass -File .\scripts\windows\service\install.ps1
Kurulum betiği şunları yapar:
C:\IQVizyon\IQVIntegrationAPI\altında dizin yapısını oluşturur.- İkili dosyayı
bin\dizinine kopyalar. - IQVIntegrationAPI Windows Servisini kaydeder.
- Servisi başlatır.
- Sağlık kontrollerini çalıştırır (
/health/liveve/health/ready). - Başarıyı yalnızca hem canlılık hem hazırlık kontrolleri geçtikten sonra bildirir.
3. Doğrulama¶
powershell
Get-Service IQVIntegrationAPI
Servis Running durumunda görünmelidir.
powershell
Invoke-RestMethod http://localhost:8080/health/live
Invoke-RestMethod http://localhost:8080/health/ready
Kurulum başarılı sayılmadan önce her iki uç nokta da HTTP 200 döndürmelidir.
Kurulum Senaryoları¶
| Senaryo | Servis | Runtime | Config |
|---|---|---|---|
| Clean install | Yok | Yok | Kaynak .env → config\.env |
| Preserved-runtime reinstall | Yok (uninstall sonrası) | Var | Mevcut config\.env korunur |
| Service repair | Var | Var | Config korunur; idempotent SCM onarım |
Varsayılan: preserve. Üzerine yazmak için yalnızca -ReplaceRuntimeConfig.
Preserved Runtime Reinstall¶
uninstall.ps1 sonrası runtime korunmuşken install.ps1 yeniden çalıştırıldığında runtime config hash değişmemeli; servis tek CreateService ile kaydedilmeli (Create sonrası gereksiz ImagePath UpdateConfig yok). Install transaction başarısız olursa partial service temizlenir / backup restore edilir. MongoDB migration geri alınmaz.
Port Ownership Validation¶
Yalnızca “port dolu mu?” bakılmaz. TCP OwningProcess, Windows SCM Win32_Service.ProcessId ile karşılaştırılır (OwnedByExpectedService). Process adı tek başına kanıt değildir.
- ServiceRepair + port mevcut
IQVIntegrationAPIPID’sine ait → PASS (-Forcegerekmez) - Clean / preserved + herhangi bir listener → FAIL (exit 15)
- ServiceRepair + foreign listener → FAIL (exit 15)
- Preflight conflict mutation-free (backup/stop yok)
- Linux: MainPID; Docker: managed Compose port mapping
Servis Yönetimi¶
Durum¶
powershell
powershell.exe -ExecutionPolicy Bypass -File .\scripts\windows\service\status.ps1
Güncelleme¶
powershell
powershell.exe -ExecutionPolicy Bypass -File .\scripts\windows\service\update.ps1
Güncelleme betiği değişiklikleri uygulamadan önce C:\IQVizyon\IQVIntegrationAPI\backups\ altında bir yedek oluşturur. Tam güncelleme prosedürü için Güncelleme ve Geri Alma sayfasına bakın.
Kaldırma¶
powershell
powershell.exe -ExecutionPolicy Bypass -File .\scripts\windows\service\uninstall.ps1
MongoDB Verileri
Kaldırma betiği MongoDB verilerini asla silmez. Servis kaldırıldıktan sonra veritabanınız bozulmadan kalır.
İkili Servis Komutları¶
İkili dosyanın kendisi servis yaşam döngüsü komutlarını destekler:
powershell
.\iqv-integration-api.exe service install --env-file C:\IQVizyon\IQVIntegrationAPI\config\.env
.\iqv-integration-api.exe service uninstall
.\iqv-integration-api.exe service start
.\iqv-integration-api.exe service stop
.\iqv-integration-api.exe service restart
.\iqv-integration-api.exe service status
.\iqv-integration-api.exe service run --env-file C:\IQVizyon\IQVIntegrationAPI\config\.env
--env-file bayrağı servise ortam yapılandırmasını nereden yükleyeceğini bildirir.
Güvenlik Duvarı Yapılandırması¶
API portunu (varsayılan 8080) entegrasyon ortaklarınızdan gelen bağlantılara açın:
powershell
New-NetFirewallRule -DisplayName "IQV Integration API" `
-Direction Inbound -Protocol TCP -LocalPort 8080 `
-Action Allow -Profile Domain,Private
Port Çakışmaları
Port 8080 zaten kullanılıyorsa servis başlatılamaz. .env dosyanızdaki portu değiştirin veya çakışan işlemi durdurun.
Günlükleme¶
Uygulama slog çıktısı süreç stdout’udur. Servis host’u bu akışı logs\ altına yönlendirmez. Olay Günlüğü kaynağı IQVIntegrationAPI SCM için kaydedilir; uygulama slog satırlarını oraya yazmaz.
Kurucu/güncelleme dosya günlüğü: C:\IQVizyon\IQVIntegrationAPI\logs\installer-update.log.
Bkz. Loglama.
Gizli bilgiler, belirteçler (token) ve kimlik bilgileri günlüklere asla yazılmaz.
Çıkış Kodları¶
| Kod | Anlam |
|---|---|
| 0 | Başarı |
| 1 | Genel hata |
| 2 | Yapılandırma hatası |
| 3 | MongoDB bağlantı hatası |
| 4 | MongoDB kimlik doğrulama hatası |
| 5 | MongoDB zaman aşımı |
| 6 | Port zaten kullanımda |
| 7 | TLS sertifika hatası |
| 8 | İzin reddedildi |
| 9 | İkili dosya bulunamadı |
| 10 | Servis kayıt hatası |
| 11 | Sağlık kontrolü hatası |
| 12 | Yedekleme hatası |
| 13 | Geri yükleme hatası |
| 14 | Migrasyon hatası |
| 15 | Kirli depo (dirty repository) |
| 16 | Ağ hatası |
| 17 | Bilinmeyen hata |
Sorun Giderme¶
DATABASE_UNAVAILABLE¶
Uygulama MongoDB'ye ulaşamıyor. Kontrol edin:
- MongoDB servisi çalışıyor:
Get-Service MongoDBveya MongoDB'nin kendi yönetim aracını kontrol edin. .envdosyasındakiMONGODB_URIdoğru ve bu sunucudan erişilebilir.- MongoDB kimlik doğrulama bilgileri geçerli.
- Güvenlik duvarı MongoDB portuna giden bağlantılara izin veriyor.
Port Çakışması (Çıkış Kodu 6)¶
Yapılandırılmış portu başka bir işlem kullanıyor. Bulun:
powershell
Get-NetTCPConnection -LocalPort 8080 | Select-Object OwningProcess
Get-Process -Id <PID>
Migrasyon Hatası (Çıkış Kodu 14)¶
Veritabanı migrasyonu başarısız oldu. Otomatik olarak yeniden denemeyin. Migrasyon günlüklerini inceleyin, sorunu düzeltin, ardından yeniden deneyin veya geri alın. Bkz. Güncelleme ve Geri Alma.
Kirli Depo (Çıkış Kodu 15)¶
Dağıtım dizini beklenmeyen değişiklikler içeriyor. Güncelleme betiği kaynak tabanlı dağıtımlarda git pull --ff-only kullanır ve çalışma dizininde commit edilmemiş değişiklikler varsa işlemi reddeder. Asla git reset --hard kullanmayın — çakışmayı elle çözün.
Çevrimdışı Kurulum¶
İnternet erişimi olmayan ortamlar için:
- Sürüm arşivini internet erişimi olan bir makinede indirin.
- Arşivi güvenli bir ortam aracılığıyla hedef sunucuya aktarın.
- Arşivi çıkartın ve kurulum betiğini yukarıda belgelendiği şekilde çalıştırın.
- MongoDB'nin hedef sunucudan erişilebilir olduğundan emin olun.
Sağlık Kontrolleri¶
Dağıtım başarılı sayılmadan önce hem canlılık hem hazırlık kontrolleri geçmelidir:
| Uç Nokta | Amaç |
|---|---|
GET /health/live |
İşlem hayatta |
GET /health/ready |
İşlem hayatta ve MongoDB erişilebilir |
Kurulum ve güncelleme betikleri her iki uç noktayı da otomatik olarak doğrular. Her iki kontrol de geçmedikçe başarı bildirmeyin.