Files

322 lines
11 KiB
Markdown
Raw Permalink Normal View History

2026-11-16 20:45:22 +08:00
# Sakura Downloader(樱云下载器)项目方案书
> 版本:v1.0 | 日期:2026-06-18 | 状态:已交付
---
## 一、项目概述
### 1.1 项目名称
**Sakura Downloader(樱云下载器)** — 个人媒体采集、本地图库管理与跨设备云同步系统。
### 1.2 项目定位
一个面向个人用户的**多媒体内容采集-整理-阅读一体化平台**,解决"从多个内容平台采集插画/漫画/小说 → 本地归档整理 → 在手机/桌面等多设备上随时浏览阅读"的完整链路。
### 1.3 核心价值
| 痛点 | 解决方案 |
|------|----------|
| 多平台内容分散(Pixiv、X、小红书、AO3、笔趣阁等) | 统一插件架构,一个入口采集所有平台 |
| 下载后文件散乱、难以检索 | 本地图库 + SQLite 索引 + 缩略图墙 + 标签/作者搜索 |
| 桌面下载了,手机上没法看 | Sakura Cloud 云端同步,手机端实时访问 |
| 关注的作者更新了不知道 | 云端每日摘要提醒,手机端查看 |
| 跨平台小说阅读体验差 | Flutter 移动端专为阅读优化:自动分页、进度记忆、翻译、字体调节 |
---
## 二、系统架构
### 2.1 整体拓扑
```text
┌─────────────────────────────────────────────────────────┐
│ Sakura Cloud (FastAPI) │
│ PostgreSQL + JWT Auth │
│ api.kunkunxiaomao.top:8000 │
└──────┬──────────────────────┬───────────────────────────┘
│ REST API │ REST API
▼ ▼
┌──────────────┐ ┌──────────────────┐
│ Windows 桌面端 │ │ Android 移动端 │
│ Python + │ │ Flutter + │
│ CustomTkinter │ │ Riverpod + Dio │
│ (采集/整理中枢) │ │ (阅读/提醒终端) │
└──────┬─────────┘ └──────────────────┘
│ 本地 SQLite │
▼ ▼
┌──────────────┐ ┌──────────────┐
│ 本地图库文件 │ │ 本地缓存/下载 │
│ (图片/漫画/小说)│ │ (离线阅读) │
└──────────────┘ └──────────────┘
```
### 2.2 技术栈总览
| 层级 | 技术选型 |
|------|----------|
| **Windows 桌面端** | Python 3.8+ · CustomTkinter · SQLite · Playwright · Pillow |
| **云端 API** | FastAPI · PostgreSQL · SQLAlchemy · Alembic · JWT · Docker |
| **Android 移动端** | Flutter 3.x · Dart · Riverpod · Dio · shared_preferences |
| **管理后台 Web** | Vite · TypeScript · Vue/React · Nginx |
| **插件系统** | Python 动态加载 · manifest.json · 统一 PluginBase 接口 |
| **打包分发** | PyInstaller (EXE) · Flutter build (APK) |
---
## 三、客户端种类与职责
### 3.1 Windows 桌面端(`pixiv_app/` + `main.py`)
**角色:采集与整理中枢**
| 功能模块 | 说明 |
|----------|------|
| **多平台采集** | 通过插件系统支持 Pixiv、X (Twitter)、小红书、AO3、笔趣阁等 |
| **Cookie/密码登录** | 支持 Cookie 导入(推荐)和账号密码登录 |
| **灵活抓取模式** | 作者全部作品、单作品/漫画、小说/系列、关键词搜索 |
| **本地图库** | SQLite 索引 + 文件系统存储,支持缩略图生成 |
| **缩略图墙** | 本地 Web 服务(127.0.0.1:8765),浏览器中浏览、搜索、筛选、收藏 |
| **关注同步** | Pixiv 关注作者管理 + X 关注同步 |
| **云同步** | 一键上传到 Sakura Cloud,自动同步新下载内容 |
| **代理池** | 浏览器代理池 + HTTP 代理,规避反爬 |
| **Playwright 集成** | 无头浏览器渲染 JS 页面(X 插件依赖) |
| **指纹伪装** | 浏览器指纹随机化,降低封禁风险 |
**打包产物**:`sakuradownloader.exe` (~68 MB, PyInstaller 单文件)
### 3.2 Sakura Cloud 云端(`sakura_cloud/`)
**角色:数据与账号中心**
| 功能模块 | 说明 |
|----------|------|
| **用户系统** | 注册/登录/邮箱验证/JWT Token 鉴权 |
| **媒体存储** | 图片/漫画/小说上传、存储、缩略图生成 |
| **收藏系统** | 跨设备收藏同步 |
| **关注与提醒** | 关注作者管理 + 每日更新摘要提醒 |
| **阅读进度** | 小说阅读进度云端存储,跨设备同步 |
| **管理后台** | SPA 管理控制台(可选) |
| **自动运维** | 启动自动 migrate、定时清理过期上传、每 5 分钟检查提醒摘要 |
**部署方式**:Docker Compose(FastAPI + PostgreSQL)
### 3.3 Android 移动端(`sakura_mobile/`)
**角色:跨设备阅读与提醒终端**
| 功能模块 | 说明 |
|----------|------|
| **发现页** | 最近浏览 + 更新提醒摘要 |
| **图片页** | 缩略图列表 · 详情 · 收藏 · 下载 · 编辑 · 删除 |
| **漫画页** | 按漫画分组浏览,整组连续阅读,整组下载 |
| **书架页** | 三列彩色方块风格,系列小说按书名归档,章节选择 |
| **小说阅读器** | 自动分页 · 阅读进度记忆 · 收藏 · 当前页翻译 · 原文/译文切换 · 字体/行高/背景色调节 · 章节切换 |
| **我的页** | 用户资料 · 云端空间 · 收藏管理 · 每日提醒开关/时间 · 提醒中心 |
| **搜索** | 图片/漫画/小说全局搜索 |
**打包产物**:`app-release.apk` (~54 MB, 调试签名)
### 3.4 管理后台 Web(`sakura_admin_web/`)
**角色:云端管理控制台**
- 基于 Vite + TypeScript 的 SPA 单页应用
- 通过 Sakura Cloud 的 `/admin` 路由挂载
- 提供可视化的数据和用户管理界面
- 可选部署(`admin_frontend_enabled` 配置项)
---
## 四、插件体系
### 4.1 插件架构
```text
plugins/
├── pixiv/ # Pixiv 插画/漫画/小说
│ ├── manifest.json
│ └── plugin.py
├── x/ # X (Twitter) 媒体
│ ├── manifest.json
│ ├── plugin.py
│ ├── playwright_client.py
│ └── x_login.py
├── xiaohongshu/ # 小红书
├── ao3/ # Archive of Our Own
└── biquge/ # 笔趣阁(小说)
```
### 4.2 插件接口规范
每个插件只需实现 `PluginBase` 抽象类,包含:
- `platform_name` — 平台标识
- `supports_modes` — 支持的抓取模式列表
- `search()` — 搜索
- `fetch_work()` — 获取作品详情
- `fetch_author_works()` — 获取作者全部作品
- `download()` — 下载媒体文件
通过 `manifest.json` 声明元数据,桌面端启动时自动发现并加载。
---
## 五、核心数据流
### 5.1 采集下载流程
```text
用户输入(ID/链接/关键词)
│
▼
任务解析器 (parser.py)
│
▼
任务队列 (queue.py)
│
▼
插件调度 → 对应平台 plugin.py
│
▼
HTTP/Playwright 抓取 → 解析作品列表
│
▼
下载器 (downloader.py) → 保存到本地图库
│
▼
SQLite 索引写入 + 缩略图生成
│
▼
(可选) 云同步上传到 Sakura Cloud
```
### 5.2 云同步流程
```text
桌面端下载完成
│
▼
检查"启用云同步"开关
│
▼
cloud_sync.py → POST /api/v1/media/upload
│
▼
Sakura Cloud 存储 + 生成缩略图
│
▼
移动端刷新 → GET /api/v1/media → 展示
```
### 5.3 每日提醒流程
```text
桌面端同步关注作者的新作品到云端
│
▼
云端写入 follow + update_alert 记录
│
▼
reminder_digest_loop (每5分钟检查)
│
▼
到达用户设定的提醒时间 → 生成每日摘要
│
▼
移动端"发现"页展示更新提醒
```
---
## 六、用法概览
### 6.1 桌面端典型工作流
1. **登录** → 导入 Pixiv Cookie(推荐)或账号密码登录
2. **抓取** → 选择平台 → 选择模式 → 输入目标 → 开始抓取
3. **浏览** → 打开缩略图墙 → 搜索/筛选/收藏
4. **关注** → 在缩略图墙中关注作者 → 后续同步关注作者更新
5. **云同步** → 登录 Sakura Cloud → 开启云同步 → 自动上传
### 6.2 移动端典型工作流
1. **安装** → 安装 APK → 允许未知来源
2. **登录** → 使用与桌面端相同的 Sakura Cloud 账号
3. **浏览** → 底部 5 个页签切换(发现/图片/漫画/书架/我的)
4. **阅读小说** → 自动分页 · 调节字体 · 翻译 · 章节切换
5. **提醒** → 我的 → 每日更新提醒 → 开启并设置时间
### 6.3 云端部署
```bash
cd sakura_cloud
docker-compose up -d
# FastAPI :8000 + PostgreSQL :5432
```
### 6.4 构建打包
```bash
# 桌面 EXE
scripts\build_desktop_exe.bat
# Android APK
scripts\build_mobile_android.bat
# 复制到 releases/
scripts\copy_release_artifacts.bat
```
---
## 七、项目交付物
| 交付物 | 路径 | 说明 |
|--------|------|------|
| Windows EXE | `releases/sakuradownloader.exe` | 双击即用,~68 MB |
| Android APK | `releases/app-release.apk` | 调试签名,~54 MB |
| 用户使用说明 | `使用说明-桌面版与安卓版.md` | 终端用户操作手册 |
| 项目方案书 | `docs/项目方案书.md` | 本文档 |
| 开发文档 | `项目文件/BUILD.md` | 构建与排错 |
| 构建脚本 | `scripts/` | 一键打包脚本 |
| 云端 API | `sakura_cloud/` | Docker 部署 |
| 源码 | 全部 Python/Dart/TypeScript | 可二次开发 |
---
## 八、技术亮点
1. **插件化架构** — 新平台接入只需新增一个插件目录,不改动核心代码
2. **多反爬策略** — Cookie 管理 · Playwright 无头浏览器 · 代理池 · 指纹伪装 · 限速退避
3. **跨设备云同步** — 桌面采集 → 云端存储 → 手机阅读,全链路打通
4. **沉浸式阅读体验** — 自动分页 · 进度记忆 · 即时翻译 · 个性化排版
5. **智能提醒** — 关注作者更新云端汇总,非本地闹钟,静默不打扰
6. **本地优先** — 所有数据本地 SQLite 存储,云端为可选项,离线也能用
---
## 九、后续演进方向
| 方向 | 说明 |
|------|------|
| iOS 客户端 | Flutter 已预留 iOS 平台支持,补充苹果开发者账号与签名 |
| 正式应用签名 | APK 替换调试签名为正式 keystore,支持上架分发 |
| 更多平台插件 | 持续扩充插件库(如 Fantia、Fanbox、DeviantArt 等) |
| AI 能力增强 | OCR 文字识别(代码已预留)· AI 翻译优化 · 智能标签 |
| 分布式爬取 | `distributed_crawler/` 目录已有 Master-Worker 架构原型 |
| PWA 移动端 | 缩略图墙升级为 PWA,支持手机浏览器直接访问 |
---
## 十、许可与免责
- 本项目仅供个人学习、研究及合法使用。
- 使用 X 插件需自行承担对应平台的使用条款风险。
- APK 当前为调试签名,仅供个人测试,不宜正式分发。
- 请遵守各内容平台的用户协议,合理使用爬取功能。
---
*文档生成于 2026-06-18 · Sakura Downloader Project*