用 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 = @()

# 按第1层文件夹逐个汇总 ── 与其一次性汇总整体，不如先「找出重点」
# 为了让根目录自身的列举失败也进入 $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 变更时: 取得 → 编辑规则 → 应用 这3个阶段
$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

# 选一个有代表性的部门文件夹,实测扫描速度后再估算整体
# (选一个1个文件都没有的文件夹会导致最后的除法出错,请选有实际数据的位置)
$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)