# CloudShadow

**Repository Path**: tactics-forge/cloud-shadow

## Basic Information

- **Project Name**: CloudShadow
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-08
- **Last Updated**: 2026-07-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CloudShadow (云影)

> 低成本、高性能的私人家庭影院系统。通过"**边缘转码,云端分发**"的架构,将高能耗的视频转码任务下沉至管理员本地设备,使服务器能以极低资源消耗支撑高画质流媒体服务。

## 架构

```
┌─────────────────┐     HLS 切片      ┌─────────────────┐     302 重定向    ┌─────────────────┐
│  CloudShadow    │  ───────────────▶ │  CloudShadow    │  ───────────────▶ │  CloudShadow    │
│    -Admin       │                   │    -Server        │                   │    -TV          │
│  Flutter+Rust   │     鉴权/进度     │   Rust/Axum     │     HLS 播放      │   Flutter       │
└─────────────────┘  ◀──────────────▶ └─────────────────┘  ◀──────────────▶ └─────────────────┘
   本地转码+上传                          轻量级中枢                            大屏观影体验
```

| 组件 | 技术栈 | 职责 |
| :--- | :--- | :--- |
| **Admin** | Flutter Desktop + Rust (FRB) + FFmpeg | 视频导入、影子转码、增量同步上传 |
| **Server** | Rust + Axum + sea-orm + PostgreSQL | 鉴权、API、网盘驱动、流媒体分发 |
| **TV** | Flutter + media_kit | 遥控器交互、HLS 硬解、换端续播 |

## 仓库结构

```
cloud-shadow/
├── server/                       # 服务端 (Rust)
│   ├── src/                    # 业务代码
│   ├── migration/              # sea-orm-migration 迁移
│   │   └── src/
│   │       ├── schemas/        # DDL 结构迁移 (8 张表)
│   │       └── datas/          # DML 数据迁移 (seed admin)
│   ├── application.toml        # 默认配置
│   └── Cargo.toml              # workspace 根 (含 migration 成员)
├── docs/                       # 设计/实施文档
│   ├── 01-需求文档.md
│   ├── 02-08-实施文档/计划.md
│   └── 05-集成网盘驱动模块需求文档.md
├── docker-compose.yml          # Postgres 本地开发环境
└── LICENSE                     # MIT
```

## 核心特性

- **边缘转码**:Admin 端本地 FFmpeg + GPU 硬件加速 (NVENC/QuickSync/VideoToolbox),转码 ≥5x 实时速度
- **网盘原生集成**:Server 直连阿里云盘/夸克网盘,秒传校验 + 流式转发,无需 rclone/Alist
- **302 直链分发**:TV 端播放请求由 Server 重定向至网盘 CDN,服务器零带宽消耗
- **M3U8 动态重构**:Server 改写 `.ts` 路径指向自身 API,确保全流程受控
- **直链缓存**:`mini-moka` 内存缓存 + 60s 安全边际,降低网盘 API 调用频次
- **JWT 鉴权**:DashMap 内存黑名单 + revoked_tokens DB 冷路径兜底

## 数据库表

| 表 | 用途 |
| :--- | :--- |
| `videos` | 视频元数据 + pg_trgm 标题模糊搜索 |
| `users` | 用户账号 (admin/viewer 角色) |
| `watch_histories` | 观看进度 (复合主键 uid+vid) |
| `cloud_accounts` | 网盘账号 + 加密 token |
| `video_files` | 视频切片文件映射 |
| `orphan_files` | 孤儿文件 (失败重试 + 指数退避) |
| `revoked_tokens` | 已撤销 JWT |

## 快速开始

### 前置要求

- Rust 1.80+ (推荐 rustup 最新 stable)
- PostgreSQL 16+
- FFmpeg (Admin 端转码,本仓库不含)

### 1. 启动 Postgres

```bash
# 选项 A: docker-compose (开箱即用)
docker compose up -d postgres

# 选项 B: 使用现有 Postgres 实例
#   确保 application.toml 中的 database.url 可连通
#   如遇 SSL 报错,可在 url 末尾追加 ?sslmode=disable
#   如遇 pg_hba.conf 拒绝,需放行客户端 IP 网段
```

### 2. 配置

编辑 [server/application.toml](server/application.toml),按需修改:

```toml
[database]
url = "postgres://user:pass@host:5432/db_cloud_shadow?sslmode=disable"
max_connections = 10
min_connections = 2

[jwt]
secret = "请替换为强随机字符串"
expires_hours = 12
```

> **生产部署**:通过环境变量 `CS_<SECTION>__<KEY>` 覆盖敏感配置 (前缀 `CS_`,层级分隔 `__`)。
> 示例:`CS_DATABASE__URL=...`、`CS_JWT__SECRET=...`

### 3. 启动 Server

```bash
cd server
cargo run
```

启动时会自动执行所有 pending 的数据库迁移 (8 张表 + admin 种子账号)。

默认监听 `0.0.0.0:8080`,健康检查:

```bash
curl http://localhost:8080/healthz
# ok
```

### 4. 命令行管理迁移 (可选)

```bash
cd server

# 查看迁移状态
cargo run -p migration -- status -u "<database_url>"

# 手动跑迁移
cargo run -p migration -- up -u "<database_url>"

# 回滚一步
cargo run -p migration -- rollback -u "<database_url>" -n 1

# 完全重置 (危险: drop 所有表后重建)
cargo run -p migration -- fresh -u "<database_url>"
```

## 配置项

| Section | Key | 说明 |
| :--- | :--- | :--- |
| `server` | `host` / `port` | 监听地址 |
| `server` | `body_limit_bytes` | 请求体上限 (切片上传单次最大 10MB) |
| `server` | `cors_origins` | CORS 白名单,空或 `["*"]` 为开发模式 |
| `database` | `url` / `max_connections` / `min_connections` | 连接配置 |
| `log` | `level` / `format` / `file_dir` | 日志 (RUST_LOG 风格、plain/json、按日切分) |
| `jwt` | `secret` / `expires_hours` | JWT 签发 |
| `storage` | `data_dir` | 海报本地存储根目录 |
| `cloud.cache` | `capacity` / `ttl_secs` | 直链缓存 |
| `cloud.rate_limit` | `aliyun_qps` / `quark_qps` | 网盘 API 限流 |

## 实施进度

详见 [docs/06-CloudShadow-Server-实施计划.md](docs/06-CloudShadow-Server-实施计划.md)。

- [x] **阶段 1 基础设施** — 项目骨架 / 配置 / DB + migrations / AppError / tracing
- [ ] **阶段 2 鉴权** — JWT / argon2 / TokenCipher / revoked_tokens / 中间件
- [ ] **阶段 3 仓储层** — sea-orm entities + repos
- [ ] **阶段 4 业务路由** — videos / admin / history / health
- [ ] **阶段 5 网盘驱动** — CloudDrive trait / aliyun / quark / LinkCache / RateLimiter
- [ ] **阶段 6 上传网关** — prepare / data / complete / 秒传
- [ ] **阶段 7 流媒体** — 302 重定向 / M3U8 动态重构
- [ ] **阶段 8 运维** — Prometheus / 优雅关闭 / 健康检查就绪位

## 文档

- [01-需求文档.md](docs/01-需求文档.md) — 系统需求规格
- [02-CloudShadow-Desktop-实施文档.md](docs/02-CloudShadow-Desktop-实施文档.md) — Desktop 端实施细节
- [03-CloudShadow-Server-实施文档.md](docs/03-CloudShadow-Server-实施文档.md) — Server 端实施细节
- [04-CloudShadow-Client-实施文档.md](docs/04-CloudShadow-Client-实施文档.md) — Client 端实施细节（TV + Mobile）
- [05-集成网盘驱动模块需求文档.md](docs/05-集成网盘驱动模块需求文档.md) — 网盘驱动模块设计
- [06-08-实施计划.md](docs/) — 三端分阶段任务清单
- [superpowers/specs/](docs/superpowers/specs/) — 设计规格文档（含多用户上传与分享设计）

## 技术栈

**Server**: Rust 1.80 · Axum 0.8 · sea-orm 1.0 · sea-orm-migration · PostgreSQL 16 · tokio · tracing · argon2 · jsonwebtoken · mini-moka · governor · reqwest

**Admin**: Flutter Desktop · Rust (flutter_rust_bridge) · FFmpeg (NVENC/QuickSync/VideoToolbox)

**TV**: Flutter · media_kit · D-Pad 焦点导航

## License

[MIT](LICENSE)