commit
9c5fef1a4d
412 files changed
+94582
No files matched your search
+322
@@ -0,0 +1,322 @@
|
||||
# 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*
|
||||
Reference in new issue
Block a user