LockBox CLI 文档

快速开始

将 LockBox.Cli.exe 放在包含在 PATH 中的文件夹里， 或通过完整路径调用它。出于兼容性考虑，--cli 标记是被接受的， 但在仅 CLI 构建时不是必须的。

.\LockBox.Cli.exe --help
.\LockBox.Cli.exe device-id
.\LockBox.Cli.exe algorithms
.\LockBox.Cli.exe keygen --count 3

最小创建和打开工作流程：

$env:LBX_MASTER = "use-a-long-master-password"
$env:LBX_L1 = "layer-1-key"

.\LockBox.Cli.exe create `
  --source "D:\Data" `
  --output "E:\Backups\data.lbx" `
  --master-env LBX_MASTER `
  --layer-env AES-128-GCM=LBX_L1

.\LockBox.Cli.exe open `
  --container "E:\Backups\data.lbx" `
  --output "D:\Restore" `
  --master-env LBX_MASTER `
  --key-env LBX_L1

Linux 使用相同的命令，只是路径使用斜杠，并且二进制文件没有 .exe 后缀：

chmod +x ./LockBox.Cli
./LockBox.Cli --help
./LockBox.Cli device-id
./LockBox.Cli create \
  --source "/srv/data" \
  --output "/backup/data.lbx" \
  --master-env LBX_MASTER \
  --layer-env AES-128-GCM=LBX_L1

安装并验证 CLI

解压适合操作系统和处理器的 ZIP 包。程序已包含 .NET。将哈希值与 SHA256SUMS.txt 核对。把 CLI 放在下文所示的绝对路径，并使用将运行备份的账户检查帮助和许可证。

Linux 还需要发行版的本机依赖库，包括 ICU 和 OpenSSL；内置 .NET 并不提供这些库。Windows 的有效执行策略必须允许运行 PowerShell 脚本。

.NET / Linux · PowerShell / ExecutionPolicy

Expand-Archive -LiteralPath '.\LockBox-Cli-win-x64.zip' -DestinationPath 'C:\Tools\LockBox'
& 'C:\Tools\LockBox\LockBox.Cli.exe' --help
& 'C:\Tools\LockBox\LockBox.Cli.exe' license
Get-FileHash -LiteralPath '.\LockBox-Cli-win-x64.zip' -Algorithm SHA256

uname -m
unzip LockBox-Cli-linux-x64.zip -d ./lockbox-cli
chmod +x ./lockbox-cli/LockBox.Cli
./lockbox-cli/LockBox.Cli --help
./lockbox-cli/LockBox.Cli license
sha256sum LockBox-Cli-linux-x64.zip

SHA256SUMS.txt

Windows x64   -> LockBox-Cli-win-x64.zip
Windows x86   -> LockBox-Cli-win-x86.zip
Windows ARM64 -> LockBox-Cli-win-arm64.zip
Linux x86_64  -> LockBox-Cli-linux-x64.zip
Linux aarch64 -> LockBox-Cli-linux-arm64.zip
Linux armv7l  -> LockBox-Cli-linux-arm.zip

文件夹、路径和磁盘空间

请替换示例路径。源文件夹不能为空，容器必须保存在其外部。重复使用输出名称会替换原有容器及其分卷。为容器旁的临时文件预留空间，计划任务还需要源数据副本空间。容量单位以 1024 为基数；填充是增加字节，并非设置最终总大小。

C:\Tools\LockBox\LockBox.Cli.exe     /opt/lockbox/LockBox.Cli
C:\LockBox\secrets\master.txt       /srv/lockbox/secrets/master.txt
C:\LockBox\secrets\layer1.txt       /srv/lockbox/secrets/layer1.txt
C:\LockBox\backup.ps1               /srv/lockbox/backup.sh
D:\Data\report.csv                 /srv/data/report.csv
E:\Backups\20260910-020000\data.lbx  /backup/20260910-020000/data.lbx
D:\Restore\Data\report.csv         /restore/data/report.csv

& 'C:\Tools\LockBox\LockBox.Cli.exe' create --source 'D:\Data' --output 'E:\Backups\data.lbx' --master-file 'C:\LockBox\secrets\master.txt' --layer-file 'AES-128-GCM=C:\LockBox\secrets\layer1.txt'

/opt/lockbox/LockBox.Cli create --source /srv/data --output /backup/data.lbx --master-file /srv/lockbox/secrets/master.txt --layer-file AES-128-GCM=/srv/lockbox/secrets/layer1.txt

准备可重复使用的秘密文件

仅生成一次秘密信息，保留受保护的备份并限制文件访问。示例拒绝覆盖现有密钥。UTF-8 文件末尾的换行会被删除，但空格会保留。打开旧备份仍需原来的密钥。

$ErrorActionPreference = 'Stop'
$cli = 'C:\Tools\LockBox\LockBox.Cli.exe'
$secretDir = 'C:\LockBox\secrets'
New-Item -ItemType Directory -Force -Path $secretDir | Out-Null
$files = @('master.txt', 'layer1.txt')
foreach ($name in $files) {
    if (Test-Path -LiteralPath (Join-Path $secretDir $name)) {
        throw "Secret already exists: $name"
    }
}
foreach ($name in $files) {
    $key = & $cli keygen --count 1
    if ($LASTEXITCODE -ne 0) { throw 'Key generation failed' }
    [IO.File]::WriteAllText((Join-Path $secretDir $name), [string]$key, [Text.UTF8Encoding]::new($false))
}

set -eu
umask 077
mkdir -p /srv/lockbox/secrets
test ! -e /srv/lockbox/secrets/master.txt
test ! -e /srv/lockbox/secrets/layer1.txt
set -C
/opt/lockbox/LockBox.Cli keygen --count 1 > /srv/lockbox/secrets/master.txt
/opt/lockbox/LockBox.Cli keygen --count 1 > /srv/lockbox/secrets/layer1.txt

激活和许可证状态

许可证密钥绑定到同一 CLI 构建打印的设备 ID。 如果许可证被复制到另一台电脑，LockBox 会拒绝它并回退到免费版。

Windows 会检查现有的 LockBox 应用程序数据位置。Linux 将激活信息存储在 $XDG_CONFIG_HOME/lockbox/.lockbox.license，然后 ~/.config/lockbox/.lockbox.license，并以 ~/.lockbox/.lockbox.license 作为备用。

.\LockBox.Cli.exe device-id

.\LockBox.Cli.exe license

从许可证文件激活

.\LockBox.Cli.exe activate --license-file "C:\Licenses\lockbox-license.txt"

从环境变量激活

$env:LBX_LICENSE = "LBX-LIC-..."
.\LockBox.Cli.exe activate --license-env LBX_LICENSE

在线激活

在线激活可用，但可能会通过 shell 历史记录或进程日志泄露。

.\LockBox.Cli.exe activate --license "LBX-LIC-..."

Linux 激活

export LBX_LICENSE="LBX-LIC-..."
./LockBox.Cli activate --license-env LBX_LICENSE
./LockBox.Cli license

密钥处理

优先使用环境变量或文件。内联密钥仅适用于测试。 主密码和层密钥必须妥善保管：没有它们，容器无法打开。

基于文件的密钥

Set-Content -Path ".\master.txt" -Value "master-password" -Encoding UTF8
Set-Content -Path ".\layer1.txt" -Value "layer-key-1" -Encoding UTF8

.\LockBox.Cli.exe create `
  -s "D:\Data" `
  -o "E:\Backups\data.lbx" `
  --master-file ".\master.txt" `
  --layer-file AES-128-GCM=.\layer1.txt

算法和密钥生成

使用 algorithms 查看所有支持的配置文件和最低版本。 使用 keygen 获取层密钥。

.\LockBox.Cli.exe algorithms
.\LockBox.Cli.exe keygen
.\LockBox.Cli.exe keygen --count 9
.\LockBox.Cli.exe generate-keys -n 20

支持的命令别名：

algorithms
list-algorithms
profiles

keygen
generate-key
generate-keys

创建容器

create 打包源文件夹，应用可选的压缩和填充， 通过一层或多层加密有效载荷，并写入一个 .lbx 容器。

必需选项

• --source 或 -s：源文件夹。
• --output 或 -o：输出 .lbx 路径。
• --master、--master-env 或 --master-file。
• 至少一层：--layer、--layer-env 或 --layer-file。

最小 AES 容器

.\LockBox.Cli.exe create `
  -s "D:\Data" `
  -o "E:\Backups\data.lbx" `
  --master-env LBX_MASTER `
  --layer-env AES-128-GCM=LBX_L1

压缩容器

.\LockBox.Cli.exe create `
  --source "D:\Exports" `
  --output "E:\Backups\exports.lbx" `
  --master-env LBX_MASTER `
  --layer-env AES-256-GCM=LBX_L1 `
  --compress

加密填充

.\LockBox.Cli.exe create `
  -s "D:\Contracts" `
  -o "E:\Backups\contracts.lbx" `
  --master-env LBX_MASTER `
  --layer-env AES-256-GCM=LBX_L1 `
  --padding 2GB

将容器拆分为多个部分

.\LockBox.Cli.exe create `
  -s "D:\Media" `
  -o "E:\Backups\media.lbx" `
  --master-env LBX_MASTER `
  --layer-env AES-256-GCM=LBX_L1 `
  --split 700MB

第一部分保留 .lbx。附加部分使用 .lbx1、.lbx2，以此类推。将所有部分保存在同一文件夹中。

九层最大示例

$env:LBX_MASTER = "use-a-long-master-password"
$env:LBX_L1 = "layer-1-key"
$env:LBX_L2 = "layer-2-key"
$env:LBX_L3 = "layer-3-key"
$env:LBX_L4 = "layer-4-key"
$env:LBX_L5 = "layer-5-key"
$env:LBX_L6 = "layer-6-key"
$env:LBX_L7 = "layer-7-key"
$env:LBX_L8 = "layer-8-key"
$env:LBX_L9 = "layer-9-key"

.\LockBox.Cli.exe create `
  --source "D:\Data" `
  --output "E:\Backups\data-max.lbx" `
  --master-env LBX_MASTER `
  --compress `
  --padding 2GB `
  --split 700MB `
  --layer-env AES-256-GCM=LBX_L1 `
  --layer-env CHACHA20-POLY1305=LBX_L2 `
  --layer-env AES-256-CCM=LBX_L3 `
  --layer-env SERPENT-256-CTR-HMACSHA512=LBX_L4 `
  --layer-env TWOFISH-256-CTR-HMACSHA512=LBX_L5 `
  --layer-env CAMELLIA-256-CTR-HMACSHA512=LBX_L6 `
  --layer-env ARIA-256-CTR-HMACSHA512=LBX_L7 `
  --layer-env AES-256-CBC-HMACSHA512=LBX_L8 `
  --layer-env AES-192-OFB-HMACSHA384=LBX_L9

替代算法/密钥语法

.\LockBox.Cli.exe create `
  -s "D:\Data" `
  -o "E:\Backups\data.lbx" `
  --master-env LBX_MASTER `
  --algorithm AES-128-GCM --key-env LBX_L1 `
  --algorithm AES-128-CTR-HMACSHA256 --key-env LBX_L2

成功手动创建后删除源文件

.\LockBox.Cli.exe create `
  -s "D:\TempToEncrypt" `
  -o "E:\Backups\temp.lbx" `
  --master-env LBX_MASTER `
  --layer-env AES-256-GCM=LBX_L1 `
  --delete-source

--delete-source 仅在容器创建成功后删除源文件夹。调度器有不同的选项：--delete-source-contents。

容器销毁密码

Max 版本可以为容器添加一个单独的销毁密码。如果以后以主密码的形式输入该密码，LockBox 会立即在不确认的情况下覆盖容器。 这是针对强迫压力场景设计的。请将其与真实主密码分开保存。

该命令会验证可用磁盘空间，将原始容器数据使用新的随机密钥和 AES-256-GCM 加密到临时文件中， 将结果标准化为原始大小，替换原始文件，并忘记随机密钥。对于分割容器，同一文件夹中的每个 .lbx、.lbx1、.lbx2 部分都会被替换，同时保留原始部分的大小。

使用销毁密码创建

$env:LBX_MASTER = "real-master-password"
$env:LBX_L1 = "layer-key-1"
$env:LBX_DESTROY = "pressure-password"

.\LockBox.Cli.exe create `
  --source "D:\Data" `
  --output "E:\Backups\data.lbx" `
  --master-env LBX_MASTER `
  --layer-env AES-256-GCM=LBX_L1 `
  --destruction-password-env LBX_DESTROY

在没有层密钥的情况下触发销毁

.\LockBox.Cli.exe open `
  --container "E:\Backups\data.lbx" `
  --output "D:\Restore" `
  --master-env LBX_DESTROY

Linux 触发

export LBX_DESTROY="pressure-password"
./LockBox.Cli open \
  --container "/backup/data.lbx" \
  --output "/restore" \
  --master-env LBX_DESTROY

销毁成功后，容器不再是有效的 LockBox 文件。CLI 返回退出代码 0， 因为请求的销毁操作已成功完成。

打开容器

open 将容器提取到输出文件夹。对于普通提取，必须按照创建时的顺序提供层密钥。 对于销毁密码工作流，只需提供容器路径、输出路径，以及作为主密码的销毁密码。

打开单层容器

.\LockBox.Cli.exe open `
  --container "E:\Backups\data.lbx" `
  --output "D:\Restore" `
  --master-env LBX_MASTER `
  --key-env LBX_L1

打开分割容器

.\LockBox.Cli.exe open `
  -c "E:\Backups\data.lbx" `
  -o "D:\Restore" `
  --master-env LBX_MASTER `
  --key-env LBX_L1

打开多层容器

.\LockBox.Cli.exe open `
  -c "E:\Backups\data-max.lbx" `
  -o "D:\Restore" `
  --master-env LBX_MASTER `
  --key-env LBX_L1 `
  --key-env LBX_L2 `
  --key-env LBX_L3 `
  --key-env LBX_L4 `
  --key-env LBX_L5 `
  --key-env LBX_L6 `
  --key-env LBX_L7 `
  --key-env LBX_L8 `
  --key-env LBX_L9

别名

open
decrypt
extract

通过恢复验证备份

为示例创建一个小型 report.csv 文件。提取到新的文件夹，内部会保留源文件夹名称。将全部分卷放在一起，并与未修改的源数据比较。提取时需要容器旁可写的临时空间；也应保护恢复出的明文文件。

$ErrorActionPreference = 'Stop'
$cli = 'C:\Tools\LockBox\LockBox.Cli.exe'
$container = 'E:\Backups\data.lbx'
$restore = Join-Path 'D:\RestoreChecks' ([guid]::NewGuid().ToString('N'))
& $cli open --container $container --output $restore --master-file 'C:\LockBox\secrets\master.txt' --key-file 'C:\LockBox\secrets\layer1.txt'
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
$original = (Get-FileHash -LiteralPath 'D:\Data\report.csv' -Algorithm SHA256).Hash
$restored = (Get-FileHash -LiteralPath (Join-Path $restore 'Data\report.csv') -Algorithm SHA256).Hash
if ($original -ne $restored) { throw 'SHA256 mismatch' }
Write-Output $restore

set -eu
umask 077
mkdir -p /restore
restore=$(mktemp -d /restore/check-XXXXXX)
/opt/lockbox/LockBox.Cli open --container /backup/data.lbx --output "$restore" --master-file /srv/lockbox/secrets/master.txt --key-file /srv/lockbox/secrets/layer1.txt
cmp /srv/data/report.csv "$restore/data/report.csv"
sha256sum /srv/data/report.csv "$restore/data/report.csv"

调度器

调度器命令在 Max 版本中可用。它们将完整的任务元数据存储在加密的 .lbxjobs 文件中，包括源路径、输出路径、密码、销毁密码、层密钥、压缩、填充、拆分以及删除源内容设置。

已计划的任务仅在 LockBox.Cli.exe schedule run 运行时执行。 如果需要在重启后自动启动工作程序，请使用 Windows 任务计划程序、Linux systemd、cron、服务包装器或长时间运行的控制台会话。

频率值

once
30m
hourly
2h
3h
6h
9h
12h
18h
daily
2d
3d
5d
weekly
2w
monthly
2mo
3mo
6mo
9mo
yearly

添加每日加密备份任务

$env:LBX_JOBS_PASSWORD = "jobs-file-password"
$env:LBX_MASTER = "master-password"
$env:LBX_L1 = "layer-key-1"
$env:LBX_DESTROY = "pressure-password"

.\LockBox.Cli.exe schedule add `
  --tasks "E:\Backups\jobs.lbxjobs" `
  --password-env LBX_JOBS_PASSWORD `
  --name "Nightly data backup" `
  --frequency daily `
  --start ((Get-Date).AddDays(1).ToString("o")) `
  --source "D:\Data" `
  --output "E:\Backups\nightly-data.lbx" `
  --master-env LBX_MASTER `
  --layer-env AES-256-GCM=LBX_L1 `
  --destruction-password-env LBX_DESTROY `
  --compress

添加成功后删除源文件夹内容的任务

.\LockBox.Cli.exe schedule add `
  --tasks "E:\Backups\jobs.lbxjobs" `
  --password-env LBX_JOBS_PASSWORD `
  --name "Encrypt outgoing folder" `
  --frequency 30m `
  --start ((Get-Date).AddDays(1).ToString("o")) `
  --source "D:\Outgoing" `
  --output "E:\Backups\outgoing.lbx" `
  --master-env LBX_MASTER `
  --layer-env AES-256-GCM=LBX_L1 `
  --delete-source-contents

添加带填充和拆分部分的每月归档

.\LockBox.Cli.exe schedule add `
  --tasks "E:\Backups\jobs.lbxjobs" `
  --password-env LBX_JOBS_PASSWORD `
  --name "Monthly legal archive" `
  --frequency monthly `
  --start ((Get-Date).AddDays(1).ToString("o")) `
  --source "D:\Legal" `
  --output "E:\Archives\legal-monthly.lbx" `
  --master-env LBX_MASTER `
  --layer-env AES-256-GCM=LBX_L1 `
  --compress `
  --padding 4GB `
  --split 2GB

列出已保存的任务

.\LockBox.Cli.exe schedule list `
  --tasks "E:\Backups\jobs.lbxjobs" `
  --password-env LBX_JOBS_PASSWORD

运行调度器工作程序

.\LockBox.Cli.exe schedule run `
  --tasks "E:\Backups\jobs.lbxjobs" `
  --password-env LBX_JOBS_PASSWORD `
  --state "E:\Backups\jobs.status.json" `
  --poll-seconds 30

运行到期任务一次并退出

.\LockBox.Cli.exe schedule run-once `
  --tasks "E:\Backups\jobs.lbxjobs" `
  --password-env LBX_JOBS_PASSWORD `
  --state "E:\Backups\jobs.status.json"

显示最新运行状态

.\LockBox.Cli.exe schedule status --state "E:\Backups\jobs.status.json"

状态标记为 [OK]、[RUNNING] 和 [FAILED]。 失败的任务会包含失败原因，并提示用户如果问题重复发生，请联系支持。

JSON 脚本

当工作流程有多个步骤时使用 --script。脚本运行器支持 create、open、keygen、algorithms、 device-id、license 和 activate。

在一个脚本中创建并打开

{
  "stopOnError": true,
  "commands": [
    {
      "command": "create",
      "source": "D:\\Data",
      "output": "E:\\Backups\\data.lbx",
      "masterPasswordEnv": "LBX_MASTER",
      "destructionPasswordEnv": "LBX_DESTROY",
      "compression": true,
      "padding": "512MB",
      "split": "700MB",
      "layers": [
        { "algorithm": "AES-256-GCM", "keyEnv": "LBX_L1" },
        { "algorithm": "CHACHA20-POLY1305", "keyEnv": "LBX_L2" }
      ]
    },
    {
      "command": "open",
      "container": "E:\\Backups\\data.lbx",
      "output": "D:\\Restore",
      "masterPasswordEnv": "LBX_MASTER",
      "keyEnvs": [ "LBX_L1", "LBX_L2" ]
    }
  ]
}

.\LockBox.Cli.exe --script ".\backup.lockbox.json"

在步骤失败后继续

{
  "stopOnError": false,
  "commands": [
    { "command": "license" },
    { "command": "algorithms" },
    {
      "command": "create",
      "source": "D:\\BuildOutput",
      "output": "E:\\Artifacts\\build.lbx",
      "masterPasswordEnv": "LBX_MASTER",
      "layers": [
        { "algorithm": "AES-128-GCM", "keyEnv": "LBX_L1" }
      ]
    }
  ]
}

从脚本激活

{
  "commands": [
    {
      "command": "activate",
      "licenseKeyFile": "C:\\Licenses\\lockbox-license.txt"
    },
    { "command": "license" }
  ]
}

JSON 字段和执行规则

表格将 create 字段及 open 密钥数组映射到 CLI 选项。相对路径基于进程工作目录，而不是 JSON 文件位置。字符串中的变量和日期不会自动展开。每个字段只使用一个秘密来源；open 依次读取 keys、keyEnvs、keyFiles。建议使用 stopOnError: true；false 时，后续成功可能掩盖先前失败。JSON 脚本不支持计划任务命令。

{
  "stopOnError": true,
  "commands": [
    {
      "command": "create",
      "source": "/srv/data",
      "output": "/backup/data.lbx",
      "masterPasswordFile": "/srv/lockbox/secrets/master.txt",
      "layers": [
        { "algorithm": "AES-128-GCM", "keyFile": "/srv/lockbox/secrets/layer1.txt" }
      ]
    },
    {
      "command": "open",
      "container": "/backup/data.lbx",
      "output": "/restore/check",
      "masterPasswordFile": "/srv/lockbox/secrets/master.txt",
      "keyFiles": ["/srv/lockbox/secrets/layer1.txt"]
    }
  ]
}

/opt/lockbox/LockBox.Cli --quiet script /srv/lockbox/backup.lockbox.json

自动化方案

加密数据库转储备份

$stamp = Get-Date -Format "yyyyMMdd-HHmmss"
$dump = "D:\DbDumps\$stamp"
New-Item -ItemType Directory -Path $dump | Out-Null

Copy-Item "D:\DatabaseExports\*" $dump -Recurse

.\LockBox.Cli.exe create `
  -s $dump `
  -o "E:\Backups\db-$stamp.lbx" `
  --master-env LBX_MASTER `
  --layer-env AES-256-GCM=LBX_L1 `
  --compress `
  --padding 512MB

CI 工件保护

.\LockBox.Cli.exe create `
  --source "$env:BUILD_ARTIFACTSTAGINGDIRECTORY" `
  --output "$env:AGENT_TEMPDIRECTORY\protected-artifacts.lbx" `
  --master-env LBX_MASTER `
  --layer-env AES-128-GCM=LBX_L1

安全合作伙伴传输

.\LockBox.Cli.exe create `
  -s "D:\PartnerPackage" `
  -o "E:\Transfer\partner-package.lbx" `
  --master-env LBX_MASTER `
  --layer-env AES-256-GCM=LBX_L1 `
  --layer-env CHACHA20-POLY1305=LBX_L2 `
  --compress `
  --split 1GB

长期存档

.\LockBox.Cli.exe create `
  -s "D:\Records\2026" `
  -o "E:\ColdStorage\records-2026.lbx" `
  --master-file "C:\Secrets\records-master.txt" `
  --layer-file AES-256-GCM=C:\Secrets\records-layer1.txt `
  --layer-file SERPENT-256-CTR-HMACSHA512=C:\Secrets\records-layer2.txt `
  --compress `
  --padding 8GB `
  --split 4GB

批处理文件示例

@echo off
set LBX_MASTER=master-password
set LBX_L1=layer-key-1

LockBox.Cli.exe create ^
  --source "D:\Data" ^
  --output "E:\Backups\data.lbx" ^
  --master-env LBX_MASTER ^
  --layer-env AES-128-GCM=LBX_L1

if errorlevel 1 exit /b %errorlevel%
echo OK

Windows：备份多个文件夹

将脚本保存到指定路径。它为每个来源创建名称唯一的容器和日志，遇到错误就停止，并保留 CLI 退出码。AES-128-GCM 示例适用于 Free；压缩和分卷需要 Pro 或 Max。

C:\LockBox\backup.ps1

param(
    [string[]]$Source = @('D:\Data'),
    [string]$Destination = 'E:\Backups'
)
$ErrorActionPreference = 'Stop'
$cli = 'C:\Tools\LockBox\LockBox.Cli.exe'
$secretDir = 'C:\LockBox\secrets'
try {
    foreach ($folder in $Source) {
        $sourcePath = (Resolve-Path -LiteralPath $folder).Path
        $stamp = (Get-Date).ToUniversalTime().ToString('yyyyMMdd-HHmmss-fff')
        $runId = [guid]::NewGuid().ToString('N')
        $runDir = Join-Path $Destination "$stamp-$runId"
        New-Item -ItemType Directory -Path $runDir | Out-Null
        $container = Join-Path $runDir 'data.lbx'
        $log = Join-Path $runDir 'create.log'
        $cliArgs = @(
            '--quiet', 'create', '--source', $sourcePath, '--output', $container,
            '--master-file', (Join-Path $secretDir 'master.txt'),
            '--layer-file', ('AES-128-GCM=' + (Join-Path $secretDir 'layer1.txt'))
        )
        $ErrorActionPreference = 'Continue'
        & $cli @cliArgs > $log 2>&1
        $result = $LASTEXITCODE
        $ErrorActionPreference = 'Stop'
        if ($result -ne 0) {
            Get-Content -LiteralPath $log
            exit $result
        }
        if (-not (Test-Path -LiteralPath $container -PathType Leaf)) {
            throw "Container missing: $container"
        }
        Write-Output $container
    }
    exit 0
} catch {
    Write-Error $_ -ErrorAction Continue
    exit 1
}

& 'C:\LockBox\backup.ps1' -Source 'D:\Data', 'D:\Reports' -Destination 'E:\Backups'
# 0 = success; 1 = runtime error; 2 = usage error; 3 = edition restriction
$LASTEXITCODE

Linux：无人值守备份

使用 LF 换行保存 Bash 脚本。在指定路径准备 CLI 和秘密文件，并将源文件夹作为参数传入。每次运行都有独立目录。失败时会保留日志并返回非零退出码；源文件保留不变。

/srv/lockbox/backup.sh

#!/bin/bash
set -eu
umask 077
cli=/opt/lockbox/LockBox.Cli
secret_dir=/srv/lockbox/secrets
backup_root=/backup
mkdir -p "$backup_root"
if [ "$#" -eq 0 ]; then
    set -- /srv/data
fi
for source in "$@"; do
    run_dir=$(mktemp -d "$backup_root/$(date -u +%Y%m%d-%H%M%S)-XXXXXX")
    container="$run_dir/data.lbx"
    log="$run_dir/create.log"
    "$cli" --quiet create \
        --source "$source" \
        --output "$container" \
        --master-file "$secret_dir/master.txt" \
        --layer-file "AES-128-GCM=$secret_dir/layer1.txt" > "$log" 2>&1 || {
        result=$?
        cat "$log" >&2
        exit "$result"
    }
    test -s "$container"
    printf '%s\n' "$container"
done

/bin/bash /srv/lockbox/backup.sh /srv/data /srv/reports

通过操作系统定时运行

这些任务启动上面的备份脚本，此种 create 用法不需要 Max。Windows 注册示例仅在用户登录时运行；如需注销后运行，请在任务计划程序中配置。确认已安装 flock 后，将 cron 条目加入备份用户的 crontab。两个示例均在本地时间 02:00 运行，并防止计划任务重叠。先检查账户权限并手动测试。

Windows

$action = New-ScheduledTaskAction -Execute 'powershell.exe' -Argument '-NoProfile -NonInteractive -File "C:\LockBox\backup.ps1"' -WorkingDirectory 'C:\LockBox'
$trigger = New-ScheduledTaskTrigger -Daily -At '02:00'
$settings = New-ScheduledTaskSettingsSet -StartWhenAvailable -MultipleInstances IgnoreNew -ExecutionTimeLimit ([TimeSpan]::Zero)
$principal = New-ScheduledTaskPrincipal -UserId ([Security.Principal.WindowsIdentity]::GetCurrent().Name) -LogonType Interactive
Register-ScheduledTask -TaskName 'LockBox backup' -Action $action -Trigger $trigger -Settings $settings -Principal $principal
Start-ScheduledTask -TaskName 'LockBox backup'
Get-ScheduledTaskInfo -TaskName 'LockBox backup'

New-ScheduledTaskSettingsSet · New-ScheduledTaskPrincipal

Linux: cron

crontab -e

0 2 * * * /usr/bin/flock -n /srv/lockbox/backup.lock /bin/bash /srv/lockbox/backup.sh >> /srv/lockbox/cron.log 2>&1

crontab(5)

Max：运行计划任务进程

先创建具有所需权限的 lockbox 服务账户，为该账户激活 Max，并准备单独的 UTF-8 密码文件 jobs.txt。add 会追加而非更新，每个任务只需执行一次。每个任务文件运行一个进程，修改定义后重启。状态 JSON 不会恢复执行历史：过期的周期任务时点会被跳过，过期的 once 任务可能再次运行。使用操作系统定期启动时，应调用 create，而非反复调用 run-once。内置计划程序会重复使用配置的输出名称。

/opt/lockbox/LockBox.Cli schedule add \
  --tasks /srv/lockbox/jobs.lbxjobs \
  --password-file /srv/lockbox/secrets/jobs.txt \
  --name nightly-data --frequency daily \
  --start "$(date -d 'tomorrow 02:00' --iso-8601=seconds)" \
  --source /srv/data --output /backup/nightly-data.lbx \
  --master-file /srv/lockbox/secrets/master.txt \
  --layer-file AES-128-GCM=/srv/lockbox/secrets/layer1.txt

/opt/lockbox/LockBox.Cli schedule list --tasks /srv/lockbox/jobs.lbxjobs --password-file /srv/lockbox/secrets/jobs.txt

/etc/systemd/system/lockbox-scheduler.service

[Unit]
Description=LockBox scheduler
After=local-fs.target
RequiresMountsFor=/srv/data /srv/lockbox /backup

[Service]
Type=simple
User=lockbox
WorkingDirectory=/srv/lockbox
UMask=0077
ExecStart=/opt/lockbox/LockBox.Cli schedule run --tasks /srv/lockbox/jobs.lbxjobs --password-file /srv/lockbox/secrets/jobs.txt --state /srv/lockbox/jobs.status.json --poll-seconds 30
Restart=on-failure
RestartSec=10
KillSignal=SIGINT
TimeoutStopSec=300

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now lockbox-scheduler.service
systemctl status lockbox-scheduler.service
journalctl -u lockbox-scheduler.service -n 50 --no-pager
/opt/lockbox/LockBox.Cli schedule status --state /srv/lockbox/jobs.status.json

systemd.service

命令参考

创建选项

打开选项

调度选项

使用 --language 或 --lang 选择控制台语言，使用 --quiet 隐藏常规进度；错误仍会输出到标准错误流。Ctrl+C 请求取消并返回代码 1。代码 2 表示命令语法无效；代码 3 表示当前版本不提供某项创建功能。代码 0 也包括有意触发销毁密码的情况，因此仅凭该代码不能证明文件已被提取。执行后续自动化步骤前，请验证预期输出。

退出码和备份监控

schedule run-once 即使有任务失败也可能返回零，schedule status 在缺少状态时也返回零。请检查 savedAt、lastSuccessAt、lastError；[OK] 可能仅表示 Ready。该监控示例假定每日备份、每 30 秒轮询，并在 26 小时内成功过一次，请按实际计划调整阈值。JSON 状态使用数字。--quiet 会抑制成功 create/open 的常规输出。

$ErrorActionPreference = 'Stop'
try {
    $status = Get-Content -LiteralPath 'E:\Backups\jobs.status.json' -Raw | ConvertFrom-Json
    if (@($status.tasks).Count -eq 0) { throw 'No tasks in status file' }
    if ([DateTimeOffset]$status.savedAt -lt [DateTimeOffset]::Now.AddMinutes(-2)) {
        throw 'Worker status is stale'
    }
    foreach ($task in $status.tasks) {
        if ($task.state -eq 3 -or $task.lastError) { throw "Task failed: $($task.name)" }
        if (-not $task.lastSuccessAt -or [DateTimeOffset]$task.lastSuccessAt -lt [DateTimeOffset]::Now.AddHours(-26)) {
            throw "No recent successful backup: $($task.name)"
        }
    }
    exit 0
} catch {
    Write-Error $_ -ErrorAction Continue
    exit 1
}

0 -> Ready
1 -> Running
2 -> Completed
3 -> Failed

故障排除