Yükleyici doğrulama matrisi¶
Bu belge, Windows Native Service yükleyicisinin (scripts/windows/service/install.ps1 + Common.ps1) gerçekten yaptığı kontrolleri ve bileşen etkilerini özetler.
Scriptte olmayan kontrol uydurulmaz.
Kanıt durumu:
| Platform | Live E2E |
|---|---|
| Windows Native Service | PASS (Windows lab, Ağustos 2026) — ayrıntı: Windows Service E2E |
| Ubuntu systemd | NOT E2E VALIDATED |
| Linux / Windows Docker | NOT E2E VALIDATED |
İlgili: Test stratejisi, Güncelleme ve geri alma, Windows servis kurulumu.
Çıkış kodları (özet)¶
| Kod | Anlam |
|---|---|
| 0 | Başarı |
| 1 | Yönetici gerekli |
| 2 | Ortam geçersiz |
| 3 | Ön gereksinim |
| 4 | Depo kirli / git |
| 5 | Bağımlılık indirme |
| 6 | Vet/test |
| 7 | Derleme |
| 8 | Application check |
| 9 | Yedek |
| 10 | Migrasyon |
| 11 | Servis güncelleme |
| 12 | Firewall |
| 13 | Health |
| 14 | Rollback başarısız |
| 15 | Port çakışması (EXIT_PORT_CONFLICT / Linux EXIT_PORT) |
| 16 | Docker N/A |
| 17 | systemd N/A |
Doğrulama adımları (Windows install)¶
| Step | Validation | How | Success Criterion | Failure Behavior | Exit Code | Mutates System? | Rollback Required? | Windows | Linux | Docker |
|---|---|---|---|---|---|---|---|---|---|---|
| 1 | Administrator | Assert-Administrator |
Elevated token | Abort | 1 | No | No | Yes | root (1) | Varies |
| 2 | OS / architecture | Assert-WindowsAmd64 |
Windows AMD64 | Abort | 3 | No | No | Yes | arch check | Host OS |
| 3 | Repository root | Get-RepoRoot / go.mod |
Repo bulundu | Abort | 3 | No | No | Yes | Yes | Yes |
| 4 | Env existence | Assert-EnvFileExists |
.env mevcut |
Abort | 2 | No | No | Yes | Yes | Yes |
| 5 | Configuration readable | Port/env read | Geçerli HTTP_PORT vb. |
Abort | 2 | No | No | Yes | Yes | Yes |
| 6 | Git | Ensure-GitAndGo |
git PATH’te |
Abort veya winget install | 3 | Maybe (winget) | No | Yes | Yes | Optional |
| 7 | Go | Ensure-GitAndGo |
go PATH’te |
Abort veya winget install | 3 | Maybe (winget) | No | Yes | Yes | Image build |
| 8 | Runtime state | Path inspection | present/absent rapor | Continue | — | No | No | Yes | Yes | Compose state |
| 9 | Service state | Get-Service |
Scenario seçimi | Continue | — | No | No | Yes | systemd | containers |
| 10 | Scenario | Get-IQVInstallScenario |
CleanInstall / PreservedRuntimeReinstall / ServiceRepair | Continue | — | No | No | Yes | Analog | Analog |
| 11 | MongoDB service | Assert-MongoServiceAndPort |
Service Running | Abort | 3 | No | No | Yes | External check | External/bundled |
| 12 | MongoDB port | TCP 27017 Listen | Listening | Abort | 3 | No | No | Yes | Yes | Network |
| 13 | HTTP port ownership | Assert-IQVHttpPortForInstall |
Free veya own SCM PID (ServiceRepair) | Abort on foreign | 15 | No | No | Yes | MainPID | Managed mapping |
| 14 | Dependencies | go mod download / verify |
Exit 0 | Abort | 5 | Module cache | No | Yes | Yes | Build |
| 15 | Vet | go vet ./... |
Exit 0 | Abort | 6 | No | No | Yes | Yes | Optional |
| 16 | Tests | go test ./... -count=1 (unless -SkipTests) |
Exit 0 | Abort | 6 | No | No | Yes | Yes | Optional |
| 17 | Build | go build |
Binary üretildi | Abort | 7 | Temp binary | No | Yes | Yes | Image |
| 18 | Application check | Binary check |
Exit 0 | Abort | 8 | No | No | Yes | Yes | Health later |
| 19 | Backup | Runtime backup (varsa) | Backup dir | Abort | 9 | Yes | Snapshot | Yes | Yes | Image tag |
| 20 | Stop / port release | Stop service; wait port | Port released | Fail path | 11/15 | Yes | Yes (txn) | Yes | Yes | compose |
| 21 | Binary deploy | Copy to runtime | Binary yerinde | Txn fail → recover | 11 | Yes | Yes | Yes | Yes | recreate |
| 22 | Config preserve/copy | Preserve default; copy on CleanInstall; -ReplaceRuntimeConfig |
Hash/policy | Txn fail → recover | 2/11 | Yes (CleanInstall) | Yes | Yes | preserve-if-exists | .env touch yok |
| 23 | Migration | App migrate (unless skip) | Exit 0 | Abort; DB rollback yok | 10 | Yes (DB) | No DB rollback | Yes | Yes | Yes |
| 24 | Service registration | service install CreateService/argv |
Registered | Txn recover | 11 | Yes | Yes | Yes | unit write | compose |
| 25 | Delayed start | Automatic Delayed | Configured | Txn recover | 11 | Yes | Yes | Yes | enable | restart policy |
| 26 | DB dependency | Depends on MongoDB service | Set | Txn recover | 11 | Yes | Yes | Yes | After= | depends_on |
| 27 | Recovery | 5s/10s/30s; reset 86400 | Set | Txn recover | 11 | Yes | Yes | Yes | Restart= | — |
| 28 | Firewall | Domain+Private rule (unless skip) | Rule present (idempotent) | Abort | 12 | Yes | Best-effort | Yes | Optional | Optional |
| 29 | Service start | Start-Service | Running | Txn recover | 11 | Yes | Yes | Yes | systemctl | up |
| 30 | Health | /health/live + /health/ready |
HTTP healthy | Fail → recover / exit 13 | 13 | No | Yes | Yes | Yes | Yes |
| 31 | Metadata | deployment metadata write | Written only on success path | Fail path does not mark success | 11 | Yes | Preserve failed state | Yes | Yes | Yes |
Linux/Docker sütunları IMPLEMENTED davranış analojisidir; canlı E2E için NOT E2E VALIDATED.
Bileşen: kontrol / kurulum / değişiklik¶
| Component | Checked | Installed Automatically | Modified | Preserved | Removed on Uninstall | Notes |
|---|---|---|---|---|---|---|
| Go | Yes | Yes via winget unless -SkipPrerequisiteInstall |
PATH may refresh | N/A | No | GoLang.Go |
| Git | Yes | Yes via winget unless -SkipPrerequisiteInstall |
PATH may refresh | N/A | No | Git.Git |
| MongoDB | Yes (service + port) | No — otomatik kurulmaz | No | Untouched | No | Önceden Running olmalı |
| Go modules | download/verify | Module cache | Cache | N/A | No | |
| Binary | After build | Deployed to runtime bin\ |
Replaced on deploy | Kept on safe uninstall | Only with -RemoveRuntime |
|
.env / runtime config |
Exists + validate | CleanInstall: copy source → runtime | Only CleanInstall or -ReplaceRuntimeConfig |
Default preserve (PreservedRuntimeReinstall / ServiceRepair / update) | Only with -RemoveRuntime |
Self-copy korunur |
| Windows service | Present/absent | Create / repair | ImagePath/account/recovery | N/A | Yes (unregister) | Duplicate create yok |
| Firewall | Rule count / presence | Create if missing | Idempotent | N/A | Yes (rule removed) | Domain+Private |
| Backups | Directory | Created on mutate paths | New stamp on real update | Yes on safe uninstall | Only -RemoveRuntime |
|
| Logs | Directory | Created | Appended by app | Yes on safe uninstall | -RemoveLogs / -RemoveRuntime |
|
| Deployment metadata | Written on success | Created | Updated on success deploy | Yes on safe uninstall | -RemoveRuntime |
Secrets yok |
| MongoDB collections | Via migration | Migrations apply | Schema/data per migrate | Uninstall dokunmaz | No | Migration rollback yok |
| Docker | N/A (native path) | No | No | — | — | Ayrı dağıtım |
| systemd unit | N/A (Windows) | Linux path | Linux writes unit | — | Linux uninstall | NOT E2E VALIDATED |
Ön gereksinim notu¶
- MongoDB otomatik kurulmaz. Yükleyici yalnızca Windows servisinin Running olduğunu ve TCP 27017’nin dinlediğini doğrular; yoksa çıkış 3.
- Go / Git: Eksikse ve
-SkipPrerequisiteInstallyoksawingetile kurulmaya çalışılır.-SkipPrerequisiteInstallvarken eksik araç → çıkış 3.
Live E2E notu¶
Windows Native Service için lab E2E sonuçları PASS olarak windows-service-e2e.md içinde belgelenmiştir (45 madde; reboot, NO-OP, ForceRedeploy, rollback exit 11, preserved reinstall, ServiceRepair port ownership, step counter 29/29).
Linux systemd ve Docker için karşılık gelen canlı senaryolar NOT E2E VALIDATED: linux-systemd-e2e.md, docker-e2e.md, known-untested-scenarios.md.