edgevoid/7z-encrypt
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 4 Wiki Activity

README 更新: 对齐 v1.3.0 架构 (卷压缩/aria2全链路/目录管理/备份单文件化/deb依赖自动装)

Browse Source
This commit is contained in:
lou
2026-08-10 22:58:00 +08:00
parent a46e43b73c
commit bb1699e9fd
1 changed files with 44 additions and 258 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+44 -258
View File
@@ -2,289 +2,75 @@
> 端到端加密文件传输 | 零知识 + 零合并 | 服务端无密钥不解密
**发行版下载 (deb 安装包):** Gitee [发行版 v1.0.0](https://gitee.com/edgevoid/7z-encrypt/releases) · Gitea [Releases v1.0.0](http://8.136.202.225:3000/edgevoid/7z-encrypt/releases)
**发行版下载 (deb 安装包, 依赖自动安装):** Gitee [Releases v1.3.0](https://gitee.com/edgevoid/7z-encrypt/releases) · Gitea [Releases v1.3.0](http://8.136.202.225:3000/edgevoid/7z-encrypt/releases)
端到端加密 + 最高压缩 + 分卷传输的私有文件网盘。自托管、零知识、零合并——服务器只存密文卷，既看不到内容，也看不到文件名。
自托管、零知识、零合并的私有文件网盘。服务器只存密文卷——看不到内容，也看不到文件名。
```
本地 服务器 (你自有的任何机器) 本地
文件 ──7z -mx=9 压缩──> ┌───────────────────────┐ ──逐卷下载──> 密文
│ │ 只存密文卷, 不合并 │ │
├─ cobblestone 加密 ─>│ 不持密钥, 不解密 │ ├─ 解密
├─ 分卷 + SHA-256 ───>│ 不存明文文件名 │ ├─ 7z 解压
└─ 分片上传(Bearer) ─>│ SQLite 元数据 │ └─ 还原原文件
└───────────────────────┘
本地 服务器 (任何自有机器) 本地
文件 ──32MB 切卷──> ┌───────────────────────────┐ ──aria2 并发拉卷──> 密文卷
│ │ 只存密文卷, 零合并不拼接 │ │
├─ 逐卷 7z ─────>│ 不持密钥, 不解密 │ ├─ 逐卷解密 (context=vol:N)
├─ 逐卷加密 ────>│ 不存明文文件名 │ ├─ 7z 解压
└─ aria2 反向拉─>│ SQLite 元数据 + 目录管理 │ └─ 按序拼接还原
└───────────────────────────┘
```
- **传输协议**: HTTPS + REST 分片上传（卷 = 分片，失败只重传该卷）
- **加密**: cryptography.cobblestone（C2SP chunked AES-256-GCM，16KiB 块级流式 + 块级认证）
- **压缩**: 7z -mx=9 最高压缩（文本类文件实测 95% 压缩率，传输量大幅下降）
- **架构**: 客户端 / 服务端 / TUI 三项目解耦，客户端只依赖共享 protocol 契约
## 核心设计
---
- **零知识**: 密钥永不出客户端。AES-256-GCM（C2SP chunked 流式认证加密, 16KiB 分块）
- **零合并**: 服务端不存在解密/拼接代码路径, 密文卷原样落盘（怎么传的怎么放）, 物理上无明文还原能力
- **卷级加密**: 32MB 统一切卷, 每卷 nonce 由 `context=7z-encrypt:v1:vol:N` 派生——加密参数零存储, 下载端按卷号重建
- **逐卷压缩**: 可压缩格式逐卷 7z mx=9; 已压缩格式（apk/zip/图片/视频黑名单）跳过二次压缩直传
- **aria2 全链路**: 上传走服务端反向拉取（客户端临时 HTTP 19000-19100）+ pull-status 实时进度; 下载 8 并发 × 4 连接/卷
- **完整性**: 逐卷 SHA-256 校验 + complete 总哈希双校验
- **账户隔离**: 一个账户一个空间, 跨账户 403 硬拒绝
- **文件名加密**: 元数据文件名也加密（enc: URL-safe base64）
## 特色
### 1. 零知识 — 服务器没有密钥
服务端不持有任何密钥材料，不解密、不碰明文。密文卷上传 → 密文卷存储 → 密文卷下载，客户端本地完成全部解密。
```
服务端被攻破 / 管理员偷看 / 服务器被扣押 → 手里只有密文
文件内容 + 密钥都在你手里, 数据安全不依赖服务器可信度
```
### 2. 零合并 — 服务器不做任何合并操作
上传的卷直接落盘（`chunk_0001..N`），complete 只校验卷齐 + 目录 move 入库，**秒回**。下载时客户端逐卷拉取、本地拼接。
```
传统方案: 上传 100% → 等服务端合并大文件 (2G 要几分钟)
本方案: 上传 100% → 秒回 done (6 卷实测全流程 1.1 秒)
服务端 CPU 几乎为零: 收卷存卷、发卷, 纯 IO 转发
```
### 3. 元数据零知识 — 文件名也加密
文件名用独立 context 加密成 URL-safe base64（`enc:` 前缀），服务器只见密文。客户端 ls / 下载时本地解密还原原名。
```
服务端能看到: 密文文件名 / 大小 / 卷数 / 卷哈希 (完整性校验用)
服务端看不到: 明文文件名 / 文件内容
```
### 4. 压缩 → 加密 → 分卷 → 上传 管线
```
源文件 → 7z -mx=9 → .7z → cobblestone 加密 → 密文 → 分卷 → 逐卷上传
下载反向: 逐卷拉取 → 本地拼接密文 → 解密 → 7z 解压 → 原文件
```
先压缩再加密（密文不可压缩，顺序反了压缩率归零）。文本实测 3.8MB → 0.2MB，传输量省 95%。
### 5. 卷粒度断点续传
每卷独立 PUT + 独立 SHA-256 校验。中断后 `GET /chunks` 查已收卷，只补传缺失卷，天然续传。
### 6. 认证 + 配额 + 文件管理
- Bearer token 认证（预共享，无/错 token 一律 401）
- 空间配额查询（已用 / 配额 / 剩余 / 百分比）
- ls / 下载 / 删除全套文件管理
- 下载按卷粒度进度显示，与上传日志对称
### 7. 全面进度可视化 (tqdm)
上传卷条、下载双层嵌套条（外层卷 / 内层字节）、加密条、分卷条、解密条——所有耗时操作都有实时进度，拒绝黑盒等待。
### 8. 轻量部署 — SQLite + 标准库优先
服务端 Python 标准库 + FastAPI，数据库 SQLite（零进程零安装）。PRoot 容器（手机 ZeroTermux）、树莓派、任何 VPS 都能跑。
### 9. 输入安全加固
- 下载文件名消毒（basename，防路径穿越）
- init json 大小限制 1MB / 卷数上限 10000 / 文件名清洗
- 所有 SQL 参数化，token 不落库
### 10. 密钥系统级管理
- 密钥默认存系统标准位置 `~/.local/share/7z-encrypt/keyring.json`（XDG），环境变量 `SZ_KEYRING` 可指定；旧版位置自动迁移
- 密钥导出/导入（TUI 菜单 7/8）：红色风险警告 + 二次确认（yes/CONFIRM），导入自动备份 `keyring.json.bak`，导出文件权限 600
- 重新生成密钥（TUI 菜单 12）：红色警告 + 二次确认，旧密文永久不可解（先导出备份）
- 换机迁移：旧机导出 → 新机导入 → 直接解密旧密文
### 11. 账号体系
- 注册 / 登录 / 注销（TUI 菜单 9/10/11 或 CLI `--register/--login/--logout`）
- **登录门禁**: TUI 启动先验证登录, 不登录不能进行文件操作 (只有登录/注册/配置)
- 密码 pbkdf2-hmac-sha256 哈希存储（20 万轮迭代，不落明文），登录 token 随机 32 字节
- 文件按用户隔离：注册用户只见自己的文件，admin（SZ_TOKEN）可见全部
- 登录后 token 自动保存到 config.json，注销即失效
---
## 与百度网盘对比
| 维度 | 百度网盘 | 7z-encrypt |
|---|---|---|
| **数据安全** | 服务器持有明文，可扫描/审查/和谐；VIP 可享"原画"也意味着服务器能看 | 端到端零知识：服务器只有密文，无密钥无法解密，内容+文件名双重加密 |
| **速度** | 非会员限速 ~100KB/s，会员才跑满 | 自己服务器的带宽，不限速；7z 压缩省 95% 传输量 |
| **空间** | 免费 2TB 但限速/限单文件大小，扩容要付费 | 服务器磁盘即空间，配额自定（环境变量 SZ_QUOTA） |
| **费用** | 会员 30+/月，续费永无止境 | 自托管零月费，一台旧手机/小 VPS 即可 |
| **隐私** | 内容会被 AI 扫描、分享链接可被举报和谐 | 零知识架构，服务器管理员都看不到内容 |
| **审查** | 敏感内容秒和谐，资源类文件风险高 | 无审查无和谐，纯私有传输 |
| **广告** | 客户端广告、推广位、全家桶 | 无广告，无推广 |
| **文件操作** | 上传/下载受客户端控制，断点续传要会员 | 卷粒度断点续传免费，上传失败只重传缺失卷 |
| **可控性** | 关停风险、政策风险、客户端强制更新 | 完全自托管，代码开源，随时审计 |
| **部署** | 不可自部署 | 单文件服务端，SQLite，手机容器都能跑 |
| **扩展** | 生态封闭，API 受限 | REST API 全开放，可编程上传/下载 |
| **成本对照** | 100GB 文件传一年会员费 ≈ 400 元 | 0 元软件成本 + 自己的服务器电费 |
**一句话**: 百度网盘是"存给百度看的网盘"，7z-encrypt 是"只存密文的管道"——前者买的是空间，后者买的是隐私和速度。
---
## 快速开始
## 安装
```bash
# 1. 服务端 (任何有 Python 3.11+ 的机器)
cd server
pip install fastapi uvicorn cryptography tqdm
SZ_TOKEN=你的token python3 main.py # 默认 0.0.0.0:8000
# deb 安装 (postinst 自动安装 aria2/p7zip/venv 依赖)
sudo dpkg -i 7z-encrypt-client_1.0.0_all.deb # 源码版 (手机/Termux)
sudo dpkg -i 7z-encrypt-client-bin_1.0.0_amd64.deb # Nuitka 编译版 (PC, 免 Python)
# 2. 客户端
cd 7z-encrypt
uv pip install --python .venv/bin/python tqdm
python config.py --init
python config.py --set-server http://服务器IP:8000
python config.py --set-token 你的token
# 密钥库位置 (系统级): 默认 ~/.local/share/7z-encrypt/keyring.json
# 环境变量 SZ_KEYRING 可指定; 旧版 config/keyring.json 自动迁移
# 密钥导出/导入: TUI 菜单 7/8 (红色警告+二次确认)
# 3. TUI (推荐)
python3 ../tui/scripts/tui.py
# 启动先登录门禁 (不登录不能操作文件) -> 主菜单:
# 1上传 / 2任务续传 / 3配置 / 4文件列表 / 5下载 / 6删除
# 7密钥导出 / 8密钥导入 / 9注册 / 10登录 / 11注销 / 12重新生成密钥 / q退出
# 源码运行
python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
```
## 原生编译 (Nuitka)
命令: `sz-transfer` (CLI) / `sz-tui` (终端界面) / `sz-config` (配置) / `sz-backup` (一键备份)
把 Python 转成 C 再用 gcc 编译成原生二进制，无需解释器依赖（onefile 单文件自包含）：
## 目录管理
```bash
# 客户端 CLI (含 cryptography/tqdm 打包)
uv pip install --python .venv/bin/python nuitka
.venv/bin/python -m nuitka --onefile --follow-imports \
--include-package=cryptography --include-package=tqdm \
--output-dir=bin --output-filename=sz-transfer transfer.py
./bin/sz-transfer --server http://127.0.0.1:8000 --whoami
# 注意: cryptography 是 C 扩展, 必须 --include-package=cryptography
# 否则运行时报 ModuleNotFoundError: cryptography.hazmat.primitives
```
sz-transfer --dir-create 相册备份 # 创建目录 (按用户隔离)
sz-transfer --dir-list # 列表 (含每目录文件数)
sz-transfer --dir-delete 1 # 删除目录
sz-transfer --init a.init.json --manifest a_manifest.json --dir 1 # 上传到指定目录
sz-transfer --move 1 2 # 移动文件到目录 (0=根)
sz-transfer --clone 1 2 # 克隆文件 (物理复制卷 + 新记录)
sz-transfer --list # 文件列表 (目录 + [目录名] 归属标记)
```
TUI 自动优先调用编译产物（`bin/sz-transfer`），无则回退源码解释执行。
## 一键备份
## Termux / 手机安装 (deb 包)
适配 PRoot Ubuntu / Termux 的安装包（配置走 XDG，`cwd` 无关）：
```bash
# 构建 (需 debhelper): dpkg-buildpackage -us -uc -b
# 生成 ../7z-encrypt-client_1.0.0_all.deb (源码版, 手机用)
# ../7z-encrypt-client-bin_1.0.0_amd64.deb (x86_64 编译版)
# 手机上 (ZeroTermux PRoot Ubuntu) 安装源码版:
apt install -y python3 python3-venv p7zip-full
dpkg -i 7z-encrypt-client_1.0.0_all.deb # postinst 自动建 venv + 装 cryptography/tqdm
# x86_64 本机安装编译版 (Nuitka 原生, 免 Python):
sudo dpkg -i 7z-encrypt-client-bin_1.0.0_amd64.deb # 依赖 p7zip-full
# 使用 (两版相同):
sz-config --init # 首次: 生成 ~/.config/7z-encrypt/config.json
sz-config --set-server http://服务器:8000
sz-config --set-token 你的token
sz-transfer --list # CLI (服务器/token 自动读配置)
sz-tui # TUI (登录门禁, 中文菜单)
# 换机密钥: 旧机导出 keyring -> 手机 ~/.local/share/7z-encrypt/keyring.json (权限 600)
```
依赖: 源码版 `python3 >= 3.10` + `cryptography >= 50.0.0`（cobblestone 流式加密，postinst 自动装最新版）；编译版无 Python 依赖。两版都需要 `p7zip-full`（7z 压缩）。
## 一键备份 (手机特色功能)
相册 / 文档 / 下载 / 聊天记录一键备份到私有加密服务器（增量，只传新文件）：
```bash
sz-backup # 备份全部 (photos+documents+download+chat)
sz-backup photos # 只备份相册
sz-backup list # 已备份清单
sz-backup restore photos # 恢复相册
sz-backup photos # 整个文件夹 = 一个文件: tar → 32MB 卷压缩 → 逐卷加密 → aria2 上传
sz-backup documents # 同上 (不分批, 全量单文件)
sz-backup restore photos # 下载 → 自动还原 → 解包
```
- 增量: mtime+size 对比本地清单, 只传新增/修改文件; 批量 tar 打包 (500MB/批)
- 源目录默认: photos=/sdcard/DCIM+Pictures, documents=/sdcard/Documents,
download=/sdcard/Download; 可在 config.json `backup` 段自定义
- **聊天记录**: PRoot 无 root 读不到微信数据库 (/data/data), 需先微信"备份与迁移/
导出"到手机存储, 再把目录配到 config.json backup.chat
- TUI 菜单 13 一键备份 / 14 恢复备份
## aria2 加速 (打满宽带)
安装 aria2 后上传/下载自动多连接并发（无 aria2 自动回退单线程）：
```bash
sudo apt install aria2 # PC / 服务端 / 手机都要装
```
- **下载**: 卷 2..N 由 aria2 并发拉取（多任务并行, 局域网实测 22MB/s+）
- **上传**: 客户端起临时 HTTP 服务 (端口 19000-19099, PC 需 `sudo ufw allow 19000:19100/tcp`),
服务端 aria2 并发反向拉卷, 逐卷 SHA-256 校验落盘
- 任一步失败自动回退原逐卷逻辑, 不影响使用
## Releases 下载
Gitee / Gitea 仓库 Releases 页下载 deb 包（tag v1.0.0）：
## 测试
```bash
cd 7z-encrypt && .venv/bin/pytest -q # 71 项
cd server && .venv/bin/pytest -q # 12 项
.venv/bin/pytest -q # 71 tests
```
覆盖：加密/解密回环、7z 压缩回环、逐卷上传下载、断点续传、token 认证、文件名加密回环、路径穿越防护、配额、幂等、坏卷拒绝、超大清单拒绝、密钥路径 env/XDG 解析、注册/登录/注销、用户文件隔离。
## 部署
---
- 服务端: [7z-encrypt-server](https://gitee.com/edgevoid/7z-encrypt-server)（独立仓库, 含 deb 双包 + 依赖自动安装）
- 终端界面: [7z-encrypt-tui](https://gitee.com/edgevoid/7z-encrypt-tui)
## 目录结构
## 代价与适用场景
```
7z-encrypt/ 客户端 (标准库优先)
├─ file_reader.py 流式读取
├─ crypto.py 加密/解密/文件名加密 (cobblestone AES-256-GCM)
├─ splitter.py 分卷 + SHA-256
├─ metadata.py 元数据 (init json / 卷清单)
├─ transfer.py HTTP 传输 (上传/下载/删除/配额, Bearer 认证)
├─ state.py 断点状态
├─ config.py 配置 (server/token/keyring)
└─ tests/ 70 项测试
server/ 服务端 (FastAPI + SQLite, 零知识零合并)
├─ api.py REST 端点 (认证/传输/文件/配额)
├─ receiver.py 卷接收 + 哈希校验
├─ storage.py 卷目录存储 (move 入库, 不合并)
├─ db.py SQLite (transfers/files/chunks)
├─ task_manager.py 任务状态机 + 输入清洗
└─ tests/ 9 项测试
tui/ 终端界面
└─ scripts/tui.py Python TUI (input() REPL, 原生支持中文输入法)
```
## 协议一览
```
POST /api/transfer/init 建任务 {transfer_id}
PUT /api/transfer/{id}/chunk/{n} 上传单卷密文 409 = 坏卷
GET /api/transfer/{id}/chunks 已收卷列表 断点续传
POST /api/transfer/{id}/complete 卷齐入库(秒回) {file_id}
GET /api/files 文件列表 文件名是加密的
GET /api/files/{id}/chunk/{n} 下载单卷密文 X-Enc-Params 头带解密参数
DELETE /api/files/{id} 删除文件
GET /api/quota 空间配额
全部端点需 Authorization: Bearer <token>
```
## 技术栈
- Python 3.11+ / FastAPI / uvicorn / SQLite
- cryptography 50 (cobblestone C2SP chunked AES-256-GCM)
- 7z (p7zip, -mx=9)
- tqdm 进度条
- 测试: pytest (真实行为测试, 无 mock)
自持硬件可用性（无 SLA/异地容灾）、无 Web/移动 App（CLI + TUI）、密钥丢失不可恢复。适合对数据主权有硬性要求的场景: 备份、涉密归档、跨设备私有传输。