edgevoid/7z-encrypt

Fork 0

Files

T

lou 8d3a2fb240 新增 CLI 使用文档 (docs/CLI.md): 四个命令全参数 + 典型流程示例 + 速查表

2026-08-11 14:52:04 +08:00

7.6 KiB

Raw Blame History

7z-encrypt CLI 使用文档

端到端加密文件传输: 加密 -> 分卷 -> 上传 (零知识服务端只存密文)。

安装后提供 4 个命令:

命令	用途
`sz-transfer`	上传 / 下载 / 列表 / 删除 / 目录 / 账号
`sz-config`	首次配置 (服务器 / token / 密钥轮换)
`sz-backup`	一键备份 (预设项或指定目录)
`sz-tui`	交互式终端界面 (菜单 1-17)

0. 首次配置

sz-config --init                 # 生成默认配置模板 (~/.config/7z-encrypt/config.json)
sz-config --set-server http://192.168.10.133:8000
sz-config --set-token <TOKEN>    # 与服务端 SZ_TOKEN 一致, 或用账号登录获取

配置保存在 ~/.config/7z-encrypt/config.json, 包含 server.url / server.token / chunk_size / retries 等。sz-transfer 所有命令默认读这份配置, 可用 --server --token 临时覆盖。

密钥库 (加密/解密唯一凭证) 在 ~/.local/share/7z-encrypt/keyring.json, 由 sz-config --init 自动生成。密钥丢失 = 所有密文永久无法解密, 请用 sz-tui 菜单 7 导出备份。

1. sz-transfer 文件操作

上传

sz-transfer --init <文件>.init.json --manifest <文件>_manifest.json

通常不需要手动生成 init/manifest: 完整上传管线 = 压缩 -> 加密 -> 分卷 -> 元数据 -> 上传, 推荐走 TUI (菜单 1) 或以下手工三步:

# 1. 卷压缩 + 逐卷加密 (32MB 切卷, 可压缩格式逐卷 7z, 已压缩格式直加密)
python metadata.py 文件路径 --chunk-size 32 --vol-compress 32 --file-name 原名

# 2. 上传 (init json + manifest 是上一步的产物)
sz-transfer --init 文件路径.init.json --manifest 文件路径_manifest.json

上传到指定目录: sz-transfer --dir <DIR_ID> --init ... --manifest ... (目录 id 用 --dir-list 查看)。

下载

sz-transfer --list                  # 查看文件 (序号. 文件名 (大小))
sz-transfer --download 3            # 按列表序号下载
sz-transfer --download <FILE_ID>    # 或直接 file_id
sz-transfer --download 3 --out /tmp/xxx
sz-transfer --download 3 --decrypt  # 下载后本地解密还原明文 (默认加密名/密文)

--out 可指定目录或完整文件名, 缺省保存在当前目录
大文件自动走 aria2 并发拉卷, 每卷独立进度条
文件名/序号通用: 纯数字 = 列表序号, 其他 = file_id

列表 / 删除 / 配额

sz-transfer --list                  # [目录] 区块 + [文件] 区块, 每文件带 [目录名] 归属
sz-transfer --delete 3              # 按序号删除 (先 --list 确认再删)
sz-transfer --delete <FILE_ID>
sz-transfer --quota                 # 已用 x MB / 配额 y MB (pct%) 剩余 z MB

目录管理

sz-transfer --dir-create 相册备份    # 创建目录 (按用户隔离, 重名 409)
sz-transfer --dir-list              # 列出目录 (序号. 名称 (N 个文件))
sz-transfer --dir-delete 1          # 删除目录
sz-transfer --move 3 2              # 文件序号 3 移到目录 2 (0 = 根目录)
sz-transfer --clone 3 2             # 克隆文件序号 3 到目录 2 (物理复制)

账号

sz-transfer --register 用户名 密码   # 注册 (成功即登录, token 写入配置)
sz-transfer --login 用户名 密码      # 登录 (token 写入配置)
sz-transfer --logout               # 注销 (服务端 token 失效 + 本地清空)
sz-transfer --whoami               # 显示当前登录用户

每设备用各自账号 token (勿统一配 admin, 否则文件全混进 admin 空间)。

2. sz-config

sz-config --init                   # 生成配置模板 (已存在不覆盖)
sz-config --set-server URL          # 更新服务器地址
sz-config --set-token TOKEN         # 更新 token
sz-config --regenerate-key          # 重新生成密钥 (交互确认; --yes 跳过确认)

--regenerate-key 会删除旧密钥并生成新密钥: 旧密钥加密的已上传文件将永久无法解密, 操作前请先导出密钥备份 (TUI 菜单 7)。

3. sz-backup 一键备份

备份 = 整个文件夹 -> 单个 tar -> 32MB 卷压缩 (逐卷 7z mx=1 + 逐卷加密) -> 上传, 一个文件夹对应一个服务端文件 (file_id), 增量机制只传新增/修改的文件。

sz-backup                    # 备份全部预设项 (photos + documents + download + chat)
sz-backup photos             # 只备份相册
sz-backup download           # 只备份下载目录
sz-backup --dir /home/lou/图片   # 备份指定目录 (PC 端任意路径)
sz-backup --dir /home/lou/图片 --chunk-size 16   # 指定卷大小
sz-backup list               # 查看已备份清单
sz-backup restore 图片        # 恢复指定目录备份 (还原到原路径)
sz-backup restore photos     # 恢复预设项

预设项默认源目录 (config.json 的 backup 段可覆盖):

项	默认源目录
photos	~/storage/dcim, ~/storage/pictures, /sdcard/DCIM, /sdcard/Pictures
documents	/sdcard/Documents
download	/sdcard/Download
chat	需在 config.json backup.chat 配置 (微信导出目录)

--dir 备份的恢复用目录名 (sz-backup restore <目录名>)。

4. sz-tui 交互界面

sz-tui

启动后先验证登录状态: 未登录只显示登录/注册/配置, 登录后显示完整菜单:

 1. 上传文件          10. 登录
 2. 任务续传          11. 注销
 3. 配置              12. 重新生成密钥
 4. 文件列表 (ls)     13. 一键备份 (相册/文档/下载/指定目录)
 5. 下载文件          14. 恢复备份
 6. 删除文件          15. 目录管理 (创建/列表/删除)
 7. 密钥导出          16. 移动文件到目录
 8. 密钥导入          17. 克隆文件
 9. 注册账号           q. 退出

常用操作: 上传输入文件路径 (目录会提示用备份); 备份菜单可直接输入目录路径备份指定目录; 文件列表/删除/下载用序号操作。TUI 内部驱动 sz-transfer 实时透传进度, 与 CLI 完全等价。

5. 典型流程示例

# 新设备接入
sz-config --init
sz-config --set-server http://192.168.10.133:8000
sz-transfer --register boss 密码
sz-transfer --whoami

# 备份一个目录
sz-backup --dir /home/lou/图片

# 查服务器文件与配额
sz-transfer --list
sz-transfer --quota

# 下载并解密还原 (第 2 个文件)
sz-transfer --download 2 --decrypt --out ~/下载/

# 删除 (确认后再删)
sz-transfer --list
sz-transfer --delete 2

6. 参数速查

sz-transfer: --init <json> --manifest <json> --dir <id>
             --list --quota --download <序号|id> --delete <序号|id>
             --out <路径> --decrypt --server <url> --token <tok>
             --dir-create <名> --dir-list --dir-delete <id>
             --move <文件> <目录|0> --clone <文件> <目录|0>
             --register <用户> <密码> --login <用户> <密码>
             --logout --whoami
sz-config:   --init --path <p> --set-server <url> --set-token <tok>
             --regenerate-key [--yes]
sz-backup:   [photos|documents|download|chat|all|list|restore <项>]
             --dir <路径> --chunk-size <MB>

安全提示: 密钥库是唯一解密凭证, 备份/迁移请用 sz-tui 菜单 7/8 导出导入; 服务端只存密文 (零知识), token 丢失/更换不影响已存文件。

7.6 KiB Raw Blame History