新增 CLI 使用文档 (docs/CLI.md): 四个命令全参数 + 典型流程示例 + 速查表
This commit is contained in:
lou
@@ -40,6 +40,8 @@ python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
|
||||
|
||||
命令: `sz-transfer` (CLI) / `sz-tui` (终端界面) / `sz-config` (配置) / `sz-backup` (一键备份)
|
||||
|
||||
**完整 CLI 使用文档: [docs/CLI.md](docs/CLI.md)** (上传/下载/备份/目录/账号/示例)
|
||||
|
||||
## 目录管理
|
||||
|
||||
```
|
||||
|
||||
+214
@@ -0,0 +1,214 @@
|
||||
# 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 丢失/更换不影响已存文件。
|
||||
Reference in New Issue
Block a user