Files
SakuraHub/docs/项目方案书.md
T
2026-11-16 20:45:22 +08:00

323 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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*