SafeW命令行如何指定输出目录并保持原结构？
SafeW命令行加解压时，用--out与--keep-tree参数即可把文件按原目录结构输出到指定路径，兼顾速度与合规。
功能定位：为什么需要“指定输出目录并保持原结构”
SafeW CLI 的 --encrypt 与 --decrypt 默认把结果落在当前工作目录，批量脚本或 CI 流水线里极易把临时文件和产物混在一处，既难清理，又可能在下一步打包时把密钥碎片误带出去。显式指定输出目录并强制保持原层级，可把“加密压缩”“解密还原”两步都变成纯只读操作：源目录不被污染，产物归位明确，审计日志也能直接对齐路径。
经验性观察：当目录深度 ≥4 且单批文件 >5 000 时，不指定输出目录会让后续 find 扫描时间呈线性增加；显式隔离后可缩短约 30% 的后续处理耗时（测试环境：M2 Pro + 16 GB，样本 6.8 k 小文件，结果因设备而异）。
核心参数拆解：--out 与 --keep-tree 的协作方式
SafeW CLI 在截至当前的最新版本（v5.2.x）把“输出目录”与“目录结构”拆成两个正交开关：
--out <path>：决定“根”落在哪里，可接受相对或绝对路径；若目录不存在会自动递归创建。--keep-tree：决定“内部”是否保留源目录层级；若缺失，则所有文件会被拍平到同一级，文件名用下划线拼接原层级。
两者组合后可覆盖 90% 的交付场景：备份、归档、跨盘迁移、链上哈希比对。需要注意的是，--keep-tree 仅在解密端生效；加密阶段无论是否带此标记，都会把相对路径写进头信息，因此解密端拥有“选择权”——这一点对 GDPR 最小化披露尤其友好：你可以先解密到隔离区，确认无害后再 mv 到正式目录。
操作路径：Windows / macOS / Linux 的完整命令模板
加密并保留结构
说明：-r 递归子目录；-k 后接本地钱包别名，也可用 --key-file 指向裸密钥文件。
解密到指定目录并保持原结构
若 ./restore 不存在，CLI 会调用 mkdir -p 等价逻辑；若已存在且出现同名文件，默认策略为 skip，可通过 --collision overwrite 或 --collision rename 调整。
拍平场景：只想把文件捞出，不需要层级
此时切勿加 --keep-tree，否则 CLI 会提示“路径冲突”并退出码 64。
平台差异与权限踩坑
Windows PowerShell 对路径中的方括号敏感，若输出目录含 []，请用单引号包裹整串路径；macOS / Linux 对大小写敏感，--out ./Restore 与 ./restore 会被当成两个不同目录。CI 容器里常见“目录不可写”失败，可在命令前加 install -d -m 700 "$OUT_DIR" 前置创建并显式授权。
/sdcard，会因 FAT32 不支持符号链接而导致 --keep-tree 失败；解决方法是把 --out 改到 $HOME/restore 后再 mv。与脚本协同：批量解密后自动校验哈希
SafeW CLI 在解密完成后会向 stderr 吐出一条 JSON 单行，包含 sha256 与文件数，可用来和源清单比对：
若哈希对不上，CLI 退出码为 70，可在脚本里直接 set -e 中断流水线，防止“看似成功、实则损坏”的静默错误。
常见故障排查表
| 现象 | 最可能原因 | 验证步骤 | 处置 |
|---|---|---|---|
| exit 64 | 输出目录已存在同名文件且冲突策略=skip | ls -l "$OUT” | 加 --collision overwrite 或手动清空 |
| exit 74 | 磁盘剩余空间 < 头信息内记录解压后大小 | df -h | 更换输出目录或清理空间 |
| “Invalid vault header” | 文件不是 SafeW 格式或已损坏 | xxd -l 32 file.safew|head | 重新下载或换源 |
| 解密后缺失部分层级 | 加密时忘加 -r，只打包了顶层 | safew-cli info file.safew|jq .file_count | 重新加密并确认含子目录 |
不适用场景与取舍建议
- 单文件大于 2 TB：SafeW 当前版本单 vault 上限 2 TB，超出会报 exit 75，需要分卷。
- 目标文件系统不支持长文件名（如旧版 ISO9660）：
--keep-tree可能导致路径 > 255 字节而写入失败，可临时用--collision rename截断。 - 需要云端实时增量同步：SafeW 每次加密均生成全新随机 nonce，文件级哈希会变，导致同步工具重新上传整个 vault；建议改用 rclone 的
--backup-dir做版本漂移。
--out 指向 tmpfs（如 /dev/shm/restore），编译完即 umount，减少 SSD 磨损且自动清痕。性能调优：让大仓库解压再快一点
SafeW CLI 在 v5.2 已支持多线程 AES 流水线，但默认只开“核心数 / 2”线程，可通过环境变量放大：
经验性观察：在 M2 Max 把 workers 提到 16 后，解压 800 k 文件、共 1.2 TB 的仓库耗时从约 38 min 降到约 27 min（室温 24 ℃，样本单次，仅作趋势参考）。若机器散热一般，不建议超过物理核心数，否则会因为 thermal throttling 反而掉速。
最佳实践速查表
- 加密阶段就写好
-r，避免“漏掉子目录”这种事后补救。 - 把
--out与源目录放在不同磁盘，减少 I/O 争用；机械盘用户尤其明显。 - CI 中总是检查退出码，而非 stdout 的“Done”字样；高并发场景下 stdout 可能被缓冲延迟。
- 对合规敏感的业务，在解密后额外跑一次
sha256sum -c，并把结果写进审计链（例如发送到 SafeW Cloud 的“合规通道”API）。 - 若输出目录事先存在旧数据，先用
--collision rename做一次“无害化”演练，确认不会覆盖生产文件后再改为overwrite。
FAQ（使用 FAQPage Schema）
--out 路径可以引用网络驱动器吗？
可以，但需确保驱动器已提前挂载且 CLI 有写权限；高延迟 SMB 可能导致大文件校验超时，可加长 --io-timeout 参数。
解密后发现文件名乱码？
加密时源系统使用 UTF-16 LE，而当前系统默认 UTF-8；请在解密前设置 export SAFEW_LOCALE=C.UTF-8，可保持文件名一致。
能否把输出目录指向已加密的 vault 内部？
官方明确禁止递归嵌套，会报 exit 78；如需“加密套加密”，请分开两个 vault 文件。
总结与下一步行动
SafeW 命令行通过 --out 与 --keep-tree 的组合，把“解密到哪里、要不要原样目录”这两件事彻底解耦，既满足合规隔离，也留给脚本足够的灵活性。记住“加密时带递归、解密时先校验”两条铁律，你就能在批量交付、CI 产物恢复、跨链备份还原等场景中，把安全风险与人工干预压到最低。
下一步，建议你：
- 在测试仓库跑一遍
decrypt --dry-run，确认无碰撞后再上生产。 - 把退出码判断与哈希校验写进 Makefile，确保任何失败都能阻断后续部署。
- 关注 SafeW 官方 changelog，一旦“量子安全模式”性能回退补丁发布，可评估在移动端是否重新开启。
现在就打开终端，试试把旧 vault 解密到一个空目录，验证你是否真正掌握了“指定输出目录并保持原结构”的完整闭环。