7z-encrypt/README.md

7z-encrypt 文件安全传输系统

端到端加密 + 最高压缩 + 分卷传输的私有文件网盘。自托管、零知识、零合并——服务器只存密文卷，既看不到内容，也看不到文件名。

本地                         服务器 (你自有的任何机器)              本地
文件 ──7z -mx=9 压缩──> ┌───────────────────────┐ ──逐卷下载──> 密文
   │                     │  只存密文卷, 不合并   │      │
   ├─ cobblestone 加密 ─>│  不持密钥, 不解密     │      ├─ 解密
   ├─ 分卷 + SHA-256 ───>│  不存明文文件名       │      ├─ 7z 解压
   └─ 分片上传(Bearer) ─>│  SQLite 元数据        │      └─ 还原原文件
                         └───────────────────────┘

• 传输协议: HTTPS + REST 分片上传（卷 = 分片，失败只重传该卷）
• 加密: cryptography.cobblestone（C2SP chunked AES-256-GCM，16KiB 块级流式 + 块级认证）
• 压缩: 7z -mx=9 最高压缩（文本类文件实测 95% 压缩率，传输量大幅下降）
• 架构: 客户端 / 服务端 / TUI 三项目解耦，客户端只依赖共享 protocol 契约

---

特色

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 不落库

---

与百度网盘对比

维度	百度网盘	7z-encrypt
数据安全	服务器持有明文，可扫描/审查/和谐；VIP 可享"原画"也意味着服务器能看	端到端零知识：服务器只有密文，无密钥无法解密，内容+文件名双重加密
速度	非会员限速 ~100KB/s，会员才跑满	自己服务器的带宽，不限速；7z 压缩省 95% 传输量
空间	免费 2TB 但限速/限单文件大小，扩容要付费	服务器磁盘即空间，配额自定（环境变量 SZ_QUOTA）
费用	会员 30+/月，续费永无止境	自托管零月费，一台旧手机/小 VPS 即可
隐私	内容会被 AI 扫描、分享链接可被举报和谐	零知识架构，服务器管理员都看不到内容
审查	敏感内容秒和谐，资源类文件风险高	无审查无和谐，纯私有传输
广告	客户端广告、推广位、全家桶	无广告，无推广
文件操作	上传/下载受客户端控制，断点续传要会员	卷粒度断点续传免费，上传失败只重传缺失卷
可控性	关停风险、政策风险、客户端强制更新	完全自托管，代码开源，随时审计
部署	不可自部署	单文件服务端，SQLite，手机容器都能跑
扩展	生态封闭，API 受限	REST API 全开放，可编程上传/下载
成本对照	100GB 文件传一年会员费 ≈ 400 元	0 元软件成本 + 自己的服务器电费

一句话: 百度网盘是"存给百度看的网盘"，7z-encrypt 是"只存密文的管道"——前者买的是空间，后者买的是隐私和速度。

---

快速开始

# 1. 服务端 (任何有 Python 3.11+ 的机器)
cd server
pip install fastapi uvicorn cryptography tqdm
SZ_TOKEN=你的token python3 main.py          # 默认 0.0.0.0:8000

# 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

# 3. TUI (推荐)
python3 ../tui/scripts/tui.py
# 菜单: 1上传 / 2任务续传 / 3配置 / 4文件列表 / 5下载 / 6删除 / q退出

测试

cd 7z-encrypt && .venv/bin/pytest -q    # 70 项
cd server && .venv/bin/pytest -q        # 9 项

覆盖：加密/解密回环、7z 压缩回环、逐卷上传下载、断点续传、token 认证、文件名加密回环、路径穿越防护、配额、幂等、坏卷拒绝、超大清单拒绝。

---

目录结构

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)