# cloud-disk

**Repository Path**: duye/cloud-disk

## Basic Information

- **Project Name**: cloud-disk
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-24
- **Last Updated**: 2026-11-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 航奇云盘

面向个人与团队的多用户航奇云盘：手机号短信登录、目录管理、秒传/分片上传、
在线预览、分享与外链、回收站、配额与后台管理。前后端分离，单机原生部署。

## 技术栈

| 层 | 选型 |
|---|---|
| 前端 | Vue 3 + Vite + TypeScript + Bootstrap 4.6.2 + Pinia + TanStack Query + ECharts |
| 后端 | Python 3.11+ / FastAPI 0.109 + SQLAlchemy 2.0（asyncpg）+ Alembic |
| 存储 | PostgreSQL（唯一权威数据源）、Redis（缓存/限流/Celery Broker） |
| 任务 | Celery 5.3（上传会话过期、回收站清理、GC、审计清理、磁盘与短信告警） |
| 部署 | Nginx + systemd，单机原生，不使用 Docker |

## 目录

```text
backend/                  FastAPI 应用
  app/core/               配置、数据库、Redis、鉴权依赖、日志、限流、指标
  app/modules/            auth users files uploads shares trash quota admin audit
  app/services/           storage（CAS 内容寻址）、sms、thumbnail
  app/workers/            Celery 应用与定时任务
  alembic/                数据库迁移 0001–0005
  tests/                  单元、集成、契约、性能脚本
frontend/                 Vue 3 应用（开发中）
deploy/                   Nginx、systemd、环境变量模板、备份恢复脚本
specs/001-multiuser-cloud-disk/ 规格、计划、任务与 API 契约
```

## 本地开发

前置：Python 3.11+、Node.js 20.19+、PostgreSQL 14+、Redis。

首次准备：

```bash
# 后端
cd backend
python3 -m venv .venv
.venv/bin/pip install -e '.[dev]'
cp ../.env.example ../.env.dev    # 按需修改 DATABASE_URL / REDIS_URL
.venv/bin/alembic upgrade head
.venv/bin/python -m app.scripts.bootstrap_accounts

# 前端
cd ../frontend
npm install
```

从仓库根目录启动：

```bash
python3 start-backend.py --migrate   # http://localhost:11443
python3 start-frontend.py            # https://117.172.222.170:19443（自签证书）
```

前端开发服务器默认使用 HTTPS，首次启动会自动把自签证书生成到根目录 `ssl/`
（`fullchain.pem` + `privkey.pem`，含 `localhost`、`127.0.0.1` 与本机网卡 IP 的 SAN）。
浏览器首次访问会提示证书不受信任，属正常现象；导入系统证书库后可消除告警。
`--renew-cert` 重新生成证书，`--http` 退回 HTTP。

脚本会读取根目录 `.env.dev`，自动使用其中的 `BACKEND_PORT` / `FRONTEND_PORT`，
并检查端口占用；`--help` 可查看覆盖参数。生产环境仍使用 systemd 单元。

也可以手动启动：

```bash
cd backend && .venv/bin/python -m uvicorn app.main:app --reload --port 11443
cd frontend && npm run dev
```

默认配额 10 GiB、单文件上限 2 GiB、回收站保留 30 天，均可在 `.env.dev` 调整。

## 测试

```bash
cd backend
.venv/bin/pytest -q                # 单元 + 集成 + 契约
.venv/bin/pytest --cov=app --cov-report=term-missing tests/unit tests/integration tests/contract

cd frontend
npm run test:unit
npm run test:e2e
```

性能脚本：`backend/tests/performance/locustfile.py`、`k6.js`（需在压测环境执行）。

## 安全要点

- 密码 bcrypt 哈希；JWT access token 30 分钟，refresh token 旋转并检测重放。
- 分享访问码 bcrypt 存储；访问授权为 2 小时 HMAC 令牌；撤销分享立即失效。
- 全站统一错误结构 `{code,message,details}`，生产环境隐藏堆栈。
- 登录、短信、分享访问均有 Redis 限流；写接口有全局每分钟限流。
- 审计日志记录登录、上传、下载、分享、后台敏感操作。
- 安全响应头（CSP、HSTS、nosniff、DENY）由应用与 Nginx 双重设置。

### 短信登录与后台配置

- 短信账号（Provider、Endpoint、AccessKey、短信登录开关）和通知配置（签名、模板、
  `##code##` 占位符、码长、有效期、重发间隔）保存在 `system_settings` 表，由
  `/admin/settings` 的「短信账号」TAB 维护（含账号与通知配置）。
- 后台保存的值优先；`.env` 中的 `SMS_*` 仅作为首次/未配置时的引导默认值。保存后下一次
  发送立即生效，无需重启服务。
- AccessKeySecret 使用 Fernet 加密落库，API 与审计日志只返回掩码。`SMS_ENC_KEY` 未设置时
  从 `APP_SECRET_KEY` 域分离派生。
- 轮换 `SMS_ENC_KEY` / `APP_SECRET_KEY` 后旧密文无法解密，后台会提示重新录入
  AccessKeySecret；环境变量回退值仍可用于恢复。
- `deploy.py` 始终安装 `.[sms]` 可选依赖，通过 `.env` 切换 Provider 不需要补装 SDK。
- 生产环境拒绝 `SMS_PROVIDER=mock`；测试与本地开发可用 mock（验证码 `SMS_MOCK_CODE`）。

## 部署

见 [`deploy/README.md`](deploy/README.md)：目录与账号、数据库、环境变量、
systemd、Nginx/TLS、健康检查、备份恢复与升级回滚。