# 7z-encrypt CLI 使用文档

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

安装后提供 4 个命令:

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

---

## 0. 首次配置

```bash
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 文件操作

### 上传

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

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

```bash
# 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` 查看)。

### 下载

```bash
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

### 列表 / 删除 / 配额

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

### 目录管理

```bash
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 (物理复制)
```

### 账号

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

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

---

## 2. sz-config

```bash
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), 增量机制只传新增/修改的文件。

```bash
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 交互界面

```bash
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. 典型流程示例

```bash
# 新设备接入
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 丢失/更换不影响已存文件。