# guangya_client

**Repository Path**: ngfchl/guangya_client

## Basic Information

- **Project Name**: guangya_client
- **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-08-13
- **Last Updated**: 2026-09-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 光鸭影视 / Media Center（Python 版）

参考 Flutter 版「光鸭影视」重写的全栈项目：**Vue 3 + Quasar 2** 前端、**FastAPI** 后端、
**Redis** 缓存/任务状态、**SQLite** 持久化。支持文件管理、云下载、分享、媒体库刮削、
播放等核心功能，适配遥控器/键盘操作（TV 场景）。

## 功能清单

| 模块 | 功能 |
|------|------|
| 认证 | 注册 / 登录 / JWT 刷新 / 登出 |
| 云盘文件 | 目录浏览 / 上传 / 下载 / 播放直链 / 新建目录 / 复制 / 移动 / 重命名 / 删除 / 回收站 / 按类型聚合（图片/视频/音频/文档）/ 全盘搜索 |
| 云下载 | URL 任务（后台线程 + Redis 进度）/ 种子任务 / 取消 / 完成后下载 |
| 分享 | 创建分享（提取码/有效期）/ 列表 / 删除 / 公开访问 / 转存 / 下载计数 |
| 媒体库 | 扫描云盘视频入库 / 列表筛选搜索 / TMDB 刮削（标题/海报/简介）/ 观看历史 |
| 设置 | 主题模式 / 分页大小 / TMDB Key / 代理 等键值设置 |

## 目录结构

```
guangya/
├── backend/
│   ├── app/
│   │   ├── main.py            # FastAPI 入口（CORS、路由注册、健康检查）
│   │   ├── config.py          # Pydantic Settings（Redis/SQLite/TMDB/路径）
│   │   ├── database.py        # SQLAlchemy 2 异步引擎 + 会话
│   │   ├── redis_client.py    # Redis 封装（缺失时降级内存缓存）
│   │   ├── models/            # User/CloudFile/ShareLink/DownloadTask/LibraryItem/WatchHistory/Setting
│   │   ├── schemas/           # Pydantic 请求响应模型
│   │   ├── api/               # auth / files / tasks / shares / media / settings 路由
│   │   └── services/          # storage（磁盘映射）/ tmdb（刮削）/ downloader（下载线程）
│   ├── pyproject.toml          # Poetry 依赖与项目配置
│   └── run.py                 # uvicorn 热重载启动
└── frontend/
    ├── quasar.config.js       # Quasar 配置（端口 9000，/api 代理到 8000）
    └── src/
        ├── router/            # 路由 + 登录守卫
        ├── stores/auth.js     # Pinia 登录态
        ├── api/http.js        # Axios 封装（JWT 刷新、401 登出）
        ├── layouts/           # 工作台布局（顶部导航）
        └── pages/             # Login / MediaLibrary / Cloud / Shares / Tasks / Settings / SharePublic
```

## 快速启动

### 1. 后端（需要 Python 3.10+、Poetry 与 Redis）

```bash
cd backend
poetry install                 # 安装依赖（自动创建虚拟环境）
# 可选：配置环境变量（不配置时用默认值）
# export GUANGYA_REDIS_URL=redis://localhost:6379/0
# export GUANGYA_TMDB_API_KEY=xxxx        # 不配也能跑，刮削会提示
poetry run python run.py       # http://0.0.0.0:8000
```

> 依赖由 Poetry 管理（`pyproject.toml` / `poetry.lock`），安装 Poetry 后
> `poetry install` 一条命令即可。未安装 Redis 时自动降级为内存缓存，功能不受影响。

### 2. 前端（需要 Node 18+ 与 pnpm）

```bash
cd frontend
pnpm install                          # 依赖由 pnpm 管理（pnpm-lock.yaml）
pnpm dev                              # http://localhost:9000
```

> 国内网络建议保留 `.npmrc` 中的 npmmirror 镜像源配置，
> 首次 `pnpm install` 若提示忽略 build scripts，运行 `pnpm approve-builds` 放行。

打开 http://localhost:9000 → 注册账号 → 登录 → 进入工作台。

## 核心设计

- **存储映射**：云盘文件是逻辑树（`cloud_files` 表），实际文件落在
  `~/guangya_data/cloud/<user_id>/<cloud_path>`；`services/storage.py` 负责
  路径映射与防目录穿越。
- **下载任务**：创建任务后后台线程下载，进度写入 Redis（`dl:task:{id}`），
  前端轮询刷新；Redis 不可用时降级内存字典。
- **播放**：`GET /api/files/{id}/stream` 返回 `FileResponse`（自动支持
  HTTP Range 分段请求），浏览器/播放器可直接播放。
- **分享**：8 位分享码，可选提取码与有效期；公开接口无需登录，
  转存 = 跨用户文件复制。
- **刮削**：`services/tmdb.py` 封装 TMDB v3 搜索/详情/剧集详情，
  未配置 API Key 时优雅降级。

## API 一览

```
POST /api/auth/register           注册
POST /api/auth/login              登录（返回 access/refresh token）
POST /api/auth/refresh            刷新令牌
GET  /api/auth/me                 当前用户
GET  /api/files                   目录列表（order_by=10 查回收站）
GET  /api/files/search            全盘搜索
GET  /api/files/category/{kind}   按类型聚合
POST /api/files/dir               新建目录
POST /api/files/upload            上传
GET  /api/files/{id}/download     下载
GET  /api/files/{id}/stream       播放直链（支持 Range）
POST /api/files/copy|move|rename|delete|purge|restore
POST /api/files/clear-recycle-bin
POST /api/tasks                   新建下载任务
GET  /api/tasks/{id}/status       任务状态
POST /api/tasks/{id}/cancel|file
POST /api/shares                  创建分享
GET  /api/shares/public/{code}    公开访问（免登录）
GET  /api/shares/public/{code}/files|download/{id}
POST /api/shares/restore          转存到我的云盘
POST /api/media/scan              扫描媒体库
GET  /api/media                   媒体列表
POST /api/media/{id}/scrape       TMDB 刮削
GET  /api/media/history           观看历史
GET/PUT /api/settings             键值设置
```

## 已知限制（相对 Flutter 版）

- 上传为整块上传，未实现断点续传/秒传（GCID）。
- 下载任务为 HTTP 直连，未实现 BT/磁力解析。
- 媒体库扫描是全量重建，未实现增量增量与多目录规则。
- 视频播放用浏览器原生 `<video>`（新标签页打开流地址），
  未内置自研播放器 UI。