Script deploy có backup, rollback và test: để deploy lúc 5 giờ chiều thứ Sáu không còn đáng sợ
Cách deploy một API lên IIS dễ nhất là một lệnh copy: lấy thư mục trong artifact, chép đè lên C:\inetpub\wwwroot\apps. Chạy được, cho tới khi bạn nhớ ra trong thư mục đó có App_Data, nơi app lưu cấu hình mà admin bên khách đã nhập tay (tenant, client ID, khoá khôi phục). Chép đè một lần là bản trống trong artifact thay thế toàn bộ, và trang quản trị của khách trở về trạng thái mới cài.
Team mình thay lệnh copy đó bằng một script PowerShell, chạy trên chính máy đích bởi agent tự host (đã nói ở bài trước). Phần mình làm là cho script cài được trên một máy trắng, và chính ở đó mình gặp hai lỗi đáng kể nhất trong bài. Bài này đi theo đúng thứ tự một lần deploy, từ lúc script nhận artifact tới lúc kiểm app sống, mỗi bước kèm lý do. Cuối bài là cách test một script đụng vào IIS mà không cần IIS.
1. Kiểm artifact đủ file ← chưa đụng gì vào máy
2. Kiểm máy đủ điều kiện ← runtime, IIS module, site tồn tại
3. Tạo hoặc sửa app pool, app ← chạy lại bao nhiêu lần cũng ra cùng kết quả
4. Backup thư mục hiện tại
5. Dừng app pool, chờ dừng hẳn
6. Copy bản mới, BỎ QUA file thuộc về máy
7. Merge appsettings theo từng khoá
8. Xoá file bản mới không còn
9. Khởi động, gọi /health
Lỗi ở 6–9 → restore từ backup, ném lại lỗi
1. Kiểm artifact trước khi đụng vào máy
function Test-ArtifactShape {
# Trả về danh sách file bản deploy cần mà artifact thiếu; rỗng nghĩa là deploy được
param([Parameter(Mandatory)] [string] $Source)
$required = @('web.config', 'App.Api.dll', 'appsettings.Production.json', 'wwwroot\index.html')
return @($required | Where-Object { -not (Test-Path -LiteralPath (Join-Path $Source $_)) })
}
$missing = @(Test-ArtifactShape -Source $source)
if ($missing.Count -gt 0) { throw "Artifact thiếu: $($missing -join ', ')" }
if ($CheckOnly) { Write-Host "Artifact đủ file."; return }
Pipeline gọi script với -CheckOnly ở một bước riêng, trước mọi bước làm thay đổi máy. Build đã kiểm một lần rồi, nhưng một lần deploy có thể chạy lại với artifact cũ hơn, hoặc artifact của một lần build chỉ build một phần app. Thiếu một file HTML là cả trang đặt hàng thành trang trắng cho mọi khách.
2. Kiểm máy, và dừng trước khi tạo bất cứ thứ gì
function Test-Prerequisites {
Import-Module WebAdministration -ErrorAction Stop
if (-not (Get-WebGlobalModule | Where-Object Name -eq 'AspNetCoreModuleV2')) {
throw "IIS chưa có AspNetCoreModuleV2. Cài ASP.NET Core Hosting Bundle rồi chạy lại."
}
if (-not (& dotnet --list-runtimes | Where-Object { $_ -match '^Microsoft\.AspNetCore\.App 10\.' })) {
throw "Máy chưa có runtime ASP.NET Core 10."
}
if (-not (Get-Website | Where-Object Name -eq $SiteName)) {
throw "IIS không có site '$SiteName'. Tạo hoặc khôi phục site rồi chạy lại."
}
}
Dòng kiểm site là một commit riêng của mình. Trước đó, máy thiếu site thì script chỉ lỗi ở lệnh New-WebApplication gần cuối, sau khi đã tạo app pool và thư mục rỗng. Lần chạy lại sau đó gặp một máy "cài dở", khó đoán hơn máy trắng. Quy tắc rút ra: kiểm mọi điều kiện trước, rồi mới tạo thứ đầu tiên.
Thông báo lỗi nói luôn cách sửa ("Cài ASP.NET Core Hosting Bundle"), vì người đọc nó lúc 5 giờ chiều không muốn đi tra lỗi.
3. Tạo app pool và app: chạy lại bao nhiêu lần cũng được
Script phải idempotent: chạy lần đầu trên máy trắng hay lần thứ mười trên máy đã cài, kết quả như nhau.
$poolPath = "IIS:\AppPools\$AppPoolName"
if (-not (Test-Path $poolPath)) {
New-WebAppPool -Name $AppPoolName | Out-Null
Set-ItemProperty $poolPath -Name managedRuntimeVersion -Value '' # No Managed Code cho ASP.NET Core
Set-ItemProperty $poolPath -Name startMode -Value 'AlwaysRunning'
Set-ItemProperty $poolPath -Name processModel.loadUserProfile -Value $true
}
# App ghi App_Data lúc khởi động: thiếu quyền Modify là chết với lỗi 500.30
& icacls $WebTarget /grant "IIS AppPool\${AppPoolName}:(OI)(CI)M" /T /Q | Out-Null
if ($LASTEXITCODE -ne 0) { throw "icacls không cấp được quyền cho app pool." }
# KHÔNG dùng Test-Path "IIS:\Sites\$SiteName\$AppName" ở đây
if (-not (Get-WebApplication -Site $SiteName -Name $AppName)) {
New-WebApplication -Site $SiteName -Name $AppName -PhysicalPath $WebTarget -ApplicationPool $AppPoolName | Out-Null
}
Hai lỗi thật nằm trong đoạn này, cả hai chỉ lộ ra khi mình cài thử trên một máy trắng:
Test-Pathtrên ổIIS:trả$truecho một thư mục thường. Script vừa tạo thư mụcC:\inetpub\wwwroot\appsở trên, và vì thư mục đó nằm dưới gốc của site,Test-Path "IIS:\Sites\Default Web Site\apps"trả về đúng. Script tưởng app đã có, không bao giờ tạo. Trên máy đã cài thì không sao, nên lỗi này sống được tới lần cài mới đầu tiên.Get-WebApplicationhỏi đúng câu hỏi: đây có phải một application của IIS không.- Lỗi 500.30 "Access to the path ... App_Data is denied". App tự tạo
App_Datalúc khởi động. Danh tính của app pool (IIS AppPool\<tên pool>) mặc định không có quyền ghi vào thư mục web.icaclscấp quyền Modify,(OI)(CI)để file và thư mục con tạo sau cũng được kế thừa.
4 và 5. Backup, rồi dừng app pool cho đàng hoàng
$stamp = (Get-Date -Format 'yyyyMMdd-HHmmss') + "-$env:BUILD_BUILDID"
$backup = Join-Path "$WebTarget.backup" $stamp
Copy-Item -Path (Join-Path $WebTarget '*') -Destination (New-Item -ItemType Directory $backup -Force) -Recurse -Force
# Giữ hai bản gần nhất, ổ đĩa không phải vô hạn
Get-ChildItem "$WebTarget.backup" -Directory | Sort-Object LastWriteTime -Descending |
Select-Object -Skip 2 | Remove-Item -Recurse -Force
Stop-WebAppPool -Name $AppPoolName
$deadline = (Get-Date).AddSeconds(120)
while ((Get-WebAppPoolState -Name $AppPoolName).Value -ne 'Stopped') {
if ((Get-Date) -gt $deadline) { throw "App pool không dừng trong 120 giây." }
Start-Sleep -Seconds 2
}
Tên thư mục backup dùng thời gian cộng ID lần chạy, không dùng số phiên bản: lần chạy được đặt tên theo bản nó sắp cài, mà thư mục backup thì chứa bản bị thay. Đặt tên theo version là thư mục 1.8.3 chứa code của 1.8.2.
Stop-WebAppPool chỉ gửi yêu cầu dừng rồi trả về ngay. Copy file khi process cũ còn giữ khoá DLL là lỗi "file is being used by another process" ngẫu nhiên. Vòng chờ có giới hạn thời gian để không treo mãi. (ASP.NET Core còn cách khác là thả file app_offline.htm vào thư mục để module tự tắt app, hợp khi bạn không muốn dừng cả pool.)
6. Copy bản mới, nhưng không đụng vào thứ thuộc về máy
Đây là bước chặn đúng chuyện đầu bài:
# Regex trên đường dẫn tương đối; khớp là không bao giờ ghi đè hay xoá
$PreservedPaths = @('^App_Data(\\|$)', '^recovery-key\.txt$')
foreach ($item in Get-ChildItem -LiteralPath $source -Recurse -Force -File) {
$rel = $item.FullName.Substring($source.Length).TrimStart('\')
if ($rel -ieq 'appsettings.Production.json') { continue } # merge ở bước 7
$isPreserved = $PreservedPaths | Where-Object { $rel -match $_ }
if ($isPreserved -and (Test-Path (Join-Path $WebTarget $rel))) { continue }
$dest = Join-Path $WebTarget $rel
New-Item -ItemType Directory -Path (Split-Path $dest) -Force | Out-Null
Copy-Item -LiteralPath $item.FullName -Destination $dest -Force
}
Để ý điều kiện -and (Test-Path ...): file được giữ chỉ khi máy đã có nó. Máy trắng chưa có thì vẫn copy từ artifact, để lần cài đầu có cấu hình mặc định. Kèm theo, bước build được sửa để không bao giờ đóng gói App_Data hay file khoá từ máy build vào artifact.
7. Merge appsettings theo từng khoá
Chép đè appsettings.Production.json là mất chuỗi kết nối, URL mà người cài đã sửa trên máy đó. Không chép thì bản mới thêm khoá cấu hình nào, máy cũ không có khoá đó. Quy tắc merge:
| Trường hợp | Làm gì |
|---|---|
| Máy chưa có file | Copy nguyên file từ artifact |
| Khoá có trong bản mới, máy chưa có | Thêm vào, in ra "+ tên khoá" |
| Khoá có ở cả hai | Giữ giá trị của máy, kể cả khi rỗng |
| Khoá chỉ có trên máy | Giữ, nhưng in cảnh báo |
Dòng cuối quan trọng hơn vẻ ngoài: nếu dev đổi tên một khoá, máy cũ có khoá tên cũ (giá trị thật) và nhận thêm khoá tên mới (giá trị mặc định, thường rỗng). App đọc khoá mới, thấy rỗng. Cảnh báo "khoá chỉ có trên máy" là dấu hiệu để người deploy nhận ra một lần đổi tên.
8 và 9. Dọn file thừa, khởi động, kiểm sức khoẻ, và restore khi lỗi
try {
# ... bước 6, 7, và xoá file bản mới không mang theo (trừ file được giữ)
Start-WebAppPool -Name $AppPoolName
$ok = $false
foreach ($i in 1..10) {
try { if ((Invoke-WebRequest $HealthUrl -UseBasicParsing -TimeoutSec 10).StatusCode -eq 200) { $ok = $true; break } } catch {}
Start-Sleep -Seconds 3
}
if (-not $ok) { throw "Health check $HealthUrl không trả 200." }
}
catch {
Write-Warning "Deploy lỗi, khôi phục từ $backup"
Stop-WebAppPool -Name $AppPoolName -ErrorAction SilentlyContinue
# robocopy /MIR: làm thư mục đích giống hệt backup; bị ngắt giữa chừng vẫn còn nội dung backup
& robocopy $backup $WebTarget /MIR /R:3 /W:5 /NFL /NDL /NP | Out-Null
if ($LASTEXITCODE -ge 8) { Write-Error "robocopy lỗi khi khôi phục, mã $LASTEXITCODE" }
Start-WebAppPool -Name $AppPoolName
throw # ném lại lỗi gốc để pipeline đỏ
}
Ba chi tiết:
- Health check gọi nhiều lần. App ASP.NET Core cần vài giây khởi động. Gọi một lần ngay sau
Startlà đỏ oan. - Restore bằng
robocopy /MIR, không phải xoá rồi copy. Bản trước của team dùng xoá thư mục đích rồi copy backup vào; một lần bị ngắt giữa chừng trên một máy test, máy còn lại thư mục gần trống./MIRđồng bộ thẳng, ngắt ở đâu thì nội dung backup vẫn còn đó. Nhớ làrobocopytrả mã 0–7 khi thành công, từ 8 trở lên mới là lỗi. throwcuối khốicatch. Khôi phục xong mà nuốt lỗi thì pipeline xanh, ai cũng tưởng bản mới đã lên.
Test một script đụng vào IIS mà không cần IIS
Script Import-Module WebAdministration ngay đầu và gọi lệnh IIS khắp nơi, không chạy được trên máy dev hay agent build. Mẹo của team: nhấc từng hàm ra khỏi file bằng parser của PowerShell, khai báo lại trong file test, rồi test hàm đó với thư mục tạm. Phần chính của script không bao giờ chạy.
# deploy-app.Tests.ps1 (Pester)
$script:Path = Join-Path $PSScriptRoot 'deploy-app.ps1'
$ast = [System.Management.Automation.Language.Parser]::ParseFile($script:Path, [ref]$null, [ref]$null)
foreach ($name in 'Test-ArtifactShape', 'Merge-AppSettings') {
$fn = $ast.FindAll({ param($n) $n -is [System.Management.Automation.Language.FunctionDefinitionAst] }, $true) |
Where-Object Name -eq $name | Select-Object -First 1
if (-not $fn) { throw "Script không còn hàm $name" }
. ([scriptblock]::Create($fn.Extent.Text))
}
Describe 'Merge-AppSettings' {
It 'giữ giá trị của máy và thêm khoá mới của bản phát hành' {
$dir = New-Item -ItemType Directory (Join-Path $env:TEMP ([guid]::NewGuid()))
'{ "Url": "https://may-khach", "Old": 1 }' | Set-Content "$dir\target.json"
'{ "Url": "", "NewFlag": true }' | Set-Content "$dir\shipped.json"
Merge-AppSettings -ShippedPath "$dir\shipped.json" -TargetPath "$dir\target.json"
$r = Get-Content "$dir\target.json" -Raw | ConvertFrom-Json
$r.Url | Should -Be 'https://may-khach' # không bị bản trống ghi đè
$r.NewFlag | Should -Be $true # khoá mới được thêm
$r.Old | Should -Be 1 # khoá chỉ có trên máy vẫn còn
}
}
Test đọc chính file script sẽ được deploy, không phải một bản copy, nên ai sửa hàm mà phá quy tắc merge là test đỏ ngay. Kèm một test kiểm giá trị mặc định của các tham số (tên site, tên pool, đường dẫn), vì đổi nhầm một mặc định là deploy vào sai chỗ. Ví dụ trên viết theo cú pháp Pester 5 (Should -Be); bản của team chạy Pester 3 trên Windows PowerShell 5.1 nên viết Should Be, không có gạch ngang.
Checklist cho một script deploy
[ ] Kiểm artifact và điều kiện máy trước khi tạo hay sửa bất cứ thứ gì
[ ] Có chế độ chỉ kiểm (-CheckOnly), pipeline chạy nó trước
[ ] Idempotent: chạy lại trên máy đã cài cho cùng kết quả
[ ] Backup có tên theo thời gian, giữ N bản
[ ] Dừng app có chờ, có giới hạn thời gian
[ ] Danh sách file thuộc về máy không bao giờ bị ghi đè
[ ] Cấu hình merge theo khoá, cảnh báo khoá chỉ có trên máy
[ ] Health check nhiều lần sau khi khởi động
[ ] Lỗi thì restore và ném lại lỗi
[ ] Có test cho các hàm quyết định (merge, kiểm artifact, giữ file)
[ ] Đã cài thử trên một máy trắng, không chỉ trên máy đã cài
Thử ngay: mở script deploy của bạn, tìm dòng copy đè. Hỏi: trên máy đích có file nào do người dùng hoặc app tự tạo nằm trong thư mục đó không? Nếu có mà script không biết tới, đó là sự cố đang chờ.
Bài sau, bài cuối của series: ghép mọi thứ lại, pipeline build image Docker, đẩy lên registry, và Portainer tự cập nhật stack. Bạn đã từng mất cấu hình trên server vì một lần deploy chưa? Comment kể mình nghe với.
P.S. Test kiểu nhấc hàm ra bằng parser không phải thứ mình nghĩ ra ngay khi nhìn một script đụng vào IIS. Mình nhờ skill test trong PrimeKit, bộ skill mình tự làm, tìm cách test phần đó bằng đúng công cụ project đang có (ở đây là Pester), thay vì đề xuất cài thêm framework. Cài bằng npx @lovehlmmm/primekit init, rồi gõ /pk:test kèm file cần test. Cài thử trên máy trắng thì vẫn phải tự làm, hai lỗi ở bước 3 chỉ lộ ra ở đó.
Tài liệu để đọc thêm
- Host ASP.NET Core trên IIS, Microsoft Learn
- app_offline.htm, Microsoft Learn
- Pester quick start
- robocopy, Microsoft Learn
Series khác của mình
- SQL thực chiến: Những bài học mình ước đã biết sớm hơn: viết query dễ đọc, đọc execution plan, lỗi NULL và N+1 không báo lỗi, schema và transaction, phân trang bằng con trỏ.
- Backend .NET thực chiến: những case hay gặp trên production: async/await làm treo API, HttpClient hết socket, EF Core kéo cả bảng, idempotency, outbox, caching, bảo mật API.
- Front End thực chiến: những bài toán UI mà tutorial không dạy: ngày giờ và giờ mùa hè, tầng dữ liệu theo hợp đồng API, chart, in ấn và accessibility, Outlook Add-in, E2E với Playwright.
- Dùng AI hiệu quả trong công việc: kinh nghiệm thực chiến của dev: viết prompt đủ ngữ cảnh, bắt AI bịa API, giao việc cho agent, review code AI viết, debug, đọc codebase lạ, đóng gói quy trình thành skill.
All Rights Reserved