混合非对称加密云端同步系统 (Hybrid Encryption System)

1. 项目简介

本项目实现了一套高安全性的混合架构云端与本地文件同步系统，专门针对**“云端明文存储，安全下云分发”**的场景设计。系统采用“信封加密”（Envelope Encryption）模型，结合了 RSA-4096 非对称加密与 AES-256-GCM 对称加密的优势。

核心特性：

• 安全下云架构：上传明文，下载加密。确保数据在云端可用（分析/审计），在分发链路中安全（防窃听），在终端受控（无私钥不可读）。
• 流式加密/解密：服务端与客户端均采用生成器模式，支持超大文件流式传输，内存占用恒定 (O(1))。
• Docker 化部署：服务端封装为轻量级 Alpine Docker 镜像。
• 身份认证系统：内置基于 SQLite 的用户认证系统（默认 admin/admin123），保护文件访问权限。
• 密钥生命周期管理：支持 RSA 密钥对的主动轮换（Rotation），在密钥泄露时可立即更新。
• 双客户端支持：提供命令行工具 (CLI) 和 Web 可视化界面 (WebUI)。

---

2. 快速开始

2.1 环境要求

• 操作系统：Windows 10/11
• Docker：Docker Desktop for Windows
• Python：Python 3.10+

2.2 一键部署与模拟

本项目提供了一键自动化脚本，用于构建环境并启动本地模拟测试。

1. 双击根目录下的 build_simulation.bat。
2. 脚本将自动执行以下操作：
   • 检查 Python 与 Docker 环境。
   • 生成初始 RSA-4096 密钥对。
   • 初始化 SQLite 用户数据库（默认用户：admin，密码：admin123）。
   • 构建服务端 Docker 镜像并启动容器（映射端口 8000，持久化数据库存储）。
   • 安装客户端依赖并打包为 EXE。
3. 脚本执行完毕后，服务端将运行在 http://localhost:8000。

2.3 使用 WebUI (推荐)

一键部署后，你可以启动 WebUI 进行可视化操作：

cd web_ui
streamlit run app.py

访问浏览器 http://localhost:8501：

• 登录：输入默认账号 admin / admin123。
• Server Module：查看云端文件列表，点击下载（此时会自动加密）。
• Local Module：上传本地文件（明文上传），或解密刚刚下载的加密文件（.enc -> 明文）。
• Key Management：点击 "Rotate Key Pair" 可生成新的 RSA 密钥对，旧私钥会自动备份。

2.4 使用 CLI 命令行

使用生成的客户端 EXE 进行测试：

上传 (明文)：

client\dist\HybridClient.exe upload <你的文件路径> --user admin --pass admin123

下载 (自动加密并本地解密)：

client\dist\HybridClient.exe download <文件名> --user admin --pass admin123

---

3. 系统架构

3.1 目录结构

/HybridAsymmetricEncryptionSystem
├── build_simulation.bat      # 一键构建与部署脚本
├── gen_keys.py               # 密钥生成与数据库初始化工具
├── README.md                 # 项目文档
├── 混合非对称加密算法实现.md   # 深度技术报告
├── 系统工作流程报告.md         # 流程与时序分析
├── server_uploads/           # [Docker映射] 云端文件存储目录 (明文)
├── web_ui/                   # WebUI 源码 (Streamlit)
│   ├── app.py                # WebUI 入口 (含登录与密钥管理)
│   └── downloads/            # WebUI 下载缓存目录
├── client/                   # 客户端源码
│   ├── main.py               # CLI 入口
│ 🎯├── decryption_engine.py  # ************流式解密引擎************
│   ├── client.spec           # PyInstaller 打包配置
│   ├── resources/            # [自动生成] 存放 RSA 私钥 (private.pem)
│   └── requirements.txt      # 客户端依赖
└── server/                   # 服务端源码
    ├── Dockerfile            # 多阶段构建文件
    ├── requirements.txt      # 服务端依赖
    └── app/
        ├── main.py           # FastAPI 应用入口 (含 /rotate-keys 接口)
      🎯├── crypto_utils.py   # ************流式加密核心逻辑***************
        ├── user_manager.py   # 用户数据库管理 (支持 Key Update)
        └── users.db          # [Docker映射] SQLite 用户数据库

3.2 HENC 协议规范 (Hybrid Encrypted Content)

系统定义了自定义的二进制协议用于传输加密数据：

偏移量	字段	长度	描述
0x00	Magic	4 Bytes	固定值 HENC
0x04	Version	1 Byte	协议版本 (0x01)
0x05	Algo	1 Byte	算法标识 (0x01 = AES-GCM)
0x06	Block Size	4 Bytes	分块大小 (Big-Endian, 默认 64KB)
0x0A	Base IV	12 Bytes	基础初始化向量
0x16	Enc DEK Len	2 Bytes	加密后的 DEK 长度
0x18	Enc DEK	Var	RSA 加密的 AES 会话密钥
Var	Payload	Stream	连续的密文块序列

加密块结构： [ Ciphertext (Block Size) ] + [ Auth Tag (16 Bytes) ]

---

4. 故障排查

• WebUI 报错 "Failed to import decryption_engine"：
  • 确保你是在 web_ui 目录下运行 streamlit run app.py。
• 点击 Rotate Key Pair 后无反应或未生效：
  • 检查 Docker 容器是否正确挂载了 users.db。如果没有挂载，容器重启后密钥变更会丢失。
• Docker 端口冲突：
  • 确保本地 8000 端口未被占用。

---

5. 开发团队

• Generated by Trae AI (Gemini-3-Pro-Preview)
• Displace