用 PowerShell 為檔案伺服器盤點 ── 容量調查與存取權限(ACL)稽核

# 從 old-files.csv 算出「3 年以上未更新的檔案總容量」
$old   = Import-Csv .\old-files.csv
$sumMB = ($old | ForEach-Object { [double]$_.SizeMB } | Measure-Object -Sum).Sum
'3 年以上未更新: {0} 筆 / {1:N1} GB' -f $old.Count, ($sumMB / 1024)

$root = 'D:\share'   # 預期在檔案伺服器上執行。透過 UNC 執行時的注意事項見第 6 章
$denied = @()

# 以第一層資料夾為單位彙總 ── 比起一次彙總整體,先「鎖定範圍」比較優先
# 為了讓根目錄本身的列舉失敗也記入 $denied,外層的 Get-ChildItem 也加上相同的指定
$report = foreach ($dir in Get-ChildItem -LiteralPath $root -Directory `
    -ErrorAction SilentlyContinue -ErrorVariable +denied) {
    # 用 SilentlyContinue 避免因存取拒絕而中斷,但拒絕的記錄會累積到 $denied
    # 列舉直接用管線送進 Measure-Object(若先存進變數,會把全部 FileInfo 保留在記憶體中,
    # 對檔案數達數百萬等級的資料夾會很吃力)
    $stats = Get-ChildItem -LiteralPath $dir.FullName -Recurse -File `
        -ErrorAction SilentlyContinue -ErrorVariable +denied |
        Measure-Object -Property Length -Sum
    [PSCustomObject]@{
        Folder    = $dir.Name
        SizeGB    = [math]::Round([double]$stats.Sum / 1GB, 2)
        FileCount = $stats.Count
    }
}
# 直接放在根目錄下的檔案也算成一列(否則會從資料夾單位的彙總中漏掉)
$rootStats = Get-ChildItem -LiteralPath $root -File `
    -ErrorAction SilentlyContinue -ErrorVariable +denied |
    Measure-Object -Property Length -Sum
if ($rootStats.Count -gt 0) {
    $report += [PSCustomObject]@{
        Folder    = '(根目錄下)'
        SizeGB    = [math]::Round([double]$rootStats.Sum / 1GB, 2)
        FileCount = $rootStats.Count
    }
}

$report | Sort-Object SizeGB -Descending | Format-Table -AutoSize

# 務必保留「無法計數的位置」── 若這裡不是空的,代表彙總並不完整
$denied | ForEach-Object { $_.TargetObject } | Sort-Object -Unique |
    Set-Content -Path .\denied-paths.txt

$cutoff = (Get-Date).AddYears(-3)

# 3 年以上未更新的檔案清單。不做刪除 ── 先做出給部門看的材料
# 列舉失敗的位置之後也要公開,所以用 -ErrorVariable 記錄下來
Get-ChildItem -LiteralPath $root -Recurse -File `
    -ErrorAction SilentlyContinue -ErrorVariable oldEnumErrors |
    Where-Object LastWriteTime -lt $cutoff |
    Select-Object FullName, LastWriteTime,
        @{ Name = 'SizeMB'; Expression = { [math]::Round($_.Length / 1MB, 2) } } |
    Sort-Object SizeMB -Descending |
    Export-Csv -Path .\old-files.csv -NoTypeInformation -Encoding utf8BOM   # 5.1 的話用 UTF8(兩者都含 BOM)

# 為避免清單看起來「完整無缺」,無法列舉的位置也務必公開
$oldEnumErrors | ForEach-Object { $_.TargetObject } |
    Set-Content -Path .\old-files-uninspected.txt

# 對全部檔案計算雜湊,I/O 負擔很重。先只篩選出「大小相同的檔案」
# 列舉失敗的位置(存取拒絕等)之後也要公開,所以用 -ErrorVariable 記錄下來
$candidates = Get-ChildItem -LiteralPath $root -Recurse -File `
    -ErrorAction SilentlyContinue -ErrorVariable enumErrors |
    Group-Object -Property Length |
    Where-Object { $_.Count -ge 2 -and [long]$_.Name -gt 0 } |   # 排除大小為 0 的
    ForEach-Object { $_.Group }

# 只針對篩選後的候選計算雜湊,把一致的群組當作重複「候選」輸出
$candidates |
    Get-FileHash -ErrorAction SilentlyContinue -ErrorVariable hashErrors |   # 預設是 SHA256
    Group-Object -Property Hash |
    Where-Object Count -ge 2 |
    ForEach-Object { $_.Group } |
    Select-Object Hash, Path |
    Export-Csv -Path .\duplicate-candidates.csv -NoTypeInformation -Encoding utf8BOM   # 5.1 的話用 UTF8

# 無法列舉的資料夾,以及因鎖定中・沒有讀取權限等原因無法計算雜湊的檔案,
# 都要以「無法調查」的身分留在清單裡
# (悄悄捨棄的話會和「重複為零」無法區分)
@($enumErrors) + @($hashErrors) | ForEach-Object { $_.TargetObject } |
    Set-Content -Path .\hash-uninspected.txt

# 把部門確認過的清單(從 old-files.csv 中只留下對象列的檔案)移到隔離資料夾
$root       = 'D:\share'
$quarantine = 'D:\quarantine\2026-07'
$list       = Import-Csv .\old-files-approved.csv   # 欄位與 old-files.csv 相同
$dryRun     = $true       # 先設為 $true 確認對象,沒問題後再改成 $false 正式執行
$planned    = @()   # 試跑的結果。輸出到與正式執行台帳不同的檔案
$moved      = @()   # 實際成功移動的項目(用於統計件數。台帳的實體是下面的檔案)
$failed     = @()   # 未能移動的項目。仍在原本的位置
$needsAcl   = @()   # 移動成功但未能限縮權限的項目

# 輸出檔案每次執行都用不同的名稱。若用固定名稱,下一批次一跑,
# 上一次的台帳就會被覆寫,當時移動過的檔案就再也無法還原
$runId    = Get-Date -Format 'yyyyMMdd-HHmmss'
$ledger   = ".\quarantine-log-$runId.csv"        # 用於復原的台帳。每移動一筆就追加寫入
$planFile = ".\quarantine-plan-$runId.csv"
$failFile = ".\quarantine-failed-$runId.csv"
$aclFile  = ".\quarantine-needs-acl-$runId.csv"
$enc      = 'utf8BOM'                            # 5.1 的話用 'UTF8'

# 用於判斷範圍的絕對路徑。統一在結尾加上 \,
# 可以避免 D:\share2 被誤判為在 D:\share 內側
$rootFull       = [System.IO.Path]::GetFullPath($root).TrimEnd('\') + '\'
$quarantineFull = [System.IO.Path]::GetFullPath($quarantine).TrimEnd('\') + '\'

foreach ($row in $list) {
    $src = $row.FullName
    if (-not (Test-Path -LiteralPath $src)) { continue }   # 已經不存在的就跳過

    # 這份 CSV 是人工編輯的,可能混入指向 $root 之外的列。
    # 下面的 Substring 在這種情況下也會悄悄執行,把完全無關位置的檔案拿去隔離。
    # 因此先轉成實體路徑,確認位於稽核對象內側之後才繼續
    $srcFull = (Resolve-Path -LiteralPath $src).ProviderPath
    if (-not $srcFull.StartsWith($rootFull, [StringComparison]::OrdinalIgnoreCase)) {
        $failed += [PSCustomObject]@{ Source = $src; Destination = ''
                                      Error  = "指向稽核對象($root)之外" }
        continue
    }

    # 保持原本的階層結構移動(避免同名檔案衝突與「無法還原」的問題)
    $relative = $srcFull.Substring($rootFull.Length)
    # Join-Path 不會解析 '..'。先用 GetFullPath 摺疊,
    # 再確認是否收在隔離目的地內側
    $dest     = [System.IO.Path]::GetFullPath((Join-Path $quarantine $relative))
    if (-not $dest.StartsWith($quarantineFull, [StringComparison]::OrdinalIgnoreCase)) {
        $failed += [PSCustomObject]@{ Source = $src; Destination = $dest
                                      Error  = "會跑到隔離目的地($quarantine)之外" }
        continue
    }

    if ($dryRun) {
        # 不可以把試跑的列混進 $moved。若寫進同一份台帳,
        # 正式執行之後只要再試跑一次,有效的台帳
        # 就會被「實際不存在的目的地」清單覆蓋掉
        $planned += [PSCustomObject]@{ Source = $src; Destination = $dest }
        continue
    }

    try {
        New-Item -ItemType Directory -Path (Split-Path -Parent $dest) -Force -ErrorAction Stop | Out-Null

        # Move-Item 的錯誤預設是非終止性的。若不加上 -ErrorAction Stop,
        # 即使因鎖定・存取拒絕・衝突而失敗,也會繼續處理下一列,
        # 導致「明明留在原本位置,台帳卻寫成已經移動」
        Move-Item -LiteralPath $srcFull -Destination $dest -ErrorAction Stop
    }
    catch {
        # 在這裡失敗的檔案並沒有被移動,仍在原本的位置
        $failed += [PSCustomObject]@{ Source = $src; Destination = $dest; Error = $_.Exception.Message }
        continue
    }

    # 走到這裡之後,檔案已經在 $dest。無論之後發生什麼失敗,
    # 「檔案在 $dest」這件事都必須留在台帳裡。若把這裡歸到 failed 那一邊,
    # 記錄上看起來是「在原本的位置」,但實物卻在隔離目的地,這是最糟的不一致,
    # 而且再執行一次時 Test-Path $src 會是假,也再也不會被撿到。
    #
    # 而且,不能等跳出迴圈之後才一次寫出去。若中途斷電,
    # 已經移動的檔案就會一筆都沒有被記錄下來。所以要一筆一筆追加寫入
    $record = [PSCustomObject]@{ Source = $srcFull; Destination = $dest; MovedAt = Get-Date }
    $record | Export-Csv -Path $ledger -NoTypeInformation -Encoding $enc -Append
    $moved += $record

    # 在同一個磁碟區內移動時,原本的權限會原封不動地跟過來(後述)。
    # 還原為繼承預設值,讓隔離資料夾的權限單獨生效
    try {
        & icacls $dest /reset /q
        if ($LASTEXITCODE -ne 0) { throw "icacls /reset 失敗 (exit $LASTEXITCODE)" }
    }
    catch {
        # 移動雖然成功,但未能限縮權限。隔離目的地仍維持原本較寬鬆的權限。
        # 這個也要一筆一筆追加寫入
        $aclRow = [PSCustomObject]@{ Destination = $dest; Error = $_.Exception.Message }
        $aclRow | Export-Csv -Path $aclFile -NoTypeInformation -Encoding $enc -Append
        $needsAcl += $aclRow
    }
}

if ($dryRun) {
    $planned | Export-Csv -Path $planFile -NoTypeInformation -Encoding $enc
    Write-Host "試跑: 對象共 $($planned.Count) 筆。尚未實際移動 ($planFile)"
    return
}

$failed | Export-Csv -Path $failFile -NoTypeInformation -Encoding $enc

# 未能限縮權限的部分不要悄悄放過。在這個數字歸零之前,不要開始觀察期間
if ($needsAcl.Count -gt 0) {
    Write-Warning "有 $($needsAcl.Count) 筆隔離檔案未能限縮權限。請查看 $aclFile 並處理"
}
Write-Host "移動 $($moved.Count) 筆 / 失敗 $($failed.Count) 筆 / 權限未處理 $($needsAcl.Count) 筆"
Write-Host "台帳: $ledger"

# 盤點從共用根目錄起算 2 層資料夾的 ACL
# 權限設計的「主幹」集中在淺層,先從那裡開始確認
$aclErrors = @()   # 加了 + 的 -ErrorVariable 是為了追加寫入,每次執行前都要初始化,避免帶入上次的結果
$targets = @(Get-Item -LiteralPath $root `
                 -ErrorAction SilentlyContinue -ErrorVariable +aclErrors) +
           @(Get-ChildItem -LiteralPath $root -Directory -Recurse -Depth 1 `
                 -ErrorAction SilentlyContinue -ErrorVariable +aclErrors)

$aclReport = foreach ($t in $targets) {
    # 取得失敗(無法讀取・掃描過程中被刪除等)也要記錄下來,以便之後公開
    $acl = Get-Acl -LiteralPath $t.FullName -ErrorAction SilentlyContinue -ErrorVariable +aclErrors
    if (-not $acl) { continue }
    if (@($acl.Access).Count -eq 0) {
        # DACL 為空(明確項目為零)的資料夾也要保留成一列,避免繼承中斷的資訊從台帳中消失
        [PSCustomObject]@{
            Path = $t.FullName; Identity = '(無項目)'; Rights = $null; Type = $null
            IsInherited = $null; Inheritance = $null
            InheritanceBroken = $acl.AreAccessRulesProtected
        }
        continue
    }
    foreach ($ace in $acl.Access) {
        [PSCustomObject]@{
            Path        = $t.FullName
            Identity    = $ace.IdentityReference    # 誰(使用者/群組)
            Rights      = $ace.FileSystemRights     # 能做什麼
            Type        = $ace.AccessControlType    # Allow / Deny
            IsInherited = $ace.IsInherited          # 是繼承自上層,還是直接授予
            # 即使是相同的權限,也要區別是「只限這個資料夾」還是「連底下的檔案/資料夾也涵蓋」
            Inheritance = "$($ace.InheritanceFlags)/$($ace.PropagationFlags)"
            InheritanceBroken = $acl.AreAccessRulesProtected  # 這個資料夾是否切斷了繼承
        }
    }
}
$aclReport | Export-Csv -Path .\acl-report.csv -NoTypeInformation -Encoding utf8BOM   # 5.1 的話用 UTF8

# 無法取得 ACL 的對象,也要當作台帳的破洞務必公開(與其他調查採用相同的方針)
$aclErrors | ForEach-Object { $_.TargetObject } |
    Set-Content -Path .\acl-uninspected.txt

# 1. 變更前先把 ACL 存到檔案(/t 表示連同底下全部,/c 表示即使有錯誤也繼續)
icacls "D:\share\sales" /save "C:\aclbackup\sales-acl.txt" /t /c
# 備份沒成功就不要進入變更。icacls 的成敗要看結束代碼來確認
if ($LASTEXITCODE -ne 0) {
    throw "ACL 備份失敗 (icacls ExitCode=$LASTEXITCODE)。中止變更作業"
}

# 2. 用 Set-Acl 變更時: 取得 → 編輯規則 → 套用 這三個階段
$path = 'D:\share\sales\estimate'
$acl  = Get-Acl -LiteralPath $path

# 授予業務群組修改權限的規則(繼承到子資料夾・檔案)
$rule = New-Object System.Security.AccessControl.FileSystemAccessRule(
    'CONTOSO\SalesTeam', 'Modify', 'ContainerInherit,ObjectInherit', 'None', 'Allow')
# 追加授予要用 AddAccessRule。SetAccessRule 會置換同一個使用者/群組現有的 Allow 規則,
# 該群組原本已設定的細部權限可能會在不知不覺間消失
$acl.AddAccessRule($rule)

# 3. 先用 -WhatIf 確認「會套用到哪裡」,沒問題後再正式執行
Set-Acl -LiteralPath $path -AclObject $acl -WhatIf
# 沒問題的話: Set-Acl -LiteralPath $path -AclObject $acl

# 挑一個具代表性的部門資料夾,實測掃描速度後再估算整體
# (若挑到一個檔案都沒有的資料夾,最後的除法會失敗,請挑有實際資料的位置)
$sample = 'D:\share\sales'
$start  = Get-Date
$count  = (Get-ChildItem -LiteralPath $sample -Recurse -File `
    -ErrorAction SilentlyContinue | Measure-Object).Count
$sec    = ((Get-Date) - $start).TotalSeconds
'列舉 {0} 個檔案花了 {1:N1} 秒 → 每萬個檔案約 {2:N1} 秒' -f `
    $count, $sec, ($sec / $count * 10000)