87 lines
3.0 KiB
Markdown
87 lines
3.0 KiB
Markdown
# CypherLegacy Backend
|
||
|
||
CypherLegacy 是一个基于 FastAPI 构建的数字遗产继承系统后端。它允许用户安全地存储加密的数字资产，并指定在用户去世（被管理员确认状态）后可以由特定的继承人领取这些资产。
|
||
|
||
## 🌟 核心功能
|
||
|
||
- **安全注册与认证**: 采用 RSA 密钥对生成机制。用户注册时自动生成公私钥对，公钥用于加密资产，私钥用于解密。
|
||
- **数字资产加密存储**: 用户可以上传资产，系统使用用户的公钥对资产内容进行加密存储。
|
||
- **遗产指定**: 用户可以为每个资产指定一名继承人（Heir）。
|
||
- **吊唁/状态确认**: 系统管理员有权标记用户为“已故”（guale）。
|
||
- **遗产申领**:
|
||
- 只有被确认标记为“已故”的用户，其指定的继承人才能申领资产。
|
||
- 申领过程中，系统利用已故用户的私钥解密内容并安全交付给继承人。
|
||
- **密钥分片 (Sharding)**: 支持私钥分片存储逻辑，增强安全性。
|
||
|
||
## 🛠 技术栈
|
||
|
||
- **框架**: [FastAPI](https://fastapi.tiangolo.com/)
|
||
- **数据库**: [PostgreSQL](https://www.postgresql.org/) (通过 `asyncpg` 异步驱动)
|
||
- **ORM**: [SQLAlchemy 2.0](https://www.sqlalchemy.org/) (AsyncIO)
|
||
- **加密**: [Cryptography](https://cryptography.io/) & [PyCryptodome](https://pycryptodome.org/) (RSA 加密)
|
||
- **权限**: [python-jose](https://github.com/mpdavis/python-jose) (JWT Token)
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 1. 使用 Docker Compose 启动 (推荐)
|
||
|
||
这是最快的方式，会自动配置数据库和应用环境。
|
||
|
||
```bash
|
||
docker-compose up --build
|
||
```
|
||
简单测试：
|
||
```bash
|
||
python3 test/test_scenario.py
|
||
```
|
||
|
||
- 接口文档: `http://localhost:8000/docs`
|
||
- 管理员默认账号: `admin` / `admin123`
|
||
|
||
### 2. 本地手动启动
|
||
|
||
1. **安装环境**:
|
||
```bash
|
||
python -m venv venv
|
||
source venv/bin/activate # Linux/macOS
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
2. **配置环境变量**:
|
||
创建一个 `.env` 文件或设置环境变量 `DATABASE_URL`。默认为：
|
||
`postgresql+asyncpg://user:password@localhost:5432/fastapi_db`
|
||
|
||
3. **初始化数据库**:
|
||
```bash
|
||
python reset_db.py
|
||
```
|
||
|
||
4. **运行服务**:
|
||
```bash
|
||
uvicorn app.main:app --reload
|
||
```
|
||
|
||
## 📖 API 概览
|
||
|
||
### 用户接口
|
||
- `POST /register`: 用户注册，自动生成 RSA 密钥对。
|
||
- `POST /token`: 登录获取 JWT Access Token。
|
||
|
||
### 资产接口
|
||
- `POST /assets/`: 创建加密资产（上传者自动加密）。
|
||
- `POST /assets/assign`: 为资产指定继承人。
|
||
- `POST /assets/claim`: 继承人申领资产（需原所有人状态为 `guale`）。
|
||
|
||
### 管理员接口
|
||
- `POST /admin/declare-guale`: 管理员宣告用户“已故”。
|
||
|
||
## 🔒 安全设计
|
||
|
||
1. **端到端思想**: 资产在存储前使用 RSA 公钥加密。
|
||
2. **状态验证**: 申领逻辑严格校验 `heir_id` 以及 `author.guale` 状态。
|
||
3. **密钥管理**: 本项目目前为了演示方便在数据库中存储了私钥，在生产环境下建议配合 KMS 或硬件安全模块使用。
|
||
|
||
## 📜 许可证
|
||
|
||
MIT License
|