fix: Backup.ps1 与 Restore.ps1 并发撞车时互踩账本(加运行锁)

问题:两个入口都会写 manifest.json,也都会在备份目录里用 <归档>.tmp 这个名字生成临时
归档。计划任务与手动运行撞在一起时,两边会互相覆盖对方的账本;更糟的是两边会把彼此的临时
归档当成自己的。计划任务的 -MultipleInstances IgnoreNew 只挡住"计划任务之间",挡不住手动运行。

修法:备份目录上的一把跨进程锁,用**独占文件句柄**(FileShare.None)而不是命名互斥体:
  * 句柄由内核持有,进程被杀 / 崩溃时自动关闭,锁自动释放 —— 不会留下需要人工清理的陈旧锁;
    命名互斥体要跨会话(计划任务在另一个会话里跑)还得用 Global\ 前缀,那需要额外权限。
  * 它是文件系统的锁:不区分会话、不区分终端,计划任务与手动运行会互相看见。
  * 锁文件里写明持有进程(pid / 起始时间 / 主机 / 用户)—— "到底是谁占着"不该靠猜。
拿不到锁就直接失败(退出码 1 + 明确消息),不等待:单个条目压缩可能十几分钟,"等它跑完"
对用户来说和挂住没区别。

只读模式不取锁(Backup 的 -DryRun;Restore 的 -DryRun / -WhatIf / -VerifyOnly):
它们一个字节都不写,没必要被正在跑的备份挡在外面。

踩到并记下的两个坑:
  1) catch [System.IO.IOException] 接不住 —— PowerShell 把 .NET 方法抛出的异常包成
     MethodInvocationException,按内层类型做的 catch 会漏。现在沿 InnerException 链找,
     不是 IOException 就把原异常抛回去(目录不可写是 UnauthorizedAccessException,那是真
     错误,不该伪装成"另一次运行在进行中")。
  2) 锁文件是独占打开的,所以内容只能在**释放之后**读 —— 第一版断言在持锁时去 Get-Content,
     被自己的锁拒了;这条断言现在挪到释放之后。

跨进程证据(真跑,不是推理):父进程持锁 → 另一个进程取锁得到 DENIED;持锁状态下跑
真实的 Backup.ps1 → 退出码 1、日志点名锁文件、manifest 的 SHA256 未变;释放后另一进程
得到 GOT。

验收:test.ps1 9/9 全绿(7 与 5.1);tests\Run-RealSmoke.ps1 4/4 全绿。
This commit is contained in:
Shuery committed 2026-09-27 09:18:49 +08:00
1 parent 79f83f6760
commit 8d67a38fb7
5 files changed
+197

No files matched your search

+84
View File
@@ -135,6 +135,87 @@ function Write-Log {
}
}
# ============================================================================
# 运行锁
# ============================================================================
# 为什么需要它:Backup.ps1 与 Restore.ps1 都会写 manifest.json,也都会在备份目录里生成
# 与替换归档。计划任务与手动运行撞在一起时,两边会互相覆盖对方的账本;更糟的是两边会
# 用同一个 <归档>.tmp 名字,把彼此的临时归档当成自己的。
#
# 用**独占文件句柄**(FileShare.None)而不是命名互斥体:
# * 句柄由内核持有,进程被杀 / 崩溃时自动关闭,锁自动释放 —— 不会留下需要人工清理的
# 陈旧锁;命名互斥体要跨会话(计划任务在另一个会话里跑)还得用 Global\ 前缀,
# 而那需要额外权限。
# * 它是文件系统的锁:不区分会话、不区分终端,计划任务与手动运行会互相看见。
function Get-BaknretRunLockPath {
<# .SYNOPSIS 运行锁文件的位置(放在备份目录里,与它保护的账本同处)。 #>
param([Parameter(Mandatory = $true)][string]$Directory)
return (Join-Path $Directory '.baknret.lock')
}
function Enter-BaknretRunLock {
<#
.SYNOPSIS
取得"同一份备份目录同一时间只允许一个进程操作"的锁;拿不到时返回 $null。
.DESCRIPTION
拿不到就直接返回 $null 交给调用方明确失败,**不等待**:单个条目压缩可能十几分钟,
"等它跑完"对用户来说和挂住没区别,不如直接说清楚是谁占着。
返回的是一个已打开的文件流。**不需要刻意释放**:进程退出(含 exit)时句柄由系统
关闭,锁随之释放。调用方仍应显式调 Exit-BaknretRunLock,让锁的覆盖范围一眼可见。
#>
param([Parameter(Mandatory = $true)][string]$Directory)
if (-not (Test-Path -LiteralPath $Directory)) {
New-Item -ItemType Directory -Path $Directory -Force | Out-Null
}
$path = Get-BaknretRunLockPath -Directory $Directory
try {
$stream = [System.IO.File]::Open(
$path,
[System.IO.FileMode]::OpenOrCreate,
[System.IO.FileAccess]::ReadWrite,
[System.IO.FileShare]::None)
} catch {
# 不能只写 `catch [System.IO.IOException]`:PowerShell 会把 .NET 方法抛出的异常包成
# MethodInvocationException,按内层类型做的 catch 接不住,于是锁被占用时会直接抛出去,
# 而不是按约定返回 $null 让调用方明确失败(实测踩到,被自己的断言逮住)。
# 这里沿 InnerException 链找那个 IOException;不是它就把原异常抛回去(例如目录不可写
# 是 UnauthorizedAccessException,那是真错误,不该伪装成"另一次运行在进行中")。
$inner = $_.Exception
while ($inner -and $inner -isnot [System.IO.IOException]) { $inner = $inner.InnerException }
if (-not $inner) { throw }
Write-Log ("运行锁不可用({0}):{1}" -f $inner.GetType().Name, $inner.Message) -Level DEBUG
return $null
}
# 写点线索进去:"到底是谁占着"这个问题不该靠猜
$info = 'pid={0}; started={1:o}; host={2}; user={3}' -f $PID, (Get-Date), $env:COMPUTERNAME, $env:USERNAME
$bytes = [System.Text.Encoding]::UTF8.GetBytes($info)
$stream.SetLength(0)
$stream.Write($bytes, 0, $bytes.Length)
$stream.Flush()
return $stream
}
function Exit-BaknretRunLock {
<#
.SYNOPSIS
释放运行锁。锁文件本身留着 —— 它的内容是最后一次持有者的线索,删不删都无所谓。
#>
param($Lock)
if (-not $Lock) { return }
try {
$Lock.Dispose()
} catch {
Write-Log "释放运行锁失败(进程退出时会自动释放):$_" -Level WARN
}
}
# ============================================================================
# 环境
# ============================================================================
@@ -3191,6 +3272,9 @@ function Get-BaknretPassword {
}
Export-ModuleMember -Function @(
'Enter-BaknretRunLock',
'Exit-BaknretRunLock',
'Get-BaknretRunLockPath',
'Set-BaknretDebug', 'Start-BaknretLog', 'Stop-BaknretLog', 'Get-BaknretLogPath', 'Write-Log',
'Test-Administrator', 'Get-BaknretFreeSpaceGB',
'ConvertTo-NativeArgumentString', 'Invoke-ExternalCommand', 'Resolve-CompressionTool', 'Get-Optimized7zArgument',