Güncelleme ve Geri Alma¶
Bu belge, IQV Integration API'yi yeni bir sürüme güncelleme ve gerektiğinde önceki sürüme geri alma prosedürlerini açıklar.
flowchart TD
pre[Ön kontrol: kimlik, SHA, port, actor formatı] --> snap[Anlık görüntü / yedek]
snap --> chk[check]
chk --> mig[migrate yalnız ileri]
mig --> dep[Binary veya compose yayın]
dep --> hl[health live + ready]
hl -->|geçti| ok[Başarı metadata yaz]
hl -->|kaldı| rb[Anlık görüntüyü geri yükle]
rb --> hl2[health tekrar]
hl2 --> fail[Sıfır olmayan çıkış — DB geri alınmaz]Üretim Dağıtım Önerileri¶
| Platform | Önerilen Yöntem |
|---|---|
| Windows | Yerel Windows Servisi |
| Linux | systemd veya Docker |
Docker, yerel işletim sistemi servislerinden ayrı bir dağıtım türüdür. Güncelleme prosedürleri dağıtım yöntemine göre farklılık gösterir.
Güncelleme Karar Modeli¶
Güncelleme kararı yalnız local HEAD'e bakılarak verilmez. Üç commit kavramı ayrılır:
| Kavram | Anlam |
|---|---|
CurrentRepositoryCommit |
Yerel depo HEAD |
TargetCommit |
Normal mod: git fetch sonrası origin/<Branch>. -SkipGitPull / --skip-git-pull ile: yerel HEAD |
DeployedCommit |
Runtime deployment metadata içindeki commit (commit / git_commit / image tag). Metadata yoksa: unknown |
Karar matrisi¶
| Deployed | Target | Bayraklar | Eylem |
|---|---|---|---|
abc |
abc |
(yok) | NO-OP (çıkış 0) |
abc |
def |
(yok) | UPDATE |
unknown |
def |
(yok) | UPDATE (uyarı: metadata yok) |
def |
def |
-ForceRedeploy / --force-redeploy |
REDEPLOY (tam pipeline) |
NO-OP davranışı¶
DeployedCommit == TargetCommit ve force-redeploy yoksa güncelleyici başarıyla çıkar ve şunların hiçbirini yapmaz: go mod / vet / test / build, application check, backup, migration, servis stop/swap/restart, firewall, config kopyası, metadata yazımı, Docker rebuild / compose recreate / container restart.
NO-OP başarılı bir güncelleme sonucudur (çıkış kodu 0).
Runtime config koruma (update)¶
| İşlem | Config davranışı |
|---|---|
| Install | Kaynak .env → runtime config\.env |
| Update (varsayılan) | Mevcut runtime C:\IQVizyon\IQVIntegrationAPI\config\.env korunur |
| Self-copy | Kaynak == runtime ise Copy-Item atlanır |
| ForceRedeploy | Yalnız pipeline zorlar; config overwrite yok |
Transactional rollback¶
Pre-deployment hataları: runtime dokunulmaz.
Transaction sınırı: başarılı pre-update backup sonrası (service stop öncesi).
Bu sınırdan sonraki hatalarda (stop/swap/migration/start/live/ready) otomatik rollback ( -NoRollback yoksa): binary+config+metadata restore, service start, live+ready. Rollback başarılı olsa bile update exit code failure kalır. MongoDB migration geri alınmaz.
Lab-only (Windows native): -TestFailAt AfterBinarySwap vb. açık parametre ile rollback E2E testi.
Lab-only (Windows/Linux Docker): -TestFailAt AfterComposeUp / --test-fail-at AfterComposeUp. Runtime image mutation öncesi çalışan API image ID snapshot (rollback-<id>-<timestamp>); same-tag ForceRedeploy güvenli. MongoDB rollback edilmez. Başarılı rollback sonrası update yine non-zero. Windows Docker kontrollü rollback: RETEST REQUIRED.
Backup kuralı¶
Runtime backup yalnız gerçek deployment yapılacaksa ve yalnız build/check başarısından sonra, servis durdurulmadan hemen önce oluşturulur. Test/build başarısızsa gereksiz backup alınmaz. NO-OP yedek oluşturmaz.
Force redeploy¶
Windows: -ForceRedeploy. Linux: --force-redeploy. Çıktı: [WARN] Force redeploy requested for already deployed commit. Üretim varsayılanı değildir.
Skip git pull ve dirty tree¶
-SkipGitPull / --skip-git-pull → TargetCommit = local HEAD, ardından yine Deployed ile karşılaştırılır. Lab aynı commit yeniden kurulumu: force-redeploy ile birlikte.
-SkipGitPull tek başına dirty tree korumasını kaldırmaz. -AllowDirty / --allow-dirty kullanın (eski -Force / --force takma addır). İzin verilirse: [WARN] Dirty working tree deployment explicitly allowed. ve metadata source_dirty: true yazabilir. Üretim normal güncellemede source_dirty: false.
Git fail-safe senaryoları¶
| Senaryo | Sonuç |
|---|---|
| Deployed == Target | NO-OP |
| Deployed != Target, local geride, fast-forward mümkün | git pull --ff-only sonra deploy |
| Local HEAD == Target, Deployed eski | Pull gerekmeden deployment pipeline |
| Local remote'tan ileri | Durdur (reset yok) |
| Local ve remote diverged | Durdur (reset yok) |
| Metadata yok | Uyarı + update gerekli |
Betikler asla git reset --hard veya force checkout çalıştırmaz.
Runtime deployment metadata¶
Windows native: C:\IQVizyon\IQVIntegrationAPI\deployment\deployment.json
Minimum alanlar (secret yok): deployment_type, commit, version, build_date_utc, deployed_at_utc, source_dirty.
Windows config path standardı¶
Kanonik runtime config: C:\IQVizyon\IQVIntegrationAPI\config\.env
Yanlış düz yol C:\IQVizyon\IQVIntegrationAPI\config.env kullanılmamalı ve gösterilmemelidir.
Güncelleme Öncesi Kontrol Listesi¶
Herhangi bir güncellemeden önce:
- [ ] Mevcut servisin çalıştığını ve sağlıklı olduğunu doğrulayın (
/health/liveve/health/readyHTTP 200 döndürmelidir). - [ ] Hedef sürüm için sürüm notlarını ve CHANGELOG'u inceleyin.
- [ ] MongoDB'nin erişilebilir ve sağlıklı olduğunu onaylayın.
- [ ] Güncelleme veritabanı migrasyonları içeriyorsa bakım penceresi planlayın.
- [ ] Geri alma için önceki sürüm arşivine erişiminiz olduğundan emin olun.
Warning
MongoDB yedekleme, uygulama kurulum betiğinin yedekleme sürecinin bir parçası değildir. MongoDB verilerini yedeklemek ayrı bir operasyonel sorumluluktur. Özellikle veritabanı migrasyonları içeren büyük güncellemelerden önce veritabanı operasyon ekibinizle koordine ederek MongoDB yedeklemesi yapın.
Güncelleme Prosedürleri¶
Windows Servisi Güncelleme¶
powershell
powershell.exe -ExecutionPolicy Bypass -File .\scripts\windows\service\update.ps1
Deployed vs Target çözülür (güncel ise NO-OP); gerektiğinde git sync; build/test; yalnız başarılı build/check sonrası backup; stop/swap/migrate/start/health; deployment.json yazımı.
Linux systemd Güncelleme (üretim: prebuilt binary)¶
bash
sudo ./scripts/update.sh --binary-path ./bin/iqv-integration-api
Production Linux native git pull / go build çalıştırmaz. Aynı SHA256 → NO-OP; --force-redeploy zorlar. Canonical runtime env (INTEGRATION_ACTOR_USER_ID dahil) korunur ve rastgele değiştirilmez. Swap sonrası salt okunur check aktörün var ve aktif olduğunu doğrular; başarısızlık uygulama rollback’ine girer. Database rollback: NOT PERFORMED.
Docker Güncelleme¶
Windows¶
powershell
powershell.exe -ExecutionPolicy Bypass -File .\scripts\windows\docker\update.ps1
Linux¶
bash
sudo bash ./scripts/linux/docker/update.sh
Hedef imaj: iqv-integration-api:<target-short-sha>. Deployed commit hedef ile aynıysa NO-OP (force-redeploy yoksa).
Kaynak Tabanlı Güncellemeler¶
text
git fetch origin
git pull --ff-only # yalnız local target'ın gerisindeyse
Local zaten target ile aynıysa pull atlanabilir; Deployed eskiyse deployment yine çalışır.
Danger
Güncelleme betikleri asla git reset --hard kullanmaz. Fast-forward mümkün değilse (ahead/diverged/dirty ve -AllowDirty yok) güncelleme durur. Çakışmayı elle çözün. Üretimde asla force-reset yapmayın.
Yedek Yapısı¶
Windows¶
text
C:\IQVizyon\IQVIntegrationAPI\backups\
YYYY-MM-DD_HH-MM-SS\
bin\ # Önceki ikili
config\ # Önceki yapılandırma
deployment\ # Önceki dağıtım meta verileri
Linux¶
text
/var/lib/iqvizyon/iqv-integration-api/backups/
YYYY-MM-DD_HH-MM-SS/
bin/ # Önceki ikili
deployment/ # Önceki dağıtım meta verileri
Note
Uygulama yedekleri ikili dosyayı, yapılandırma meta verilerini ve dağıtım durumunu içerir. MongoDB verilerini içermezler. NO-OP güncellemeler yedek oluşturmaz.
Geri Alma Prosedürleri¶
Windows Servisi Geri Alma¶
-
Mevcut servisi durdurun:
powershell Stop-Service IQVIntegrationAPI -
Geri yüklenecek yedeği belirleyin:
powershell Get-ChildItem C:\IQVizyon\IQVIntegrationAPI\backups\ -
Mevcut ikili dosyayı yedeklenen sürümle değiştirin:
powershell Copy-Item C:\IQVizyon\IQVIntegrationAPI\backups\<timestamp>\bin\* C:\IQVizyon\IQVIntegrationAPI\bin\ -Force -
Servisi başlatın:
powershell Start-Service IQVIntegrationAPI -
Sağlığı doğrulayın:
powershell Invoke-RestMethod http://localhost:8080/health/live Invoke-RestMethod http://localhost:8080/health/ready
Linux systemd Geri Alma¶
-
Mevcut servisi durdurun:
bash sudo systemctl stop iqv-integration-api.service -
Geri yüklenecek yedeği belirleyin:
bash ls /var/lib/iqvizyon/iqv-integration-api/backups/ -
Mevcut ikili dosyayı yedeklenen sürümle değiştirin:
bash sudo cp /var/lib/iqvizyon/iqv-integration-api/backups/<timestamp>/bin/* /opt/iqvizyon/iqv-integration-api/bin/ -
Servisi başlatın:
bash sudo systemctl start iqv-integration-api.service -
Sağlığı doğrulayın:
bash curl -s http://localhost:8080/health/live curl -s http://localhost:8080/health/ready
Linux Docker Geri Alma (offline üretim)¶
Müşteri sunucusunda git checkout veya docker compose up --build yapılmaz.
update.sh mutation öncesi çalışan API image’ını (iqv-integration-api:rollback-<id>-<timestamp>) snapshot’lar. live/ready FAIL olursa:
- Önceki immutable image geri yüklenir.
- Compose
--no-buildile ayağa kalkar. - Başarısız sürüm metadata’sı yazılmaz.
- Orijinal non-zero exit kodu döner.
- Database rollback: NOT PERFORMED. Harici MongoDB değiştirilmez.
Aynı image digest/ID ve --force-redeploy yoksa NO-OP (container restart yok).
Opsiyonel auto-update doğrulanmış artifact sonrası aynı update.sh yolunu kullanır. Auto-update git pull değildir.
Windows / lab Docker Geri Alma¶
Windows Docker mevcut snapshot + -TestFailAt AfterComposeUp yolunu kullanır. Live durum: RETEST REQUIRED.
Migrasyon Hatası Kurtarma¶
Veritabanı migrasyonu başarısız olursa (çıkış kodu 14):
- Güncellemeyi otomatik olarak yeniden denemeyin.
- Migrasyon günlüklerini tam hata için inceleyin.
- Migrasyonun kısmen uygulanıp uygulanmadığını belirleyin.
- Kısmen uygulandıysa, elle düzeltme adımları için sürüm notlarına başvurun.
- İkili dosyayı önceki sürüme geri alın.
- Migrasyon güvenli bir şekilde geri alınamıyorsa geliştirme ekibiyle iletişime geçin.
Veri Bütünlüğü
Migrasyon hatasını aşmak için koleksiyonları asla truncate etmeyin, drop etmeyin veya zorla değiştirmeyin. Başarısız migrasyonlar verileri dikkatli elle çözüm gerektiren ara durumda bırakabilir.
MongoDB Yedekleme (Ayrı Operasyonel Sorumluluk)¶
MongoDB yedekleme, uygulama kurulum veya güncelleme betikleri tarafından yönetilmez. Veritabanı operasyon ekibinizin sorumluluğundadır.
Önerilen uygulamalar:
- Veritabanı migrasyonları içeren herhangi bir güncellemeden önce MongoDB yedeklemesi yapın.
mongodumpveya kuruluşunuzun standart yedekleme aracını kullanın.- Yedekleri uygulama sunucusundan ayrı güvenli bir konumda saklayın.
- Yedek geri yüklemesini periyodik olarak test edin.
- MongoDB yedekleme programınızı ve saklama politikanızı belgelendirin.
bash
mongodump --uri="mongodb://localhost:27017/iqv_integration" --out=/backup/path/
Warning
Uygulama kaldırma sırasında MongoDB verilerini asla silmeyin. Kaldırma betiği MongoDB'ye dokunmaz — bu şekilde tutun.
Sağlık Kontrolü Gereksinimleri¶
Güncelleme 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 |
Güncellemeden sonra herhangi bir kontrol başarısız olursa güncelleme başarılı olmamıştır. Hatayı araştırın veya geri alın.
Windows E2E kabul matrisi (lab)¶
Kanıt: Windows lab, Ağustos 2026. Ayrıntı: Windows Service E2E.
| Senaryo | Durum |
|---|---|
| Clean Install | PASS |
| Reboot Auto Start | PASS |
| NO-OP Update | PASS |
| ForceRedeploy | PASS |
| Config Preserve Update | PASS |
| Automatic Update Rollback | PASS |
| Rollback Exit Code | PASS (başarısız update + başarılı rollback → exit 11, 0 değil) |
| Status | PASS |
| Uninstall Preserve Runtime | PASS |
| Preserved Runtime Reinstall | PASS |
| ServiceRepair / Existing Listener Ownership | PASS |
| Firewall idempotency | PASS |
Step counter [1/29]…[29/29] |
PASS |
Linux systemd: offline kurulum / reboot / NO-OP LIVE PASS; inbound POST RETEST REQUIRED. Linux Docker offline image: IMPLEMENTED / AUTOMATED TESTED / LIVE E2E RETEST REQUIRED.
Çıkış Kodları Referansı¶
| 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 |
Kaldırma Hatırlatması¶
Kaldırırken:
- Kaldırma betiği uygulama ikili dosyasını, servis kaydını ve uygulama dizinlerini kaldırır.
- Kaldırma betiği MongoDB verilerini asla silmez.
.envdosyası kaldırma betiğine bağlı olarak kaldırılabilir veya kaldırılmayabilir — yapılandırmanızın güvenli bir kopyasını her zaman saklayın.- Kaldırma sonrasında MongoDB bağımsız olarak çalışmaya devam eder.