功能定位：为什么要在终端批量更新
SafeW 的加密容器（Encrypted Container，下文简称容器）把链上私钥分片、地址标签与本地策略打包成一组 .scw 文件。图形界面一次只能改 20 条密钥的元数据，而 DAO 财库、空投工作室往往一次轮换上千条地址。macOS 自带的 security、plutil 与 SafeW 随包附送的 safew-cli 正好提供了“无界面、可脚本化”的批量入口，能在 10 秒内完成千级密钥的 expiry、label、access-policy 字段更新，且不会触发 MPC 云端重新分片，这是图形端目前做不到的。
前置检查：版本、权限与备份
1. 版本与安装路径
截至当前的最新版本（SafeW 4.9.1）把命令行工具放在 /Applications/SafeW.app/Contents/MacOS/safew-cli。若你在 2026-03-28 之后通过 Homebrew 安装，则路径为 /opt/homebrew/bin/safew。以下示例统一用 safew 指代，请按实际路径替换。
2. 权限模型
容器文件默认由 mobile 用户所有，组为 staff，权限 640。终端操作需要：
- 读权限：访问
*.scw - 写权限：覆盖原容器或写入临时
*.scw.tmp - 钥匙串：解锁
SafeW-CLI条目，用于本地签名验证
经验性观察：若你在公司 MDM 下发设备上操作，security set-key-partition-list 可能阻止 safew-cli 读取钥匙串，需让 IT 把 com.safew.cli 加入白名单。
三步模板：从导出到批量改写
Step 1 导出可解析的中间格式
safew container export \ --container ~/SafeW/Vaults/main.scw \ --format json \ --output /tmp/main_keys.json \ --include-encrypted-keys false
加上 --include-encrypted-keys false 可让输出文件不含私钥分片，降低在脚本仓库泄露的风险；后续只改元数据，不影响签名。
Step 2 批量改写 JSON
用 jq 把 30 天后过期的密钥全部改成 90 天：
jq '(.. | objects | select(.expiry < (now + 2592000)) | .expiry) |= (now + 7776000)' \ /tmp/main_keys.json > /tmp/main_keys_new.json
若需同步改标签，可再管道一次 jq，此处不再赘述。
Step 3 写回容器并重新签名
safew container import \ --container ~/SafeW/Vaults/main.scw \ --backup-path ~/SafeW/Vaults/main.scw.$(date +%s) \ --data /tmp/main_keys_new.json \ --local-sign true
--local-sign true 会调用钥匙串里的“SafeW-CLI”私钥对容器做 ECDSA 签名，防止文件在传输到云端前被篡改。签名失败最常见原因是钥匙串未解锁，可提前执行：
security unlock-keychain ~/Library/Keychains/login.keychain-db
常见分支与回退
- 分支 A：导入中断——若
import中途被Ctrl-C打断，SafeW 会保留*.scw.tmp文件。下次启动图形端会提示“检测到未完成写操作”，可选择丢弃或重试。 - 分支 B：签名验证失败——日志出现
SWErr-202，99% 是钥匙串权限不足。用security find-identity -v确认“SafeW-CLI”证书标记为valid identities only。 - 回退方案：只要备份文件
main.scw.{timestamp}还在，直接cp覆盖即可，无需重启图形端。
不适用场景与副作用
| 场景 | 副作用 | 缓解办法 |
|---|---|---|
| 容器已启用“硬件冷签”策略 | 批量改写后，冷签模块需重新配对 NFC，否则签名会跳失败 | 在导入前加 --skip-hardware-policy-check，改完再手动配对一次 |
| 多人共管容器（>5 名 MPC 参与方） | 本地签名仅覆盖本地分片，其他 4 份仍用旧策略，导致“策略分叉” | 批量更新后，强制触发一次“同步策略”云端提案，等待 3/5 签名通过 |
| 合规审计模式已开启 | 直接改写容器会跳过审计日志，报表缺失 | 使用 --audit-log /tmp/cli_audit.json 参数，再把该文件上传到 SafeW 云端，报表即可补录 |
与第三方自动化工具协同
在 GitHub Actions 自托管 macOS runner 上，可把 safew 加入 PATH，再配合 MASKED_JQ 变量脱敏。示例片段：
- name: Rotate keys metadata
run: |
safew container export --container "$CONTAINER" --format json -o keys.json \
--include-encrypted-keys false
jq '.keys |= map(if .label | startswith("airdrop") then .expiry += 7776000 else . end)' \
keys.json > keys_new.json
safew container import --container "$CONTAINER" --data keys_new.json \
--backup-path "${CONTAINER}.bak.$(date +%s)" --local-sign true
注意给 runner 开通钥匙串解锁权限，否则签名阶段会无限等待交互输入。
故障排查速查表
- 现象：export 报
SWErr-104“container locked”
可能原因：图形端正在占用
验证：lsof | grep main.scw
处置：退出图形端或加--force参数 - 现象：import 报
SWErr-306“policy mismatch”
可能原因：你改动了key-derivation-algorithm字段
验证：diff 原 JSON 与新 JSON
处置：回滚备份，仅改允许字段（label、expiry、access-policy） - 现象：签名成功但云端同步失败
可能原因：本地时间偏差 >90 秒，导致 JWT 过期
验证：sntp -s time.apple.com
处置：校准时间后重试
最佳实践 10 条检查表
- 操作前复制容器并验证备份 SHA-256
- 用
--include-encrypted-keys false避免私钥落盘 - 批量改写前先在测试容器跑通
jq语法 - 钥匙串解锁与
security set-keychain-settings超时设为 300 秒以上，防止长任务锁中断 - 导入时务必加
--backup-path，文件名带时间戳 - 多人共管场景，提前在 Slack 开“策略同步”审批单，避免分叉
- 合规审计模式开启时，同步上传
--audit-log - 硬件冷签用户，改写后第一时间重新配对 NFC，防止首笔交易失败
- 脚本化运行前，把
safew路径写进变量，避免系统更新后路径漂移 - 每月抽查一次备份文件能否正常导入，防止“静默损坏”
FAQ（结构化数据）
批量更新会触发 MPC 重新分片吗？
不会。仅改 label、expiry、access-policy 属于元数据层，私钥分片不变；只有当你主动轮换私钥时才会重新分片。
可以用 Windows 的 PowerShell 完成同样操作吗？
目前 safew-cli 仅提供 macOS 与 Linux 二进制，Windows 需借助 WSL2 + Ubuntu 子系统，性能与路径兼容性经验性观察良好，但官方未做完整测试矩阵。
导入时忘记加 --backup-path，还能回滚吗？
可以。SafeW 图形端在检测到容器被外部改写时，会自动在同级目录生成 main.scw.auto-bak，保留最近 3 次；你可在图形端“设置-高级-恢复历史容器”里找回。
批量更新后，为什么链上风险引擎弹出“策略未同步”？
风险引擎的本地缓存与容器元数据存在 200 ms 窗口差；批量改写后，点击“立即同步”或重启图形端即可消除提示，不影响转账。
钥匙串解锁命令会暴露主密码吗？
不会。security unlock-keychain 只在当前 shell session 生效，且密码通过掩码输入；CI 环境建议用一次性钥匙串专用密码，避免与登录密码复用。
收尾：下一步行动
如果你管理超过 100 条地址，且每月至少做一次密钥轮换，现在就可以把上面三步脚本化，并放进 cron 或 LaunchAgent，实现“零点击”批量更新。首次运行前，记得在测试容器验证 jq 语法与钥匙串解锁逻辑，确认备份可回滚。一旦跑通，你将把原来 2 小时的图形端手工操作缩短到 30 秒终端命令，同时保留完整的审计与合规日志。
